coorl-lost-cities/web/README.md

COOLRL Lost Cities Web

Browser-only Lost Cities client. The rules engine, observation builder, and PPO inference all run on the device. There is no application server.

Setup

From the repository root, export an Orbax checkpoint to the browser model:

uv run --with onnx scripts/export_jax_ppo_onnx.py \
  --checkpoint /path/to/checkpoint \
  --output web/public/models/jax-ppo.onnx

Then install and run the web app:

cd web
npm install
npm run dev

The policy tries WebGPU first and falls back to ONNX Runtime WebAssembly. If the model asset is absent, the UI remains playable using a simple local heuristic and reports that fallback in the header.

Checks

cd web
npm test
npm run build

The TypeScript engine follows src/lost_cities_jax/engine.py and its 96-action atomic action space. Cross-runtime fixtures can be regenerated with:

uv run python scripts/generate_web_parity_fixture.py