Getting Started with Photon Quantum in Unity

This page accompanies the Photon Quantum Tutorial: Beginner Guide to Deterministic Multiplayer in Unity video and explains how to install Quantum, set up a Unity project, create a basic Quantum entity, define input, write a system, spawn a player avatar, and test online multiplayer.

Use this page if you are new to Photon Quantum and want to understand the basic workflow of building a deterministic multiplayer prototype in Unity.

Overview

Photon Quantum is a deterministic multiplayer engine.

Deterministic means that the same input produces the same simulation result on every client. Instead of synchronizing full game state between players, Quantum synchronizes player input and runs the same simulation on each client.

Unity is used for the view layer. Quantum runs the deterministic simulation, while Unity handles presentation, rendering, UI, input collection, and GameObject views.

This video covers:

• downloading and installing Photon Quantum;
• setting up a Unity project;
• understanding the Quantum project folder structure;
• exploring the default Quantum Game Scene;
• creating a Quantum entity;
• defining a custom Quantum component with QTN;
• creating a Quantum system;
• sending Unity input into the Quantum simulation;
• detecting when a player joins;
• spawning a player entity;
• moving the player with physics;
• assigning the player avatar prefab;
• configuring an App ID;
• building and testing online multiplayer.

Video Timeline

Time	Section
00:00	Introduction to Photon Quantum
00:30	Downloading and installing Quantum
01:50	Unity project setup
02:15	Quantum folder structure
03:10	Exploring the Quantum Game Scene
04:21	Quantum ECS basics
05:56	Creating your first QTN component
07:17	Creating a system
09:30	Prefabs and preparing for movement logic
10:19	Sending input from Unity to Quantum
11:30	Detecting player join and spawning player entity
13:19	Processing input and moving the player
14:04	Assigning player avatar prefab
14:21	Online setup and App ID
15:09	Building and testing online multiplayer
15:20	Closing remarks

Downloading Photon Quantum

To download Photon Quantum:

1. Open the Photon website.
2. Go to the SDKs section.
3. Select Quantum.
4. Download the Photon Quantum 3 SDK.
5. Sign in or create a Photon account if required.

At the time of recording, the video uses Quantum 3.0.8 Stable Build 1858.

For setup instructions, see:

• Photon Quantum
• What’s New in Quantum 3
• Download Photon Quantum 3

Creating the Unity Project

The video creates a new Unity project using:

• Unity 6;
• 3D URP template;
• project name: Quantum Demo.

After the project is created, import the downloaded Quantum Unity package.

When the package import is complete, the Photon Quantum Hub opens and guides you through the initial setup.

Quantum Hub Setup

After importing Quantum, complete the required setup steps in the Quantum Hub.

Recommended setup for this beginner project:

Step	Action
Install Quantum User Files	Required. Installs the user-editable Quantum project files.
Install Asteroids sample	Skipped in the video. Not required for this project.
Enter App ID	Skipped initially. The App ID is added later for online play.
Install multiplayer menu	Skipped in the video. Not required for the basic local test.
Configure log level	Set to Debug so simulation logs appear in the Unity Console.

After changing the log level, Unity recompiles the project.

Scene Overlay

After Quantum is installed, an overlay appears in the Unity Scene view.

The video docks this overlay into the scene toolbar so it remains accessible while working in the scene.

This overlay can be useful during development, but it is not required for the basic project setup.

Quantum Folder Structure

After the initial setup, the project contains two important folders:

Folder	Purpose
Photon	Contains Photon Quantum core logic. This folder should generally not be modified.
QuantumUser	Contains user project code and game-specific Quantum logic.

For this tutorial series, all game-related code is placed inside QuantumUser.

In a production project, game-specific code can also live outside QuantumUser, but that requires additional manual setup.

QuantumUser Subfolders

The QuantumUser folder contains two important areas:

Folder	Purpose
Simulation	Contains deterministic gameplay logic, including systems, components, and input handling.
View	Contains Unity-side logic, including animations, UI, rendering, and presentation code.

A useful mental model is:

• Quantum Simulation contains the game rules.
• Unity View contains how the game is displayed to the player.

Exploring the Quantum Game Scene

After importing Quantum, the project opens the Quantum Game Scene.

This scene contains the GameObjects required to run a Quantum simulation in Unity.

Two important objects are:

Object / Component	Purpose
QuantumEntityViewUpdater	Manages Unity views for Quantum entities. It creates, destroys, and updates GameObjects that represent simulation entities.
QuantumDebugInput	Collects local player input in Unity and sends it to the Quantum simulation.

Adding the Start UI

Before entering Play Mode, add the Start UI to the scene.

Use:

Tools > Quantum > Setup > Add Start UI to the Scene

If prompted, import TextMesh Pro Essentials.

When entering Play Mode, the Start UI shows options for:

• online simulation;
• local simulation.

For the first test, choose local simulation.

In local simulation mode, predicted and verified frames are identical because there is no remote server connection and no networked prediction scenario.

Quantum ECS Basics

Quantum uses an Entity Component System architecture.

This should not be confused with Unity DOTS/ECS. Quantum has its own ECS model for deterministic simulation code.

The main concepts are:

Concept	Description
Entity	A simulation object.
Component	Data attached to an entity.
System	Logic that reads and modifies component data.

In ECS, components store data. Systems contain behavior.

Creating a Quantum Entity

To create a sphere entity in the scene:

Right Click in Hierarchy > Quantum > 3D > Sphere Entity

This creates a Unity GameObject with Quantum-specific components.

Two important components are:

Component	Purpose
QuantumEntityPrototype	Represents the Quantum entity configuration in Unity. When the simulation starts, this data is baked and sent into the Quantum simulation.
QuantumEntityView	Connects the simulated entity to the Unity view so position, rotation, and other view data can be displayed.

If an object has a QuantumEntityPrototype but no QuantumEntityView, the simulation entity may still exist and move, but the movement will not be visible in Unity.

Adding Physics

The video enables PhysicsBody3D on the sphere entity.

When PhysicsBody3D is enabled, the entity responds to physics forces such as gravity.

To prevent the sphere from falling indefinitely, add a static box collider:

Right Click in Hierarchy > Quantum > 3D > Static Box Collider

Then adjust it:

• move it below the sphere;
• scale it on the X and Z axes;
• example scale: 30 on X and Z.

Creating a QTN Component

Quantum components are defined in .qtn files using the Quantum DSL.

Quantum DSL is a domain-specific language. It resembles C#, but is more restricted and is used to define deterministic simulation data.

To create the first component:

1. Open QuantumUser/Simulation.
2. Create a new folder named QTN.
3. Right-click inside the folder.
4. Select Create > Quantum > Qtn.
5. Name the file PlayerLink.

The PlayerLink component links a player to the entity they will control.

Example:

c#

component PlayerLink {
    PlayerRef Player;
}

PlayerRef identifies the player inside the Quantum simulation.

After saving the .qtn file, Unity recompiles and Quantum generates the required C# code.

Quantum components are structs. To modify their values in systems, use pointers.

Adding the Component to an Entity

After creating PlayerLink, return to the Unity Editor.

Select the sphere entity and add PlayerLink to its QuantumEntityPrototype.

This means the baked Quantum entity will contain the PlayerLink component when the simulation starts.

Creating a Quantum System

Components only store data. To execute gameplay logic, create a system.

To create the system:

1. Open QuantumUser/Simulation.
2. Create a folder named Systems.
3. Right-click inside it.
4. Select Create > Quantum > SystemFilter.

This creates a system based on SystemMainThreadFilter.

The system contains an Update method. It is similar in purpose to Unity’s Update, but runs inside the Quantum simulation.

Using a Filter

A system filter defines which entities the system runs on.

The filter must contain at least one Quantum component pointer.

Example:

c#

public struct Filter {
    public EntityRef Entity;
    public PlayerLink* PlayerLink;
}

With this filter, the system only runs on entities that have a PlayerLink component.

The * indicates a pointer. Pointers are required because Quantum components are structs and are modified through pointer access.

Registering the System

After creating a system, add it to the Quantum systems list.

To do this:

1. Search for QuantumDefaultConfigs.
2. Open the ScriptableObject.
3. Find the systems list.
4. Add a new element.
5. Set the system type to the newly created PlayerSystem.

If the system is not registered, Quantum will not run it.

Testing the System

The video tests the system by:

1. creating two sphere entities;
2. giving both PhysicsBody3D;
3. adding PlayerLink only to one sphere;
4. starting the local simulation;
5. logging entities processed by the system.

Only the entity with PlayerLink appears in the debug output.

This confirms that the filter works as expected.

Creating a Player Prefab

After testing the sphere entity:

1. Drag the configured sphere GameObject into the Project window.
2. Create a prefab from it.
3. Remove the test sphere objects from the scene.

The prefab will later be used as the player avatar spawned by the Quantum simulation.

Defining Input

In Quantum, Unity should send input to the simulation.

The input definition is created in a QTN file.

Create a new QTN file named:

Input.qtn

Add the input block:

c#

input {
    FPVector3 Direction;
}

FPVector3 is Quantum’s deterministic fixed-point vector type.

This input will be used to send movement direction from Unity to the Quantum simulation.

Sending Unity Input to Quantum

Open QuantumDebugInput.

Read Unity input axes:

c#

var direction = new Vector3();
direction.x = UnityEngine.Input.GetAxisRaw("Horizontal");
direction.z = UnityEngine.Input.GetAxisRaw("Vertical");

Unity input uses Vector3.

Quantum expects FPVector3, so convert the direction before assigning it:

c#

i.Direction = direction.ToFPVector3();

At this point, Unity sends movement input to Quantum, but the simulation still needs to process it.

Detecting When a Player Joins

To spawn a player avatar, the system needs to react when a player joins the Quantum simulation.

Implement:

c#

ISignalOnPlayerAdded

This signal is called when a player is added to the simulation.

The callback provides:

Parameter	Description
Frame f	Current simulation frame.
PlayerRef player	Reference to the player that joined.
bool isFirstTime	Indicates whether this is the player’s first join or a reconnect.

Spawning the Player Entity

Inside the player-added callback, get the player data and create the player entity:

c#

var playerData = f.GetPlayerData(player);
var playerEntity = f.Create(playerData.PlayerAvatar);

RuntimePlayer can hold player-specific data. The video uses PlayerAvatar to define which entity prefab should be spawned for the player.

Additional fields can be added to RuntimePlayer.User.cs, but that is outside the scope of this beginner setup.

Linking the Player to the Entity

The spawned player entity already has the PlayerLink component because the prefab was configured earlier.

To modify the component, retrieve a pointer:

c#

PlayerLink* playerLink = f.Unsafe.GetPointer<PlayerLink>(playerEntity);

Assign the joined player reference:

c#

playerLink->Player = player;

This links the player to the entity they control.

Processing Player Input

To move the entity, extend the system filter so it also includes the physics body.

Example:

c#

public struct Filter {
    public EntityRef Entity;
    public PlayerLink* PlayerLink;
    public PhysicsBody3D* PhysicsBody;
}

Then read the player input in the update loop:

c#

Input* input = f.GetPlayerInput(filter.PlayerLink->Player);

Apply force based on the input direction:

c#

filter.PhysicsBody->AddForce(input->Direction * 10);

The entity now moves based on input collected in Unity and processed inside the deterministic Quantum simulation.

Assigning the Player Avatar Prefab

The player prefab must be assigned to the local player configuration.

In the Game Scene:

1. Find the QuantumStartUI prefab.
2. Open the Quantum Start UI settings.
3. Find Local Players.
4. Set the array size to 1.
5. Expand Element 0.
6. Assign the ScriptableObject next to the created prefab to Player Avatar.

This tells Quantum which avatar prefab should be spawned for the local player.

Online Setup

To test online multiplayer, create a Quantum App ID in the Photon Dashboard.

Steps:

1. Open the Photon Dashboard.
2. Create a new app.
3. Set Application Type to Multiplayer.
4. Set Photon SDK to Quantum.
5. Set SDK Version to Quantum 3.
6. Give the app a name, for example Quantum Demo.
7. Copy the App ID.

Then return to Unity and open:

PhotonServerSettings

Paste the copied App ID into:

AppId Quantum

under the App Settings dropdown.

Building and Testing Online Multiplayer

To test two clients:

1. Build the Unity project as a standalone executable.
2. Use windowed mode and a smaller resolution so the build and Unity Editor can be visible at the same time.
3. Start the standalone build.
4. Enter a nickname.
5. Leave the room name empty if you want the UI to create or join automatically.
6. Press Play.
7. Enter Play Mode in the Unity Editor.
8. Connect the second player.

After both clients connect, each player spawns and can move their own physics body.

Because both avatars are physics bodies, they can move and react to each other in the simulation.

Key Concepts

Concept	Meaning
Determinism	The same input produces the same output on every client.
Input synchronization	Quantum sends player input instead of synchronizing full game state.
Simulation	Deterministic Quantum gameplay logic.
View	Unity-side presentation, rendering, UI, and animation.
Entity	A simulated object in Quantum.
Component	Data attached to an entity.
System	Logic that processes entities with specific components.
QTN	Quantum DSL file used to define simulation data such as components and input.
PlayerRef	Reference to a player in the Quantum simulation.
RuntimePlayer	Player-specific runtime configuration data.
QuantumEntityPrototype	Unity-side prototype that is baked into a Quantum entity.
QuantumEntityView	Unity-side view representation of a Quantum entity.
QuantumEntityViewUpdater	Updates Unity GameObjects based on Quantum entity state.

Best Practices

Use this checklist when starting a new Quantum project:

• Keep deterministic gameplay logic in the Quantum simulation.
• Keep Unity-specific logic in the view layer.
• Send input from Unity to Quantum, not arbitrary gameplay state.
• Define simulation data in .qtn files.
• Register new systems in the Quantum systems config.
• Use filters to control which entities a system processes.
• Use pointers when modifying Quantum component data.
• Assign player avatar prefabs through player configuration.
• Test locally before configuring online multiplayer.
• Add the Quantum App ID only when you are ready to test online.
• Use Release builds for meaningful performance tests later in development.

Related Links

• Photon
• Photon Quantum
• What’s New in Quantum 3
• Download Photon Quantum 3
• Photon Dashboard
• Photon Samples

Summary

This video introduces the basic Photon Quantum workflow in Unity.

The project starts with a local Quantum setup, then adds a simple entity, a custom component, a system, input handling, player spawning, movement logic, and finally online multiplayer through a Quantum App ID.

The main architectural separation is between Quantum simulation code and Unity view code. Quantum owns deterministic gameplay logic. Unity collects input and displays the result.

This structure allows the project to move from a local prototype to an online deterministic multiplayer test while keeping simulation logic centralized and predictable.

Back to top