@jgengine/core 0.15.0-next.0 → 0.16.0

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 } : {}),
+    };
+}

package/dist/runtime/snapshot.d.ts

@@ -1,3 +1,4 @@
+import type { InventoryState } from "../inventory/inventoryModel.js";
 export declare const RUNTIME_SNAPSHOT_VERSION = 1;
 export type RuntimeEntityRow = {
     instanceId: string;
@@ -14,13 +15,20 @@ export type RuntimeEntityRow = {
     targetInstanceId?: string | null;
     userId?: string;
 };
+/**
+ * The persisted form of a placed `SceneObject`: identity, placement, per-instance state, and slot
+ * contents. Convert with `toRuntimeObjectRow`/`fromRuntimeObjectRow` (`runtime/objectRows`).
+ */
 export type RuntimeObjectRow = {
     instanceId: string;
     catalogId: string;
     position: [number, number, number];
     rotationY?: number;
     parentSpace?: string;
+    /** Opaque per-instance state; the persisted name for `SceneObject.state`. */
     flags?: Record<string, unknown>;
+    /** Container contents for a catalog `slotInventory` object. */
+    slots?: InventoryState;
 };
 export type RuntimeInventorySlot = {
     item: string;
@@ -93,3 +101,10 @@ export declare function splitProfilePlayer(player: RuntimePlayerRow): {
     persistent: RuntimePlayerRow;
     session: Record<string, unknown>;
 };
+/**
+ * Mark every player plus the server row dirty without bumping `revision` — the "write everything now"
+ * preparation a flush needs, because hydrating a snapshot from storage resets the dirty set to empty.
+ * Revision stays put so a flush cannot look like a mutation to the revision CAS.
+ * @internal
+ */
+export declare function markAllPlayersDirty(snapshot: GameRuntimeSnapshot): GameRuntimeSnapshot;

package/dist/runtime/snapshot.js

@@ -80,3 +80,15 @@ export function splitProfilePlayer(player) {
         session,
     };
 }
+/**
+ * Mark every player plus the server row dirty without bumping `revision` — the "write everything now"
+ * preparation a flush needs, because hydrating a snapshot from storage resets the dirty set to empty.
+ * Revision stays put so a flush cannot look like a mutation to the revision CAS.
+ * @internal
+ */
+export function markAllPlayersDirty(snapshot) {
+    return {
+        ...snapshot,
+        dirty: { ...snapshot.dirty, server: true, players: Object.keys(snapshot.players) },
+    };
+}

package/dist/scene/objectStore.d.ts

@@ -1,4 +1,5 @@
 import type { ModelAnimationConfig } from "../game/playableGame.js";
+import type { InventoryState } from "../inventory/inventoryModel.js";
 import type { EntityPosition } from "./entityStore.js";
 export interface ObjectVisual {
     scale?: number | readonly [number, number, number];
@@ -19,12 +20,29 @@ export interface SceneObject {
      * `resolveAuthoredObjects` → `placeAuthoredObjects`; `undefined` keeps the catalog-resolved default.
      */
     animation?: ModelAnimationConfig | "auto" | "none";
+    /**
+     * Opaque per-instance state for this placement — a chest's locked flag, a machine's fill level, the
+     * owner of a placed turret. Replicated and saved with the object through the `objects` snapshot
+     * module and round-trips as `RuntimeObjectRow.flags`, so a command may own it without the game
+     * hand-rolling a parallel store keyed by `instanceId`.
+     */
+    state?: Record<string, unknown>;
+    /**
+     * Container contents when this object's catalog entry declares `slotInventory`. Mutate through
+     * `ctx.scene.object.slots` rather than writing it directly — that path validates against the
+     * declared `accepts` and stack limits.
+     */
+    slots?: InventoryState;
 }
 export interface PlaceOptions {
     instanceId?: string;
     parentSpace?: string;
     rotation?: number;
     visual?: ObjectVisual;
+    /** Initial {@link SceneObject.state} for this placement. */
+    state?: Record<string, unknown>;
+    /** Initial {@link SceneObject.slots} contents; omit to start from the catalog `slotInventory` layout's empty slots. */
+    slots?: InventoryState;
     /** Per-placement rig animation override stored on the placed {@link SceneObject}; same shape as `ModelConfig.animation`. Omit to keep the catalog-resolved default. */
     animation?: ModelAnimationConfig | "auto" | "none";
     /** When `instanceId` is already placed: `"throw"` (default), `"replace"` (fresh placement over it — remount-safe world setup, #284.10), or `"keep"` (leave it untouched and return the id). */
@@ -39,6 +57,12 @@ export interface ObjectStore {
     move(instanceId: string, x: number, y: number, z: number): boolean;
     rotate(instanceId: string, rotationY: number): boolean;
     setVisual(instanceId: string, visual: ObjectVisual | undefined): boolean;
+    /** Replace {@link SceneObject.state} wholesale; `undefined` drops the field. Returns `false` when the instance is not placed. */
+    setState(instanceId: string, state: Record<string, unknown> | undefined): boolean;
+    /** Shallow-merge `patch` into {@link SceneObject.state}; a key set to `undefined` is removed. Returns `false` when the instance is not placed. */
+    patchState(instanceId: string, patch: Record<string, unknown>): boolean;
+    /** Replace {@link SceneObject.slots} wholesale; prefer `ctx.scene.object.slots` which validates against the catalog layout. */
+    setSlots(instanceId: string, slots: InventoryState | undefined): boolean;
     get(instanceId: string): SceneObject | null;
     list(filter?: ObjectListFilter): readonly SceneObject[];
     /** Stable-identity list of all placed object ids; identity changes only on place/remove, not on move/rotate/setVisual. Pair with {@link subscribeMembership} for membership-only React subscriptions (#625). */
@@ -50,6 +74,8 @@ export interface ObjectStore {
     /** Notified only when the object set changes (place/remove), never on move/rotate/setVisual — markers read live poses imperatively. */
     subscribeMembership(listener: () => void): () => void;
     snapshot(): readonly SceneObject[];
+    /** Replace the placed set with `objects` — the client half of `objects` replication; instances absent from the payload are removed. */
+    hydrate(objects: readonly SceneObject[]): void;
 }
 export declare function createObjectStore(): ObjectStore;
 export declare function objectVisualScale(visual: ObjectVisual | undefined): readonly [number, number, number];

package/dist/scene/objectStore.js

@@ -72,6 +72,8 @@ export function createObjectStore() {
                 ...(options.parentSpace !== undefined ? { parentSpace: options.parentSpace } : {}),
                 ...(options.visual !== undefined ? { visual: options.visual } : {}),
                 ...(options.animation !== undefined ? { animation: options.animation } : {}),
+                ...(options.state !== undefined ? { state: options.state } : {}),
+                ...(options.slots !== undefined ? { slots: options.slots } : {}),
             });
             indexAdd(instanceId, position);
             return instanceId;
@@ -105,15 +107,39 @@ export function createObjectStore() {
             const current = store.get(instanceId);
             if (!current)
                 return false;
-            store.set(instanceId, {
-                instanceId: current.instanceId,
-                catalogId: current.catalogId,
-                position: current.position,
-                rotationY: current.rotationY,
-                ...(current.parentSpace !== undefined ? { parentSpace: current.parentSpace } : {}),
-                ...(current.animation !== undefined ? { animation: current.animation } : {}),
-                ...(visual !== undefined ? { visual } : {}),
-            });
+            const { visual: _cleared, ...rest } = current;
+            store.set(instanceId, visual === undefined ? rest : { ...rest, visual });
+            return true;
+        },
+        setState(instanceId, state) {
+            const current = store.get(instanceId);
+            if (!current)
+                return false;
+            const { state: _cleared, ...rest } = current;
+            store.set(instanceId, state === undefined ? rest : { ...rest, state });
+            return true;
+        },
+        patchState(instanceId, patch) {
+            const current = store.get(instanceId);
+            if (!current)
+                return false;
+            const state = { ...current.state };
+            for (const [key, value] of Object.entries(patch)) {
+                if (value === undefined)
+                    delete state[key];
+                else
+                    state[key] = value;
+            }
+            const { state: _cleared, ...rest } = current;
+            store.set(instanceId, Object.keys(state).length === 0 ? rest : { ...rest, state });
+            return true;
+        },
+        setSlots(instanceId, slots) {
+            const current = store.get(instanceId);
+            if (!current)
+                return false;
+            const { slots: _cleared, ...rest } = current;
+            store.set(instanceId, slots === undefined ? rest : { ...rest, slots });
             return true;
         },
         get(instanceId) {
@@ -212,6 +238,22 @@ export function createObjectStore() {
         snapshot() {
             return store.arraySnapshot();
         },
+        hydrate(objects) {
+            const incoming = new Set(objects.map((object) => object.instanceId));
+            for (const current of store.arraySnapshot()) {
+                if (!incoming.has(current.instanceId)) {
+                    store.delete(current.instanceId);
+                    indexRemove(current.instanceId, current.position);
+                }
+            }
+            for (const object of objects) {
+                const current = store.get(object.instanceId);
+                if (current !== undefined)
+                    indexRemove(object.instanceId, current.position);
+                store.set(object.instanceId, object);
+                indexAdd(object.instanceId, object.position);
+            }
+        },
     };
 }
 export function objectVisualScale(visual) {

package/dist/world/buildingKit.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Binds the part slots `world/buildings` generates to real models, so a procedural building renders
+ * as an instanced asset kit instead of untextured blocks. Pure serializable data — core resolves
+ * bindings, the renderer loads them.
+ */
+import type { BuildingKitSlot, BuildingPartKind, BuildingVariantCounts, Vec3 } from "./buildings.js";
+/**
+ * How a kit model's native bounds are mapped onto the slot box `BuildingPartPlacement.scale`
+ * describes.
+ *
+ * - `stretch` — non-uniform scale to exactly fill the slot on all three axes. Right for tiling
+ *   panels (walls, shutters) whose art is meant to fill its bay.
+ * - `contain` — uniform scale so the model fits entirely inside the slot. Right for props that
+ *   must not distort (AC units, chimneys, roof clutter).
+ * - `cover` — uniform scale so the model covers the slot on its widest axis; may overhang.
+ * - `native` — no fit scaling; the model's authored size is used as-is.
+ */
+export type BuildingKitFit = "stretch" | "contain" | "cover" | "native";
+/**
+ * One bindable variant for a building part slot. `model` is an opaque reference the host resolves
+ * (an asset id, a pack-relative path, or a URL) — core never loads anything.
+ *
+ * Adjustments apply in slot-local space after `fit`: `x` runs along the facade, `y` is up, `z`
+ * points outward from the wall.
+ */
+export interface BuildingKitPart {
+    model: string;
+    fit?: BuildingKitFit;
+    offset?: Vec3;
+    /** Euler XYZ in radians, applied on top of the slot's facade rotation. */
+    rotation?: Vec3;
+    /** Multiplier applied after `fit`. */
+    scale?: Vec3;
+    tint?: string;
+    /**
+     * Quarter-turn the model when its long horizontal axis disagrees with the slot's, so a panel
+     * authored running along Z still tiles a bay that runs along X. Default true — modular kits do not
+     * agree on a facing convention, and a stretched panel that is 90° off is always wrong. Set false
+     * when a model's authored orientation is deliberate.
+     */
+    autoOrient?: boolean;
+}
+/**
+ * Binds a building's generated part slots to models. A kit is plain serializable data — scene
+ * documents can carry one — and is deliberately unopinionated about art direction: the engine ships
+ * the seam, games ship the bindings.
+ */
+export interface BuildingKit {
+    id: string;
+    /** Variants per part kind; `BuildingKitSlot.variant` indexes this list, wrapping. */
+    parts: Readonly<Partial<Record<BuildingPartKind, readonly BuildingKitPart[]>>>;
+    /** Overrides keyed by `BuildingKitSlot.key` (`${facade}.${kind}`); beats `parts` for that facade. */
+    slots?: Readonly<Record<string, readonly BuildingKitPart[]>>;
+    /** Kinds this kit deliberately drops — no mesh, and no box fallback either. */
+    omit?: readonly BuildingPartKind[];
+    /** Fit for parts that do not set their own. Defaults to `stretch`. */
+    fit?: BuildingKitFit;
+}
+/** A variant as authored: a bare model reference, or the full {@link BuildingKitPart} when it needs fit or transform tuning. */
+export type BuildingKitPartInput = string | BuildingKitPart;
+/** The authoring shape {@link defineBuildingKit} normalizes into a {@link BuildingKit}. */
+export interface BuildingKitInput {
+    id?: string;
+    parts: Readonly<Partial<Record<BuildingPartKind, readonly BuildingKitPartInput[]>>>;
+    slots?: Readonly<Record<string, readonly BuildingKitPartInput[]>>;
+    omit?: readonly BuildingPartKind[];
+    fit?: BuildingKitFit;
+}
+/**
+ * What a renderer should do with one generated part.
+ *
+ * `model` carries a resolved variant with its fit already defaulted; `box` means fall back to the
+ * engine's untextured block; `omit` means draw nothing.
+ */
+export type BuildingKitBinding = {
+    readonly type: "model";
+    readonly part: BuildingKitPart;
+    readonly fit: BuildingKitFit;
+} | {
+    readonly type: "box";
+} | {
+    readonly type: "omit";
+};
+/**
+ * Validates and normalizes a kit description, accepting bare model strings as single-field variants.
+ * Throws on empty variant lists so a typo fails at authoring time rather than silently falling back
+ * to untextured boxes.
+ *
+ * @capability building-kit bind generated facade part slots to real models instead of untextured blocks
+ */
+export declare function defineBuildingKit(input: BuildingKitInput): BuildingKit;
+/**
+ * Resolves one generated part against a kit. Pass the placement's `kind` and its `kit` slot; the
+ * slot's `variant` wraps around the bound list, so a kit may carry any number of variants
+ * independent of the generator's `variants` counts.
+ *
+ * Returns `box` when the kind is unbound — the renderer keeps drawing today's block, so a partial
+ * kit is a valid kit.
+ *
+ * @capability building-kit resolve one generated part to its bound model, a block fallback, or nothing
+ */
+export declare function resolveBuildingKitPart(kit: BuildingKit | undefined, kind: BuildingPartKind, slot?: BuildingKitSlot): BuildingKitBinding;
+/**
+ * The variant counts a kit actually supplies, shaped for `BuildingConfigInput.variants`. Feed this
+ * into `generateBuilding` so seeded picks spread across exactly the models the kit binds instead of
+ * indexing past them and wrapping unevenly.
+ *
+ * @capability building-kit bind generated facade part slots to real models instead of untextured blocks
+ */
+export declare function buildingKitVariantCounts(kit: BuildingKit): Partial<BuildingVariantCounts>;

package/dist/world/buildingKit.js

@@ -0,0 +1,93 @@
+const BOX = { type: "box" };
+const OMIT = { type: "omit" };
+const DEFAULT_FIT = "stretch";
+function normalizePart(input, where) {
+    const part = typeof input === "string" ? { model: input } : input;
+    if (typeof part.model !== "string" || part.model.length === 0) {
+        throw new Error(`Building kit ${where} has a variant with no model reference.`);
+    }
+    return part;
+}
+function normalizeList(list, where) {
+    if (list.length === 0) {
+        throw new Error(`Building kit ${where} binds an empty variant list. Bind at least one model, or add the kind to \`omit\` to drop it.`);
+    }
+    return list.map((entry) => normalizePart(entry, where));
+}
+/**
+ * Validates and normalizes a kit description, accepting bare model strings as single-field variants.
+ * Throws on empty variant lists so a typo fails at authoring time rather than silently falling back
+ * to untextured boxes.
+ *
+ * @capability building-kit bind generated facade part slots to real models instead of untextured blocks
+ */
+export function defineBuildingKit(input) {
+    const parts = {};
+    for (const [kind, list] of Object.entries(input.parts)) {
+        if (list === undefined)
+            continue;
+        parts[kind] = normalizeList(list, `"${input.id ?? "kit"}" part "${kind}"`);
+    }
+    const kit = {
+        id: input.id ?? "building-kit",
+        parts,
+        ...(input.omit === undefined ? {} : { omit: input.omit }),
+        ...(input.fit === undefined ? {} : { fit: input.fit }),
+    };
+    if (input.slots === undefined)
+        return kit;
+    const slots = {};
+    for (const [key, list] of Object.entries(input.slots)) {
+        slots[key] = normalizeList(list, `"${kit.id}" slot "${key}"`);
+    }
+    return { ...kit, slots };
+}
+function variantsFor(kit, kind, slotKey) {
+    if (slotKey !== undefined) {
+        const override = kit.slots?.[slotKey];
+        if (override !== undefined)
+            return override;
+    }
+    return kit.parts[kind];
+}
+/**
+ * Resolves one generated part against a kit. Pass the placement's `kind` and its `kit` slot; the
+ * slot's `variant` wraps around the bound list, so a kit may carry any number of variants
+ * independent of the generator's `variants` counts.
+ *
+ * Returns `box` when the kind is unbound — the renderer keeps drawing today's block, so a partial
+ * kit is a valid kit.
+ *
+ * @capability building-kit resolve one generated part to its bound model, a block fallback, or nothing
+ */
+export function resolveBuildingKitPart(kit, kind, slot) {
+    if (kit === undefined)
+        return BOX;
+    if (kit.omit?.includes(kind) === true)
+        return OMIT;
+    const variants = variantsFor(kit, kind, slot?.key);
+    if (variants === undefined || variants.length === 0)
+        return BOX;
+    const index = slot === undefined ? 0 : Math.abs(Math.trunc(slot.variant)) % variants.length;
+    const part = variants[index];
+    return { type: "model", part, fit: part.fit ?? kit.fit ?? DEFAULT_FIT };
+}
+/**
+ * The variant counts a kit actually supplies, shaped for `BuildingConfigInput.variants`. Feed this
+ * into `generateBuilding` so seeded picks spread across exactly the models the kit binds instead of
+ * indexing past them and wrapping unevenly.
+ *
+ * @capability building-kit bind generated facade part slots to real models instead of untextured blocks
+ */
+export function buildingKitVariantCounts(kit) {
+    const counts = {};
+    for (const [kind, list] of Object.entries(kit.parts)) {
+        if (list === undefined || list.length === 0)
+            continue;
+        // `roof`, `guardrail`, and `corner` have no variant knob on BuildingVariantCounts.
+        if (kind === "roof" || kind === "guardrail" || kind === "corner")
+            continue;
+        counts[kind] = list.length;
+    }
+    return counts;
+}