CellGridSimulation

2D Grid Cellular Simulation for environmental interactions, fire spread, heat conduction, extinguishing, and update-budgeted stepping.

Constructor

new CellGridSimulation(widthOrOptionsopt, heightopt, optionsopt)

Creates a new CellGridSimulation instance.

Parameters:
NameTypeAttributesDefaultDescription
widthOrOptionsnumber | object<optional>
16

Grid width or options object.

heightnumber<optional>
16

Grid height if first argument was width.

optionsobject<optional>
{}

Configuration options.

Classes

CellGridSimulation

Methods

clear()

Resets all cells to default material and temperature.

countCells(predicate) → {number}

Counts the number of cells matching a predicate function.

Parameters:
NameTypeDescription
predicatefunction

(cell, x, y) => boolean.

Returns:
Type: 
number

extinguish(x, y) → {boolean}

Manually extinguishes a cell at (x, y).

Parameters:
NameTypeDescription
xnumber
ynumber
Returns:

True if cell was extinguished.

Type: 
boolean

findCells(predicate) → {Array.<object>}

Finds coordinates of all cells matching a predicate function.

Parameters:
NameTypeDescription
predicatefunction

(cell, x, y) => boolean.

Returns:

Array of { x, y, cell }.

Type: 
Array.<object>

getCell(x, y) → {object|null}

Queries a cell safely. Returns null if coordinates are out of bounds.

Parameters:
NameTypeDescription
xnumber

Column index.

ynumber

Row index.

Returns:

The cell object, or null if out of bounds.

Type: 
object | null

getCoordinates(index) → {object}

Converts a 1D flat array index to { x, y } coordinates.

Parameters:
NameTypeDescription
indexnumber
Returns:

{ x, y } coordinates.

Type: 
object

getIgnitionThreshold(materialId) → {number}

Computes the effective ignition threshold temperature for a material. Non-flammable materials (flammability === 0) return Infinity.

Parameters:
NameTypeDescription
materialIdstring
Returns:

Threshold temperature.

Type: 
number

getIndex(x, y) → {number}

Gets 1D flat array index for (x, y) coordinates.

Parameters:
NameTypeDescription
xnumber
ynumber
Returns:

Index, or -1 if out of bounds.

Type: 
number

getNeighbors(x, y) → {Array.<object>}

Queries the 4-cardinal in-bounds neighbors of a cell. Out-of-bounds coordinates are filtered out safely.

Parameters:
NameTypeDescription
xnumber
ynumber
Returns:

Array of { x, y, index, cell }.

Type: 
Array.<object>

ignite(x, y) → {boolean}

Manually ignites a cell at (x, y) if the material is flammable and not charred.

Parameters:
NameTypeDescription
xnumber
ynumber
Returns:

True if cell successfully ignited.

Type: 
boolean

isInBounds(x, y) → {boolean}

Checks if coordinates are within the grid bounds. Coordinates outside the grid boundary are safely identified.

Parameters:
NameTypeDescription
xnumber

Column index.

ynumber

Row index.

Returns:
Type: 
boolean

restore(snapshot) → {CellGridSimulation}

Restores cell grid state from a snapshot.

Parameters:
NameTypeDescription
snapshotobject

Saved snapshot object.

Returns:

this instance.

Type: 
CellGridSimulation

setCell(x, y, data) → {object|null}

Sets or updates cell data safely. Safely ignores out-of-bounds coordinates.

Parameters:
NameTypeDescription
xnumber

Column index.

ynumber

Row index.

datastring | object

Material ID or partial cell properties.

Returns:

The updated cell object or null if out of bounds.

Type: 
object | null

setMaterial(x, y, materialId, stateopt) → {object|null}

Convenience helper to set material ID and optional state on a cell.

Parameters:
NameTypeAttributesDescription
xnumber

Column index.

ynumber

Row index.

materialIdstring

Material ID.

statestring<optional>

Material interaction state.

Returns:
Type: 
object | null

snapshot() → {object}

Serializes the cell grid state for save games.

Returns:

Serializable snapshot object.

Type: 
object

step(dtopt, optionsopt) → {object}

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.
Parameters:
NameTypeAttributesDefaultDescription
dtnumber<optional>
1

Time step delta.

optionsobject<optional>
{}

Override step options.

Returns:

Step summary statistics.

Type: 
object