Log inGet started
World

Cascade — a self-organising system you have to keep safe

Branchmain
Branchesmain
Commit1e11026548

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:

  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.