@unboxy/phaser-sdk 0.2.16 → 0.2.17

package/SDK-GUIDE.md

@@ -544,6 +544,88 @@ Don't blindly apply interpolation to everything. It's wrong for a chess piece an
 - Unsubscribe on scene shutdown. `onStateChange`, `on`, `onLeave`, `onError` all return an unsubscribe function — call them from `scene.events.once('shutdown', ...)`.
 - One Colyseus client is kept internally; repeated `joinOrCreate` calls reuse it and mint fresh tokens each connection.
 
+## Scene-as-data (visual editor foundation, since 0.2.17)
+
+Games that ship with `public/scenes/manifest.json` load layout from JSON instead of hardcoding `this.add.sprite(x, y, ...)` in scene classes. This split is what lets the visual editor edit a game without touching code.
+
+**File layout:**
+```
+src/scenes/
+  BootScene.ts            — preloads manifest, draws loading bar, starts GameScene
+  GameScene.ts            — generic loader: await loadWorldScene(this, sceneId)
+public/scenes/
+  manifest.json           — scenes list + asset table + initial scene id
+  world/<scene>.json      — one world scene per file (entities, camera, world dims)
+```
+
+**Manifest shape:**
+```json
+{
+  "schemaVersion": 1,
+  "id": "my-game", "title": "My Game", "version": "1.0.0",
+  "initialScene": "main",
+  "scenes":  [{ "id": "main", "type": "world", "file": "world/main.json", "hud": null }],
+  "huds":    [],
+  "assets":  [
+    { "id": "knight", "textureKey": "knight", "path": "uploaded/knight.png", "kind": "image" },
+    { "id": "tiles",  "textureKey": "tiles",  "path": "uploaded/tiles.png",
+      "kind": "spritesheet",
+      "spriteSheetConfig": { "frameWidth": 16, "frameHeight": 16 } }
+  ]
+}
+```
+
+The `assets[]` table is the single source of truth for asset loading in scene-as-data games. Replaces hand-rolled `BootScene.preload()` lines: `loadWorldScene` queues the right `this.load.*` call based on each asset's `kind` and config (lazy — only assets the active scene uses).
+
+**Entity shape (world scenes):**
+```json
+{
+  "id": "player",
+  "kind": "sprite",
+  "role": "player",
+  "transform": { "x": 200, "y": 400, "rotation": 0, "scaleX": 1, "scaleY": 1 },
+  "visual": { "kind": "sprite", "assetId": "knight" },
+  "properties": { "maxHp": 3, "speed": 200 }
+}
+```
+
+`kind` is the entity-kind discriminator (`sprite` / `primitive` / `group` / `code-rendered` / `tilemap` / `trigger` — last three not in v1). `visual.kind` is the visual variant (`sprite` / `rect` / `circle` / `code-rendered`). They are separate fields with separate enums.
+
+**API:**
+```ts
+import { preloadManifest, getManifest, loadWorldScene, getEntityRegistry } from '@unboxy/phaser-sdk';
+
+class BootScene extends Phaser.Scene {
+  preload() { preloadManifest(this); /* + draw loading bar */ }
+  create() {
+    const manifest = getManifest(this);
+    this.scene.start('GameScene', { sceneId: manifest.initialScene });
+  }
+}
+
+class GameScene extends Phaser.Scene {
+  private sceneId!: string;
+  init(data: { sceneId: string }) { this.sceneId = data.sceneId; }
+  async create() {
+    await loadWorldScene(this, this.sceneId);  // spawns entities, applies camera
+    const registry = getEntityRegistry(this)!;
+    const player = registry.byRole('player')[0] as Phaser.GameObjects.Sprite;
+    // ...wire physics + input on `player`...
+  }
+}
+```
+
+**Behavior conventions:**
+- Layout (positions, asset references, world dims, camera bounds) lives in scene JSON.
+- Behavior (physics setup, input handlers, update loop, tweens) lives in `GameScene.ts`.
+- Look entities up by `role` (`registry.byRole('player')`) — portable across scenes. By id (`registry.byId('boss-1')`) when you need a specific one.
+- Don't hand-write `this.load.image(...)` lines for game assets — declare them in `manifest.assets[]`.
+- Don't call `this.add.sprite(...)` for game entities in code — declare them in scene JSON.
+
+The `scene-data-architecture` agent skill has the full guidance. The `scene-data-migration` skill walks an existing scene-as-code game through the conversion.
+
+**Edit mode (host-driven):** when the host (home-ui) sends `{ type: 'unboxy:setEditMode', enabled: true }` via `postMessage`, the SDK pauses every active non-Boot Phaser scene — entities stay rendered but `update`/physics/tweens stop. Sending `enabled: false` resumes. Used by the visual editor's read-only viewer in slice 1.
+
 ## Anti-patterns (don't do these)
 
 - Do **not** call `Unboxy.init()` inside a scene. Initialize at module load in `main.ts` and export the promise.
@@ -556,6 +638,7 @@ Don't blindly apply interpolation to everything. It's wrong for a chess piece an
 
 ## Changelog
 
+- **0.2.17** — added scene-as-data foundation (visual editor slice 1). New exports: `loadWorldScene`, `preloadManifest`, `getManifest`, `preloadSceneAssets`, `spawnEntity`, `EntityRegistry`, `attachEntityRegistry`, `getEntityRegistry`, `setupEditorModeListener`, `isEditMode`, `parseColor`, `SCHEMA_VERSION`, plus all schema types (`Manifest`, `WorldScene`, `WorldEntity`, `Transform`, `AssetRecord`, etc.). New games that ship with `public/scenes/manifest.json` load entities + camera config from JSON; `GameScene.ts` becomes a generic loader that calls `await loadWorldScene(this, sceneId)`. `createUnboxyGame` now also wires `setupEditorModeListener` so the host (home-ui) can pause active scenes via `postMessage({ type: 'unboxy:setEditMode', enabled: boolean })`. Purely additive — existing scene-as-code games are unaffected. Migration to scene-as-data is opt-in via the `scene-data-migration` agent skill.
 - **0.2.16** — added orientation presets. `createUnboxyGame` now accepts an `orientation: 'portrait' | 'landscape'` option as an alternative to explicit `width`/`height` (TS union — pass one or the other). New exports: `Orientation` type and `ORIENTATION_DIMENSIONS` map (`landscape: 1280×720`, `portrait: 720×1280`). Lets games declare orientation once and have a single source of truth for canvas dimensions.
 - **0.2.15** — fix: `ChatFacade.subscribeToPlayers` early-returned when `state.players` was `undefined` at construction time, which it always is on a fresh `joinOrCreate` (Colyseus delivers initial state as a separate message a few ms later). The early return meant `onStateChange` never subscribed and `system.joined` / `system.left` stayed silent in production despite the 0.2.14 callback-API fix. Now: always subscribe; treat the first state change as initial hydration (silent), subsequent changes do real diff. Three regression tests cover the deferred-hydration flow.
 - **0.2.14** — fix: `ChatFacade` `system.joined` / `system.left` events were silently no-op'ing in production. The lifecycle subscription used `state.players.onAdd` / `.onRemove` instance methods that Colyseus 0.16 removed in favour of `getStateCallbacks(room)`; the runtime check `typeof players.onAdd === 'function'` evaluated false, so neither system message fired. Now uses `room.onStateChange` + a known-names diff — robust to future Colyseus API changes. Tests updated to match. Patch-only; no API change for game code.

package/dist/core/UnboxyGame.js

@@ -1,6 +1,7 @@
 import Phaser from 'phaser';
 import { setupScreenshotListener } from '../screenshot/ScreenshotManager.js';
 import { setupRecordingListener } from '../recording/RecordingManager.js';
+import { setupEditorModeListener } from '../scene/EditorMode.js';
 import { ORIENTATION_DIMENSIONS } from '../orientation.js';
 /**
  * Create an Unboxy-enhanced Phaser game instance.
@@ -34,5 +35,6 @@ export function createUnboxyGame(options) {
     // Built-in integrations
     setupScreenshotListener(game);
     setupRecordingListener(game);
+    setupEditorModeListener(game);
     return game;
 }

package/dist/index.d.ts

@@ -16,4 +16,12 @@ export type { ChatMessage, ChatMessageKind } from './realtime/UnboxyRoom.js';
 export { RpcError } from './core/Transport.js';
 export type { Transport, TransportKind } from './core/Transport.js';
 export type { UnboxyUser } from './protocol.js';
+export { loadWorldScene, preloadManifest, preloadSceneAssets, getManifest, SCENES_BASE, MANIFEST_PATH, } from './scene/SceneLoader.js';
+export type { LoadWorldSceneOptions } from './scene/SceneLoader.js';
+export { spawnEntity, parseColor } from './scene/spawnEntity.js';
+export type { SpawnContext, AssetResolver, RenderScriptResolver, } from './scene/spawnEntity.js';
+export { EntityRegistry, attachEntityRegistry, getEntityRegistry, } from './scene/EntityRegistry.js';
+export { setupEditorModeListener, isEditMode } from './scene/EditorMode.js';
+export { SCHEMA_VERSION, } from './scene/types.js';
+export type { Manifest, SceneRef, HudRef, AssetRecord, AssetKind, SceneType, SceneFile, WorldScene, HudScene, WorldSceneConfig, CameraConfig, WorldEntity, WorldEntityKind, NonGroupWorldEntity, SpriteEntity, PrimitiveEntity, CodeRenderedEntity, GroupEntity, TilemapEntity, TriggerEntity, WorldVisual, SpriteVisual, PrimitiveVisual, PrimitiveRectVisual, PrimitiveCircleVisual, CodeRenderedVisual, Transform, Anchor, AnchorSide, } from './scene/types.js';
 export { PROTOCOL_VERSION, type HelloMessage, type InitMessage, type RpcRequestMessage, type RpcResultOk, type RpcResultError, type HostToSdkMessage, type SdkToHostMessage, type RpcErrorPayload, type RpcMethod, type SavesGetParams, type SavesGetResult, type SavesSetParams, type SavesSetResult, type SavesDeleteParams, type SavesDeleteResult, type SavesListResult, type GameDataGetParams, type GameDataGetResult, type GameDataSetParams, type GameDataSetResult, type GameDataDeleteParams, type GameDataDeleteResult, type GameDataListResult, type RealtimeGetTokenParams, type RealtimeGetTokenResult, } from './protocol.js';

package/dist/index.js

@@ -13,4 +13,10 @@ export { GameDataModule } from './gamedata/GameDataModule.js';
 export { RealtimeModule } from './realtime/RealtimeModule.js';
 export { UnboxyRoom, PlayerDataFacade, RoomDataFacade, ChatFacade, MAX_CHAT_TEXT_LEN, } from './realtime/UnboxyRoom.js';
 export { RpcError } from './core/Transport.js';
+// Scene-as-data (visual editor foundation, slice 1)
+export { loadWorldScene, preloadManifest, preloadSceneAssets, getManifest, SCENES_BASE, MANIFEST_PATH, } from './scene/SceneLoader.js';
+export { spawnEntity, parseColor } from './scene/spawnEntity.js';
+export { EntityRegistry, attachEntityRegistry, getEntityRegistry, } from './scene/EntityRegistry.js';
+export { setupEditorModeListener, isEditMode } from './scene/EditorMode.js';
+export { SCHEMA_VERSION, } from './scene/types.js';
 export { PROTOCOL_VERSION, } from './protocol.js';

package/dist/scene/EditorMode.d.ts

@@ -0,0 +1,3 @@
+import Phaser from 'phaser';
+export declare function setupEditorModeListener(game: Phaser.Game): void;
+export declare function isEditMode(game: Phaser.Game): boolean;

package/dist/scene/EditorMode.js

@@ -0,0 +1,57 @@
+/**
+ * Edit mode = pause every active world/HUD scene so the canvas freezes
+ * but stays rendered. The visual editor uses this for slice 1's
+ * read-only viewer; later slices add overlay/gizmo layers on top.
+ *
+ * Wire shape (host → SDK only — no reply expected):
+ *   { type: 'unboxy:setEditMode', enabled: boolean }
+ *
+ * Boot scenes are skipped — pausing them stalls the loader.
+ */
+const BOOT_SCENE_KEYS = new Set(['BootScene', 'Boot']);
+const EDIT_MODE_FLAG = '__unboxyEditMode';
+export function setupEditorModeListener(game) {
+    window.addEventListener('message', (event) => {
+        const data = event.data;
+        if (!data || typeof data !== 'object')
+            return;
+        if (data.type !== 'unboxy:setEditMode')
+            return;
+        const enabled = !!data.enabled;
+        if (enabled)
+            enterEditMode(game);
+        else
+            exitEditMode(game);
+    });
+}
+export function isEditMode(game) {
+    return !!game[EDIT_MODE_FLAG];
+}
+function enterEditMode(game) {
+    const flagged = game;
+    if (flagged[EDIT_MODE_FLAG])
+        return;
+    flagged[EDIT_MODE_FLAG] = true;
+    for (const scene of game.scene.getScenes(true)) {
+        const key = scene.scene.key;
+        if (BOOT_SCENE_KEYS.has(key))
+            continue;
+        // Phaser's pause() stops update + physics + tweens but leaves the
+        // scene rendered — exactly what the read-only viewer wants.
+        if (scene.scene.isActive())
+            scene.scene.pause();
+    }
+}
+function exitEditMode(game) {
+    const flagged = game;
+    if (!flagged[EDIT_MODE_FLAG])
+        return;
+    flagged[EDIT_MODE_FLAG] = false;
+    for (const scene of game.scene.getScenes(false)) {
+        const key = scene.scene.key;
+        if (BOOT_SCENE_KEYS.has(key))
+            continue;
+        if (scene.scene.isPaused())
+            scene.scene.resume();
+    }
+}

package/dist/scene/EntityRegistry.d.ts

@@ -0,0 +1,20 @@
+import Phaser from 'phaser';
+/**
+ * Per-scene lookup of spawned entities. Behavior code uses this to find
+ * the player, enemies, doors, etc. by id or role without coupling to
+ * scene-file structure.
+ *
+ * Created by `loadWorldScene` and stashed on `scene.data` under the key
+ * `'unboxyEntityRegistry'`. Access via `getEntityRegistry(scene)`.
+ */
+export declare class EntityRegistry {
+    private byIdMap;
+    private byRoleMap;
+    register(id: string, role: string | undefined, go: Phaser.GameObjects.GameObject): void;
+    byId(id: string): Phaser.GameObjects.GameObject | undefined;
+    byRole(role: string): Phaser.GameObjects.GameObject[];
+    all(): Phaser.GameObjects.GameObject[];
+    clear(): void;
+}
+export declare function attachEntityRegistry(scene: Phaser.Scene): EntityRegistry;
+export declare function getEntityRegistry(scene: Phaser.Scene): EntityRegistry | undefined;

package/dist/scene/EntityRegistry.js

@@ -0,0 +1,50 @@
+/**
+ * Per-scene lookup of spawned entities. Behavior code uses this to find
+ * the player, enemies, doors, etc. by id or role without coupling to
+ * scene-file structure.
+ *
+ * Created by `loadWorldScene` and stashed on `scene.data` under the key
+ * `'unboxyEntityRegistry'`. Access via `getEntityRegistry(scene)`.
+ */
+export class EntityRegistry {
+    constructor() {
+        this.byIdMap = new Map();
+        this.byRoleMap = new Map();
+    }
+    register(id, role, go) {
+        this.byIdMap.set(id, go);
+        if (role) {
+            const list = this.byRoleMap.get(role) ?? [];
+            list.push(go);
+            this.byRoleMap.set(role, list);
+        }
+    }
+    byId(id) {
+        return this.byIdMap.get(id);
+    }
+    byRole(role) {
+        return this.byRoleMap.get(role) ?? [];
+    }
+    all() {
+        return Array.from(this.byIdMap.values());
+    }
+    clear() {
+        this.byIdMap.clear();
+        this.byRoleMap.clear();
+    }
+}
+const REGISTRY_KEY = 'unboxyEntityRegistry';
+export function attachEntityRegistry(scene) {
+    const existing = scene.data?.get(REGISTRY_KEY);
+    if (existing) {
+        existing.clear();
+        return existing;
+    }
+    const registry = new EntityRegistry();
+    // Phaser auto-creates DataManager on first .data access if absent.
+    scene.data.set(REGISTRY_KEY, registry);
+    return registry;
+}
+export function getEntityRegistry(scene) {
+    return scene.data?.get(REGISTRY_KEY);
+}

package/dist/scene/SceneLoader.d.ts

@@ -0,0 +1,59 @@
+import Phaser from 'phaser';
+import { Manifest, SceneFile, WorldScene } from './types.js';
+import { RenderScriptResolver } from './spawnEntity.js';
+import { EntityRegistry } from './EntityRegistry.js';
+/**
+ * Where scene files live in the workspace and at runtime. The Vite build
+ * copies `public/` to the served root, so paths are origin-relative
+ * (`scenes/manifest.json`). No leading slash — the iframe is sometimes
+ * served under a sub-path (`/preview/:gameId/`).
+ */
+export declare const SCENES_BASE = "scenes/";
+export declare const MANIFEST_PATH = "scenes/manifest.json";
+/**
+ * Fetches the manifest via Phaser's loader. Must be called from a Phaser
+ * scene's `preload()` since it queues a load request. Subsequent calls
+ * (e.g. on scene transitions) hit the Phaser JSON cache.
+ *
+ * Resolves once Phaser fires `complete` for the load batch — callers
+ * typically await this in `create()` after `this.load.start()` is done.
+ */
+export declare function preloadManifest(scene: Phaser.Scene): void;
+/**
+ * Read the manifest from Phaser's JSON cache. Throws if `preloadManifest`
+ * hasn't completed first.
+ */
+export declare function getManifest(scene: Phaser.Scene): Manifest;
+/**
+ * Walk a scene file's entities and queue Phaser loads for any assets that
+ * aren't already in the texture cache. Caller is responsible for awaiting
+ * the loader (`scene.load.once('complete', ...)` or do it in `preload()`).
+ *
+ * Idempotent across scenes — once an asset is loaded, switching to another
+ * scene that uses it is free.
+ */
+export declare function preloadSceneAssets(scene: Phaser.Scene, sceneFile: SceneFile, manifest: Manifest): void;
+export interface LoadWorldSceneOptions {
+    /**
+     * Optional render-script resolver for `code-rendered` entities. When
+     * absent, the loader throws on code-rendered entities (slice 1).
+     */
+    resolveRenderScript?: RenderScriptResolver;
+}
+/**
+ * One-shot async loader: fetch scene JSON (if not already cached), lazy
+ * preload its assets, spawn entities, configure camera, and return the
+ * EntityRegistry. Idempotent re-loads of the same scene id reuse the
+ * Phaser JSON cache.
+ *
+ * Pattern (in `GameScene.create()`):
+ *
+ * ```ts
+ * const result = await loadWorldScene(this, sceneId);
+ * // entities live; behavior code can use result.registry.byRole('player')
+ * ```
+ */
+export declare function loadWorldScene(scene: Phaser.Scene, sceneId: string, options?: LoadWorldSceneOptions): Promise<{
+    sceneFile: WorldScene;
+    registry: EntityRegistry;
+}>;

package/dist/scene/SceneLoader.js

@@ -0,0 +1,259 @@
+import Phaser from 'phaser';
+import { SCHEMA_VERSION, } from './types.js';
+import { spawnEntity } from './spawnEntity.js';
+import { attachEntityRegistry } from './EntityRegistry.js';
+/**
+ * Where scene files live in the workspace and at runtime. The Vite build
+ * copies `public/` to the served root, so paths are origin-relative
+ * (`scenes/manifest.json`). No leading slash — the iframe is sometimes
+ * served under a sub-path (`/preview/:gameId/`).
+ */
+export const SCENES_BASE = 'scenes/';
+export const MANIFEST_PATH = `${SCENES_BASE}manifest.json`;
+const MANIFEST_CACHE_KEY = '__unboxyManifestState';
+/**
+ * Fetches the manifest via Phaser's loader. Must be called from a Phaser
+ * scene's `preload()` since it queues a load request. Subsequent calls
+ * (e.g. on scene transitions) hit the Phaser JSON cache.
+ *
+ * Resolves once Phaser fires `complete` for the load batch — callers
+ * typically await this in `create()` after `this.load.start()` is done.
+ */
+export function preloadManifest(scene) {
+    if (!scene.cache.json.exists('unboxy:manifest')) {
+        scene.load.json('unboxy:manifest', MANIFEST_PATH);
+    }
+}
+/**
+ * Read the manifest from Phaser's JSON cache. Throws if `preloadManifest`
+ * hasn't completed first.
+ */
+export function getManifest(scene) {
+    const raw = scene.cache.json.get('unboxy:manifest');
+    if (!raw) {
+        throw new Error("[unboxy/scene] manifest not loaded — call preloadManifest(scene) in BootScene.preload() and wait for the loader's 'complete' event");
+    }
+    const manifest = raw;
+    validateManifest(manifest);
+    return manifest;
+}
+function validateManifest(m) {
+    if (m.schemaVersion !== SCHEMA_VERSION) {
+        throw new Error(`[unboxy/scene] manifest schemaVersion ${m.schemaVersion} but SDK expects ${SCHEMA_VERSION}`);
+    }
+    if (!m.scenes?.length) {
+        throw new Error('[unboxy/scene] manifest has no scenes');
+    }
+    if (!m.scenes.find((s) => s.id === m.initialScene)) {
+        throw new Error(`[unboxy/scene] manifest.initialScene '${m.initialScene}' is not in scenes[]`);
+    }
+}
+function getOrInitState(scene, manifest) {
+    const game = scene.game;
+    const existing = game[MANIFEST_CACHE_KEY];
+    if (existing && existing.manifest === manifest)
+        return existing;
+    const assetsById = new Map();
+    for (const a of manifest.assets ?? [])
+        assetsById.set(a.id, a);
+    const state = {
+        manifest,
+        assetsById,
+        requestedAssetIds: new Set(),
+    };
+    game[MANIFEST_CACHE_KEY] = state;
+    return state;
+}
+// --- Lazy asset preload ----------------------------------------------------
+/**
+ * Walk a scene file's entities and queue Phaser loads for any assets that
+ * aren't already in the texture cache. Caller is responsible for awaiting
+ * the loader (`scene.load.once('complete', ...)` or do it in `preload()`).
+ *
+ * Idempotent across scenes — once an asset is loaded, switching to another
+ * scene that uses it is free.
+ */
+export function preloadSceneAssets(scene, sceneFile, manifest) {
+    if (sceneFile.type !== 'world')
+        return; // HUD slice will add its own walker
+    const state = getOrInitState(scene, manifest);
+    const ids = collectAssetIds(sceneFile.entities);
+    for (const id of ids) {
+        if (state.requestedAssetIds.has(id))
+            continue;
+        const asset = state.assetsById.get(id);
+        if (!asset) {
+            throw new Error(`[unboxy/scene] scene '${sceneFile.id}' references assetId '${id}' but the manifest has no such asset`);
+        }
+        queueAssetLoad(scene, asset);
+        state.requestedAssetIds.add(id);
+    }
+}
+function collectAssetIds(entities) {
+    const ids = new Set();
+    function walk(e) {
+        if (e.kind === 'sprite') {
+            ids.add(e.visual.assetId);
+        }
+        else if (e.kind === 'group') {
+            for (const child of e.children)
+                walk(child);
+        }
+        // primitive / code-rendered / tilemap / trigger don't reference assets
+        // (yet — tilemap/trigger are deferred slices).
+    }
+    for (const e of entities)
+        walk(e);
+    return Array.from(ids);
+}
+function queueAssetLoad(scene, asset) {
+    if (scene.textures.exists(asset.textureKey))
+        return;
+    switch (asset.kind) {
+        case 'image':
+            scene.load.image(asset.textureKey, asset.path);
+            return;
+        case 'spritesheet':
+            if (!asset.spriteSheetConfig) {
+                throw new Error(`[unboxy/scene] asset '${asset.id}' kind=spritesheet missing spriteSheetConfig`);
+            }
+            scene.load.spritesheet(asset.textureKey, asset.path, asset.spriteSheetConfig);
+            return;
+        case 'atlas':
+            if (!asset.atlasPath || !asset.atlasFormat) {
+                throw new Error(`[unboxy/scene] asset '${asset.id}' kind=atlas missing atlasPath/atlasFormat`);
+            }
+            if (asset.atlasFormat === 'xml') {
+                scene.load.atlasXML(asset.textureKey, asset.path, asset.atlasPath);
+            }
+            else {
+                scene.load.atlas(asset.textureKey, asset.path, asset.atlasPath);
+            }
+            return;
+        case 'audio':
+            scene.load.audio(asset.textureKey, asset.path);
+            return;
+        case 'json':
+            scene.load.json(asset.textureKey, asset.path);
+            return;
+        default: {
+            const exhaustive = asset.kind;
+            throw new Error(`[unboxy/scene] unknown asset kind: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+/**
+ * One-shot async loader: fetch scene JSON (if not already cached), lazy
+ * preload its assets, spawn entities, configure camera, and return the
+ * EntityRegistry. Idempotent re-loads of the same scene id reuse the
+ * Phaser JSON cache.
+ *
+ * Pattern (in `GameScene.create()`):
+ *
+ * ```ts
+ * const result = await loadWorldScene(this, sceneId);
+ * // entities live; behavior code can use result.registry.byRole('player')
+ * ```
+ */
+export async function loadWorldScene(scene, sceneId, options = {}) {
+    const manifest = getManifest(scene);
+    const ref = manifest.scenes.find((s) => s.id === sceneId);
+    if (!ref)
+        throw new Error(`[unboxy/scene] manifest has no scene with id '${sceneId}'`);
+    if (ref.type !== 'world') {
+        throw new Error(`[unboxy/scene] scene '${sceneId}' is type=${ref.type}; loadWorldScene expects type=world`);
+    }
+    const sceneFile = (await loadSceneJson(scene, ref));
+    if (sceneFile.schemaVersion !== SCHEMA_VERSION) {
+        throw new Error(`[unboxy/scene] scene '${sceneId}' schemaVersion ${sceneFile.schemaVersion} but SDK expects ${SCHEMA_VERSION}`);
+    }
+    if (sceneFile.type !== 'world') {
+        throw new Error(`[unboxy/scene] scene '${sceneId}' has type=${sceneFile.type} in file body`);
+    }
+    // Lazy preload of any new assets this scene needs, then await loader.
+    preloadSceneAssets(scene, sceneFile, manifest);
+    await runLoader(scene);
+    // Spawn entities.
+    const registry = attachEntityRegistry(scene);
+    const ctx = {
+        scene,
+        registry,
+        resolveAsset: (id) => resolveAsset(manifest, id),
+        resolveRenderScript: options.resolveRenderScript,
+    };
+    for (const entity of sceneFile.entities)
+        spawnEntity(ctx, entity);
+    // Configure camera.
+    applyCamera(scene, sceneFile, registry);
+    return { sceneFile, registry };
+}
+async function loadSceneJson(scene, ref) {
+    const cacheKey = `unboxy:scene:${ref.id}`;
+    if (scene.cache.json.exists(cacheKey)) {
+        return scene.cache.json.get(cacheKey);
+    }
+    scene.load.json(cacheKey, `${SCENES_BASE}${ref.file}`);
+    await runLoader(scene);
+    return scene.cache.json.get(cacheKey);
+}
+/**
+ * Phaser's `load` queue is fire-and-forget; this wraps it in a promise.
+ * If the loader is already idle and has nothing queued, resolves
+ * immediately on next tick.
+ */
+function runLoader(scene) {
+    return new Promise((resolve, reject) => {
+        if (!scene.load.isLoading() && scene.load.totalToLoad === 0) {
+            // Nothing to do — but `totalToLoad` resets to 0 on each `start()`
+            // so check whether anything was queued since last start.
+            if (scene.load.list.size === 0) {
+                queueMicrotask(resolve);
+                return;
+            }
+        }
+        scene.load.once(Phaser.Loader.Events.COMPLETE, () => resolve());
+        scene.load.once(Phaser.Loader.Events.FILE_LOAD_ERROR, (file) => {
+            reject(new Error(`[unboxy/scene] loader failed: ${file.key} (${file.url})`));
+        });
+        scene.load.start();
+    });
+}
+function resolveAsset(manifest, assetId) {
+    const asset = manifest.assets?.find((a) => a.id === assetId);
+    if (!asset) {
+        throw new Error(`[unboxy/scene] manifest has no asset with id '${assetId}'`);
+    }
+    return asset;
+}
+function applyCamera(scene, sceneFile, registry) {
+    const cam = scene.cameras.main;
+    const cfg = sceneFile.camera ?? {};
+    // World bounds — default to scene world dims if not specified.
+    const bounds = cfg.bounds ?? { x: 0, y: 0, width: sceneFile.world.width, height: sceneFile.world.height };
+    cam.setBounds(bounds.x, bounds.y, bounds.width, bounds.height);
+    if (typeof cfg.zoom === 'number')
+        cam.setZoom(cfg.zoom);
+    if (cfg.pixelPerfect)
+        cam.setRoundPixels(true);
+    if (sceneFile.world.background?.color) {
+        cam.setBackgroundColor(sceneFile.world.background.color);
+    }
+    if (cfg.follow) {
+        const target = registry.byId(cfg.follow);
+        if (target) {
+            const lerp = typeof cfg.smoothing === 'number' ? cfg.smoothing : 1;
+            cam.startFollow(target, true, lerp, lerp);
+            if (cfg.deadzone)
+                cam.setDeadzone(cfg.deadzone.x * 2, cfg.deadzone.y * 2);
+            if (typeof cfg.lookahead === 'number') {
+                cam.setFollowOffset(-cfg.lookahead, 0);
+            }
+        }
+        else {
+            // Soft warning — behavior code might create the follow target later.
+            // Surfacing a console.warn keeps the runtime running while flagging
+            // the data inconsistency to whoever is debugging.
+            console.warn(`[unboxy/scene] camera.follow id='${cfg.follow}' has no matching entity in scene '${sceneFile.id}'`);
+        }
+    }
+}

package/dist/scene/spawnEntity.d.ts

@@ -0,0 +1,30 @@
+import Phaser from 'phaser';
+import { AssetRecord, WorldEntity } from './types.js';
+import { EntityRegistry } from './EntityRegistry.js';
+/**
+ * Resolves an asset id to its AssetRecord, throwing a clear error if the
+ * scene file references something the manifest doesn't know about. We
+ * surface this as an error (not a silent miss) because a missing asset
+ * means either the manifest is stale or the scene file was hand-edited
+ * — both worth catching at runtime, not skipping silently.
+ */
+export type AssetResolver = (assetId: string) => AssetRecord;
+/** Optional hook for `code-rendered` visuals. v1 throws if not provided. */
+export type RenderScriptResolver = (scriptPath: string) => ((g: Phaser.GameObjects.Graphics, params: Record<string, unknown>) => void) | undefined;
+export interface SpawnContext {
+    scene: Phaser.Scene;
+    registry: EntityRegistry;
+    resolveAsset: AssetResolver;
+    resolveRenderScript?: RenderScriptResolver;
+}
+/**
+ * Spawn one entity into the scene and register it. Returns the created
+ * GameObject so callers (notably `spawnEntity` itself, recursing on a
+ * group's children) can attach it to a parent container.
+ */
+export declare function spawnEntity(ctx: SpawnContext, entity: WorldEntity): Phaser.GameObjects.GameObject;
+/**
+ * Accepts `'#rrggbb'`, `'rrggbb'`, or `'0xrrggbb'` and returns a number
+ * suitable for Phaser's color APIs.
+ */
+export declare function parseColor(input: string): number;

package/dist/scene/spawnEntity.js

@@ -0,0 +1,136 @@
+/**
+ * Spawn one entity into the scene and register it. Returns the created
+ * GameObject so callers (notably `spawnEntity` itself, recursing on a
+ * group's children) can attach it to a parent container.
+ */
+export function spawnEntity(ctx, entity) {
+    let go;
+    switch (entity.kind) {
+        case 'sprite':
+            go = createSprite(ctx, entity);
+            break;
+        case 'primitive':
+            go = createPrimitive(ctx, entity);
+            break;
+        case 'group':
+            go = createGroup(ctx, entity);
+            break;
+        case 'code-rendered':
+            go = createCodeRendered(ctx, entity);
+            break;
+        case 'tilemap':
+            throw new Error(`[unboxy/scene] tilemap entity ('${entity.id}') not supported in slice 1 — see 06-tilemap.md`);
+        case 'trigger':
+            throw new Error(`[unboxy/scene] trigger entity ('${entity.id}') not supported in slice 1 — see 03-world-editor.md`);
+        default: {
+            const exhaustive = entity;
+            throw new Error(`[unboxy/scene] unknown entity kind: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+    applyTransform(go, entity.transform);
+    tagGameObject(go, entity);
+    ctx.registry.register(entity.id, entity.role, go);
+    return go;
+}
+function createSprite(ctx, entity) {
+    const v = entity.visual;
+    const asset = ctx.resolveAsset(v.assetId);
+    // Phaser's add.sprite handles both plain images and atlas/spritesheet
+    // textures uniformly when given (key, frame). For plain images, frame
+    // is undefined and Phaser uses the default frame.
+    const sprite = ctx.scene.add.sprite(0, 0, asset.textureKey, v.frame);
+    if (v.tint)
+        sprite.setTint(parseColor(v.tint));
+    if (typeof v.alpha === 'number')
+        sprite.setAlpha(v.alpha);
+    if (v.flipX)
+        sprite.setFlipX(true);
+    if (v.flipY)
+        sprite.setFlipY(true);
+    return sprite;
+}
+function createPrimitive(ctx, entity) {
+    const v = entity.visual;
+    if (v.kind === 'rect')
+        return createRect(ctx, v);
+    if (v.kind === 'circle')
+        return createCircle(ctx, v);
+    const exhaustive = v;
+    throw new Error(`[unboxy/scene] unknown primitive kind: ${JSON.stringify(exhaustive)}`);
+}
+function createRect(ctx, v) {
+    const fill = v.fillColor ? parseColor(v.fillColor) : 0xffffff;
+    const rect = ctx.scene.add.rectangle(0, 0, v.width, v.height, fill);
+    if (v.strokeColor && v.strokeWidth) {
+        rect.setStrokeStyle(v.strokeWidth, parseColor(v.strokeColor));
+    }
+    if (typeof v.alpha === 'number')
+        rect.setAlpha(v.alpha);
+    return rect;
+}
+function createCircle(ctx, v) {
+    const fill = v.fillColor ? parseColor(v.fillColor) : 0xffffff;
+    const arc = ctx.scene.add.circle(0, 0, v.radius, fill);
+    if (v.strokeColor && v.strokeWidth) {
+        arc.setStrokeStyle(v.strokeWidth, parseColor(v.strokeColor));
+    }
+    if (typeof v.alpha === 'number')
+        arc.setAlpha(v.alpha);
+    return arc;
+}
+function createGroup(ctx, entity) {
+    const container = ctx.scene.add.container(0, 0);
+    for (const child of entity.children) {
+        if (child.kind === 'group') {
+            // v1 cap: groups can't nest. Surface a clear error rather than
+            // silently producing a half-attached hierarchy.
+            throw new Error(`[unboxy/scene] group '${entity.id}' has a nested group child '${child.id}' — v1 supports one level of nesting only`);
+        }
+        const childGo = spawnEntity(ctx, child);
+        container.add(childGo);
+    }
+    return container;
+}
+function createCodeRendered(ctx, entity) {
+    const render = ctx.resolveRenderScript?.(entity.visual.script);
+    if (!render) {
+        throw new Error(`[unboxy/scene] code-rendered entity '${entity.id}' references '${entity.visual.script}' but no render-script resolver was provided — render scripts land in a later slice (see 02-render-scripts.md)`);
+    }
+    const g = ctx.scene.add.graphics();
+    render(g, entity.visual.params ?? {});
+    return g;
+}
+function applyTransform(go, t) {
+    // Most game objects implement Transform; Container does too. Cast through
+    // a permissive shape so this works for sprite/rect/circle/container alike.
+    const target = go;
+    target.x = t.x;
+    target.y = t.y;
+    if (typeof t.rotation === 'number')
+        target.rotation = t.rotation;
+    if (typeof t.scaleX === 'number')
+        target.scaleX = t.scaleX;
+    if (typeof t.scaleY === 'number')
+        target.scaleY = t.scaleY;
+    if (typeof t.depth === 'number' && target.setDepth)
+        target.setDepth(t.depth);
+}
+function tagGameObject(go, entity) {
+    go.setData('entityId', entity.id);
+    if (entity.role)
+        go.setData('entityRole', entity.role);
+    if (entity.properties)
+        go.setData('entityProperties', entity.properties);
+}
+/**
+ * Accepts `'#rrggbb'`, `'rrggbb'`, or `'0xrrggbb'` and returns a number
+ * suitable for Phaser's color APIs.
+ */
+export function parseColor(input) {
+    const trimmed = input.trim();
+    if (trimmed.startsWith('#'))
+        return parseInt(trimmed.slice(1), 16);
+    if (trimmed.startsWith('0x'))
+        return parseInt(trimmed.slice(2), 16);
+    return parseInt(trimmed, 16);
+}

package/dist/scene/types.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Scene-as-data types — visual editor foundation (slice 1).
+ *
+ * Spec: unboxy-design/features/visual-editor/01-scene-data-foundation.md
+ *
+ * v1 schema (`schemaVersion: 1`) supports the entity kinds needed for the
+ * read-only scene viewer. HUD entity kinds, tilemap, trigger, and
+ * code-rendered visuals will land in later slices.
+ */
+export declare const SCHEMA_VERSION = 1;
+export type SceneType = 'world' | 'hud';
+export interface SceneRef {
+    id: string;
+    type: SceneType;
+    /** Path under `public/scenes/`, e.g. `"world/level-1-1.json"`. */
+    file: string;
+    /** Optional HUD scene id to overlay (world scenes only). Null = no HUD. */
+    hud?: string | null;
+}
+export interface HudRef {
+    id: string;
+    /** Path under `public/scenes/`, e.g. `"hud/game-hud.json"`. */
+    file: string;
+}
+/**
+ * Per-game asset table. Source of truth for asset id → Phaser textureKey
+ * resolution. The editor and runtime both read from this.
+ */
+export type AssetKind = 'image' | 'spritesheet' | 'atlas' | 'audio' | 'json';
+export interface AssetRecord {
+    /** Stable asset id used in scene files (`visual.assetId`). */
+    id: string;
+    /** Phaser texture / cache key. May equal `id` for simple cases. */
+    textureKey: string;
+    /** Path relative to `public/`. */
+    path: string;
+    kind: AssetKind;
+    /** For `spritesheet`: Phaser SpriteSheetConfig. */
+    spriteSheetConfig?: {
+        frameWidth: number;
+        frameHeight: number;
+        margin?: number;
+        spacing?: number;
+    };
+    /** For `atlas`: companion atlas file path (xml or json). */
+    atlasPath?: string;
+    /** `'xml'` (Starling) or `'json'` (TexturePacker). */
+    atlasFormat?: 'xml' | 'json';
+}
+export interface Manifest {
+    schemaVersion: number;
+    id: string;
+    title: string;
+    version: string;
+    initialScene: string;
+    scenes: SceneRef[];
+    huds: HudRef[];
+    assets: AssetRecord[];
+    globals?: {
+        physics?: {
+            gravity?: {
+                x?: number;
+                y?: number;
+            };
+        };
+        world?: {
+            pixelArt?: boolean;
+        };
+    };
+}
+export interface Transform {
+    x: number;
+    y: number;
+    /** Radians. */
+    rotation?: number;
+    scaleX?: number;
+    scaleY?: number;
+    depth?: number;
+}
+export type AnchorSide = 'top-left' | 'top' | 'top-right' | 'left' | 'center' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right';
+export interface Anchor {
+    side: AnchorSide;
+    offsetX?: number;
+    offsetY?: number;
+}
+export interface SpriteVisual {
+    kind: 'sprite';
+    assetId: string;
+    /** Atlas frame name OR sprite-sheet frame index. */
+    frame?: string | number;
+    tint?: string;
+    alpha?: number;
+    flipX?: boolean;
+    flipY?: boolean;
+}
+export interface PrimitiveRectVisual {
+    kind: 'rect';
+    width: number;
+    height: number;
+    fillColor?: string;
+    strokeColor?: string | null;
+    strokeWidth?: number;
+    alpha?: number;
+}
+export interface PrimitiveCircleVisual {
+    kind: 'circle';
+    radius: number;
+    fillColor?: string;
+    strokeColor?: string | null;
+    strokeWidth?: number;
+    alpha?: number;
+}
+export type PrimitiveVisual = PrimitiveRectVisual | PrimitiveCircleVisual;
+export interface CodeRenderedVisual {
+    kind: 'code-rendered';
+    /** Path to render script, e.g. `"src/visuals/boss-renderer.ts"`. */
+    script: string;
+    params?: Record<string, unknown>;
+}
+export type WorldVisual = SpriteVisual | PrimitiveVisual | CodeRenderedVisual;
+export type WorldEntityKind = 'sprite' | 'primitive' | 'code-rendered' | 'group' | 'tilemap' | 'trigger';
+export interface WorldEntityBase {
+    id: string;
+    /** Optional semantic tag. Behavior code keys off this. */
+    role?: string;
+    /** Free-form per-entity data the agent's behavior code reads. */
+    properties?: Record<string, unknown>;
+    transform: Transform;
+}
+export interface SpriteEntity extends WorldEntityBase {
+    kind: 'sprite';
+    visual: SpriteVisual;
+}
+export interface PrimitiveEntity extends WorldEntityBase {
+    kind: 'primitive';
+    visual: PrimitiveVisual;
+}
+export interface CodeRenderedEntity extends WorldEntityBase {
+    kind: 'code-rendered';
+    visual: CodeRenderedVisual;
+}
+export interface GroupEntity extends WorldEntityBase {
+    kind: 'group';
+    /**
+     * One level of nesting in v1: a child cannot itself be a `group`.
+     * If you need deeper hierarchy, the agent should flatten via the
+     * existing transform and add a role tag for grouping queries.
+     */
+    children: NonGroupWorldEntity[];
+}
+/**
+ * v1 placeholder — schema slot reserved so future slices can layer in
+ * tilemap/trigger without a schemaVersion bump. Loader currently throws
+ * on these kinds so an unmigrated game can't silently render nothing.
+ */
+export interface TilemapEntity extends WorldEntityBase {
+    kind: 'tilemap';
+    /** Opaque tilemap payload — defined in `06-tilemap.md`. */
+    data: unknown;
+}
+export interface TriggerEntity extends WorldEntityBase {
+    kind: 'trigger';
+    /** Opaque trigger payload — defined in `03-world-editor.md`. */
+    data: unknown;
+}
+export type NonGroupWorldEntity = SpriteEntity | PrimitiveEntity | CodeRenderedEntity | TilemapEntity | TriggerEntity;
+export type WorldEntity = NonGroupWorldEntity | GroupEntity;
+export interface CameraConfig {
+    /** Entity id to follow. Null = static camera. */
+    follow?: string | null;
+    smoothing?: number;
+    deadzone?: {
+        x: number;
+        y: number;
+    };
+    lookahead?: number;
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    zoom?: number;
+    pixelPerfect?: boolean;
+    shakeDecay?: number;
+}
+export interface WorldSceneConfig {
+    width: number;
+    height: number;
+    background?: {
+        color?: string;
+    };
+    physics?: {
+        gravity?: {
+            x?: number;
+            y?: number;
+        };
+    };
+}
+export interface WorldScene {
+    schemaVersion: number;
+    id: string;
+    name: string;
+    type: 'world';
+    world: WorldSceneConfig;
+    camera?: CameraConfig;
+    entities: WorldEntity[];
+    metadata?: {
+        tags?: string[];
+        author?: string;
+        createdAt?: string;
+        updatedAt?: string;
+    };
+}
+/**
+ * HUD scene schema slot — v1 reserves the shape for slice 5. The loader
+ * throws if it encounters one in slice 1; the type lives here so the
+ * manifest's `huds[]` list is well-typed.
+ */
+export interface HudScene {
+    schemaVersion: number;
+    id: string;
+    name: string;
+    type: 'hud';
+    design?: {
+        designAspectRatio?: string;
+        safeArea?: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+    };
+    entities: unknown[];
+    metadata?: WorldScene['metadata'];
+}
+export type SceneFile = WorldScene | HudScene;

package/dist/scene/types.js

@@ -0,0 +1,10 @@
+/**
+ * Scene-as-data types — visual editor foundation (slice 1).
+ *
+ * Spec: unboxy-design/features/visual-editor/01-scene-data-foundation.md
+ *
+ * v1 schema (`schemaVersion: 1`) supports the entity kinds needed for the
+ * read-only scene viewer. HUD entity kinds, tilemap, trigger, and
+ * code-rendered visuals will land in later slices.
+ */
+export const SCHEMA_VERSION = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboxy/phaser-sdk",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,7 +11,8 @@
   "scripts": {
     "build": "tsc",
     "test": "npm run build && node --test scripts/test-chat-facade.mjs",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && [ \"$UNBOXY_PUBLISH_VIA_SCRIPT\" = \"1\" ] || (echo '\\nERROR: do not run `npm publish` directly. Use ./publish.sh instead — it gates on the template-sync checklist.\\nSee CLAUDE.md \"Template sync — do not skip\".\\n' >&2 && exit 1)",
+    "release": "./publish.sh"
   },
   "dependencies": {
     "colyseus.js": "^0.16.0"