@jgengine/core 0.10.0 → 0.12.0

package/dist/runtime/context/scene.js

@@ -0,0 +1,291 @@
+import { createBodyBind } from "../../scene/bodyBind.js";
+import { createEntityStatsApi, seedStatValues, } from "../../scene/entityStats.js";
+import { createEntityStore, } from "../../scene/entityStore.js";
+import { createForms } from "../../scene/form.js";
+import { fittedEntityColliders, fittedObjectColliders, scaledEntityColliders, scaledObjectColliders, } from "../../scene/colliders.js";
+import { raycastObjects, raycastObjectsAll } from "../../scene/objectQuery.js";
+import { createObjectStore, objectVisualScale } from "../../scene/objectStore.js";
+import { createPaintLayer } from "../../scene/paintLayer.js";
+import { createSelectionSet } from "../../scene/selection.js";
+import { createSceneRaycast, } from "../../scene/sceneRaycast.js";
+import { createSpatialApi } from "../../scene/spatial.js";
+import { createTargeting } from "../../scene/targeting.js";
+import { notifyAfter } from "../../store/changeSignal.js";
+/** @internal */
+export function createSceneSubsystem(d) {
+    const { content, signalNotify, ground, events, time, occluder } = d;
+    const entities = createEntityStore();
+    const objects = createObjectStore();
+    entities.subscribe(signalNotify);
+    objects.subscribe(signalNotify);
+    const statsByInstance = new Map();
+    const entityStats = notifyAfter(createEntityStatsApi((instanceId) => statsByInstance.get(instanceId)), ["set", "delta"], signalNotify);
+    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();
+    const fittedEntityByKind = new Map();
+    const fittedObjectByCatalogId = new Map();
+    function fittedEntitySetFor(kind) {
+        const cached = fittedEntityByKind.get(kind);
+        if (cached !== undefined)
+            return cached;
+        const model = d.models?.entity?.(kind);
+        const fitted = model === null || model === undefined ? null : fittedEntityColliders(model);
+        fittedEntityByKind.set(kind, fitted);
+        return fitted;
+    }
+    function fittedObjectSetFor(catalogId) {
+        const cached = fittedObjectByCatalogId.get(catalogId);
+        if (cached !== undefined)
+            return cached;
+        const model = d.models?.object?.(catalogId);
+        const fitted = model === null || model === undefined ? null : fittedObjectColliders(model);
+        fittedObjectByCatalogId.set(catalogId, fitted);
+        return fitted;
+    }
+    function entityCollidersOf(instanceId) {
+        const override = entityColliders.get(instanceId);
+        if (override !== undefined)
+            return override;
+        const entry = catalogEntry(instanceId);
+        if (entry?.colliders !== undefined)
+            return entry.colliders;
+        const kind = entities.get(instanceId)?.name;
+        if (kind !== undefined) {
+            const fitted = fittedEntitySetFor(kind);
+            if (fitted !== null)
+                return fitted;
+        }
+        const scale = entry?.scale;
+        if (scale !== undefined && scale !== 1)
+            return scaledEntityColliders(scale);
+        return null;
+    }
+    function entityVisualScaleOf(instanceId) {
+        return catalogEntry(instanceId)?.scale ?? 1;
+    }
+    function objectCollidersOf(instanceId) {
+        const override = objectColliders.get(instanceId);
+        if (override !== undefined)
+            return override;
+        const catalog = catalogObject(instanceId);
+        if (catalog?.colliders !== undefined)
+            return catalog.colliders;
+        if (catalog?.halfExtents !== undefined)
+            return null;
+        const object = objects.get(instanceId);
+        if (object === null)
+            return null;
+        const fitted = fittedObjectSetFor(object.catalogId);
+        if (fitted !== null)
+            return fitted;
+        if (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"], signalNotify);
+    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 forms = notifyAfter(createForms({ entities, time, events }), ["shapeshift", "revert"], signalNotify);
+    const paintLayer = notifyAfter(createPaintLayer(), ["paint", "clear"], signalNotify);
+    let onAfterSpawn = () => { };
+    let onAfterDespawn = () => { };
+    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);
+        onAfterSpawn(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);
+        entityColliders.delete(instanceId);
+        onAfterDespawn(instanceId);
+        return existed;
+    }
+    function moveEntityTowardCommit(instanceId, target, options) {
+        const next = spatial.moveToward(instanceId, target, options);
+        if (next === null)
+            return null;
+        const current = entities.get(instanceId);
+        if (current === null)
+            return null;
+        let rotationY = current.rotationY;
+        if (options.face === true) {
+            const dx = next[0] - current.position[0];
+            const dz = next[2] - current.position[2];
+            if (Math.hypot(dx, dz) > 1e-9)
+                rotationY = Math.atan2(dx, dz);
+        }
+        entities.setPose(instanceId, { position: next, rotationY });
+        return next;
+    }
+    function resetAllToSpawn(filter) {
+        let count = 0;
+        for (const entity of entities.list()) {
+            if (filter !== undefined && !filter(entity))
+                continue;
+            if (entities.resetToSpawn(entity.id))
+                count += 1;
+        }
+        return count;
+    }
+    const bodyBinds = new Map();
+    function bind(key) {
+        const existing = bodyBinds.get(key);
+        if (existing !== undefined)
+            return existing;
+        const created = createBodyBind({
+            has: (id) => entities.get(id) !== null,
+            spawn: spawnEntity,
+            despawn: despawnEntity,
+            setPose: entities.setPose,
+            update: entities.update,
+        });
+        bodyBinds.set(key, created);
+        return created;
+    }
+    const objectSelection = notifyAfter(createSelectionSet(), ["add", "remove", "toggle", "replace", "clear"], signalNotify);
+    const sceneObjects = {
+        ...objects,
+        remove(instanceId) {
+            const existed = objects.remove(instanceId);
+            if (existed)
+                objectSelection.remove(instanceId);
+            return existed;
+        },
+        catalog: (instanceId) => catalogObject(instanceId) ?? null,
+        raycast: (input) => raycastObjects(objects, input),
+        raycastAll: (input) => raycastObjectsAll(objects, input),
+        setColliders(instanceId, colliders) {
+            if (colliders === null)
+                objectColliders.delete(instanceId);
+            else
+                objectColliders.set(instanceId, colliders);
+            signalNotify();
+        },
+        collidersOf: objectCollidersOf,
+        selection: objectSelection,
+    };
+    return {
+        entities,
+        objects,
+        statsByInstance,
+        entityStats,
+        ensureInstanceStats,
+        catalogEntry,
+        catalogObject,
+        spatial,
+        combatSpatial,
+        sceneRaycast,
+        targeting,
+        entityColliders,
+        objectColliders,
+        entityCollidersOf,
+        objectCollidersOf,
+        entityVisualScaleOf,
+        forms,
+        paintLayer,
+        spawnEntity,
+        despawnEntity,
+        moveEntityTowardCommit,
+        resetAllToSpawn,
+        bind,
+        sceneObjects,
+        setOnAfterSpawn(fn) {
+            onAfterSpawn = fn;
+        },
+        setOnAfterDespawn(fn) {
+            onAfterDespawn = fn;
+        },
+    };
+}

package/dist/runtime/context/snapshotCodecs.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shallow wire codecs for {@link SnapshotModule.decode} — reject obviously wrong shapes so hydrate
+ * never receives bare casts of garbage. Fail soft (return `null`); deeper field validation stays with
+ * each subsystem's hydrate.
+ * @internal
+ */
+/** @internal Reject non-arrays; return a typed array or null. */
+export declare function decodeArray<T = unknown>(raw: unknown): T[] | null;
+/** @internal Reject non-plain objects; return a typed record or null. */
+export declare function decodeRecord<T = unknown>(raw: unknown): Record<string, T> | null;
+/** @internal Reject non-[string, T][] entry lists; return entries or null. */
+export declare function decodeEntries<T = unknown>(raw: unknown): readonly (readonly [string, T])[] | null;

package/dist/runtime/context/snapshotCodecs.js

@@ -0,0 +1,26 @@
+/**
+ * Shallow wire codecs for {@link SnapshotModule.decode} — reject obviously wrong shapes so hydrate
+ * never receives bare casts of garbage. Fail soft (return `null`); deeper field validation stays with
+ * each subsystem's hydrate.
+ * @internal
+ */
+/** @internal Reject non-arrays; return a typed array or null. */
+export function decodeArray(raw) {
+    return Array.isArray(raw) ? raw : null;
+}
+/** @internal Reject non-plain objects; return a typed record or null. */
+export function decodeRecord(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    return raw;
+}
+/** @internal Reject non-[string, T][] entry lists; return entries or null. */
+export function decodeEntries(raw) {
+    if (!Array.isArray(raw))
+        return null;
+    for (const entry of raw) {
+        if (!Array.isArray(entry) || entry.length < 2 || typeof entry[0] !== "string")
+            return null;
+    }
+    return raw;
+}

package/dist/runtime/context/worldItems.d.ts

@@ -0,0 +1,21 @@
+import type { GameEvents } from "../../game/events.js";
+import { type WorldItemRecord, type WorldItemSpawnInput, type WorldItemStore } from "../../game/worldItem.js";
+import type { Drop } from "../../game/lootTable.js";
+import type { EntityStore } from "../../scene/entityStore.js";
+import type { WorldItemPickupResult } from "../gameContext.js";
+/** @internal What the ground-item surface needs from the live context: entity spawn/despawn, the event bus, loot granting, and change notification. */
+export interface WorldItemContextDeps {
+    entities: EntityStore;
+    events: GameEvents;
+    despawnEntity: (instanceId: string) => boolean;
+    grantToPlayer: (userId: string, drops: Drop[], source?: string) => void;
+    signalNotify: () => void;
+}
+/** @internal The `ctx.scene.worldItem` wiring: the reactive store plus the spawn/pickup verbs that emit `worldItem.*` events and route pickups through loot. */
+export interface WorldItemContext {
+    worldItems: WorldItemStore;
+    spawnWorldItem(input: WorldItemSpawnInput): WorldItemRecord;
+    pickupWorldItem(instanceId: string, userId: string): WorldItemPickupResult;
+}
+/** @internal */
+export declare function createWorldItemContext(d: WorldItemContextDeps): WorldItemContext;

package/dist/runtime/context/worldItems.js

@@ -0,0 +1,37 @@
+import { createWorldItemStore, WORLD_ITEM_ENTITY_NAME, } from "../../game/worldItem.js";
+import { notifyAfter } from "../../store/changeSignal.js";
+/** @internal */
+export function createWorldItemContext(d) {
+    const worldItems = notifyAfter(createWorldItemStore({
+        spawnEntity: (position) => d.entities.spawn(WORLD_ITEM_ENTITY_NAME, { position, role: "prop" }),
+        despawnEntity: d.despawnEntity,
+        resolvePosition: (instanceId) => d.entities.get(instanceId)?.position,
+    }), ["spawn", "take", "remove"], d.signalNotify);
+    function spawnWorldItem(input) {
+        const record = worldItems.spawn(input);
+        d.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" };
+        d.grantToPlayer(userId, [{ item: record.itemId, count: record.count }], "worldItem.pickup");
+        d.events.emit("worldItem.picked_up", {
+            instanceId,
+            userId,
+            itemId: record.itemId,
+            rarity: record.rarity,
+            count: record.count,
+        });
+        return { status: "ok", record };
+    }
+    return { worldItems, spawnWorldItem, pickupWorldItem };
+}

package/dist/runtime/descriptors/baseline.d.ts

@@ -0,0 +1,48 @@
+import type { WalletState } from "../../economy/wallet.js";
+import type { GameFeed } from "../../game/feed.js";
+import type { InventorySet } from "../../inventory/inventoryModel.js";
+import type { PoseState } from "../../movement/poseState.js";
+import { type StatValueMap } from "../../scene/entityStats.js";
+import type { EntityStore } from "../../scene/entityStore.js";
+import type { Possession } from "../../scene/possession.js";
+import type { ObservableKeyedStore } from "../../store/observableKeyedStore.js";
+import type { SimClock } from "../../time/simClock.js";
+import type { MotionIntents } from "../motionIntents.js";
+import type { SnapshotModule } from "../worldSnapshot.js";
+/** @internal The live always-on subsystems the baseline descriptors serialize — handed in by `createGameContext`. */
+export interface BaselineDeps {
+    signalNotify: () => void;
+    entities: EntityStore;
+    statsByInstance: Map<string, StatValueMap>;
+    store: ObservableKeyedStore<unknown>;
+    feed: GameFeed;
+    inventoryIds: readonly string[];
+    inventoryByUser: ReadonlyMap<string, InventorySet<string>>;
+    inventoryFor: (userId: string) => InventorySet<string>;
+    wallets: Map<string, WalletState>;
+    time: SimClock;
+    pose: PoseState;
+    possession: Possession;
+    motionByUser: ReadonlyMap<string, MotionIntents>;
+    motionFor: (userId: string) => MotionIntents;
+}
+/** @internal What an always-on baseline descriptor contributes: a replication module, a save-only module, or both. */
+export interface BaselineBuild {
+    /** Registered into the host→client replication set (`ctx.snapshot`/`ctx.hydrate`), and therefore also into the save set. */
+    replicate?: SnapshotModule;
+    /** Registered into the whole-world save-only set (`ctx.game.save`) — persisted but never sent to clients. */
+    save?: SnapshotModule;
+}
+/**
+ * Always-on counterpart to {@link featureDescriptors}: each baseline subsystem (entities, stats,
+ * store, feed, inventory, economy, time, pose, possession, motion) owns its own serialization here
+ * instead of `createGameContext` hand-maintaining two distant module arrays. Order is
+ * load-bearing — it fixes the snapshot key order, so it must stay stable.
+ * @internal
+ */
+export interface BaselineDescriptor {
+    readonly key: string;
+    create(deps: BaselineDeps): BaselineBuild;
+}
+/** @internal */
+export declare const baselineDescriptors: readonly BaselineDescriptor[];

package/dist/runtime/descriptors/baseline.js

@@ -0,0 +1,157 @@
+import { hydrateEntityStats, snapshotEntityStats, } from "../../scene/entityStats.js";
+import { decodeArray, decodeEntries, decodeRecord } from "../context/snapshotCodecs.js";
+/** @internal */
+export const baselineDescriptors = [
+    {
+        key: "entities",
+        create: (d) => ({
+            replicate: {
+                key: "entities",
+                snapshot: () => d.entities.snapshot(),
+                decode: (raw) => decodeArray(raw),
+                hydrate: (data) => d.entities.hydrate(data),
+            },
+        }),
+    },
+    {
+        key: "stats",
+        create: (d) => ({
+            replicate: {
+                key: "stats",
+                snapshot: () => snapshotEntityStats(d.statsByInstance),
+                decode: (raw) => decodeRecord(raw),
+                hydrate: (data) => hydrateEntityStats(d.statsByInstance, data),
+            },
+        }),
+    },
+    {
+        key: "store",
+        create: (d) => ({
+            replicate: {
+                key: "store",
+                snapshot: () => d.store.snapshot(),
+                decode: (raw) => decodeEntries(raw),
+                hydrate: (data) => d.store.hydrate(data),
+            },
+        }),
+    },
+    {
+        key: "feed",
+        create: (d) => ({
+            replicate: {
+                key: "feed",
+                snapshot: () => d.feed.snapshot(),
+                decode: (raw) => decodeRecord(raw),
+                hydrate: (data) => d.feed.hydrate(data),
+            },
+        }),
+    },
+    {
+        key: "inventory",
+        create: (d) => ({
+            replicate: {
+                key: "inventory",
+                snapshot: () => {
+                    const byUser = {};
+                    for (const [userId, set] of d.inventoryByUser) {
+                        const states = {};
+                        for (const inventoryId of d.inventoryIds)
+                            states[inventoryId] = set.state(inventoryId);
+                        byUser[userId] = states;
+                    }
+                    return byUser;
+                },
+                decode: (raw) => decodeRecord(raw),
+                hydrate: (data) => {
+                    const byUser = data;
+                    for (const [userId, states] of Object.entries(byUser)) {
+                        const set = d.inventoryFor(userId);
+                        for (const [inventoryId, state] of Object.entries(states))
+                            set.replaceState(inventoryId, state);
+                    }
+                },
+            },
+        }),
+    },
+    {
+        key: "economy",
+        create: (d) => ({
+            save: {
+                key: "economy",
+                snapshot: () => Object.fromEntries(d.wallets),
+                decode: (raw) => decodeRecord(raw),
+                hydrate: (data) => {
+                    const wallets = data;
+                    d.wallets.clear();
+                    for (const [userId, state] of Object.entries(wallets)) {
+                        d.wallets.set(userId, state);
+                    }
+                    d.signalNotify();
+                },
+            },
+        }),
+    },
+    {
+        key: "time",
+        create: (d) => ({
+            save: {
+                key: "time",
+                snapshot: () => d.time.snapshot(),
+                decode: (raw) => {
+                    const rec = decodeRecord(raw);
+                    return rec === null ? null : rec;
+                },
+                hydrate: (data) => d.time.hydrate(data),
+            },
+        }),
+    },
+    {
+        key: "pose",
+        create: (d) => ({
+            save: {
+                key: "pose",
+                snapshot: () => d.pose.snapshotAll(),
+                decode: (raw) => {
+                    const rec = decodeRecord(raw);
+                    return rec === null ? null : rec;
+                },
+                hydrate: (data) => d.pose.hydrateAll(data),
+            },
+        }),
+    },
+    {
+        key: "possession",
+        create: (d) => ({
+            save: {
+                key: "possession",
+                snapshot: () => d.possession.snapshotAll(),
+                decode: (raw) => {
+                    const rec = decodeRecord(raw);
+                    return rec === null ? null : rec;
+                },
+                hydrate: (data) => d.possession.hydrateAll(data),
+            },
+        }),
+    },
+    {
+        key: "motion",
+        create: (d) => ({
+            save: {
+                key: "motion",
+                snapshot: () => {
+                    const out = {};
+                    for (const [userId, queue] of d.motionByUser)
+                        out[userId] = queue.snapshot();
+                    return out;
+                },
+                decode: (raw) => decodeRecord(raw),
+                hydrate: (data) => {
+                    const batches = data;
+                    for (const [userId, batch] of Object.entries(batches)) {
+                        d.motionFor(userId).hydrate(batch);
+                    }
+                },
+            },
+        }),
+    },
+];

package/dist/runtime/descriptors/features.d.ts

@@ -0,0 +1,79 @@
+import type { CardPile, CardPileConfig } from "../../cards/cardPile.js";
+import type { CommandRegistry } from "../../commands/commandRegistry.js";
+import { type WalletState } from "../../economy/wallet.js";
+import type { GameFeatures } from "../../game/defineGame.js";
+import type { GameEvents } from "../../game/events.js";
+import { type Social } from "../../game/social.js";
+import type { InventoryLayout, InventorySet } from "../../inventory/inventoryModel.js";
+import type { StatValueMap } from "../../scene/entityStats.js";
+import type { EntityStore } from "../../scene/entityStore.js";
+import type { SpatialApi } from "../../scene/spatial.js";
+import type { ObservableKeyedStore } from "../../store/observableKeyedStore.js";
+import type { SnapshotModule } from "../worldSnapshot.js";
+import type { TurnLoop, TurnLoopConfig } from "../../turn/turnLoop.js";
+import type { RaceState, RaceStateConfig } from "../../game/race.js";
+import type { GameContext, GameContextContent, GameContextEconomy } from "../gameContext.js";
+/**
+ * Shared wiring every optional-feature descriptor draws from — the live core subsystems (entities,
+ * spatial, economy, inventory) plus reactive plumbing (`signalNotify`) and a `feature` reader for the
+ * few features that reference another (quest reads unlocks). Handed to each {@link FeatureDescriptor}'s
+ * `create` so a new opt-in subsystem plugs into one registration, never a new `features.x ?` branch.
+ * @internal
+ */
+export interface FeatureDeps {
+    features: GameFeatures;
+    signalNotify: () => void;
+    events: GameEvents;
+    now: () => number;
+    entities: EntityStore;
+    spatial: SpatialApi;
+    store: ObservableKeyedStore<unknown>;
+    commandRegistry: CommandRegistry<GameContext>;
+    economy: GameContextEconomy;
+    content: GameContextContent;
+    activeUserId: () => string;
+    walletOf: (userId: string) => WalletState;
+    setWallet: (userId: string, state: WalletState) => void;
+    layouts: Record<string, InventoryLayout>;
+    inventoryFor: (userId: string) => InventorySet<string>;
+    ensureInstanceStats: (instanceId: string) => StatValueMap;
+    seedUserPool: (userId: string, statId: string, pool: {
+        current: number;
+        max?: number;
+        min?: number;
+    }) => void;
+    sharedSocial: () => Social;
+    pile: (id: string, config?: CardPileConfig) => CardPile;
+    loop: (id: string, config?: TurnLoopConfig) => TurnLoop;
+    cardPiles: ReadonlyMap<string, CardPile>;
+    turnLoops: ReadonlyMap<string, TurnLoop>;
+    raceState: (id: string, config?: RaceStateConfig) => RaceState;
+    feature: <T>(key: keyof GameFeatures) => T | undefined;
+}
+/** @internal What a descriptor produces: the `ctx`-facing value plus its optional replication/save modules. */
+export interface FeatureBuild {
+    value: unknown;
+    /** Registered into the host→client replication set when present (`ctx.snapshot`/`ctx.hydrate`). */
+    replicate?: SnapshotModule;
+    /** Registered into the whole-world save-only set when present (`ctx.game.save`). */
+    save?: SnapshotModule;
+}
+/**
+ * One opt-in subsystem expressed as data: which `features` flag turns it on, how it wires itself from
+ * {@link FeatureDeps}, and whether it replicates or persists. `createGameContext` iterates the
+ * descriptor list instead of hand-wiring each `features.x ? create : undefined` branch — the seam a
+ * new feature extends through.
+ *
+ * Feature activation has **one path**: `definition.features` after `defineGame` has already
+ * OR-merged explicit `features: { quest: true }` sugar with system-implied flags via
+ * `mergeSystemFeatures`. Descriptors only call `enabled(features)` against that final map — never
+ * re-check systems or a second flag source.
+ * @internal
+ */
+export interface FeatureDescriptor {
+    readonly key: keyof GameFeatures;
+    enabled(features: GameFeatures): boolean;
+    create(deps: FeatureDeps): FeatureBuild;
+}
+/** @internal */
+export declare const featureDescriptors: readonly FeatureDescriptor[];