# Falling sand ## What this builds A grid of cells. Each cell is empty or one of a small set of elements: sand, water, fire, plant, fuse, and ash. They fall, flow, burn and grow by local rules. A person paints with a brush and can save a scene. The rules are original and fully listed. Tests run on tiny grids and on one known scene that must hash to a golden frame after a stated number of ticks. Read `spekkr.inputs.json` first. `width` and `height` size the grid. `wind` and `seed` add a sideways bias. `wrap` is for the sides. `palette` changes colours, not rules. ## Out of scope - A live community gallery in the checks. - Network, accounts, or a room where strangers' scenes appear. - Elements beyond the six named here, in this version. ## Requirements Each requirement has an id. Checks name the id they cover. ### R1. The grid - A cell is one of `empty`, `sand`, `water`, `fire`, `plant`, `fuse`, `ash`. - A tick updates every cell from the previous grid, in the order and with the rules in `design.md`. - The same grid and the same seed produce the same next grid. Accept when: two ticks of a 4 by 4 fixture match the documented next grids bit-identically. ### R2. Element rules - Sand falls down, or down-left or down-right if down is solid, preferring left when `wind` is off. - Water falls like sand, and also slides left or right on a floor. - Fire consumes fuse in a von Neumann neighbour and becomes ash after 3 ticks. Plant next to water may grow into an empty neighbour, at most one cell per 8 ticks. - Ash is solid and does not fall. Accept when: the tiny-grid cases in `design.md` all hold: water flows down, fire consumes fuse, sand piles, plant grows. ### R3. A known scene - `fixtures/scene-fountain.bin` is a 128 by 128 scene. After 240 ticks with `wind` off, a PNG of the grid hashed with the palette `studio` matches the golden `water-flow` frame, and a cell-count checksum matches the figure in `design.md`. Accept when: the checksum matches, and the frame is within the screenshot tolerance. ### R4. Painting and files - A brush paints the chosen element in a 1, 3 or 5 cell radius. Painting is the only input besides play/pause and a reset. - One command runs the tiny-grid tests, the known scene, and writes the four screenshots. No network. Accept when: the command passes at 32 by 32 and at the default size, with wind on and off. ### R5. Inputs - The build reads `spekkr.inputs.json`. Settings label the UI, options turn features on or off, and a swap must be one of its choices. - A value outside a stated range, or a swap that is not one of its choices, is refused before the app starts its checks, with a message that names the key. Accept when: the default inputs render, an illegal swap is refused by name, and changing a visible setting (for example the title) shows up in a later check. ## Verification Cellular tests on tiny grids assert that water flows down, fire consumes fuse, sand piles, and plant grows, exactly as the case file says. A known 128 by 128 scene is ticked 240 times and must match a checksum and a golden frame. No network and no live gallery. ## Definition of done - Every acceptance check above runs from one command, and all pass at the person's inputs. - A README says how to paint, how to run the checks, and how to add an element later.