@jgengine/core 0.11.0 → 0.13.0

package/dist/runtime/gameContext.js

@@ -1,47 +1,16 @@
-import {} from "../cards/cardPile.js";
-import { createDeathSystem, deathReasonFromEffect, normalizeOnDeath } from "../combat/death.js";
-import { createEffectSystem, } from "../combat/effects.js";
-import { createProjectileSystem } from "../combat/projectiles.js";
-import {} from "../combat/hitReaction.js";
-import {} from "../combat/telegraph.js";
-import { createCommandRegistry, } from "../commands/commandRegistry.js";
-import { balance as walletBalance, charge as walletCharge, createEmptyWallet, grant as walletGrant, isOverdrawn as walletIsOverdrawn, } from "../economy/wallet.js";
+import { createCommandRegistry } from "../commands/commandRegistry.js";
 import {} from "../game/cosmetics.js";
 import { groundFieldFor } from "../world/terrain.js";
 import { createGameEvents } from "../game/events.js";
-import { createVfxInstanceStore } from "../game/vfxInstance.js";
 import { createGameFeed } from "../game/feed.js";
 import { setGamePhase } from "../game/gamePhase.js";
-import {} from "../game/leaderboard.js";
-import { createLoadouts } from "../game/loadout.js";
 import { createLootRegistry, grantDrops } from "../game/lootTable.js";
-import {} from "../game/dialogue.js";
-import {} from "../game/quest.js";
-import { resolveDeathDrops, DEFAULT_RARITY, } from "../game/worldItem.js";
-import {} from "../game/chat.js";
 import { createSocial } from "../game/social.js";
-import {} from "../game/trade.js";
-import {} from "../game/unlocks.js";
-import { createInventorySet, putItem, } from "../inventory/inventoryModel.js";
-import { createItemUse, } from "../item/use.js";
+import { splitStack } from "../inventory/inventoryModel.js";
+import { createItemUse } from "../item/use.js";
 import { createWeaponStats } from "../item/weapon.js";
-import { createPoseState } from "../movement/poseState.js";
-import { createBodyBind } from "../scene/bodyBind.js";
-import { createPaintLayer } from "../scene/paintLayer.js";
-import { createEntityStatsApi, seedStatValues, setStatValue, } from "../scene/entityStats.js";
-import { createEntityStore, } from "../scene/entityStore.js";
-import { createForms } from "../scene/form.js";
-import { scaledEntityColliders, scaledObjectColliders } from "../scene/colliders.js";
-import { raycastObjects, raycastObjectsAll } from "../scene/objectQuery.js";
-import { createObjectStore, objectVisualScale } from "../scene/objectStore.js";
-import {} from "../scene/roster.js";
-import { createSelectionSet } from "../scene/selection.js";
-import {} from "../game/connectedPlayers.js";
-import { createPossession } from "../scene/possession.js";
-import { createSceneRaycast, } from "../scene/sceneRaycast.js";
-import { createSpatialApi } from "../scene/spatial.js";
-import { createTargeting } from "../scene/targeting.js";
-import { createStats } from "../stats/statModifiers.js";
+import {} from "../scene/entityStats.js";
+import {} from "../scene/entityStore.js";
 import { createChangeSignal, notifyAfter } from "../store/changeSignal.js";
 import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
 import { applyWorldSnapshot, composeWorldSnapshot, } from "./worldSnapshot.js";
@@ -50,15 +19,14 @@ import { createRuntimeSave } from "./runtimeSave.js";
 import { isOffline } from "./adapter.js";
 import { localSaveBackend, memorySaveBackend } from "../game/saveStore.js";
 import { createSimClock } from "../time/simClock.js";
-import {} from "../turn/turnLoop.js";
-import { RaceState } from "../game/race.js";
 import { createCameraDirector } from "./cameraDirector.js";
 import { createInputSnapshot } from "./inputSnapshot.js";
-import { createMotionIntents } from "./motionIntents.js";
 import { baselineDescriptors } from "./descriptors/baseline.js";
 import { featureDescriptors } from "./descriptors/features.js";
-import { createCombatFx } from "./context/combatFx.js";
+import { createCombatSubsystem } from "./context/combat.js";
 import { createContextRegistries } from "./context/registries.js";
+import { createPlayerSubsystem } from "./context/player.js";
+import { createSceneSubsystem } from "./context/scene.js";
 import { createWorldItemContext } from "./context/worldItems.js";
 export function createGameContext(options) {
     const { definition, content, player } = options;
@@ -69,131 +37,6 @@ export function createGameContext(options) {
     const activeUserId = () => actingUserId ?? player.userId;
     const time = createSimClock({ config: definition.time, onChange: signal.notify });
     const ground = groundFieldFor(definition.world);
-    const entities = createEntityStore();
-    const objects = createObjectStore();
-    entities.subscribe(signal.notify);
-    objects.subscribe(signal.notify);
-    const statsByInstance = new Map();
-    const entityStats = notifyAfter(createEntityStatsApi((instanceId) => statsByInstance.get(instanceId)), ["set", "delta"], signal.notify);
-    function ensureInstanceStats(instanceId) {
-        let map = statsByInstance.get(instanceId);
-        if (map === undefined) {
-            map = {};
-            statsByInstance.set(instanceId, map);
-        }
-        return map;
-    }
-    function catalogEntry(instanceId) {
-        const entity = entities.get(instanceId);
-        return entity === null ? undefined : content.entityById?.(entity.name);
-    }
-    function catalogObject(instanceId) {
-        const object = objects.get(instanceId);
-        return object === null ? undefined : content.objectById?.(object.catalogId);
-    }
-    let spatialGeneration = 0;
-    const candidateIds = [];
-    let candidateIdsDirty = true;
-    function refreshCandidateIds() {
-        if (!candidateIdsDirty)
-            return candidateIds;
-        candidateIds.length = 0;
-        for (const entity of entities.list())
-            candidateIds.push(entity.id);
-        candidateIdsDirty = false;
-        return candidateIds;
-    }
-    const spatial = createSpatialApi({
-        resolvePosition: (instanceId) => entities.get(instanceId)?.position,
-        candidates: refreshCandidateIds,
-        grid: { cellSize: 8 },
-        getVersion: () => spatialGeneration,
-        ...(occluder !== undefined ? { occluder } : {}),
-    });
-    entities.subscribe(() => {
-        candidateIdsDirty = true;
-        spatialGeneration += 1;
-        spatial.invalidate();
-    });
-    const entityColliders = new Map();
-    const objectColliders = new Map();
-    function entityCollidersOf(instanceId) {
-        const override = entityColliders.get(instanceId);
-        if (override !== undefined)
-            return override;
-        const entry = catalogEntry(instanceId);
-        if (entry?.colliders !== undefined)
-            return entry.colliders;
-        const scale = entry?.scale;
-        if (scale !== undefined && scale !== 1)
-            return scaledEntityColliders(scale);
-        return null;
-    }
-    function entityVisualScaleOf(instanceId) {
-        return catalogEntry(instanceId)?.scale ?? 1;
-    }
-    function objectCollidersOf(instanceId) {
-        const override = objectColliders.get(instanceId);
-        if (override !== undefined)
-            return override;
-        const catalog = catalogObject(instanceId);
-        if (catalog?.colliders !== undefined)
-            return catalog.colliders;
-        if (catalog?.halfExtents !== undefined)
-            return null;
-        const object = objects.get(instanceId);
-        if (object === null || object.visual?.scale === undefined)
-            return null;
-        return scaledObjectColliders(objectVisualScale(object.visual));
-    }
-    const targeting = notifyAfter(createTargeting({
-        candidates: () => [...refreshCandidateIds()],
-        classify(_fromId, toId) {
-            const role = catalogEntry(toId)?.role;
-            return role === "enemy" || role === "hostile" ? "hostile" : "friendly";
-        },
-        distance: (fromId, toId) => spatial.distance(fromId, toId),
-    }), ["setTarget", "cycleTarget"], signal.notify);
-    const combatSpatial = {
-        inRadius: (center, radius) => spatial.inRadius(center, radius),
-        hasLineOfSight: (from, to) => {
-            if (typeof from === "string")
-                return spatial.hasLineOfSight(from, to);
-            const toPos = entities.get(to)?.position;
-            if (toPos === undefined)
-                return false;
-            if (occluder === undefined)
-                return true;
-            return !occluder(from, toPos);
-        },
-        positionOf: (instanceId) => entities.get(instanceId)?.position,
-    };
-    const sceneRaycast = createSceneRaycast({
-        entities: {
-            list: () => entities.list().map((entity) => ({
-                id: entity.id,
-                position: entity.position,
-                rotationY: entity.rotationY,
-                name: entity.name,
-            })),
-            collidersOf: entityCollidersOf,
-            inRadius: (center, radius) => spatial.inRadius(center, radius),
-            get: (id) => {
-                const entity = entities.get(id);
-                if (entity === null)
-                    return null;
-                return { id: entity.id, position: entity.position, rotationY: entity.rotationY, name: entity.name };
-            },
-        },
-        objects: {
-            list: () => objects.list(),
-            inBox: (min, max) => objects.inBox(min, max),
-            collidersOf: objectCollidersOf,
-            halfExtentsOf: (catalogId) => content.objectById?.(catalogId)?.halfExtents ?? null,
-        },
-        terrain: ground,
-    });
-    const weapon = createWeaponStats((itemId) => content.itemById?.(itemId));
     const rawEvents = createGameEvents();
     const events = {
         on: rawEvents.on,
@@ -203,8 +46,27 @@ export function createGameContext(options) {
             signal.notify();
         },
     };
+    // --- Scene installer (entities, objects, colliders, spatial, raycast, targeting) ---
+    const scene = createSceneSubsystem({
+        content,
+        signalNotify: signal.notify,
+        ground,
+        events,
+        time,
+        ...(occluder !== undefined ? { occluder } : {}),
+        ...(options.models !== undefined ? { models: options.models } : {}),
+    });
+    const { entities, objects, statsByInstance, entityStats, ensureInstanceStats, catalogEntry, spatial, combatSpatial, sceneRaycast, targeting, entityColliders, entityCollidersOf, objectCollidersOf, reportEntityBounds, entityVisualScaleOf, forms, paintLayer, spawnEntity, despawnEntity, moveEntityTowardCommit, resetAllToSpawn, bind, sceneObjects, } = scene;
+    // --- Shared game services (weapon, feed, features bag, commands, item use) ---
+    const weapon = createWeaponStats((itemId) => content.itemById?.(itemId));
     const feed = createGameFeed(definition.feed);
     const lootRegistry = createLootRegistry();
+    /**
+     * Single feature-activation path (G9): `definition.features` is already the final map after
+     * `defineGame` OR-merged explicit boolean sugar (`features: { quest: true }`) with system-implied
+     * flags via `mergeSystemFeatures`. Descriptor install below is the only place that decides
+     * "feature on" — never a second enable check against systems.
+     */
     const features = definition.features ?? {};
     const featureRegistry = new Map();
     const featureValue = (key) => featureRegistry.get(key);
@@ -222,16 +84,6 @@ export function createGameContext(options) {
         }
         return rawSocial;
     };
-    const playerStatsByUser = new Map();
-    function playerStatsFor(userId) {
-        let stats = playerStatsByUser.get(userId);
-        if (stats === undefined) {
-            stats = createStats({});
-            playerStatsByUser.set(userId, stats);
-        }
-        return stats;
-    }
-    const pose = createPoseState((instanceId) => catalogEntry(instanceId)?.movement);
     const commandRegistry = createCommandRegistry();
     if (definition.lifecycle !== undefined) {
         const lifecycle = definition.lifecycle;
@@ -251,50 +103,57 @@ export function createGameContext(options) {
         });
     }
     const itemUse = createItemUse((itemId) => content.itemById?.(itemId)?.use);
-    const possession = notifyAfter(createPossession({ entities, events }), ["possess", "own", "disown"], signal.notify);
-    const forms = notifyAfter(createForms({ entities, time, events }), ["shapeshift", "revert"], signal.notify);
-    const paintLayer = notifyAfter(createPaintLayer(), ["paint", "clear"], signal.notify);
-    const inventoryDeclarations = definition.inventories ?? {};
-    const inventoryIds = Object.keys(inventoryDeclarations);
-    const layouts = {};
-    for (const [inventoryId, declaration] of Object.entries(inventoryDeclarations)) {
-        layouts[inventoryId] = { slots: declaration.slots, accepts: declaration.accepts };
-    }
-    const traits = Object.values(inventoryDeclarations).find((declaration) => declaration.traits !== undefined)?.traits ?? { stackLimit: () => Number.POSITIVE_INFINITY };
-    const inventoryByUser = new Map();
-    function inventoryFor(userId) {
-        let set = inventoryByUser.get(userId);
-        if (set === undefined) {
-            set = notifyAfter(createInventorySet(layouts, traits), ["put", "take", "move", "replaceState"], signal.notify);
-            inventoryByUser.set(userId, set);
-        }
-        return set;
-    }
-    const wallets = new Map();
-    const walletOf = (userId) => wallets.get(userId) ?? createEmptyWallet();
-    const economy = {
-        balance: (userId, currencyId) => walletBalance(walletOf(userId), currencyId),
-        grant(userId, currencyId, amount) {
-            wallets.set(userId, walletGrant(walletOf(userId), currencyId, amount));
-            signal.notify();
+    // --- Player installer (inventory, wallets, pose, motion, loadout) ---
+    const playerSys = createPlayerSubsystem({
+        signalNotify: signal.notify,
+        inventoryDeclarations: definition.inventories ?? {},
+        entities,
+        events,
+        catalogEntry,
+        ensureInstanceStats,
+        feature: featureValue,
+    });
+    const { inventoryIds, inventoryByUser, inventoryFor, layouts, wallets, walletOf, economy, putIntoAnyInventory, playerStatsFor, pose, possession, motionByUser, motionFor, loadouts, seedUserPool, } = playerSys;
+    scene.setOnAfterDespawn((instanceId) => pose.clear(instanceId));
+    // Built-in inventory mutation commands so a HUD grid drives moves/splits through the notifying
+    // command path (a raw InventorySet mutation would not re-render React). Each resolves the acting
+    // user's own inventory, so it respects `privatePerUser` replication.
+    const knownInventory = (inventoryId) => layouts[inventoryId] !== undefined;
+    const slotInRange = (inventoryId, slot) => typeof slot === "number" && Number.isInteger(slot) && slot >= 0 && slot < layouts[inventoryId].slots;
+    commandRegistry.define("inventory.move", {
+        validate(_state, input) {
+            if (!knownInventory(input.inventoryId))
+                return { reason: `unknown inventory "${input.inventoryId}"` };
+            if (!slotInRange(input.inventoryId, input.from) || !slotInRange(input.inventoryId, input.to)) {
+                return { reason: "invalid-slot" };
+            }
+            return null;
         },
-        charge(userId, currencyId, amount, options) {
-            const result = walletCharge(walletOf(userId), currencyId, amount, options);
-            if (result.status === "rejected")
-                return { reason: result.reason };
-            wallets.set(userId, result.state);
-            signal.notify();
+        apply(_state, input) {
+            const inventory = inventoryFor(activeUserId());
+            // A rejected move (empty source, wrong-kind, no-space) is a harmless no-op: the item bounces back.
+            inventory.move(input.inventoryId, input.from, input.inventoryId, input.to);
+        },
+    });
+    commandRegistry.define("inventory.split", {
+        validate(_state, input) {
+            if (!knownInventory(input.inventoryId))
+                return { reason: `unknown inventory "${input.inventoryId}"` };
+            if (!slotInRange(input.inventoryId, input.slot))
+                return { reason: "invalid-slot" };
+            if (input.toSlot !== undefined && !slotInRange(input.inventoryId, input.toSlot)) {
+                return { reason: "invalid-slot" };
+            }
             return null;
         },
-        isOverdrawn: (userId, currencyId) => walletIsOverdrawn(walletOf(userId), currencyId),
-    };
-    function putIntoAnyInventory(userId, itemId, count) {
-        const inventory = inventoryFor(userId);
-        for (const inventoryId of inventoryIds) {
-            if (inventory.put(inventoryId, itemId, count).status === "ok")
+        apply(_state, input) {
+            const inventory = inventoryFor(activeUserId());
+            const result = splitStack(inventory.state(input.inventoryId), input.slot, input.amount, input.toSlot);
+            if (result.status === "rejected")
                 return;
-        }
-    }
+            inventory.replaceState(input.inventoryId, result.state);
+        },
+    });
     const loot = {
         register: lootRegistry.register,
         has: lootRegistry.has,
@@ -310,100 +169,6 @@ export function createGameContext(options) {
             events.emit("loot.granted", event);
         },
     };
-    function seedUserPool(userId, statId, pool) {
-        const map = ensureInstanceStats(userId);
-        const next = setStatValue(map, statId, pool);
-        map[statId] = next[statId];
-    }
-    const loadouts = notifyAfter(createLoadouts({
-        inventory: {
-            begin(userId) {
-                const inventory = inventoryFor(userId);
-                const staged = new Map();
-                return {
-                    put(inventoryId, itemId, count, slot) {
-                        const layout = layouts[inventoryId];
-                        if (layout === undefined)
-                            return { reason: `unknown inventory "${inventoryId}"` };
-                        const state = staged.get(inventoryId) ?? inventory.state(inventoryId);
-                        const result = putItem(state, layout, traits, itemId, count, slot === undefined ? undefined : { slot });
-                        if (result.status === "rejected")
-                            return { reason: result.reason };
-                        staged.set(inventoryId, result.state);
-                        return null;
-                    },
-                    commit() {
-                        for (const [inventoryId, state] of staged)
-                            inventory.replaceState(inventoryId, state);
-                    },
-                };
-            },
-        },
-        stats: { seed: seedUserPool },
-        economy: { grant: economy.grant },
-        unlocks: { grant: (userId, unlockId) => featureValue("unlocks")?.grant(userId, unlockId) },
-    }), ["applyLoadout"], signal.notify);
-    function spawnEntity(name, spawnOptions) {
-        const entry = content.entityById?.(name);
-        const walkSpeed = spawnOptions?.movement?.walkSpeed ?? entry?.movement?.walkSpeed;
-        const options = walkSpeed === undefined
-            ? spawnOptions
-            : { ...spawnOptions, movement: { ...spawnOptions?.movement, walkSpeed } };
-        const instanceId = entities.spawn(name, options);
-        death.revive(instanceId);
-        statsByInstance.set(instanceId, entry?.stats === undefined ? {} : seedStatValues(entry.stats));
-        return instanceId;
-    }
-    function despawnEntity(instanceId) {
-        const existed = entities.despawn(instanceId);
-        statsByInstance.delete(instanceId);
-        targeting.clearAll(instanceId);
-        pose.clear(instanceId);
-        entityColliders.delete(instanceId);
-        return existed;
-    }
-    function moveEntityTowardCommit(instanceId, target, options) {
-        const next = spatial.moveToward(instanceId, target, options);
-        if (next === null)
-            return null;
-        const current = entities.get(instanceId);
-        if (current === null)
-            return null;
-        let rotationY = current.rotationY;
-        if (options.face === true) {
-            const dx = next[0] - current.position[0];
-            const dz = next[2] - current.position[2];
-            if (Math.hypot(dx, dz) > 1e-9)
-                rotationY = Math.atan2(dx, dz);
-        }
-        entities.setPose(instanceId, { position: next, rotationY });
-        return next;
-    }
-    function resetAllToSpawn(filter) {
-        let count = 0;
-        for (const entity of entities.list()) {
-            if (filter !== undefined && !filter(entity))
-                continue;
-            if (entities.resetToSpawn(entity.id))
-                count += 1;
-        }
-        return count;
-    }
-    const bodyBinds = new Map();
-    function bind(key) {
-        const existing = bodyBinds.get(key);
-        if (existing !== undefined)
-            return existing;
-        const created = createBodyBind({
-            has: (id) => entities.get(id) !== null,
-            spawn: spawnEntity,
-            despawn: despawnEntity,
-            setPose: entities.setPose,
-            update: entities.update,
-        });
-        bodyBinds.set(key, created);
-        return created;
-    }
     const { worldItems, spawnWorldItem, pickupWorldItem } = createWorldItemContext({
         entities,
         events,
@@ -411,171 +176,43 @@ export function createGameContext(options) {
         grantToPlayer: loot.grantToPlayer,
         signalNotify: signal.notify,
     });
-    const death = createDeathSystem({
-        resolveOnDeath: (instanceId) => catalogEntry(instanceId)?.onDeath,
-        resolveIdentity(instanceId) {
-            const entity = entities.get(instanceId);
-            if (entity === null)
-                return null;
-            return {
-                catalogId: entity.name,
-                position: [entity.position[0], entity.position[1], entity.position[2]],
-            };
-        },
-        loot: { roll: (tableId) => (lootRegistry.has(tableId) ? lootRegistry.roll(tableId) : []) },
-        events,
-        runCommand(name, args) {
-            commandRegistry.run(ctx, name, args);
-        },
-        despawn(instanceId) {
-            despawnEntity(instanceId);
-        },
-    });
-    const effects = notifyAfter(createEffectSystem({
-        resolveReceive: (instanceId) => catalogEntry(instanceId)?.receive,
-        resolveStats: (instanceId) => statsByInstance.get(instanceId),
-        getStat: weapon.getStat,
-        spatial: combatSpatial,
-        onLethal(instanceId, lethalCtx) {
-            const dyingEntity = entities.get(instanceId);
-            const catalogId = dyingEntity?.name;
-            const position = dyingEntity?.position;
-            const normalizedOnDeath = normalizeOnDeath(catalogEntry(instanceId)?.onDeath);
-            const reason = deathReasonFromEffect({
-                ...lethalCtx,
-                userIdOf: (id) => (id === player.userId ? player.userId : undefined),
-            });
-            const resolution = death.resolveDeath(instanceId, reason);
-            if (resolution.status === "resolved" &&
-                resolution.drops.length > 0 &&
-                reason.kind === "player_kill" &&
-                reason.killerUserId === player.userId) {
-                if (normalizedOnDeath.dropMode === "world" && position !== undefined) {
-                    const resolved = resolveDeathDrops(resolution.drops, {
-                        mode: "world",
-                        origin: position,
-                        resolveRarity: (itemId) => content.itemById?.(itemId)?.rarity ?? DEFAULT_RARITY,
-                        resolveBaseType: (itemId) => content.itemById?.(itemId)?.baseType ?? itemId,
-                        scatter: normalizedOnDeath.scatter,
-                        ...(catalogId !== undefined ? { source: catalogId } : {}),
-                    });
-                    for (const spawn of resolved.worldSpawns)
-                        spawnWorldItem(spawn);
-                    if (resolved.grants.length > 0)
-                        loot.grantToPlayer(player.userId, resolved.grants, catalogId);
-                }
-                else {
-                    loot.grantToPlayer(player.userId, resolution.drops, catalogId);
-                }
-            }
-        },
-    }), ["applyEffect"], signal.notify);
-    const { emitFloatText, emitVfx, fireTelegraph, applyHitReaction, applyEffectAndFloat } = createCombatFx({
-        entities,
+    // --- Combat installer (effects, projectiles, death, combat FX) ---
+    // Command runner closes over `ctx` once assembled (same late-bind pattern as before).
+    let ctxRef = null;
+    const combat = createCombatSubsystem({
+        content,
+        signalNotify: signal.notify,
+        now,
         events,
         time,
-        applyEffect: (input) => effects.applyEffect(input),
-    });
-    const vfxInstances = createVfxInstanceStore({
-        onOp: (op) => events.emit("combat.vfxInstance", op),
-        now: () => time.now() * 1000,
-    });
-    const floatingEffects = {
-        canReceive: effects.canReceive,
-        preview: effects.preview,
-        applyEffect: applyEffectAndFloat,
-    };
-    const projectileObstacles = definition.physics?.projectileObstacles === true;
-    const projectileSceneRaycast = {
-        raycast(input) {
-            return sceneRaycast.raycast({
-                ...input,
-                filter: {
-                    entities: true,
-                    objects: projectileObstacles,
-                    terrain: false,
-                    walls: projectileObstacles,
-                    ...input.filter,
-                },
-            });
-        },
-        raycastAll(input) {
-            return sceneRaycast.raycastAll({
-                ...input,
-                filter: {
-                    entities: true,
-                    objects: projectileObstacles,
-                    terrain: false,
-                    walls: projectileObstacles,
-                    ...input.filter,
-                },
-            });
-        },
-    };
-    const projectiles = notifyAfter(createProjectileSystem({
-        effects: floatingEffects,
-        spatial: combatSpatial,
-        getStat: weapon.getStat,
-        sceneRaycast: projectileSceneRaycast,
-        objects: projectileObstacles
-            ? {
-                list: () => objects.list(),
-                inBox: (min, max) => objects.inBox(min, max),
-                halfExtents: (catalogId) => {
-                    const half = content.objectById?.(catalogId)?.halfExtents;
-                    return half === undefined ? null : [half[0], half[1], half[2]];
-                },
-                collidersOf: objectCollidersOf,
-            }
-            : undefined,
+        entities,
+        objects,
+        combatSpatial,
+        sceneRaycast,
         entityCollidersOf,
-        rotationYOf: (instanceId) => entities.get(instanceId)?.rotationY,
-        now,
-        onSettle(report) {
-            events.emit("projectile.settled", {
-                from: report.from,
-                origin: [report.origin[0], report.origin[1], report.origin[2]],
-                at: [report.at[0], report.at[1], report.at[2]],
-                effect: report.effect,
-                hit: report.hit,
-            });
-        },
-    }), ["fireProjectile", "settleProjectile"], signal.notify);
-    const objectSelection = notifyAfter(createSelectionSet(), ["add", "remove", "toggle", "replace", "clear"], signal.notify);
-    const sceneObjects = {
-        ...objects,
-        remove(instanceId) {
-            const existed = objects.remove(instanceId);
-            if (existed)
-                objectSelection.remove(instanceId);
-            return existed;
-        },
-        catalog: (instanceId) => catalogObject(instanceId) ?? null,
-        raycast: (input) => raycastObjects(objects, input),
-        raycastAll: (input) => raycastObjectsAll(objects, input),
-        setColliders(instanceId, colliders) {
-            if (colliders === null)
-                objectColliders.delete(instanceId);
-            else
-                objectColliders.set(instanceId, colliders);
-            signal.notify();
+        objectCollidersOf,
+        catalogEntry,
+        statsByInstance,
+        weapon,
+        loot,
+        lootRegistry,
+        spawnWorldItem,
+        despawnEntity,
+        runCommand(name, args) {
+            if (ctxRef === null)
+                return;
+            commandRegistry.run(ctxRef, name, args);
         },
-        collidersOf: objectCollidersOf,
-        selection: objectSelection,
-    };
+        localUserId: player.userId,
+        ...(definition.physics !== undefined ? { physics: definition.physics } : {}),
+    });
+    scene.setOnAfterSpawn((instanceId) => combat.death.revive(instanceId));
+    const { projectiles, combatFx, vfxInstances, effects } = combat;
     const store = notifyAfter(createObservableKeyedStore(), ["set", "delete", "hydrate"], signal.notify);
     const { pile, loop, raceState, cardPiles, turnLoops } = createContextRegistries(signal.notify);
     const camera = notifyAfter(createCameraDirector(), ["follow", "setCinematic", "setChaseTuning"], signal.notify);
     const input = createInputSnapshot();
-    const motionByUser = new Map();
-    function motionFor(userId) {
-        let queue = motionByUser.get(userId);
-        if (queue === undefined) {
-            queue = createMotionIntents();
-            motionByUser.set(userId, queue);
-        }
-        return queue;
-    }
+    // --- Descriptor install (single feature enable path) ---
     const featureDeps = {
         features,
         signalNotify: signal.notify,
@@ -614,6 +251,12 @@ export function createGameContext(options) {
         if (build.save !== undefined)
             featureSaveModules.push(build.save);
     }
+    const gameFeatureBlock = {};
+    for (const descriptor of featureDescriptors) {
+        if (descriptor.key === "cosmetics")
+            continue;
+        gameFeatureBlock[descriptor.key] = featureRegistry.get(descriptor.key);
+    }
     const baselineDeps = {
         signalNotify: signal.notify,
         entities,
@@ -638,15 +281,16 @@ export function createGameContext(options) {
     const replication = options.replication;
     const projectsViewers = policyProjectsViewers(replication);
     const aoiRadius = replication?.aoiRadius;
+    const typedProject = (project) => (data, viewer, world) => project(data, viewer, world);
     const projectorFor = (key) => {
         if (aoiRadius !== undefined && key === "entities") {
-            return (data, viewer) => projectEntitiesForViewer(data, viewer, aoiRadius);
+            return typedProject((data, viewer) => projectEntitiesForViewer(data, viewer, aoiRadius));
         }
         if (aoiRadius !== undefined && key === "stats") {
-            return (data, viewer, world) => projectByVisibleIds(data, visibleEntityIds((world["entities"] ?? []), viewer, aoiRadius));
+            return typedProject((data, viewer, world) => projectByVisibleIds(data, visibleEntityIds((world["entities"] ?? []), viewer, aoiRadius)));
         }
         if (replication?.privatePerUser === true && key === "inventory") {
-            return (data, viewer) => projectPerUserForViewer(data, viewer);
+            return typedProject((data, viewer) => projectPerUserForViewer(data, viewer));
         }
         return undefined;
     };
@@ -659,17 +303,6 @@ export function createGameContext(options) {
         };
     });
     const replicationVersion = () => replicationModules.reduce((sum, module) => sum + (module.version?.() ?? 0), 0);
-    /**
-     * The whole-world *save* set is a superset of the *replication* set (`snapshotModules`): it adds the
-     * always-on baseline subsystems (economy, time, pose, possession, motion) plus every opted-in
-     * feature's `save` module (unlocks, roster, quest, cosmetics, cards, turn) — the persistent state a
-     * single-player save must restore but a host does not replicate to clients. Coverage is owned per
-     * subsystem, not hand-listed against a drifting feature manifest: each feature descriptor emits its
-     * own `save`, so a new persistent feature can't silently fall out of the save. Keeping the two sets
-     * distinct leaves `ctx.snapshot()`/`ctx.hydrate()` — the host→client payload — byte-identical for
-     * every multiplayer game, while `ctx.game.save` still persists everything.
-     * Mutable so game systems can register save modules at install time via `ctx.game.registerSave`.
-     */
     const saveModules = [
         ...snapshotModules,
         ...baselineBuilds.flatMap((build) => (build.save === undefined ? [] : [build.save])),
@@ -687,6 +320,7 @@ export function createGameContext(options) {
         });
         saveModules.push(module);
     }
+    // --- Assemble public GameContext ---
     const ctx = {
         scene: {
             object: sceneObjects,
@@ -705,17 +339,17 @@ export function createGameContext(options) {
                 resetAllToSpawn,
                 blackboard: entities.blackboard,
                 stats: entityStats,
-                floatText: emitFloatText,
-                vfx: emitVfx,
+                floatText: combatFx.emitFloatText,
+                vfx: combatFx.emitVfx,
                 vfxInstance: vfxInstances,
-                telegraph: fireTelegraph,
-                hitReaction: applyHitReaction,
+                telegraph: combatFx.fireTelegraph,
+                hitReaction: combatFx.applyHitReaction,
                 setTarget: targeting.setTarget,
                 getTarget: targeting.getTarget,
                 cycleTarget: targeting.cycleTarget,
                 canReceive: effects.canReceive,
                 preview: effects.preview,
-                effect: applyEffectAndFloat,
+                effect: combatFx.applyEffectAndFloat,
                 willHitProjectile: projectiles.willHitProjectile,
                 fireProjectile: projectiles.fireProjectile,
                 settleProjectile: projectiles.settleProjectile,
@@ -734,6 +368,7 @@ export function createGameContext(options) {
                     signal.notify();
                 },
                 collidersOf: entityCollidersOf,
+                reportBounds: reportEntityBounds,
                 visualScaleOf: entityVisualScaleOf,
                 form: forms,
                 paint: paintLayer,
@@ -784,6 +419,9 @@ export function createGameContext(options) {
                 play: (sound, at) => events.emit("audio.play", at === undefined ? { sound } : { sound, at }),
                 music: (theme, transpose) => events.emit("audio.music", transpose === undefined ? { theme } : { theme, transpose }),
                 resume: () => events.emit("audio.resume", {}),
+                loop: (id, sound, options) => events.emit("audio.loopStart", options?.at === undefined ? { id, sound } : { id, sound, at: options.at }),
+                setLoop: (id, params) => events.emit("audio.loopSet", { id, ...params }),
+                stopLoop: (id) => events.emit("audio.loopStop", { id }),
             },
             feed: {
                 bind: (action) => feed.bind(action, events),
@@ -800,20 +438,9 @@ export function createGameContext(options) {
                 },
             },
             loot,
-            trade: featureValue("trade"),
-            quest: featureValue("quest"),
-            social: featureValue("social"),
-            chat: featureValue("chat"),
-            unlocks: featureValue("unlocks"),
             economy,
-            leaderboard: featureValue("leaderboard"),
-            roster: featureValue("roster"),
             store,
-            dialogue: featureValue("dialogue"),
-            cards: featureValue("cards"),
-            turn: featureValue("turn"),
-            race: featureValue("race"),
-            players: featureValue("players"),
+            ...gameFeatureBlock,
             registerSave,
             registerReplicate,
         },
@@ -867,6 +494,7 @@ export function createGameContext(options) {
         replicationVersion,
         replicatesPerViewer: () => projectsViewers,
     };
+    ctxRef = ctx;
     const saveOptions = resolveSaveOptions(definition, options);
     if (saveOptions !== undefined) {
         const saveTarget = {
@@ -885,16 +513,21 @@ function saveKey(name) {
     const slug = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
     return `jgengine:save:${slug === "" ? "game" : slug}`;
 }
-/** Explicit `options.save` wins (the shell can inject any backend, e.g. cloud); otherwise `defineGame({ persist })` auto-wires a localStorage save for offline/single-player worlds only. */
+/**
+ * Explicit `options.save` wins (the shell can inject any backend, e.g. cloud); otherwise an offline /
+ * single-player world auto-wires a `localStorage` whole-world save **by default** — a game gets `ctx.game.save`
+ * and autosave without touching `persist`. Only an explicit `persist: false` opts out; a host-authoritative
+ * multiplayer world never persists to `localStorage` (its host owns persistence) regardless of `persist`.
+ */
 function resolveSaveOptions(definition, options) {
     if (options.save !== undefined)
         return options.save;
     const persist = definition.persist;
-    if (persist === undefined || persist === false)
+    if (persist === false)
         return undefined;
     if (!isOffline(definition.multiplayer))
         return undefined;
-    const config = persist === true ? {} : persist;
+    const config = persist === undefined || persist === true ? {} : persist;
     return {
         backend: config.storage === "memory" ? memorySaveBackend() : localSaveBackend(),
         mode: config.mode,