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.
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)
Section titled “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
Section titled “SceneData format”interface SceneData { version: 2; entities: SerializedEntity[]; 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.
Scene and prefab files in a game
Section titled “Scene and prefab files in a game”A game loads the files the editor writes with SceneLoader and PrefabFiles. The game’s own plugin binds them, as a new Project’s src/core/game-plugin.ts does, and the game loads its scene files as Scenes, as its src/core/game.ts does:
world.bindResource('sceneLoader', new SceneLoader(world));world.bindResource('prefabFiles', new PrefabFiles(world));
// Once the world is mounted: the shared scene stays while `switch` changes the level.const scenes = world.get('scenes');await scenes.load('/assets/scenes/shared.scene.json', { persistent: true });await scenes.switch('/assets/scenes/level-1.scene.json');
// In a system: undefined until the file is read, which the first ask starts.const pipe = resources.get('prefabFiles').get('/assets/prefabs/pipe.prefab.json');if (pipe) commands.spawn(pipe);sceneLoader.load(url) makes no Scene of the file: its entities go to the active Scene, as any spawn does, or to none when no Scene is loaded, and those a switch never unloads. A game’s levels are loaded with scenes.load() and scenes.switch() (Scenes).
A prefab file that cannot be read is reported once with console.error, and get() stays undefined for it. The plugin that binds them also declares both names on IocRegistry.
Topics
Section titled “Topics”- Scene Serializer —
snapshot(),deserialize(),apply(), andload() - Dynamic Scene Builder — Filtered scene extraction with allowlists and denylists
- State Patching — Authoritative state sync, field serializers, and
apply()vsload()