Deepgrain Foundry

A falling-sand factory game in the browser, in the style of Sandustry.

Every grain of sand, ore, water and fire is simulated. You fly a small bot over a side-view world, dig with a resonance drill and vacuum up what breaks loose. You build furnaces from blocks, melt ore with coal and air, and cast the metal in molds. Then you sell bars, alloys and other goods at a trade dock, automating with belts, screw tubes, filters, fans, pipes and machines, until the land claim is paid off and beyond.

Play

python3 build.py
python3 tools/serve.py            # builds, serves at http://localhost:8000 and rebuilds when src/ changes

Opening dist/index.html directly works too. The game is one self-contained page with no downloads; sound and graphics are all generated in code. Saves stay in your browser.

• To keep or move a world, use Pause → Export world file.
• To load one, use Settings → Load a world file on the title screen, or Pause → Import world file during a game. World files exported from the claude.ai version load here too.

The controls are in the in-game notebook (N) under Controls. The basics:

• WASD to fly;
• 1–4 for the drill, vacuum, build and igniter;
• left and right mouse to use the tool;
• Q/E and R to change what it does;
• F to use things;
• Esc for the menu.

Develop

You need Node (tested with 22), Python 3, and Playwright for the browser tests and screenshots:

uv venv .venv
uv pip install --python .venv/bin/python -r requirements.txt
.venv/bin/python -m playwright install chromium

If uv is not installed, python3 -m venv .venv and .venv/bin/pip install -r requirements.txt also work; then install Chromium as above. After that, plain python3 works for every command below; the browser scripts switch to .venv on their own.

python3 build.py                     # build dist/index.html
python3 test/run_all.py              # headless test suites
python3 test/run_all.py --browser    # plus the browser tests
python3 tools/shot.py shots/x.png --setup tools/scenes/clear-sky.js   # a screenshot

The source is small JavaScript files with no dependencies or bundler:

• src/sim/: the simulation;
• src/render/: drawing;
• src/ui/: the browser shell.

build.py joins them in the order given in src/manifest.json.

Documents

• AGENTS.md / CLAUDE.md: how coding agents work on this project.
• tasks/: the to-do list, a kandown board (kandown opens it; see docs/kandown.md).
• docs/PROJECT_MAP.md: where everything is.
• docs/DESIGN.md: what the game is meant to be, and the decisions made.
• docs/TESTING.md: tests, screenshots and pitfalls.
• docs/systems/: notes on individual systems.
• docs/history/requests.md: the owner's requests while the game was built.
• docs/agent-log.md: the work log.