This document is about: QUANTUM 3
SWITCH TO

Quantum Entity Prototypes: Scene Entities, Prefabs, and Runtime Spawning

This page accompanies the Photon Quantum Entity Prototypes Explained — Scene Entities, Prefabs & Runtime Spawning video and explains how to compose entities visually in Unity and have Quantum instantiate them with the exact component data configured in the editor.

Use this page as a reference before moving into related Quantum topics such as the Quantum Asset Database, Entity Views, or custom spawning systems.

If you want to dive deeper into Entity Prototypes, take a look at the dedicated documentation.

Photon Quantum Entity Prototypes Explained — Scene Entities, Prefabs & Runtime Spawning

Overview

In Quantum's ECS architecture, entities are just IDs, and components are pure data containers. Assembling an entity purely through code means manually adding every component and setting every value by hand.

An Entity Prototype avoids that: it lets you assemble an entity visually in the Unity Editor, assign components, and configure its starting values before the simulation instantiates it. It is a serialized description of an entity — its component composition and the exact data it is born with inside the simulation.

The video covers:

  • how to create an Entity Prototype from an empty GameObject;
  • how to add and configure components such as Transform3D and PhysicsCollider3D;
  • the difference between scene entities baked into the Map Asset and prefab entities spawned at runtime;
  • how Quantum generates an independent EntityPrototype asset for prefabs;
  • how nested Entity Prototypes form Entity Groups with a shared lifecycle;
  • how to link an Entity Prototype to its visual representation with QuantumEntityView;
  • how to reference and spawn an Entity Prototype at runtime with frame.Create.

Video Timeline

Time Section
00:00 Introduction
00:11 ECS Architecture explained
00:26 Entity Prototype explained
00:49 Creating an entity prototype
01:30 Prefab entities vs entities in the map
02:21 Prefab entity explained
02:41 Entity groups
04:25 Quantum Entity View

Entities, Components, and Why Prototypes Exist

In Quantum's ECS, an entity is nothing more than an ID, and a component is a pure data container attached to that ID.

Building an entity strictly through code requires manually creating the entity, adding each component one at a time, and setting every field by hand. For entities with several components and many initial values, this becomes tedious and error-prone to maintain.

The Entity Prototype solves this by moving composition and initial data entry into the Unity Editor, where it can be configured visually and reused across scenes and prefabs.

What Is an Entity Prototype?

An Entity Prototype is a serialized version of an entity. It records:

  • which components the entity has;
  • the initial values of each component's fields.

When the simulation instantiates a prototype, Quantum recreates the entity with exactly the composition and data configured in the editor, without any additional setup code.

Creating an Entity Prototype

To create a basic Entity Prototype:

  1. In the Hierarchy, right-click and select Quantum > Empty Entity.
  2. Unity creates a GameObject with a QuantumEntityPrototype script already attached.

This GameObject is the starting point for any entity that needs to be composed visually.

Adding Components

Components are added to an Entity Prototype directly through the QuantumEntityPrototype script:

  1. Click the plus icon on the component.
  2. Select the components to add, for example Transform3D and PhysicsCollider3D.

Any values configured here — such as the collider's size and shape, or the entity's initial rotation — are mirrored exactly into the Quantum simulation when the game starts.

Scene Entities vs. Prefab Entities

Quantum treats an Entity Prototype differently depending on where it lives.

Scene Entities and the Map Asset

If an Entity Prototype is left directly in the Unity scene, it is baked into the Map Asset. The simulation automatically loads it at the exact position and with the exact values it was baked with as soon as the map initializes.

Use this for anything that should already exist on the map at game start, with no spawning code required — for example, interactive dynamic props or test dummies.

Prefab Entities and the Quantum Asset Database

If an entity needs to be spawned dynamically during gameplay — such as a rocket fired by a player, or a newly spawned character — it should not be left in the scene. Instead, drag the Entity Prototype GameObject into the Project window to turn it into a Prefab.

When this happens, Quantum generates a separate, independent asset inside the Quantum Asset Database to represent the prefab, assigning it its own deterministic GUID. This asset sits next to the Unity Prefab in the project folder, sharing the same name with the suffix EntityPrototype.

Location Behavior
Entity Prototype in the scene Baked into the Map Asset; instantiated automatically when the map loads.
Entity Prototype as a Prefab Generates a separate EntityPrototype asset with its own GUID; spawned dynamically at runtime via code.

Entity Groups: Nested Entity Prototypes

Quantum does not have a classic hierarchy internally the way Unity does, but the editor still supports nested prototypes, often referred to as Entity Groups.

Inside the editor, a Root Entity Prototype can have child objects that also carry Entity Prototypes. When the root object is saved as a Prefab, all nested entities share its lifecycle:

  • instantiating the root entity through the simulation also creates all child entities;
  • destroying the root entity destroys the child entities as well.

This matters for complex objects made up of several tightly connected parts.

This is only a lifecycle connection, not a transform hierarchy. Once instantiated, moving the root entity does not move its children — in Quantum's ECS, their components and positions exist completely independently of one another.

Linking the Entity to Its View

To connect the logical Quantum entity to its visual representation in Unity, add a QuantumEntityView script to the Entity Prototype Prefab.

As soon as this script is added, the View field on the prototype is automatically set to Self, creating a nested Entity View asset inside the prefab itself. This tells Quantum exactly which 3D model, particles, and Unity scripts to activate when the logical entity appears in the ECS.

Referencing an Entity Prototype in Code

To spawn a prefab-based Entity Prototype dynamically, the simulation first needs a reference to its asset.

This is typically done by declaring a field of type AssetRef<EntityPrototype> in a configuration file, such as RuntimeConfig.User.cs, and dragging the prefab from the Unity Editor into that field.

C#

public AssetRef<EntityPrototype> MyPrototypeReference;

Spawning an Entity Prototype at Runtime

Inside a System, an entity can be spawned from a referenced prototype with a single call:

C#

var myEntity = frame.Create(config.MyPrototypeReference);

frame.Create returns the EntityRef of the new entity immediately. Quantum handles the rest: allocating memory, adding the configured components, and setting the values exactly as configured in Unity.

Key Concepts

Concept Description
Entity Prototype A serialized description of an entity's component composition and initial data.
QuantumEntityPrototype The script that turns a GameObject into an Entity Prototype.
Scene Entity An Entity Prototype left in the scene; baked into the Map Asset at map load.
Prefab Entity An Entity Prototype saved as a Prefab; spawned dynamically at runtime via code.
EntityPrototype asset The independent Quantum Asset Database asset generated for a prefab, with its own GUID.
Entity Group A Root Entity Prototype with nested child prototypes that share a lifecycle.
QuantumEntityView The script that links a logical entity to its visual model, particles, and Unity scripts.
AssetRef<EntityPrototype> A reference field used to pass a prototype asset into the simulation.
frame.Create The simulation call that instantiates an entity from a referenced Entity Prototype.
RuntimeConfig.User.cs A common location for declaring AssetRef<EntityPrototype> fields.

Best Practices

Use this checklist when working with Entity Prototypes:

  • Use scene-baked Entity Prototypes for anything that should already exist on the map when it loads.
  • Convert an Entity Prototype to a Prefab whenever it needs to be spawned dynamically at runtime.
  • Rely on the generated EntityPrototype asset's deterministic GUID rather than referencing prefabs directly in simulation code.
  • Use nested Entity Prototypes (Entity Groups) for complex objects made of multiple tightly connected parts.
  • Remember that nested prototypes only share a lifecycle, not transform hierarchy behavior, once instantiated.
  • Add QuantumEntityView to a prefab to link it to its 3D model, particles, and Unity-side scripts.
  • Declare AssetRef<EntityPrototype> fields in configuration files such as RuntimeConfig.User.cs to pass prototype references into the simulation.
  • Use frame.Create to spawn entities at runtime instead of manually adding components in code.

Common Pitfalls

Pitfall Why It Is a Problem
Leaving a dynamically spawned entity in the scene It gets baked into the Map Asset instead of being available for runtime spawning.
Expecting child entities to follow the root entity's transform Nested prototypes only share a lifecycle; positions and components remain independent after instantiation.
Forgetting to add QuantumEntityView The entity has no visual representation linked in Unity.
Manually adding components in code instead of using a prototype Duplicates work that the Entity Prototype and frame.Create already handle.
Losing the reference to the generated EntityPrototype asset The simulation cannot spawn the prefab without a valid AssetRef<EntityPrototype>.

Summary

Entity Prototypes let you assemble entities visually in Unity instead of building them by hand in code. Left in the scene, a prototype is baked into the Map Asset and instantiated automatically when the map loads. Saved as a Prefab, it becomes an independent asset in the Quantum Asset Database that can be spawned dynamically at runtime.

Nested prototypes form Entity Groups that share a lifecycle but not transform hierarchy behavior, and QuantumEntityView links a logical entity to its visual representation. At runtime, a referenced prototype can be instantiated with a single call to frame.Create, which allocates the entity, adds its components, and sets its values exactly as configured in the editor.

Last updated on

Back to top