@jgengine/core 0.18.1 → 0.19.0

package/dist/vfx/feedbackMixer.js

@@ -0,0 +1,106 @@
+/** Sample a {@link FeedbackCurve}; an empty curve is the identity. */
+export function sampleFeedbackCurve(curve, x) {
+    if (curve === undefined || curve.length === 0)
+        return x;
+    const first = curve[0];
+    if (x <= first[0])
+        return first[1];
+    for (let i = 1; i < curve.length; i += 1) {
+        const [x1, y1] = curve[i];
+        if (x <= x1) {
+            const [x0, y0] = curve[i - 1];
+            const span = x1 - x0;
+            return span <= 0 ? y1 : y0 + ((y1 - y0) * (x - x0)) / span;
+        }
+    }
+    return curve[curve.length - 1][1];
+}
+function approach(current, target, attack, release, dt) {
+    const rate = target > current ? attack : release;
+    if (!Number.isFinite(rate))
+        return target;
+    const step = Math.max(0, rate) * dt;
+    return Math.abs(target - current) <= step ? target : current + Math.sign(target - current) * step;
+}
+/**
+ * Creates a {@link FeedbackMixer}: the one place a game declares how sim telemetry drives presentation —
+ * rpm to engine pitch, tire saturation to squeal and rumble, speed to FOV, landing speed to a thud — instead
+ * of hand-writing that glue per vehicle, aircraft or weapon. Deterministic, allocation-free per update.
+ * @capability feedback-mixer map sim telemetry to camera, audio and haptic parameters through curves, smoothing and threshold events
+ */
+export function createFeedbackMixer(initial) {
+    let config = initial;
+    let routeValues = [];
+    let eventSignals = [];
+    let cooldowns = [];
+    let firedNow = new Set();
+    const output = {};
+    const touched = new Set();
+    function shapeState() {
+        routeValues = config.routes.map((_, i) => routeValues[i] ?? 0);
+        eventSignals = (config.events ?? []).map((_, i) => eventSignals[i] ?? 0);
+        cooldowns = (config.events ?? []).map((_, i) => cooldowns[i] ?? 0);
+        for (const route of config.routes)
+            output[route.target] ??= 0;
+        for (const key of Object.keys(config.base ?? {}))
+            output[key] ??= config.base?.[key] ?? 0;
+    }
+    shapeState();
+    return {
+        update(dt, signals) {
+            const step = Math.max(0, dt);
+            for (const key of Object.keys(output))
+                output[key] = config.base?.[key] ?? 0;
+            touched.clear();
+            for (let i = 0; i < config.routes.length; i += 1) {
+                const route = config.routes[i];
+                const target = sampleFeedbackCurve(route.curve, signals[route.signal] ?? 0);
+                const attack = route.attack ?? Number.POSITIVE_INFINITY;
+                const value = approach(routeValues[i], target, attack, route.release ?? attack, step);
+                routeValues[i] = value;
+                const mode = config.combine?.[route.target] ?? "sum";
+                if (mode === "max") {
+                    const current = touched.has(route.target) ? output[route.target] : Number.NEGATIVE_INFINITY;
+                    output[route.target] = Math.max(current, value);
+                }
+                else
+                    output[route.target] += value;
+                touched.add(route.target);
+            }
+            firedNow.clear();
+            const events = config.events ?? [];
+            for (let i = 0; i < events.length; i += 1) {
+                const event = events[i];
+                const value = signals[event.signal] ?? 0;
+                cooldowns[i] = Math.max(0, cooldowns[i] - step);
+                if (value >= event.threshold && eventSignals[i] < event.threshold && cooldowns[i] === 0) {
+                    firedNow.add(event.id);
+                    cooldowns[i] = event.cooldown ?? 0;
+                }
+                eventSignals[i] = value;
+            }
+            return output;
+        },
+        fired: (id) => firedNow.has(id),
+        value: () => output,
+        retune(next) {
+            config = next;
+            shapeState();
+        },
+        snapshot: () => ({ routes: [...routeValues], eventSignals: [...eventSignals], cooldowns: [...cooldowns] }),
+        restore(state) {
+            routeValues = [...state.routes];
+            eventSignals = [...state.eventSignals];
+            cooldowns = [...state.cooldowns];
+            shapeState();
+        },
+        reset() {
+            routeValues = routeValues.map(() => 0);
+            eventSignals = eventSignals.map(() => 0);
+            cooldowns = cooldowns.map(() => 0);
+            firedNow = new Set();
+            for (const key of Object.keys(output))
+                output[key] = config.base?.[key] ?? 0;
+        },
+    };
+}

package/dist/visibility/simulationCulling.d.ts

@@ -1,4 +1,4 @@
-import type { LodBand } from "../world/lod.js";
+import type { LodBand, LodSchedulerState } from "../world/lod.js";
 /**
  * Simulation culling is a SEPARATE, opt-in system from render culling. Render culling only
  * decides what is drawn; this decides whether a low-priority off-screen entity updates this
@@ -23,6 +23,11 @@ export interface SimulationDecision {
     /** Seconds of accumulated time delivered when `update` is true (for catch-up integration). */
     elapsed: number;
 }
+/** Plain JSON state of a {@link SimulationCuller}: the enabled flag and each id's throttle accumulator. */
+export interface SimulationCullerState {
+    enabled: boolean;
+    scheduler: LodSchedulerState;
+}
 export interface SimulationCuller {
     enabled(): boolean;
     setEnabled(value: boolean): void;
@@ -30,5 +35,7 @@ export interface SimulationCuller {
     step(id: string, distance: number, dt: number): SimulationDecision;
     forget(id: string): void;
     clear(): void;
+    snapshot(): SimulationCullerState;
+    restore(next: SimulationCullerState): void;
 }
 export declare function createSimulationCuller(options?: SimulationCullingOptions): SimulationCuller;

package/dist/visibility/simulationCulling.js

@@ -32,5 +32,12 @@ export function createSimulationCuller(options = {}) {
         clear() {
             scheduler.clear();
         },
+        snapshot() {
+            return { enabled, scheduler: scheduler.snapshot() };
+        },
+        restore(next) {
+            enabled = next.enabled;
+            scheduler.restore(next.scheduler);
+        },
     };
 }

package/dist/visibility/spatialIndex.d.ts

@@ -10,6 +10,25 @@ export interface SpatialIndexOptions {
      */
     readonly maxCellSpan?: number;
 }
+/** Integer cell bounds an object covers, inclusive on both ends. */
+export interface SpatialCellRange {
+    x0: number;
+    y0: number;
+    z0: number;
+    x1: number;
+    y1: number;
+    z1: number;
+}
+/**
+ * Plain JSON state of a {@link SpatialIndex}. Cells and their ids keep insertion order, so a restored
+ * index returns query results in the same order.
+ */
+export interface SpatialIndexState {
+    /** Per object: its cell range (`null` when oversized) and whether it was inserted as dynamic. */
+    entries: [id: string, range: SpatialCellRange | null, dynamic: boolean][];
+    cells: [x: number, y: number, z: number, ids: string[]][];
+    oversized: string[];
+}
 /**
  * A uniform 3D spatial hash the renderer and streaming system query for potentially-visible
  * objects instead of scanning the whole scene. Objects are keyed by their world AABB into
@@ -39,6 +58,8 @@ export interface SpatialIndex {
     }[];
     cellSize(): number;
     clear(): void;
+    snapshot(): SpatialIndexState;
+    restore(next: SpatialIndexState): void;
 }
 export declare function createSpatialIndex(options?: SpatialIndexOptions): SpatialIndex;
 /** Precise AABB-vs-AABB test re-exported for callers refining a broad-phase result. */

package/dist/visibility/spatialIndex.js

@@ -206,6 +206,22 @@ export function createSpatialIndex(options = {}) {
             entries.clear();
             stamps.clear();
         },
+        snapshot() {
+            return {
+                entries: [...entries].map(([id, entry]) => [id, entry.range === null ? null : { ...entry.range }, entry.dynamic]),
+                cells: [...cells.values()].map((bucket) => [bucket.x, bucket.y, bucket.z, [...bucket.ids]]),
+                oversized: [...oversized],
+            };
+        },
+        restore(next) {
+            this.clear();
+            for (const [id, range, dynamic] of next.entries)
+                entries.set(id, { range: range === null ? null : { ...range }, dynamic });
+            for (const [x, y, z, ids] of next.cells)
+                cells.set(packCell(x, y, z), { x, y, z, ids: new Set(ids) });
+            for (const id of next.oversized)
+                oversized.add(id);
+        },
     };
 }
 /** Precise AABB-vs-AABB test re-exported for callers refining a broad-phase result. */

package/dist/world/authoredSolids.d.ts

@@ -0,0 +1,46 @@
+import type { WorldSolid, WorldSolids } from "./worldSolids.js";
+type Vec3Like = {
+    x: number;
+    y: number;
+    z: number;
+};
+/** Minimal editor document shape {@link resolveAuthoredSolids} walks; any `EditorDocument` satisfies it. */
+export interface AuthoredSolidsDocumentLike {
+    markers: readonly {
+        id: string;
+        kind: string;
+        position: Vec3Like;
+        rotationY?: number;
+        meta?: Record<string, unknown>;
+    }[];
+    volumes: readonly {
+        id: string;
+        kind: string;
+        center: Vec3Like;
+        halfExtents?: Vec3Like;
+        radius?: number;
+        meta?: Record<string, unknown>;
+    }[];
+    paths: readonly {
+        id: string;
+        kind: string;
+        points: readonly Vec3Like[];
+        meta?: Record<string, unknown>;
+    }[];
+}
+/** Layer prefix `syncAuthoredSolids` owns in `ctx.world.solids`; one layer per document object. */
+export declare const AUTHORED_SOLID_LAYER_PREFIX = "authored:";
+/**
+ * Solids for every document object whose scene kind declares `solids`, keyed by object id. Objects
+ * whose kind has no `solids` hook, or whose hook returns none, are left out.
+ * @capability authored-solids collision for studio-authored world content such as city volumes
+ */
+export declare function resolveAuthoredSolids(document: AuthoredSolidsDocumentLike, sampleHeight?: (x: number, z: number) => number): Map<string, readonly WorldSolid[]>;
+/**
+ * Write a document's studio solids into `solids` (usually `ctx.world.solids`), one
+ * `authored:<objectId>` layer per object, dropping authored layers the document no longer has.
+ * Call again whenever the document changes.
+ * @capability authored-solids collision for studio-authored world content such as city volumes
+ */
+export declare function syncAuthoredSolids(solids: WorldSolids, document: AuthoredSolidsDocumentLike, sampleHeight?: (x: number, z: number) => number): void;
+export {};

package/dist/world/authoredSolids.js

@@ -0,0 +1,75 @@
+import { registerBuiltinSceneKinds } from "../scene/builtinSceneKinds.js";
+import { getSceneKind, parseParams } from "../scene/sceneKinds.js";
+/** Layer prefix `syncAuthoredSolids` owns in `ctx.world.solids`; one layer per document object. */
+export const AUTHORED_SOLID_LAYER_PREFIX = "authored:";
+function kindObjects(document) {
+    const objects = [];
+    for (const marker of document.markers) {
+        objects.push({
+            id: marker.id,
+            kind: marker.kind,
+            position: marker.position,
+            ...(marker.rotationY === undefined ? {} : { rotationY: marker.rotationY }),
+            ...(marker.meta === undefined ? {} : { meta: marker.meta }),
+        });
+    }
+    for (const volume of document.volumes) {
+        objects.push({
+            id: volume.id,
+            kind: volume.kind,
+            center: volume.center,
+            ...(volume.halfExtents === undefined ? {} : { halfExtents: volume.halfExtents }),
+            ...(volume.radius === undefined ? {} : { radius: volume.radius }),
+            ...(volume.meta === undefined ? {} : { meta: volume.meta }),
+        });
+    }
+    for (const path of document.paths) {
+        objects.push({
+            id: path.id,
+            kind: path.kind,
+            points: path.points,
+            ...(path.meta === undefined ? {} : { meta: path.meta }),
+        });
+    }
+    return objects;
+}
+/**
+ * Solids for every document object whose scene kind declares `solids`, keyed by object id. Objects
+ * whose kind has no `solids` hook, or whose hook returns none, are left out.
+ * @capability authored-solids collision for studio-authored world content such as city volumes
+ */
+export function resolveAuthoredSolids(document, sampleHeight) {
+    registerBuiltinSceneKinds();
+    const out = new Map();
+    const objects = kindObjects(document);
+    const context = { ...(sampleHeight === undefined ? {} : { sampleHeight }), objects };
+    for (const object of objects) {
+        const definition = getSceneKind(object.kind);
+        if (definition?.solids === undefined || definition.resolve === undefined)
+            continue;
+        const params = parseParams(definition.schema, object.meta);
+        const solids = definition.solids(definition.resolve(object, params, context), object, params, context);
+        if (solids.length > 0)
+            out.set(object.id, solids);
+    }
+    return out;
+}
+/**
+ * Write a document's studio solids into `solids` (usually `ctx.world.solids`), one
+ * `authored:<objectId>` layer per object, dropping authored layers the document no longer has.
+ * Call again whenever the document changes.
+ * @capability authored-solids collision for studio-authored world content such as city volumes
+ */
+export function syncAuthoredSolids(solids, document, sampleHeight) {
+    const resolved = resolveAuthoredSolids(document, sampleHeight);
+    solids.batch(() => {
+        for (const layer of solids.layers()) {
+            if (!layer.startsWith(AUTHORED_SOLID_LAYER_PREFIX))
+                continue;
+            if (!resolved.has(layer.slice(AUTHORED_SOLID_LAYER_PREFIX.length)))
+                solids.remove(layer);
+        }
+        for (const [id, set] of resolved)
+            solids.set(`${AUTHORED_SOLID_LAYER_PREFIX}${id}`, set);
+    });
+}

package/dist/world/buildingGenerator.js

@@ -7,7 +7,7 @@
  * @capability building-generator seeded building as a placeable parametric asset
  */
 import { registerAssetGenerator, partsBounds } from "../scene/assetGenerator.js";
-import { BUILDING_STYLE_PALETTES, DEFAULT_BUILDING_CONFIG, generateBuilding, resolveBuildingPalette } from "./buildings.js";
+import { BUILDING_STYLE_PALETTES, DEFAULT_BUILDING_CONFIG, buildingSurfaceColor, generateBuilding, resolveBuildingPalette } from "./buildings.js";
 /** The generator id a catalog entry / placed marker references. */
 export const BUILDING_GENERATOR_ID = "building";
 /** The building generator's slider schema — drives the inspector via #809. */
@@ -47,7 +47,7 @@ export function generateBuildingAsset(params, seed) {
         position: part.position,
         size: part.scale,
         rotationY: part.rotationY,
-        color: palette[part.kind],
+        color: buildingSurfaceColor(palette[part.kind]),
     }));
     return { parts, bounds: partsBounds(parts) };
 }

package/dist/world/buildingKit.d.ts

@@ -3,7 +3,7 @@
  * 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";
+import type { BuildingKitSlot, BuildingPartKind, BuildingSurfaceMaterial, BuildingVariantCounts, Vec3 } from "./buildings.js";
 /**
  * How a kit model's native bounds are mapped onto the slot box `BuildingPartPlacement.scale`
  * describes.
@@ -32,6 +32,8 @@ export interface BuildingKitPart {
     /** Multiplier applied after `fit`. */
     scale?: Vec3;
     tint?: string;
+    /** Tiled PBR maps applied over the model's own materials; `color` tints, `repeat` sets the tiling. */
+    material?: BuildingSurfaceMaterial;
     /**
      * 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

package/dist/world/buildings.d.ts

@@ -103,11 +103,43 @@ export interface BuildingGridConfig {
     floorRange?: readonly [number, number];
 }
 export declare const DEFAULT_BUILDING_CONFIG: BuildingConfig;
-export type BuildingPalette = Record<BuildingPartKind, string>;
+/** URLs of the PBR maps a building surface tiles; `buildMaterialCatalog(...).resolve(id)!.maps` fits directly. */
+export interface BuildingSurfaceMaps {
+    color?: string;
+    normal?: string;
+    roughness?: string;
+    ao?: string;
+    metalness?: string;
+}
+/**
+ * A textured building surface: a base colour plus optional tiled PBR maps. With `maps`, `color`
+ * multiplies the albedo (leave it light to show the map as authored); without, it is the flat
+ * colour the part has always had.
+ */
+export interface BuildingSurfaceMaterial {
+    /** Base colour; the style's colour for that part kind when unset. */
+    color?: string;
+    maps?: BuildingSurfaceMaps;
+    /**
+     * Texture tiles per part slot along [x, y]; a number tiles both. Slots within one building share
+     * a size, so one repeat per kind is uniform there; it drifts across buildings with a different
+     * `bayWidth`. Default 1.
+     */
+    repeat?: number | readonly [number, number];
+    roughness?: number;
+    metalness?: number;
+}
+/** What a building part kind is painted with: a hex colour, or a colour plus tiled PBR maps. */
+export type BuildingSurface = string | BuildingSurfaceMaterial;
+export type BuildingPalette = Record<BuildingPartKind, BuildingSurface>;
 export type BuildingPaletteOverrides = Partial<BuildingPalette>;
+/** The flat colour of a surface: the hex itself, or a material's `color`, else `fallback`. */
+export declare function buildingSurfaceColor(surface: BuildingSurface | undefined, fallback?: string): string;
+/** Normalises a surface to its material form so a renderer reads one shape. */
+export declare function resolveBuildingSurface(surface: BuildingSurface): BuildingSurfaceMaterial;
 export type BuildingStyle = "generic" | "capital" | "village" | "desert" | "industrial" | "coastal" | "neon" | "ruin" | "frontier" | "aerial";
 export declare const DEFAULT_BUILDING_STYLE: BuildingStyle;
-export declare const BUILDING_STYLE_PALETTES: Record<BuildingStyle, BuildingPalette>;
+export declare const BUILDING_STYLE_PALETTES: Record<BuildingStyle, Record<BuildingPartKind, string>>;
 /**
  * Per-style facade-tone family: the wall colours a district spreads across its buildings so
  * neighbours differ in hue and value while the block stays one palette. Index 0 is the palette's

package/dist/world/buildings.js

@@ -38,6 +38,16 @@ export const DEFAULT_BUILDING_CONFIG = {
     probabilities: DEFAULT_PROBABILITIES,
     variants: DEFAULT_VARIANTS,
 };
+/** The flat colour of a surface: the hex itself, or a material's `color`, else `fallback`. */
+export function buildingSurfaceColor(surface, fallback = "#808080") {
+    if (surface === undefined)
+        return fallback;
+    return typeof surface === "string" ? surface : (surface.color ?? fallback);
+}
+/** Normalises a surface to its material form so a renderer reads one shape. */
+export function resolveBuildingSurface(surface) {
+    return typeof surface === "string" ? { color: surface } : surface;
+}
 export const DEFAULT_BUILDING_STYLE = "generic";
 export const BUILDING_STYLE_PALETTES = {
     generic: {
@@ -207,7 +217,7 @@ export function resolveBuildingWallTones(style = DEFAULT_BUILDING_STYLE) {
     const tones = BUILDING_STYLE_WALL_TONES[style];
     if (tones !== undefined && tones.length > 0)
         return tones;
-    return [resolveBuildingPalette(style).wall];
+    return [buildingSurfaceColor(resolveBuildingPalette(style).wall)];
 }
 /** @internal */
 export function resolveBuildingPalette(style = DEFAULT_BUILDING_STYLE, overrides) {

package/dist/world/cityKind.d.ts

@@ -2,6 +2,7 @@ import { type ParamSchema, type SceneKindObject, type SceneKindResolveContext, t
 import { type BuildingStyle } from "./buildings.js";
 import { type CityLotClass, type CityLotPiece, type CityTreeSpecies, type CityZoneBand, type CityZoneProfile } from "./cityContent.js";
 import { type CircuitCorner, type CircuitGate, type CircuitSealKind } from "./raceCircuit.js";
+import type { WorldSolid } from "./worldSolids.js";
 import type { RoadPoint } from "./roads.js";
 import { type StreetFeatureKind } from "./streetGenerator.js";
 import { type CityBlockKind } from "./cityBlocks.js";
@@ -432,6 +433,12 @@ export interface ResolvedCity {
     /** The instanced street race through these streets, when `race` is on and a lap could be found. */
     race?: ResolvedRace;
 }
+/**
+ * One solid per wall and roof piece of every lot, grounded the way the city renderer grounds it:
+ * grade at the highest lot corner, foundations down to half a metre under the lowest.
+ * @capability city-district editor-authorable procedural city district (streets, zoning, buildings, furniture)
+ */
+export declare function citySolids(city: ResolvedCity, sampleHeight?: (x: number, z: number) => number): WorldSolid[];
 /** Extended resolve context: sibling `cityzone` volumes that override the band/mix locally. */
 export interface CityResolveContext extends SceneKindResolveContext {
     zoneOverrides?: readonly SceneKindObject[];

package/dist/world/cityKind.js

@@ -164,6 +164,7 @@ export const CITY_SCHEMA = {
             options: [{ value: "auto" }, { value: "gravel" }],
         },
         { type: "bool", key: "fabric", label: "buildings & parcels", group: "layout", default: CITY_DEFAULTS.fabric },
+        { type: "bool", key: "solid", label: "solid buildings", group: "layout", default: true },
         { type: "bool", key: "bridges", label: "bridges over water", group: "layout", default: CITY_DEFAULTS.bridges },
         { type: "bool", key: "tunnels", label: "tunnels through ridges", group: "layout", default: CITY_DEFAULTS.tunnels },
         {
@@ -638,6 +639,55 @@ export function readCityRules(meta) {
         seed: params["seed"],
     };
 }
+/** Lot pieces that block: walls and roofs. Trim and accents (cornices, awnings) stay passable. */
+const SOLID_PIECE_ROLES = new Set(["wall", "roof"]);
+/**
+ * One solid per wall and roof piece of every lot, grounded the way the city renderer grounds it:
+ * grade at the highest lot corner, foundations down to half a metre under the lowest.
+ * @capability city-district editor-authorable procedural city district (streets, zoning, buildings, furniture)
+ */
+export function citySolids(city, sampleHeight = () => 0) {
+    const solids = [];
+    for (const lot of city.lots) {
+        const c = Math.cos(lot.rotationY);
+        const s = Math.sin(lot.rotationY);
+        const hw = lot.size[0] / 2;
+        const hd = lot.size[1] / 2;
+        let minY = Infinity;
+        let maxY = -Infinity;
+        for (const [dx, dz] of [
+            [hw, hd],
+            [hw, -hd],
+            [-hw, hd],
+            [-hw, -hd],
+        ]) {
+            const y = sampleHeight(lot.center[0] + dx * c + dz * s, lot.center[1] - dx * s + dz * c);
+            minY = Math.min(minY, y);
+            maxY = Math.max(maxY, y);
+        }
+        const grade = maxY;
+        const foundationBase = minY - 0.5;
+        for (const piece of lot.pieces) {
+            if (!SOLID_PIECE_ROLES.has(piece.role))
+                continue;
+            const bottom = piece.grounded ? foundationBase : grade + piece.offset[1];
+            const top = piece.grounded ? grade + piece.size[1] : grade + piece.offset[1] + piece.size[1];
+            if (top - bottom <= 0 || piece.size[0] <= 0 || piece.size[2] <= 0)
+                continue;
+            const yaw = lot.rotationY + piece.rotationY;
+            solids.push({
+                center: [
+                    lot.center[0] + piece.offset[0] * c + piece.offset[2] * s,
+                    (bottom + top) / 2,
+                    lot.center[1] - piece.offset[0] * s + piece.offset[2] * c,
+                ],
+                halfExtents: [piece.size[0] / 2, (top - bottom) / 2, piece.size[2] / 2],
+                ...(yaw === 0 ? {} : { rotationY: yaw }),
+            });
+        }
+    }
+    return solids;
+}
 /** Bounded-work caps so a huge volume can never generate unbounded content. */
 const MAX_STREETS = 320;
 /** Building budget — the shared scatterable cap so the inspector's "capped at N (budget)" note is truthful. */
@@ -1302,7 +1352,7 @@ export function resolveCityObject(object, context) {
             return Math.hypot(dx, dz) / (2 * d);
         };
     // Child `cityzone` volumes override the band (and optionally the class mix) for lots inside them.
-    const overrides = (context?.zoneOverrides ?? []).filter((volume) => volume.kind === CITY_ZONE_KIND);
+    const overrides = (context?.zoneOverrides ?? context?.objects ?? []).filter((volume) => volume.kind === CITY_ZONE_KIND);
     const overrideAt = overrides.length === 0
         ? null
         : (x, z) => {
@@ -1789,6 +1839,7 @@ export function registerCityKind() {
         schema: CITY_SCHEMA,
         coverage: { spec: "city", densityKey: "roadsideOccupancy" },
         resolve: (object, _params, context) => resolveCityObject(object, context),
+        solids: (resolved, _object, params, context) => resolved === null || params["solid"] === false ? [] : citySolids(resolved, context.sampleHeight),
         note: (object) => {
             const resolved = resolveCityObject(object);
             if (resolved === null)

package/dist/world/features.d.ts

@@ -296,16 +296,38 @@ export interface OceanEnvironmentConfig {
     waveSpeed?: number;
     color?: string;
 }
+/**
+ * Where the sun sits, as a compass bearing and a height above the horizon, both in degrees.
+ * `azimuth` 0 points toward -Z (north), 90 toward +X (east); `elevation` 90 is straight overhead.
+ */
+export interface SkySunConfig {
+    /** Compass bearing of the sun in degrees; 0 = -Z, 90 = +X. Default 0. */
+    azimuth?: number;
+    /** Height above the horizon in degrees; 0 sits on the horizon, 90 is overhead. Default 68. */
+    elevation?: number;
+}
 export interface SkyEnvironmentConfig {
     /** Fixed look used when `timeOfDay` is off (or no clock is available); default "day". */
     preset?: "day" | "dusk" | "night";
     /** Drive sun/sky from the world clock's `calendar().dayFraction` instead of the fixed `preset`. */
     timeOfDay?: boolean;
+    /**
+     * Horizon tint at noon. Under `timeOfDay` this only sets the noon keyframe; dawn, dusk, and night
+     * still crossfade through the engine presets, so an authored tint is visible for part of the day.
+     */
     horizonColor?: string;
+    /** Zenith tint at noon; same `timeOfDay` crossfade caveat as `horizonColor`. */
     zenithColor?: string;
     sunIntensity?: number;
     ambientIntensity?: number;
-    /** Sky-dome sphere radius in world units. Enlarge for a playfield sited far from the origin so the viewer never exits the dome. Default 260. */
+    /**
+     * Sun placement for the dome glow and the sky-owned sun light. With a fixed `preset` this is the
+     * sun's exact direction; under `timeOfDay` it is where the sun stands at noon and the day arc
+     * swings around that bearing. Unset with an authored `lighting.directional` light, the shell takes
+     * the first directional light's direction so the dome sun agrees with the shadows.
+     */
+    sun?: SkySunConfig;
+    /** Sky-dome sphere radius in world units. Enlarge for a playfield sited far from the origin so the viewer never exits the dome. Must stay below the camera far plane or the dome depth-clips to black. Default 260. */
     radius?: number;
     /** Horizon haze-band strength: 0 removes the dusty band, ~1 makes it heavy. Default 0.5. */
     hazeStrength?: number;
@@ -377,6 +399,11 @@ export interface BuildingEnvironmentConfig {
      * untextured block; without a kit the whole facade stays blocks, as before.
      */
     kit?: BuildingKit;
+    /**
+     * Whether the buildings block movement and physics through `ctx.world.solids` (default `true`).
+     * `false` keeps them render-only, e.g. a distant skyline nobody can reach.
+     */
+    solid?: boolean;
 }
 export type PadSize = readonly [number, number] | {
     radius: number;
@@ -418,7 +445,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" | "kit">;
+} & Required<Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style">> & Pick<BuildingEnvironmentConfig, "seed" | "position" | "palette" | "along" | "kit" | "solid">;
 export type PadEnvironmentDescriptor = {
     kind: "pad";
 } & Required<Pick<PadEnvironmentConfig, "center" | "size" | "height" | "color">> & Pick<PadEnvironmentConfig, "rotationY" | "elevation">;

package/dist/world/features.js

@@ -1,3 +1,4 @@
+import { warnOnce } from "../devtools/warnOnce.js";
 function list(value) {
     if (value === undefined) {
         return undefined;
@@ -110,6 +111,9 @@ export function terrain(config = {}) {
     });
 }
 export function sky(config = {}) {
+    if (config.timeOfDay === true && (config.zenithColor !== undefined || config.horizonColor !== undefined)) {
+        warnOnce("sky-timeofday-tint", "[jgengine] sky(): zenithColor/horizonColor only set the noon keyframe under timeOfDay; dawn, dusk, and night crossfade through the engine presets. Drop timeOfDay for a fixed tint.");
+    }
     return withOptional({
         kind: "sky",
         preset: config.preset ?? "day",
@@ -119,6 +123,7 @@ export function sky(config = {}) {
         ...(config.zenithColor === undefined ? {} : { zenithColor: config.zenithColor }),
         ...(config.sunIntensity === undefined ? {} : { sunIntensity: config.sunIntensity }),
         ...(config.ambientIntensity === undefined ? {} : { ambientIntensity: config.ambientIntensity }),
+        ...(config.sun === undefined ? {} : { sun: { ...config.sun } }),
         ...(config.radius === undefined ? {} : { radius: config.radius }),
         ...(config.hazeStrength === undefined ? {} : { hazeStrength: config.hazeStrength }),
         ...(config.sunGlowStrength === undefined ? {} : { sunGlowStrength: config.sunGlowStrength }),
@@ -253,6 +258,7 @@ export function building(config = {}) {
         ...(config.palette === undefined ? {} : { palette: config.palette }),
         ...(config.along === undefined ? {} : { along: config.along }),
         ...(config.kit === undefined ? {} : { kit: config.kit }),
+        ...(config.solid === undefined ? {} : { solid: config.solid }),
     });
 }
 export function pad(config) {

package/dist/world/footprintGrid.d.ts

@@ -16,6 +16,10 @@ export interface FootprintReservation {
     kind: string;
     cells: readonly GridCell[];
 }
+/** Plain JSON state of a {@link FootprintGrid}: live reservations in claim order. */
+export interface FootprintGridState {
+    reservations: FootprintReservation[];
+}
 /** Handle returned by {@link createFootprintGrid}. */
 export interface FootprintGrid {
     readonly cellSize: number;
@@ -30,6 +34,9 @@ export interface FootprintGrid {
     reservationOf(id: string): FootprintReservation | null;
     list(): readonly FootprintReservation[];
     clear(): void;
+    snapshot(): FootprintGridState;
+    /** Replaces every reservation with `next`'s and rebuilds cell occupancy from them. */
+    restore(next: FootprintGridState): void;
 }
 /**
  * Multi-cell footprint occupancy/reservation on a shared build grid — `world/placementController`