# 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

```sh
python3 build.py
python3 -m http.server -d dist     # then open http://localhost:8000
```

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:

```sh
pip install -r requirements.txt
python3 -m playwright install chromium
```

```sh
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.
- `NOTES.md`: the to-do list.
- `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.