98 lines
3.8 KiB
Markdown
98 lines
3.8 KiB
Markdown
# 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.
|