# Falling Sand Game

> A falling-sand cellular automaton you paint with. Eight materials on a grid;
> simple per-cell rules produce piling, levelling, layering, burning and
> condensation. It runs entirely in the browser tab. There is no AI model
> behind it, nothing to meter, and no account is needed to use it.

Live at https://falling-sand-game.skillsafe.ai/

## What it is

A grid of cells — 400 x 225 by default, 90,000 of them — where every cell holds
one material and follows a short rule about where it would rather be. You paint
materials in with the mouse and watch the rules resolve. Nothing in the program
knows what a pile, a water level or a flame front is; those are consequences.

## The materials, and why these eight

Each one changes the behaviour of at least two others. That was the selection
rule; variety was not.

| Material | Moves | Density | Behaviour |
|---|---|---|---|
| Stone | never | — | The skeleton. Nothing burns it, nothing displaces it. |
| Sand | falls, then diagonally | 60 | Piles at its own angle of repose. Sinks through both liquids. |
| Water | falls, then runs flat | 30 | Finds its level. Puts fire out. Boils to steam doing it. |
| Oil | falls, then runs flat | 20 | Lighter than water, so it floats on it. Catches fire readily. |
| Wood | never | — | Fuel. Holds like stone until lit, then burns a long time. |
| Fire | clings to fuel, else rises | -10 | Spreads only to cells it touches. Dies in water. |
| Smoke | rises | -30 | What fire leaves. Thins to nothing. |
| Steam | rises, twice as fast | -20 | What boiled water leaves. Condenses back to water. |

## The rules, in full

There are only four ideas in the engine.

1. **Density decides every move.** A cell may move *down* into anything lighter
   and *up* into anything heavier. That single comparison is why sand sinks
   through water, why water sinks under oil (which is what puts the oil on
   top), and why smoke bubbles up through both. Nothing says "oil floats"
   anywhere in the code.

2. **Powders try down, then a diagonal.** Which diagonal is tried first is
   random, which is what makes a pile a symmetrical cone rather than a slope
   leaning one way. Liquids do the same and then run flat along a remembered
   flow direction, jumping to the furthest free cell within their dispersion
   rather than oozing one cell per frame — that is what makes a basin find its
   level in a few frames.

3. **Fire is the only material that reads its neighbours and rewrites them.**
   It spreads solely to cells it is directly touching, so a gap stops it and a
   water channel is a working firebreak. Water beside a flame very likely puts
   it out each frame — likely, not certainly, and that gap is deliberate: make
   it certain and fire and water can never be adjacent long enough for water to
   boil, which removes steam from the simulation entirely. Fire burning on fuel
   holds position and throws short-lived flames upward; fire in open air drifts
   up and burns out into smoke.

4. **A flame clings to fuel.** A free flame only drifts upward when it has
   nothing to burn. Without this rule a spark painted onto a log floats away
   before it can light it, and nothing in the box ever catches fire.

## How it is made fast

- Four typed arrays, one byte per cell each: material, per-material scratch
  (life for gases, flow direction for liquids), a fixed colour jitter, and the
  frame number at which the cell last moved.
- The grid is diced into 16x16 blocks. A block is stepped only if something
  changed in or beside it last frame, so a settled scene costs almost nothing
  and cost tracks the moving area rather than the grid area.
- Rows are swept bottom-up, because sweeping downward drains a whole column in
  one frame. The horizontal direction flips every frame, because sweeping the
  same way each time biases every diagonal slide and makes sand piles lean.
- A cell that already moved this frame is stamped with the frame number and
  skipped. A single parity bit is not enough — a long-settled cell then looks
  identical to one that just moved, and the grid freezes on alternate frames.
- Rendering is one pass over the material array into a Uint32 view of an
  ImageData buffer, then one putImageData. The canvas is one pixel per cell and
  CSS scales it up with `image-rendering: pixelated`.

Measured worst case, entire grid in free fall with every block awake: about
1.3 ms per frame at 400x225, against the 16.7 ms a 60fps frame allows. A
settled scene is far cheaper. Grid sizes offered: 240x135, 400x225, 560x315.

## Cost

Completely free. There is no model, so there is no run to bill, no credits, no
estimate and no top-up. The app holds the platform's "Completely free" label,
which is enforced rather than advisory: while it is held, the paid run endpoint
returns 403 for this app and data-API usage is not metered to users.

Signing in is optional and does exactly one thing: it lets you save named
scenes to your account so they follow you to another browser.

## Saved scenes

Scenes are stored in a declared collection called `scenes`, one record per
scene, readable and writable only by their owner. A scene is the material array
run-length encoded — `sb1;400x225;` followed by runs of one uppercase letter
(A-I for the eight materials plus empty) and a base-36 length. Life counters and
colour jitter are deliberately not stored: they are a frame of animation, not a
scene.

The `title`, `note` and `materials` fields are vector-embedded, so scenes are
searchable by meaning — "the one with the oil fire" finds it without the title
containing either word.

There is also an unnamed `workbench` key in the per-user store holding the box
as you last left it, so closing the tab is not destructive.

## Pages

- `/` — the app.
- `/api.html` — the data API: tokens, session, and the `scenes` collection.
  There is deliberately no run API documented, because this app has none.
- `/tokens.html` — inspect the token this browser holds. Not indexed.

## Bundled scenes

Four, each built so one interaction is unmissable, all free and requiring no
account:

- **Hourglass** — sand through a throat. Piling, sliding, angle of repose.
- **Oil and water** — oil poured underneath water, which then sorts itself out.
- **Forest fire** — nine trees and a water channel. The channel is the only
  reason the far stand survives.
- **Boiler** — fire under a grate holding water. It boils, the steam climbs to
  the lid, cools, and rains back into the pot.

## Not here

No AI model, no chat, no generation, no upload, no server. Nothing you paint
leaves the tab unless you deliberately save a scene to your account.