This document is about: QUANTUM 3
SWITCH TO
QUANTUM 1 QUANTUM 2 QUANTUM 3

Migration Guide 3.1

Migrating Quantum From 3.0 to 3.1

Projects in Quantum SDK 2.1 should be upgraded to the latest 3.0 SDK before being upgraded to 3.1.

Migration Steps

  • Download the latest Quantum SDK 3.1 unitypackage
  • Check for modifications to any Quantum Unity scripts and backup the changes.
  • Import the .unitypackage into the Unity project.
  • Delete remnants of the Quantum.Deterministic library: Quantum.Deterministic.dll, Quantum.Deterministic.pdb and Quantum.Deterministic.xml.
  • Delete the folders Assets/Photon/PhotonRealtime and Assets/Photon/PhotonLibs. Photon Realtime and the Photon libraries are now embedded in the Quantum SDK under Assets/Photon/Quantum/Runtime/Realtime (assemblies Quantum.Realtime and Quantum.Realtime.WebSocket), keeping the old folders results in duplicate types and duplicate PhotonClient.dll errors.
    • If the SDK was converted to local UPM packages before (Tools > Quantum > Export > Convert SDK to local UPM packages), remove the com.photonengine.photonlibs and com.photonengine.realtime packages from the Packages folder and from Packages/manifest.json instead.
    • Custom asmdefs that reference Photon Realtime (e.g. copies of Quantum.Unity.asmdef or Quantum.Unity.Editor.asmdef) need the new reference Quantum.Realtime (GUID:73202fbdf404a7c438fa1b7b7d5c6957)
    • To keep using Photon Realtime from its own UPM package (com.photonengine.realtime), add the scripting define QUANTUM_DISABLE_REALTIME, which excludes the embedded assemblies and the Photon dlls.
  • Delete the SDK files that were removed in 3.1, importing the .unitypackage does not delete them:
    • Assets/Photon/Quantum/Editor/QuantumEditorConfigImporter.cs
    • Assets/Photon/Quantum/Runtime/QuantumLookupTables.cs
    • Assets/Photon/Quantum/Runtime/RuntimeAssets/LUT (folder)
    • Assets/QuantumUser/Resources/QuantumLookupTables.asset
  • Restart the Unity Editor.
  • Run the Quantum CodeGen (Tools > Quantum > CodeGen > Run Qtn CodeGen), the generated Globals layout changed.
  • Fix any remaining compilation errors.
  • (Optional) If the project uses Bot SDK, close its AI documents and editor window, download Bot SDK 3.1.0 Preview package and import it into the project.
  • Reimport the asset Assets/QuantumUser/Resources/QuantumDefaultConfigs.asset to make sure the InputActionAsset is set.
  • The multi client scripts and prefabs have been moved into an additional .unitypackage, delete these files from the SDK.
    • Assets/Photon/Quantum/Runtime/RuntimeAssets/QuantumMultiClientRunner.prefab
    • Assets/Photon/Quantum/Runtime/QuantumMultiClientPlayer.cs
    • Assets/Photon/Quantum/Runtime/QuantumMultiClientPlayerView.cs
    • Assets/Photon/Quantum/Runtime/QuantumMultiClientRunner.cs
  • Import optional used Quantum packages from Assets/Photon/Quantum/PackageResources: Quantum-DemoInput, Quantum-Menu or Quantum-MultiClient by importing the .unitypackage manually or by reinstalling it using the Quantum Hub Sample section.
  • (Optional) If the project uses a custom server plugin, upgrade the Quantum Plugin SDK as well, see Plugin SDK Migration To 3.1.
  • Go through the Breaking Changes table below and apply the mitigations that affect the project.

Breaking Changes

The table lists the breaking changes from the 3.1 changelog and whether they require action when migrating.

Change Action Mitigation
Quantum.Deterministic.dll was merged into Quantum.Engine.dll Required Delete the old dll, pdb and xml files, see migration steps.
Photon Realtime is embedded in the Quantum SDK (Assets/Photon/Quantum/Runtime/Realtime, assembly Quantum.Realtime) with new script GUIDs Required Delete Assets/Photon/PhotonRealtime and Assets/Photon/PhotonLibs, update custom asmdef references and reassign Realtime MonoBehaviours, see migration steps. Define QUANTUM_DISABLE_REALTIME to use the Realtime UPM package instead.
Lookup tables were removed, FPMath uses polynomial approximations Required Delete QuantumLookupTables.cs, the RuntimeAssets/LUT folder and QuantumUser/Resources/QuantumLookupTables.asset.
Globals layout changed Required Run the Quantum CodeGen after upgrading.
Command API: QuantumGame.SendCommand() renamed to AddCommand(), multiple commands per player and frame are supported If used SendCommand() is obsolete and forwards to AddCommand(). Replace frame.GetPlayerCommand(player) with foreach (var command in frame.GetPlayerCommands<MyCommand>(player)) { }. A CompoundCommand is no longer needed to send several commands in one frame.
SessionRunner.Arguments requires an explicit TaskRunner If used Set by Init() and QuantumRunnerUnityFactory.CreateGameParameters. Other start code sets TaskRunner = QuantumTaskRunnerJobs.GetInstance(), or new DotNetTaskRunner() outside of Unity.
Quantum.Profiling.HostProfiler was renamed to Quantum.HostProfiler If used Replace the namespace in code that uses the profiler API.
DeterministicSessionConfig computes Hard Tolerance from Simulation Rate, Offset Ping Start and Offset Min Check If the project used a custom hard tolerance, enable Override Hard Tolerance and enter the value again.
Frame.DeltaTime is derived from Frame.GameTimeScale, setting DeltaTime is obsolete. FrameTimer seconds are converted with the simulation rate and ignore a modified DeltaTime Check Set Frame.GameTimeScale for slow motion or pause instead of DeltaTime and use GameTimer for timers that follow the time scale. Disable SimulationConfig.GameTimeScaleAffectsDeltaTime to keep the legacy behavior.
QuantumGame.Frames.PredictedPrevious and PreviousUpdatePredicted alias the Verified frame unless QuantumGameFlags.IsLegacyFrameCopiesEnabled is set. DisableInterpolatableStates and IsInterpolatable are obsolete Check View code that reads these frames, e.g. custom interpolation, sets QuantumGameFlags.IsLegacyFrameCopiesEnabled. Replace DisableInterpolatableStates with IsLegacyFrameCopiesEnabled, which has the inverted meaning.
QuantumEntityView.InterpolationMode defaults to ExponentialDecay Check Select another interpolation mode on the entity view if the previous behavior is required.
QuantumCallback.Subscribe and QuantumEvent.Subscribe use onlyIfActiveAndEnabled = true by default Check Subscriptions that must reach disabled or pooled GameObjects pass onlyIfActiveAndEnabled: false, or define QUANTUM_ENABLE_LEGACY_SUBSCRIBE_PARAM to restore the old default.
Frame.DeferredAdd(), DeferredSet() and CommitDeferred() were removed If used Call Add() and Set() directly and remove CommitDeferred(), adding components while a filter iterates the entity no longer throws.
CodeGen reports multiple signals with the same name as an error If used Rename or merge the duplicate signal declarations in the .qtn files.
Global Unity navmesh baking was removed If used Bake with NavMeshSurface from the com.unity.ai.navigation package.
Map.NavMeshLinks was renamed to Map.NavMeshAssets, NavMeshAgentConfig.AutomaticTargetCorrection was removed If used Rename the property. Target correction is enabled when AutomaticTargetCorrectionRadius > 0.
QuantumGame.CreateSavegame() was renamed to GetSnapshotFile(), QuantumRunnerLocalSavegame merged into QuantumRunnerLocalDebug If used Rename the call and use the snapshot options of QuantumRunnerLocalDebug.
QuantumCallbackHandler_UnityCallbacks.LoadAddressableScenePathsAsync is static If used Call it on the type instead of an instance.
ByteUtils compression methods are obsolete Optional Use Quantum.Compression instead.
The non-Unity DLLs, the DotNet simulation DLL and the console runner target net10.0 If used Upgrade custom .NET tooling, the console runner and the server to net10.0.
The Quantum Server SDK integration changed, deploy_win was removed from the plugin SDK search path If used Upgrade and migrate the Quantum plugin SDK together with the Unity SDK, see Plugin SDK Migration To 3.1.
Photon Enterprise Cloud servers require an upgrade If used Upgrade the Enterprise Cloud server before releasing clients with 3.1.
The default simulation rate changed from 60 Hz to 64 Hz None Existing session config assets keep their rate. Consider changing to 64 Hz for DeltaTime without rounding errors.

Last updated on

Back to top

Cookies,
anyone?

We use cookies and related technologies to enhance your experience, show you personalised content and analyze performance and traffic on our website. By clicking on the „Accept All“ button you consent to the use of non-functional cookies and the subsequent processing of personal data to optimize our website and services as described in more detail in our Privacy and Cookie Policy.

By clicking on the „Customize or Deny all“ button you can decide otherwise. Clicking on the „Customize“ button will take you to a page where you can configure the usage of non-functional cookies (and related technologies) or deny all of them. You can access these settings at any time and also subsequently deselect cookies at any time in the footer area of our website.

Cookie Overview

We use the following categories of cookies and related technologies to enhance your experience, show you personalized content, and analyze performance and traffic on our website. We respect your right to privacy and accordingly you can chose to not allow some types of cookies (and related technologies). Click on the different category sliders and change our default settings to manage your cookie settings.

For more information on the specific cookies/related technologies we use and on how we use these, please see section 16 E. of our Privacy and Cookie Policy.

ABSOLUTELY NECESSARY

Authentication cookies we use are required to run our services.

FUNCTIONAL COOKIES

These cookies collect data and allow us to optimize our website and user experience.

EMBEDDED CONTENT (e.g. YouTube)

Some pages embed third-party party content.
These providers may set cookies when this content is loaded.

ANALYTICS

Helps us to understand how visitors interact with our services, enables us to analyze and improve our services (also through third party analytics).