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 to Quantum.Simulation.dll
• Renaming Assets/QuantumUser/Game to Assets/QuantumUser/Simulation
• Renaming Assets/QuantumUser/Runtime to Assets/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 defines
  • QPrototypeTransform2DLegacy 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

• 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 replace Quantum.Game with Quantum.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 script QPrototypeTransform2D.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 the Debug Unity inspector and drag and drop the non-legacy scripts into the Script field

• Test the migrated project
• Remove the QUANTUM_ENABLE_MIGRATION_Q3PREVIEW define (if all usages of QPrototypeLegacy scripts have been converted)
• Rename the Game and Runtime folders inside Assets/QuantumUser and remove the implementations in QuantumCodeGenSettings from earlier again

Back to top