@jgengine/core 0.11.0 → 0.13.0

package/dist/runtime/context/player.js

@@ -0,0 +1,125 @@
+import { balance as walletBalance, charge as walletCharge, createEmptyWallet, grant as walletGrant, isOverdrawn as walletIsOverdrawn, } from "../../economy/wallet.js";
+import { createLoadouts } from "../../game/loadout.js";
+import { createInventorySet, putItem, } from "../../inventory/inventoryModel.js";
+import { createPoseState } from "../../movement/poseState.js";
+import { createPossession } from "../../scene/possession.js";
+import { setStatValue } from "../../scene/entityStats.js";
+import { createStats } from "../../stats/statModifiers.js";
+import { notifyAfter } from "../../store/changeSignal.js";
+import { createMotionIntents } from "../motionIntents.js";
+/** @internal */
+export function createPlayerSubsystem(d) {
+    const { signalNotify, entities, events, catalogEntry, ensureInstanceStats, feature } = d;
+    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 possession = notifyAfter(createPossession({ entities, events }), ["possess", "own", "disown"], signalNotify);
+    const inventoryDeclarations = d.inventoryDeclarations;
+    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"], signalNotify);
+            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));
+            signalNotify();
+        },
+        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);
+            signalNotify();
+            return null;
+        },
+        isOverdrawn: (userId, currencyId) => walletIsOverdrawn(walletOf(userId), currencyId),
+    };
+    function putIntoAnyInventory(userId, itemId, count) {
+        const inventory = inventoryFor(userId);
+        for (const inventoryId of inventoryIds) {
+            if (inventory.put(inventoryId, itemId, count).status === "ok")
+                return;
+        }
+    }
+    function seedUserPool(userId, statId, pool) {
+        const map = ensureInstanceStats(userId);
+        const next = setStatValue(map, statId, pool);
+        map[statId] = next[statId];
+    }
+    const loadouts = notifyAfter(createLoadouts({
+        inventory: {
+            begin(userId) {
+                const inventory = inventoryFor(userId);
+                const staged = new Map();
+                return {
+                    put(inventoryId, itemId, count, slot) {
+                        const layout = layouts[inventoryId];
+                        if (layout === undefined)
+                            return { reason: `unknown inventory "${inventoryId}"` };
+                        const state = staged.get(inventoryId) ?? inventory.state(inventoryId);
+                        const result = putItem(state, layout, traits, itemId, count, slot === undefined ? undefined : { slot });
+                        if (result.status === "rejected")
+                            return { reason: result.reason };
+                        staged.set(inventoryId, result.state);
+                        return null;
+                    },
+                    commit() {
+                        for (const [inventoryId, state] of staged)
+                            inventory.replaceState(inventoryId, state);
+                    },
+                };
+            },
+        },
+        stats: { seed: seedUserPool },
+        economy: { grant: economy.grant },
+        unlocks: { grant: (userId, unlockId) => feature("unlocks")?.grant(userId, unlockId) },
+    }), ["applyLoadout"], signalNotify);
+    const motionByUser = new Map();
+    function motionFor(userId) {
+        let queue = motionByUser.get(userId);
+        if (queue === undefined) {
+            queue = createMotionIntents();
+            motionByUser.set(userId, queue);
+        }
+        return queue;
+    }
+    return {
+        inventoryIds,
+        inventoryByUser,
+        inventoryFor,
+        layouts,
+        wallets,
+        walletOf,
+        economy,
+        putIntoAnyInventory,
+        playerStatsFor,
+        pose,
+        possession,
+        motionByUser,
+        motionFor,
+        loadouts,
+        seedUserPool,
+    };
+}

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

@@ -0,0 +1,60 @@
+import type { CombatSpatialDeps } from "../../combat/effects.js";
+import type { GameEvents } from "../../game/events.js";
+import { type BodyBind } from "../../scene/bodyBind.js";
+import { type EntityStatsApi, type StatValueMap } from "../../scene/entityStats.js";
+import { type EntityPosition, type EntityStore, type SceneEntity, type SpawnOptions } from "../../scene/entityStore.js";
+import { type Forms } from "../../scene/form.js";
+import { type EntityColliderSet, type MeasuredBounds } from "../../scene/colliders.js";
+import { type ObjectStore } from "../../scene/objectStore.js";
+import { type PaintLayer } from "../../scene/paintLayer.js";
+import { type SceneRaycastApi } from "../../scene/sceneRaycast.js";
+import { type SpatialApi } from "../../scene/spatial.js";
+import { type Targeting } from "../../scene/targeting.js";
+import type { TerrainField } from "../../world/terrain.js";
+import type { SimClock } from "../../time/simClock.js";
+import type { GameContextContent, GameContextEntityEntry, GameContextModels, GameContextObjectEntry, MoveTowardCommitOptions, SceneObjectContext } from "../gameContext.js";
+/** @internal Live scene stores + spatial/collider/raycast wiring handed in by `createGameContext`. */
+export interface SceneSubsystemDeps {
+    content: GameContextContent;
+    signalNotify: () => void;
+    ground: TerrainField;
+    events: GameEvents;
+    /** Full sim clock — forms need `after` for timed shapeshift reversion. */
+    time: SimClock;
+    occluder?: (from: EntityPosition, to: EntityPosition) => boolean;
+    models?: GameContextModels;
+}
+/** @internal Always-on scene surface: entities, objects, colliders, spatial, raycast, targeting. */
+export interface SceneSubsystem {
+    entities: EntityStore;
+    objects: ObjectStore;
+    statsByInstance: Map<string, StatValueMap>;
+    entityStats: EntityStatsApi;
+    ensureInstanceStats: (instanceId: string) => StatValueMap;
+    catalogEntry: (instanceId: string) => GameContextEntityEntry | null | undefined;
+    catalogObject: (instanceId: string) => GameContextObjectEntry | null | undefined;
+    spatial: SpatialApi;
+    combatSpatial: CombatSpatialDeps;
+    sceneRaycast: SceneRaycastApi;
+    targeting: Targeting;
+    entityColliders: Map<string, EntityColliderSet>;
+    objectColliders: Map<string, EntityColliderSet>;
+    entityCollidersOf: (instanceId: string) => EntityColliderSet | null;
+    objectCollidersOf: (instanceId: string) => EntityColliderSet | null;
+    reportEntityBounds: (kind: string, bounds: MeasuredBounds | null) => boolean;
+    entityVisualScaleOf: (instanceId: string) => number;
+    forms: Forms;
+    paintLayer: PaintLayer;
+    spawnEntity: (name: string, spawnOptions?: SpawnOptions) => string;
+    despawnEntity: (instanceId: string) => boolean;
+    moveEntityTowardCommit: (instanceId: string, target: EntityPosition | string, options: MoveTowardCommitOptions) => EntityPosition | null;
+    resetAllToSpawn: (filter?: (entity: SceneEntity) => boolean) => number;
+    bind: (key: string) => BodyBind;
+    sceneObjects: SceneObjectContext;
+    /** Install post-spawn side effects (death.revive) after combat is constructed. */
+    setOnAfterSpawn: (fn: (instanceId: string) => void) => void;
+    /** Install post-despawn side effects (pose.clear) after player is constructed. */
+    setOnAfterDespawn: (fn: (instanceId: string) => void) => void;
+}
+/** @internal */
+export declare function createSceneSubsystem(d: SceneSubsystemDeps): SceneSubsystem;

package/dist/runtime/context/scene.js

@@ -0,0 +1,329 @@
+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, measuredEntityColliders, measuredObjectColliders, 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;
+    }
+    const measuredEntityByKind = new Map();
+    const measuredObjectByCatalogId = new Map();
+    function reportEntityBounds(kind, bounds) {
+        if (bounds === null) {
+            const existed = measuredEntityByKind.delete(kind);
+            if (existed)
+                signalNotify();
+            return existed;
+        }
+        const measured = measuredEntityColliders(bounds);
+        if (measured === null)
+            return false;
+        measuredEntityByKind.set(kind, measured);
+        signalNotify();
+        return true;
+    }
+    function reportObjectBounds(catalogId, bounds) {
+        if (bounds === null) {
+            const existed = measuredObjectByCatalogId.delete(catalogId);
+            if (existed)
+                signalNotify();
+            return existed;
+        }
+        const measured = measuredObjectColliders(bounds);
+        if (measured === null)
+            return false;
+        measuredObjectByCatalogId.set(catalogId, measured);
+        signalNotify();
+        return true;
+    }
+    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 measured = measuredEntityByKind.get(kind);
+            if (measured !== undefined)
+                return measured;
+        }
+        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;
+        const measured = measuredObjectByCatalogId.get(object.catalogId);
+        if (measured !== undefined)
+            return measured;
+        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,
+        reportBounds: reportObjectBounds,
+        selection: objectSelection,
+    };
+    return {
+        entities,
+        objects,
+        statsByInstance,
+        entityStats,
+        ensureInstanceStats,
+        catalogEntry,
+        catalogObject,
+        spatial,
+        combatSpatial,
+        sceneRaycast,
+        targeting,
+        entityColliders,
+        objectColliders,
+        entityCollidersOf,
+        objectCollidersOf,
+        reportEntityBounds,
+        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/descriptors/baseline.js

@@ -1,4 +1,5 @@
 import { hydrateEntityStats, snapshotEntityStats, } from "../../scene/entityStats.js";
+import { decodeArray, decodeEntries, decodeRecord } from "../context/snapshotCodecs.js";
 /** @internal */
 export const baselineDescriptors = [
     {
@@ -7,6 +8,7 @@ export const baselineDescriptors = [
             replicate: {
                 key: "entities",
                 snapshot: () => d.entities.snapshot(),
+                decode: (raw) => decodeArray(raw),
                 hydrate: (data) => d.entities.hydrate(data),
             },
         }),
@@ -17,6 +19,7 @@ export const baselineDescriptors = [
             replicate: {
                 key: "stats",
                 snapshot: () => snapshotEntityStats(d.statsByInstance),
+                decode: (raw) => decodeRecord(raw),
                 hydrate: (data) => hydrateEntityStats(d.statsByInstance, data),
             },
         }),
@@ -27,6 +30,7 @@ export const baselineDescriptors = [
             replicate: {
                 key: "store",
                 snapshot: () => d.store.snapshot(),
+                decode: (raw) => decodeEntries(raw),
                 hydrate: (data) => d.store.hydrate(data),
             },
         }),
@@ -37,6 +41,7 @@ export const baselineDescriptors = [
             replicate: {
                 key: "feed",
                 snapshot: () => d.feed.snapshot(),
+                decode: (raw) => decodeRecord(raw),
                 hydrate: (data) => d.feed.hydrate(data),
             },
         }),
@@ -56,8 +61,10 @@ export const baselineDescriptors = [
                     }
                     return byUser;
                 },
+                decode: (raw) => decodeRecord(raw),
                 hydrate: (data) => {
-                    for (const [userId, states] of Object.entries(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);
@@ -72,9 +79,11 @@ export const baselineDescriptors = [
             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(data)) {
+                    for (const [userId, state] of Object.entries(wallets)) {
                         d.wallets.set(userId, state);
                     }
                     d.signalNotify();
@@ -88,6 +97,10 @@ export const baselineDescriptors = [
             save: {
                 key: "time",
                 snapshot: () => d.time.snapshot(),
+                decode: (raw) => {
+                    const rec = decodeRecord(raw);
+                    return rec === null ? null : rec;
+                },
                 hydrate: (data) => d.time.hydrate(data),
             },
         }),
@@ -98,6 +111,10 @@ export const baselineDescriptors = [
             save: {
                 key: "pose",
                 snapshot: () => d.pose.snapshotAll(),
+                decode: (raw) => {
+                    const rec = decodeRecord(raw);
+                    return rec === null ? null : rec;
+                },
                 hydrate: (data) => d.pose.hydrateAll(data),
             },
         }),
@@ -108,6 +125,10 @@ export const baselineDescriptors = [
             save: {
                 key: "possession",
                 snapshot: () => d.possession.snapshotAll(),
+                decode: (raw) => {
+                    const rec = decodeRecord(raw);
+                    return rec === null ? null : rec;
+                },
                 hydrate: (data) => d.possession.hydrateAll(data),
             },
         }),
@@ -123,8 +144,10 @@ export const baselineDescriptors = [
                         out[userId] = queue.snapshot();
                     return out;
                 },
+                decode: (raw) => decodeRecord(raw),
                 hydrate: (data) => {
-                    for (const [userId, batch] of Object.entries(data)) {
+                    const batches = data;
+                    for (const [userId, batch] of Object.entries(batches)) {
                         d.motionFor(userId).hydrate(batch);
                     }
                 },

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

@@ -63,6 +63,11 @@ export interface FeatureBuild {
  * {@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 {