@jgengine/core 0.18.1 → 0.21.0

package/dist/world/authoredWeather.js

@@ -0,0 +1,314 @@
+import { createEnvironmentField } from "./envField.js";
+import { windField } from "./wind.js";
+const MAX_ENTRIES = 256;
+const MAX_MAGNITUDE = 1_000_000;
+const MAX_DOMAIN = 1_000_000_000_000;
+const MODES = ["clear", "rain", "snow", "mixed", "dust"];
+const CLEAR = { mode: "clear", intensity: 0 };
+function identifier(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0 || value.length > 128)
+        throw new Error(`${label} must be a nonempty string of at most 128 characters`);
+}
+function finite(value, label, min = -Infinity, max = Infinity) {
+    if (!Number.isFinite(value) || value < min || value > max)
+        throw new Error(`${label} must be finite and within ${min}..${max}`);
+}
+function objectKeys(value, allowed, label) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+    for (const key of Object.keys(value))
+        if (!allowed.includes(key))
+            throw new Error(`${label}.${key}: unknown field`);
+}
+function conditions(value, profile = false) {
+    objectKeys(value, ["mode", "intensity", "temperatureOffset", "lightning", ...(profile ? ["id"] : [])], "weather conditions");
+    if (!MODES.includes(value.mode))
+        throw new Error(`unknown weather mode: ${value.mode}`);
+    finite(value.intensity, "weather intensity", 0);
+    if (value.intensity > 1)
+        throw new Error("weather intensity must be <= 1");
+    if (value.temperatureOffset !== undefined)
+        finite(value.temperatureOffset, "weather temperatureOffset", -MAX_MAGNITUDE, MAX_MAGNITUDE);
+    if (value.lightning !== undefined) {
+        finite(value.lightning, "weather lightning", 0);
+        if (value.lightning > 1)
+            throw new Error("weather lightning must be <= 1");
+    }
+}
+function validateWind(value) {
+    if (value === undefined)
+        return;
+    objectKeys(value, ["direction", "speed", "gust", "gustFrequency", "turbulence", "seed"], "wind");
+    if (value.direction !== undefined) {
+        if (!Array.isArray(value.direction) || value.direction.length !== 2)
+            throw new Error("wind direction requires world X,Z");
+        for (const axis of value.direction)
+            finite(axis, "wind direction", -MAX_MAGNITUDE, MAX_MAGNITUDE);
+    }
+    for (const key of ["speed", "gust", "gustFrequency", "turbulence"]) {
+        if (value[key] !== undefined)
+            finite(value[key], `wind.${key}`, 0, key === "gustFrequency" ? 1000 : MAX_MAGNITUDE);
+    }
+    if (value.seed !== undefined && typeof value.seed !== "string")
+        finite(value.seed, "wind seed");
+}
+/** Validate authoring references and work bounds before persisting a weather document.
+ * @capability authored-weather-validation Reject invalid weather profiles, schedules, zones and wind before authoring mutations.
+ */
+export function validateAuthoredWeather(config) {
+    objectKeys(config, ["ambient", "profiles", "initialProfileId", "schedule", "wind", "zones"], "weather");
+    for (const list of [config.profiles, config.schedule, config.zones]) {
+        if (list !== undefined && !Array.isArray(list))
+            throw new Error("weather profiles, schedule and zones must be arrays");
+        if (list !== undefined && list.length > MAX_ENTRIES)
+            throw new Error(`weather lists are limited to ${MAX_ENTRIES} entries`);
+    }
+    if (config.ambient !== undefined)
+        conditions(config.ambient);
+    validateWind(config.wind);
+    const ids = new Set();
+    for (const profile of config.profiles ?? []) {
+        identifier(profile.id, "weather profile id");
+        if (!profile.id || ids.has(profile.id))
+            throw new Error(`invalid or duplicate weather profile: ${profile.id}`);
+        ids.add(profile.id);
+        conditions(profile, true);
+    }
+    if (config.initialProfileId !== undefined)
+        identifier(config.initialProfileId, "initial weather profile id");
+    if (config.initialProfileId !== undefined && !ids.has(config.initialProfileId))
+        throw new Error(`unknown initial weather profile: ${config.initialProfileId}`);
+    let previous = -1;
+    for (const entry of config.schedule ?? []) {
+        objectKeys(entry, ["atSeconds", "profileId", "transitionSeconds"], "weather schedule");
+        identifier(entry.profileId, "scheduled weather profile id");
+        finite(entry.atSeconds, "weather schedule time", 0, MAX_DOMAIN);
+        if (entry.atSeconds <= previous)
+            throw new Error("weather schedule times must be strictly increasing");
+        previous = entry.atSeconds;
+        if (!ids.has(entry.profileId))
+            throw new Error(`unknown weather profile: ${entry.profileId}`);
+        if (entry.transitionSeconds !== undefined)
+            finite(entry.transitionSeconds, "weather transition duration", 0, MAX_DOMAIN);
+    }
+    ids.clear();
+    for (const zone of config.zones ?? []) {
+        objectKeys(zone, ["id", "center", "radius", "falloff", "weather", "wind", "radial"], "weather zone");
+        identifier(zone.id, "weather zone id");
+        if (zone.radial !== undefined && typeof zone.radial !== "boolean")
+            throw new Error("weather zone radial must be boolean");
+        if (!zone.id || ids.has(zone.id))
+            throw new Error(`invalid or duplicate weather zone: ${zone.id}`);
+        ids.add(zone.id);
+        if (!Array.isArray(zone.center) || zone.center.length !== 2)
+            throw new Error("weather zone center requires world X,Z");
+        for (const axis of zone.center)
+            finite(axis, "weather zone center", -MAX_DOMAIN, MAX_DOMAIN);
+        finite(zone.radius, "weather zone radius", Number.MIN_VALUE, MAX_DOMAIN);
+        if (zone.falloff !== undefined)
+            finite(zone.falloff, "weather zone falloff", 0, MAX_DOMAIN);
+        if (zone.weather !== undefined)
+            conditions(zone.weather);
+        validateWind(zone.wind);
+    }
+}
+function amounts(value) {
+    return [
+        value.mode === "rain" ? value.intensity : value.mode === "mixed" ? value.intensity * 0.5 : 0,
+        value.mode === "snow" ? value.intensity : value.mode === "mixed" ? value.intensity * 0.5 : 0,
+        value.mode === "dust" ? value.intensity : 0,
+    ];
+}
+function modeOf(rain, snow, dust) {
+    if (rain > 0 && snow > 0)
+        return "mixed";
+    if (rain > 0)
+        return "rain";
+    if (snow > 0)
+        return "snow";
+    return dust > 0 ? "dust" : "clear";
+}
+function blendOf(value) {
+    const [rain, snow, dust] = amounts(value);
+    return { rain, snow, dust, temperatureOffset: value.temperatureOffset ?? 0, lightning: value.lightning ?? 0 };
+}
+function blend(a, b, weight) {
+    const out = { ...a };
+    for (const key of ["rain", "snow", "dust", "temperatureOffset", "lightning"])
+        out[key] += (b[key] - a[key]) * weight;
+    return out;
+}
+function scheduledWeather(initial, transitions, time) {
+    let current = initial;
+    for (const entry of transitions) {
+        if (time < entry.at)
+            break;
+        current = blend(entry.from, entry.to, entry.duration === 0 ? 1 : Math.min(1, (time - entry.at) / entry.duration));
+    }
+    return current;
+}
+function compileWeather(source) {
+    validateAuthoredWeather(source);
+    const config = JSON.parse(JSON.stringify(source));
+    const profiles = new Map((config.profiles ?? []).map((profile) => [profile.id, Object.freeze(blendOf(profile))]));
+    const initial = config.initialProfileId === undefined ? Object.freeze(blendOf(config.ambient ?? CLEAR)) : profiles.get(config.initialProfileId);
+    const ambientWind = config.wind === undefined ? null : windField(config.wind);
+    const zones = (config.zones ?? []).map((zone) => Object.freeze({ zone, field: zone.wind === undefined ? null : windField(zone.wind) }));
+    const transitions = [];
+    for (const entry of config.schedule ?? []) {
+        transitions.push(Object.freeze({ at: entry.atSeconds, duration: entry.transitionSeconds ?? 0, from: Object.freeze(scheduledWeather(initial, transitions, entry.atSeconds)), to: profiles.get(entry.profileId) }));
+    }
+    return Object.freeze({ initial, profiles, ambientWind, zones: Object.freeze(zones), transitions: Object.freeze(transitions) });
+}
+/** Pure authored weather sampling; the caller's simulation clock owns pause, replay and restore.
+ * @capability authored-weather Sample scheduled precipitation and local wind from one authored document and simulation clock.
+ */
+export function createAuthoredWeather(source = {}) {
+    const compiled = compileWeather(source);
+    return {
+        sample(x, z, timeSeconds) {
+            finite(x, "weather sample x", -MAX_DOMAIN, MAX_DOMAIN);
+            finite(z, "weather sample z", -MAX_DOMAIN, MAX_DOMAIN);
+            finite(timeSeconds, "weather sample time", 0, MAX_DOMAIN);
+            let value = scheduledWeather(compiled.initial, compiled.transitions, timeSeconds);
+            const ambient = compiled.ambientWind?.atPoint(x, z, timeSeconds) ?? [0, 0];
+            let wx = ambient[0];
+            let wz = ambient[1];
+            for (const { zone, field } of compiled.zones) {
+                const dx = x - zone.center[0];
+                const dz = z - zone.center[1];
+                const distance = Math.hypot(dx, dz);
+                const falloff = zone.falloff ?? 0;
+                if (distance > zone.radius + falloff)
+                    continue;
+                const t = distance <= zone.radius ? 1 : 1 - (distance - zone.radius) / falloff;
+                const weight = t * t * (3 - 2 * t);
+                if (zone.weather !== undefined)
+                    value = blend(value, blendOf(zone.weather), weight);
+                if (field !== null) {
+                    const vector = zoneWind(field, zone.radial ?? false, dx, dz, distance, timeSeconds);
+                    wx += vector[0] * weight;
+                    wz += vector[1] * weight;
+                }
+            }
+            const precipitation = value.rain + value.snow;
+            return { ...value, mode: modeOf(value.rain, value.snow, value.dust), intensity: Math.min(1, precipitation + value.dust), timeSeconds, wind: [wx, wz], precipitation };
+        },
+    };
+}
+function zoneWind(field, radial, dx, dz, distance, time) {
+    if (!radial)
+        return field.atPoint(dx, dz, time);
+    if (distance === 0)
+        return [0, 0];
+    const speed = field.strengthAt(dx, dz, time);
+    return [dx / distance * speed, dz / distance * speed];
+}
+function exposureConfig(config) {
+    const out = { maxSurfaces: config.maxSurfaces ?? 1024, wettingRate: config.wettingRate ?? 0.2, dryingRate: config.dryingRate ?? 0.05, snowRate: config.snowRate ?? 0.1, meltRate: config.meltRate ?? 0.02 };
+    if (!Number.isInteger(out.maxSurfaces) || out.maxSurfaces < 1 || out.maxSurfaces > 65_536)
+        throw new Error("weather exposure maxSurfaces must be an integer in 1..65536");
+    for (const key of ["wettingRate", "dryingRate", "snowRate", "meltRate"])
+        finite(out[key], `weather exposure ${key}`, 0);
+    return out;
+}
+const clamp01 = (value) => Math.max(0, Math.min(1, value));
+/** Bounded surface accumulation shared by gameplay and material adapters, with injected persistence.
+ * @capability weather-surface-accumulation Persist and retune bounded surface wetness, snow, temperature and exposure independently of rendering.
+ */
+export function createWeatherExposure(config = {}, storage) {
+    let tuning = exposureConfig(config);
+    const values = new Map();
+    const snapshot = () => ({ surfaces: Array.from(values, ([id, value]) => ({ id, value: { ...value } })) });
+    const persist = () => storage?.write(snapshot());
+    function restore(state) {
+        if (state.surfaces.length > tuning.maxSurfaces)
+            throw new Error("weather exposure snapshot exceeds capacity");
+        const next = new Map();
+        for (const entry of state.surfaces) {
+            if (!entry.id || next.has(entry.id))
+                throw new Error("weather exposure snapshot has invalid surface ids");
+            for (const key of ["wetness", "snow", "heat", "exposure"])
+                finite(entry.value[key], `weather exposure ${key}`);
+            for (const key of ["wetness", "snow", "exposure"])
+                if (entry.value[key] < 0 || entry.value[key] > 1)
+                    throw new Error(`weather exposure ${key} must be in 0..1`);
+            next.set(entry.id, { ...entry.value });
+        }
+        values.clear();
+        for (const [id, value] of next)
+            values.set(id, value);
+        persist();
+    }
+    const saved = storage?.read();
+    if (saved !== undefined)
+        restore(saved);
+    return {
+        step(dt, timeSeconds, surfaces, weather) {
+            finite(dt, "weather exposure dt", 0);
+            finite(timeSeconds, "weather exposure time", 0);
+            if (dt === 0)
+                return;
+            if (surfaces.length > tuning.maxSurfaces)
+                throw new Error("weather exposure step exceeds capacity");
+            const ids = new Set();
+            let added = 0;
+            for (const surface of surfaces) {
+                if (!surface.id || ids.has(surface.id))
+                    throw new Error("weather exposure step has invalid surface ids");
+                ids.add(surface.id);
+                finite(surface.x, "weather exposure x");
+                finite(surface.z, "weather exposure z");
+                if (surface.exposure !== undefined)
+                    finite(surface.exposure, "weather exposure exposure", 0);
+                if ((surface.exposure ?? 1) > 1)
+                    throw new Error("weather exposure exposure must be <= 1");
+                if (surface.temperature !== undefined)
+                    finite(surface.temperature, "weather exposure temperature");
+                if (!values.has(surface.id))
+                    added += 1;
+            }
+            if (values.size + added > tuning.maxSurfaces)
+                throw new Error("weather exposure capacity exhausted; forget unused surfaces");
+            for (const surface of surfaces) {
+                const sample = weather.sample(surface.x, surface.z, timeSeconds);
+                const current = values.get(surface.id) ?? { wetness: 0, snow: 0, heat: 0, exposure: 1 };
+                const exposure = surface.exposure ?? 1;
+                const heat = surface.temperature ?? sample.temperatureOffset ?? 0;
+                const rain = sample.rain * exposure;
+                const snowfall = sample.snow * exposure * tuning.snowRate * dt;
+                const melt = Math.min(current.snow + snowfall, Math.max(0, heat) * tuning.meltRate * dt);
+                values.set(surface.id, {
+                    wetness: clamp01(current.wetness + (rain * tuning.wettingRate - (1 - rain) * tuning.dryingRate) * dt + melt),
+                    snow: clamp01(current.snow + snowfall - melt),
+                    heat,
+                    exposure,
+                });
+            }
+            persist();
+        },
+        sample(id) { const value = values.get(id); return value === undefined ? null : { ...value }; },
+        forget(id) { if (values.delete(id))
+            persist(); },
+        snapshot,
+        restore,
+        retune(next) {
+            const resolved = exposureConfig(next);
+            if (values.size > resolved.maxSurfaces)
+                throw new Error("weather exposure retune capacity is below retained surface count");
+            tuning = resolved;
+        },
+    };
+}
+/** Environment temperature, sunlight and shelter read the same authored precipitation as rendering.
+ * @capability weather-environment-field Connect authored precipitation and temperature changes to spatial environment queries.
+ */
+export function createWeatherEnvironmentField(weather, config = {}) {
+    const base = createEnvironmentField({ ...config, rain: (x, z, time) => weather.sample(x, z, time).rain });
+    const temperature = (x, z, time, y) => base.temperature(x, z, time, y) + (weather.sample(x, z, time).temperatureOffset ?? 0);
+    return {
+        ...base,
+        temperature,
+        sample(x, z, time, y) { return { ...base.sample(x, z, time, y), temperature: temperature(x, z, time, y) }; },
+    };
+}

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,8 @@
  * 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 MaterialAsset, type MaterialAssignment } from "../material/materialAsset.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 +33,10 @@ 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;
+    /** Editor-authored mesh/slot selectors applied after the broad tint and surface. */
+    materialAssignments?: readonly MaterialAssignment[];
     /**
      * 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
@@ -47,6 +52,8 @@ export interface BuildingKitPart {
  */
 export interface BuildingKit {
     id: string;
+    /** The caller's existing editor-document material assets; only assigned IDs are loaded. */
+    materialAssets?: readonly MaterialAsset[];
     /** 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. */
@@ -61,6 +68,7 @@ export type BuildingKitPartInput = string | BuildingKitPart;
 /** The authoring shape {@link defineBuildingKit} normalizes into a {@link BuildingKit}. */
 export interface BuildingKitInput {
     id?: string;
+    materialAssets?: readonly MaterialAsset[];
     parts: Readonly<Partial<Record<BuildingPartKind, readonly BuildingKitPartInput[]>>>;
     slots?: Readonly<Record<string, readonly BuildingKitPartInput[]>>;
     omit?: readonly BuildingPartKind[];
@@ -83,10 +91,9 @@ export type BuildingKitBinding = {
 };
 /**
  * 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.
+ * Throws on empty variants or invalid editor material references/selectors before loading models.
  *
- * @capability building-kit bind generated facade part slots to real models instead of untextured blocks
+ * @capability building-kit bind generated facade part slots to caller models and editor-authored named materials
  */
 export declare function defineBuildingKit(input: BuildingKitInput): BuildingKit;
 /**

package/dist/world/buildingKit.js

@@ -1,36 +1,49 @@
+/**
+ * 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 { parseMaterialAssignments, validateMaterialAssignments } from "../material/materialAsset.js";
 const BOX = { type: "box" };
 const OMIT = { type: "omit" };
 const DEFAULT_FIT = "stretch";
-function normalizePart(input, where) {
+function normalizePart(input, where, assets) {
     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.`);
     }
+    if (part.materialAssignments !== undefined) {
+        const assignments = parseMaterialAssignments(part.materialAssignments);
+        const errors = validateMaterialAssignments(assignments, assets, { disallowedTextureRoles: ["height"] }).filter(item => item.severity === "error");
+        if (errors.length > 0)
+            throw new Error(`Building kit ${where}: ${errors.map(item => `${item.path}: ${item.message}`).join("; ")}`);
+        return { ...part, materialAssignments: assignments };
+    }
     return part;
 }
-function normalizeList(list, where) {
+function normalizeList(list, where, assets) {
     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));
+    return list.map((entry) => normalizePart(entry, where, assets));
 }
 /**
  * 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.
+ * Throws on empty variants or invalid editor material references/selectors before loading models.
  *
- * @capability building-kit bind generated facade part slots to real models instead of untextured blocks
+ * @capability building-kit bind generated facade part slots to caller models and editor-authored named materials
  */
 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}"`);
+        parts[kind] = normalizeList(list, `"${input.id ?? "kit"}" part "${kind}"`, input.materialAssets ?? []);
     }
     const kit = {
         id: input.id ?? "building-kit",
         parts,
+        ...(input.materialAssets === undefined ? {} : { materialAssets: input.materialAssets }),
         ...(input.omit === undefined ? {} : { omit: input.omit }),
         ...(input.fit === undefined ? {} : { fit: input.fit }),
     };
@@ -38,7 +51,7 @@ export function defineBuildingKit(input) {
         return kit;
     const slots = {};
     for (const [key, list] of Object.entries(input.slots)) {
-        slots[key] = normalizeList(list, `"${kit.id}" slot "${key}"`);
+        slots[key] = normalizeList(list, `"${kit.id}" slot "${key}"`, input.materialAssets ?? []);
     }
     return { ...kit, slots };
 }

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

@@ -0,0 +1,21 @@
+import type { GameContext } from "../runtime/gameContextTypes.js";
+import type { MotionIntents } from "../runtime/motionIntents.js";
+/** The game selects affected players, coupling, target bits and its acceleration limit. */
+export interface EnvironmentMotionTarget {
+    entityId: string;
+    motion: Pick<MotionIntents, "impulse" | "pushHorizontal">;
+    /** Wind coupling in 1/second; supported range 0..1e12. */
+    windResponse: number;
+    /** Maximum combined acceleration in metres/second²; supported range 0..1e12. */
+    maxAcceleration: number;
+    mask?: number;
+    /** Opt into authored shelter exposure scaling for wind and localized forces. */
+    sheltered?: boolean;
+}
+/** Inject authoritative spatial forces before existing movement consumes its motion intents.
+ * @capability environment-motion apply capped spatial wind and vortex forces to game-selected actors through shared motion intents
+ */
+export declare function installEnvironmentMotion(ctx: GameContext, options: {
+    targets: () => readonly EnvironmentMotionTarget[];
+    maxTargets?: number;
+}): () => void;