Skip to content

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.

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

world.bindResource('serializer', () => new SceneSerializer(world), { rebind: true });
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.

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.