Migration Guide Preview
The newest Quantum 3 Preview comes with a couple of breaking changes and projects that are already on Quantum 3 Preview a few migration steps are necessary.
Breaking Changes Explanation
The QuantumMenu code and prefabs are now delivered as a separate Unity package inside the SDK. This makes it much easier for applications that are not using the default menu to create a build without unnecessary parts. The menu code will keep being upgraded but it's now completely optional and packaged as an Unity package.
Quantum 2 had a clear separation between the simulation code and Unity. The combined approach in Quantum helps greatly with simplicity but the separation, which of course is still happening, is quite subtle. Tiny changes on the naming of user folders and the final dll will help to clarify where for example system scripts have to go.
- Renaming
Quantum.Game.dll
toQuantum.Simulation.dll
- Renaming
Assets/QuantumUser/Game
toAssets/QuantumUser/Simulation
- Renaming
Assets/QuantumUser/Runtime
toAssets/QuantumUser/View
In the initial version of Quantum 3.0.0 Preview the Quantum build-in component prototype types (QPrototypeTransform2D
, etc.) were moved from inside the SDK (Quantum 2) to user generated. This creates a problem when trying to include a simple demos inside the SDK: component prototypes cannot be used, as the script Guids are different in each installation. The build-in component prototypes will be internalize again, which creates an effort to migrate. When migrating projects that where originally build in Quantum 2, then the Guids might already be correct.
Migrating Quantum 3.0.0 Preview
- Add
QUANTUM_ENABLE_MIGRATION_Q3PREVIEW
to global scripting definesQPrototypeTransform2DLegacy
etc. scripts will be generated which will take over the old Guids and prevent any references from being lost
- Close the Unity project
- Delete the
Assets/Photon/Quantum
directory - Configure CodeGen legacy folders inside the
QuantumCodeGenSettings
class
C#
public static partial class QuantumCodeGenSettings {
static partial void GetCodeGenFolderPathUser(ref string path) {
path = "Assets/QuantumUser/Game/Generated";
}
static partial void GetCodeGenUnityRuntimeFolderPathUser(ref string path) {
path = "Assets/QuantumUser/Runtime/Generated";
}
static partial void GetOptionsUser(ref GeneratorOptions options) { }
}
- Open the Quantum SDK Unity package and review the upgrade window, don't press import yet
- If any files inside the
QuantumUser/Runtime/Generated
folder are showing up in the import preview (see screenshot) delete these files from the project, cancel the import and start the process again
- If any files inside the
- Press Import
- Restart Unity Editor to reload the CodeGen library
- Install the Quantum-Menu using the Quantum Hub (samples section) or if compile errors prevent the Hub from opening import the Unity package directly from
Assets/Photon/QuantumMenu/Quantum.Menu.unitypackage
- Open all
SystemsConfig
assets with a text editor and replaceQuantum.Game
withQuantum.Simulation
, configs will throw an exception otherwise - Fix any remaining issues and code compilation by reading the changelog
- Rebake all maps
- Replace all usages of
QPrototype(..)Legacy
scripts in assets and scenes- Text based: use the Unity Guid from the script
QPrototypeTransform2DLegacy.cs.meta
and from the build-in scriptQPrototypeTransform2D.cs.meta
and search and replace all occurrences of the former with the latter in all.asset
and.unity
files in the Unity project - Editor based: use the Unity Search (Window-Search-New Window) to find scene objects and prefabs using the legacy scripts with
t:QPrototypeCharacterController2DLegacy
etc. then toggle theDebug
Unity inspector and drag and drop the non-legacy scripts into theScript
field
- Text based: use the Unity Guid from the script
- Test the migrated project
- Remove the
QUANTUM_ENABLE_MIGRATION_Q3PREVIEW
define (if all usages of QPrototypeLegacy scripts have been converted) - Rename the
Game
andRuntime
folders insideAssets/QuantumUser
and remove the implementations inQuantumCodeGenSettings
from earlier again