Migration Guide

Available in the Gaming Circle and Industries Circle

The complete guide to migrate Quantum 2.1 projects to Quantum 3.0.

Make sure to upgrade the projects to the latest Quantum 2.1 release and Unity 2021.3 before starting the Quantum 3 migration.

The automated process is recommended to use. When facing problems use the instructions for debugging and contact us.

Scripts GUIDs have been preserved, so prefabs and scenes are not going to suffer from missing components.

To reduce the number of possible compile errors to a minimum during migration, obsoleted scripts with legacy names are provided as well.

The following addons are not yet compatible with Quantum 3:

FlowFields
Custom Animator
Photon Chat

Quantum 3.0 Migration

Ensure that the project has a backup and/or is under source control.
Upgrade the Quantum project to the latest 2.1 Quantum SDK
Upgrade the Quantum project to Unity Editor 2021.3 or later
Because of changes to the Quantum Asset
- Each non-abstract non-generic Asset has to live in a separate file that is names as this: <AssetName>.cs
- Methods that are common for ScriptableObject have to be renamed: Update(), Start(), etc.
If the GraphProfiler addon has been added and it has been moved from its default location Assets/Photon/Profiling it has to be deleted.
Download the latest Photon-Quantum-3.0.0-Preview-Migration.zip package
Extract the content into the root folder of the Quantum 2.1 project
Bot SDK specifics: find on the Bot SDK v3 package the migration instructions which are specific to the addon

A) Automated Process

Run the Quantum3Migration.ps1 Powershell script
- To troubleshoot inspect the migration logs and enable -PauseAfterEachStep then wrap the changes into a git commit after each step.
Open Unity Editor
Continue with Final Steps

Unknown

Quantum3Migration.ps1 --UnityEditorPath <path> --Quantum2MigrationPreparationPackagePath <path> --Quantum3PackagePath <path> --Quantum3MigrationPackagePath <path> [..]

Usage:
  -UnityEditorPath <path>                 The path to the UnityEditor exe.
  -QuantumUnityPath <path>                The path to the Quantum Unity project folder. By default "quantum_unity".
  -QuantumCodePath <path>                 The path to the Quantum code project. By default "quantum_code/quantum.code".
  -AssetDBPath <path>                     The path to the temporary exported assets. By default "Quantum3MigrationAssets".
  -Quantum2MigrationPreparationPackagePath <path> 
                                         The path to the Quantum 3 Migration Preparation unitypackage.
  -Quantum3PackagePath <path>            The path to the Quantum 3 SDK unitypackage.
  -Quantum3MigrationPackagePath <path>   The path to the Quantum 3 Migration unitypackage.
  -LogBasePath <path>                    The folder where the migration logs are stored. If not set logs are created inside the executing directory.
  -AssemblyDefinitionsDecision           Define the answer for the "remove assembly definition" prompt. "yes" or "no".
  -PauseAfterEachStep                    Pause and wait for user input after each step. Default is false.
  -SkipQuantum3PackageImports            Disable the package import steps.
  -SkipQuantumCodeCopy                   Disable importing the quantum code.
  -SkipInitialCodeGen                    Disable initial CodeGen steps.
  -SkipCompileErrorDetection             Disable waiting for compiler error fixes.
  -SkipAssetsUpgrade                     Disable upgrading the Quantum assets.

B) Manual Process

Import Quantum3MigrationPreparation.unitypackage
Run Quantum > Migration Preparation > Add Migration Defines
Run Quantum > Migration Preparation > Export Assets
Run Quantum > Migration Preparation > Delete Photon
Import Photon-Quantum-3.0.0-Preview.unitypackage (if the Unity Editor crashes, restart Unity)
Import Photon-Quantum-3.0.0-Preview-Migration.unitypackage
Restart Unity Editor (click Ignore on the Enter Safemode dialog)
Run Quantum > Migration > Import Simulation Project
Run Quantum > Migration > Run Initial CodeGen
Optionally run Quantum > Migration > Run Delete Assembly Definitions
Restart Unity Editor (click Ignore on the Enter Safemode dialog)
Fix compilation errors
- If Quantum AssetObjects have existing abstract void Update(Frame f) methods Unity will complain that ScriptableObject have to have parameter-less Update() methods, add void Update() {} to fix the compilation error
Run Quantum > Migration > Check Asset Object Scripts
Run Quantum > Migration > Transfer AssetBase Guids To AssetObjects
Run Quantum > Migration > Upgrade AssetsObjects
Run Quantum > Migration > Enable AssetObject Postprocessor
Run Quantum > Migration > Reimport All AssetObjects
Run the Quantum user file installation from the QuantumHub (Ctrl+H)

Final Steps

While the migration define QUANTUM_ENABLE_MIGRATION is enabled, the detection if CodeGen has to run (qtn files changed) is disabled and needs to be run manually using the Unity menu: Quantum > CodeGen > Run Qtn CodeGen
Scripts have went through an extensive refactor:
- Component prototype suffix has been changed from _Prototype to Prototype.
- Component prototype wrapper prefix changed from EntityComponent to QPrototype (e.g. EntityComponentTransform2D -> QPrototypeTransform2D).
- All Unity-only scripts have been put in Quantum namespace and have been given Quantum prefix (e.g. MapData -> QuantumMapData, EntityPrototype -> QuantumEntityPrototype).
The config assets may have different names and different locations, browse them inside the Quantum Setup section.
QuantumEditorSettings was split into QuantumEditorSettings and QuantumGameGizmosSettings.
A new set of default configs (previously located in Resources/DB/Configs) has been generated and does not support static Guids anymore.
A Quantum3 AppId has to be created on the Photon dashboard.
QuantumEditorSettings.AssetSearchPaths can be set to Assets to search the complete project. It's fast enough now.
Let Unity reimport the Quantum assets (right-click > Reimport) located in the Resources folder for example and reimport the QuantumUnityDB.qunitydb asset (which will fix broken Quantum Asset Guids).
Re-bake all maps and navmeshes.
Quantum 3 API changes have all been wrapped into [Obsolete] attributes to make a successfully migrated project compile. Make sure to check and fix all related warnings after that especially Quantum asset and prototype scripts and prefer their new names to make GameObject.AddComponent<QAssetEntityView> work.

Breaking Changes Realtime 5

The namespaces ExitGames.* are obsolete. Use Photon.Client and Photon.Realtime instead.
The LoadBalancingClient was renamed to RealtimeClient.
The LoadBalancingClient.LoadBalancingPeer was renamed to RealtimeClient.RealtimePeer.
Removed LoadBalancingPeer class. Operations are now in the RealtimeClient.
The ExitGames.Client.Photon.Hashtable class was renamed to Photon.Client.PhotonHashtable. The client can only send PhotonHashtable now.
ConnectToRegionMaster(), ConnectToMasterServer(), ConnectToNameServer() have been removed. Use only ConnectUsingSettings() instead.
LoadBalancingClient.CloudRegion is obsolete. Use RealtimeClient.CurrentRegion instead.
LoadBalancingClient.AppVersion is obsolete. Set the version via AppSettings and ConnectUsingSetting() instead.
AppId setter now throws a NotImplementedException. Set the AppId in the AppSettings and use ConnectUsingSettings() instead.
The RaiseEventOptions class was changed to a struct called RaiseEventArgs.
EnterRoomParams was renamed to EnterRoomArgs.
OpJoinRandomRoomParams was renamed to JoinRandomRoomArgs.
RealtimeClient.ConnectionCallbackTargets is now internal. Use AddCallbackTarget() and RemoveCallbackTarget() instead.
Enum DebugLevel was renamed to LogLevel. The enum names are now Pascal case.

Quantum 3.0 Migration
Breaking Changes Realtime 5