@jgengine/core 0.6.0 → 0.7.0

package/dist/world/support.js

@@ -0,0 +1,75 @@
+export function solveSupport(pieces, links, config = {}) {
+    const maxDistance = config.maxDistance ?? Infinity;
+    const ids = new Set(pieces.map((piece) => piece.id));
+    const adjacency = new Map();
+    for (const id of ids)
+        adjacency.set(id, []);
+    for (const link of links) {
+        if (!ids.has(link.a) || !ids.has(link.b))
+            continue;
+        adjacency.get(link.a).push(link.b);
+        adjacency.get(link.b).push(link.a);
+    }
+    const distance = {};
+    const queue = [];
+    for (const piece of pieces) {
+        if (piece.grounded === true) {
+            distance[piece.id] = 0;
+            queue.push(piece.id);
+        }
+    }
+    let head = 0;
+    while (head < queue.length) {
+        const current = queue[head];
+        head += 1;
+        const currentDistance = distance[current];
+        if (currentDistance >= maxDistance)
+            continue;
+        for (const neighbor of adjacency.get(current) ?? []) {
+            const next = currentDistance + 1;
+            if (distance[neighbor] === undefined || next < distance[neighbor]) {
+                distance[neighbor] = next;
+                queue.push(neighbor);
+            }
+        }
+    }
+    const supported = [];
+    const unsupported = [];
+    for (const piece of pieces) {
+        const d = distance[piece.id];
+        if (d !== undefined && d <= maxDistance)
+            supported.push(piece.id);
+        else
+            unsupported.push(piece.id);
+    }
+    return { supported, unsupported, distance };
+}
+function scatterHash(seed, index) {
+    let h = (seed ^ Math.imul(index + 1, 0x9e3779b1)) >>> 0;
+    h = Math.imul(h ^ (h >>> 15), 0x85ebca6b);
+    h ^= h >>> 13;
+    return ((h >>> 0) / 4294967295) * 2 - 1;
+}
+export function toDebrisBodies(pieces, collapsedIds, options = {}) {
+    const scatter = options.scatter ?? 1.5;
+    const seed = options.seed ?? 1;
+    const collapse = new Set(collapsedIds);
+    const bodies = [];
+    let index = 0;
+    for (const piece of pieces) {
+        if (!collapse.has(piece.id))
+            continue;
+        const position = piece.position ?? [0, 0, 0];
+        const halfExtents = piece.halfExtents ?? [0.5, 0.5, 0.5];
+        const vx = scatterHash(seed, index) * scatter;
+        const vz = scatterHash(seed, index + 977) * scatter;
+        bodies.push({
+            position,
+            halfExtents,
+            velocity: [vx, 0, vz],
+            ...(piece.mass === undefined ? {} : { mass: piece.mass }),
+        });
+        index += 1;
+    }
+    return bodies;
+}

package/dist/world/terraform.d.ts

@@ -0,0 +1,54 @@
+import type { Aabb, Vec2 } from "./geometry.js";
+import { type TerrainField } from "./terrain.js";
+export type TerraformMode = "raise" | "lower" | "flatten" | "paint";
+export type TerraformFalloff = "smooth" | "linear" | "none";
+export interface TerraformEdit {
+    mode: TerraformMode;
+    center: Vec2;
+    radius: number;
+    strength?: number;
+    target?: number;
+    surface?: string;
+    falloff?: TerraformFalloff;
+}
+export interface EditableTerrainConfig {
+    bounds: Aabb;
+    base?: TerrainField;
+    cellSize?: number;
+}
+export interface TerraformSnapshot {
+    bounds: Aabb;
+    cellSize: number;
+    cols: number;
+    rows: number;
+    offsets: readonly number[];
+    surfaces: readonly (string | null)[];
+}
+export interface EditableTerrain extends TerrainField {
+    apply(edit: TerraformEdit): number;
+    heightOffsetAt(x: number, z: number): number;
+    surfaceAt(x: number, z: number): string | null;
+    reset(): void;
+    snapshot(): TerraformSnapshot;
+    restore(snapshot: TerraformSnapshot): void;
+}
+export declare function brushWeight(distance: number, radius: number, falloff: TerraformFalloff): number;
+export declare function createEditableTerrain(config: EditableTerrainConfig): EditableTerrain;
+export interface TerraformBrushConfig {
+    radius?: number;
+    strength?: number;
+    falloff?: TerraformFalloff;
+    surface?: string;
+}
+export interface TerraformBrush {
+    raise(center: Vec2): number;
+    lower(center: Vec2): number;
+    flatten(center: Vec2, target?: number): number;
+    paint(center: Vec2, surface?: string): number;
+    setRadius(radius: number): void;
+    setStrength(strength: number): void;
+    config(): Required<Omit<TerraformBrushConfig, "surface">> & {
+        surface: string | undefined;
+    };
+}
+export declare function createTerraformBrush(terrain: Pick<EditableTerrain, "apply">, config?: TerraformBrushConfig): TerraformBrush;

package/dist/world/terraform.js

@@ -0,0 +1,186 @@
+import { FLAT_FIELD, withNormal } from "./terrain.js";
+export function brushWeight(distance, radius, falloff) {
+    if (radius <= 0)
+        return distance <= 0 ? 1 : 0;
+    const t = distance / radius;
+    if (t >= 1)
+        return 0;
+    if (falloff === "none")
+        return 1;
+    if (falloff === "linear")
+        return 1 - t;
+    const s = 1 - t;
+    return s * s * (3 - 2 * s);
+}
+function clampIndex(value, max) {
+    return value < 0 ? 0 : value > max ? max : value;
+}
+export function createEditableTerrain(config) {
+    const base = config.base ?? FLAT_FIELD;
+    const bounds = config.bounds;
+    const cellSize = config.cellSize && config.cellSize > 0 ? config.cellSize : 1;
+    const spanX = Math.max(bounds.maxX - bounds.minX, cellSize);
+    const spanZ = Math.max(bounds.maxZ - bounds.minZ, cellSize);
+    const cols = Math.max(1, Math.round(spanX / cellSize));
+    const rows = Math.max(1, Math.round(spanZ / cellSize));
+    const vertsX = cols + 1;
+    const vertsZ = rows + 1;
+    const offsets = new Float32Array(vertsX * vertsZ);
+    const surfaces = new Array(cols * rows).fill(null);
+    function gridX(x) {
+        return ((x - bounds.minX) / spanX) * cols;
+    }
+    function gridZ(z) {
+        return ((z - bounds.minZ) / spanZ) * rows;
+    }
+    function heightOffsetAt(x, z) {
+        const fx = gridX(x);
+        const fz = gridZ(z);
+        const x0 = clampIndex(Math.floor(fx), cols);
+        const z0 = clampIndex(Math.floor(fz), rows);
+        const x1 = clampIndex(x0 + 1, cols);
+        const z1 = clampIndex(z0 + 1, rows);
+        const tx = fx - x0 < 0 ? 0 : fx - x0 > 1 ? 1 : fx - x0;
+        const tz = fz - z0 < 0 ? 0 : fz - z0 > 1 ? 1 : fz - z0;
+        const v00 = offsets[z0 * vertsX + x0];
+        const v10 = offsets[z0 * vertsX + x1];
+        const v01 = offsets[z1 * vertsX + x0];
+        const v11 = offsets[z1 * vertsX + x1];
+        const top = v00 + (v10 - v00) * tx;
+        const bottom = v01 + (v11 - v01) * tx;
+        return top + (bottom - top) * tz;
+    }
+    const sampleHeight = (x, z) => base.sampleHeight(x, z) + heightOffsetAt(x, z);
+    const sampleNormal = withNormal(sampleHeight);
+    function editHeight(edit) {
+        const falloff = edit.falloff ?? "smooth";
+        const strength = edit.strength ?? 1;
+        const target = edit.mode === "flatten" ? edit.target ?? sampleHeight(edit.center[0], edit.center[1]) : 0;
+        const rCells = Math.ceil(edit.radius / cellSize) + 1;
+        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 wx = bounds.minX + (gx / cols) * spanX;
+                const wz = bounds.minZ + (gz / rows) * spanZ;
+                const dist = Math.hypot(wx - edit.center[0], wz - edit.center[1]);
+                const weight = brushWeight(dist, edit.radius, falloff);
+                if (weight <= 0)
+                    continue;
+                const index = gz * vertsX + gx;
+                if (edit.mode === "raise")
+                    offsets[index] += strength * weight;
+                else if (edit.mode === "lower")
+                    offsets[index] -= strength * weight;
+                else {
+                    const current = base.sampleHeight(wx, wz) + offsets[index];
+                    offsets[index] += (target - current) * weight * strength;
+                }
+                changed += 1;
+            }
+        }
+        return changed;
+    }
+    function paintSurface(edit) {
+        const surface = edit.surface ?? null;
+        const rCells = Math.ceil(edit.radius / cellSize) + 1;
+        const cx = gridX(edit.center[0]);
+        const cz = gridZ(edit.center[1]);
+        let painted = 0;
+        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 wx = bounds.minX + ((gx + 0.5) / cols) * spanX;
+                const wz = bounds.minZ + ((gz + 0.5) / rows) * spanZ;
+                if (Math.hypot(wx - edit.center[0], wz - edit.center[1]) > edit.radius)
+                    continue;
+                surfaces[gz * cols + gx] = surface;
+                painted += 1;
+            }
+        }
+        return painted;
+    }
+    function surfaceAt(x, z) {
+        const gx = Math.floor(gridX(x));
+        const gz = Math.floor(gridZ(z));
+        if (gx < 0 || gx >= cols || gz < 0 || gz >= rows)
+            return null;
+        return surfaces[gz * cols + gx] ?? null;
+    }
+    const field = {
+        sampleHeight,
+        sampleNormal,
+        ...(base.bounds === undefined ? {} : { bounds: base.bounds }),
+        ...(base.waterLevel === undefined ? {} : { waterLevel: base.waterLevel }),
+        apply(edit) {
+            return edit.mode === "paint" ? paintSurface(edit) : editHeight(edit);
+        },
+        heightOffsetAt,
+        surfaceAt,
+        reset() {
+            offsets.fill(0);
+            surfaces.fill(null);
+        },
+        snapshot() {
+            return {
+                bounds: { ...bounds },
+                cellSize,
+                cols,
+                rows,
+                offsets: Array.from(offsets),
+                surfaces: surfaces.slice(),
+            };
+        },
+        restore(snapshot) {
+            const count = Math.min(offsets.length, snapshot.offsets.length);
+            for (let index = 0; index < count; index += 1)
+                offsets[index] = snapshot.offsets[index];
+            const surfaceCount = Math.min(surfaces.length, snapshot.surfaces.length);
+            for (let index = 0; index < surfaceCount; index += 1)
+                surfaces[index] = snapshot.surfaces[index] ?? null;
+        },
+    };
+    return field;
+}
+export function createTerraformBrush(terrain, config = {}) {
+    let radius = config.radius ?? 3;
+    let strength = config.strength ?? 0.5;
+    const falloff = config.falloff ?? "smooth";
+    const surface = config.surface;
+    return {
+        raise(center) {
+            return terrain.apply({ mode: "raise", center, radius, strength, falloff });
+        },
+        lower(center) {
+            return terrain.apply({ mode: "lower", center, radius, strength, falloff });
+        },
+        flatten(center, target) {
+            return terrain.apply({ mode: "flatten", center, radius, strength, falloff, ...(target === undefined ? {} : { target }) });
+        },
+        paint(center, paintSurface) {
+            const chosen = paintSurface ?? surface;
+            return terrain.apply({ mode: "paint", center, radius, ...(chosen === undefined ? {} : { surface: chosen }) });
+        },
+        setRadius(next) {
+            radius = next;
+        },
+        setStrength(next) {
+            strength = next;
+        },
+        config() {
+            return { radius, strength, falloff, surface };
+        },
+    };
+}

package/dist/world/walls.d.ts

@@ -0,0 +1,61 @@
+import { type Aabb, type Vec2 } from "./geometry.js";
+export type WallVec3 = readonly [number, number, number];
+export interface WallSegment {
+    from: Vec2;
+    to: Vec2;
+    length: number;
+    angle: number;
+}
+export interface EnclosedFootprint {
+    polygon: readonly Vec2[];
+    aabb: Aabb;
+    area: number;
+    perimeter: number;
+    closed: boolean;
+}
+export type RoofStyle = "hip" | "gable" | "flat";
+export interface RoofPlan {
+    style: RoofStyle;
+    ridge: readonly [Vec2, Vec2];
+    apexHeight: number;
+    eaveHeight: number;
+    faces: readonly (readonly WallVec3[])[];
+}
+export interface RoofConfig {
+    style?: RoofStyle;
+    eaveHeight?: number;
+    pitch?: number;
+    overhang?: number;
+}
+export declare function wallSegments(points: readonly Vec2[], closed: boolean): WallSegment[];
+export declare function isEnclosed(points: readonly Vec2[], tolerance?: number): boolean;
+export declare function enclosePath(points: readonly Vec2[], tolerance?: number): readonly Vec2[];
+export declare function polygonArea(polygon: readonly Vec2[]): number;
+export declare function footprintFromWalls(points: readonly Vec2[], tolerance?: number): EnclosedFootprint | null;
+export declare function autoRoof(footprint: EnclosedFootprint, config?: RoofConfig): RoofPlan;
+export type PaintTarget = "floor" | "wall";
+export interface SurfacePaintStore {
+    paint(target: PaintTarget, key: string, surface: string): void;
+    clear(target: PaintTarget, key: string): void;
+    get(target: PaintTarget, key: string): string | null;
+    entries(target: PaintTarget): readonly (readonly [string, string])[];
+    snapshot(): Record<PaintTarget, Record<string, string>>;
+    restore(snapshot: Record<PaintTarget, Record<string, string>>): void;
+}
+export declare function createSurfacePaint(): SurfacePaintStore;
+export interface WallDrawTool {
+    addPoint(point: Vec2, snap?: number): Vec2;
+    undo(): void;
+    close(): void;
+    clear(): void;
+    points(): readonly Vec2[];
+    segments(): WallSegment[];
+    isClosed(): boolean;
+    footprint(): EnclosedFootprint | null;
+    roof(config?: RoofConfig): RoofPlan | null;
+}
+export declare function createWallDrawTool(config?: {
+    snap?: number;
+    closeTolerance?: number;
+}): WallDrawTool;
+export declare function wallSegmentBounds(segment: WallSegment, thickness: number): Aabb;

package/dist/world/walls.js

@@ -0,0 +1,221 @@
+import { footprintAabb } from "./geometry.js";
+export function wallSegments(points, closed) {
+    const segments = [];
+    const count = closed ? points.length : points.length - 1;
+    for (let index = 0; index < count; index += 1) {
+        const from = points[index];
+        const to = points[(index + 1) % points.length];
+        const dx = to[0] - from[0];
+        const dz = to[1] - from[1];
+        segments.push({ from, to, length: Math.hypot(dx, dz), angle: Math.atan2(dz, dx) });
+    }
+    return segments;
+}
+export function isEnclosed(points, tolerance = 0.5) {
+    if (points.length < 3)
+        return false;
+    const first = points[0];
+    const last = points[points.length - 1];
+    return Math.hypot(first[0] - last[0], first[1] - last[1]) <= tolerance;
+}
+export function enclosePath(points, tolerance = 0.5) {
+    if (points.length < 3)
+        return points;
+    if (!isEnclosed(points, tolerance))
+        return points;
+    return points.slice(0, points.length - 1);
+}
+export function polygonArea(polygon) {
+    let sum = 0;
+    for (let index = 0; index < polygon.length; index += 1) {
+        const a = polygon[index];
+        const b = polygon[(index + 1) % polygon.length];
+        sum += a[0] * b[1] - b[0] * a[1];
+    }
+    return Math.abs(sum) / 2;
+}
+export function footprintFromWalls(points, tolerance = 0.5) {
+    const closed = isEnclosed(points, tolerance);
+    const polygon = enclosePath(points, tolerance);
+    if (polygon.length < 3)
+        return null;
+    let minX = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxZ = -Infinity;
+    let perimeter = 0;
+    for (let index = 0; index < polygon.length; index += 1) {
+        const point = polygon[index];
+        if (point[0] < minX)
+            minX = point[0];
+        if (point[0] > maxX)
+            maxX = point[0];
+        if (point[1] < minZ)
+            minZ = point[1];
+        if (point[1] > maxZ)
+            maxZ = point[1];
+        const next = polygon[(index + 1) % polygon.length];
+        perimeter += Math.hypot(next[0] - point[0], next[1] - point[1]);
+    }
+    return {
+        polygon,
+        aabb: { minX, minZ, maxX, maxZ },
+        area: polygonArea(polygon),
+        perimeter,
+        closed,
+    };
+}
+export function autoRoof(footprint, config = {}) {
+    const style = config.style ?? "hip";
+    const eaveHeight = config.eaveHeight ?? 3;
+    const pitch = config.pitch ?? 0.5;
+    const overhang = config.overhang ?? 0.4;
+    const aabb = footprint.aabb;
+    const minX = aabb.minX - overhang;
+    const maxX = aabb.maxX + overhang;
+    const minZ = aabb.minZ - overhang;
+    const maxZ = aabb.maxZ + overhang;
+    const width = maxX - minX;
+    const depth = maxZ - minZ;
+    const cx = (minX + maxX) / 2;
+    const cz = (minZ + maxZ) / 2;
+    const ridgeAlongX = width >= depth;
+    const halfSpan = (ridgeAlongX ? depth : width) / 2;
+    const apexHeight = style === "flat" ? eaveHeight : eaveHeight + halfSpan * pitch;
+    if (style === "flat") {
+        const face = [
+            [minX, eaveHeight, minZ],
+            [maxX, eaveHeight, minZ],
+            [maxX, eaveHeight, maxZ],
+            [minX, eaveHeight, maxZ],
+        ];
+        const flatRidge = [
+            [minX, cz],
+            [maxX, cz],
+        ];
+        return { style, ridge: flatRidge, apexHeight, eaveHeight, faces: [face] };
+    }
+    const ridge = ridgeAlongX
+        ? [
+            [minX + (style === "hip" ? halfSpan : 0), cz],
+            [maxX - (style === "hip" ? halfSpan : 0), cz],
+        ]
+        : [
+            [cx, minZ + (style === "hip" ? halfSpan : 0)],
+            [cx, maxZ - (style === "hip" ? halfSpan : 0)],
+        ];
+    const r0 = [ridge[0][0], apexHeight, ridge[0][1]];
+    const r1 = [ridge[1][0], apexHeight, ridge[1][1]];
+    const corners = {
+        nw: [minX, eaveHeight, minZ],
+        ne: [maxX, eaveHeight, minZ],
+        se: [maxX, eaveHeight, maxZ],
+        sw: [minX, eaveHeight, maxZ],
+    };
+    const faces = ridgeAlongX
+        ? [
+            [corners.nw, corners.ne, r1, r0],
+            [corners.se, corners.sw, r0, r1],
+        ]
+        : [
+            [corners.ne, corners.se, r1, r0],
+            [corners.sw, corners.nw, r0, r1],
+        ];
+    if (style === "hip") {
+        faces.push(ridgeAlongX
+            ? [corners.sw, corners.nw, r0]
+            : [corners.nw, corners.ne, r0]);
+        faces.push(ridgeAlongX
+            ? [corners.ne, corners.se, r1]
+            : [corners.se, corners.sw, r1]);
+    }
+    return { style, ridge, apexHeight, eaveHeight, faces };
+}
+export function createSurfacePaint() {
+    const maps = {
+        floor: new Map(),
+        wall: new Map(),
+    };
+    return {
+        paint(target, key, surface) {
+            maps[target].set(key, surface);
+        },
+        clear(target, key) {
+            maps[target].delete(key);
+        },
+        get(target, key) {
+            return maps[target].get(key) ?? null;
+        },
+        entries(target) {
+            return Array.from(maps[target].entries());
+        },
+        snapshot() {
+            return {
+                floor: Object.fromEntries(maps.floor),
+                wall: Object.fromEntries(maps.wall),
+            };
+        },
+        restore(snapshot) {
+            maps.floor = new Map(Object.entries(snapshot.floor ?? {}));
+            maps.wall = new Map(Object.entries(snapshot.wall ?? {}));
+        },
+    };
+}
+function snapPoint(point, grid) {
+    if (!(grid > 0))
+        return point;
+    return [Math.round(point[0] / grid) * grid, Math.round(point[1] / grid) * grid];
+}
+export function createWallDrawTool(config = {}) {
+    const defaultSnap = config.snap ?? 0;
+    const closeTolerance = config.closeTolerance ?? 0.5;
+    let pts = [];
+    let closed = false;
+    return {
+        addPoint(point, snap) {
+            const grid = snap ?? defaultSnap;
+            const next = snapPoint(point, grid);
+            if (pts.length >= 3 && Math.hypot(next[0] - pts[0][0], next[1] - pts[0][1]) <= closeTolerance) {
+                closed = true;
+                return pts[0];
+            }
+            pts.push(next);
+            return next;
+        },
+        undo() {
+            pts.pop();
+            closed = false;
+        },
+        close() {
+            if (pts.length >= 3)
+                closed = true;
+        },
+        clear() {
+            pts = [];
+            closed = false;
+        },
+        points() {
+            return pts;
+        },
+        segments() {
+            return wallSegments(pts, closed);
+        },
+        isClosed() {
+            return closed;
+        },
+        footprint() {
+            if (!closed && !isEnclosed(pts, closeTolerance))
+                return null;
+            return footprintFromWalls(pts, closeTolerance);
+        },
+        roof(roofConfig) {
+            const fp = this.footprint();
+            return fp === null ? null : autoRoof(fp, roofConfig);
+        },
+    };
+}
+export function wallSegmentBounds(segment, thickness) {
+    const center = [(segment.from[0] + segment.to[0]) / 2, (segment.from[1] + segment.to[1]) / 2];
+    const quarterTurns = Math.abs(Math.round(segment.angle / (Math.PI / 2))) % 2;
+    return footprintAabb(center, { w: segment.length, d: thickness }, quarterTurns);
+}

package/dist/world/weather.d.ts

@@ -0,0 +1,92 @@
+import type { WindVector } from "./wind.js";
+export type WeatherKind = string;
+export interface WeatherState {
+    /** Game-defined kind: "clear", "rain", "storm", "snow", "fog", "sandstorm". */
+    kind: WeatherKind;
+    /** 0..1 severity — scales every modifier. */
+    intensity: number;
+    wind?: WindVector;
+}
+/** Per-kind gameplay effect values at full intensity. Intensity interpolates from neutral. */
+export interface WeatherModifier {
+    /** Movement traction multiplier at full intensity — <1 = mud/ice slows, 1 = normal. */
+    grip?: number;
+    /** View distance multiplier at full intensity — 0..1, 1 = clear. */
+    visibility?: number;
+    /** Structure HP lost per game-second at full intensity (hail, storm). */
+    structureDamage?: number;
+    /** Temperature delta at full intensity (a blizzard chills). */
+    chill?: number;
+    /** Lightning ignition chance per game-second at full intensity. */
+    ignition?: number;
+    /** Fire spread-rate multiplier at full intensity — rain suppresses (<1). Default neutral 1. */
+    spread?: number;
+}
+export type WeatherModifierTable = Record<WeatherKind, WeatherModifier>;
+export interface ResolvedWeather {
+    grip: number;
+    visibility: number;
+    structureDamage: number;
+    chill: number;
+    ignition: number;
+    spread: number;
+}
+/**
+ * Resolve a weather state against a game-owned modifier table into concrete gameplay
+ * numbers. Multiplier-style effects (grip, visibility, spread) interpolate from the
+ * neutral 1 by intensity; rate-style effects (structureDamage, ignition, chill) scale
+ * linearly. Games read `grip`/`visibility` in movement and AI, `structureDamage` on a
+ * building tick, and `spread`/`ignition` feed the fire grid.
+ */
+export declare function resolveWeather(state: WeatherState, table: WeatherModifierTable): ResolvedWeather;
+export type FireCellState = "unburnt" | "burning" | "burnt";
+export interface FireCell {
+    fuel: number;
+    heat: number;
+    state: FireCellState;
+}
+export interface FireGridConfig {
+    cols: number;
+    rows: number;
+    cellSize: number;
+    /** World x,z of the center of cell (0,0). Default [0,0]. */
+    origin?: readonly [number, number];
+    /** Initial fuel 0..1 per cell; default 1 everywhere. */
+    fuelAt?: (col: number, row: number) => number;
+    /** Accumulated heat needed to ignite a fuelled cell. Default 1. */
+    ignitionThreshold?: number;
+    /** Heat pushed to each neighbour per second from a burning cell. Default 0.6. */
+    spreadRate?: number;
+    /** Fuel consumed per second while burning. Default 0.25. */
+    burnRate?: number;
+    /** Prevailing wind biasing spread direction. */
+    wind?: WindVector;
+    /** How strongly wind biases downwind vs upwind spread, 0..1. Default 0.6. */
+    windBias?: number;
+}
+export interface FireStepOptions {
+    /** Global spread multiplier this step (rain suppression from resolveWeather().spread). Default 1. */
+    spread?: number;
+    /** Per-cell wetness 0..1 that resists ignition — from an environment field. */
+    wetnessAt?: (col: number, row: number) => number;
+}
+export interface FireGrid {
+    readonly cols: number;
+    readonly rows: number;
+    /** Advance the cellular propagation by game-time `dt`. */
+    step(dt: number, options?: FireStepOptions): void;
+    igniteCell(col: number, row: number): void;
+    /** 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;
+    cellAt(x: number, z: number): FireCell | null;
+    cellCoord(x: number, z: number): {
+        col: number;
+        row: number;
+    } | null;
+    /** Count of currently burning cells. */
+    readonly burning: number;
+    /** Flat snapshot (row-major) for rendering. */
+    snapshot(): FireCell[];
+}
+export declare function createFireGrid(config: FireGridConfig): FireGrid;