Cascade — a self-organising system you have to keep safe
README.md
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
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:
- adjacency — every occupied neighbour ignites
- probabilistic — each at
spread_probability - distance — within
spread_radius, probability falling with distance - directional — probability weighted toward
direction_x/y, withdirection_biasas 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. SeeCascadeRng. - 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.