EntityBuilder struct
#include <Runtime/ECS/Public/EntityBuilder.h>
Public types
- struct SceneMeta
- Scene-level metadata parsed without spawning any entities.
Public static functions
- static auto SpawnEntity(Registry* reg, const JsonValue& entityJson, bool bBackground = false) -> EntityHandle
- Spawn a single entity from a JSON object.
- static auto SpawnScene(Registry* reg, const JsonValue& sceneJson, bool bBackground = false) -> size_t
- Spawn all entities described in a scene JSON.
- static auto SpawnFromFile(Registry* reg, const char* filePath, bool bBackground = false) -> size_t
- Load a .prefab or .tnxscene file from disk and spawn its contents.
- static auto StreamChunkTracked(Registry* reg, const AssetID& assetID, uint16_t instanceIndex = 0) -> size_t
- Background-load a content chunk by AssetID and register spawned handles.
- static auto ActivateStreamedChunk(Registry* reg, int64_t assetIDRaw, uint16_t instanceIndex = 0) -> std::vector<uint32_t>
- Activate entities registered by StreamChunkTracked for (assetID, instanceIndex).
- static auto SpawnFromFileTracked(Registry* reg, const char* filePath, bool bBackground, std::vector<GlobalEntityHandle>& outHandles) -> size_t
- Like SpawnFromFile but also collects GlobalEntityHandle of each spawned entity.
- static auto SpawnFromAsset(Registry* reg, const AssetID& id, bool bBackground = false) -> size_t
- Load by AssetID — resolves the path via
AssetRegistry::ResolvePath. -
template<template<FieldWidth> class TEntity>static auto SpawnTyped(Registry* reg, AssetID prefabID, bool bBackground = false) -> EntityHandle
- Typed prefab spawn from an AssetID.
- static auto SpawnEntityFromFile(Registry* reg, const char* filePath, bool bBackground = false) -> EntityHandle
- Load a single-entity prefab from a file path and spawn it.
- static auto ParseSceneMeta(const JsonValue& sceneJson) -> SceneMeta
- Parse scene-level metadata from a JSON scene without spawning entities.
- static auto SerializeEntity(Registry* reg, Archetype* arch, size_t chunkIdx, uint32_t localIndex) -> JsonValue
- Serialize a single entity at a given slot within an archetype chunk.
- static auto SerializeScene(Registry* reg, const char* sceneName, const char* defaultState = nullptr, const char* defaultMode = nullptr) -> JsonValue
- Serialize all entities in the registry into a scene JSON document.
- static auto SaveToFile(Registry* reg, const char* sceneName, const char* filePath, const char* defaultState = nullptr, const char* defaultMode = nullptr) -> bool
- Save a scene to disk.
Function documentation
static EntityHandle EntityBuilder::
Spawn a single entity from a JSON object.
| Parameters | |
|---|---|
| reg | |
| entityJson | |
| bBackground | If true, entity is Alive but not Active — will not tick or render until an explicit Alive→Active sweep. |
| Returns | The created handle, or an invalid handle on failure. |
Expected format: { "type": "CubeEntity", "components": { "CTransform": { "PosX": 1.0, ... } } }
static size_t EntityBuilder::
Spawn all entities described in a scene JSON.
| Parameters | |
|---|---|
| reg | |
| sceneJson | |
| bBackground | Passed through to each SpawnEntity call. |
| Returns | Number of entities successfully spawned. |
Expected format: { "name": "SceneName", "entities": [ ... ] }
static size_t EntityBuilder::
Load a .prefab or .tnxscene file from disk and spawn its contents.
| Parameters | |
|---|---|
| reg | |
| filePath | |
| bBackground | See SpawnEntity. |
| Returns | Number of entities spawned (1 for prefab, N for scene). |
File I/O and JSON parse are synchronous on the calling thread.
static size_t EntityBuilder::
Background-load a content chunk by AssetID and register spawned handles.
| Returns | Number of entities spawned. |
|---|
InstanceIndex disambiguates multiple simultaneous loads of the same asset. Must be called from a logic-thread-synchronized context (SpawnAndWait / PostAndWait).
static std::vector<uint32_t> EntityBuilder::
Activate entities registered by StreamChunkTracked for (assetID, instanceIndex).
Sets Active|Dirty|DirtiedFrame on each slot. Returns slab indices for rollback event replay. Must be called from a logic-thread-synchronized context.
static size_t EntityBuilder::
Like SpawnFromFile but also collects GlobalEntityHandle of each spawned entity.
| Parameters | |
|---|---|
| reg | |
| filePath | |
| bBackground | |
| outHandles out | Receives a handle per successfully spawned entity. |
template<template<FieldWidth> class TEntity>
static EntityHandle EntityBuilder::
Typed prefab spawn from an AssetID.
Loads a single-entity prefab and creates an entity of type TEntity. Asset-ref fields are resolved through the checkout system. Typically called from ConstructView::Initialize(owner, assetID).
static EntityHandle EntityBuilder::
Load a single-entity prefab from a file path and spawn it.
| Returns | Invalid handle if the file is a scene or construct prefab. |
|---|
static JsonValue EntityBuilder::
Serialize a single entity at a given slot within an archetype chunk.
| Returns | JSON object: { "type": "...", "components": { ... } } |
|---|
static JsonValue EntityBuilder::
Serialize all entities in the registry into a scene JSON document.
| Returns | JSON: { "name": "...", "entities": [ ... ], "defaultState": "...", "defaultMode": "..." } |
|---|
static bool EntityBuilder::
Save a scene to disk.
| Returns | true on success. |
|---|