@jgengine/core 0.19.0 → 0.22.0

package/dist/world/footprintGrid.js

@@ -127,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/grassKind.d.ts

@@ -16,6 +16,16 @@ export interface GrassRules {
     density: number;
     /** Blade height in meters. */
     bladeHeight: number;
+    /** Blade-width range in metres; endpoints are normalized on read. */
+    bladeWidthMin: number;
+    bladeWidthMax: number;
+    /** Bend range, 0..1. */
+    bladeBendMin: number;
+    bladeBendMax: number;
+    /** Spread of blades around each tuft root, in metres. */
+    tuftRadius: number;
+    /** Normal lift toward the sky, 0..1; controls the card lighting response. */
+    normalLift: number;
     /** Base (root) color, hex. */
     colorBase: string;
     /** Tip color, hex. */

package/dist/world/grassKind.js

@@ -15,6 +15,12 @@ export const GRASS_FIELD_KIND = "grass_field";
 export const GRASS_DEFAULTS = {
     density: 12,
     bladeHeight: 0.6,
+    bladeWidthMin: 0.05,
+    bladeWidthMax: 0.1,
+    bladeBendMin: 0.12,
+    bladeBendMax: 0.42,
+    tuftRadius: 0.16,
+    normalLift: 0.6,
     colorBase: "#3f6f37",
     colorTip: "#9ac25a",
     colorVariation: 0.35,
@@ -29,6 +35,12 @@ export const GRASS_SCHEMA = {
     fields: [
         { type: "range", key: "density", label: "density", min: 0.5, max: 160, step: 0.5, default: GRASS_DEFAULTS.density, unit: "/m²" },
         { type: "range", key: "bladeHeight", label: "blade height", min: 0.1, max: 2, step: 0.05, default: GRASS_DEFAULTS.bladeHeight, unit: "m" },
+        { type: "range", key: "bladeWidthMin", label: "minimum blade width", min: 0.005, max: 0.3, step: 0.005, default: GRASS_DEFAULTS.bladeWidthMin, unit: "m" },
+        { type: "range", key: "bladeWidthMax", label: "maximum blade width", min: 0.005, max: 0.3, step: 0.005, default: GRASS_DEFAULTS.bladeWidthMax, unit: "m" },
+        { type: "range", key: "bladeBendMin", label: "minimum bend", min: 0, max: 1, step: 0.01, default: GRASS_DEFAULTS.bladeBendMin },
+        { type: "range", key: "bladeBendMax", label: "maximum bend", min: 0, max: 1, step: 0.01, default: GRASS_DEFAULTS.bladeBendMax },
+        { type: "range", key: "tuftRadius", label: "tuft radius", min: 0, max: 0.6, step: 0.01, default: GRASS_DEFAULTS.tuftRadius, unit: "m" },
+        { type: "range", key: "normalLift", label: "normal lift", min: 0, max: 1, step: 0.01, default: GRASS_DEFAULTS.normalLift },
         { type: "color", key: "colorBase", label: "base color", default: GRASS_DEFAULTS.colorBase },
         { type: "color", key: "colorTip", label: "tip color", default: GRASS_DEFAULTS.colorTip },
         { type: "range", key: "colorVariation", label: "color variation", min: 0, max: 1, step: 0.02, default: GRASS_DEFAULTS.colorVariation },
@@ -49,9 +61,19 @@ function metaString(meta, key, fallback) {
 }
 /** Parse a volume's `meta` into fully-defaulted grass rules. @internal */
 export function readGrassRules(meta) {
+    const widthMin = Math.max(0.005, metaNumber(meta, "bladeWidthMin", GRASS_DEFAULTS.bladeWidthMin));
+    const widthMax = Math.max(0.005, metaNumber(meta, "bladeWidthMax", GRASS_DEFAULTS.bladeWidthMax));
+    const bendMin = Math.max(0, Math.min(1, metaNumber(meta, "bladeBendMin", GRASS_DEFAULTS.bladeBendMin)));
+    const bendMax = Math.max(0, Math.min(1, metaNumber(meta, "bladeBendMax", GRASS_DEFAULTS.bladeBendMax)));
     return {
         density: Math.max(0, metaNumber(meta, "density", GRASS_DEFAULTS.density)),
         bladeHeight: Math.max(0.05, metaNumber(meta, "bladeHeight", GRASS_DEFAULTS.bladeHeight)),
+        bladeWidthMin: Math.min(widthMin, widthMax),
+        bladeWidthMax: Math.max(widthMin, widthMax),
+        bladeBendMin: Math.min(bendMin, bendMax),
+        bladeBendMax: Math.max(bendMin, bendMax),
+        tuftRadius: Math.max(0, metaNumber(meta, "tuftRadius", GRASS_DEFAULTS.tuftRadius)),
+        normalLift: Math.max(0, Math.min(1, metaNumber(meta, "normalLift", GRASS_DEFAULTS.normalLift))),
         colorBase: metaString(meta, "colorBase", GRASS_DEFAULTS.colorBase),
         colorTip: metaString(meta, "colorTip", GRASS_DEFAULTS.colorTip),
         colorVariation: metaNumber(meta, "colorVariation", GRASS_DEFAULTS.colorVariation),

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

@@ -53,7 +53,7 @@ export interface TerrainMaterialLayer {
     tiling?: number;
     /** Project the material on all three axes to hide stretching on cliffs. */
     triplanar?: boolean;
-    /** Hex color multiplied over the surface color. */
+    /** Authored hex color replacing the default surface palette color in editor and runtime. */
     tint?: string;
     /** Layer master opacity 0..1 — scales this layer's blend weight everywhere. */
     opacity?: number;
@@ -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

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);

package/dist/world/weather.d.ts

@@ -48,19 +48,34 @@ export interface FireGridConfig {
     wind?: WindVector;
     /** How strongly wind biases downwind vs upwind spread, 0..1. Default 0.6. */
     windBias?: number;
+    /** Hard allocation bound; defaults to 65536 cells. */
+    maxCells?: number;
 }
+/** Live fire ignition, spread, consumption and wind policies; grid geometry stays fixed. */
+export type FireGridTuning = Pick<FireGridConfig, "ignitionThreshold" | "spreadRate" | "burnRate" | "wind" | "windBias">;
 export interface FireStepOptions {
     /** Global spread multiplier this step (rain suppression from resolveWeather().spread). Default 1. */
     spread?: number;
+    /** Live wind in metres/second along world X,Z, overriding configured wind this step. */
+    wind?: WindVector;
+    windAt?: (x: number, z: number) => WindVector;
     /** Per-cell wetness 0..1 that resists ignition — from an environment field. */
     wetnessAt?: (col: number, row: number) => number;
+    /** Heat removed per second at full wetness; 0 (default) leaves extinction to game policy. */
+    extinguishRate?: number;
 }
 export interface FireGrid {
     readonly cols: number;
     readonly rows: number;
+    readonly cellSize: number;
+    readonly origin: readonly [number, number];
     /** Advance the cellular propagation by game-time `dt`. */
     step(dt: number, options?: FireStepOptions): void;
     igniteCell(col: number, row: number): void;
+    /** Cool a burning cell to unburnt without replacing its remaining fuel. */
+    extinguishCell(col: number, row: number): boolean;
+    /** Extinguish the cell under a world position; false outside the grid or when not burning. */
+    extinguish(x: number, z: number): boolean;
     /** Ignite the cell under a world position; no-op if outside the grid. */
     ignite(x: number, z: number): boolean;
     cell(col: number, row: number): FireCell;
@@ -73,5 +88,7 @@ export interface FireGrid {
     readonly burning: number;
     /** Flat snapshot (row-major) for rendering. */
     snapshot(): FireCell[];
+    restore(state: readonly FireCell[]): void;
+    retune(tuning: FireGridTuning): void;
 }
 export declare function createFireGrid(config: FireGridConfig): FireGrid;

package/dist/world/weather.js

@@ -29,39 +29,66 @@ const NEIGHBOURS = [
 ];
 export function createFireGrid(config) {
     const { cols, rows, cellSize } = config;
-    if (cols <= 0 || rows <= 0)
-        throw new Error("createFireGrid: cols/rows must be positive");
+    const maxCells = config.maxCells ?? 65_536;
+    if (!Number.isSafeInteger(maxCells) || maxCells < 1 || maxCells > 1_048_576)
+        throw new Error("createFireGrid: maxCells must be an integer in 1..1048576");
+    if (!Number.isSafeInteger(cols) || !Number.isSafeInteger(rows) || cols <= 0 || rows <= 0 || cols * rows > maxCells)
+        throw new Error("createFireGrid: cols/rows must be positive integers within maxCells");
+    if (!Number.isFinite(cellSize) || cellSize <= 0)
+        throw new Error("createFireGrid: cellSize must be finite and positive");
     const originX = config.origin?.[0] ?? 0;
     const originZ = config.origin?.[1] ?? 0;
-    const ignitionThreshold = config.ignitionThreshold ?? 1;
-    const spreadRate = config.spreadRate ?? 0.6;
-    const burnRate = config.burnRate ?? 0.25;
-    const windBias = Math.max(0, Math.min(1, config.windBias ?? 0.6));
-    const wind = config.wind;
-    const windLen = wind === undefined ? 0 : Math.hypot(wind[0], wind[1]);
-    const windX = windLen > 0 ? wind[0] / windLen : 0;
-    const windZ = windLen > 0 ? wind[1] / windLen : 0;
+    if (!Number.isFinite(originX) || !Number.isFinite(originZ))
+        throw new Error("createFireGrid: origin must be finite");
+    let ignitionThreshold = 1;
+    let spreadRate = 0.6;
+    let burnRate = 0.25;
+    let windBias = 0.6;
+    let wind;
+    function retune(tuning) {
+        for (const key of ["ignitionThreshold", "spreadRate", "burnRate", "windBias"]) {
+            const value = tuning[key];
+            if (value !== undefined && (!Number.isFinite(value) || value < 0 || (key === "windBias" && value > 1)))
+                throw new Error(`fire ${key} is invalid`);
+        }
+        if (tuning.wind !== undefined && (!Number.isFinite(tuning.wind[0]) || !Number.isFinite(tuning.wind[1])))
+            throw new Error("fire wind must be finite");
+        ignitionThreshold = tuning.ignitionThreshold ?? ignitionThreshold;
+        spreadRate = tuning.spreadRate ?? spreadRate;
+        burnRate = tuning.burnRate ?? burnRate;
+        windBias = tuning.windBias ?? windBias;
+        if (tuning.wind !== undefined)
+            wind = [tuning.wind[0], tuning.wind[1]];
+    }
+    retune(config);
     const cells = new Array(cols * rows);
     for (let row = 0; row < rows; row += 1) {
         for (let col = 0; col < cols; col += 1) {
             const fuel = config.fuelAt?.(col, row) ?? 1;
+            if (!Number.isFinite(fuel) || fuel < 0)
+                throw new Error("fire initial fuel must be finite and nonnegative");
             cells[row * cols + col] = { fuel: Math.max(0, fuel), heat: 0, state: "unburnt" };
         }
     }
     const index = (col, row) => row * cols + col;
-    const inBounds = (col, row) => col >= 0 && col < cols && row >= 0 && row < rows;
+    const inBounds = (col, row) => Number.isInteger(col) && Number.isInteger(row) && col >= 0 && col < cols && row >= 0 && row < rows;
     const cellCoord = (x, z) => {
         const col = Math.round((x - originX) / cellSize);
         const row = Math.round((z - originZ) / cellSize);
         return inBounds(col, row) ? { col, row } : null;
     };
-    const directionalWeight = (dx, dz) => {
+    const directionalWeight = (dx, dz, vector) => {
+        if (vector === undefined)
+            return 1;
+        const windLen = Math.hypot(vector[0], vector[1]);
         if (windLen === 0)
             return 1;
         const len = Math.hypot(dx, dz) || 1;
-        const alignment = (dx / len) * windX + (dz / len) * windZ;
+        const alignment = (dx / len) * vector[0] / windLen + (dz / len) * vector[1] / windLen;
         return 1 + windBias * alignment;
     };
+    const addedHeat = new Float64Array(cols * rows);
+    const wetness = new Float64Array(cols * rows);
     let burning = 0;
     for (const cell of cells)
         if (cell.state === "burning")
@@ -77,20 +104,71 @@ export function createFireGrid(config) {
         cell.state = "burning";
         cell.heat = Math.max(cell.heat, ignitionThreshold);
     };
+    const extinguishCell = (col, row) => {
+        if (!inBounds(col, row))
+            return false;
+        const cell = cells[index(col, row)];
+        if (cell.state !== "burning")
+            return false;
+        cell.state = "unburnt";
+        cell.heat = 0;
+        burning -= 1;
+        return true;
+    };
     return {
         cols,
         rows,
+        cellSize,
+        origin: [originX, originZ],
+        retune,
+        restore(state) {
+            if (state.length !== cells.length)
+                throw new Error("fire snapshot dimensions do not match");
+            const next = state.map((cell) => {
+                if (!Number.isFinite(cell.fuel) || cell.fuel < 0 || !Number.isFinite(cell.heat) || cell.heat < 0 || !["unburnt", "burning", "burnt"].includes(cell.state) || (cell.state === "burning" && cell.fuel <= 0) || (cell.state === "burnt" && (cell.fuel !== 0 || cell.heat !== 0)))
+                    throw new Error("invalid fire snapshot cell");
+                return { ...cell };
+            });
+            burning = 0;
+            for (let i = 0; i < cells.length; i += 1) {
+                cells[i] = next[i];
+                if (cells[i].state === "burning")
+                    burning += 1;
+            }
+        },
         step(dt, options) {
-            if (dt <= 0)
+            if (!Number.isFinite(dt) || dt < 0)
+                throw new Error("fire dt must be finite and nonnegative");
+            if (dt === 0)
                 return;
             const globalSpread = options?.spread ?? 1;
+            if (!Number.isFinite(globalSpread) || globalSpread < 0)
+                throw new Error("fire spread multiplier must be finite and nonnegative");
             const wetnessAt = options?.wetnessAt;
-            const addedHeat = new Float64Array(cols * rows);
+            const extinguishRate = options?.extinguishRate ?? 0;
+            if (!Number.isFinite(extinguishRate) || extinguishRate < 0)
+                throw new Error("fire extinguishRate must be finite and nonnegative");
+            const resolveWetness = (col, row) => {
+                const value = wetnessAt?.(col, row) ?? 0;
+                if (!Number.isFinite(value))
+                    throw new Error("fire wetness must be finite");
+                return Math.max(0, Math.min(1, value));
+            };
+            addedHeat.fill(0);
+            wetness.fill(0);
             for (let row = 0; row < rows; row += 1) {
                 for (let col = 0; col < cols; col += 1) {
                     const cell = cells[index(col, row)];
                     if (cell.state !== "burning")
                         continue;
+                    const vector = options?.windAt?.(originX + col * cellSize, originZ + row * cellSize) ?? options?.wind ?? wind;
+                    if (vector !== undefined && (!Number.isFinite(vector[0]) || !Number.isFinite(vector[1])))
+                        throw new Error("fire step wind must be finite");
+                    const i = index(col, row);
+                    if (extinguishRate > 0)
+                        wetness[i] = resolveWetness(col, row);
+                    const coolingRate = extinguishRate * wetness[i];
+                    const burningDt = Math.min(dt, burnRate === 0 ? Infinity : cell.fuel / burnRate, coolingRate === 0 ? Infinity : cell.heat / coolingRate);
                     for (const [dx, dz] of NEIGHBOURS) {
                         const nc = col + dx;
                         const nr = row + dz;
@@ -100,7 +178,7 @@ export function createFireGrid(config) {
                         if (neighbour.state === "burnt" || neighbour.fuel <= 0)
                             continue;
                         addedHeat[index(nc, nr)] +=
-                            spreadRate * globalSpread * directionalWeight(dx, dz) * dt;
+                            spreadRate * globalSpread * directionalWeight(dx, dz, vector) * burningDt;
                     }
                 }
             }
@@ -108,19 +186,32 @@ export function createFireGrid(config) {
                 for (let col = 0; col < cols; col += 1) {
                     const i = index(col, row);
                     const cell = cells[i];
+                    if (cell.state === "unburnt" && (addedHeat[i] > 0 || (extinguishRate > 0 && cell.heat > 0)))
+                        wetness[i] = resolveWetness(col, row);
+                }
+            }
+            for (let row = 0; row < rows; row += 1) {
+                for (let col = 0; col < cols; col += 1) {
+                    const i = index(col, row);
+                    const cell = cells[i];
+                    const coolingRate = extinguishRate * wetness[i];
                     if (cell.state === "burning") {
-                        cell.fuel = Math.max(0, cell.fuel - burnRate * dt);
+                        const burningDt = Math.min(dt, coolingRate === 0 ? Infinity : cell.heat / coolingRate);
+                        cell.fuel = Math.max(0, cell.fuel - burnRate * burningDt);
+                        cell.heat = Math.max(0, cell.heat - coolingRate * dt);
                         if (cell.fuel <= 0) {
                             cell.state = "burnt";
                             cell.heat = 0;
                             burning -= 1;
                         }
+                        else if (coolingRate > 0 && cell.heat <= 0) {
+                            extinguishCell(col, row);
+                        }
                         continue;
                     }
-                    if (cell.state !== "unburnt" || addedHeat[i] === 0)
+                    if (cell.state !== "unburnt" || (addedHeat[i] === 0 && coolingRate === 0))
                         continue;
-                    const resist = wetnessAt === undefined ? 0 : Math.max(0, Math.min(1, wetnessAt(col, row)));
-                    cell.heat += addedHeat[i] * (1 - resist);
+                    cell.heat = Math.max(0, cell.heat + addedHeat[i] * (1 - wetness[i]) - coolingRate * dt);
                     if (cell.heat >= ignitionThreshold && cell.fuel > 0) {
                         cell.state = "burning";
                         burning += 1;
@@ -129,6 +220,11 @@ export function createFireGrid(config) {
             }
         },
         igniteCell,
+        extinguishCell,
+        extinguish(x, z) {
+            const coord = cellCoord(x, z);
+            return coord !== null && extinguishCell(coord.col, coord.row);
+        },
         ignite(x, z) {
             const coord = cellCoord(x, z);
             if (coord === null)