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()
Section titled “snapshot()”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.
deserialize(data)
Section titled “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:
- Create all entities first so entity reference UIDs can be resolved
- Apply component data with field deserialization
apply(data, managedEntities?)
Section titled “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 despawnserializer.apply(data);
// Scoped authority — only managed entities can be despawnedserializer.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?)
Section titled “load(data, options?)”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 restartawait serializer.load(data);
// Skip lifecycle restart (for editor use)await serializer.load(data, { restartLifecycle: false });createBuilder()
Section titled “createBuilder()”Returns a DynamicSceneBuilder for filtered extraction.
const builder = serializer.createBuilder();