Quantum View Framework and Entity Views

This page accompanies the Photon Quantum Tutorial | View Framework & Entity Views Explained video and explains how Quantum entity views, entity view components, view contexts, and scene view components work.

Use this page when you want to connect deterministic Quantum simulation data to Unity-side presentation logic such as audio, particles, camera behavior, and UI.

Overview

Quantum separates simulation logic from presentation logic.

The deterministic simulation runs in Quantum. Unity handles the visual and interactive presentation layer, including cameras, audio, particle effects, UI, animations, and scene-specific references.

For simple visual synchronization, Quantum entity views already handle the basics. With a QuantumEntityViewUpdater in the scene and an EntityView script on the entity prefab, Quantum can:

• spawn entity views;
• update their transforms;
• interpolate movement;
• smooth misprediction corrections;
• destroy entity views when simulation entities are removed.

For many game-specific presentation features, automatic transform synchronization is not enough. Quantum cannot know how your project should update a camera, play a specific sound, trigger a particle effect, or update a custom UI label.

That is what the Quantum View Framework is for.

The View Framework helps connect simulation events and state to Unity-side view logic while minimizing boilerplate code.

Video Timeline

Time	Section
00:00	Introduction to Quantum’s View Framework
01:42	Exploring the simulation side: QTN file
02:28	Exploring the simulation side: system
03:12	Creating the first Entity View Component
04:14	Entity View Component methods, fields, and properties
06:32	Subscribing to events and event handlers
07:40	Entity View Context
08:45	Entity View Component with Context
10:43	Scene View Component
11:59	Scene View Component: finding QuantumEntityViewUpdater
12:15	Challenge / bug

Entity Views

Entity views are Unity-side GameObjects that represent Quantum simulation entities.

If an entity only needs smooth visual movement, no additional view code is required beyond the default setup.

A typical setup requires:

Object / Component	Purpose
QuantumEntityViewUpdater	Scene-level component that manages entity views.
EntityView	Component on the entity prefab that connects the Unity GameObject to the Quantum entity.

The QuantumEntityViewUpdater handles:

• spawning entity views;
• updating view transforms;
• interpolating movement;
• applying misprediction correction;
• destroying or reusing views.

The default misprediction correction settings work well for most cases.

Pooling Entity Views

Entity views can be pooled to reduce runtime allocations and improve memory behavior.

For basic pooling, add the reference pool script provided by Quantum.

For advanced cases, implement the relevant pooling interface manually.

Pooling is especially relevant for projects that spawn and despawn many entity views during gameplay, such as bullets, pickups, enemies, or temporary effects.

What Entity Views Do Not Handle Automatically

Entity views solve the basic problem of visualizing simulated entities, but they do not automatically handle game-specific presentation logic.

Examples of features that require custom view code:

• updating a camera;
• playing sound effects;
• spawning particles;
• updating UI;
• changing animation states;
• displaying local-player-only effects;
• reacting to simulation events.

The View Framework provides structured hooks for this Unity-side logic.

Simulation Side: Events and Systems

The tutorial project already contains Quantum simulation events in DSL files.

One example is an event triggered when a coin is collected.

The corresponding simulation systems trigger these events at the relevant moment.

The View Framework can subscribe to these simulation events from Unity-side view components and react to them.

This allows the deterministic simulation to remain clean while Unity handles presentation behavior such as playing a sound effect.

Creating an Entity View Component

To create an entity-specific view component, use the Unity context menu:

Create > Quantum > EntityView Component

In the video, the component is named:

CharacterSFXHandler

After Unity finishes compiling:

1. Drag the component onto the character prefab.
2. Apply the prefab changes.
3. Open the script in the code editor.

Adding Unity References

The CharacterSFXHandler needs Unity-side references to play a sound effect.

Add public fields for:

• the coin audio clip;
• the audio source used to play the clip.

Example:

c#

public AudioClip CoinSfx;
public AudioSource AudioSource;

After compiling, return to Unity and assign both references in the prefab Inspector.

The script now has all required Unity references, but it still needs to subscribe to the simulation event.

Subscribing to Simulation Events

Use OnActivate to subscribe when the view becomes associated with a Quantum entity.

OnActivate is called each time the entity view is connected to a simulation entity.

This is the right place for entity-specific initialization, including event subscriptions.

When subscribing, use parameters such as OnlyIfActive and Enabled so the handler only runs while the view is active.

This avoids the need to manually unsubscribe when the view is despawned.

Filtering Events by Entity

A simulation event may be emitted for any entity.

The view component should only react if the event belongs to the same entity as the view.

To do this, compare the event entity reference with the entity reference associated with the view.

Conceptually:

c#

if (eventData.Entity != EntityRef) {
    return;
}

After verifying that the event belongs to this entity, play the audio clip once through the assigned audio source.

The result is that the character plays a coin collection sound whenever that specific character collects a coin.

Entity View Component Methods

Entity view components provide lifecycle callbacks for common view logic.

Method	Description
OnInitialize	Called once when the Entity View GameObject is first spawned.
OnActivate	Called every time the view is associated with a Quantum entity.
OnDeactivate	Called when the view is no longer associated with the entity.
OnUpdateView	Called every Unity update after the view transform has been updated and interpolated.
OnLateUpdateView	Called after all views have completed OnUpdateView.
OnGameChanged	Called when the observed Quantum game changes.

OnInitialize

OnInitialize is called only once, the first time an Entity View GameObject is spawned.

This matters when pooling is used.

If a pooled view is reused for another entity later, OnInitialize is not called again. Use it only for setup that should happen once per GameObject lifetime.

OnActivate and OnDeactivate

OnActivate and OnDeactivate are called whenever the view is assigned to, or removed from, a simulation entity.

These methods are called reliably when using pooling.

Use them for entity-specific initialization and cleanup.

Good use cases include:

• subscribing to entity-related events;
• caching entity-specific state;
• enabling local-player-only presentation logic;
• resetting view-specific runtime values;
• disabling effects when the entity is removed.

OnUpdateView

OnUpdateView is called every Unity update.

It is called after the Entity View transform has already been updated and interpolated.

Use it to poll simulation state related to this entity and update Unity-side presentation.

Good use cases include:

• camera follow behavior;
• animation parameter updates;
• visual state interpolation;
• entity-specific UI indicators;
• presentation logic that depends on the current frame.

OnLateUpdateView

OnLateUpdateView is similar to Unity’s LateUpdate.

It is called after all entity views have run OnUpdateView.

Use it for logic that depends on all views having already updated for the current Unity frame.

OnGameChanged

OnGameChanged is called when the active observed Quantum game changes.

A common case is instant replay.

When a replay starts, Quantum switches to observe the replay game. When the replay ends, it switches back to the main game instance.

Use OnGameChanged if camera behavior, UI, or other view logic needs to change while observing a replay.

Entity View Context

Some view components need references to objects already present in the Unity scene.

Examples include:

• the main camera;
• UI root objects;
• TextMesh Pro labels;
• audio mixers;
• scene-specific managers;
• post-processing objects.

Dynamically spawned entity views cannot easily reference these scene objects directly through prefab fields.

View Contexts solve this.

A View Context is a Unity MonoBehaviour attached to the QuantumEntityViewUpdater GameObject. Quantum can inject this context into view components that request it.

Creating a View Context

To create a View Context class, use:

Create > Quantum > View Context

In the video, the class is named:

CameraContext

Add a field for the camera transform:

c#

public Transform CameraTransform;

Then:

1. Attach CameraContext to the QuantumEntityViewUpdater GameObject.
2. Drag the scene camera into the CameraTransform field.
3. Save the scene.

The context can now be injected into context-aware view components.

Entity View Component with Context

To create an entity view component that depends on a context, use:

Create > Quantum > Entity View Component With Context

In the video, the component is named:

CharacterCameraHandler

This component uses CameraContext to make the camera follow the local player.

Context-aware view components are generic classes. The required context type is specified as the generic type.

Conceptually:

c#

public unsafe class CharacterCameraHandler 
    : QuantumEntityViewComponent<CameraContext>
{
}

The QuantumEntityViewUpdater injects the requested context when the Entity View is registered at runtime.

Running Camera Logic Only for the Local Player

Camera follow logic should only run for the character controlled by the local client.

Otherwise, each client could try to follow every player character.

The video uses a common pattern:

1. Check whether the entity has a PlayerLink component.
2. Read the player reference from PlayerLink.
3. Check whether that player is controlled by the local client.
4. Enable camera follow only for the local player entity.

This ensures that in online play, each client’s camera follows only its own character.

Base Class References

The View Framework base class provides several useful references.

Examples include:

Reference	Purpose
Game	The active Quantum game instance.
PredictedFrame / frame references	Access to simulation frame data, depending on context.
EntityRef	The Quantum entity associated with this view.
View / transform references	Access to the Unity-side entity view.
Context	The injected view context for context-aware components.

This reduces boilerplate and keeps view scripts focused on presentation logic.

Camera Follow Logic

The tutorial camera logic follows the player horizontally.

The script checks whether the absolute horizontal difference between the camera and character exceeds a threshold.

If the threshold is exceeded, the camera position is updated.

Because OnUpdateView is called after the Entity View transform has been interpolated, camera follow behavior uses the already-smoothed view position.

After implementing the script:

1. Add CharacterCameraHandler to the character prefab.
2. Apply prefab changes.
3. Enter Play Mode.
4. Verify that the camera follows the local player.

In online play, each client should follow only the character controlled by that client.

Scene View Components

So far, the examples are entity-specific. They are attached to entity prefabs and run in relation to a specific Quantum entity.

Some view logic is not tied to a single entity.

Examples include:

• game score UI;
• match timer UI;
• global audio;
• scene transitions;
• spectator UI;
• replay UI;
• global VFX or screen effects.

For these cases, use a scene-level view component.

Example: Score UI

The video implements a scene view component for the main game score UI.

The score is stored in a singleton component in the Quantum simulation and represents the total number of coins collected by all players combined.

First, create the UI object in Unity.

For example:

• create a TextMesh Pro label;
• position it in the UI;
• style it as needed.

Then add a field to CameraContext to reference the TextMesh Pro text component.

Example:

c#

public TMP_Text ScoreText;

Return to Unity and assign the UI text object to the context field.

Creating a Scene View Script

Create a normal Unity C# script:

ScoreView

Make it extend the Quantum view component base class and use the same context type.

Conceptually:

c#

public class ScoreView : QuantumViewComponent<CameraContext>
{
}

From OnActivate, subscribe to the Quantum event that is triggered when a player scores a point.

In the event callback, update the score UI text with the new value.

Updating Text and Garbage Collection

Be careful when modifying UI text frequently.

Some text update patterns can allocate memory and create garbage collection pressure.

For this simple tutorial example, updating the text in response to score events is acceptable because the event is not called frequently.

For high-frequency UI updates, use allocation-conscious text formatting patterns.

Attaching the Scene View Script

Attach the scene view script to the same GameObject that contains the QuantumEntityViewUpdater.

Then save the scene.

When the game runs, the score UI updates whenever the character collects a coin.

Finding QuantumEntityViewUpdater

Scene view components and View Contexts should be attached where the QuantumEntityViewUpdater can find and manage them.

In the tutorial setup, this means attaching them to the QuantumEntityViewUpdater GameObject.

This allows the View Framework to register the components and inject the configured context.

Common View Framework Use Cases

Use Case	Recommended Tool
Smoothly displaying an entity position	EntityView and QuantumEntityViewUpdater
Playing SFX for one entity	Entity View Component
Spawning VFX for one entity	Entity View Component
Camera follow for local player	Entity View Component with Context
Accessing scene camera from spawned views	View Context
Updating global score UI	Scene View Component
Updating match timer UI	Scene View Component
Handling replay-specific camera/UI changes	OnGameChanged

Best Practices

Use this checklist when working with the Quantum View Framework:

• Keep deterministic gameplay logic in the Quantum simulation.
• Keep audio, UI, camera, particles, and rendering logic in Unity view code.
• Use entity views for visual representations of Quantum entities.
• Use entity view components for presentation logic tied to a specific entity.
• Use OnActivate for entity-specific setup.
• Use OnDeactivate for entity-specific cleanup.
• Use OnInitialize only for one-time GameObject setup.
• Use OnUpdateView for view logic that depends on the interpolated entity transform.
• Use View Contexts for scene references needed by dynamically spawned views.
• Attach View Contexts to the QuantumEntityViewUpdater GameObject.
• Use scene view components for UI and presentation logic not tied to one entity.
• Filter event handlers so a view reacts only to events for its own entity.
• Make local-only presentation logic check whether the entity belongs to the local player.
• Be careful with garbage allocation when updating UI text.
• Use pooling for frequently spawned entity views.

Common Pitfalls

Pitfall	Why It Is a Problem
Putting camera or UI logic into the deterministic simulation	These are Unity-side presentation concerns and should stay in the view layer.
Assuming every event belongs to the current view entity	Event handlers must check entity references before reacting.
Forgetting to apply prefab changes	New entity view components will not be present on spawned views.
Assigning scene references directly to spawned prefabs	Dynamically spawned prefabs should use View Contexts for scene dependencies.
Running camera follow logic for all players	Each client should follow only its local player.
Using OnInitialize for per-entity setup with pooling	OnInitialize is not called every time a pooled view is reused.
Updating UI text every frame without considering allocations	Frequent text changes can create garbage collection pressure.
Forgetting to attach View Contexts to the QuantumEntityViewUpdater	Context injection depends on the updater finding the context.

Related Links

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

Summary

Quantum entity views handle the basic visual representation of simulation entities, including transform updates, interpolation, and misprediction correction.

The View Framework extends this by providing structured Unity-side components for presentation logic.

Entity view components are used for logic tied to a specific entity, such as playing a sound when that entity collects a coin. View Contexts provide scene references, such as a camera or UI label, to dynamically spawned views. Scene view components handle presentation logic that is not tied to one specific entity, such as updating global score UI.

This keeps the deterministic simulation focused on gameplay state and rules, while Unity handles cameras, audio, UI, and other presentation-specific behavior.

Back to top