Tips and best practices to upgrade thhe SDK avoiding risk of data loss
If you wish to get started and install the coherence Unity SDK, please refer to the installation page.
Open Unity Package Manager under Window > Package Manager and check the Packages - coherence section. It will state the currently installed version and if there are any recommended updates available:
When upgrading coherence, please do it one major or minor version at a time (considering semantic versioning, so MAJOR.MINOR.PATCH).
For example, if your project is on 0.7 and would like to upgrade to 1.0, upgrade from 0.7 to 0.8, then from 0.8 to 0.9, and so on. Always back up your project before upgrading, to avoid any risk of losing your data.
Versions prior to 0.9 are considered legacy. We don't provide an insightful upgrade guide for such versions.
Refer to the specific upgrade guides provided as subsections of this article.
Refer to the troubleshooting section at any time to find solutions to issues found during or after upgrading.
This page lists changes in coherence 1.0.0 version which might affect existing projects when upgrading from a 0.10.x version to 1.0.0.
Version 1.0.0 includes breaking changes to the baked scripts, which means your current ones will cause compilation errors. It is recommended to delete your current baked scripts under Assets/coherence/baked before performing a coherence Unity SDK update.
For automatic migrations to run smoothly, we recommend not having any Prefab with missing component scripts that have the CoherenceSync component attached to it. These Prefabs will stop Unity from saving assets and automatic data migrations might get interrupted because of it.
There have been a number of updates to the old CoherenceMonoBridge, which have resulted in a rebranding of the component to CoherenceBridge.
If your custom scripts have references to the class CoherenceMonoBridge, you will have to rename all these references to CoherenceBridge.
The script asset GUID and the public API of the component remain unchanged, so asset references to CoherenceMonoBridge components should remain intact.
In coherence 1.0.0, we have revamped our asset management systems to make them more scalable and customizable, both in Editor and in runtime. Read more about the new implementations and the possibilities in the article.
Upon upgrading the SDK, a new CoherenceSyncConfigRegistry asset will be automatically created in Assets/coherence/CoherenceSyncConfigRegistry.asset and populated with sub-assets for each of your Prefabs that have a CoherenceSync component attached.
If the automatic migration completed successfully, you can browse all your networked Prefabs in the new CoherenceSync Objects window found under the coherence menu item:
If something has gone wrong during the automatic migration, you can restart the process by deleting the current CoherenceSyncConfigRegistry asset, and selecting the Reimport coherence Assets option under the coherence menu item. This will automatically create a config entry for each of your CoherenceSync Prefabs:
In previous versions of coherence, Prefabs with the CoherenceSync component would be automatically synced over the network in the Start method, and they would stop being synced only when destroyed. This prevented us from supporting things like object pooling and reusing the same CoherenceSync instance to represent different network entities across its lifetime.
As a result, CoherenceSync instances are now automatically synced and unsynced with the network in the OnEnable and OnDisable methods of the MonoBehaviour. This means you can disable the GameObject instance in the hierarchy and it will stop being synced, you can also keep the local visual representation by only disabling the CoherenceSync component.
This change may or may not affect your current project. If you wish to use the new Object Pooling feature (or make your own!), you might need to upgrade your custom components logic to accommodate the new paradigm.
The Play API was the public API we offered to connect with your coherence Cloud project in runtime. It has been deprecated in favor of a new non-static API called CloudService, with separation of a ReplicationServerRoomsService so you can talk to self-hosted Room Replication Servers with a lot more customization and without having to use the coherence Cloud.
The Play API includes the following classes:
PlayResolver
PlayClient
Play
WorldsResolverClient
RoomsResolverClient
If you were using PlayResolver static calls, you can now access CloudService instance from CoherenceBridge instead, and you will be able to use the CloudService.Worlds or CloudService.Rooms instances to fetch Worlds or to create, delete or fetch available Rooms respectively.
CloudService offers callback-based methods and an async variant for all of the available requests.
No Domain Reload is a Unity Editor option that allows users to enter Play mode very fast without having to recompile all your code. This wasn't properly supported in earlier versions of coherence, but now it is!
You can find this option under Edit > Project Settings > Editor > Enter Play Mode Settings.
Keep in mind that you might have custom implementations in your project that prevents you from using this option successfully, the most common are:
Static state and initializers: since your app domain isn't reloaded when entering Play mode, that means static contexts aren't reset either, which might cause issues.
SerializeReference instances: similar to the previous one, SerializeReference instances won't be recreated when entering Play mode, so you will have to make sure that the state of SerializeReference instances are properly reset on application quit.
In previous releases of coherence, this event would be fired strictly for CoherenceSync prefab instances created by coherence, which means it would be fired for instances you didn't have authority over.
In 1.0, this event will be fired for every instance of CoherenceSync that starts being synchronized over the network.
If you wish to hook behaviour to non-authority instances, please use the OnStateRemote event instead, which is fired when a CoherenceSync instance is non-authoritative.
In 1.0, there has been two major changes to Client Connection instances.
You can learn more about the CoherenceSync lifetime cycle in the page.
You can learn more about the Cloud Service API under the section.
Client Connection instances now live in the DontDestroyOnLoad scene. Since now we support , and Client Connections instances are managed by coherence, they need to survive the destruction of the Scene they were in.
References to the Client Connection Prefab in the CoherenceBridge Component have been changed from hard referencing a Unity Prefab, to referencing a asset. If you were using a Unity Prefab reference, it still exists serialized but is deprecated. If you wish to stop using the Unity Prefab reference, please delete the CoherenceBridge Component and add it again.
Notable API changes include:
Coherence.Network is removed now. OnConnected and OnDisconnected events are moved to IClient and have changed a signature:
BridgeStore.GetBridge is now obsolete, and will be replaced with
BridgeStore.TryGetBridge.
CoherenceSync.isSimulated is now obsolete, and will be replaced with CoherenceSync.HasStateAuthority.
CoherenceSync.RequestAuthority is now obsolete, and will be replaced with CoherenceSync.RequestAuthority(AuthorityType).
For more information, see Release Notes.
For detailed documentation of the updated CoherenceSync component, see CoherenceSync.
The CLI tools have been updated, especially the ones that handle Simulators. To learn more about this, see CLI utilities.
using Coherence.Entity; -> using Coherence.Entities;
It is recommended to switch to Assets strategy before upgrading. If you upgrade while using the Source Generator, you might see an error popup, guiding you to switch back to Assets. After upgrade and a clean Bake, you can switch back to Source Generators baking strategy.
