# CascadeCore — the model The simulation, and nothing else. This module owns no engine API: it is pure Luau over flat arrays, so the same code steps headless (baseline strategies, batch experiments) at the speed it steps on screen. ## Shape ```lua local Core = require("CascadeCore") local sim = Core.new({ width = 256, height = 256, seed = 42, params = {} }) for _ = 1, 1000 do Core.step(sim) Core.afterTick(sim, 1 / 25) end print(Core.summary(sim).efficiency) ``` `Core.step` advances the model by one tick. `Core.afterTick` does the bookkeeping a driver wants at its own cadence — production accrual, connectivity, pressure, history samples — and takes the wall-clock seconds since the last call. A caller that only wants the physics can skip it. ## Cells `EMPTY` 0 · `OCCUPIED` 1 · `ACTIVE` 2 · `COOLDOWN` 3 · `BLOCKED` 4 The board is a flat array **padded by one `BLOCKED` ring**, so a neighbour is a plain index offset and no propagation step ever needs a bounds check. `Core.idx(sim, x, y)` maps board coordinates to that index. ## Propagating the grid `neighbor_mode` (4 or 8) fixes the neighbourhood. `propagation_mode` picks how fire crosses it: 1. **adjacency** — every occupied neighbour ignites 2. **probabilistic** — each at `spread_probability` 3. **distance** — within `spread_radius`, probability falling with distance 4. **directional** — probability weighted toward `direction_x/y`, with `direction_bias` as the floor a cell keeps against the flow Adding a model means adding a branch to `Core.rebuildNeighbors`, which fills each offset's probability once per parameter change rather than per tick. ## Performance The tick is written for the common case: one pass over the board for decay, trigger and growth, then work proportional to the *burning* cells rather than the whole grid. Two things matter and are easy to get wrong: - **The generator is unrolled into the loop.** A tick draws a number for most cells on the board, and at this VM's call costs a `bit32`-based xorshift made the simulation three times slower than the arithmetic it was producing. See `CascadeRng`. - **Thresholds are integers.** A probability is stored pre-multiplied by the generator's modulus, so the hot comparison never pays for a float divide. Measured: ~5.4 ms per tick at 256×256 on a sparse board, ~7.3 ms at the density the model settles at. ## `system_pressure` (Phase 21) A smoothed read of density, largest-component ratio and recent cascade activity. **It is observational only.** Nothing in this module reads it to decide an outcome — catastrophic events remain emergent consequences of the cellular system, and there is no branch anywhere that spawns one.