@jgengine/core 0.19.0 → 0.22.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/buildingKit.d.ts

@@ -3,6 +3,7 @@
  * as an instanced asset kit instead of untextured blocks. Pure serializable data — core resolves
  * bindings, the renderer loads them.
  */
+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`
@@ -34,6 +35,8 @@ export interface BuildingKitPart {
     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
@@ -49,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. */
@@ -63,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[];
@@ -85,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/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;

package/dist/world/environmentForces.js

@@ -0,0 +1,42 @@
+/** 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 function installEnvironmentMotion(ctx, options) {
+    const limit = options.maxTargets ?? 64;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 4096)
+        throw new Error("environment motion target budget must be an integer in 1..4096");
+    const seen = new Set();
+    const pending = [];
+    return ctx.sim.addStage({
+        id: "environment-motion",
+        phase: "beforeMovement",
+        run(_realDt, _tick, gameDt) {
+            if (gameDt <= 0)
+                return;
+            const targets = options.targets();
+            if (targets.length > limit)
+                throw new Error("environment motion target budget exceeded");
+            seen.clear();
+            pending.length = 0;
+            for (const target of targets) {
+                if (!target || typeof target.entityId !== "string" || target.entityId.length === 0 || typeof target.motion?.pushHorizontal !== "function" || typeof target.motion?.impulse !== "function")
+                    throw new Error("environment motion target requires an entity id and motion sink");
+                if (seen.has(target.entityId))
+                    throw new Error(`duplicate environment motion target ${target.entityId}`);
+                seen.add(target.entityId);
+                const entity = ctx.scene.entity.get(target.entityId);
+                if (entity === null)
+                    continue;
+                const acceleration = ctx.environment.accelerationAt(entity.position, ctx.time.now(), target.windResponse, target.maxAcceleration, target.mask ?? 0);
+                const exposure = target.sheltered === true ? ctx.environment.exposureAt(...entity.position) : 1;
+                pending.push({ target, acceleration, exposure });
+            }
+            for (const { target, acceleration, exposure } of pending) {
+                if (acceleration[0] !== 0 || acceleration[2] !== 0)
+                    target.motion.pushHorizontal(acceleration[0] * gameDt * exposure, acceleration[2] * gameDt * exposure);
+                if (acceleration[1] !== 0)
+                    target.motion.impulse(acceleration[1] * gameDt * exposure);
+            }
+        },
+    });
+}

package/dist/world/features.d.ts

@@ -66,13 +66,13 @@ export interface TerrainDetailConfig {
  * PBR map URLs for a real ground texture — the same shape
  * `buildMaterialCatalog({ basePath }).resolve(id)!.maps` from `@jgengine/assets` returns. Kept
  * dependency-free here so `core` never imports the assets package; any URLs (pulled maps, a CDN, a
- * data URI) satisfy it.
+ * data URI) satisfy it. Omitted roughness keeps the terrain scalar; omitted AO skips occlusion sampling.
  */
 export interface TerrainMaterialMaps {
     color: string;
     normal: string;
-    roughness: string;
-    ao: string;
+    roughness?: string;
+    ao?: string;
     displacement: string;
 }
 /**

package/dist/world/footprintGrid.d.ts

@@ -62,5 +62,60 @@ export declare function boundaryNeighbors(grid: FootprintGrid, cells: readonly G
  * (no occupied neighbors at all) passes unless `requireConnection` demands one.
  */
 export declare function hasValidAdjacency(grid: FootprintGrid, cells: readonly GridCell[], accepts: (neighborKind: string) => boolean, requireConnection?: boolean): boolean;
+/** Caller-owned logical footprint. Cells must be unique, safe integer addresses and cardinally connected. */
+export interface RegionFootprint {
+    readonly id: string;
+    readonly kind: string;
+    readonly tier: number;
+    readonly cells: readonly GridCell[];
+    /** Nonnegative finite contribution; independent of occupied area. */
+    readonly capacity: number;
+}
+/** Original footprint identity and capacity retained when regions pool. */
+export interface RegionContribution {
+    readonly id: string;
+    readonly cells: readonly GridCell[];
+    readonly capacity: number;
+}
+/** Plain JSON pooled region. Contributions partition its cells and sum to its capacity. */
+export interface MergedRegion extends RegionFootprint {
+    readonly contributions: readonly RegionContribution[];
+}
+/** Optional caller work limits, checked before cell traversal. Omitted limits follow input size. */
+export interface RegionWorkBudget {
+    readonly maxCells?: number;
+    readonly maxContributions?: number;
+}
+/** Identities for split sides containing multiple contributions; singletons retain their original id. */
+export interface RegionSplitIds {
+    readonly left?: string;
+    readonly right?: string;
+}
+/** A standalone footprint or a pooled region carrying its original contributions. */
+export type FootprintRegion = RegionFootprint | MergedRegion;
+/** Matching kind/tier, disjoint valid source identities/cells, and cardinal contact. Linear in input size.
+ * @capability mergeable-footprint-regions check compatible adjacent regions within caller work budgets
+ */
+export declare function canMerge(a: FootprintRegion, b: FootprintRegion, budget?: RegionWorkBudget): boolean;
+/**
+ * Pool compatible footprints under caller-owned `id`, retaining original capacities and identities.
+ * Returns null for invalid data, kind/tier mismatch, overlap, no cardinal contact or exhausted budget.
+ * Does not mutate inputs or grid reservations; costs, merge width and upgrade policy remain caller-owned.
+ * Capacity is the ordered JavaScript-number sum of original contributions, independent of cell area.
+ *
+ * @capability merge-footprint-regions pool adjacent compatible footprints with serializable capacity provenance
+ */
+export declare function mergeFootprints(a: FootprintRegion, b: FootprintRegion, id: string, budget?: RegionWorkBudget): MergedRegion | null;
+/**
+ * Partition whole original contributions by `leftIds`; both sides must remain cardinally connected.
+ * Singletons restore their original id and capacity; larger sides require explicit output identities.
+ * Returns null for invalid provenance/budget, unknown or duplicate ids, empty/disconnected sides, or
+ * conflicting output identities (including identities from the opposite side's contributions).
+ * An output may reuse its own side's source identity. Cell cuts/capacity repricing require caller policy.
+ * Both sides inherit the current region kind/tier. Inputs and grid reservations remain unchanged.
+ *
+ * @capability split-footprint-regions split pooled regions along retained contributions without area-based capacity loss
+ */
+export declare function splitRegion(region: MergedRegion, leftIds: readonly string[], ids?: RegionSplitIds, budget?: RegionWorkBudget): [FootprintRegion, FootprintRegion] | null;
 /** Bridges live reservations into `world/placement`'s `PlacementRules.obstacles` so `validatePlacement`/`createPlacementController` see the grid's committed footprints unchanged. */
 export declare function footprintObstacles(grid: FootprintGrid): PlacementObstacle[];