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

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

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:

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