@jgengine/core 0.18.1 → 0.21.0

package/dist/world/walls.d.ts

@@ -50,6 +50,11 @@ export interface SurfacePaintStore {
 }
 /** @internal */
 export declare function createSurfacePaint(): SurfacePaintStore;
+/** Plain JSON state of a {@link WallDrawTool}: the drawn points and whether the loop is closed. */
+export interface WallDrawToolState {
+    points: Vec2[];
+    closed: boolean;
+}
 export interface WallDrawTool {
     addPoint(point: Vec2, snap?: number): Vec2;
     undo(): void;
@@ -60,6 +65,8 @@ export interface WallDrawTool {
     isClosed(): boolean;
     footprint(): EnclosedFootprint | null;
     roof(config?: RoofConfig): RoofPlan | null;
+    snapshot(): WallDrawToolState;
+    restore(next: WallDrawToolState): void;
 }
 /** @internal */
 export declare function createWallDrawTool(config?: {

package/dist/world/walls.js

@@ -220,6 +220,13 @@ export function createWallDrawTool(config = {}) {
             const fp = this.footprint();
             return fp === null ? null : autoRoof(fp, roofConfig);
         },
+        snapshot() {
+            return { points: pts.map((point) => [point[0], point[1]]), closed };
+        },
+        restore(next) {
+            pts = next.points.map((point) => [point[0], point[1]]);
+            closed = next.closed;
+        },
     };
 }
 /** @internal */

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)

package/dist/world/worldSolids.d.ts

@@ -0,0 +1,95 @@
+import type { GeneratedBuilding } from "./buildings.js";
+import type { EnvironmentWorldFeature } from "./features.js";
+import type { Aabb } from "./geometry.js";
+import type { WallSegment } from "./walls.js";
+/** One solid box in world space: the collision half of generated or authored world geometry. */
+export interface WorldSolid {
+    center: readonly [number, number, number];
+    halfExtents: readonly [number, number, number];
+    /** Yaw about `center`, radians, in the engine's `rotationY` convention. Default `0`. */
+    rotationY?: number;
+}
+/** Serializable contents of a {@link WorldSolids}: every layer's solids by layer id. */
+export interface WorldSolidsState {
+    layers: Record<string, readonly WorldSolid[]>;
+}
+/** Caller-owned work counters, reset by each world-solid ray candidate query. */
+export interface WorldSolidRayWork {
+    /** Hash-grid cell lookups, including empty cells. */
+    cells: number;
+    /** Indexed entry visits, including duplicates removed before bounds tests. */
+    entries: number;
+    /** Cached AABB ray tests after deduplication. */
+    bounds: number;
+}
+/**
+ * Static collision for world geometry that is not a scene object: generated buildings, studio
+ * volumes like `city`, wall runs. Solids live in named layers so a feature can replace or drop its
+ * own set without touching the rest. `solidObstaclesNear` (player and NPC movement),
+ * `syncWorldColliders` (physics backends) and `populateNavGridFromSolids` all read this one store.
+ */
+export interface WorldSolids {
+    /** Replace a layer's solids; an empty list removes the layer. */
+    set(layer: string, solids: readonly WorldSolid[]): void;
+    remove(layer: string): void;
+    /** Run several `set`/`remove` calls as one change: one index rebuild, one notification. */
+    batch(apply: () => void): void;
+    /** Solids in one layer, empty when absent. */
+    layer(layer: string): readonly WorldSolid[];
+    layers(): readonly string[];
+    /** Every solid whose world AABB overlaps `min`..`max`. Bounded by a uniform XZ hash grid. */
+    inBox(min: readonly [number, number, number], max: readonly [number, number, number]): WorldSolid[];
+    /** Optional accelerated ray candidates; finite coordinates/direction and nonnegative finite distance, normalized internally. */
+    inRay?(origin: readonly [number, number, number], direction: readonly [number, number, number], maxDistance: number, work?: WorldSolidRayWork): WorldSolid[];
+    /** Every solid in every layer. */
+    all(): WorldSolid[];
+    count(): number;
+    /** Bumps on every change; cheap cache key for consumers. */
+    version(): number;
+    subscribe(listener: () => void): () => void;
+    snapshot(): WorldSolidsState;
+    restore(state: WorldSolidsState): void;
+}
+/**
+ * Yaw-expanded world AABB of an oriented solid box.
+ * @capability world-solid-bounds world AABB and nav footprint of a world solid
+ */
+export declare function worldSolidBounds(solid: WorldSolid): {
+    min: [number, number, number];
+    max: [number, number, number];
+};
+/**
+ * XZ footprint of a solid's world AABB, for 2D consumers such as nav grids.
+ * @capability world-solid-bounds world AABB and nav footprint of a world solid
+ */
+export declare function worldSolidFootprint(solid: WorldSolid): Aabb;
+/**
+ * A store of static world solids in named layers.
+ * @capability world-solids collision for generated and authored world geometry (buildings, city lots, walls)
+ */
+export declare function createWorldSolids(options?: {
+    cellSize?: number;
+}): WorldSolids;
+/**
+ * One solid per generated building: its `bounds` footprint turned by `rotationY` about `center`,
+ * from the ground under its center up through its floors. `groundHeight` defaults to flat `0`.
+ * @capability world-solids-from-data derive collision boxes from generated buildings and wall runs
+ */
+export declare function buildingSolids(buildings: readonly GeneratedBuilding[], groundHeight?: (x: number, z: number) => number): WorldSolid[];
+/**
+ * Solids for every `structures` descriptor on an environment feature, skipping any marked `solid: false`.
+ * @capability world-solids-from-data derive collision boxes from generated buildings and wall runs
+ */
+export declare function structureSolids(world: EnvironmentWorldFeature, groundHeight?: (x: number, z: number) => number): WorldSolid[];
+/** Wall height, thickness and base for {@link wallSolids}. */
+export interface WallSolidOptions {
+    height: number;
+    thickness: number;
+    /** Ground height under a point; the wall stands on it at each segment's midpoint. Default flat `0`. */
+    groundHeight?: (x: number, z: number) => number;
+}
+/**
+ * One oriented solid per wall segment (see `wallSegments` in `world/walls`).
+ * @capability world-solids-from-data derive collision boxes from generated buildings and wall runs
+ */
+export declare function wallSolids(segments: readonly WallSegment[], options: WallSolidOptions): WorldSolid[];