@jgengine/core 0.10.0 → 0.11.0

package/dist/runtime/gameContext.js

@@ -1,36 +1,42 @@
-import { createCardPile } from "../cards/cardPile.js";
+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 { resolveHitReaction, } from "../combat/hitReaction.js";
-import { pointInTelegraph, } from "../combat/telegraph.js";
+import {} from "../combat/hitReaction.js";
+import {} 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 { balance as walletBalance, charge as walletCharge, createEmptyWallet, grant as walletGrant, isOverdrawn as walletIsOverdrawn, } from "../economy/wallet.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 { createLeaderboard } from "../game/leaderboard.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 { 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 {} 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 { createTradeSystem } from "../game/trade.js";
-import { createUnlocks } from "../game/unlocks.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 { 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, hydrateEntityStats, seedStatValues, setStatValue, snapshotEntityStats, } from "../scene/entityStats.js";
+import { createEntityStatsApi, seedStatValues, setStatValue, } from "../scene/entityStats.js";
+import { createEntityStore, } from "../scene/entityStore.js";
 import { createForms } from "../scene/form.js";
-import { scaledObjectColliders } from "../scene/colliders.js";
+import { scaledEntityColliders, 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 {} 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";
@@ -39,12 +45,21 @@ import { createStats } from "../stats/statModifiers.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 {} 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 { createContextRegistries } from "./context/registries.js";
+import { createWorldItemContext } from "./context/worldItems.js";
 export function createGameContext(options) {
     const { definition, content, player } = options;
     const now = options.now ?? Date.now;
@@ -54,7 +69,7 @@ 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 entities = createEntityStore();
     const objects = createObjectStore();
     entities.subscribe(signal.notify);
     objects.subscribe(signal.notify);
@@ -106,7 +121,16 @@ export function createGameContext(options) {
         const override = entityColliders.get(instanceId);
         if (override !== undefined)
             return override;
-        return catalogEntry(instanceId)?.colliders ?? null;
+        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);
@@ -181,47 +205,23 @@ export function createGameContext(options) {
     };
     const feed = createGameFeed(definition.feed);
     const lootRegistry = createLootRegistry();
-    const unlocks = notifyAfter(createUnlocks(), ["grant", "hydrate"], signal.notify);
     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) },
-            },
-        })
-        : 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) },
-            },
-            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 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 playerStatsByUser = new Map();
     function playerStatsFor(userId) {
         let stats = playerStatsByUser.get(userId);
@@ -233,10 +233,26 @@ export function createGameContext(options) {
     }
     const pose = createPoseState((instanceId) => catalogEntry(instanceId)?.movement);
     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));
+            },
+        });
+        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));
+            },
+        });
+    }
     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);
@@ -262,14 +278,15 @@ export function createGameContext(options) {
             wallets.set(userId, walletGrant(walletOf(userId), currencyId, amount));
             signal.notify();
         },
-        charge(userId, currencyId, amount) {
-            const result = walletCharge(walletOf(userId), currencyId, amount);
+        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();
             return null;
         },
+        isOverdrawn: (userId, currencyId) => walletIsOverdrawn(walletOf(userId), currencyId),
     };
     function putIntoAnyInventory(userId, itemId, count) {
         const inventory = inventoryFor(userId);
@@ -293,64 +310,11 @@ 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({
-        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) {
@@ -377,7 +341,7 @@ export function createGameContext(options) {
         },
         stats: { seed: seedUserPool },
         economy: { grant: economy.grant },
-        unlocks: { grant: unlocks.grant },
+        unlocks: { grant: (userId, unlockId) => featureValue("unlocks")?.grant(userId, unlockId) },
     }), ["applyLoadout"], signal.notify);
     function spawnEntity(name, spawnOptions) {
         const entry = content.entityById?.(name);
@@ -398,6 +362,23 @@ export function createGameContext(options) {
         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()) {
@@ -408,37 +389,28 @@ export function createGameContext(options) {
         }
         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,
+    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,
         });
-        return { status: "ok", record };
+        bodyBinds.set(key, created);
+        return created;
     }
+    const { worldItems, spawnWorldItem, pickupWorldItem } = createWorldItemContext({
+        entities,
+        events,
+        despawnEntity,
+        grantToPlayer: loot.grantToPlayer,
+        signalNotify: signal.notify,
+    });
     const death = createDeathSystem({
         resolveOnDeath: (instanceId) => catalogEntry(instanceId)?.onDeath,
         resolveIdentity(instanceId) {
@@ -498,121 +470,16 @@ export function createGameContext(options) {
             }
         },
     }), ["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 { emitFloatText, emitVfx, fireTelegraph, applyHitReaction, applyEffectAndFloat } = createCombatFx({
+        entities,
+        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,
@@ -674,8 +541,15 @@ export function createGameContext(options) {
             });
         },
     }), ["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),
@@ -687,87 +561,10 @@ export function createGameContext(options) {
             signal.notify();
         },
         collidersOf: objectCollidersOf,
+        selection: objectSelection,
     };
     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 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;
-    }
-    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 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`);
-        }
-        const created = new NotifyingRaceState(config);
-        raceStates.set(id, created);
-        return created;
-    }
+    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();
@@ -779,53 +576,116 @@ export function createGameContext(options) {
         }
         return queue;
     }
+    const featureDeps = {
+        features,
+        signalNotify: signal.notify,
+        events,
+        now,
+        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 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 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 = [
-        { 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);
-                }
-            },
-        },
+        ...baselineBuilds.flatMap((build) => (build.replicate === undefined ? [] : [build.replicate])),
+        ...featureReplicateModules,
     ];
-    if (leaderboard) {
-        snapshotModules.push({
-            key: "leaderboard",
-            snapshot: () => leaderboard.snapshot(),
-            hydrate: (data) => leaderboard.hydrate(data),
-        });
+    const replication = options.replication;
+    const projectsViewers = policyProjectsViewers(replication);
+    const aoiRadius = replication?.aoiRadius;
+    const projectorFor = (key) => {
+        if (aoiRadius !== undefined && key === "entities") {
+            return (data, viewer) => projectEntitiesForViewer(data, viewer, aoiRadius);
+        }
+        if (aoiRadius !== undefined && key === "stats") {
+            return (data, viewer, world) => projectByVisibleIds(data, visibleEntityIds((world["entities"] ?? []), viewer, aoiRadius));
+        }
+        if (replication?.privatePerUser === true && key === "inventory") {
+            return (data, viewer) => projectPerUserForViewer(data, viewer);
+        }
+        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);
+    /**
+     * 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])),
+        ...featureSaveModules,
+    ];
+    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);
     }
     const ctx = {
         scene: {
@@ -838,12 +698,16 @@ 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,
+                vfx: emitVfx,
+                vfxInstance: vfxInstances,
                 telegraph: fireTelegraph,
                 hitReaction: applyHitReaction,
                 setTarget: targeting.setTarget,
@@ -860,6 +724,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 +734,10 @@ export function createGameContext(options) {
                     signal.notify();
                 },
                 collidersOf: entityCollidersOf,
+                visualScaleOf: entityVisualScaleOf,
                 form: forms,
                 paint: paintLayer,
+                bind,
             },
             worldItem: {
                 spawn: spawnWorldItem,
@@ -933,19 +800,22 @@ export function createGameContext(options) {
                 },
             },
             loot,
-            trade,
-            quest,
-            social,
-            chat,
-            unlocks,
+            trade: featureValue("trade"),
+            quest: featureValue("quest"),
+            social: featureValue("social"),
+            chat: featureValue("chat"),
+            unlocks: featureValue("unlocks"),
             economy,
-            leaderboard,
-            roster,
+            leaderboard: featureValue("leaderboard"),
+            roster: featureValue("roster"),
             store,
-            cards: features.cards ? { pile } : undefined,
-            turn: features.turn ? { loop } : undefined,
-            race: features.race ? { state: raceState } : undefined,
-            players,
+            dialogue: featureValue("dialogue"),
+            cards: featureValue("cards"),
+            turn: featureValue("turn"),
+            race: featureValue("race"),
+            players: featureValue("players"),
+            registerSave,
+            registerReplicate,
         },
         player: {
             get userId() {
@@ -964,7 +834,7 @@ export function createGameContext(options) {
             applyLoadout: loadouts.applyLoadout,
             movement: pose,
             possession,
-            cosmetics,
+            cosmetics: featureValue("cosmetics"),
             get motion() {
                 return motionFor(activeUserId());
             },
@@ -988,11 +858,49 @@ 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,
     };
+    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,
+    };
+}