@jgengine/core 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -34,6 +34,38 @@ At publish, rename this heading to the new version and mirror the entries into
 
 ### Fixed
 
+## 0.16.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.16.0`:** `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.13.0`; `@jgengine/github` is `0.3.0`.
+- **Placed objects now replicate.** `objects` joined the always-on baseline snapshot modules, so `ctx.hydrate` replaces the client's placed object set with the host's, the way `entities` already did. A game whose peers all run the same authored placement is unaffected; a game that places props on the client only, after hydrate, must move that placement to the host or keep it out of `ctx.scene.object`.
+
+### Changed
+
+- **`GeneratedBuilding`'s `kit` prop is now the `BuildingKit`**; the per-part React escape hatch it used to name moved to `partRenderer`, so `kit` means the same thing on `GeneratedBuilding` and `InstancedBuildings`. Rename the prop if you passed a `BuildingKitRenderer`.
+
+### Added
+
+- **`modelLoadFallbacks()` from `@jgengine/shell/render/modelLoad`** lists every model the shared loader diagnosed as broken and replaced with a magenta placeholder. A placeholder was only ever a console warning, so a shipped game could render one in its starting area and nobody found out until someone looked at a screenshot; a capture host or smoke test can now require the list to be empty. `clearModelLoadFallbacks()` resets it between runs.
+- **`worldHealthBars.occlude` / `WorldHealthBars`+`WorldNameplates` `occlude` prop.** World bars and nameplates are a screen-space overlay drawn outside the WebGL depth buffer, so nothing in the scene can hide them and an enemy's health bar reads straight through the building it stands behind. Set `occlude: true` to drop a bar when world geometry blocks the line from the player to the entity. Default `false` preserves the always-visible behaviour every shipped game currently relies on.
+
+- **`DustField` + `WeatherLayer` mode `"dust"` (`@jgengine/shell/weather`) — wind-borne particulate.** `WeatherLayer` could only do `clear`/`rain`/`snow`/`mixed`, so an arid, volcanic, ashen, or blown-out world had no way to put anything in the air. Dust drifts on horizontal wind with a slow vertical bob rather than falling; `groundBias` packs density toward the surface, motes fade near the top of the volume so recycled ones do not pop against the sky, and faster motes ride higher. Set `dustAlways` to keep it in the air alongside rain or snow instead of replacing them. Defaults `DEFAULT_DUST_COUNT`/`DEFAULT_DUST_DENSITY` sit beside the rain and snow pair.
+
+- **Authored `city` volumes render their near-LOD facades with a `BuildingKit`.** `CityRules.buildingKit` names a kit; a game registers the bound art with `registerBuildingKit(kit)` from `@jgengine/shell/structures/buildingKitRegistry` and the scene document carries only the name, so a city stays portable and free of model paths. Unset or unknown names keep the palette blocks. This puts the whole `city` primitive — not just the `building()` feature — on the kit path.
+- **`BuildingKit` from `@jgengine/core/world/buildingKit`** binds a generated building's facade part slots to real models, so procedural buildings render as an instanced asset kit instead of untextured blocks. `defineBuildingKit({ parts: { wall: ["Wall_A.glb", …] } })` maps a part kind — or a `${facade}.${kind}` slot — to ordered variants that `kit.variant` indexes, with `fit`/`offset`/`rotation`/`scale`/`tint`/`autoOrient` per variant. Kinds a kit leaves unbound keep rendering the palette block, so a partial kit is a valid kit, and `omit` drops a kind entirely. Pass one through `building({ kit })` or straight to `InstancedBuildings`; `buildingKitVariantCounts(kit)` feeds `generateBuilding` so its seeded picks span exactly the models the kit binds.
+- **`generateBuilding`, `generateBuildingDistrict`, and `createBuildingConfig` are now documented public API** (`@jgengine/core/world/buildings`) and appear in `capabilities.md` under `building-generator`.
+- **`capture.views` on `defineGame`** — named framings (`GameCaptureView`: `look`, `lookFrom`, `spawn`, `state`, `run`, `settleMs`) that `shoot <game> --view <name>` and `drive --view <name>` replay exactly, so a before/after pair is the same view by construction. `shoot <game> --list-views` prints what a game declares; an unknown name fails listing them, and any explicit capture flag still wins over the view's value.
+- **`modelLoadIdleMs()` from `@jgengine/shell/render/modelLoad`** reports how long the shared GLB loader has been idle (`0` while a model is in flight). Capture hosts wait on it instead of guessing a settle delay, so an establishing shot no longer races streaming models.
+- **Per-instance state on placed objects** — `SceneObject.state` (opaque `Record`), set through `ctx.scene.object.setState`/`patchState`/`place({ state })`. It survives move/rotate/setVisual, replicates and saves with the object, and round-trips as `RuntimeObjectRow.flags` via `toRuntimeObjectRow`/`fromRuntimeObjectRow` (`@jgengine/core/multiplayer`). A chest's locked flag or a machine's fill level no longer needs a game-owned map keyed by `instanceId`.
+- **`slotInventory` is a working feature** — `ctx.scene.object.slots` gives objects whose catalog entry declares it real per-instance container contents: `layout`/`state`/`count`, `put`/`take`, and `transferIn`/`transferOut` between a player inventory and the object, all validated against the declared slot count, `accepts` kind filter, and stack limits, with neither side mutated on a rejection. Contents live on `SceneObject.slots`, so they replicate and save with the placement.
+- **`loadServerSnapshot` and `persistServerSnapshot` are public** (`@jgengine/convex/server`), and `createGameServerFunctions` also returns `helpers` (`loadSnapshot`, `applyCommand`, `persistSnapshot`, `runCommand`) bound to the same runtimes and auth mode. A host mutation can now pair snapshot work with its own table writes in one transaction; the registered `runCommand` mutation delegates to `helpers.runCommand`, so there is one implementation.
+
+### Fixed
+
+- **Open storefronts are no longer holes through the building.** `generateBuilding` emitted an open ground-floor store as a lone `storefront` panel with no wall behind it, while every upper-floor window was correctly backed by one. Storefront and window materials render at 0.56 opacity and a generated building is a hollow shell, so those bays let you see straight through the building to the world beyond — and open stores only land on the street-facing facade, so a row of shops along a road was the worst case. The bay now emits its wall first, exactly as an upper floor does.
+- **`joinServer`, `flushSave`, `flushDirtyServers`, and the `auto` autosave can write player profiles again.** All four cleared the snapshot's dirty set before handing it to the persist plan, which gates profile writes on exactly that set — so the functions named "flush" flushed the server row and chunks only, and an `onNewPlayer` grant (starting money, starting items) never reached `jgPlayerProfiles`. `joinServer` now persists the snapshot it just marked; the flush paths mark every player dirty first, since hydrating from storage resets the dirty set. `planServerPersist` also clears `dirtyAt` once everything outstanding is written, so a successful flush stops autosave from re-firing forever, and a profile patch no longer clobbers a host-maintained `dirtyAt`.
+
 ## 0.15.0
 
 ### Migrate

package/dist/game/playableGame.d.ts

@@ -340,6 +340,33 @@ export interface PresentationEffectsConfig {
     shake?: boolean;
 }
 /** How a screenshot host reaches live gameplay in this game — the data behind `shoot --mode play`. */
+/**
+ * One named framing in {@link GameCaptureConfig.views}: everything about a capture except the host-side
+ * viewport (`--device`, `--size`) and `--mode`, which the runner routes on before the game module loads.
+ * Every field mirrors the equivalent capture flag, and an explicit flag on the command line wins over the
+ * shot's value so a declared framing stays a starting point rather than a cage.
+ */
+export interface GameCaptureView {
+    /** One line naming what this shot is for — printed by `shoot <game> --list-views`. */
+    description?: string;
+    /** `--look`: `x,z`, `x,y,z`, `@marker:<id>`, or `@entity:<id>`. */
+    look?: string;
+    /** `--look-from`: `dist[,height[,angle]]`. */
+    lookFrom?: string;
+    /** `--spawn`: `x,y,z` or `x,y,z,yaw`, for a shot framed from the player's vantage instead of a detached camera. */
+    spawn?: string;
+    /** `--state`: a {@link GameCaptureConfig.states} entry to reach before capturing. */
+    state?: string;
+    /** `--run`: commands to dispatch before capturing, when the shot needs staging no declared state covers. */
+    run?: readonly string[];
+    /** `--settle`: milliseconds to wait before the frame, for a shot behind an animation. */
+    settleMs?: number;
+}
+/**
+ * How a game makes itself screenshottable: the commands that reach live play or a named screen, the
+ * framings worth re-capturing, and the progress metrics a bot playtest samples. Declaring these once
+ * is what lets a capture host reproduce a view instead of re-deriving it by hand every run.
+ */
 export interface GameCaptureConfig {
     /**
      * Commands run (in order, via `ctx.game.commands.run`) right after boot when a capture host requests the
@@ -363,6 +390,13 @@ export interface GameCaptureConfig {
         name: string;
         input?: unknown;
     })[]>;
+    /**
+     * Named framings worth re-capturing — the views a reviewer actually asks about (`street`, `keep-exterior`,
+     * `boss-arena`), each pinning the camera, the staging, and the settle for that shot. `shoot <game> --view <name>`
+     * reproduces one exactly, so a before/after pair is the same framing by construction instead of two hand-typed
+     * flag sets that drifted. An unknown name fails the capture listing the declared views.
+     */
+    views?: Record<string, GameCaptureView>;
     /** Extra milliseconds the capture host waits after `play` commands before taking the play-mode screenshot — cover an intro cinematic or spawn-in fade. Default 2500. */
     settleMs?: number;
     /** Bot-playtest read hook: maps live game state to a flat vector of numeric progress metrics the `drive --playtest` harness samples over time (e.g. `{ x, z, score, phase }`). Genre-agnostic — "progress" is whatever the game reports; the engine stays neutral. The harness watches these numbers move under scripted input: any metric changing beyond an epsilon counts as forward progress, all metrics flat past the softlock threshold under active input flags a softlock. Return every value that should count as advancing; omit to opt the game out of the playtest rung. */
@@ -422,6 +456,8 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
         statId?: string;
         roles?: readonly CatalogEntityRole[];
         maxDistance?: number;
+        /** Hide a bar when world geometry stands between the player and the entity. These bars are a screen-space overlay outside the depth buffer, so by default they draw through walls. Default false. */
+        occlude?: boolean;
     };
     /**
      * Opt in to billboarded nameplates (name + optional HP bar) floating over non-local entities — the

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.15.0";
+export declare const VERSION = "0.16.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];

package/dist/meta/changelog.js

@@ -1,7 +1,29 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.15.0";
+export const VERSION = "0.16.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.16.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.16.0`: `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.13.0`; `@jgengine/github` is `0.3.0`.",
+            "Placed objects now replicate. `objects` joined the always-on baseline snapshot modules, so `ctx.hydrate` replaces the client's placed object set with the host's, the way `entities` already did. A game whose peers all run the same authored placement is unaffected; a game that places props on the client only, after hydrate, must move that placement to the host or keep it out of `ctx.scene.object`.",
+        ],
+        added: [
+            "`worldHealthBars.occlude` / `WorldHealthBars`+`WorldNameplates` `occlude` prop. World bars and nameplates are a screen-space overlay drawn outside the WebGL depth buffer, so nothing in the scene can hide them and an enemy's health bar reads straight through the building it stands behind. Set `occlude: true` to drop a bar when world geometry blocks the line from the player to the entity. Default `false` preserves the always-visible behaviour every shipped game currently relies on.",
+            "`DustField` + `WeatherLayer` mode `\"dust\"` (`@jgengine/shell/weather`) \u2014 wind-borne particulate. `WeatherLayer` could only do `clear`/`rain`/`snow`/`mixed`, so an arid, volcanic, ashen, or blown-out world had no way to put anything in the air. Dust drifts on horizontal wind with a slow vertical bob rather than falling; `groundBias` packs density toward the surface, motes fade near the top of the volume so recycled ones do not pop against the sky, and faster motes ride higher. Set `dustAlways` to keep it in the air alongside rain or snow instead of replacing them. Defaults `DEFAULT_DUST_COUNT`/`DEFAULT_DUST_DENSITY` sit beside the rain and snow pair.",
+            "Authored `city` volumes render their near-LOD facades with a `BuildingKit`. `CityRules.buildingKit` names a kit; a game registers the bound art with `registerBuildingKit(kit)` from `@jgengine/shell/structures/buildingKitRegistry` and the scene document carries only the name, so a city stays portable and free of model paths. Unset or unknown names keep the palette blocks. This puts the whole `city` primitive \u2014 not just the `building()` feature \u2014 on the kit path.",
+            "`BuildingKit` from `@jgengine/core/world/buildingKit` binds a generated building's facade part slots to real models, so procedural buildings render as an instanced asset kit instead of untextured blocks. `defineBuildingKit({ parts: { wall: [\"Wall_A.glb\", \u2026] } })` maps a part kind \u2014 or a `${facade}.${kind}` slot \u2014 to ordered variants that `kit.variant` indexes, with `fit`/`offset`/`rotation`/`scale`/`tint`/`autoOrient` per variant. Kinds a kit leaves unbound keep rendering the palette block, so a partial kit is a valid kit, and `omit` drops a kind entirely. Pass one through `building({ kit })` or straight to `InstancedBuildings`; `buildingKitVariantCounts(kit)` feeds `generateBuilding` so its seeded picks span exactly the models the kit binds.",
+            "`generateBuilding`, `generateBuildingDistrict`, and `createBuildingConfig` are now documented public API (`@jgengine/core/world/buildings`) and appear in `capabilities.md` under `building-generator`.",
+            "`capture.views` on `defineGame` \u2014 named framings (`GameCaptureView`: `look`, `lookFrom`, `spawn`, `state`, `run`, `settleMs`) that `shoot <game> --view <name>` and `drive --view <name>` replay exactly, so a before/after pair is the same view by construction. `shoot <game> --list-views` prints what a game declares; an unknown name fails listing them, and any explicit capture flag still wins over the view's value.",
+            "`modelLoadIdleMs()` from `@jgengine/shell/render/modelLoad` reports how long the shared GLB loader has been idle (`0` while a model is in flight). Capture hosts wait on it instead of guessing a settle delay, so an establishing shot no longer races streaming models.",
+            "Per-instance state on placed objects \u2014 `SceneObject.state` (opaque `Record`), set through `ctx.scene.object.setState`/`patchState`/`place({ state })`. It survives move/rotate/setVisual, replicates and saves with the object, and round-trips as `RuntimeObjectRow.flags` via `toRuntimeObjectRow`/`fromRuntimeObjectRow` (`@jgengine/core/multiplayer`). A chest's locked flag or a machine's fill level no longer needs a game-owned map keyed by `instanceId`.",
+            "`slotInventory` is a working feature \u2014 `ctx.scene.object.slots` gives objects whose catalog entry declares it real per-instance container contents: `layout`/`state`/`count`, `put`/`take`, and `transferIn`/`transferOut` between a player inventory and the object, all validated against the declared slot count, `accepts` kind filter, and stack limits, with neither side mutated on a rejection. Contents live on `SceneObject.slots`, so they replicate and save with the placement.",
+            "`loadServerSnapshot` and `persistServerSnapshot` are public (`@jgengine/convex/server`), and `createGameServerFunctions` also returns `helpers` (`loadSnapshot`, `applyCommand`, `persistSnapshot`, `runCommand`) bound to the same runtimes and auth mode. A host mutation can now pair snapshot work with its own table writes in one transaction; the registered `runCommand` mutation delegates to `helpers.runCommand`, so there is one implementation.",
+        ],
+        changed: [
+            "`GeneratedBuilding`'s `kit` prop is now the `BuildingKit`; the per-part React escape hatch it used to name moved to `partRenderer`, so `kit` means the same thing on `GeneratedBuilding` and `InstancedBuildings`. Rename the prop if you passed a `BuildingKitRenderer`.",
+        ],
+        removed: [],
+    },
     "0.15.0": {
         migrate: [
             "Bump lockstep SDK packages to ^0.15.0: @jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}. CLI jgengine is 0.12.0; @jgengine/github is 0.2.0.",

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,6 +6,7 @@ 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";
@@ -316,6 +317,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 +348,7 @@ export function createSceneSubsystem(d) {
         reportBounds: reportObjectBounds,
         reportCollisionMesh: reportObjectCollisionMesh,
         selection: objectSelection,
+        slots: objectSlots,
     };
     return {
         entities,
@@ -372,5 +383,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

@@ -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,

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/hostPersistence.js

@@ -147,6 +147,8 @@ export function planServerPersist(server, snapshot, save, now) {
     const leaderboard = drained.increments.map((entry) => entry.scope === "server" && entry.serverId === undefined
         ? { ...entry, serverId: server.serverId }
         : entry);
+    const canWritePlayers = isSaveEnabled(save) && saveScopeIncludesPlayer(save.scope);
+    const canWriteChunks = isSaveEnabled(save) && saveScopeIncludesChunks(save.scope);
     const sessionPlayers = {};
     const profiles = [];
     for (const userId of Object.keys(snapshot.players)) {
@@ -155,9 +157,7 @@ export function planServerPersist(server, snapshot, save, now) {
             continue;
         const { persistent, session } = splitProfilePlayer(player);
         sessionPlayers[userId] = { ...persistent, session };
-        if (isSaveEnabled(save) &&
-            saveScopeIncludesPlayer(save.scope) &&
-            snapshot.dirty.players.includes(userId)) {
+        if (canWritePlayers && snapshot.dirty.players.includes(userId)) {
             profiles.push({
                 userId,
                 gameId: server.gameId,
@@ -169,7 +169,7 @@ export function planServerPersist(server, snapshot, save, now) {
     }
     const chunks = [];
     const deletedChunks = [];
-    if (isSaveEnabled(save) && saveScopeIncludesChunks(save.scope)) {
+    if (canWriteChunks) {
         for (const chunkKey of snapshot.dirty.chunks) {
             const chunk = snapshot.chunks[chunkKey];
             if (chunk) {
@@ -180,13 +180,17 @@ export function planServerPersist(server, snapshot, save, now) {
             }
         }
     }
+    // Server state is written unconditionally, so only unwritable player/chunk dirt keeps the row dirty;
+    // anything else would make shouldAutoSave re-fire forever after a successful full flush.
+    const unwritten = (snapshot.dirty.players.length > 0 && !canWritePlayers) ||
+        (snapshot.dirty.chunks.length > 0 && !canWriteChunks);
     return {
         server: {
             ...server,
             serverState,
             sessionPlayers,
             revision: snapshot.revision,
-            dirtyAt: snapshot.dirty.server || snapshot.dirty.players.length > 0 ? now : server.dirtyAt,
+            dirtyAt: unwritten ? (server.dirtyAt ?? now) : undefined,
             updatedAt: now,
             lastSavedAt: now,
         },

package/dist/runtime/objectRows.d.ts

@@ -0,0 +1,17 @@
+import type { SceneObject } from "../scene/objectStore.js";
+import type { RuntimeObjectRow } from "./snapshot.js";
+/**
+ * Convert a live placed object into its persisted row — the bridge between `ctx.scene.object` and
+ * `GameRuntimeSnapshot.server.objects`/`chunks[].objects`. Per-instance `state` is carried as
+ * `flags`. Presentation overrides (`visual`, `animation`) are catalog- and authoring-resolved and
+ * deliberately stay off the persisted row — put anything a command must own in `state`.
+ *
+ * @capability placed-object-rows a placed object's per-instance state and container contents convert to and from the persisted snapshot row a host stores
+ */
+export declare function toRuntimeObjectRow(object: SceneObject): RuntimeObjectRow;
+/**
+ * Inverse of {@link toRuntimeObjectRow}: rebuild the live placed object a host persisted.
+ *
+ * @capability placed-object-rehydrate rebuild live placed objects, with their state and slot contents, from persisted snapshot rows
+ */
+export declare function fromRuntimeObjectRow(row: RuntimeObjectRow): SceneObject;

package/dist/runtime/objectRows.js

@@ -0,0 +1,35 @@
+/**
+ * Convert a live placed object into its persisted row — the bridge between `ctx.scene.object` and
+ * `GameRuntimeSnapshot.server.objects`/`chunks[].objects`. Per-instance `state` is carried as
+ * `flags`. Presentation overrides (`visual`, `animation`) are catalog- and authoring-resolved and
+ * deliberately stay off the persisted row — put anything a command must own in `state`.
+ *
+ * @capability placed-object-rows a placed object's per-instance state and container contents convert to and from the persisted snapshot row a host stores
+ */
+export function toRuntimeObjectRow(object) {
+    return {
+        instanceId: object.instanceId,
+        catalogId: object.catalogId,
+        position: [object.position[0], object.position[1], object.position[2]],
+        rotationY: object.rotationY,
+        ...(object.parentSpace !== undefined ? { parentSpace: object.parentSpace } : {}),
+        ...(object.state !== undefined ? { flags: object.state } : {}),
+        ...(object.slots !== undefined ? { slots: object.slots } : {}),
+    };
+}
+/**
+ * Inverse of {@link toRuntimeObjectRow}: rebuild the live placed object a host persisted.
+ *
+ * @capability placed-object-rehydrate rebuild live placed objects, with their state and slot contents, from persisted snapshot rows
+ */
+export function fromRuntimeObjectRow(row) {
+    return {
+        instanceId: row.instanceId,
+        catalogId: row.catalogId,
+        position: [row.position[0], row.position[1], row.position[2]],
+        rotationY: row.rotationY ?? 0,
+        ...(row.parentSpace !== undefined ? { parentSpace: row.parentSpace } : {}),
+        ...(row.flags !== undefined ? { state: row.flags } : {}),
+        ...(row.slots !== undefined ? { slots: row.slots } : {}),
+    };
+}