init

2026-09-19 20:21:47 +02:00
commit 0798933b05
62 changed files with 7658 additions and 0 deletions
@@ -0,0 +1,65 @@
+# Halcyon belt
+
+A once-a-day asteroid-belt simulator. Players cannot fly their ships: they write a
+program for the ship's flight computer, launch it, and then exchange 1 KB a day with
+it over a "wormhole" link. The belt is simulated once a day, deterministically.
+
+- `docs/manual.txt` -- the HC-33 flight computer programmer's manual (also served at `/manual.txt`)
+- `examples/programs/` -- sample ship programs (assembly)
+
+## Run it
+
+```sh
+go run ./cmd/server -db sqlite:wh.db            # API + website on :8080
+go run ./cmd/daily  -db sqlite:wh.db            # simulate one day (run once a day, e.g. from cron)
+```
+
+`-db` is `sqlite:<path>` or a `postgres://` URL. The world parameters (`-seed`,
+`-ticks-per-day`, `-asteroids`, ...) or their `WH_*` variables must be the same for `server` and
+`daily`, and cannot be changed for an existing database.
+
+Open <http://localhost:8080/>, create an account (you are shown an access key once;
+it is your login), write a program, seal it into your ship, launch it, then run `daily`.
+
+## Docker
+
+```sh
+docker build -t halcyon .
+docker run -d -p 8080:8080 -v whdata:/data halcyon                       # SQLite on a volume
+docker run --rm -v whdata:/data halcyon daily                            # simulate one day
+docker run -d -p 8080:8080 -e DATABASE_URL=postgres://user:pw@db/wh halcyon   # or Postgres
+docker build --target test .                                             # run the tests
+```
+
+With Compose, Caddy serves the site over HTTPS at `sandbox.clearsky.dev` (edit `caddy/Caddyfile`
+for another name; DNS must point at the host and ports 80/443 must be open). The app itself is
+also on <http://localhost:8070>, bound to localhost only. SQLite lives in the `halcyon-data` volume:
+
+```sh
+docker compose up -d --build
+scripts/daily.sh          # one simulated day via `docker exec`; schedule it once a day
+```
+
+The world settings are environment variables (`WH_SEED`, `WH_TICKS_PER_DAY`, `WH_CYCLES_PER_TICK`,
+`WH_PROGRAM_BYTES`, `WH_RAM_BYTES`, `WH_COMM_BYTES`, `WH_ASTEROIDS`); flags of the same name override
+them. In Compose they are set once on the `web` service, so `scripts/daily.sh` always matches the
+server. Change them only before a world has run.
+
+`DATABASE_URL` sets the database for both `server` and `daily` (default in the image:
+`sqlite:/data/wh.db`); the `-db` flag overrides it. The image also contains `asm`.
+
+## Layout
+
+| path | what |
+|---|---|
+| `fixed`, `rng` | deterministic Q32.32 maths and PRNG |
+| `vm` | the ship CPU and its assembler (`cmd/asm`) |
+| `world`, `sim`, `market` | belt generation, the daily simulation, ore prices |
+| `store`, `runner` | SQLite/Postgres persistence and the daily run |
+| `api`, `web`, `cmd/server` | HTTP API and the browser front end |
+| `examples`, `docs` | embedded sample programs and manual |
+
+## Tests
+
+`go test ./...` covers everything; set `WH_TEST_PG=postgres://...` to also run the API
+test against PostgreSQL (it wipes that database's `public` schema).