Quantum Project

Unitypackage Content

The Quantum 3 SDK is distributed as a unitypackage file. It's roughly separated into two sections: Assets/Photon and Assets/QuantumUser. The former represents the Quantum SDK and the latter the mutable user code.

After installing Quantum, the user is presented with the following folder structure:

Unknown

Assets
├───Photon
│   ├───PhotonLibs
│   ├───PhotonRealtime
│   └───Quantum
└───QuantumUser
    ├───Editor
    │   └───CodeGen
    ├───Resources
    ├───Scenes
    ├───Simulation
    │   └───Generated
    └───View
        └───Generated

All the deterministic simulation code should be placed in QuantumUser/Simulation. Any code extending either Quantum.Unity or Quantum.Unity.Editor classes should be placed in View and Editor, respectively.

User code can either be put into the predefined folder structure or by using AssemblyDefinitionReferences.

It is possible to opt out of the Quantum assembly definitions, for example for users migrating from such setup in Quantum 2.1 projects.

Assets/Photon

• Assets/Photon: This folder contains Photon Quantum and other packages. Changes to files in here will be overwritten during upgrades
• Assets/Photon/PhotonLibs (and PhotonRealtime): Contains Photon dependencies that Quantum uses to connect and communicate with the Quantum cloud.
• Assets/Photon/Quantum/Assemblies: Contains Quantum libraries for Unity and their debug versions.
• Assets/Photon/Quantum/Editor: Quantum Unity editor scripts. Compiles to Quantum.Unity.Editor.dll.
• Assets/Photon/Quantum/Editor/Assemblies: Contains the Quantum CodeGen libraries.
• Assets/Photon/Quantum/Editor/CodeGen: Includes the Quantum CodeGen scripts. Compiles to Quantum.CodeGen.Qtn.dll.
• Assets/Photon/Quantum/Runtime: Quantum Unity runtime scripts. Compiles to Quantum.Unity.dll.
• Assets/Photon/Quantum/Simulation: Quantum simulation core scripts. Compiles to Quantum.Simulation.dll.
• Assets/Photon/Quantum/Samples: Contains the demo menu scene and currently the GraphProfiler.

Assets/QuantumUser

• Assets/QuantumUser: Files inside this folder will never be overwritten by an upgrade and are under the developers control. It uses assembly definition references to add code to the Quantum and simulation libraries.
• Assets/QuantumUser/Editor/CodeGen: Files that extend the Qtn CodeGen.
• Assets/QuantumUser/Editor/Generated: Generated Unity Editor scripts.
• Assets/QuantumUser/Simulation: The actual simulation code.
• Assets/QuantumUser/Simulation/Generated: Generated Quantum C# code.
• Assets/QuantumUser/Resources: Runtime config files.
• Assets/QuantumUser/Scenes: The default folder for new Quantum scenes.
• Assets/QuantumUser/View: Scripts inside this folder extend the Quantum.Unity.dll.
• Assets/QuantumUser/View/Generated: Generated Quantum prototype scripts.

Quantum is split into four assemblies:

• Quantum.Simulation: contains simulation code. Any user simulation code should be added to this assembly with AssemblyDefinitionReferences. Unity/Odin property attributes can be used at will, but any use of non-deterministic Unity API is heavy discouraged. Code from this assembly can be easily worked on as a standalone .csproj, similar to quantum.code.csproj in Quantum 2.
• Quantum.Unity: contains code specific to Quantum's integration with Unity. Additionally, CodeGen emits MonoBehaviours that wraps component prototypes.
• Quantum.Unity.Editor: contains editor code for Quantum.Simulation and Quantum.Unity
• Quantum.Unity.Editor.CodeGen: contains CodeGen integration code. It is fully independent of other Quantum assemblies, so can always be run, even if there are compile errors - this may require exiting Safe Mode.

Quantum Dependencies

Quantum Hub

Open by pressing Ctrl+H or via the Quantum menu.

The Hub window will also pop up when a vital Quantum configuration files is missing (e.g. PhotonServerSettings) and recommend pressing the installation button.

The installation process takes care of installing files locally that cannot originate from the unitypackage because they would be overwritten by the next Quantum version upgrade.

Installing The Quantum Menu

The Quantum menu is an addon that can be installed with the SDK using the Hub. The unitypackage can be found under Asset/Photon/QuantumMenu/Quantum-Menu.unitypackage.

The menu is a functional and graphical in-game menu to start random online matches or create parties.

Find more information about customization possibilities here: Sample Menu Customization.

Release And Debug Builds

The Quantum libraries (Quantum.Deterministic.dll, Quantum.Engine.dll and Quantum.Corium.dll) come both in release and debug configurations. To make Unity recognize the correct library the QUANTUM_DEBUG global scripting define is used.

To toggle between debug and release use the menu:

Caveat: because the define needs to be set per platform, there is a risk that the debug version is not disabled for every platform when making release builds for example.

The debug build has significant performance penalties compared to a release build. For performance tests always use a Quantum release build (and Unity IL2CPP). Read more about this in the Profiling section.

The development build contains assertions, exceptions, checks and debug outputs that help during development and which are disabled in release configuration. For example:

• Log.Debug() and Log.Trace(), when called from the quantum code project, will not be outputting log anymore.
• As well as all Draw.Shape() methods.
• NavMeshAgentConfig.ShowDebugAvoidance and ShowDebugSteering will not draw gizmos anymore.
• Assertions and exceptions inside low level systems like physics are disabled.

Logging

Quantum provides the static Quantum.Log class to log from the simulation code and also to produce all its owns log outputs.

C#

namespace Quantum {
  public unsafe class MyQuantumSystem : SystemMainThread
    public override void Update(Frame f) {
      Log.Debug($"Updating MyQuantumSystem tick {f.Number}");
    }
  }
}

The Unity SDK has wrapper around that called QuantumUnityLogger. It will statically initialize itself during RuntimeInitializeOnLoadMethod and/or InitializeOnLoadMethod (see QuantumUnityLogger.Initialize())

The partial method InitializePartial() can be used to customize the initialization.

The QuantumUnityLogger class offers various customizations fields to for example define the color schemes.

Log Level

The global log level is controlled by Quantum.Log.LogLevel. To set the initial log level use the following scripting defines:

• QUANTUM_LOGLEVEL_TRACE
• QUANTUM_LOGLEVEL_DEBUG
• QUANTUM_LOGLEVEL_INFO
• QUANTUM_LOGLEVEL_WARN
• QUANTUM_LOGLEVEL_ERROR

They are toggled with the QuantumEditorSettings inspector.

As mentioned in the last section about debug builds Log.Trace() and Log.Debug() messages will only be logged with TRACE and DEBUG defines respectively. Notice that running the UnityEditor always defines DEBUG.

Photon Realtime Log

The Photon Realtime library used by Quantum has its own log levels that can be controlled with the Photon.Realtime.AppSettings found on the PhotonServerSettings ScriptableObject.

• AppSettings.NetworkLogging: Log level for the PhotonPeer and connection. Useful to debug connection related issues.
• AppSettings.ClientLogging: Log level for the RealtimeClient and callbacks. Useful to get info about the client state, servers it uses and operations called.

In non-development builds Realtime logs less than the ERROR severity will not log unless defining LOG_WARNING, LOG_INFO and LOG_DEBUG.

Back to top