@jgengine/core 0.15.0 → 0.17.0

package/dist/movement/solidObstacles.js

@@ -0,0 +1,208 @@
+import { perContext } from "../runtime/perContext.js";
+import { resolveColliders } from "../scene/colliders.js";
+import { DEFAULT_OBSTACLE_PLAYER_RADIUS, resolveObstacleStep, } from "./movementModel.js";
+/**
+ * Broadphase reach floor (XZ): the `inBox` query indexes objects by their center *point*, so the query
+ * must extend past the walker by at least the largest blocking-collider extent or a wide object's edge
+ * is missed. Floored so default unit boxes stay covered.
+ */
+const OBSTACLE_MAX_HALF_EXTENT = 4;
+/**
+ * Hard cap on XZ broadphase reach. City lots ~12-17 m footprint need ~17-20 m after yaw expansion;
+ * beyond that we refuse to grow the query into a city-wide box (and rely on the outer AABB of each
+ * solid still blocking once its *center* is in range).
+ */
+const OBSTACLE_HORIZONTAL_CAP = 22;
+/**
+ * Vertical broadphase floor/cap. A walker only needs nearby ground props / step-ups — never full tower
+ * height. Using building height for Y was the Vice Isle pose killer: a 50 m tower turned `inBox` into
+ * a 100^3 empty cell walk every frame.
+ */
+const OBSTACLE_VERTICAL_FLOOR = 3;
+const OBSTACLE_VERTICAL_CAP = 8;
+/**
+ * Mesh compound `boxes` under this count are treated as intentional openings (archways). Above it we
+ * walk against the outer fitted AABB only — solid city buildings often ship dense box soups that
+ * multiply narrowphase cost without changing the blocked footprint.
+ */
+const MOVEMENT_MESH_BOX_BUDGET = 12;
+/** Feet-to-head span a walker is tested over — matches the player's, so both agree on what a wall is. */
+const WALKER_HEIGHT = 1.8;
+/** A fresh {@link ObstacleReachCache} for a caller that owns its own source. @internal */
+export function createObstacleReachCache() {
+    return { count: -1, value: { horizontal: OBSTACLE_MAX_HALF_EXTENT, vertical: OBSTACLE_VERTICAL_FLOOR } };
+}
+const reachCache = perContext(() => createObstacleReachCache());
+/**
+ * Largest blocking reach in the scene, split into horizontal vs vertical and hard-capped. Cached per
+ * ctx and recomputed when the object count changes — the broadphase box every consumer inflates by, so
+ * a wall wider than the query box can never be missed.
+ * @internal
+ */
+export function solidObstacleReach(ctx) {
+    return sourceObstacleReach(ctx.scene.object, reachCache(ctx));
+}
+/** {@link solidObstacleReach} against a bare source and caller-owned cache. @internal */
+export function sourceObstacleReach(source, cache) {
+    const objects = source.list();
+    if (cache.count === objects.length)
+        return cache.value;
+    let horizontal = OBSTACLE_MAX_HALF_EXTENT;
+    let vertical = OBSTACLE_VERTICAL_FLOOR;
+    for (const object of objects) {
+        const set = source.collidersOf(object.instanceId);
+        if (set === null)
+            continue;
+        for (const collider of resolveColliders(set)) {
+            if (!collider.blocks || collider.purpose !== "physical")
+                continue;
+            const shape = collider.shape;
+            const offset = shape.offset;
+            const ox = offset !== undefined ? Math.abs(offset[0]) : 0;
+            const oy = offset !== undefined ? Math.abs(offset[1]) : 0;
+            const oz = offset !== undefined ? Math.abs(offset[2]) : 0;
+            if (shape.kind === "sphere") {
+                horizontal = Math.max(horizontal, ox + oz + shape.radius);
+                vertical = Math.max(vertical, oy + shape.radius);
+            }
+            else {
+                // Horizontal bound sums both axes so any yaw of the box stays covered.
+                const h = shape.halfExtents;
+                horizontal = Math.max(horizontal, ox + oz + h[0] + h[2]);
+                vertical = Math.max(vertical, oy + h[1]);
+            }
+        }
+    }
+    const value = {
+        horizontal: Math.min(horizontal, OBSTACLE_HORIZONTAL_CAP),
+        vertical: Math.min(vertical, OBSTACLE_VERTICAL_CAP),
+    };
+    cache.count = objects.length;
+    cache.value = value;
+    return value;
+}
+/** Yaw-rotate an entity-local AABB about the object origin and re-fit it to an axis-aligned box, expressed
+ * as `min`/`max` relative to `position`. Conservative: the rotated box is grown to its enclosing AABB. */
+function yawExpandLocalBox(boxMin, boxMax, cos, sin) {
+    const centerX = (boxMin[0] + boxMax[0]) / 2;
+    const centerY = (boxMin[1] + boxMax[1]) / 2;
+    const centerZ = (boxMin[2] + boxMax[2]) / 2;
+    const halfX = (boxMax[0] - boxMin[0]) / 2;
+    const halfY = (boxMax[1] - boxMin[1]) / 2;
+    const halfZ = (boxMax[2] - boxMin[2]) / 2;
+    const rcX = centerX * cos + centerZ * sin;
+    const rcZ = -centerX * sin + centerZ * cos;
+    const rhX = Math.abs(halfX * cos) + Math.abs(halfZ * sin);
+    const rhZ = Math.abs(halfX * sin) + Math.abs(halfZ * cos);
+    return {
+        min: [rcX - rhX, centerY - halfY, rcZ - rhZ],
+        max: [rcX + rhX, centerY + halfY, rcZ + rhZ],
+    };
+}
+/** One blocking collider as a {@link CollisionObstacle}: a compound `boxes` obstacle for a mesh collider
+ * carrying a small sub-box set (openings), else a single half-extents/offset AABB. Yaw is applied by
+ * conservatively expanding each AABB to its rotated extent (mirroring `worldOffset`), so the obstruction
+ * never under-covers.
+ * @internal */
+export function obstacleFromCollider(collider, position, rotationY) {
+    const cos = Math.cos(rotationY);
+    const sin = Math.sin(rotationY);
+    const shape = collider.shape;
+    // Dense compound soups (city buildings) collapse to the outer fitted AABB for movement — openings
+    // only stay mesh-box accurate when the box count is small (arches, doorways).
+    if (shape.kind === "mesh" &&
+        shape.boxes !== undefined &&
+        shape.boxes.length > 0 &&
+        shape.boxes.length <= MOVEMENT_MESH_BOX_BUDGET) {
+        return {
+            position,
+            boxes: shape.boxes.map((b) => yawExpandLocalBox(b.min, b.max, cos, sin)),
+        };
+    }
+    let hx;
+    let hy;
+    let hz;
+    if (shape.kind === "sphere") {
+        hx = hy = hz = shape.radius;
+    }
+    else {
+        hx = shape.halfExtents[0];
+        hy = shape.halfExtents[1];
+        hz = shape.halfExtents[2];
+    }
+    const offset = shape.offset;
+    const ox = offset !== undefined ? offset[0] : 0;
+    const oy = offset !== undefined ? offset[1] : 0;
+    const oz = offset !== undefined ? offset[2] : 0;
+    return {
+        position,
+        // Rotate the offset by yaw (mirror of colliders.worldOffset), expand the extents to the rotated AABB.
+        offset: [ox * cos + oz * sin, oy, -ox * sin + oz * cos],
+        halfExtents: [Math.abs(hx * cos) + Math.abs(hz * sin), hy, Math.abs(hx * sin) + Math.abs(hz * cos)],
+    };
+}
+/**
+ * Every blocking physical obstacle overlapping the box `position` ± `reachX`/`reachZ`, read from the
+ * scene's resolved colliders.
+ *
+ * This is the engine's single answer to "what is solid here". The player resolver, a walking NPC, and
+ * anything else that has to stop at a wall read it rather than deriving their own set — three
+ * divergent notions of solid (engine colliders / game catalog flags / nothing at all) is what let a
+ * pedestrian stroll through the building the player cannot enter.
+ *
+ * @capability solid-obstacles the one blocking-geometry query the player resolver and NPC movers share
+ */
+export function solidObstaclesNear(ctx, position, reachX, reachZ, height = WALKER_HEIGHT) {
+    return sourceObstaclesNear(ctx.scene.object, solidObstacleReach(ctx), position, reachX, reachZ, height);
+}
+/** {@link solidObstaclesNear} against a bare source and an already-resolved reach. @internal */
+export function sourceObstaclesNear(source, reach, position, reachX, reachZ, height = WALKER_HEIGHT) {
+    const min = [
+        position[0] - reachX - reach.horizontal,
+        position[1] - reach.vertical,
+        position[2] - reachZ - reach.horizontal,
+    ];
+    const max = [
+        position[0] + reachX + reach.horizontal,
+        position[1] + height + reach.vertical,
+        position[2] + reachZ + reach.horizontal,
+    ];
+    const obstacles = [];
+    for (const object of source.inBox(min, max)) {
+        const set = source.collidersOf(object.instanceId);
+        if (set === null) {
+            // No resolved collider: preserve the default 1×1×1 box.
+            obstacles.push({ position: object.position });
+            continue;
+        }
+        for (const collider of resolveColliders(set)) {
+            if (!collider.blocks || collider.purpose !== "physical")
+                continue;
+            obstacles.push(obstacleFromCollider(collider, object.position, object.rotationY));
+        }
+    }
+    return obstacles;
+}
+/**
+ * Slide a walker's horizontal step against the same solid geometry that stops the player, returning the
+ * X/Z it may actually take this tick. A step into a wall is cut on the blocked axis and preserved on the
+ * other, exactly as {@link stepPlayerMovement} resolves the player's.
+ *
+ * Bounded by the same broadphase as the player's gather: one `inBox` query sized to this step, never a
+ * full-world scan, so it stays affordable per NPC per tick.
+ *
+ * @capability walker-solid-step slide an NPC's step against the geometry that blocks the player
+ */
+export function resolveWalkerStep(ctx, position, stepX, stepZ, options = {}) {
+    if (stepX === 0 && stepZ === 0)
+        return { stepX, stepZ };
+    const radius = options.radius ?? DEFAULT_OBSTACLE_PLAYER_RADIUS;
+    const obstacles = solidObstaclesNear(ctx, position, Math.abs(stepX) + radius, Math.abs(stepZ) + radius);
+    return slideStep(position, stepX, stepZ, obstacles, radius, options.stepUpHeight ?? 0);
+}
+/** {@link resolveWalkerStep} against an already-gathered obstacle set. @internal */
+export function slideStep(position, stepX, stepZ, obstacles, radius = DEFAULT_OBSTACLE_PLAYER_RADIUS, stepUpHeight = 0) {
+    if (obstacles.length === 0)
+        return { stepX, stepZ };
+    return resolveObstacleStep(position, stepX, stepZ, obstacles, radius, stepUpHeight);
+}

package/dist/multiplayer.d.ts

@@ -8,4 +8,5 @@ export { createPoseSyncGate, type PlayerPose, type PoseSyncTuning } from "./mult
 export { type EnsurePresenceResult, type PresenceActions, type PresenceFeeds, type PresenceSession, type PresenceTransport, } from "./multiplayer/presenceContract.js";
 export { type PoseSyncRules, type PresencePoseState } from "./multiplayer/presenceModel.js";
 export { createLocalVoiceTransport, createPushToTalk, type PushToTalkMode, type PushToTalkStatus, type VoiceParticipant, type VoiceRoute, type VoiceTransport, } from "./multiplayer/voiceContract.js";
+export { fromRuntimeObjectRow, toRuntimeObjectRow } from "./runtime/objectRows.js";
 export { type ReplicationPolicy } from "./runtime/worldProjection.js";

package/dist/multiplayer.js

@@ -8,4 +8,5 @@ export { createPoseSyncGate } from "./multiplayer/poseSyncGate.js";
 export {} from "./multiplayer/presenceContract.js";
 export {} from "./multiplayer/presenceModel.js";
 export { createLocalVoiceTransport, createPushToTalk, } from "./multiplayer/voiceContract.js";
+export { fromRuntimeObjectRow, toRuntimeObjectRow } from "./runtime/objectRows.js";
 export {} from "./runtime/worldProjection.js";

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

@@ -0,0 +1,60 @@
+import { type InventoryLayout, type InventorySet, type InventoryState, type ItemTraits } from "../../inventory/inventoryModel.js";
+import type { ObjectStore } from "../../scene/objectStore.js";
+/** Why an object slot mutation was refused — the instance, its catalog entry, the player inventory, or the declared `accepts`/capacity. */
+export type ObjectSlotRejection = "unknown-object" | "no-slot-inventory" | "unknown-inventory" | "no-space" | "wrong-kind" | "slot-occupied" | "invalid-slot" | "insufficient";
+/** Outcome of an object slot mutation: applied, or refused with a reason and no state change on either side. */
+export type ObjectSlotResult = {
+    status: "ok";
+} | {
+    status: "rejected";
+    reason: ObjectSlotRejection;
+};
+/** Which player inventory a transfer moves between, and what it moves. */
+export interface ObjectSlotTransfer {
+    instanceId: string;
+    userId: string;
+    inventoryId: string;
+    itemId: string;
+    /** Defaults to `1`. */
+    count?: number;
+    /** Explicit slot index **on the object**; omit to auto-place (transfer in) or drain the object's matching stacks (transfer out). */
+    slot?: number;
+}
+/**
+ * Per-instance container contents for placed objects whose catalog entry declares `slotInventory` —
+ * the engine side of "install a GPU into a rack", "put an item in a chest". Contents live on
+ * `SceneObject.slots`, so they replicate and save with the object rather than needing a game-owned
+ * table keyed by `instanceId`, and every mutation is validated against the declared `accepts` and
+ * stack limits.
+ *
+ * @capability object-slot-inventory placed objects hold validated per-instance container contents that replicate and save with the placement
+ */
+export interface SceneObjectSlots {
+    /** The catalog `slotInventory` layout for a placed instance, or `null` when its catalog entry declares none. */
+    layout(instanceId: string): InventoryLayout | null;
+    /** Live contents, defaulting to the layout's empty slots. `null` when the instance is unplaced or has no `slotInventory`. */
+    state(instanceId: string): InventoryState | null;
+    /** How many of `itemId` this object holds; `0` for an unplaced or slot-less instance. */
+    count(instanceId: string, itemId: string): number;
+    /** Add items directly, bypassing any player inventory — world seeding, loot generation, admin tools. */
+    put(instanceId: string, itemId: string, count?: number, options?: {
+        slot?: number;
+    }): ObjectSlotResult;
+    /** Remove items directly, bypassing any player inventory. */
+    take(instanceId: string, itemId: string, count?: number): ObjectSlotResult;
+    /** Move items from a player inventory into the object's slots; nothing is consumed if the object rejects them. */
+    transferIn(transfer: ObjectSlotTransfer): ObjectSlotResult;
+    /** Move items from the object's slots into a player inventory; nothing leaves the object if the inventory rejects them. */
+    transferOut(transfer: ObjectSlotTransfer): ObjectSlotResult;
+}
+/** @internal */
+export interface ObjectSlotsDeps {
+    objects: ObjectStore;
+    layoutOf: (instanceId: string) => InventoryLayout | null;
+    traits: () => ItemTraits;
+    hasInventory: (inventoryId: string) => boolean;
+    inventoryFor: (userId: string) => InventorySet<string> | null;
+    notify: () => void;
+}
+/** @internal */
+export declare function createObjectSlots(d: ObjectSlotsDeps): SceneObjectSlots;

package/dist/runtime/context/objectSlots.js

@@ -0,0 +1,103 @@
+import { countItem, createEmptyInventory, putItem, takeItem, } from "../../inventory/inventoryModel.js";
+/** Drain `count` of `itemId` from one explicit slot, so "pull the GPU out of rack slot 3" is expressible. */
+function takeFromSlot(state, slot, itemId, count) {
+    if (!Number.isInteger(slot) || slot < 0 || slot >= state.slots.length) {
+        return { status: "rejected", reason: "invalid-slot" };
+    }
+    const held = state.slots[slot];
+    if (held === null || held === undefined || held.itemId !== itemId || held.count < count) {
+        return { status: "rejected", reason: "insufficient" };
+    }
+    const slots = [...state.slots];
+    slots[slot] = held.count === count ? null : { itemId, count: held.count - count };
+    return { status: "ok", state: { slots } };
+}
+/** @internal */
+export function createObjectSlots(d) {
+    function resolve(instanceId) {
+        const object = d.objects.get(instanceId);
+        if (object === null)
+            return { status: "rejected", reason: "unknown-object" };
+        const layout = d.layoutOf(instanceId);
+        if (layout === null)
+            return { status: "rejected", reason: "no-slot-inventory" };
+        return { layout, state: object.slots ?? createEmptyInventory(layout) };
+    }
+    function playerInventory(transfer) {
+        if (!d.hasInventory(transfer.inventoryId))
+            return null;
+        return d.inventoryFor(transfer.userId);
+    }
+    function commit(instanceId, state) {
+        d.objects.setSlots(instanceId, state);
+        d.notify();
+        return { status: "ok" };
+    }
+    return {
+        layout(instanceId) {
+            return d.objects.get(instanceId) === null ? null : d.layoutOf(instanceId);
+        },
+        state(instanceId) {
+            const resolved = resolve(instanceId);
+            return "status" in resolved ? null : resolved.state;
+        },
+        count(instanceId, itemId) {
+            const resolved = resolve(instanceId);
+            return "status" in resolved ? 0 : countItem(resolved.state, itemId);
+        },
+        put(instanceId, itemId, count = 1, options) {
+            const resolved = resolve(instanceId);
+            if ("status" in resolved)
+                return resolved;
+            const result = putItem(resolved.state, resolved.layout, d.traits(), itemId, count, options);
+            if (result.status === "rejected")
+                return result;
+            return commit(instanceId, result.state);
+        },
+        take(instanceId, itemId, count = 1) {
+            const resolved = resolve(instanceId);
+            if ("status" in resolved)
+                return resolved;
+            const result = takeItem(resolved.state, itemId, count);
+            if (result.status === "rejected")
+                return result;
+            return commit(instanceId, result.state);
+        },
+        transferIn(transfer) {
+            const count = transfer.count ?? 1;
+            const resolved = resolve(transfer.instanceId);
+            if ("status" in resolved)
+                return resolved;
+            const inventory = playerInventory(transfer);
+            if (inventory === null)
+                return { status: "rejected", reason: "unknown-inventory" };
+            const options = transfer.slot === undefined ? undefined : { slot: transfer.slot };
+            const accepted = putItem(resolved.state, resolved.layout, d.traits(), transfer.itemId, count, options);
+            if (accepted.status === "rejected")
+                return accepted;
+            const removed = inventory.take(transfer.inventoryId, transfer.itemId, count);
+            if (removed.status === "rejected")
+                return removed;
+            return commit(transfer.instanceId, accepted.state);
+        },
+        transferOut(transfer) {
+            const count = transfer.count ?? 1;
+            const resolved = resolve(transfer.instanceId);
+            if ("status" in resolved)
+                return resolved;
+            const inventory = playerInventory(transfer);
+            if (inventory === null)
+                return { status: "rejected", reason: "unknown-inventory" };
+            const drained = transfer.slot === undefined
+                ? takeItem(resolved.state, transfer.itemId, count)
+                : takeFromSlot(resolved.state, transfer.slot, transfer.itemId, count);
+            if (drained.status === "rejected" || drained.state === undefined) {
+                return drained.status === "rejected" ? drained : { status: "rejected", reason: "insufficient" };
+            }
+            const given = inventory.put(transfer.inventoryId, transfer.itemId, count);
+            if (given.status === "rejected")
+                return given;
+            return commit(transfer.instanceId, drained.state);
+        },
+    };
+}

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

@@ -3,7 +3,7 @@ import type { GameFeatures } from "../../game/defineGame.js";
 import type { InventoryDeclaration } from "../../game/defineGame.js";
 import type { GameEvents } from "../../game/events.js";
 import { type Loadouts } from "../../game/loadout.js";
-import { type InventoryLayout, type InventorySet } from "../../inventory/inventoryModel.js";
+import { type InventoryLayout, type InventorySet, type ItemTraits } from "../../inventory/inventoryModel.js";
 import { type PoseState } from "../../movement/poseState.js";
 import { type Possession } from "../../scene/possession.js";
 import type { EntityStore } from "../../scene/entityStore.js";
@@ -28,6 +28,8 @@ export interface PlayerSubsystem {
     inventoryByUser: ReadonlyMap<string, InventorySet<string>>;
     inventoryFor: (userId: string) => InventorySet<string>;
     layouts: Record<string, InventoryLayout>;
+    /** Shared stack-limit/kind table for every declared inventory — also what object slot inventories validate against. */
+    itemTraits: ItemTraits;
     wallets: Map<string, WalletState>;
     walletOf: (userId: string) => WalletState;
     economy: GameContextEconomy;

package/dist/runtime/context/player.js

@@ -110,6 +110,7 @@ export function createPlayerSubsystem(d) {
         inventoryByUser,
         inventoryFor,
         layouts,
+        itemTraits: traits,
         wallets,
         walletOf,
         economy,

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

@@ -7,6 +7,7 @@ import { type Forms } from "../../scene/form.js";
 import { type EntityColliderSet, type MeasuredBounds } from "../../scene/colliders.js";
 import { type CollisionMeshSource } from "../../scene/collisionMesh.js";
 import { type ObjectStore } from "../../scene/objectStore.js";
+import type { InventorySet, ItemTraits } from "../../inventory/inventoryModel.js";
 import { type PaintLayer } from "../../scene/paintLayer.js";
 import { type SceneRaycastApi } from "../../scene/sceneRaycast.js";
 import { type SpatialApi } from "../../scene/spatial.js";
@@ -57,6 +58,14 @@ export interface SceneSubsystem {
     setOnAfterSpawn: (fn: (instanceId: string) => void) => void;
     /** Install post-despawn side effects (pose.clear) after player is constructed. */
     setOnAfterDespawn: (fn: (instanceId: string) => void) => void;
+    /** Hand the player subsystem's inventories to `sceneObjects.slots`, which is built before they exist. */
+    setInventoryAccess: (access: ObjectSlotInventoryAccess) => void;
+}
+/** @internal What `sceneObjects.slots` needs from the player subsystem to move items between a player and an object. */
+export interface ObjectSlotInventoryAccess {
+    traits: ItemTraits;
+    hasInventory: (inventoryId: string) => boolean;
+    inventoryFor: (userId: string) => InventorySet<string>;
 }
 /** @internal */
 export declare function createSceneSubsystem(d: SceneSubsystemDeps): SceneSubsystem;

package/dist/runtime/context/scene.js

@@ -6,10 +6,13 @@ import { fittedEntityColliders, fittedObjectColliders, hasMeshColliderShape, mea
 import { prepareCollisionMeshSource } from "../../scene/collisionMesh.js";
 import { raycastObjects, raycastObjectsAll } from "../../scene/objectQuery.js";
 import { createObjectStore, objectVisualScale } from "../../scene/objectStore.js";
+import { createObjectSlots } from "./objectSlots.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 { DEFAULT_OBSTACLE_PLAYER_RADIUS } from "../../movement/movementModel.js";
+import { createObstacleReachCache, slideStep, sourceObstacleReach, sourceObstaclesNear, } from "../../movement/solidObstacles.js";
 import { createTargeting } from "../../scene/targeting.js";
 import { notifyAfter } from "../../store/changeSignal.js";
 /** @internal */
@@ -49,11 +52,20 @@ export function createSceneSubsystem(d) {
         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 = {
+        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,
         grid: { cellSize: 8 },
         getVersion: () => spatialGeneration,
+        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(() => {
@@ -316,6 +328,15 @@ export function createSceneSubsystem(d) {
         return created;
     }
     const objectSelection = notifyAfter(createSelectionSet(), ["add", "remove", "toggle", "replace", "clear"], signalNotify);
+    let inventoryAccess = null;
+    const objectSlots = createObjectSlots({
+        objects,
+        layoutOf: (instanceId) => catalogObject(instanceId)?.slotInventory ?? null,
+        traits: () => inventoryAccess?.traits ?? { stackLimit: () => Number.POSITIVE_INFINITY },
+        hasInventory: (inventoryId) => inventoryAccess?.hasInventory(inventoryId) ?? false,
+        inventoryFor: (userId) => inventoryAccess?.inventoryFor(userId) ?? null,
+        notify: signalNotify,
+    });
     const sceneObjects = {
         ...objects,
         remove(instanceId) {
@@ -338,6 +359,7 @@ export function createSceneSubsystem(d) {
         reportBounds: reportObjectBounds,
         reportCollisionMesh: reportObjectCollisionMesh,
         selection: objectSelection,
+        slots: objectSlots,
     };
     return {
         entities,
@@ -372,5 +394,8 @@ export function createSceneSubsystem(d) {
         setOnAfterDespawn(fn) {
             onAfterDespawn = fn;
         },
+        setInventoryAccess(access) {
+            inventoryAccess = access;
+        },
     };
 }

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

@@ -4,6 +4,7 @@ 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 { ObjectStore } from "../../scene/objectStore.js";
 import type { Possession } from "../../scene/possession.js";
 import type { ObservableKeyedStore } from "../../store/observableKeyedStore.js";
 import type { SimClock } from "../../time/simClock.js";
@@ -13,6 +14,7 @@ import type { SnapshotModule } from "../worldSnapshot.js";
 export interface BaselineDeps {
     signalNotify: () => void;
     entities: EntityStore;
+    objects: ObjectStore;
     statsByInstance: Map<string, StatValueMap>;
     store: ObservableKeyedStore<unknown>;
     feed: GameFeed;
@@ -35,7 +37,7 @@ export interface BaselineBuild {
 }
 /**
  * Always-on counterpart to {@link featureDescriptors}: each baseline subsystem (entities, stats,
- * store, feed, inventory, economy, time, pose, possession, motion) owns its own serialization here
+ * store, feed, inventory, economy, time, pose, possession, motion, objects) 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

package/dist/runtime/descriptors/baseline.js

@@ -154,4 +154,15 @@ export const baselineDescriptors = [
             },
         }),
     },
+    {
+        key: "objects",
+        create: (d) => ({
+            replicate: {
+                key: "objects",
+                snapshot: () => d.objects.snapshot(),
+                decode: (raw) => decodeArray(raw),
+                hydrate: (data) => d.objects.hydrate(data),
+            },
+        }),
+    },
 ];

package/dist/runtime/gameContext.js

@@ -14,7 +14,7 @@ import {} from "../scene/entityStore.js";
 import { createChangeSignal, notifyAfter } from "../store/changeSignal.js";
 import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
 import { applyWorldSnapshot, composeWorldSnapshot, } from "./worldSnapshot.js";
-import { policyProjectsViewers, projectByVisibleIds, projectEntitiesForViewer, projectPerUserForViewer, visibleEntityIds, } from "./worldProjection.js";
+import { policyProjectsViewers, projectByVisibleIds, projectEntitiesForViewer, projectObjectsForViewer, projectPerUserForViewer, viewerOrigin, visibleEntityIds, } from "./worldProjection.js";
 import { createRuntimeSave } from "./runtimeSave.js";
 import { isOffline } from "./adapter.js";
 import { localSaveBackend, memorySaveBackend } from "../game/saveStore.js";
@@ -119,6 +119,11 @@ export function createGameContext(options) {
     });
     const { inventoryIds, inventoryByUser, inventoryFor, layouts, wallets, walletOf, economy, putIntoAnyInventory, playerStatsFor, pose, possession, motionByUser, motionFor, loadouts, seedUserPool, } = playerSys;
     scene.setOnAfterDespawn((instanceId) => pose.clear(instanceId));
+    scene.setInventoryAccess({
+        traits: playerSys.itemTraits,
+        hasInventory: (inventoryId) => layouts[inventoryId] !== undefined,
+        inventoryFor,
+    });
     // Built-in inventory mutation commands so a HUD grid drives moves/splits through the notifying
     // command path (a raw InventorySet mutation would not re-render React). Each resolves the acting
     // user's own inventory, so it respects `privatePerUser` replication.
@@ -264,6 +269,7 @@ export function createGameContext(options) {
     const baselineDeps = {
         signalNotify: signal.notify,
         entities,
+        objects,
         statsByInstance,
         store,
         feed,
@@ -293,6 +299,9 @@ export function createGameContext(options) {
         if (aoiRadius !== undefined && key === "stats") {
             return typedProject((data, viewer, world) => projectByVisibleIds(data, visibleEntityIds((world["entities"] ?? []), viewer, aoiRadius)));
         }
+        if (aoiRadius !== undefined && key === "objects") {
+            return typedProject((data, viewer, world) => projectObjectsForViewer(data, viewerOrigin(world, viewer), aoiRadius));
+        }
         if (replication?.privatePerUser === true && key === "inventory") {
             return typedProject((data, viewer) => projectPerUserForViewer(data, viewer));
         }

package/dist/runtime/gameContextTypes.d.ts

@@ -23,6 +23,7 @@ import type { Social } from "../game/social.js";
 import type { TradeField, TradeSystem } from "../game/trade.js";
 import type { Unlocks } from "../game/unlocks.js";
 import type { InventoryLayout, InventorySet } from "../inventory/inventoryModel.js";
+import type { SceneObjectSlots } from "./context/objectSlots.js";
 import type { ContextVerb } from "../interaction/contextMenu.js";
 import type { ProximityPrompt } from "../interaction/proximityPrompt.js";
 import type { ItemUseHandler, ItemUseInput, ItemUseRejection, ItemUseResult } from "../item/use.js";
@@ -87,6 +88,11 @@ export interface GameContextObjectEntry {
     breakable?: false | {
         baseBreakTime: number;
     };
+    /**
+     * Declares this object a container: every placement gets its own slots, held on `SceneObject.slots`
+     * and mutated through `ctx.scene.object.slots`, which enforces the declared `slots` count and
+     * `accepts` kind filter.
+     */
     slotInventory?: InventoryLayout;
     /** Right-click context-menu verbs for this object (#31). */
     verbs?: readonly ContextVerb[];
@@ -174,6 +180,13 @@ export interface SceneObjectContext extends ObjectStore {
      * (`@jgengine/shell/world/WorldHud`).
      */
     selection: SelectionSet;
+    /**
+     * Per-instance container contents for objects whose catalog entry declares {@link GameContextObjectEntry.slotInventory}
+     * — chests, racks, machines. Contents live on `SceneObject.slots`, so they replicate and save with
+     * the placement, and `transferIn`/`transferOut` move items to and from a player inventory with the
+     * declared `accepts` and stack limits enforced.
+     */
+    slots: SceneObjectSlots;
 }
 export interface FloatTextInput {
     instanceId?: string;

package/dist/runtime/gameRuntime.d.ts

@@ -37,6 +37,12 @@ export type HydrateInput = {
 export type GameRuntime = {
     gameId: string;
     save: SaveConfig;
+    /**
+     * Whether this runtime declares `loop.onTick`. A host's tick cron reads it to skip hydrating and
+     * persisting a server whose `tick` is a no-op by construction — the difference between a world that
+     * costs a full read/write every second while idle and one that costs nothing.
+     */
+    hasTick: boolean;
     hydrate: (input: HydrateInput) => GameRuntimeSnapshot;
     runCommand: (snapshot: GameRuntimeSnapshot, actorUserId: string, commandName: string, input: unknown) => ReturnType<typeof runCommand>;
     tick: (snapshot: GameRuntimeSnapshot, dtSeconds: number) => GameRuntimeSnapshot;

package/dist/runtime/gameRuntime.js

@@ -7,6 +7,7 @@ export function createGameRuntime(definition) {
     return {
         gameId: definition.gameId,
         save: definition.save,
+        hasTick: loop?.onTick !== undefined,
         hydrate(input) {
             let current = createRuntimeSnapshot({
                 gameId: input.gameId,