@umicat/phaser-sdk 1.0.0

package/dist/scene/SceneLoader.js

@@ -0,0 +1,615 @@
+import Phaser from 'phaser';
+import { SCHEMA_VERSION, } from './types.js';
+import { spawnEntity } from './spawnEntity.js';
+import { attachEntityRegistry } from './EntityRegistry.js';
+import { resolveRenderScript } from './renderScripts.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('umicat:manifest')) {
+        scene.load.json('umicat: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('umicat:manifest');
+    if (!raw) {
+        throw new Error("[umicat/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(`[umicat/scene] manifest schemaVersion ${m.schemaVersion} but SDK expects ${SCHEMA_VERSION}`);
+    }
+    if (!m.scenes?.length) {
+        throw new Error('[umicat/scene] manifest has no scenes');
+    }
+    if (!m.scenes.find((s) => s.id === m.initialScene)) {
+        throw new Error(`[umicat/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) {
+            // Soft-fail: warn, continue. The downstream spawn path renders a
+            // magenta "?" placeholder for the offending entity so the user sees
+            // *where* a missing asset would have been, without losing every
+            // other entity in the scene. Common cause is the editor adding a
+            // sprite that references an asset whose manifest entry never got
+            // synced (e.g. AssetShelf drag without manifest update).
+            // eslint-disable-next-line no-console
+            console.warn(`[umicat/scene] scene '${sceneFile.id}' references assetId '${id}' but the manifest has no such asset; entity will render as a placeholder`);
+            continue;
+        }
+        queueAssetLoad(scene, asset);
+        state.requestedAssetIds.add(id);
+    }
+}
+function collectAssetIds(entities) {
+    const ids = new Set();
+    function walk(e) {
+        if (e.kind === 'sprite') {
+            ids.add(e.assetId);
+        }
+        else if (e.kind === 'group') {
+            for (const child of e.children)
+                walk(child);
+        }
+        else if (e.kind === 'tilemap') {
+            // Slice 6 Phase A: each layer's tilesetIds reference Asset records
+            // the same way sprite.assetId does. Walk every layer and queue each
+            // tileset's PNG for load. Phase A consumes one tileset per layer at
+            // render time but we collect the whole tilesetIds[] array so later
+            // phases (multi-tileset blended layers) need no change here.
+            for (const layer of e.layers) {
+                for (const id of layer.tilesetIds ?? [])
+                    ids.add(id);
+            }
+        }
+        // rect / circle / code-rendered / trigger don't reference assets.
+    }
+    for (const e of entities)
+        walk(e);
+    return Array.from(ids);
+}
+/**
+ * Walk every `kind=spritesheet` asset in the manifest and register each one's
+ * `animations[]` as a Phaser animation, so behavior code can call
+ * `sprite.play('walk-down')` directly. Idempotent — uses `scene.anims.exists()`
+ * to skip duplicates (Phaser's anims.create throws otherwise).
+ *
+ * <p>Animation keys are scene-global. Two sheets registering the same name
+ * (e.g. two characters both with `walk-down`) → first wins, second logs a
+ * warning. Sheets that need disambiguation should namespace their keys
+ * (e.g. `cow:walk-down`) at metadata time.
+ */
+/**
+ * Walk every asset in the manifest and apply `Phaser.Textures.FilterMode.NEAREST`
+ * to each `pixelArt: true` entry's loaded texture. Without this, pixel-art
+ * sprites render bilinear-blurred — visible immediately on imported character
+ * sheets when the agent hasn't manually set Phaser game config's `pixelArt`.
+ *
+ * <p>Idempotent: setFilter is safe to call multiple times. Skip silently when
+ * a texture isn't loaded yet (next call after that asset is requested will
+ * pick it up). Wrap in try/catch so a single bad asset doesn't block the rest
+ * of scene init.
+ *
+ * <p>Per-asset NEAREST closes the visible blur gap; the game-wide flag
+ * (`Phaser.Game.config.pixelArt` + `camera.setRoundPixels`) is a separate
+ * concern (framebuffer-stretch crispness, perf) deferred to a follow-up.
+ */
+export function applyPixelArtFilters(scene, manifest) {
+    for (const asset of manifest.assets ?? []) {
+        if (!asset.pixelArt)
+            continue;
+        if (!scene.textures.exists(asset.textureKey))
+            continue;
+        try {
+            const tex = scene.textures.get(asset.textureKey);
+            tex.setFilter(Phaser.Textures.FilterMode.NEAREST);
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.warn(`[umicat/scene] failed to apply NEAREST filter to '${asset.id}': ${String(e)}`);
+        }
+    }
+}
+function registerSheetAnimations(scene, manifest) {
+    const assets = manifest.assets ?? [];
+    for (const asset of assets) {
+        if (asset.kind !== 'spritesheet')
+            continue;
+        if (!asset.animations || asset.animations.length === 0)
+            continue;
+        if (!scene.textures.exists(asset.textureKey))
+            continue; // not loaded — skip
+        const defaultFps = asset.fps && asset.fps > 0 ? asset.fps : 8;
+        for (const anim of asset.animations) {
+            if (!anim.name)
+                continue;
+            if (scene.anims.exists(anim.name)) {
+                // Don't error out on collision — first registration wins.
+                // eslint-disable-next-line no-console
+                console.warn(`[umicat/scene] animation key '${anim.name}' already registered; skipping (asset '${asset.id}'). Disambiguate by renaming in the asset's animations metadata.`);
+                continue;
+            }
+            const fps = anim.fps && anim.fps > 0 ? anim.fps : defaultFps;
+            const loop = anim.loop !== false; // default true
+            try {
+                scene.anims.create({
+                    key: anim.name,
+                    frames: scene.anims.generateFrameNumbers(asset.textureKey, {
+                        start: anim.from,
+                        end: anim.to,
+                    }),
+                    frameRate: fps,
+                    repeat: loop ? -1 : 0,
+                });
+            }
+            catch (e) {
+                // eslint-disable-next-line no-console
+                console.warn(`[umicat/scene] failed to register animation '${anim.name}' on '${asset.id}': ${String(e)}`);
+            }
+        }
+    }
+}
+/**
+ * Atlas-json side-cache key. Phaser's `scene.load.atlas()` loads + parses the
+ * JSON but drops unknown per-frame fields (e.g. `ninePatch`) — they don't
+ * survive into the Phaser Frame object. To consume them at runtime we ALSO
+ * fetch the raw JSON via `scene.load.json()` and stash it under this key so
+ * `getAtlasFrameNinePatch` can read it back.
+ *
+ * Used by region-atlas assets (visual editor slice 10) where each tagged
+ * region can carry its own 9-slice cuts.
+ */
+function atlasNinePatchCacheKey(textureKey) {
+    return `umicat:atlas-ninepatch:${textureKey}`;
+}
+function queueAtlasNinePatchSidecar(scene, asset) {
+    if (!asset.atlasPath)
+        return;
+    const cacheKey = atlasNinePatchCacheKey(asset.textureKey);
+    if (scene.cache.json.exists(cacheKey))
+        return;
+    scene.load.json(cacheKey, asset.atlasPath);
+}
+/**
+ * Look up per-frame 9-slice metadata for an atlas-format asset. Returns the
+ * `NinePatchConfig` declared inline on the named frame in the atlas JSON, or
+ * `undefined` if the asset isn't an atlas, the cache miss happened, or the
+ * frame has no `ninePatch` entry (plain stretched draw).
+ */
+export function getAtlasFrameNinePatch(scene, textureKey, frameName) {
+    const cacheKey = atlasNinePatchCacheKey(textureKey);
+    if (!scene.cache.json.exists(cacheKey))
+        return undefined;
+    const raw = scene.cache.json.get(cacheKey);
+    const entry = raw?.frames?.[frameName];
+    const np = entry?.ninePatch;
+    if (!np)
+        return undefined;
+    if (typeof np.leftWidth !== 'number' ||
+        typeof np.rightWidth !== 'number' ||
+        typeof np.topHeight !== 'number' ||
+        typeof np.bottomHeight !== 'number') {
+        return undefined;
+    }
+    return {
+        leftWidth: np.leftWidth,
+        rightWidth: np.rightWidth,
+        topHeight: np.topHeight,
+        bottomHeight: np.bottomHeight,
+    };
+}
+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': {
+            // Tolerant config resolution: prefer nested `spriteSheetConfig`, fall
+            // back to top-level `frameWidth/frameHeight/margin/spacing` if the
+            // agent put them there (common typo — both shapes appear in real
+            // workspaces). Soft-fail with warning when neither shape provides
+            // frame dims so the rest of the scene still boots.
+            const cfg = asset.spriteSheetConfig
+                ?? (asset.frameWidth && asset.frameHeight
+                    ? {
+                        frameWidth: asset.frameWidth,
+                        frameHeight: asset.frameHeight,
+                        margin: asset.margin,
+                        spacing: asset.spacing,
+                    }
+                    : null);
+            if (!cfg) {
+                // eslint-disable-next-line no-console
+                console.warn(`[umicat/scene] asset '${asset.id}' kind=spritesheet missing spriteSheetConfig (and no top-level frameWidth/frameHeight); skipping load`);
+                return;
+            }
+            scene.load.spritesheet(asset.textureKey, asset.path, cfg);
+            return;
+        }
+        case 'atlas':
+            if (!asset.atlasPath || !asset.atlasFormat) {
+                throw new Error(`[umicat/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);
+                queueAtlasNinePatchSidecar(scene, asset);
+            }
+            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(`[umicat/scene] unknown asset kind: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+/**
+ * Suspend the scene's update/physics/tween processing while async work
+ * runs inside `create()`. Phaser does not await an async `create()` —
+ * the scene transitions to RUNNING as soon as the call returns its
+ * Promise, and `update()` starts ticking on the next frame regardless of
+ * whether the awaited load has settled. Without this guard, any
+ * `update()` code that reads class fields populated AFTER the await
+ * (e.g. `this.player.body`) crashes on frame 1 with
+ * `Cannot read properties of undefined (reading 'body')`.
+ *
+ * Idempotent: if the scene is already paused (e.g. the editor has
+ * paused everything via `setupEditorModeListener`), we leave it that
+ * way and the returned release is a no-op.
+ */
+export function suspendSceneUpdates(scene) {
+    const wasActive = scene.sys.settings.active;
+    if (!wasActive)
+        return () => { };
+    scene.scene.pause();
+    return () => {
+        scene.scene.resume();
+    };
+}
+/**
+ * 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.
+ *
+ * Phaser's update loop is suspended for the duration of the await so
+ * `update()` can safely read fields the agent assigns AFTER `await
+ * loadWorldScene(...)` — no manual `if (!this.player) return;` guard
+ * required.
+ *
+ * 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 release = suspendSceneUpdates(scene);
+    try {
+        return await loadWorldSceneImpl(scene, sceneId, options);
+    }
+    finally {
+        release();
+    }
+}
+async function loadWorldSceneImpl(scene, sceneId, options) {
+    const manifest = getManifest(scene);
+    const ref = manifest.scenes.find((s) => s.id === sceneId);
+    if (!ref)
+        throw new Error(`[umicat/scene] manifest has no scene with id '${sceneId}'`);
+    if (ref.type !== 'world') {
+        throw new Error(`[umicat/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(`[umicat/scene] scene '${sceneId}' schemaVersion ${sceneFile.schemaVersion} but SDK expects ${SCHEMA_VERSION}`);
+    }
+    if (sceneFile.type !== 'world') {
+        throw new Error(`[umicat/scene] scene '${sceneId}' has type=${sceneFile.type} in file body`);
+    }
+    // Apply gravity declared in scene data to the Arcade physics world before
+    // entities spawn. Scene-level `world.physics.gravity` wins over the
+    // manifest-wide `globals.physics.gravity`.
+    applyWorldGravity(scene, sceneFile, manifest);
+    // Lazy preload of any new assets this scene needs, then await loader.
+    preloadSceneAssets(scene, sceneFile, manifest);
+    await runLoader(scene);
+    // Per-asset NEAREST filter for `pixelArt: true` entries. Must run after
+    // textures are loaded — setFilter on a missing texture is a no-op.
+    applyPixelArtFilters(scene, manifest);
+    // Register Phaser animations declared in `manifest.assets[].animations`.
+    // Done after texture load + before entity spawn so behavior code can call
+    // `sprite.play('walk-down')` from frame 1 without manual `anims.create()`.
+    registerSheetAnimations(scene, manifest);
+    // Spawn entities.
+    const registry = attachEntityRegistry(scene);
+    const ctx = {
+        scene,
+        registry,
+        resolveAsset: (id) => resolveAsset(manifest, id),
+        resolveRenderScript: options.resolveRenderScript ??
+            ((path) => resolveRenderScript(scene.game, path)),
+    };
+    for (const entity of sceneFile.entities)
+        spawnEntity(ctx, entity);
+    // Configure camera.
+    applyCamera(scene, sceneFile, registry);
+    // Slice 8: install per-frame Y-sort hook when the scene opts in. Walks
+    // the entity registry every frame and sets `sprite.depth = sprite.y` so
+    // closer-to-camera sprites overlap farther ones. Two opt-out signals
+    // (explicit transform.depth or properties.skipYSort) keep specific
+    // entities on their constant layer.
+    if (sceneFile.ySort) {
+        installYSortHook(scene, registry);
+    }
+    // Slice 6 Phase B fix — keep TilemapLayers visually anchored to their
+    // tilemap entity's container.x/y. Layers can't be Container children due
+    // to a Phaser render quirk (see createTilemap), so we sync world position
+    // every frame. **Edit-mode sync** runs from EditorOverlayScene.update()
+    // (which is always active during edit, unlike the world scene which is
+    // paused — `setActive(false)` per Phase A camera architecture suspends
+    // scene.events.UPDATE → a hook registered here wouldn't fire during edit
+    // mode, which is exactly when the user drags entities). **Play-mode
+    // sync** runs from scene.events.UPDATE (active scene fires events
+    // normally) — required for any future behavior code that moves a
+    // tilemap entity dynamically.
+    installTilemapLayerSync(scene, registry);
+    // Auto-launch the HUD scene attached to this world (slice 5). Imported
+    // lazily to avoid pulling HudRuntime into worlds that don't need it.
+    if (ref.hud) {
+        const { UMICAT_HUD_SCENE_KEY } = await import('./HudRuntime.js');
+        if (scene.scene.isActive(UMICAT_HUD_SCENE_KEY)) {
+            scene.scene.stop(UMICAT_HUD_SCENE_KEY);
+        }
+        scene.scene.launch(UMICAT_HUD_SCENE_KEY, { hudId: ref.hud });
+    }
+    return { sceneFile, registry };
+}
+async function loadSceneJson(scene, ref) {
+    const cacheKey = `umicat: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(`[umicat/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(`[umicat/scene] manifest has no asset with id '${assetId}'`);
+    }
+    return asset;
+}
+/**
+ * Slice 8: per-frame Y-sort. Walks the entity registry and assigns
+ * `setDepth(y)` to every sprite/primitive/code-rendered entity that hasn't
+ * opted out via explicit `transform.depth` or `properties.skipYSort`.
+ *
+ * Iteration scope is the registry, not `scene.children.list` — registry
+ * holds slice-1 entities only (no editor overlay graphics, no transient
+ * Graphics drawn by behavior code). Cost is O(n) per frame where n =
+ * entity count; well within budget for a 200-entity top-down scene at
+ * 60 FPS.
+ *
+ * Opt-out priority:
+ * 1. `entity.transform.depth` is a number → that constant wins permanently;
+ *    setDepth never overwrites. For "cloud always on top," "tilemap at
+ *    -1000," etc.
+ * 2. `entity.properties.skipYSort: true` → behavior code manages depth;
+ *    ySort doesn't touch the entity.
+ *
+ * Both checks read from the data manager (stashed by `tagGameObject` in
+ * spawnEntity.ts) to avoid round-tripping to the scene file every frame.
+ */
+function installYSortHook(scene, registry) {
+    scene.events.on(Phaser.Scenes.Events.UPDATE, () => {
+        for (const go of registry.all()) {
+            const transform = go.getData('entityTransform');
+            if (typeof transform?.depth === 'number')
+                continue;
+            const props = go.getData('entityProperties');
+            if (props?.skipYSort)
+                continue;
+            const target = go;
+            if (typeof target.y === 'number' && target.setDepth) {
+                target.setDepth(target.y);
+            }
+        }
+    });
+}
+/**
+ * Slice 6 Phase B — per-frame sync of TilemapLayer world positions to
+ * their parent tilemap container's transform. TilemapLayer can't be a
+ * Container child due to a Phaser rendering quirk (parent transform isn't
+ * applied to tilemap render), so layers live in scene root and we manually
+ * keep their world position in step with the container's. Each layer's
+ * `tilemapLocalOffsetX/Y` stash records the centered offset relative to
+ * the container; world position = container.x/y + offset.
+ *
+ * Cheap loop — only iterates entities tagged `entityKind === 'tilemap'`.
+ * Skips silently when no layers stashed (e.g. tilemap with no tilesets).
+ *
+ * Without this: dragging a painted tilemap in the editor would visually
+ * separate the grid bounds (which DO move with the container) from the
+ * painted tiles (which would stay frozen at their initial world position).
+ */
+function installTilemapLayerSync(scene, registry) {
+    scene.events.on(Phaser.Scenes.Events.UPDATE, () => {
+        for (const go of registry.all()) {
+            if (go.getData('entityKind') !== 'tilemap')
+                continue;
+            const container = go;
+            const layers = go.getData('tilemapLayers');
+            if (!layers)
+                continue;
+            const containerDepth = container.depth ?? 0;
+            for (const layer of layers) {
+                const offX = layer.getData('tilemapLocalOffsetX') ?? 0;
+                const offY = layer.getData('tilemapLocalOffsetY') ?? 0;
+                const targetX = container.x + offX;
+                const targetY = container.y + offY;
+                if (layer.x !== targetX)
+                    layer.x = targetX;
+                if (layer.y !== targetY)
+                    layer.y = targetY;
+                // FB.10 — sync depth from container so user-driven z-order
+                // changes (Hierarchy drag → patchEntity → setDepth on container)
+                // actually move the layer's tiles. Without this, container.depth
+                // changes but layers stay at depth=0, so tilemap A "above" B
+                // doesn't actually render on top of B. Multiple layers within
+                // one tilemap share the container's depth; their relative order
+                // falls back to scene add order (= layer.z from createTilemap).
+                if (layer.depth !== containerDepth)
+                    layer.setDepth(containerDepth);
+            }
+        }
+    });
+}
+/**
+ * Apply gravity declared in scene data to the scene's Arcade physics world.
+ *
+ * Precedence: the scene's own `world.physics.gravity` wins over the
+ * manifest-wide `globals.physics.gravity`. When neither is set, the world's
+ * gravity is left untouched — whatever `createUmicatGame` (or a game.json
+ * `GameConfig` wired through it) already established.
+ *
+ * Before this, both fields were typed-but-dead: a game could declare gravity
+ * in scene data, the SDK would silently ignore it, and e.g. a platformer
+ * would run at zero gravity. Applied per scene-load so each world scene can
+ * carry its own gravity. Components are applied individually so a partial
+ * `{ y }` leaves the existing `x` (and vice versa) intact.
+ */
+function applyWorldGravity(scene, sceneFile, manifest) {
+    const gravity = sceneFile.world.physics?.gravity ?? manifest.globals?.physics?.gravity;
+    if (!gravity)
+        return;
+    const world = scene.physics?.world;
+    if (!world)
+        return; // Arcade physics not enabled on this scene — nothing to do.
+    if (typeof gravity.x === 'number')
+        world.gravity.x = gravity.x;
+    if (typeof gravity.y === 'number')
+        world.gravity.y = gravity.y;
+}
+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(`[umicat/scene] camera.follow id='${cfg.follow}' has no matching entity in scene '${sceneFile.id}'`);
+        }
+    }
+}