sim_cellSimulation.js

/**
 * Neptune Environmental Simulation - Cell Grid Simulation System
 * SIM-02 implementation.
 */

import {
    MaterialRegistry,
    MaterialInteraction,
    MaterialState,
    InteractionType,
} from "./materialRegistry.js";

/**
 * Normalizes cell coordinates and data.
 * @param {string|object} data - Material ID or partial cell data.
 * @param {object} defaults - Default configuration values.
 * @returns {object} Normalized cell state object.
 */
function normalizeCellData(data, defaults) {
    if (typeof data === "string") {
        const materialId = data;
        const isWater = materialId === "water";
        return {
            materialId,
            state: isWater ? MaterialState.WET : MaterialState.DRY,
            moisture: isWater ? 1.0 : 0.0,
            burnTicks: 0,
            temperature: defaults.ambientTemperature,
            isSource: isWater,
            flowDistance: 0,
            originalMaterialId: null,
        };
    }

    const obj = (data && typeof data === "object") ? data : {};
    const materialId = typeof obj.materialId === "string" ? obj.materialId : defaults.defaultMaterial;
    const isWater = materialId === "water";

    let state = obj.state;
    if (!state) {
        state = isWater ? MaterialState.WET : MaterialState.DRY;
    }

    const moisture = Number.isFinite(obj.moisture)
        ? Number(obj.moisture)
        : (isWater || state === MaterialState.WET ? 1.0 : 0.0);

    const burnTicks = Number.isFinite(obj.burnTicks) ? Math.max(0, Number(obj.burnTicks)) : 0;

    let temperature = defaults.ambientTemperature;
    if (Number.isFinite(obj.temperature)) {
        temperature = Number(obj.temperature);
    } else if (state === MaterialState.BURNING) {
        temperature = defaults.burningTemperature;
    }

    const isSource = obj.isSource !== undefined ? Boolean(obj.isSource) : isWater;
    const flowDistance = Number.isFinite(obj.flowDistance) ? Math.max(0, Number(obj.flowDistance)) : 0;
    const originalMaterialId = obj.originalMaterialId ?? null;

    return {
        materialId,
        state,
        moisture,
        burnTicks,
        temperature,
        isSource,
        flowDistance,
        originalMaterialId,
    };
}

/**
 * 2D Grid Cellular Simulation for environmental interactions, fire spread,
 * heat conduction, extinguishing, and update-budgeted stepping.
 */
export class CellGridSimulation {
    /**
     * Creates a new CellGridSimulation instance.
     * @param {number|object} [widthOrOptions=16] - Grid width or options object.
     * @param {number} [height=16] - Grid height if first argument was width.
     * @param {object} [options={}] - Configuration options.
     */
    constructor(widthOrOptions = 16, height = 16, options = {}) {
        let opts = {};
        let w = 16;
        let h = 16;

        if (typeof widthOrOptions === "object" && widthOrOptions !== null) {
            opts = widthOrOptions;
            w = Number(opts.width) || 16;
            h = Number(opts.height) || 16;
        } else {
            w = Number(widthOrOptions) || 16;
            h = Number(height) || 16;
            opts = options || {};
        }

        this.width = Math.max(1, Math.floor(w));
        this.height = Math.max(1, Math.floor(h));

        this.registry = opts.registry || MaterialRegistry.getDefault();
        this.eventBus = opts.eventBus || null;

        this.maxCellUpdatesPerTick = Number.isFinite(opts.maxCellUpdatesPerTick)
            ? Math.max(1, Number(opts.maxCellUpdatesPerTick))
            : 10000;

        this.ambientTemperature = Number.isFinite(opts.ambientTemperature)
            ? Number(opts.ambientTemperature)
            : 20;

        this.burningTemperature = Number.isFinite(opts.burningTemperature)
            ? Number(opts.burningTemperature)
            : 100;

        this.heatTransferRate = Number.isFinite(opts.heatTransferRate)
            ? Number(opts.heatTransferRate)
            : 25;

        this.coolingRate = Number.isFinite(opts.coolingRate)
            ? Number(opts.coolingRate)
            : 5;

        this.dryingRate = Number.isFinite(opts.dryingRate)
            ? Number(opts.dryingRate)
            : 0.2;

        this.defaultMaterial = typeof opts.defaultMaterial === "string"
            ? opts.defaultMaterial
            : "dirt";

        this.waterFlow = opts.waterFlow !== undefined ? Boolean(opts.waterFlow) : true;
        this.maxWaterFlowDistance = Number.isFinite(opts.maxWaterFlowDistance)
            ? Math.max(0, Number(opts.maxWaterFlowDistance))
            : 3;

        this._updateCursor = 0;
        this._cells = new Array(this.width * this.height);

        this._initCells();
    }

    /**
     * Initializes all grid cells to default state.
     * @private
     */
    _initCells() {
        const defaults = {
            ambientTemperature: this.ambientTemperature,
            burningTemperature: this.burningTemperature,
            defaultMaterial: this.defaultMaterial,
        };

        for (let i = 0; i < this._cells.length; i++) {
            this._cells[i] = normalizeCellData(this.defaultMaterial, defaults);
        }
    }

    /**
     * Checks if coordinates are within the grid bounds.
     * Coordinates outside the grid boundary are safely identified.
     * @param {number} x - Column index.
     * @param {number} y - Row index.
     * @returns {boolean}
     */
    isInBounds(x, y) {
        return (
            typeof x === "number" &&
            typeof y === "number" &&
            Number.isInteger(x) &&
            Number.isInteger(y) &&
            x >= 0 &&
            x < this.width &&
            y >= 0 &&
            y < this.height
        );
    }

    /**
     * Gets 1D flat array index for (x, y) coordinates.
     * @param {number} x
     * @param {number} y
     * @returns {number} Index, or -1 if out of bounds.
     */
    getIndex(x, y) {
        if (!this.isInBounds(x, y)) return -1;
        return y * this.width + x;
    }

    /**
     * Converts a 1D flat array index to { x, y } coordinates.
     * @param {number} index
     * @returns {object} { x, y } coordinates.
     */
    getCoordinates(index) {
        return {
            x: index % this.width,
            y: Math.floor(index / this.width),
        };
    }

    /**
     * Queries a cell safely. Returns null if coordinates are out of bounds.
     * @param {number} x - Column index.
     * @param {number} y - Row index.
     * @returns {object|null} The cell object, or null if out of bounds.
     */
    getCell(x, y) {
        const idx = this.getIndex(x, y);
        if (idx === -1) return null;
        return this._cells[idx];
    }

    /**
     * Sets or updates cell data safely. Safely ignores out-of-bounds coordinates.
     * @param {number} x - Column index.
     * @param {number} y - Row index.
     * @param {string|object} data - Material ID or partial cell properties.
     * @returns {object|null} The updated cell object or null if out of bounds.
     */
    setCell(x, y, data) {
        const idx = this.getIndex(x, y);
        if (idx === -1) return null;

        const defaults = {
            ambientTemperature: this.ambientTemperature,
            burningTemperature: this.burningTemperature,
            defaultMaterial: this.defaultMaterial,
        };

        const existing = this._cells[idx];
        if (typeof data === "string") {
            this._cells[idx] = normalizeCellData(data, defaults);
        } else if (data && typeof data === "object") {
            const materialChanged = data.materialId !== undefined && data.materialId !== existing.materialId;
            const merged = { ...existing, ...data };
            if (materialChanged && data.moisture === undefined) {
                merged.moisture = data.materialId === "water" ? 1.0 : (data.state === MaterialState.WET ? 1.0 : 0.0);
            }
            if (materialChanged && data.isSource === undefined) {
                merged.isSource = data.materialId === "water";
            }
            if (data.state === MaterialState.DRY && data.moisture === undefined) {
                merged.moisture = 0.0;
            }
            this._cells[idx] = normalizeCellData(merged, defaults);
        }

        return this._cells[idx];
    }

    /**
     * Convenience helper to set material ID and optional state on a cell.
     * @param {number} x - Column index.
     * @param {number} y - Row index.
     * @param {string} materialId - Material ID.
     * @param {string} [state] - Material interaction state.
     * @returns {object|null}
     */
    setMaterial(x, y, materialId, state) {
        return this.setCell(x, y, { materialId, state });
    }

    /**
     * Queries the 4-cardinal in-bounds neighbors of a cell.
     * Out-of-bounds coordinates are filtered out safely.
     * @param {number} x
     * @param {number} y
     * @returns {Array<object>} Array of { x, y, index, cell }.
     */
    getNeighbors(x, y) {
        const cardinalOffsets = [
            { x: 0, y: -1 }, // North
            { x: 1, y: 0 },  // East
            { x: 0, y: 1 },  // South
            { x: -1, y: 0 }, // West
        ];

        const neighbors = [];
        for (let i = 0; i < cardinalOffsets.length; i++) {
            const nx = x + cardinalOffsets[i].x;
            const ny = y + cardinalOffsets[i].y;
            if (this.isInBounds(nx, ny)) {
                const idx = this.getIndex(nx, ny);
                neighbors.push({
                    x: nx,
                    y: ny,
                    index: idx,
                    cell: this._cells[idx],
                });
            }
        }
        return neighbors;
    }

    /**
     * Computes the effective ignition threshold temperature for a material.
     * Non-flammable materials (flammability === 0) return Infinity.
     * @param {string} materialId
     * @returns {number} Threshold temperature.
     */
    getIgnitionThreshold(materialId) {
        const mat = this.registry.get(materialId, { suppressWarning: true });
        if (!mat || mat.flammability <= 0) {
            return Infinity;
        }
        if (typeof mat.ignitionThreshold === "number") {
            return mat.ignitionThreshold;
        }
        // Base formula: higher flammability = lower threshold above ambient
        return this.ambientTemperature + (1.0 - mat.flammability) * 50;
    }

    /**
     * Manually ignites a cell at (x, y) if the material is flammable and not charred.
     * @param {number} x
     * @param {number} y
     * @returns {boolean} True if cell successfully ignited.
     */
    ignite(x, y) {
        const cell = this.getCell(x, y);
        if (!cell) return false;

        const mat = this.registry.get(cell.materialId);
        if (mat.flammability <= 0 || cell.state === MaterialState.CHARRED) {
            return false;
        }

        const prev = cell.state;
        cell.state = MaterialState.BURNING;
        cell.burnTicks = 0;
        cell.temperature = Math.max(cell.temperature, this.burningTemperature);
        cell.moisture = 0;

        this._emitEvent("sim:ignited", {
            x,
            y,
            materialId: cell.materialId,
            state: MaterialState.BURNING,
            previousState: prev,
            cell,
        });

        return true;
    }

    /**
     * Manually extinguishes a cell at (x, y).
     * @param {number} x
     * @param {number} y
     * @returns {boolean} True if cell was extinguished.
     */
    extinguish(x, y) {
        const cell = this.getCell(x, y);
        if (!cell) return false;

        const prev = cell.state;
        cell.state = MaterialState.EXTINGUISHED;
        cell.temperature = this.ambientTemperature;
        cell.moisture = Math.max(cell.moisture, 1.0);
        cell.burnTicks = 0;

        this._emitEvent("sim:extinguished", {
            x,
            y,
            materialId: cell.materialId,
            state: MaterialState.EXTINGUISHED,
            previousState: prev,
            cell,
        });

        return true;
    }

    /**
     * Emits a typed event to the TypedEventBus if one is attached.
     * Also emits an alias under `material:` namespace for compatibility.
     * @private
     * @param {string} eventName
     * @param {object} data
     */
    _emitEvent(eventName, data) {
        if (!this.eventBus || typeof this.eventBus.emit !== "function") return;

        this.eventBus.emit(eventName, data);

        if (eventName.startsWith("sim:")) {
            const alias = "material:" + eventName.slice(4);
            this.eventBus.emit(alias, data);
        }
    }

    /**
     * Advances the simulation by one step (dt).
     * Handles:
     * - Local fire spread & heat transfer to 4-cardinal neighbors.
     * - Burning progression and burnout transition to charred.
     * - Water flow & extinguishing (extinguishing takes precedence).
     * - Out-of-bounds boundary safety.
     * - Update budget capping via maxCellUpdatesPerTick.
     * - Typed event dispatching.
     *
     * @param {number} [dt=1] - Time step delta.
     * @param {object} [options={}] - Override step options.
     * @returns {object} Step summary statistics.
     */
    step(dt = 1, options = {}) {
        const totalCells = this._cells.length;
        const maxUpdates = options.maxCellUpdatesPerTick !== undefined
            ? Math.max(0, Number(options.maxCellUpdatesPerTick))
            : this.maxCellUpdatesPerTick;

        const limit = Math.min(maxUpdates, totalCells);
        if (limit === 0) {
            return {
                updatesProcessed: 0,
                ignitedCount: 0,
                extinguishedCount: 0,
                charredCount: 0,
                activeFires: 0,
            };
        }

        const heatTransferRate = Number.isFinite(options.heatTransferRate)
            ? Number(options.heatTransferRate)
            : this.heatTransferRate;

        const coolingRate = Number.isFinite(options.coolingRate)
            ? Number(options.coolingRate)
            : this.coolingRate;

        const dryingRate = Number.isFinite(options.dryingRate)
            ? Number(options.dryingRate)
            : this.dryingRate;

        // Snapshot prior cell states for read-isolation (prevents iteration order bias)
        const prevCells = new Array(totalCells);
        for (let i = 0; i < totalCells; i++) {
            const c = this._cells[i];
            prevCells[i] = {
                materialId: c.materialId,
                state: c.state,
                moisture: c.moisture,
                burnTicks: c.burnTicks,
                temperature: c.temperature,
                isSource: c.isSource,
                flowDistance: c.flowDistance,
                originalMaterialId: c.originalMaterialId,
            };
        }

        let ignitedCount = 0;
        let extinguishedCount = 0;
        let charredCount = 0;
        let updatesProcessed = 0;

        // Process up to `limit` cells starting from `_updateCursor` for bounded computation
        for (let stepCount = 0; stepCount < limit; stepCount++) {
            const idx = (this._updateCursor + stepCount) % totalCells;
            updatesProcessed++;

            const { x, y } = this.getCoordinates(idx);
            const prev = prevCells[idx];
            const curr = this._cells[idx];
            const mat = this.registry.get(prev.materialId, { suppressWarning: true });

            // Inspect 4-cardinal neighbors from prevCells
            const neighbors = this.getNeighbors(x, y);
            const burningNeighbors = [];
            const waterNeighbors = [];

            for (let n = 0; n < neighbors.length; n++) {
                const nIdx = neighbors[n].index;
                const nPrev = prevCells[nIdx];
                const nMat = this.registry.get(nPrev.materialId, { suppressWarning: true });

                if (nPrev.state === MaterialState.BURNING) {
                    burningNeighbors.push(nPrev);
                }

                // A cell acts as water if it is water material
                if (nMat.id === "water" || nPrev.materialId === "water") {
                    waterNeighbors.push(nPrev);
                }
            }

            const hasWaterNeighbor = waterNeighbors.length > 0;
            const hasBurningNeighbor = burningNeighbors.length > 0;

            // =================================================================
            // 1. BURNING CELL PROCESSING
            // =================================================================
            if (prev.state === MaterialState.BURNING) {
                // Extinguishing takes precedence over burning
                if (hasWaterNeighbor) {
                    curr.state = MaterialState.EXTINGUISHED;
                    curr.temperature = this.ambientTemperature;
                    curr.moisture = 1.0;
                    curr.burnTicks = 0;
                    extinguishedCount++;

                    this._emitEvent("sim:extinguished", {
                        x,
                        y,
                        materialId: curr.materialId,
                        state: MaterialState.EXTINGUISHED,
                        previousState: MaterialState.BURNING,
                        cell: curr,
                    });
                } else {
                    // Cell continues burning for burnDuration ticks then chars
                    const newBurnTicks = prev.burnTicks + 1;
                    curr.burnTicks = newBurnTicks;
                    curr.temperature = Math.max(prev.temperature, this.burningTemperature);

                    if (newBurnTicks >= (mat.burnDuration || 0)) {
                        curr.state = MaterialState.CHARRED;
                        curr.temperature = Math.max(this.ambientTemperature, prev.temperature - coolingRate);
                        charredCount++;

                        this._emitEvent("sim:charred", {
                            x,
                            y,
                            materialId: curr.materialId,
                            state: MaterialState.CHARRED,
                            previousState: MaterialState.BURNING,
                            cell: curr,
                        });
                    }
                }
                continue;
            }

            // =================================================================
            // 2. CHARRED CELL PROCESSING (Cannot re-ignite)
            // =================================================================
            if (prev.state === MaterialState.CHARRED) {
                if (hasWaterNeighbor) {
                    curr.moisture = 1.0;
                    curr.temperature = this.ambientTemperature;
                } else if (curr.temperature > this.ambientTemperature) {
                    curr.temperature = Math.max(this.ambientTemperature, curr.temperature - coolingRate);
                }
                continue;
            }

            // =================================================================
            // 3. WATER MATERIAL PROCESSING
            // =================================================================
            if (prev.materialId === "water") {
                curr.state = MaterialState.WET;
                curr.moisture = 1.0;
                curr.temperature = this.ambientTemperature;
                curr.burnTicks = 0;

                // Handle removed source: non-source flowing water dissipates if no upstream source
                if (!prev.isSource) {
                    const hasUpstream = waterNeighbors.some(
                        (wn) => wn.materialId === "water" && wn.flowDistance < prev.flowDistance
                    );
                    if (!hasUpstream) {
                        curr.materialId = prev.originalMaterialId || this.defaultMaterial;
                        curr.state = MaterialState.WET;
                        curr.flowDistance = 0;
                    }
                }
                continue;
            }

            // =================================================================
            // 4. CONFLICTING INTERACTIONS (Extinguishing takes precedence)
            // =================================================================
            if (hasBurningNeighbor && hasWaterNeighbor) {
                // Extinguishing suppresses ignition completely
                curr.state = MaterialState.WET;
                curr.moisture = 1.0;
                curr.temperature = this.ambientTemperature;
                curr.burnTicks = 0;
                continue;
            }

            // =================================================================
            // 5. WATER FLOW & EXTINQUISHING (Adjacent water cell)
            // =================================================================
            if (hasWaterNeighbor) {
                // If cell was wet or dry, moisture is refreshed and fire cannot ignite
                if (curr.state === MaterialState.DRY) {
                    curr.state = MaterialState.WET;
                }
                curr.moisture = 1.0;
                curr.temperature = this.ambientTemperature;
                continue;
            }

            // =================================================================
            // 6. LOCAL FIRE SPREAD & HEAT CONDUCTION (Adjacent burning cells)
            // =================================================================
            if (hasBurningNeighbor) {
                const heatReceived = burningNeighbors.length * heatTransferRate;
                const newTemp = prev.temperature + heatReceived;
                curr.temperature = newTemp;

                const threshold = this.getIgnitionThreshold(curr.materialId);

                // Flammable cell ignites when threshold is met
                if (mat.flammability > 0 && newTemp >= threshold) {
                    const interactionIntensity = (newTemp - this.ambientTemperature) / 25;
                    const result = MaterialInteraction.applyInteraction({
                        state: prev.state,
                        interaction: InteractionType.IGNITE,
                        materialId: curr.materialId,
                        intensity: interactionIntensity,
                        moistureThreshold: prev.moisture || 1.0,
                        registry: this.registry,
                    });

                    if (result.state === MaterialState.BURNING) {
                        curr.state = MaterialState.BURNING;
                        curr.temperature = Math.max(newTemp, this.burningTemperature);
                        curr.burnTicks = 0;
                        curr.moisture = 0;
                        ignitedCount++;

                        this._emitEvent("sim:ignited", {
                            x,
                            y,
                            materialId: curr.materialId,
                            state: MaterialState.BURNING,
                            previousState: prev.state,
                            cell: curr,
                        });
                    }
                }
                continue;
            }

            // =================================================================
            // 7. AMBIENT COOLING & DRYING (No fire or water neighbors)
            // =================================================================
            if (curr.temperature > this.ambientTemperature) {
                curr.temperature = Math.max(this.ambientTemperature, curr.temperature - coolingRate);
            }

            // Wet or extinguished ground gradually dries if water source is absent
            if (curr.state === MaterialState.WET || curr.state === MaterialState.EXTINGUISHED) {
                const newMoisture = Math.max(0, prev.moisture - dryingRate);
                curr.moisture = newMoisture;
                if (newMoisture <= 0) {
                    curr.state = MaterialState.DRY;
                }
            }
        }

        // Advance update cursor for bounded round-robin execution
        this._updateCursor = (this._updateCursor + limit) % totalCells;

        let activeFires = 0;
        for (let i = 0; i < totalCells; i++) {
            if (this._cells[i].state === MaterialState.BURNING) {
                activeFires++;
            }
        }

        return {
            updatesProcessed,
            ignitedCount,
            extinguishedCount,
            charredCount,
            activeFires,
        };
    }

    /**
     * Resets all cells to default material and temperature.
     */
    clear() {
        this._updateCursor = 0;
        this._initCells();
    }

    /**
     * Serializes the cell grid state for save games.
     * @returns {object} Serializable snapshot object.
     */
    snapshot() {
        const cells = new Array(this._cells.length);
        for (let i = 0; i < this._cells.length; i++) {
            const c = this._cells[i];
            cells[i] = {
                materialId: c.materialId,
                state: c.state,
                moisture: c.moisture,
                burnTicks: c.burnTicks,
                temperature: c.temperature,
                isSource: c.isSource,
                flowDistance: c.flowDistance,
                originalMaterialId: c.originalMaterialId,
            };
        }

        return {
            version: 1,
            timestamp: Date.now(),
            width: this.width,
            height: this.height,
            updateCursor: this._updateCursor,
            ambientTemperature: this.ambientTemperature,
            burningTemperature: this.burningTemperature,
            defaultMaterial: this.defaultMaterial,
            cells,
        };
    }

    /**
     * Restores cell grid state from a snapshot.
     * @param {object} snapshot - Saved snapshot object.
     * @returns {CellGridSimulation} this instance.
     */
    restore(snapshot) {
        if (!snapshot || typeof snapshot !== "object") {
            throw new TypeError("Snapshot must be an object");
        }

        if (Number.isFinite(snapshot.width) && Number.isFinite(snapshot.height)) {
            this.width = Math.max(1, Math.floor(snapshot.width));
            this.height = Math.max(1, Math.floor(snapshot.height));
        }

        if (!Array.isArray(snapshot.cells)) {
            throw new TypeError("Snapshot must contain a cells array");
        }

        if (Number.isFinite(snapshot.updateCursor)) {
            this._updateCursor = snapshot.updateCursor % (this.width * this.height);
        } else {
            this._updateCursor = 0;
        }

        if (Number.isFinite(snapshot.ambientTemperature)) {
            this.ambientTemperature = snapshot.ambientTemperature;
        }
        if (Number.isFinite(snapshot.burningTemperature)) {
            this.burningTemperature = snapshot.burningTemperature;
        }
        if (typeof snapshot.defaultMaterial === "string") {
            this.defaultMaterial = snapshot.defaultMaterial;
        }

        const defaults = {
            ambientTemperature: this.ambientTemperature,
            burningTemperature: this.burningTemperature,
            defaultMaterial: this.defaultMaterial,
        };

        const total = this.width * this.height;
        this._cells = new Array(total);

        for (let i = 0; i < total; i++) {
            const raw = snapshot.cells[i] || {};
            this._cells[i] = normalizeCellData(raw, defaults);
        }

        return this;
    }

    /**
     * Counts the number of cells matching a predicate function.
     * @param {Function} predicate - (cell, x, y) => boolean.
     * @returns {number}
     */
    countCells(predicate) {
        if (typeof predicate !== "function") return 0;
        let count = 0;
        for (let i = 0; i < this._cells.length; i++) {
            const { x, y } = this.getCoordinates(i);
            if (predicate(this._cells[i], x, y)) {
                count++;
            }
        }
        return count;
    }

    /**
     * Finds coordinates of all cells matching a predicate function.
     * @param {Function} predicate - (cell, x, y) => boolean.
     * @returns {Array<object>} Array of { x, y, cell }.
     */
    findCells(predicate) {
        if (typeof predicate !== "function") return [];
        const matches = [];
        for (let i = 0; i < this._cells.length; i++) {
            const { x, y } = this.getCoordinates(i);
            if (predicate(this._cells[i], x, y)) {
                matches.push({ x, y, cell: this._cells[i] });
            }
        }
        return matches;
    }
}

export default CellGridSimulation;