@jgengine/core 0.15.0 → 0.17.0

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/scene/spatial.d.ts

@@ -17,6 +17,12 @@ export interface MoveTowardOptions {
     speed: number;
     stopDistance?: number;
     dt: number;
+    /**
+     * Slide the step against the solid geometry that blocks the player instead of lerping through it
+     * (default `true` wherever the runtime wires a resolver). Set `false` for a mover that is meant to
+     * ignore the world — a flier, a camera rig, a decorative drift.
+     */
+    avoidSolids?: boolean;
 }
 export interface SpatialGridOptions {
     cellSize: number;
@@ -37,6 +43,16 @@ export interface SpatialApiOptions {
     grid?: SpatialGridOptions | false;
     /** When this number changes between queries, the grid rebuilds without an explicit `invalidate()`. */
     getVersion?: () => number;
+    /**
+     * Slide a horizontal step against the scene's solid geometry, returning the step actually allowed.
+     * Wired by the runtime to the same blocking-collider query the player resolver reads, so a chaser
+     * calling `moveToward` stops at the wall the player stops at. Omitted (tests, bare indexes) leaves
+     * `moveToward` a pure lerp.
+     */
+    resolveStep?: (position: EntityPosition, stepX: number, stepZ: number) => {
+        stepX: number;
+        stepZ: number;
+    };
 }
 export interface SpatialApi {
     distance(aInstanceId: string, bInstanceId: string): number | null;

package/dist/scene/spatial.js

@@ -23,7 +23,7 @@ function packCell(cx, cz) {
 }
 const DEFAULT_CELL_SIZE = 8;
 export function createSpatialApi(options) {
-    const { resolvePosition, candidates, occluder, getVersion } = options;
+    const { resolvePosition, candidates, occluder, getVersion, resolveStep } = options;
     const gridConfig = options.grid === false ? undefined : (options.grid ?? { cellSize: DEFAULT_CELL_SIZE });
     const cellSize = gridConfig?.cellSize;
     let gridIndex = null;
@@ -198,7 +198,7 @@ export function createSpatialApi(options) {
         invalidate() {
             gridDirty = true;
         },
-        moveToward(instanceId, target, { speed, stopDistance = 0, dt }) {
+        moveToward(instanceId, target, { speed, stopDistance = 0, dt, avoidSolids = true }) {
             const current = resolvePosition(instanceId);
             const destination = resolveTarget(target);
             if (current === undefined || destination === undefined)
@@ -209,10 +209,13 @@ export function createSpatialApi(options) {
                 return current;
             const step = Math.min(speed * dt, remaining);
             const scale = step / total;
+            const stepX = (destination[0] - current[0]) * scale;
+            const stepZ = (destination[2] - current[2]) * scale;
+            const slid = avoidSolids && resolveStep !== undefined ? resolveStep(current, stepX, stepZ) : { stepX, stepZ };
             return [
-                current[0] + (destination[0] - current[0]) * scale,
+                current[0] + slid.stepX,
                 current[1] + (destination[1] - current[1]) * scale,
-                current[2] + (destination[2] - current[2]) * scale,
+                current[2] + slid.stepZ,
             ];
         },
     };

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;
+}

package/dist/world/buildings.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Seeded procedural buildings: a footprint of bays × floors emitted as placed facade parts — walls,
+ * windows, storefronts, roof and decor — each tagged with a kit slot `world/buildingKit` binds to a
+ * model. Deterministic and renderer-agnostic.
+ */
 import { type Aabb, type Footprint, type Vec2 } from "./geometry.js";
 export type BuildingSeed = number | string;
 export type Vec3 = readonly [number, number, number];
@@ -105,11 +110,28 @@ export declare const DEFAULT_BUILDING_STYLE: BuildingStyle;
 export declare const BUILDING_STYLE_PALETTES: Record<BuildingStyle, BuildingPalette>;
 /** @internal */
 export declare function resolveBuildingPalette(style?: BuildingStyle, overrides?: BuildingPaletteOverrides): BuildingPalette;
-/** @internal */
+/**
+ * Fill a partial building description out to a complete {@link BuildingConfig}, clamping counts and
+ * probabilities. Use it to inspect or adjust the resolved shape before generating.
+ *
+ * @capability building-generator generate seeded buildings as placed facade parts — bays, floors, roof, decor
+ */
 export declare function createBuildingConfig(input?: BuildingConfigInput): BuildingConfig;
-/** @internal */
+/**
+ * Generate one building as a flat list of placed facade parts: bays × floors per facade, a ground
+ * row, corners, and a roof, with every decorative part rolled from `probabilities` and every part
+ * tagged with a `kit` slot the renderer binds to a model (see `world/buildingKit`). Deterministic
+ * from `seed`.
+ *
+ * @capability building-generator generate a seeded building as placed facade parts (bays, floors, roof, decor)
+ */
 export declare function generateBuilding(input?: BuildingConfigInput): GeneratedBuilding;
 /** @internal */
 export declare function createBuildingGrid(config: BuildingGridConfig): BuildingLot[];
-/** @internal */
+/**
+ * Generate a grid of buildings on lots sized by `lotSize` and separated by `streetWidth`, each with
+ * its floor count rolled from `floorRange`.
+ *
+ * @capability building-generator generate a grid district of seeded buildings
+ */
 export declare function generateBuildingDistrict(config: BuildingGridConfig): GeneratedBuilding[];

package/dist/world/buildings.js

@@ -1,3 +1,8 @@
+/**
+ * Seeded procedural buildings: a footprint of bays × floors emitted as placed facade parts — walls,
+ * windows, storefronts, roof and decor — each tagged with a kit slot `world/buildingKit` binds to a
+ * model. Deterministic and renderer-agnostic.
+ */
 import { footprintAabb } from "./geometry.js";
 const DEFAULT_PROBABILITIES = {
     window: 0.88,
@@ -229,7 +234,12 @@ function rangeInt(seed, key, min, max) {
     const hi = Math.max(min, max);
     return lo + Math.floor(hash01(seed, key) * (hi - lo + 1));
 }
-/** @internal */
+/**
+ * Fill a partial building description out to a complete {@link BuildingConfig}, clamping counts and
+ * probabilities. Use it to inspect or adjust the resolved shape before generating.
+ *
+ * @capability building-generator generate seeded buildings as placed facade parts — bays, floors, roof, decor
+ */
 export function createBuildingConfig(input = {}) {
     return {
         id: input.id ?? DEFAULT_BUILDING_CONFIG.id,
@@ -291,6 +301,13 @@ function panelPosition(config, facade, bay, level, width, depth) {
     const z = config.center[1] - depth / 2 + config.bayWidth * (bay + 0.5);
     return [faceDepth(facade, width, depth, config), y, z];
 }
+/**
+ * Panel dimensions inside one bay. Structural parts (wall, shutter) must pass 1/1 so they tile their
+ * bay completely — a generated building is a shell of thin panels with no solid core, so any ratio
+ * below 1 leaves a continuous slit at every bay seam and floor line that you can see through the
+ * building and out the far side. Decorative overlays (window, storefront, awning, sign) sit on top of
+ * a full wall and are meant to be inset.
+ */
 function panelScale(config, _facade, heightRatio, widthRatio = 0.92) {
     const along = config.bayWidth * widthRatio;
     const high = config.floorHeight * heightRatio;
@@ -333,7 +350,7 @@ function pushUpperFloorParts(parts, config, facade, bay, level, width, depth) {
     const cell = { facade, level, bay };
     const key = `${facade}:${level}:${bay}`;
     const position = panelPosition(config, facade, bay, level, width, depth);
-    parts.push(part(config, "wall", facade, position, panelScale(config, facade, 0.92), `${key}:wall`, cell, ["structure", "upper"]));
+    parts.push(part(config, "wall", facade, position, panelScale(config, facade, 1, 1), `${key}:wall`, cell, ["structure", "upper"]));
     if (!chance(config.seed, `${key}:window`, config.probabilities.window))
         return;
     parts.push(part(config, "window", facade, position, panelScale(config, facade, 0.46, 0.58), `${key}:window`, cell, ["upper"]));
@@ -355,6 +372,11 @@ function pushGroundFloorParts(parts, config, facade, bay, width, depth) {
     const key = `${facade}:0:${bay}`;
     const position = panelPosition(config, facade, bay, 0, width, depth);
     if (facade === "front" && chance(config.seed, `${key}:open`, config.probabilities.openStore)) {
+        // Back the glass with a wall the way an upper floor backs its window. A generated building is a
+        // hollow shell, so a translucent storefront with nothing behind it is a hole 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 most visible place for it to read as see-through.
+        parts.push(part(config, "wall", facade, position, panelScale(config, facade, 1, 1), `${key}:wall`, cell, ["structure", "ground"]));
         parts.push(part(config, "storefront", facade, position, panelScale(config, facade, 0.86), `${key}:store`, cell, ["ground", "open"]));
         if (chance(config.seed, `${key}:sign`, config.probabilities.storeSign)) {
             const signPosition = [position[0], position[1] + config.floorHeight * 0.34, position[2]];
@@ -363,7 +385,7 @@ function pushGroundFloorParts(parts, config, facade, bay, width, depth) {
         return;
     }
     const kind = facade === "front" ? "shutter" : "wall";
-    parts.push(part(config, kind, facade, position, panelScale(config, facade, 0.86), `${key}:${kind}`, cell, ["ground", "closed"]));
+    parts.push(part(config, kind, facade, position, panelScale(config, facade, 1, 1), `${key}:${kind}`, cell, ["ground", "closed"]));
 }
 function pushFacade(parts, config, facade, width, depth) {
     const bays = facade === "front" || facade === "back" ? config.baysWide : config.baysDeep;
@@ -408,7 +430,14 @@ function pushCorners(parts, config, width, depth) {
         parts.push(part(config, "corner", index < 2 ? "back" : "front", position, [config.facadeDepth * 1.35, height, config.facadeDepth * 1.35], `corner:${index}`, undefined, ["structure"]));
     });
 }
-/** @internal */
+/**
+ * Generate one building as a flat list of placed facade parts: bays × floors per facade, a ground
+ * row, corners, and a roof, with every decorative part rolled from `probabilities` and every part
+ * tagged with a `kit` slot the renderer binds to a model (see `world/buildingKit`). Deterministic
+ * from `seed`.
+ *
+ * @capability building-generator generate a seeded building as placed facade parts (bays, floors, roof, decor)
+ */
 export function generateBuilding(input = {}) {
     const config = createBuildingConfig(input);
     const width = config.baysWide * config.bayWidth;
@@ -471,7 +500,12 @@ export function createBuildingGrid(config) {
     }
     return lots;
 }
-/** @internal */
+/**
+ * Generate a grid of buildings on lots sized by `lotSize` and separated by `streetWidth`, each with
+ * its floor count rolled from `floorRange`.
+ *
+ * @capability building-generator generate a grid district of seeded buildings
+ */
 export function generateBuildingDistrict(config) {
     return createBuildingGrid(config).map((lot) => generateBuilding(lot.config));
 }

package/dist/world/cityKind.d.ts

@@ -106,6 +106,12 @@ export interface CityRules {
     sidewalkWidth: number;
     /** Building style palette id (see {@link BUILDING_STYLE_PALETTES}). */
     style: BuildingStyle;
+    /**
+     * Name of the `BuildingKit` the near-LOD facades render with, or `""` for the palette blocks.
+     * A game registers its bound art under this name; the document carries only the name, so a scene
+     * stays portable and small.
+     */
+    buildingKit: string;
     /** Seed string; same seed reproduces the same city. Empty falls back to the volume id. */
     seed: string;
 }

package/dist/world/cityKind.js

@@ -103,6 +103,7 @@ export const CITY_DEFAULTS = {
     sidewalks: true,
     sidewalkWidth: 1.9,
     style: DEFAULT_BUILDING_STYLE,
+    buildingKit: "",
     seed: "",
 };
 /** The city parameter schema — drives the inspector sliders and `meta` parse via the studio seam. */
@@ -184,6 +185,7 @@ export const CITY_SCHEMA = {
             default: CITY_DEFAULTS.style,
             options: Object.keys(BUILDING_STYLE_PALETTES).map((style) => ({ value: style })),
         },
+        { type: "text", key: "buildingKit", label: "building kit", group: "buildings", default: CITY_DEFAULTS.buildingKit },
         { type: "range", key: "treeDensity", label: "tree density", group: "greenery", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.treeDensity },
         { type: "weightedList", key: "treeMix", label: "tree mix", group: "greenery", itemLabel: "species", default: CITY_DEFAULTS.treeMix },
         { type: "range", key: "lightDensity", label: "street lights", group: "greenery", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.lightDensity },
@@ -563,6 +565,7 @@ export function readCityRules(meta) {
         sidewalks: params["sidewalks"],
         sidewalkWidth: params["sidewalkWidth"],
         style: params["style"],
+        buildingKit: params["buildingKit"] ?? CITY_DEFAULTS.buildingKit,
         seed: params["seed"],
     };
 }

package/dist/world/environmentSummary.js

@@ -1,4 +1,5 @@
 import { DEFAULT_BUILDING_CONFIG, generateBuilding, generateBuildingDistrict, resolveBuildingPalette, } from "./buildings.js";
+import { buildingKitVariantCounts } from "./buildingKit.js";
 import { deriveBuildingLots } from "./buildingLots.js";
 import { pathLength } from "./roads.js";
 import { resolveTerrainField, resolveTerrainPalette } from "./terrain.js";
@@ -21,10 +22,17 @@ export function resolveStructureBuildings(descriptor) {
         lotSize: descriptor.footprint,
         streetWidth: spacing,
         floorRange: descriptor.stories,
-        base: { floorHeight: descriptor.storyHeight },
+        base: { floorHeight: descriptor.storyHeight, ...kitVariants(descriptor.kit) },
         ...(descriptor.seed === undefined ? {} : { seed: descriptor.seed }),
     }).slice(0, descriptor.count);
 }
+/** Spread seeded variant picks across exactly the models a kit binds, so no bound variant goes unused. */
+function kitVariants(kit) {
+    if (kit === undefined)
+        return {};
+    const variants = buildingKitVariantCounts(kit);
+    return Object.keys(variants).length === 0 ? {} : { variants };
+}
 function hashU32(input) {
     let hash = 2166136261;
     for (let i = 0; i < input.length; i += 1) {
@@ -57,9 +65,10 @@ function resolveFrontageBuildings(descriptor, along) {
     });
     const [floorsMin, floorsMax] = descriptor.stories;
     const bayWidth = DEFAULT_BUILDING_CONFIG.bayWidth;
-    return lots.map((lot, index) => buildLot(lot, index, seed, floorsMin, floorsMax, bayWidth, descriptor.storyHeight));
+    const variants = kitVariants(descriptor.kit);
+    return lots.map((lot, index) => buildLot(lot, index, seed, floorsMin, floorsMax, bayWidth, descriptor.storyHeight, variants));
 }
-function buildLot(lot, index, seed, floorsMin, floorsMax, bayWidth, storyHeight) {
+function buildLot(lot, index, seed, floorsMin, floorsMax, bayWidth, storyHeight, variants = {}) {
     const lo = Math.min(floorsMin, floorsMax);
     const hi = Math.max(floorsMin, floorsMax);
     const floors = lo + Math.floor((hashU32(`${seed}:floors:${index}`) / 4294967296) * (hi - lo + 1));
@@ -74,6 +83,7 @@ function buildLot(lot, index, seed, floorsMin, floorsMax, bayWidth, storyHeight)
         baysDeep,
         bayWidth,
         floorHeight: storyHeight,
+        ...variants,
     });
     return { ...building, rotationY: lot.rotationY };
 }

package/dist/world/features.d.ts

@@ -1,4 +1,5 @@
 import type { BuildingPaletteOverrides, BuildingStyle } from "./buildings.js";
+import type { BuildingKit } from "./buildingKit.js";
 import type { AvoidZone } from "./geometry.js";
 import type { TerrainPathProfile } from "./pathTerrain.js";
 import type { PlaceWorldFeature } from "./place.js";
@@ -352,6 +353,11 @@ export interface BuildingEnvironmentConfig {
      * back by a sidewalk strip) instead of the grid around `position`. See {@link BuildingFrontageConfig}.
      */
     along?: BuildingFrontageConfig;
+    /**
+     * Binds facade part slots to real models (see `world/buildingKit`). Unbound kinds keep the
+     * untextured block; without a kit the whole facade stays blocks, as before.
+     */
+    kit?: BuildingKit;
 }
 export type PadSize = readonly [number, number] | {
     radius: number;
@@ -393,7 +399,7 @@ export type OceanEnvironmentDescriptor = {
 } & Required<Pick<OceanEnvironmentConfig, "bounds" | "level" | "waveHeight" | "waveScale" | "waveSpeed" | "color">> & Pick<OceanEnvironmentConfig, "position" | "levelAt">;
 export type BuildingEnvironmentDescriptor = {
     kind: "building";
-} & Required<Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style">> & Pick<BuildingEnvironmentConfig, "seed" | "position" | "palette" | "along">;
+} & Required<Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style">> & Pick<BuildingEnvironmentConfig, "seed" | "position" | "palette" | "along" | "kit">;
 export type PadEnvironmentDescriptor = {
     kind: "pad";
 } & Required<Pick<PadEnvironmentConfig, "center" | "size" | "height" | "color">> & Pick<PadEnvironmentConfig, "rotationY" | "elevation">;