Skip to content

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

Returns a full world snapshot: every entity of the world.

const data: SceneData = serializer.snapshot();

One Scene’s file is snapshotScene(scene): the entities it owns.

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

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.

Full state replacement: stops the lifecycle, wipes every entity, deserializes, commits, then optionally restarts. Every Scene goes with it: after load() the world has no Scene (scenes.all is empty), and the loaded entities belong to none. A game changes level with scenes.switch() (Scenes), not with load().

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

Returns a DynamicSceneBuilder for filtered extraction.

const builder = serializer.createBuilder();