@jgengine/core 0.18.1 → 0.21.0

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;
 }
 /**
@@ -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`
@@ -55,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[];

package/dist/world/footprintGrid.js

@@ -1,6 +1,9 @@
 function cellKey(cell) {
     return `${cell.col}:${cell.row}`;
 }
+function copyReservation(reservation) {
+    return { id: reservation.id, kind: reservation.kind, cells: reservation.cells.map((cell) => ({ col: cell.col, row: cell.row })) };
+}
 /**
  * Multi-cell footprint occupancy/reservation on a shared build grid — `world/placementController`
  * only owns the ghost preview; this is the persistent claim a committed placement holds so the next
@@ -70,6 +73,19 @@ export function createFootprintGrid(options = {}) {
             occupied.clear();
             reservations.clear();
         },
+        snapshot() {
+            return { reservations: Array.from(reservations.values(), copyReservation) };
+        },
+        restore(next) {
+            occupied.clear();
+            reservations.clear();
+            for (const reservation of next.reservations) {
+                const copy = copyReservation(reservation);
+                reservations.set(copy.id, copy);
+                for (const cell of copy.cells)
+                    occupied.set(cellKey(cell), copy.id);
+            }
+        },
     };
 }
 const CARDINAL_OFFSETS = [
@@ -111,6 +127,207 @@ export function hasValidAdjacency(grid, cells, accepts, requireConnection = fals
         return false;
     return !requireConnection || neighbors.some((neighbor) => accepts(neighbor.kind));
 }
+function validId(id) { return typeof id === "string" && id.length > 0; }
+function validCapacity(capacity) { return Number.isFinite(capacity) && capacity >= 0; }
+function contributionCount(region) {
+    if (region === null || typeof region !== "object")
+        return null;
+    if (!Array.isArray(region.cells))
+        return null;
+    if (!("contributions" in region))
+        return 1;
+    return Array.isArray(region.contributions) ? region.contributions.length : null;
+}
+function withinRegionBudget(regions, budget) {
+    let cells = 0;
+    let contributions = 0;
+    for (const region of regions) {
+        const count = contributionCount(region);
+        if (count === null)
+            return false;
+        cells += region.cells.length;
+        contributions += count;
+    }
+    for (const [limit, count] of [[budget.maxCells, cells], [budget.maxContributions, contributions]]) {
+        if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 0 || count > limit))
+            return false;
+    }
+    return true;
+}
+function regionCells(cells) {
+    if (cells.length === 0)
+        return null;
+    const out = new Map();
+    for (const cell of cells) {
+        if (cell === null || typeof cell !== "object")
+            return null;
+        if (!Number.isSafeInteger(cell.col) || !Number.isSafeInteger(cell.row))
+            return null;
+        const key = cellKey(cell);
+        if (out.has(key))
+            return null;
+        out.set(key, cell);
+    }
+    return out;
+}
+function connectedRegion(cells) {
+    const first = cells.values().next().value;
+    if (first === undefined)
+        return false;
+    const queue = [first];
+    const visited = new Set([cellKey(first)]);
+    for (let index = 0; index < queue.length; index++) {
+        const cell = queue[index];
+        for (const offset of CARDINAL_OFFSETS) {
+            const key = cellKey({ col: cell.col + offset.col, row: cell.row + offset.row });
+            const next = cells.get(key);
+            if (next !== undefined && !visited.has(key)) {
+                visited.add(key);
+                queue.push(next);
+            }
+        }
+    }
+    return queue.length === cells.size;
+}
+function checkedRegion(region) {
+    if (!validId(region.id) || !validId(region.kind) || !Number.isFinite(region.tier) || !validCapacity(region.capacity))
+        return null;
+    const cells = regionCells(region.cells);
+    if (cells === null || !connectedRegion(cells))
+        return null;
+    const contributions = "contributions" in region ? region.contributions : [region];
+    if (contributions.length === 0)
+        return null;
+    const ids = new Set();
+    const covered = new Set();
+    let capacity = 0;
+    for (const contribution of contributions) {
+        if (contribution === null || typeof contribution !== "object")
+            return null;
+        if (!validId(contribution.id) || ids.has(contribution.id) || !validCapacity(contribution.capacity) || !Array.isArray(contribution.cells))
+            return null;
+        if (contribution.cells.length > cells.size - covered.size)
+            return null;
+        ids.add(contribution.id);
+        const partCells = regionCells(contribution.cells);
+        if (partCells === null || !connectedRegion(partCells))
+            return null;
+        for (const key of partCells.keys()) {
+            if (!cells.has(key) || covered.has(key))
+                return null;
+            covered.add(key);
+        }
+        capacity += contribution.capacity;
+    }
+    if (!Number.isFinite(capacity) || capacity !== region.capacity || covered.size !== cells.size)
+        return null;
+    return { cells, contributions, ids };
+}
+function mergeableRegions(a, b, budget) {
+    if (!withinRegionBudget([a, b], budget) || a.id === b.id || a.kind !== b.kind || a.tier !== b.tier)
+        return null;
+    const left = checkedRegion(a);
+    const right = checkedRegion(b);
+    if (left === null || right === null)
+        return null;
+    if (right.ids.has(a.id) || left.ids.has(b.id))
+        return null;
+    for (const id of left.ids)
+        if (right.ids.has(id))
+            return null;
+    let adjacent = false;
+    for (const [key, cell] of left.cells) {
+        if (right.cells.has(key))
+            return null;
+        for (const offset of CARDINAL_OFFSETS) {
+            if (right.cells.has(cellKey({ col: cell.col + offset.col, row: cell.row + offset.row })))
+                adjacent = true;
+        }
+    }
+    let capacity = 0;
+    for (const contribution of left.contributions)
+        capacity += contribution.capacity;
+    for (const contribution of right.contributions)
+        capacity += contribution.capacity;
+    return adjacent && Number.isFinite(capacity) ? [left, right] : null;
+}
+function copyRegionCells(cells) {
+    return cells.map(cell => ({ col: cell.col, row: cell.row }));
+}
+function pooledRegion(id, kind, tier, parts) {
+    const contributions = parts.map(part => ({ id: part.id, capacity: part.capacity, cells: copyRegionCells(part.cells) }));
+    return { id, kind, tier, capacity: contributions.reduce((sum, part) => sum + part.capacity, 0),
+        cells: contributions.flatMap(part => copyRegionCells(part.cells)), contributions };
+}
+/** 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 function canMerge(a, b, budget = {}) {
+    return mergeableRegions(a, b, budget) !== null;
+}
+/**
+ * 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 function mergeFootprints(a, b, id, budget = {}) {
+    if (!validId(id))
+        return null;
+    const checked = mergeableRegions(a, b, budget);
+    if (checked === null)
+        return null;
+    return pooledRegion(id, a.kind, a.tier, [...checked[0].contributions, ...checked[1].contributions]);
+}
+/**
+ * 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 function splitRegion(region, leftIds, ids = {}, budget = {}) {
+    if (!withinRegionBudget([region], budget))
+        return null;
+    const checked = checkedRegion(region);
+    if (checked === null || leftIds.length === 0 || leftIds.length >= checked.contributions.length)
+        return null;
+    const selected = new Set();
+    for (const id of leftIds) {
+        if (!checked.ids.has(id) || selected.has(id))
+            return null;
+        selected.add(id);
+    }
+    const left = [];
+    const right = [];
+    for (const part of checked.contributions)
+        (selected.has(part.id) ? left : right).push(part);
+    function side(parts, id) {
+        if (parts.length === 1) {
+            const part = parts[0];
+            if (id !== undefined && id !== part.id)
+                return null;
+            return { id: part.id, kind: region.kind, tier: region.tier, capacity: part.capacity, cells: copyRegionCells(part.cells) };
+        }
+        if (id === undefined || !validId(id))
+            return null;
+        const pooled = pooledRegion(id, region.kind, region.tier, parts);
+        const cells = regionCells(pooled.cells);
+        return cells !== null && connectedRegion(cells) ? pooled : null;
+    }
+    const a = side(left, ids.left);
+    const b = side(right, ids.right);
+    if (a === null || b === null || a.id === b.id)
+        return null;
+    if (right.some(part => part.id === a.id) || left.some(part => part.id === b.id))
+        return null;
+    return [a, b];
+}
 /** Bridges live reservations into `world/placement`'s `PlacementRules.obstacles` so `validatePlacement`/`createPlacementController` see the grid's committed footprints unchanged. */
 export function footprintObstacles(grid) {
     return grid.list().map((reservation) => {

package/dist/world/interiors.d.ts

@@ -32,4 +32,5 @@ export interface Interiors {
     toInterior(id: string, exterior: Vec2): Vec2 | null;
     toExterior(id: string, interior: Vec2): Vec2 | null;
 }
+/** Frame conversion and bounded movement across an exterior and its interiors; holds config only, no play state. */
 export declare function createInteriors(config?: InteriorsConfig): Interiors;

package/dist/world/interiors.js

@@ -14,12 +14,14 @@ function toExteriorFrame(interior, local) {
     const rotated = rotate(local, interior.rotation ?? 0);
     return [rotated[0] + interior.origin[0], rotated[1] + interior.origin[1]];
 }
+function indexInteriors(interiors) {
+    return new Map(interiors.map((interior) => [interior.id, interior]));
+}
+/** Frame conversion and bounded movement across an exterior and its interiors; holds config only, no play state. */
 export function createInteriors(config = {}) {
     const radius = config.radius ?? 0;
     const exterior = config.exterior ?? {};
-    const byId = new Map();
-    for (const interior of config.interiors ?? [])
-        byId.set(interior.id, interior);
+    const byId = indexInteriors(config.interiors ?? []);
     return {
         move(location, delta) {
             if (location.space.kind === "exterior") {

package/dist/world/lod.d.ts

@@ -7,11 +7,17 @@ export interface LodSchedulerConfig {
     beyondInterval?: number | null;
     stagger?: boolean;
 }
+/** Plain JSON state of a {@link LodScheduler}: each id's accumulated seconds. */
+export interface LodSchedulerState {
+    buckets: Record<string, number>;
+}
 export interface LodScheduler {
     bandIndex(distance: number): number;
     step(id: string, distance: number, dtSeconds: number): number;
     remove(id: string): void;
     clear(): void;
     size(): number;
+    snapshot(): LodSchedulerState;
+    restore(next: LodSchedulerState): void;
 }
 export declare function createLodScheduler(config: LodSchedulerConfig): LodScheduler;

package/dist/world/lod.js

@@ -62,5 +62,13 @@ export function createLodScheduler(config) {
         size() {
             return buckets.size;
         },
+        snapshot() {
+            return { buckets: Object.fromEntries(buckets) };
+        },
+        restore(next) {
+            buckets.clear();
+            for (const [id, seconds] of Object.entries(next.buckets))
+                buckets.set(id, seconds);
+        },
     };
 }

package/dist/world/pathTerrain.d.ts

@@ -7,7 +7,7 @@
  * (O(points) per sample), and serializable; it composes onto any height sampler and pairs with
  * `resolveTerrainField` so the same authored path drives both the rendered mesh and player collision.
  * @capability path-terrain flatten / grade / carve a heightfield from an authored path with retaining profiles
- * @consumer packages/core/src/world/terrain.ts (resolveTerrainField), Games/the-robots roads
+ * @consumer packages/core/src/world/terrain.ts (resolveTerrainField), Games/scrap-signal roads
  */
 import type { Vec2 } from "./geometry.js";
 /**

package/dist/world/terraform.d.ts

@@ -148,7 +148,7 @@ export interface EditableTerrain extends TerrainField {
     revertSurfaceDelta(delta: SurfaceDelta): void;
     /** The current material layer stack (lower index paints under higher). */
     readonly layers: readonly TerrainMaterialLayer[];
-    /** Replace the material layer stack; drops blend weights whose layer index no longer exists. */
+    /** Replace the material stack, retaining weights by layer id and normalizing when painted layers are removed. */
     setLayers(layers: readonly TerrainMaterialLayer[]): void;
     /**
      * Paint the active `edit.surface` layer's blend weight into the brush footprint, pushing the
@@ -262,5 +262,13 @@ export interface TerraformBrush {
     config(): Required<Omit<TerraformBrushConfig, "surface">> & {
         surface: string | undefined;
     };
+    /** The retunable brush settings; the terrain keeps its own `snapshot()`. */
+    snapshot(): TerraformBrushState;
+    restore(next: TerraformBrushState): void;
+}
+/** Plain JSON state of a {@link TerraformBrush}. */
+export interface TerraformBrushState {
+    radius: number;
+    strength: number;
 }
 export declare function createTerraformBrush(terrain: Pick<EditableTerrain, "apply">, config?: TerraformBrushConfig): TerraformBrush;

package/dist/world/terraform.js

@@ -123,14 +123,12 @@ export function createEditableTerrain(config) {
         const cx = gridX(edit.center[0]);
         const cz = gridZ(edit.center[1]);
         let changed = 0;
-        for (let iz = -rCells; iz <= rCells; iz += 1) {
-            const gz = Math.round(cz) + iz;
-            if (gz < 0 || gz >= vertsZ)
-                continue;
-            for (let ix = -rCells; ix <= rCells; ix += 1) {
-                const gx = Math.round(cx) + ix;
-                if (gx < 0 || gx >= vertsX)
-                    continue;
+        const minZ = Math.max(0, Math.round(cz) - rCells);
+        const maxZ = Math.min(vertsZ - 1, Math.round(cz) + rCells);
+        const minX = Math.max(0, Math.round(cx) - rCells);
+        const maxX = Math.min(vertsX - 1, Math.round(cx) + rCells);
+        for (let gz = minZ; gz <= maxZ; gz += 1) {
+            for (let gx = minX; gx <= maxX; gx += 1) {
                 const wx = vertexWorldX(gx);
                 const wz = vertexWorldZ(gz);
                 const dx = wx - edit.center[0];
@@ -230,14 +228,12 @@ export function createEditableTerrain(config) {
         const rCells = Math.ceil(edit.radius / cellSize) + 1;
         const cx = gridX(edit.center[0]);
         const cz = gridZ(edit.center[1]);
-        for (let iz = -rCells; iz <= rCells; iz += 1) {
-            const gz = Math.floor(cz) + iz;
-            if (gz < 0 || gz >= rows)
-                continue;
-            for (let ix = -rCells; ix <= rCells; ix += 1) {
-                const gx = Math.floor(cx) + ix;
-                if (gx < 0 || gx >= cols)
-                    continue;
+        const minZ = Math.max(0, Math.floor(cz) - rCells);
+        const maxZ = Math.min(rows - 1, Math.floor(cz) + rCells);
+        const minX = Math.max(0, Math.floor(cx) - rCells);
+        const maxX = Math.min(cols - 1, Math.floor(cx) + rCells);
+        for (let gz = minZ; gz <= maxZ; gz += 1) {
+            for (let gx = minX; gx <= maxX; gx += 1) {
                 const wx = cellWorldX(gx);
                 const wz = cellWorldZ(gz);
                 const dx = wx - edit.center[0];
@@ -469,9 +465,41 @@ export function createEditableTerrain(config) {
             return layers;
         },
         setLayers(next) {
+            const previous = layers;
+            const previousWeights = weights;
             layers = next.map((layer) => ({ ...layer }));
-            // Layer count changed shape: drop the weight buffer, blends re-seed from surfaces on demand.
-            weights = null;
+            if (previousWeights === null || layers.length === 0) {
+                weights = null;
+                return;
+            }
+            const previousIndices = layers.map((layer) => previous.findIndex((entry) => entry.id === layer.id));
+            const buffer = new Float32Array(cellCount * layers.length);
+            let retained = false;
+            for (let cell = 0; cell < cellCount; cell += 1) {
+                let total = 0;
+                for (let layer = 0; layer < layers.length; layer += 1) {
+                    const before = previousIndices[layer];
+                    const weight = before < 0 ? 0 : previousWeights[cell * previous.length + before];
+                    buffer[cell * layers.length + layer] = weight;
+                    total += weight;
+                }
+                if (total > 0) {
+                    retained = true;
+                    let previousTotal = 0;
+                    for (let layer = 0; layer < previous.length; layer += 1)
+                        previousTotal += previousWeights[cell * previous.length + layer];
+                    if (total < previousTotal) {
+                        for (let layer = 0; layer < layers.length; layer += 1)
+                            buffer[cell * layers.length + layer] /= total;
+                    }
+                }
+                else {
+                    const fallback = layers.findIndex((layer) => layer.surface === surfaces[cell]);
+                    if (fallback >= 0)
+                        buffer[cell * layers.length + fallback] = 1;
+                }
+            }
+            weights = retained ? buffer : null;
         },
         blendRecording(edit, record) {
             return blendPaint(edit, record);
@@ -787,5 +815,12 @@ export function createTerraformBrush(terrain, config = {}) {
         config() {
             return { radius, strength, falloff, surface };
         },
+        snapshot() {
+            return { radius, strength };
+        },
+        restore(next) {
+            radius = next.radius;
+            strength = next.strength;
+        },
     };
 }