@jgengine/core 0.10.0 → 0.12.0

package/dist/runtime/gameContext.js

@@ -1,50 +1,32 @@
-import { createCardPile } 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 { resolveHitReaction, } from "../combat/hitReaction.js";
-import { pointInTelegraph, } from "../combat/telegraph.js";
-import { createCommandRegistry, } from "../commands/commandRegistry.js";
-import { balance as walletBalance, canAfford as walletCanAfford, charge as walletCharge, chargeAll as walletChargeAll, createEmptyWallet, grant as walletGrant, } from "../economy/wallet.js";
-import { createCosmetics } from "../game/cosmetics.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 { createGameFeed } from "../game/feed.js";
-import { createLeaderboard } from "../game/leaderboard.js";
-import { createLoadouts } from "../game/loadout.js";
+import { setGamePhase } from "../game/gamePhase.js";
 import { createLootRegistry, grantDrops } from "../game/lootTable.js";
-import { createQuestJournal } from "../game/quest.js";
-import { createWorldItemStore, resolveDeathDrops, DEFAULT_RARITY, WORLD_ITEM_ENTITY_NAME, } from "../game/worldItem.js";
-import { createChat } from "../game/chat.js";
 import { createSocial } from "../game/social.js";
-import { createTradeSystem } from "../game/trade.js";
-import { createUnlocks } from "../game/unlocks.js";
-import { createInventorySet, putItem, } from "../inventory/inventoryModel.js";
-import { createItemUse, } from "../item/use.js";
+import { createItemUse } from "../item/use.js";
 import { createWeaponStats } from "../item/weapon.js";
-import { createPoseState } from "../movement/poseState.js";
-import { createPaintLayer } from "../scene/paintLayer.js";
-import { createEntityStatsApi, hydrateEntityStats, seedStatValues, setStatValue, snapshotEntityStats, } from "../scene/entityStats.js";
-import { createForms } from "../scene/form.js";
-import { scaledObjectColliders } from "../scene/colliders.js";
-import { raycastObjects, raycastObjectsAll } from "../scene/objectQuery.js";
-import { createObjectStore, objectVisualScale } from "../scene/objectStore.js";
-import { createRoster } from "../scene/roster.js";
-import { createConnectedPlayers } 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";
+import { policyProjectsViewers, projectByVisibleIds, projectEntitiesForViewer, projectPerUserForViewer, visibleEntityIds, } from "./worldProjection.js";
+import { createRuntimeSave } from "./runtimeSave.js";
+import { isOffline } from "./adapter.js";
+import { localSaveBackend, memorySaveBackend } from "../game/saveStore.js";
 import { createSimClock } from "../time/simClock.js";
-import { createTurnLoop } 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 { 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;
     const now = options.now ?? Date.now;
@@ -54,122 +36,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 = definition.scene;
-    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;
-        return catalogEntry(instanceId)?.colliders ?? null;
-    }
-    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,
@@ -179,105 +45,75 @@ 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, 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();
-    const unlocks = notifyAfter(createUnlocks(), ["grant", "hydrate"], signal.notify);
+    /**
+     * 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 rawSocial = features.social || features.chat
-        ? createSocial({
-            events,
-            now,
-            emotes: {
-                entities: { get: (id) => entities.get(id) },
-                spatial: { inRadius: (center, radius, filter) => spatial.inRadius(center, radius, filter) },
+    const featureRegistry = new Map();
+    const featureValue = (key) => featureRegistry.get(key);
+    let rawSocial = null;
+    const sharedSocial = () => {
+        if (rawSocial === null) {
+            rawSocial = createSocial({
+                events,
+                now,
+                emotes: {
+                    entities: { get: (id) => entities.get(id) },
+                    spatial: { inRadius: (center, radius, filter) => spatial.inRadius(center, radius, filter) },
+                },
+            });
+        }
+        return rawSocial;
+    };
+    const commandRegistry = createCommandRegistry();
+    if (definition.lifecycle !== undefined) {
+        const lifecycle = definition.lifecycle;
+        commandRegistry.define(lifecycle.commands?.start ?? "start", {
+            apply(state, input) {
+                const next = lifecycle.start(lifecycle.store.read(state), state, input);
+                lifecycle.store.write(state, next);
+                setGamePhase(state, lifecycle.phaseOf(next));
             },
-        })
-        : null;
-    let social;
-    if (features.social && rawSocial !== null) {
-        social = {
-            friends: notifyAfter(rawSocial.friends, ["request", "accept", "decline", "remove", "block", "hydrate"], signal.notify),
-            party: notifyAfter(rawSocial.party, ["invite", "accept", "decline", "kick", "leave", "promote"], signal.notify),
-            presence: rawSocial.presence,
-            emotes: rawSocial.emotes,
-            worldInvites: notifyAfter(rawSocial.worldInvites, ["invite", "accept", "decline"], signal.notify),
-        };
-    }
-    let chat;
-    if (features.chat && rawSocial !== null) {
-        chat = notifyAfter(createChat({
-            events,
-            now,
-            party: rawSocial.party,
-            proximity: {
-                entities: { get: (id) => entities.get(id) },
-                spatial: { inRadius: (center, radius, filter) => spatial.inRadius(center, radius, filter) },
+        });
+        commandRegistry.define(lifecycle.commands?.restart ?? "restart", {
+            apply(state) {
+                const next = lifecycle.restart(lifecycle.store.read(state), state);
+                lifecycle.store.write(state, next);
+                setGamePhase(state, lifecycle.phaseOf(next));
             },
-            blockedBy: (userId) => rawSocial.friends.snapshot(userId).blocked,
-        }), ["register", "send", "whisper", "hydrate"], signal.notify);
-    }
-    const leaderboard = features.leaderboard
-        ? notifyAfter(createLeaderboard(), ["increment", "hydrate"], signal.notify)
-        : undefined;
-    const roster = features.roster
-        ? notifyAfter(createRoster({ now }), ["capture", "release", "setEquipped", "hydrate"], signal.notify)
-        : undefined;
-    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();
     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 cosmetics = notifyAfter(createCosmetics({ events }), ["apply", "equip", "hydrate"], 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();
-        },
-        charge(userId, currencyId, amount) {
-            const result = walletCharge(walletOf(userId), currencyId, amount);
-            if (result.status === "rejected")
-                return { reason: result.reason };
-            wallets.set(userId, result.state);
-            signal.notify();
-            return null;
-        },
-    };
-    function putIntoAnyInventory(userId, itemId, count) {
-        const inventory = inventoryFor(userId);
-        for (const inventoryId of inventoryIds) {
-            if (inventory.put(inventoryId, itemId, count).status === "ok")
-                return;
-        }
-    }
+    // --- 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));
     const loot = {
         register: lootRegistry.register,
         has: lootRegistry.has,
@@ -293,540 +129,158 @@ export function createGameContext(options) {
             events.emit("loot.granted", event);
         },
     };
-    const trade = createTradeSystem({
-        resolveTrade: (itemId) => content.itemById?.(itemId)?.trade,
-        wallet: {
-            canAfford: (costs) => (walletCanAfford(walletOf(activeUserId()), costs) ? null : "insufficient-funds"),
-            charge(costs) {
-                const result = walletChargeAll(walletOf(activeUserId()), costs);
-                if (result.status === "ok") {
-                    wallets.set(activeUserId(), result.state);
-                    signal.notify();
-                }
-            },
-            grant(gains) {
-                for (const [currencyId, amount] of Object.entries(gains)) {
-                    economy.grant(activeUserId(), currencyId, amount);
-                }
-            },
-        },
-        inventory: {
-            put(inventoryId, itemId, count) {
-                if (layouts[inventoryId] === undefined)
-                    return { reason: `unknown inventory "${inventoryId}"` };
-                const result = inventoryFor(activeUserId()).put(inventoryId, itemId, count);
-                return result.status === "ok" ? null : { reason: result.reason };
-            },
-            take(inventoryId, itemId, count) {
-                if (layouts[inventoryId] === undefined)
-                    return { reason: `unknown inventory "${inventoryId}"` };
-                const result = inventoryFor(activeUserId()).take(inventoryId, itemId, count);
-                return result.status === "ok" ? null : { reason: result.reason };
-            },
-            count: (inventoryId, itemId) => inventoryFor(activeUserId()).count(inventoryId, itemId),
-        },
-    });
-    function seedUserPool(userId, statId, pool) {
-        const map = ensureInstanceStats(userId);
-        const next = setStatValue(map, statId, pool);
-        map[statId] = next[statId];
-    }
-    const rawQuest = createQuestJournal({
+    const { worldItems, spawnWorldItem, pickupWorldItem } = createWorldItemContext({
+        entities,
         events,
-        rewards: {
-            grantXp(userId, amount) {
-                const existing = ensureInstanceStats(userId)["xp"];
-                const current = (existing?.current ?? 0) + amount;
-                seedUserPool(userId, "xp", { current, max: Math.max(existing?.max ?? 0, current) });
-            },
-            grantEconomy: (userId, currencyId, amount) => economy.grant(userId, currencyId, amount),
-            grantItem(userId, inventoryId, itemId, count) {
-                if (layouts[inventoryId] === undefined)
-                    return { reason: `unknown inventory "${inventoryId}"` };
-                const result = inventoryFor(userId).put(inventoryId, itemId, count);
-                return result.status === "ok" ? null : { reason: result.reason };
-            },
-            grantUnlock: (userId, unlockId) => unlocks.grant(userId, unlockId),
-        },
-        hasUnlock: (userId, id) => unlocks.has(userId, id),
-    });
-    const quest = notifyAfter(rawQuest, ["accept", "abandon", "progress", "turnIn", "grant", "revoke", "hydrate"], signal.notify);
-    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: unlocks.grant },
-    }), ["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 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 worldItems = notifyAfter(createWorldItemStore({
-        spawnEntity: (position) => entities.spawn(WORLD_ITEM_ENTITY_NAME, { position, role: "prop" }),
         despawnEntity,
-        resolvePosition: (instanceId) => entities.get(instanceId)?.position,
-    }), ["spawn", "take", "remove"], signal.notify);
-    function spawnWorldItem(input) {
-        const record = worldItems.spawn(input);
-        events.emit("worldItem.dropped", {
-            instanceId: record.instanceId,
-            itemId: record.itemId,
-            rarity: record.rarity,
-            count: record.count,
-            position: [input.position[0], input.position[1], input.position[2]],
-            ...(record.source !== undefined ? { source: record.source } : {}),
-        });
-        return record;
-    }
-    function pickupWorldItem(instanceId, userId) {
-        const record = worldItems.take(instanceId);
-        if (record === null)
-            return { status: "rejected", reason: "not-found" };
-        loot.grantToPlayer(userId, [{ item: record.itemId, count: record.count }], "worldItem.pickup");
-        events.emit("worldItem.picked_up", {
-            instanceId,
-            userId,
-            itemId: record.itemId,
-            rarity: record.rarity,
-            count: record.count,
-        });
-        return { status: "ok", record };
-    }
-    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) : []) },
+        grantToPlayer: loot.grantToPlayer,
+        signalNotify: signal.notify,
+    });
+    // --- 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,
+        entities,
+        objects,
+        combatSpatial,
+        sceneRaycast,
+        entityCollidersOf,
+        objectCollidersOf,
+        catalogEntry,
+        statsByInstance,
+        weapon,
+        loot,
+        lootRegistry,
+        spawnWorldItem,
+        despawnEntity,
         runCommand(name, args) {
-            commandRegistry.run(ctx, name, args);
-        },
-        despawn(instanceId) {
-            despawnEntity(instanceId);
+            if (ctxRef === null)
+                return;
+            commandRegistry.run(ctxRef, name, args);
         },
+        localUserId: player.userId,
+        ...(definition.physics !== undefined ? { physics: definition.physics } : {}),
     });
-    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);
-    function emitFloatText(input) {
-        const position = input.position ??
-            (input.instanceId === undefined ? undefined : entities.get(input.instanceId)?.position);
-        if (position === undefined)
-            return;
-        const text = input.text ?? (input.amount === undefined ? "" : String(Math.round(input.amount)));
-        const event = {
-            position: [position[0], position[1], position[2]],
-            text,
-            kind: input.kind ?? "info",
-        };
-        if (input.instanceId !== undefined)
-            event.instanceId = input.instanceId;
-        if (input.amount !== undefined)
-            event.amount = input.amount;
-        if (input.hitType !== undefined)
-            event.hitType = input.hitType;
-        if (input.element !== undefined)
-            event.element = input.element;
-        if (input.crit !== undefined)
-            event.crit = input.crit;
-        if (input.scale !== undefined)
-            event.scale = input.scale;
-        events.emit("entity.floatText", event);
-    }
-    let telegraphSeq = 0;
-    function fireTelegraph(input) {
-        const id = telegraphSeq++;
-        const telegraphEvent = {
-            id,
-            shape: input.shape,
-            position: [input.at[0], input.at[1], input.at[2]],
-            windupMs: input.windupMs,
-            kind: input.kind ?? "danger",
-        };
-        if (input.dir !== undefined)
-            telegraphEvent.dir = input.dir;
-        events.emit("combat.telegraph", telegraphEvent);
-        const cancelVisual = () => events.emit("combat.telegraphCancelled", { id });
-        const bound = input.effect;
-        if (bound === undefined)
-            return cancelVisual;
-        const config = { shape: input.shape, at: input.at, windupMs: input.windupMs };
-        if (input.dir !== undefined)
-            config.dir = input.dir;
-        const cancelEffect = time.after(input.windupMs / 1000, () => {
-            const targets = entities.list().filter((entity) => pointInTelegraph(config, entity.position));
-            for (const target of targets) {
-                applyEffectAndFloat({
-                    from: input.from,
-                    to: target.id,
-                    effect: bound.effect,
-                    ...(bound.via === undefined ? {} : { via: bound.via }),
-                });
-            }
-        });
-        return () => {
-            cancelEffect();
-            cancelVisual();
-        };
-    }
-    function applyHitReaction(input) {
-        const attacker = entities.get(input.from);
-        const target = entities.get(input.to);
-        if (target === null)
-            return null;
-        const attackerPos = attacker?.position ?? target.position;
-        const reaction = resolveHitReaction(input.config, {
-            attackerPos,
-            targetPos: target.position,
-            ...(input.power === undefined ? {} : { power: input.power }),
-        });
-        entities.setPose(input.to, {
-            position: [
-                target.position[0] + reaction.impulse[0],
-                target.position[1] + reaction.impulse[1],
-                target.position[2] + reaction.impulse[2],
-            ],
-            rotationY: target.rotationY,
-        });
-        const reactionEvent = {
-            instanceId: input.to,
-            position: [target.position[0], target.position[1], target.position[2]],
-            hitstopMs: reaction.hitstopMs,
-        };
-        if (reaction.shake !== null)
-            reactionEvent.shake = reaction.shake;
-        events.emit("combat.hitReaction", reactionEvent);
-        return reaction;
-    }
-    function applyEffectAndFloat(input) {
-        const positionsBefore = new Map();
-        for (const entity of entities.list())
-            positionsBefore.set(entity.id, entity.position);
-        const results = effects.applyEffect(input);
-        for (const result of results) {
-            let total = 0;
-            for (const delta of result.applied)
-                total += delta.delta;
-            if (total === 0)
-                continue;
-            const position = entities.get(result.instanceId)?.position ?? positionsBefore.get(result.instanceId);
-            if (position === undefined)
-                continue;
-            const magnitude = Math.abs(total);
-            emitFloatText({
-                instanceId: result.instanceId,
-                position: [position[0], position[1], position[2]],
-                text: String(Math.round(magnitude)),
-                kind: total < 0 ? "damage" : "heal",
-                amount: magnitude,
-            });
-        }
-        return results;
-    }
-    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,
-        entityCollidersOf,
-        rotationYOf: (instanceId) => entities.get(instanceId)?.rotationY,
+    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();
+    // --- Descriptor install (single feature enable path) ---
+    const featureDeps = {
+        features,
+        signalNotify: signal.notify,
+        events,
         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 sceneObjects = {
-        ...objects,
-        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();
-        },
-        collidersOf: objectCollidersOf,
+        entities,
+        spatial,
+        store,
+        commandRegistry,
+        economy,
+        content,
+        activeUserId,
+        walletOf,
+        setWallet: (userId, state) => wallets.set(userId, state),
+        layouts,
+        inventoryFor,
+        ensureInstanceStats,
+        seedUserPool,
+        sharedSocial,
+        pile,
+        loop,
+        cardPiles,
+        turnLoops,
+        raceState,
+        feature: featureValue,
     };
-    const store = notifyAfter(createObservableKeyedStore(), ["set", "delete", "hydrate"], signal.notify);
-    const players = features.players
-        ? notifyAfter(createConnectedPlayers(), ["join", "leave"], signal.notify)
-        : undefined;
-    const cardPiles = new Map();
-    function pile(id, config) {
-        const existing = cardPiles.get(id);
-        if (existing !== undefined)
-            return existing;
-        if (config === undefined) {
-            throw new Error(`cardPile "${id}" has not been created yet; pass a config on first access`);
-        }
-        const created = notifyAfter(createCardPile(config), ["shuffle", "draw", "discard", "exhaust", "move", "reset"], signal.notify);
-        cardPiles.set(id, created);
-        return created;
+    const featureReplicateModules = [];
+    const featureSaveModules = [];
+    for (const descriptor of featureDescriptors) {
+        if (!descriptor.enabled(features))
+            continue;
+        const build = descriptor.create(featureDeps);
+        featureRegistry.set(descriptor.key, build.value);
+        if (build.replicate !== undefined)
+            featureReplicateModules.push(build.replicate);
+        if (build.save !== undefined)
+            featureSaveModules.push(build.save);
     }
-    const turnLoops = new Map();
-    function loop(id, config) {
-        const existing = turnLoops.get(id);
-        if (existing !== undefined)
-            return existing;
-        if (config === undefined) {
-            throw new Error(`turn loop "${id}" has not been created yet; pass a config on first access`);
-        }
-        const raw = createTurnLoop(config);
-        const wrappedCommit = notifyAfter(raw.commit, ["submit", "expected", "commit", "discard", "clear"], signal.notify);
-        const wrapped = {
-            ...notifyAfter(raw, [
-                "setOrder",
-                "addParticipant",
-                "removeParticipant",
-                "advancePhase",
-                "advanceTurn",
-                "advanceRound",
-                "spend",
-                "gain",
-                "refill",
-                "restore",
-            ], signal.notify),
-            commit: wrappedCommit,
-        };
-        turnLoops.set(id, wrapped);
-        return wrapped;
+    const gameFeatureBlock = {};
+    for (const descriptor of featureDescriptors) {
+        if (descriptor.key === "cosmetics")
+            continue;
+        gameFeatureBlock[descriptor.key] = featureRegistry.get(descriptor.key);
     }
-    class NotifyingRaceState extends RaceState {
-        addRacer(racerId, startTime) {
-            super.addRacer(racerId, startTime);
-            signal.notify();
-        }
-        removeRacer(racerId) {
-            super.removeRacer(racerId);
-            signal.notify();
-        }
-        reset() {
-            super.reset();
-            signal.notify();
-        }
-        eliminate(racerId) {
-            super.eliminate(racerId);
-            signal.notify();
-        }
-        update(now, positions) {
-            const raceEvents = super.update(now, positions);
-            if (raceEvents.length > 0)
-                signal.notify();
-            return raceEvents;
+    const baselineDeps = {
+        signalNotify: signal.notify,
+        entities,
+        statsByInstance,
+        store,
+        feed,
+        inventoryIds,
+        inventoryByUser,
+        inventoryFor,
+        wallets,
+        time,
+        pose,
+        possession,
+        motionByUser,
+        motionFor,
+    };
+    const baselineBuilds = baselineDescriptors.map((descriptor) => descriptor.create(baselineDeps));
+    const snapshotModules = [
+        ...baselineBuilds.flatMap((build) => (build.replicate === undefined ? [] : [build.replicate])),
+        ...featureReplicateModules,
+    ];
+    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 typedProject((data, viewer) => projectEntitiesForViewer(data, viewer, aoiRadius));
         }
-    }
-    const raceStates = new Map();
-    function raceState(id, config) {
-        const existing = raceStates.get(id);
-        if (existing !== undefined)
-            return existing;
-        if (config === undefined) {
-            throw new Error(`race "${id}" has not been created yet; pass a config on first access`);
+        if (aoiRadius !== undefined && key === "stats") {
+            return typedProject((data, viewer, world) => projectByVisibleIds(data, visibleEntityIds((world["entities"] ?? []), viewer, aoiRadius)));
         }
-        const created = new NotifyingRaceState(config);
-        raceStates.set(id, created);
-        return created;
-    }
-    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);
+        if (replication?.privatePerUser === true && key === "inventory") {
+            return typedProject((data, viewer) => projectPerUserForViewer(data, viewer));
         }
-        return queue;
-    }
-    const snapshotModules = [
-        { key: "entities", snapshot: () => entities.snapshot(), hydrate: (data) => entities.hydrate(data) },
-        {
-            key: "stats",
-            snapshot: () => snapshotEntityStats(statsByInstance),
-            hydrate: (data) => hydrateEntityStats(statsByInstance, data),
-        },
-        {
-            key: "store",
-            snapshot: () => store.snapshot(),
-            hydrate: (data) => store.hydrate(data),
-        },
-        { key: "feed", snapshot: () => feed.snapshot(), hydrate: (data) => feed.hydrate(data) },
-        {
-            key: "inventory",
-            snapshot: () => {
-                const byUser = {};
-                for (const [userId, set] of inventoryByUser) {
-                    const states = {};
-                    for (const inventoryId of inventoryIds)
-                        states[inventoryId] = set.state(inventoryId);
-                    byUser[userId] = states;
-                }
-                return byUser;
-            },
-            hydrate: (data) => {
-                for (const [userId, states] of Object.entries(data)) {
-                    const set = inventoryFor(userId);
-                    for (const [inventoryId, state] of Object.entries(states))
-                        set.replaceState(inventoryId, state);
-                }
-            },
-        },
+        return undefined;
+    };
+    const replicationModules = snapshotModules.map((module) => {
+        const project = projectorFor(module.key);
+        return {
+            ...module,
+            version: () => signal.version(),
+            ...(project === undefined ? {} : { project }),
+        };
+    });
+    const replicationVersion = () => replicationModules.reduce((sum, module) => sum + (module.version?.() ?? 0), 0);
+    const saveModules = [
+        ...snapshotModules,
+        ...baselineBuilds.flatMap((build) => (build.save === undefined ? [] : [build.save])),
+        ...featureSaveModules,
     ];
-    if (leaderboard) {
-        snapshotModules.push({
-            key: "leaderboard",
-            snapshot: () => leaderboard.snapshot(),
-            hydrate: (data) => leaderboard.hydrate(data),
-        });
+    function registerSave(module) {
+        saveModules.push(module);
     }
-    if (chat) {
-        snapshotModules.push({
-            key: "chat",
-            snapshot: () => chat.snapshot(),
-            hydrate: (data) => chat.hydrate(data),
+    function registerReplicate(module) {
+        const project = projectorFor(module.key);
+        replicationModules.push({
+            ...module,
+            version: () => signal.version(),
+            ...(project === undefined ? {} : { project }),
         });
+        saveModules.push(module);
     }
+    // --- Assemble public GameContext ---
     const ctx = {
         scene: {
             object: sceneObjects,
@@ -838,20 +292,24 @@ export function createGameContext(options) {
                 setPoseConstraint: entities.setPoseConstraint,
                 get: entities.get,
                 list: entities.list,
+                ids: entities.ids,
+                subscribeMembership: entities.subscribeMembership,
                 spawnPoseOf: entities.spawnPoseOf,
                 resetToSpawn: entities.resetToSpawn,
                 resetAllToSpawn,
                 blackboard: entities.blackboard,
                 stats: entityStats,
-                floatText: emitFloatText,
-                telegraph: fireTelegraph,
-                hitReaction: applyHitReaction,
+                floatText: combatFx.emitFloatText,
+                vfx: combatFx.emitVfx,
+                vfxInstance: vfxInstances,
+                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,
@@ -860,6 +318,7 @@ export function createGameContext(options) {
                 hasLineOfSight: spatial.hasLineOfSight,
                 queryArc: spatial.queryArc,
                 moveToward: spatial.moveToward,
+                moveTowardCommit: moveEntityTowardCommit,
                 invalidateSpatial: spatial.invalidate,
                 setColliders(instanceId, colliders) {
                     if (colliders === null)
@@ -869,8 +328,10 @@ export function createGameContext(options) {
                     signal.notify();
                 },
                 collidersOf: entityCollidersOf,
+                visualScaleOf: entityVisualScaleOf,
                 form: forms,
                 paint: paintLayer,
+                bind,
             },
             worldItem: {
                 spawn: spawnWorldItem,
@@ -917,6 +378,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),
@@ -933,19 +397,11 @@ export function createGameContext(options) {
                 },
             },
             loot,
-            trade,
-            quest,
-            social,
-            chat,
-            unlocks,
             economy,
-            leaderboard,
-            roster,
             store,
-            cards: features.cards ? { pile } : undefined,
-            turn: features.turn ? { loop } : undefined,
-            race: features.race ? { state: raceState } : undefined,
-            players,
+            ...gameFeatureBlock,
+            registerSave,
+            registerReplicate,
         },
         player: {
             get userId() {
@@ -964,7 +420,7 @@ export function createGameContext(options) {
             applyLoadout: loadouts.applyLoadout,
             movement: pose,
             possession,
-            cosmetics,
+            cosmetics: featureValue("cosmetics"),
             get motion() {
                 return motionFor(activeUserId());
             },
@@ -988,11 +444,50 @@ export function createGameContext(options) {
         input,
         subscribe: signal.subscribe,
         version: signal.version,
-        snapshot: () => composeWorldSnapshot(snapshotModules),
+        touch: signal.notify,
+        snapshot: (viewer) => composeWorldSnapshot(replicationModules, viewer),
         hydrate(snapshot) {
-            applyWorldSnapshot(snapshotModules, snapshot);
+            applyWorldSnapshot(replicationModules, snapshot);
             signal.notify();
         },
+        replicationVersion,
+        replicatesPerViewer: () => projectsViewers,
     };
+    ctxRef = ctx;
+    const saveOptions = resolveSaveOptions(definition, options);
+    if (saveOptions !== undefined) {
+        const saveTarget = {
+            snapshot: () => composeWorldSnapshot(saveModules),
+            hydrate: (snapshot) => {
+                applyWorldSnapshot(saveModules, snapshot);
+                signal.notify();
+            },
+            subscribe: signal.subscribe,
+        };
+        ctx.game.save = createRuntimeSave({ target: saveTarget, ...saveOptions });
+    }
     return ctx;
 }
+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. */
+function resolveSaveOptions(definition, options) {
+    if (options.save !== undefined)
+        return options.save;
+    const persist = definition.persist;
+    if (persist === undefined || persist === false)
+        return undefined;
+    if (!isOffline(definition.multiplayer))
+        return undefined;
+    const config = persist === true ? {} : persist;
+    return {
+        backend: config.storage === "memory" ? memorySaveBackend() : localSaveBackend(),
+        mode: config.mode,
+        key: saveKey(definition.name),
+        version: config.version,
+        autosaveMs: config.autosaveMs,
+        now: options.now,
+    };
+}