@jgengine/core 0.18.1 → 0.21.0

package/dist/runtime/context/combat.js

@@ -2,28 +2,45 @@ import { createDeathSystem, deathReasonFromEffect } from "../../combat/death.js"
 import { createEffectSystem, } from "../../combat/effects.js";
 import { createProjectileSystem } from "../../combat/projectiles.js";
 import { createVfxInstanceStore } from "../../game/vfxInstance.js";
+import { colliderBounds, colliderWorldCenter, defaultEntityColliders, resolveColliders } from "../../scene/colliders.js";
+import { raycastCollisionMesh } from "../../scene/collisionMesh.js";
+import { sweepMovingBounds, sweepMovingSphere } from "../../physics/ballisticSweep.js";
+import { createSpatialIndex } from "../../visibility/spatialIndex.js";
 import { createEntityStatsApi } from "../../scene/entityStats.js";
 import { notifyAfter } from "../../store/changeSignal.js";
 import { createCombatFx } from "./combatFx.js";
-import { applyLethalLoot, isLocalPlayerKill } from "./deathLoot.js";
+import { allowsUnownedWorldDrops, applyLethalLoot } from "./deathLoot.js";
 /** @internal */
 export function createCombatSubsystem(d) {
-    const { content, signalNotify, now, events, time, entities, objects, combatSpatial, sceneRaycast, entityCollidersOf, objectCollidersOf, catalogEntry, statsByInstance, weapon, loot, lootRegistry, spawnWorldItem, despawnEntity, runCommand, localUserId, } = d;
+    const { content, signalNotify, now, events, time, entities, objects, combatSpatial, sceneRaycast, entityCollidersOf, objectCollidersOf, catalogEntry, statsByInstance, weapon, loot, lootRegistry, spawnWorldItem, despawnEntity, runCommand, userIdOf, rng, } = d;
     const death = createDeathSystem({
-        resolveOnDeath: (instanceId) => catalogEntry(instanceId)?.onDeath,
+        resolveOnDeath(instanceId, reason) {
+            const spec = catalogEntry(instanceId)?.onDeath;
+            if (reason !== undefined && reason.kind !== "player_kill" && allowsUnownedWorldDrops(spec)) {
+                // Explicit opt-in must not enable neighboring legacy/unfiltered tables.
+                return {
+                    ...spec,
+                    drops: Array.isArray(spec?.drops)
+                        ? spec.drops.filter((rule) => rule.when?.reason === "any") : [],
+                };
+            }
+            return spec;
+        },
         resolveIdentity(instanceId) {
             const entity = entities.get(instanceId);
             if (entity === null)
                 return null;
+            const userId = userIdOf(instanceId);
             return {
                 catalogId: entity.name,
                 position: [entity.position[0], entity.position[1], entity.position[2]],
+                ...(userId === undefined ? {} : { userId }),
             };
         },
         loot: { roll: (tableId) => (lootRegistry.has(tableId) ? lootRegistry.roll(tableId) : []) },
         events,
-        runCommand(name, args) {
-            runCommand(name, args);
+        runCommand(name, args, reason) {
+            runCommand(name, args, reason?.kind === "player_kill" ? reason.killerUserId : undefined);
         },
         despawn(instanceId) {
             despawnEntity(instanceId);
@@ -39,7 +56,8 @@ export function createCombatSubsystem(d) {
             if (entity === null)
                 return null;
             // `entity.name` is the spawn kind/catalog id, matching the `entity.died` event.
-            return { catalogId: entity.name, name: entity.name };
+            const userId = userIdOf(instanceId);
+            return { catalogId: entity.name, name: entity.name, ...(userId === undefined ? {} : { userId }) };
         },
         onLethal(instanceId, lethalCtx) {
             // Capture identity + onDeath *before* resolveDeath despawns the entity.
@@ -49,21 +67,22 @@ export function createCombatSubsystem(d) {
             const onDeath = catalogEntry(instanceId)?.onDeath;
             const reason = deathReasonFromEffect({
                 ...lethalCtx,
-                userIdOf: (id) => (id === localUserId ? localUserId : undefined),
+                userIdOf,
             });
             const resolution = death.resolveDeath(instanceId, reason);
             if (resolution.status !== "resolved")
                 return;
             applyLethalLoot({
                 drops: resolution.drops,
-                grantToLocalPlayer: isLocalPlayerKill(lethalCtx, localUserId),
+                recipientUserId: reason.kind === "player_kill" ? reason.killerUserId : undefined,
+                allowUnownedWorldDrops: reason.kind !== "player_kill" && allowsUnownedWorldDrops(onDeath),
                 onDeath,
                 position,
                 catalogId,
                 content,
                 spawnWorldItem,
                 grantToPlayer: loot.grantToPlayer,
-                localUserId,
+                rng,
             });
         },
     }), ["applyEffect"], signalNotify);
@@ -98,7 +117,8 @@ export function createCombatSubsystem(d) {
             return sceneRaycast.raycastAll({ ...input, filter: projectileFilterFor(input.filter) });
         },
     };
-    const projectiles = notifyAfter(createProjectileSystem({
+    const travelQueries = createProjectileTravelQueries(d);
+    const projectileOwner = createProjectileSystem({
         effects: floatingEffects,
         spatial: combatSpatial,
         getStat: weapon.getStat,
@@ -117,8 +137,12 @@ export function createCombatSubsystem(d) {
         entityCollidersOf,
         rotationYOf: (instanceId) => entities.get(instanceId)?.rotationY,
         now,
+        rng,
+        travel: { ...d.projectileTravel, now: time.now, sweep: d.projectileTravel?.sweep ?? travelQueries.sweep },
         onSettle(report) {
             events.emit("projectile.settled", {
+                shotId: report.shotId,
+                hits: structuredClone(report.hits),
                 from: report.from,
                 origin: [report.origin[0], report.origin[1], report.origin[2]],
                 at: [report.at[0], report.at[1], report.at[2]],
@@ -127,7 +151,15 @@ export function createCombatSubsystem(d) {
                 ballistic: report.ballistic,
             });
         },
-    }), ["fireProjectile", "settleProjectile"], signalNotify);
+    });
+    const resettingProjectileOwner = {
+        ...projectileOwner,
+        restore(state) {
+            projectileOwner.restore(state);
+            travelQueries.reset();
+        },
+    };
+    const projectiles = notifyAfter(resettingProjectileOwner, ["fireProjectile", "settleProjectile", "restore"], signalNotify);
     return {
         death,
         effects,
@@ -135,5 +167,141 @@ export function createCombatSubsystem(d) {
         projectiles,
         combatFx,
         vfxInstances,
+        captureProjectileTargets(gameDt) { travelQueries.capture(gameDt, projectiles.activeProjectiles().length > 0); },
+    };
+}
+/** Derived collision scratch data is rebuilt from the scene each authoritative step. */
+function createProjectileTravelQueries(d) {
+    const { entities, time, sceneRaycast, entityCollidersOf } = d;
+    const projectileObstacles = d.physics?.projectileObstacles === true;
+    const previousTargets = new Map();
+    const maxTargets = d.projectileTravel?.maxTargets ?? 2048;
+    if (!Number.isInteger(maxTargets) || maxTargets <= 0)
+        throw new RangeError("Projectile collision budget must be a positive integer");
+    const targetIndex = createSpatialIndex();
+    const targetColliders = new Map();
+    const targetCandidates = [];
+    let targetIndexReady = false;
+    let targetStepStart = 0;
+    let targetStepDuration = 0;
+    function captureProjectileTargets(gameDt, active) {
+        previousTargets.clear();
+        targetIndexReady = false;
+        targetStepDuration = gameDt;
+        targetStepStart = time.now() - gameDt;
+        if (!active)
+            return;
+        const ids = d.projectileTravel?.targets?.() ?? entities.ids();
+        if (ids.length > maxTargets)
+            throw new RangeError("Projectile collision target budget exhausted; provide a bounded target source");
+        for (const id of ids) {
+            const entity = entities.get(id);
+            if (entity !== null)
+                previousTargets.set(id, { position: [...entity.position], rotationY: entity.rotationY });
+        }
+    }
+    function indexProjectileTargets() {
+        if (targetIndexReady)
+            return;
+        targetIndex.clear();
+        targetColliders.clear();
+        const ids = d.projectileTravel?.targets?.() ?? entities.ids();
+        if (ids.length > maxTargets)
+            throw new RangeError("Projectile collision target budget exhausted; provide a bounded target source");
+        for (const id of ids) {
+            const entity = entities.get(id);
+            if (entity === null)
+                continue;
+            const previous = previousTargets.get(id);
+            const colliders = resolveColliders(entityCollidersOf(id) ?? defaultEntityColliders());
+            targetColliders.set(id, colliders);
+            let minX = Infinity, minY = Infinity, minZ = Infinity, maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+            for (const collider of colliders) {
+                const start = colliderBounds(collider, previous?.position ?? entity.position, previous?.rotationY ?? entity.rotationY);
+                const end = colliderBounds(collider, entity.position, entity.rotationY);
+                minX = Math.min(minX, start.min[0], end.min[0]);
+                minY = Math.min(minY, start.min[1], end.min[1]);
+                minZ = Math.min(minZ, start.min[2], end.min[2]);
+                maxX = Math.max(maxX, start.max[0], end.max[0]);
+                maxY = Math.max(maxY, start.max[1], end.max[1]);
+                maxZ = Math.max(maxZ, start.max[2], end.max[2]);
+            }
+            if (colliders.length > 0)
+                targetIndex.insert(id, { minX, minY, minZ, maxX, maxY, maxZ, centerX: (minX + maxX) / 2, centerY: (minY + maxY) / 2, centerZ: (minZ + maxZ) / 2, radius: Math.hypot(maxX - minX, maxY - minY, maxZ - minZ) / 2 });
+        }
+        targetIndexReady = true;
+    }
+    function sweepProjectile(from, to, step) {
+        if (projectileObstacles && step.radius > 0)
+            throw new RangeError("Authored cover requires centerline projectiles (radius 0); inject a radius-aware travel sweep for larger projectiles");
+        const distance = Math.hypot(to[0] - from[0], to[1] - from[1], to[2] - from[2]);
+        const staticHits = distance > 0 ? sceneRaycast.raycastAll({ origin: from, direction: [to[0] - from[0], to[1] - from[1], to[2] - from[2]], maxDistance: distance, excludeInstanceIds: [step.input.from], filter: { entities: false, objects: projectileObstacles, walls: projectileObstacles, terrain: projectileObstacles } }) : [];
+        const blocker = staticHits.find(hit => hit.blocks);
+        let nearest = blocker === undefined ? null : { fraction: blocker.distance / distance, at: blocker.point };
+        let nearestKey = blocker === undefined ? "" : `${blocker.instanceId}:${blocker.colliderName}`;
+        indexProjectileTargets();
+        const radius = step.radius;
+        const ids = targetIndex.queryBox(Math.min(from[0], to[0]) - radius, Math.min(from[1], to[1]) - radius, Math.min(from[2], to[2]) - radius, Math.max(from[0], to[0]) + radius, Math.max(from[1], to[1]) + radius, Math.max(from[2], to[2]) + radius, targetCandidates);
+        for (const id of ids) {
+            if (id === step.input.from)
+                continue;
+            const entity = entities.get(id);
+            if (entity === null)
+                continue;
+            const previous = previousTargets.get(id);
+            const fractionAt = (at) => targetStepDuration > 0 ? Math.max(0, Math.min(1, (at - targetStepStart) / targetStepDuration)) : 1;
+            const positionAt = (at) => {
+                if (previous === undefined)
+                    return entity.position;
+                const alpha = fractionAt(at);
+                return [previous.position[0] + (entity.position[0] - previous.position[0]) * alpha, previous.position[1] + (entity.position[1] - previous.position[1]) * alpha, previous.position[2] + (entity.position[2] - previous.position[2]) * alpha];
+            };
+            const colliders = targetColliders.get(id);
+            for (const collider of colliders) {
+                if (!collider.blocks && !collider.damageEligible)
+                    continue;
+                const targetFrom = colliderWorldCenter(collider, positionAt(step.fromTime), previous?.rotationY ?? entity.rotationY);
+                const targetTo = colliderWorldCenter(collider, positionAt(step.toTime), entity.rotationY);
+                let fraction;
+                if (collider.shape.kind === "sphere") {
+                    fraction = sweepMovingSphere(from, to, targetFrom, targetTo, collider.shape.radius + step.radius);
+                }
+                else if (collider.shape.kind === "mesh" && step.radius === 0) {
+                    const start = positionAt(step.fromTime);
+                    const end = positionAt(step.toTime);
+                    const origin = [from[0] + end[0] - start[0], from[1] + end[1] - start[1], from[2] + end[2] - start[2]];
+                    const motion = [to[0] - origin[0], to[1] - origin[1], to[2] - origin[2]];
+                    const length = Math.hypot(...motion);
+                    const hit = length > 0 ? raycastCollisionMesh(collider.shape.mesh, origin, [motion[0] / length, motion[1] / length, motion[2] / length], length, end, entity.rotationY, collider.shape.meshScale, collider.shape.meshTranslate) : null;
+                    fraction = hit === null ? null : hit.distance / length;
+                }
+                else {
+                    const half = collider.shape.halfExtents;
+                    fraction = sweepMovingBounds(from, to, targetFrom, targetTo, [half[0] + step.radius, half[1] + step.radius, half[2] + step.radius]);
+                }
+                const key = `${id}:${collider.name}`;
+                if (fraction === null || (nearest !== null && (fraction > nearest.fraction || (fraction === nearest.fraction && key >= nearestKey))))
+                    continue;
+                nearestKey = key;
+                nearest = {
+                    fraction, at: [from[0] + (to[0] - from[0]) * fraction, from[1] + (to[1] - from[1]) * fraction, from[2] + (to[2] - from[2]) * fraction],
+                    target: { kind: "entity", instanceId: id, distance: distance * fraction, colliderName: collider.name, damageEligible: collider.damageEligible },
+                };
+            }
+        }
+        return nearest;
+    }
+    return {
+        capture: captureProjectileTargets,
+        sweep: sweepProjectile,
+        reset() {
+            previousTargets.clear();
+            targetIndex.clear();
+            targetColliders.clear();
+            targetCandidates.length = 0;
+            targetIndexReady = false;
+            targetStepStart = 0;
+            targetStepDuration = 0;
+        },
     };
 }

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

@@ -1,4 +1,4 @@
-import { type EffectDeathContext, type OnDeathSpec } from "../../combat/death.js";
+import { type OnDeathSpec } from "../../combat/death.js";
 import type { Drop } from "../../game/lootTable.js";
 import { type WorldItemSpawnInput } from "../../game/worldItem.js";
 import type { GameContextContent } from "../gameContext.js";
@@ -6,8 +6,10 @@ import type { GameContextContent } from "../gameContext.js";
 export interface LethalLootInput {
     /** Drops produced by the death system's resolution (already rolled). */
     drops: readonly Drop[];
-    /** True when the killer is the local/host player this context is resolving loot for. */
-    grantToLocalPlayer: boolean;
+    /** Resolved killer identity; environmental kills have no player recipient. */
+    recipientUserId: string | undefined;
+    /** Explicit any-death world rules may spawn items without a player recipient. */
+    allowUnownedWorldDrops?: boolean;
     /** Catalog `onDeath` for the dying entity (drop mode + scatter). */
     onDeath: OnDeathSpec | undefined;
     /** World position of the dying entity — required for `dropMode: "world"`. */
@@ -17,14 +19,15 @@ export interface LethalLootInput {
     content: GameContextContent;
     spawnWorldItem: (input: WorldItemSpawnInput) => void;
     grantToPlayer: (userId: string, drops: Drop[], source?: string) => void;
-    localUserId: string;
+    /** The world's seeded stream — scatter positions must replay with the rest of the simulation. */
+    rng: () => number;
 }
+/** @internal Only an explicit rule opts a catalog into unowned world drops. */
+export declare function allowsUnownedWorldDrops(onDeath: OnDeathSpec | undefined): boolean;
 /**
- * Pure death→loot policy: when a kill yields drops for the local player, either scatter them as
- * world items (`dropMode: "world"`) or grant straight into bags. Extracted from `createGameContext`
+ * Pure death→loot policy: scatter world items or grant straight into player bags.
+ * Unowned deaths require explicit opt-in and never grant currency. Extracted from `createGameContext`
  * so combat install stays free of nested loot branching.
  * @internal
  */
 export declare function applyLethalLoot(input: LethalLootInput): void;
-/** @internal Build the grant-to-local-player flag from a lethal effect context + local user id. */
-export declare function isLocalPlayerKill(lethalCtx: EffectDeathContext, localUserId: string): boolean;

package/dist/runtime/context/deathLoot.js

@@ -1,19 +1,28 @@
-import { deathReasonFromEffect, normalizeOnDeath, } from "../../combat/death.js";
+import { normalizeOnDeath } from "../../combat/death.js";
 import { DEFAULT_RARITY, resolveDeathDrops, } from "../../game/worldItem.js";
+/** @internal Only an explicit rule opts a catalog into unowned world drops. */
+export function allowsUnownedWorldDrops(onDeath) {
+    const normalized = normalizeOnDeath(onDeath);
+    return normalized.dropMode === "world" && normalized.drops.some((rule) => rule.when?.reason === "any");
+}
 /**
- * Pure death→loot policy: when a kill yields drops for the local player, either scatter them as
- * world items (`dropMode: "world"`) or grant straight into bags. Extracted from `createGameContext`
+ * Pure death→loot policy: scatter world items or grant straight into player bags.
+ * Unowned deaths require explicit opt-in and never grant currency. Extracted from `createGameContext`
  * so combat install stays free of nested loot branching.
  * @internal
  */
 export function applyLethalLoot(input) {
-    if (input.drops.length === 0 || !input.grantToLocalPlayer)
+    if (input.drops.length === 0)
         return;
     const normalizedOnDeath = normalizeOnDeath(input.onDeath);
+    if (input.recipientUserId === undefined &&
+        !(input.allowUnownedWorldDrops && normalizedOnDeath.dropMode === "world" && input.position !== undefined))
+        return;
     if (normalizedOnDeath.dropMode === "world" && input.position !== undefined) {
         const resolved = resolveDeathDrops([...input.drops], {
             mode: "world",
             origin: input.position,
+            rng: input.rng,
             resolveRarity: (itemId) => input.content.itemById?.(itemId)?.rarity ?? DEFAULT_RARITY,
             resolveBaseType: (itemId) => input.content.itemById?.(itemId)?.baseType ?? itemId,
             scatter: normalizedOnDeath.scatter,
@@ -21,19 +30,11 @@ export function applyLethalLoot(input) {
         });
         for (const spawn of resolved.worldSpawns)
             input.spawnWorldItem(spawn);
-        if (resolved.grants.length > 0) {
-            input.grantToPlayer(input.localUserId, resolved.grants, input.catalogId);
+        if (resolved.grants.length > 0 && input.recipientUserId !== undefined) {
+            input.grantToPlayer(input.recipientUserId, resolved.grants, input.catalogId);
         }
     }
-    else {
-        input.grantToPlayer(input.localUserId, [...input.drops], input.catalogId);
+    else if (input.recipientUserId !== undefined) {
+        input.grantToPlayer(input.recipientUserId, [...input.drops], input.catalogId);
     }
 }
-/** @internal Build the grant-to-local-player flag from a lethal effect context + local user id. */
-export function isLocalPlayerKill(lethalCtx, localUserId) {
-    const reason = deathReasonFromEffect({
-        ...lethalCtx,
-        userIdOf: (id) => (id === localUserId ? localUserId : undefined),
-    });
-    return reason.kind === "player_kill" && reason.killerUserId === localUserId;
-}

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

@@ -13,6 +13,7 @@ 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 { WorldSolids } from "../../world/worldSolids.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`. */
@@ -20,6 +21,7 @@ export interface SceneSubsystemDeps {
     content: GameContextContent;
     signalNotify: () => void;
     ground: TerrainField;
+    solids?: Pick<WorldSolids, "count" | "inBox">;
     events: GameEvents;
     /** Full sim clock — forms need `after` for timed shapeshift reversion. */
     time: SimClock;

package/dist/runtime/context/scene.js

@@ -18,7 +18,14 @@ import { notifyAfter } from "../../store/changeSignal.js";
 /** @internal */
 export function createSceneSubsystem(d) {
     const { content, signalNotify, ground, events, time, occluder } = d;
-    const entities = createEntityStore();
+    const entities = createEntityStore({
+        onChange: (instanceId) => {
+            if (instanceId === undefined)
+                spatial.invalidate();
+            else
+                spatial.updateEntity(instanceId);
+        },
+    });
     const objects = createObjectStore();
     entities.subscribe(signalNotify);
     objects.subscribe(signalNotify);
@@ -40,39 +47,23 @@ export function createSceneSubsystem(d) {
         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;
-    }
     // `moveToward` reads the same blocking colliders the player resolver does, so a chaser stops at the
     // wall that stops the player rather than lerping through it.
     const walkerReach = createObstacleReachCache();
     const solidSource = {
+        solids: d.solids,
         list: () => objects.list(),
         inBox: (min, max) => objects.inBox(min, max),
         collidersOf: (instanceId) => objectCollidersOf(instanceId),
     };
     const spatial = createSpatialApi({
         resolvePosition: (instanceId) => entities.get(instanceId)?.position,
-        candidates: refreshCandidateIds,
+        candidates: entities.ids,
         grid: { cellSize: 8 },
-        getVersion: () => spatialGeneration,
+        incremental: true,
         resolveStep: (position, stepX, stepZ) => slideStep(position, stepX, stepZ, sourceObstaclesNear(solidSource, sourceObstacleReach(solidSource, walkerReach), position, Math.abs(stepX) + DEFAULT_OBSTACLE_PLAYER_RADIUS, Math.abs(stepZ) + DEFAULT_OBSTACLE_PLAYER_RADIUS)),
         ...(occluder !== undefined ? { occluder } : {}),
     });
-    entities.subscribe(() => {
-        candidateIdsDirty = true;
-        spatialGeneration += 1;
-        spatial.invalidate();
-    });
     const entityColliders = new Map();
     const objectColliders = new Map();
     const fittedEntityByKind = new Map();
@@ -216,7 +207,7 @@ export function createSceneSubsystem(d) {
         return scaledObjectColliders(objectVisualScale(object.visual));
     }
     const targeting = notifyAfter(createTargeting({
-        candidates: () => [...refreshCandidateIds()],
+        candidates: () => [...entities.ids()],
         classify(_fromId, toId) {
             const role = catalogEntry(toId)?.role;
             return role === "enemy" || role === "hostile" ? "hostile" : "friendly";
@@ -238,6 +229,7 @@ export function createSceneSubsystem(d) {
         positionOf: (instanceId) => entities.get(instanceId)?.position,
     };
     const sceneRaycast = createSceneRaycast({
+        solids: d.solids,
         entities: {
             list: () => entities.list().map((entity) => ({
                 id: entity.id,

package/dist/runtime/descriptors/baseline.js

@@ -1,5 +1,31 @@
 import { hydrateEntityStats, snapshotEntityStats, } from "../../scene/entityStats.js";
 import { decodeArray, decodeEntries, decodeRecord } from "../context/snapshotCodecs.js";
+// A store slot whose value carries functions (a closure-based run store, an input handle) is that
+// world's runtime object, not world state: it cannot be cloned, persisted or sent, so it stays out of
+// snapshots and survives hydration in place.
+function holdsLiveCode(value, seen = new Set()) {
+    if (typeof value === "function")
+        return true;
+    if (value === null || typeof value !== "object" || seen.has(value) || ArrayBuffer.isView(value))
+        return false;
+    seen.add(value);
+    if (value instanceof Map) {
+        for (const [key, entry] of value)
+            if (holdsLiveCode(key, seen) || holdsLiveCode(entry, seen))
+                return true;
+        return false;
+    }
+    if (value instanceof Set) {
+        for (const entry of value)
+            if (holdsLiveCode(entry, seen))
+                return true;
+        return false;
+    }
+    for (const key in value)
+        if (holdsLiveCode(value[key], seen))
+            return true;
+    return false;
+}
 /** @internal */
 export const baselineDescriptors = [
     {
@@ -29,9 +55,14 @@ export const baselineDescriptors = [
         create: (d) => ({
             replicate: {
                 key: "store",
-                snapshot: () => d.store.snapshot(),
+                snapshot: () => d.store.snapshot().filter(([, value]) => !holdsLiveCode(value)),
                 decode: (raw) => decodeEntries(raw),
-                hydrate: (data) => d.store.hydrate(data),
+                hydrate: (data) => {
+                    const incoming = data;
+                    const incomingKeys = new Set(incoming.map(([key]) => key));
+                    const localLive = d.store.snapshot().filter(([key, value]) => !incomingKeys.has(key) && holdsLiveCode(value));
+                    d.store.hydrate(localLive.length === 0 ? incoming : [...incoming, ...localLive]);
+                },
             },
         }),
     },
@@ -94,7 +125,7 @@ export const baselineDescriptors = [
     {
         key: "time",
         create: (d) => ({
-            save: {
+            replicate: {
                 key: "time",
                 snapshot: () => d.time.snapshot(),
                 decode: (raw) => {

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

@@ -4,7 +4,7 @@ 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 InventoryLayout, type InventorySet, type ItemTraits } 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";
@@ -35,6 +35,7 @@ export interface FeatureDeps {
     walletOf: (userId: string) => WalletState;
     setWallet: (userId: string, state: WalletState) => void;
     layouts: Record<string, InventoryLayout>;
+    itemTraits: ItemTraits;
     inventoryFor: (userId: string) => InventorySet<string>;
     ensureInstanceStats: (instanceId: string) => StatValueMap;
     seedUserPool: (userId: string, statId: string, pool: {

package/dist/runtime/descriptors/features.js

@@ -7,6 +7,7 @@ import { createChat } from "../../game/chat.js";
 import {} from "../../game/social.js";
 import { createTradeSystem } from "../../game/trade.js";
 import { createUnlocks } from "../../game/unlocks.js";
+import { putItem, } from "../../inventory/inventoryModel.js";
 import { createRoster } from "../../scene/roster.js";
 import { createConnectedPlayers } from "../../game/connectedPlayers.js";
 import { notifyAfter } from "../../store/changeSignal.js";
@@ -197,6 +198,23 @@ export const featureDescriptors = [
                         const result = d.inventoryFor(userId).put(inventoryId, itemId, count);
                         return result.status === "ok" ? null : { reason: result.reason };
                     },
+                    grantItems(userId, items) {
+                        const inventories = d.inventoryFor(userId);
+                        const staged = new Map();
+                        for (const entry of items) {
+                            const layout = d.layouts[entry.inventory];
+                            if (layout === undefined)
+                                return { reason: `unknown inventory "${entry.inventory}"` };
+                            const current = staged.get(entry.inventory) ?? inventories.state(entry.inventory);
+                            const result = putItem(current, layout, d.itemTraits, entry.item, entry.count);
+                            if (result.status !== "ok")
+                                return { reason: result.reason };
+                            staged.set(entry.inventory, result.state);
+                        }
+                        for (const [inventoryId, state] of staged)
+                            inventories.replaceState(inventoryId, state);
+                        return null;
+                    },
                     grantUnlock: (userId, unlockId) => d.feature("unlocks")?.grant(userId, unlockId),
                 },
                 hasUnlock: (userId, id) => d.feature("unlocks")?.has(userId, id) ?? false,