Quantum Assets: Deterministic Data, AssetRefs, and Unity Integration

This page accompanies the Photon Quantum Assets Explained – Deterministic Data, AssetRefs & Unity Integration video and explains how Quantum assets are created, referenced, retrieved, and used across the deterministic simulation and the Unity view layer.

Use this page when you need to store shared configuration, reference gameplay data from components or runtime configuration, implement data-driven polymorphism, or connect deterministic asset data to Unity-specific presentation resources.

Overview

Quantum assets are C# classes used as shared data containers.

In Unity projects, Quantum asset classes inherit from AssetObject, which integrates them with Unity’s ScriptableObject workflow. Asset instances are stored in the Quantum asset database and are identified by a deterministic GUID and path.

Unlike components, assets are not stored directly in the simulation frame. Simulation code accesses them through references such as AssetRef<T>.

Asset fields should be treated as immutable during the simulation. Changing an asset field at runtime is not synchronized between clients and is not part of Quantum’s rollback state.

Switching an AssetRef, however, is deterministic and rollback-compatible when that reference is stored in simulation state.

This video covers:

• what Quantum assets are;
• how assets differ from components;
• how asset paths and GUIDs work;
• how to create a custom asset class;
• how to create an asset instance in Unity;
• how to expose an asset through RuntimeConfig;
• how to retrieve an asset with Frame.FindAsset;
• why asset values should not be modified at runtime;
• how to switch asset references deterministically;
• how to add methods and polymorphic behavior to asset classes;
• which built-in Quantum systems use assets;
• how to inspect the Quantum asset database;
• how to load assets without access to a simulation frame;
• how assets integrate with Unity and Addressables;
• which Unity types must remain outside deterministic simulation code.

Video Timeline

Time	Section
00:00	Introduction
00:22	What are Quantum assets?
01:42	Creating a custom asset class
02:07	Creating an asset instance
02:44	Using the asset in a system
04:22	Changing asset values at runtime
04:37	Switching between asset references
05:22	Methods in asset objects
05:47	Data-driven polymorphism
06:16	Quantum built-in assets
06:36	Changing asset search paths
06:46	Quantum asset database
07:19	Retrieving assets in the Editor or without a frame
07:44	Assets and Addressables
07:56	Assets in the Unity view
08:24	Unity types in simulation code
09:01	Advanced asset topics

What Are Quantum Assets?

Quantum assets are classes that contain reusable data and behavior.

In Unity, custom Quantum asset classes inherit from:

c#

AssetObject

AssetObject integrates the asset with Unity’s ScriptableObject-based authoring workflow.

Because the class is represented by a .cs file, its class name must match the source file name.

For example:

AssetBasic.cs

should contain:

c#

public class AssetBasic : AssetObject
{
}

Assets Compared to Components

Components and assets serve different purposes.

Type	Stored In	Typical Purpose	Mutable During Simulation
Component	Simulation frame	Per-entity runtime state	Yes, through the frame
Singleton component	Simulation frame	Global runtime state	Yes
Runtime configuration	Match configuration	Data shared when starting a session	Set before the simulation
Quantum asset	Asset database	Shared configuration and reusable behavior	Treat as immutable

Components represent state that changes during gameplay.

Examples include:

• current health;
• current velocity;
• active weapon index;
• cooldown remaining;
• current skill reference.

Assets represent shared definitions or configuration.

Examples include:

• weapon properties;
• skill behavior;
• character configuration;
• physics materials;
• maps;
• system configurations;
• entity prototypes.

Asset References

Quantum assets are not retrieved directly from the frame like components.

Instead, they are referenced using types such as:

c#

AssetRef<AssetBasic>

The reference identifies an asset in the Quantum asset database.

Simulation code passes the reference to an asset lookup method, which resolves it to the corresponding asset object.

This separation keeps shared asset definitions outside the mutable simulation state while allowing simulation data to reference them deterministically.

Asset Path and GUID

Every Quantum asset has two important identifiers:

Identifier	Purpose
Path	Describes where the asset is located in the asset structure.
GUID	Unique deterministic identifier used by the Quantum asset database.

The GUID is generated when the asset instance is created.

Asset references use this deterministic identity to resolve the corresponding asset across clients and simulation instances.

Asset Data Is Immutable During Simulation

Asset fields should only be read during simulation runtime.

Do not change values inside a Quantum asset while the simulation is running.

For example, do not modify a shared character asset to change its speed:

c#

characterAsset.Speed = newSpeed;

This is unsafe because asset field changes:

• are not exchanged as player input;
• are not sent to other clients;
• are not stored as frame state;
• are not restored through rollback;
• can cause different clients to simulate different results.

Store mutable values in components or other frame-backed simulation data instead.

Deterministic Asset Reference Switching

Although asset fields must remain immutable, references to assets can be switched during runtime.

For example, a component can store:

c#

AssetRef<CharacterSkill> CurrentSkill;

The simulation can replace CurrentSkill with a reference to another asset.

The referenced asset remains immutable, but the reference stored in the component changes as part of the simulation state.

This approach is:

• deterministic;
• rollback-compatible;
• suitable for changing weapons, skills, classes, or configurations.

Use multiple immutable asset definitions rather than changing one shared asset object.

Creating a Custom Asset Class

To create a custom asset class:

1. Open the simulation folder.
2. Select:
   Create > Quantum > Asset Script
3. Name the file:
   AssetBasic

The generated class inherits from AssetObject.

Add a deterministic field for the example:

c#

public FP Value;

The complete class can look like:

c#

public class AssetBasic : AssetObject
{
    public FP Value;
}

FP is Quantum’s deterministic fixed-point number type.

Creating an Asset Instance

Creating the class does not automatically create a usable asset instance.

To create the asset object in Unity:

1. Open the project’s Resources folder.
2. Right-click.
3. Select:
   Create > Quantum > Asset
4. Search for:
   AssetBasic
5. Select the class.

Unity creates a ScriptableObject instance of AssetBasic.

When the instance is created:

• its GUID is populated;
• the asset is discovered by Quantum;
• it becomes available through the Quantum asset database.

RuntimeConfig

RuntimeConfig contains per-match configuration.

It defines data that is selected for a particular game session rather than fixed globally for the entire project.

Typical runtime configuration data can include:

• selected map;
• random seed;
• game mode;
• match-specific parameters;
• asset references used by the session.

Custom runtime configuration fields are commonly added in:

RuntimeConfig.User.cs

Adding an AssetRef to RuntimeConfig

To make the custom asset available through the match configuration, add an AssetRef field:

c#

public AssetRef<AssetBasic> AssetBasic;

After compiling:

1. Find the RuntimeConfig ScriptableObject used by the scene.
2. Locate the new AssetBasic field.
3. Drag the created AssetBasic asset into the field.

All clients starting the simulation with this runtime configuration now use the same asset reference.

Retrieving an Asset in a System

Assets are resolved through the simulation frame.

For example, inside a system initialization method:

c#

public override void OnInit(Frame f)
{
    var asset = f.FindAsset(f.RuntimeConfig.AssetBasic);

    Log.Debug($"Asset value: {asset.Value}");
}

The generic asset type can be inferred from the type of the AssetRef.

The lookup process is:

1. Read the asset reference from RuntimeConfig.
2. Use the GUID stored by the reference.
3. Find the matching asset in the Quantum asset database.
4. Return the complete asset object.
5. Read its immutable fields or call its methods.

Retrieving Assets with Explicit Types

An explicitly typed lookup can also be used where required:

c#

var asset = f.FindAsset<AssetBasic>(
    f.RuntimeConfig.AssetBasic
);

Both approaches resolve the asset reference to its asset object.

Using Asset Values

After retrieving the asset, its fields can be used in deterministic simulation logic.

For example:

c#

var value = asset.Value;

The value can influence:

• movement;
• damage;
• cooldowns;
• entity creation;
• ability behavior;
• simulation rules.

The asset itself must remain unchanged.

If a mutable value is needed, copy it into a component or another frame-backed structure.

Switching Character Skills

The video demonstrates deterministic asset switching by changing the skill references used by several characters.

A character can store a reference such as:

c#

AssetRef<CharacterSkill> Skill;

To switch skills:

1. Find the character entities.
2. Retrieve their mutable components.
3. Assign a different AssetRef<CharacterSkill>.
4. Let the simulation resolve the newly referenced skill when used.

After switching the references, characters execute different abilities or spawn different effects.

The assets themselves have not changed. Only the simulation-backed references have changed.

Asset Methods

Asset objects are classes and can contain methods in addition to fields.

For example:

c#

public class BasicCharacter : AssetObject
{
    public FP Speed;
    public FP Health;

    public void LogCharacterDetails()
    {
        Log.Debug($"Speed: {Speed}, Health: {Health}");
    }
}

Methods can use the asset’s immutable fields to perform calculations, return values, or execute reusable behavior.

The same immutability rule applies inside asset methods.

Do not change asset fields from within those methods.

Data-Driven Polymorphism

Because Quantum asset objects are classes, they can use inheritance and polymorphism.

This provides an alternative to component inheritance, which is not available because Quantum components are structs.

For example:

c#

public abstract class CharacterSkill : AssetObject
{
    public abstract void Use(Frame frame, EntityRef entity);
}

Derived classes can implement different behaviors:

c#

public class FireSkill : CharacterSkill
{
    public override void Use(Frame frame, EntityRef entity)
    {
        // Fire skill behavior
    }
}

c#

public class IceSkill : CharacterSkill
{
    public override void Use(Frame frame, EntityRef entity)
    {
        // Ice skill behavior
    }
}

Simulation code can hold a base reference:

c#

AssetRef<CharacterSkill> Skill;

When the asset is resolved, calling Use executes the derived implementation associated with the referenced asset.

This is known as data-driven polymorphism.

When to Use Data-Driven Polymorphism

Data-driven polymorphism is useful when multiple gameplay definitions share common data but require different behavior.

Examples include:

• weapons;
• skills;
• projectiles;
• character classes;
• AI behaviors;
• interactables;
• effects;
• item types.

Keep mutable runtime state in components and reusable definitions or behavior in immutable assets.

Built-In Quantum Assets

Quantum itself uses assets for many core systems.

When opening:

Create > Quantum > Asset

the available asset types can include:

• physics materials;
• navmeshes;
• maps;
• system configurations;
• entity prototypes;
• other Quantum configuration objects.

The same reference and database model used by custom assets is also used by Quantum’s built-in assets.

Asset Search Paths

By default, Quantum searches the configured project locations for asset objects.

To customize asset discovery, open:

QuantumEditorSettings

Then edit:

Asset Search Paths

Use this setting when:

• assets are stored outside the default project folders;
• only selected directories should be scanned;
• the project has a custom asset organization;
• imported packages should be included or excluded.

Make sure required assets are located inside configured search paths.

Quantum Unity Database

To inspect the asset database, open:

Tools > Quantum > Window > Quantum Unity DB

The database window can be used to:

• find assets;
• inspect asset paths;
• copy GUIDs;
• load asset instances;
• debug missing references;
• verify whether an asset has been discovered.

The database window is mainly an editor and debugging tool. Gameplay systems should normally use AssetRef and frame-based lookup APIs.

EntityPrototype and EntityView Assets

EntityPrototype and EntityView are also part of Quantum’s asset workflow.

EntityPrototype

The entity prototype is typically represented by a standalone asset that links to its source prefab.

It contains the baked data used to create the Quantum simulation entity.

EntityView

The entity view asset is embedded in the Unity prefab.

It connects the simulation entity to the Unity-side visual representation.

Although these objects are commonly encountered through prefabs and scene tooling, they are integrated with the same broader Quantum asset system.

Retrieving Assets Without a Frame

Some Unity-side code may need to load a Quantum asset without access to a simulation Frame.

For runtime Unity code, use:

c#

QuantumUnityDB.GetGlobalAsset()

Depending on the API overload, the asset can be identified by:

• asset reference;
• GUID;
• path.

Use this API for Unity-side runtime integration when no simulation frame is available.

Simulation gameplay code should continue to use frame-based asset lookup.

Retrieving Assets in Editor Code

For editor-only tooling, use:

c#

QuantumUnityDB.GetGlobalAssetEditorInstance()

This editor-compatible API is intended for Unity Editor workflows rather than runtime simulation logic.

Examples include:

• custom inspectors;
• editor validation;
• build tools;
• asset migration tools;
• editor windows.

Assets and Addressables

Quantum assets support Unity Addressables.

No additional asset-system integration is required solely because Addressables are enabled.

Continue using Quantum asset references and database APIs while configuring the Unity project’s Addressables workflow as required.

Validate the project’s loading and packaging setup on all intended target platforms.

Unity-Specific Fields in Assets

Quantum asset classes can also contain Unity-specific references.

Examples include:

• GameObject;
• ParticleSystem;
• AudioClip;
• materials;
• sprites;
• Unity animation assets.

These references are intended for Unity view code.

They must not be used by deterministic simulation logic because Unity object types are not guaranteed to behave deterministically.

Wrapping Unity-Specific Fields

Wrap Unity-only fields with:

c#

#if QUANTUM_UNITY
#endif

Example:

c#

public class CharacterSkill : AssetObject
{
    public FP Damage;

#if QUANTUM_UNITY
    public UnityEngine.GameObject EffectPrefab;
    public UnityEngine.AudioClip SoundEffect;
#endif
}

This separates deterministic data from Unity-specific presentation resources.

It also allows the simulation assembly to compile outside Unity, such as in a standalone .NET environment.

Simulation and View Separation

A single asset can contain both deterministic configuration and Unity presentation references, provided the boundaries remain explicit.

Asset Data	Used By
FP Damage	Quantum simulation
FP Cooldown	Quantum simulation
Entity prototype reference	Quantum simulation
Particle prefab	Unity view
Audio clip	Unity view
Material or sprite	Unity view

Simulation code must only access deterministic fields.

Unity view code can use the Unity-specific fields to present the simulation result.

Advanced Asset Creation

Quantum also supports more advanced asset workflows.

Static Assets Created Before Simulation

Static assets can be created from code before the simulation begins.

This can be useful for content such as:

• maps downloaded from a backend;
• generated level definitions;
• externally supplied configuration;
• procedural match data.

These assets must be created and registered before they are needed by the simulation.

Dynamic Assets Created at Runtime

Quantum can also support dynamic asset creation when the simulation starts.

Dynamic asset workflows require additional lifecycle, synchronization, and registration considerations.

Use the dedicated Quantum documentation for these advanced cases.

Recommended Asset Workflow

Use this workflow when adding custom assets:

1. Create a class that inherits from AssetObject.
2. Keep the class name identical to the .cs file name.
3. Add deterministic configuration fields.
4. Wrap Unity-only fields in #if QUANTUM_UNITY.
5. Create an asset instance through Create > Quantum > Asset.
6. Verify that the asset has a GUID.
7. Store an AssetRef<T> in configuration or simulation state.
8. Resolve the asset through Frame.FindAsset.
9. Read fields or call methods without modifying the asset.
10. Switch references when gameplay configuration needs to change.
11. Store mutable runtime values in components.
12. Use QuantumUnityDB APIs only for Unity-side or editor-side access.

Key Concepts

Concept	Description
AssetObject	Base class for Quantum assets in Unity.
AssetRef<T>	Deterministic reference to a Quantum asset.
Asset database	Database containing discovered Quantum asset instances.
GUID	Deterministic unique identifier for an asset.
Path	Location identifier for an asset.
Frame.FindAsset	Resolves an asset reference inside simulation code.
RuntimeConfig	Per-match configuration shared when starting a simulation.
Immutable asset data	Asset fields that should only be read during runtime.
Reference switching	Deterministic replacement of one asset reference with another.
Data-driven polymorphism	Using asset class inheritance and virtual methods for configurable behavior.
QuantumUnityDB	Unity-side API and tooling for accessing Quantum assets.
QUANTUM_UNITY	Compilation symbol used to isolate Unity-specific asset fields.
Static asset	Asset created and registered before simulation use.
Dynamic asset	Asset created as part of a runtime asset workflow.

Best Practices

Use this checklist when working with Quantum assets:

• Use assets for shared, immutable configuration.
• Use components for mutable runtime state.
• Access assets through AssetRef<T>.
• Resolve simulation assets through Frame.FindAsset.
• Never rely on runtime asset field mutation.
• Switch asset references instead of changing asset values.
• Store changed references in frame-backed data.
• Use asset methods for reusable behavior based on immutable fields.
• Use inheritance and polymorphism in asset classes, not components.
• Keep the asset class name identical to the file name.
• Verify that required assets are inside configured search paths.
• Use the Quantum Unity DB to diagnose missing assets or GUIDs.
• Keep Unity object references out of deterministic simulation logic.
• Wrap Unity-specific fields in #if QUANTUM_UNITY.
• Use frame-based lookup in simulation code.
• Use QuantumUnityDB APIs for Unity-side and editor-side workflows.
• Validate advanced static or dynamic asset creation against the relevant documentation.

Common Pitfalls

Pitfall	Why It Is a Problem
Modifying an asset field during simulation	The change is not synchronized or rolled back and can break determinism.
Treating an asset like a component	Assets do not live directly in the simulation frame.
Forgetting to create an asset instance	A class definition alone does not create a database asset.
Using a direct asset object where an AssetRef is required	Simulation state should store deterministic references.
Storing mutable gameplay state in an asset	Shared asset state is not frame-backed.
Using Unity types in simulation code	Unity object types are not deterministic.
Forgetting #if QUANTUM_UNITY	Can break compilation outside the Unity environment.
Changing asset search paths without including required folders	Assets may disappear from the Quantum database.
Using editor asset APIs at runtime	Editor instances are intended for tooling, not builds.
Switching a local Unity reference instead of simulation state	The change may not be deterministic or shared by all clients.
Assuming Addressables replace Quantum asset references	Quantum references and database identity are still required.

Related Links

• Photon
• Photon Quantum
• Quantum Documentation
• Photon Dashboard
• Photon Samples

Summary

Quantum assets are shared class-based definitions stored in the Quantum asset database.

Simulation code references them through AssetRef<T> and resolves them with Frame.FindAsset. Their fields should remain immutable during runtime because asset mutations are not synchronized or rollback-compatible.

When gameplay configuration needs to change, switch the asset reference stored in simulation state instead of modifying the asset itself.

Because assets are classes, they can also contain methods, use inheritance, and support data-driven polymorphism. Unity-specific references can be included for view code, but they must be separated from deterministic simulation fields and wrapped in #if QUANTUM_UNITY.

This asset model provides a structured way to share deterministic configuration, extend gameplay behavior, and connect Quantum simulation data with Unity presentation resources.

Back to top