# Deepgrain Foundry

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

WebGPU is required (Chrome or Edge with a supported graphics adapter). Both looks use WebGPU;
there is no fallback renderer. Browsers without an adapter, including Firefox on Linux in our
checks, show a notice on the start screen. Serve the page over HTTP as described below.

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 conveyors, filters, fans, pipes and
machines, until the land claim is paid off and beyond.

## Play

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

The game requires WebGPU and cross-origin isolation for shared-memory CPU workers.
Grains and heat run across up to 16 helpers (two CPU cores are reserved); Settings →
Simulation → CPU workers caps the pool on the next world load. Small jobs run inline.

The game must be served: use `python3 tools/serve.py` locally, or serve `dist/` with any web
server that sends these headers. Opening `dist/index.html` from disk is no longer supported.
Use HTTPS when hosting remotely (localhost works over HTTP).

nginx, in the site's `server` or `location` block:

```nginx
add_header Cross-Origin-Opener-Policy same-origin always;
add_header Cross-Origin-Embedder-Policy require-corp always;
```

Caddy, in the site block alongside `root * /path/to/dist` and `file_server`:

```caddyfile
header {
    Cross-Origin-Opener-Policy same-origin
    Cross-Origin-Embedder-Policy require-corp
}
```

These are plain static files, so a small server is enough. The game is one self-contained page
with no downloads; sound and graphics are 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.
The golden-image tests also use ImageMagick (`magick`):

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

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

```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

- `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.