@unboxy/phaser-sdk 0.2.16 → 0.2.18

package/dist/editor/EditorState.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Per-game editor state, shared between EditorBridge (postMessage handler)
+ * and EditorOverlayScene (canvas renderer + pointer source).
+ *
+ * Design 03 §13.5: in Edit mode the editor overlay captures clicks before
+ * they reach game systems; this state carries the selection + drag-in-progress
+ * info both sides read.
+ */
+interface EditorStateShape {
+    active: boolean;
+    selectedId: string | null;
+    /**
+     * Drag-in-progress info. While set, the overlay scene mutates the entity's
+     * x/y directly per pointermove without going through the host. On
+     * pointerup it posts dragEnd with before/after, and the host pushes a
+     * single command. This is the "SDK holds short-lived visual state" path
+     * from the slice-2 design discussion.
+     */
+    drag: {
+        entityId: string;
+        startWorld: {
+            x: number;
+            y: number;
+        };
+        startEntity: {
+            x: number;
+            y: number;
+        };
+    } | null;
+}
+/**
+ * Accept any object — we only use a single internal symbol-style key, so
+ * there's no risk of collision with Phaser's own props.
+ */
+type AnyObject = object;
+export declare function getEditorState(game: AnyObject): EditorStateShape;
+export declare function setEditorActive(game: AnyObject, active: boolean): void;
+export declare function setSelection(game: AnyObject, id: string | null): void;
+export declare function getSelection(game: AnyObject): string | null;
+export declare function startDrag(game: AnyObject, entityId: string, startWorld: {
+    x: number;
+    y: number;
+}, startEntity: {
+    x: number;
+    y: number;
+}): void;
+export declare function clearDrag(game: AnyObject): void;
+export declare function getDrag(game: AnyObject): EditorStateShape['drag'];
+export {};

package/dist/editor/EditorState.js

@@ -0,0 +1,39 @@
+/**
+ * Per-game editor state, shared between EditorBridge (postMessage handler)
+ * and EditorOverlayScene (canvas renderer + pointer source).
+ *
+ * Design 03 §13.5: in Edit mode the editor overlay captures clicks before
+ * they reach game systems; this state carries the selection + drag-in-progress
+ * info both sides read.
+ */
+const KEY = '__unboxyEditorState';
+function bag(game) {
+    return game;
+}
+export function getEditorState(game) {
+    const b = bag(game);
+    const existing = b[KEY];
+    if (existing)
+        return existing;
+    const fresh = { active: false, selectedId: null, drag: null };
+    b[KEY] = fresh;
+    return fresh;
+}
+export function setEditorActive(game, active) {
+    getEditorState(game).active = active;
+}
+export function setSelection(game, id) {
+    getEditorState(game).selectedId = id;
+}
+export function getSelection(game) {
+    return getEditorState(game).selectedId;
+}
+export function startDrag(game, entityId, startWorld, startEntity) {
+    getEditorState(game).drag = { entityId, startWorld, startEntity };
+}
+export function clearDrag(game) {
+    getEditorState(game).drag = null;
+}
+export function getDrag(game) {
+    return getEditorState(game).drag;
+}

package/dist/index.d.ts

@@ -16,4 +16,15 @@ 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 { setupEditorBridge } from './editor/EditorBridge.js';
+export { EditorOverlayScene, EDITOR_OVERLAY_KEY } from './editor/EditorOverlayScene.js';
+export type { EditorEntityPatch, EditorEnterMessage, EditorExitMessage, EditorGetSceneMessage, EditorApplyEditMessage, EditorSetSelectionMessage, EditorPanZoomMessage, EditorHostToSdkMessage, EditorSceneLoadedMessage, EditorSelectionPickedMessage, EditorDragEndMessage, EditorSdkToHostMessage, } from './protocol.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,12 @@ 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 { setupEditorBridge } from './editor/EditorBridge.js';
+export { EditorOverlayScene, EDITOR_OVERLAY_KEY } from './editor/EditorOverlayScene.js';
+export { SCHEMA_VERSION, } from './scene/types.js';
 export { PROTOCOL_VERSION, } from './protocol.js';

package/dist/protocol.d.ts

@@ -46,6 +46,102 @@ export interface RpcResultError {
     error: RpcErrorPayload;
 }
 export type HostToSdkMessage = InitMessage | RpcResultOk | RpcResultError;
+/**
+ * Patch shape applied to a live entity. Only the fields present are updated;
+ * `null` is the explicit clear (drops the field). The patch mirrors the slice
+ * of the entity schema the editor edits in slice 2 — transform + simple
+ * visual fields. Properties / behavior wiring extend this in later slices.
+ */
+export interface EditorEntityPatch {
+    transform?: Partial<{
+        x: number;
+        y: number;
+        rotation: number;
+        scaleX: number;
+        scaleY: number;
+        depth: number;
+    }>;
+    visual?: {
+        tint?: string | null;
+        alpha?: number;
+        flipX?: boolean;
+        flipY?: boolean;
+        frame?: string | number;
+        /** For primitives. */
+        width?: number;
+        height?: number;
+        radius?: number;
+        fillColor?: string;
+        strokeColor?: string | null;
+        strokeWidth?: number;
+    };
+    role?: string | null;
+    properties?: Record<string, unknown>;
+}
+export interface EditorEnterMessage {
+    type: 'unboxy:editor:enter';
+}
+export interface EditorExitMessage {
+    type: 'unboxy:editor:exit';
+}
+export interface EditorGetSceneMessage {
+    /** Host requests a snapshot of what's currently loaded in the iframe. */
+    type: 'unboxy:editor:getScene';
+}
+export interface EditorApplyEditMessage {
+    type: 'unboxy:editor:applyEdit';
+    entityId: string;
+    patch: EditorEntityPatch;
+}
+export interface EditorSetSelectionMessage {
+    type: 'unboxy:editor:setSelection';
+    /** Empty array deselects. v1: max length 1 (multi-select is slice 2.5). */
+    entityIds: string[];
+}
+export interface EditorPanZoomMessage {
+    /** Editor camera control — separate from in-game camera. */
+    type: 'unboxy:editor:panZoom';
+    scrollX?: number;
+    scrollY?: number;
+    /** Absolute zoom (1 = 100%). */
+    zoom?: number;
+    /** If true, deltas are added to current scroll. */
+    relative?: boolean;
+}
+export type EditorHostToSdkMessage = EditorEnterMessage | EditorExitMessage | EditorGetSceneMessage | EditorApplyEditMessage | EditorSetSelectionMessage | EditorPanZoomMessage;
+export interface EditorSceneLoadedMessage {
+    type: 'unboxy:editor:sceneLoaded';
+    sceneId: string;
+    /** Snapshot of the world scene file's current entities + camera. */
+    sceneFile: unknown;
+}
+export interface EditorSelectionPickedMessage {
+    /** Pointer-down on an entity in the canvas — host should update selection. */
+    type: 'unboxy:editor:pickEntity';
+    entityId: string | null;
+    /** Modifier keys at pointer-down so host can decide single/toggle/range. */
+    modifiers: {
+        shift: boolean;
+        cmdOrCtrl: boolean;
+        alt: boolean;
+    };
+}
+export interface EditorDragEndMessage {
+    /** Pointer-up after dragging an entity. delta is total movement in world coords. */
+    type: 'unboxy:editor:dragEnd';
+    entityId: string;
+    /** Position before drag started. */
+    before: {
+        x: number;
+        y: number;
+    };
+    /** Position at release. */
+    after: {
+        x: number;
+        y: number;
+    };
+}
+export type EditorSdkToHostMessage = EditorSceneLoadedMessage | EditorSelectionPickedMessage | EditorDragEndMessage;
 export type RpcMethod = 'saves.get' | 'saves.set' | 'saves.delete' | 'saves.list' | 'gameData.get' | 'gameData.set' | 'gameData.delete' | 'gameData.list' | 'realtime.getToken';
 export interface SavesGetParams {
     key: string;

package/dist/scene/EditorMode.d.ts

@@ -0,0 +1,17 @@
+import Phaser from 'phaser';
+/**
+ * Slice-1 entry point that became a thin wrapper over the slice-2 editor
+ * bridge. The bridge owns the full edit-mode lifecycle (pause world scenes,
+ * launch overlay, handle pointer events, route postMessage commands).
+ *
+ * Wire shape (host → SDK):
+ *   { type: 'unboxy:editor:enter' }   - enter edit mode
+ *   { type: 'unboxy:editor:exit'  }   - exit edit mode
+ *   ...plus the rest of the editor protocol — see protocol.ts
+ *
+ * The slice-1 `unboxy:setEditMode` message is no longer accepted; home-ui
+ * has been updated to send the editor:enter / editor:exit pair as part of
+ * the slice-2 work.
+ */
+export declare function setupEditorModeListener(game: Phaser.Game): void;
+export declare function isEditMode(game: Phaser.Game): boolean;

package/dist/scene/EditorMode.js

@@ -0,0 +1,22 @@
+import { setupEditorBridge } from '../editor/EditorBridge.js';
+import { getEditorState } from '../editor/EditorState.js';
+/**
+ * Slice-1 entry point that became a thin wrapper over the slice-2 editor
+ * bridge. The bridge owns the full edit-mode lifecycle (pause world scenes,
+ * launch overlay, handle pointer events, route postMessage commands).
+ *
+ * Wire shape (host → SDK):
+ *   { type: 'unboxy:editor:enter' }   - enter edit mode
+ *   { type: 'unboxy:editor:exit'  }   - exit edit mode
+ *   ...plus the rest of the editor protocol — see protocol.ts
+ *
+ * The slice-1 `unboxy:setEditMode` message is no longer accepted; home-ui
+ * has been updated to send the editor:enter / editor:exit pair as part of
+ * the slice-2 work.
+ */
+export function setupEditorModeListener(game) {
+    setupEditorBridge(game);
+}
+export function isEditMode(game) {
+    return getEditorState(game).active;
+}

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}'`);
+        }
+    }
+}