Scene Serializer

SceneSerializer is the core serialization service for the ECS world. It provides full-world snapshots, additive deserialization, authoritative state patching, and full state replacement.

Source: packages/serialization/src/serializer.ts

snapshot()

Returns a full world snapshot including child scenes.

const data: SceneData = serializer.snapshot();

snapshot() automatically includes data from all registered child scenes under the scenes key. Scene inclusion is skipped when called from a scene’s own serializer to avoid infinite recursion.

deserialize(data)

Additively applies scene data to the world. Creates missing entities and updates existing ones by UID. Does not remove entities or components absent from the data.

const entities = serializer.deserialize(data);

Uses a two-pass approach:

1. Create all entities first so entity reference UIDs can be resolved
2. Apply component data with field deserialization

apply(data, managedEntities?)

Authoritative state patch: treats the incoming data as the desired world state.

• Entities in data but not in world → spawned
• Entities in both → component data updated; stale serializable components removed
• Entities in world but not in data → despawned

// Full authority — all entities in the world are candidates for despawn
serializer.apply(data);

// Scoped authority — only managed entities can be despawned
serializer.apply(data, replicatedEntities);

The managedEntities parameter restricts which existing entities are candidates for despawning. Useful for network replication where only server-owned entities should be touched.

load(data, options?)

Full state replacement: stops the lifecycle, wipes all entities (root + scenes), deserializes, commits, then optionally restarts.

// Full restore with lifecycle restart
await serializer.load(data);

// Skip lifecycle restart (for editor use)
await serializer.load(data, { restartLifecycle: false });

createBuilder()

Returns a DynamicSceneBuilder for filtered extraction.

const builder = serializer.createBuilder();

Scene-aware serialization

snapshot(), deserialize(), apply(), and load() all work recursively with child scenes. snapshot() iterates all registered scenes and includes their data. deserialize() and apply() delegate to each scene’s own SceneSerializer instance. No IoC registration is needed on child worlds.