@web-engine-dev/scene

ECS-native scene serialization for Web Engine.

Features

• Scene Serialization: Save/load ECS worlds to JSON
• Persistent IDs: Stable entity identity across saves
• SceneState Resource: Consolidated active-scene metadata, persistent ID index, and entity names
• Editor Support: Optional editor metadata blob
• Clean API: Function-first design (loadScene, saveScene, unloadScene)

Installation

npm install @web-engine-dev/scene
# or
pnpm add @web-engine-dev/scene

Quick Start

import { loadScene, saveScene, unloadScene, type SceneData } from '@web-engine-dev/scene';
import { World } from '@web-engine-dev/ecs';

const world = new World();

// Save world to JSON
const sceneData: SceneData = saveScene(world, { name: 'Level 1' });

// Load scene into a world
loadScene(world, sceneData);

// Unload scene entities
unloadScene(world, sceneData.name);

Scene Data Format

{
  "version": 1,
  "name": "Level 1",
  "entities": [
    {
      "stableId": "1e2c2c4c-7f7a-4a1f-9ed3-6b5c4d52b4a1",
      "name": "Player",
      "parent": "ce9d7e1e-4dfb-49d2-9e3e-8f5d7f4f2b10",
      "components": {
        "Transform3D": { "x": 0, "y": 0, "z": 0 },
        "Sprite": { "texture": "player.png" }
      },
      "active": true
    }
  ],
  "editorMetadata": {
    "editorCamera": { "x": 0, "y": 3, "z": 8 },
    "selectedEntities": ["1e2c2c4c-7f7a-4a1f-9ed3-6b5c4d52b4a1"]
  }
}

Core API

import {
  loadScene,
  saveScene,
  unloadScene,
  findEntityByPersistentId,
  assignPersistentId,
  getPersistentId,
  getEntityName,
  setEntityName,
  clearEntityName,
  getSceneState,
  createSceneState,
  SceneEntity,
  PersistentId,
  Active,
  Volatile,
  SceneState,
} from '@web-engine-dev/scene';

Notes

• loadScene automatically tags entities with SceneEntity and assigns PersistentId.
• saveScene serializes all components on SceneEntity except internal tags.
• Scene-level runtime data lives in the SceneState resource.
• Component serialization uses ComponentRegistry.global mappers/serializers.