Serialization

The @shell/serialization package provides scene serialization, deserialization, and state patching for the ECS world. It depends on @shell/ecs and is designed for save/load workflows, editor state, and network replication.

Setup

import { World } from '@shell/ecs';
import { SceneSerializer } from '@shell/serialization';

const world = new World();
await world.mount();

const serializer = new SceneSerializer(world);
const data = serializer.snapshot();

The SceneSerializer takes a World directly. No plugin or IoC registration is needed.

IoC binding (optional)

If you need the serializer available via world.get('serializer'), bind it manually:

world.bindResource('serializer', () => new SceneSerializer(world), { rebind: true });

SceneData format

interface SceneData {
  version: 2;
  entities: SerializedEntity[];
  scenes?: Record<string, SceneData>; // nested child scene data
  resources?: Record<string, unknown>;
  metadata?: Record<string, unknown>;
}

interface SerializedEntity {
  uid: string;
  components: Record<string, Record<string, unknown>>;
}

Only components marked .serializable() participate in serialization.

Topics

• Scene Serializer — snapshot(), deserialize(), apply(), and load()
• Dynamic Scene Builder — Filtered scene extraction with allowlists and denylists
• State Patching — Authoritative state sync, field serializers, and apply() vs load()