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.
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
Transform3DandPhysicsCollider3D; - the difference between scene entities baked into the Map Asset and prefab entities spawned at runtime;
- how Quantum generates an independent
EntityPrototypeasset 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:
- In the Hierarchy, right-click and select
Quantum > Empty Entity. - Unity creates a GameObject with a
QuantumEntityPrototypescript 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:
- Click the plus icon on the component.
- Select the components to add, for example
Transform3DandPhysicsCollider3D.
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
EntityPrototypeasset'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
QuantumEntityViewto a prefab to link it to its 3D model, particles, and Unity-side scripts. - Declare
AssetRef<EntityPrototype>fields in configuration files such asRuntimeConfig.User.csto pass prototype references into the simulation. - Use
frame.Createto 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- Overview
- Video Timeline
- Entities, Components, and Why Prototypes Exist
- What Is an Entity Prototype?
- Creating an Entity Prototype
- Adding Components
- Scene Entities vs. Prefab Entities
- Entity Groups: Nested Entity Prototypes
- Linking the Entity to Its View
- Referencing an Entity Prototype in Code
- Spawning an Entity Prototype at Runtime
- Key Concepts
- Best Practices
- Common Pitfalls
- Summary