Files
README.md

Cavu Games #

Small games that play nicely with your Atmosphere account. Ludos liberi.

A Lua game runtime run isomorphically on the server and in a Rust→wasm browser client, the play.cavu.games game fleet, the cavu.games host (catalog, sign-in, launch, delegated record writes) and first-party games in games/. The plan and design notes are in PLAN.md; work is tracked with beads (bd ready).

./build.sh                      # wasm client -> web/pkg, server binary
./target/release/cavu-server    # http://127.0.0.1:8788/?game=haiku-day   (&debug for stats)
crate role
cavu-world the entity engine: worlds of entities held natively, routing, transactions, schedules, projection, the client's mirror and prediction; lua/glue.lua calls the classes.
cavu-lua luars VM + deterministic math (pure-Rust libm), pack-scoped require, Lua <-> IPLD. lua/shared.lua (both sides), lua/server.lua (server bridge), lua/client.lua (UI stdlib + client bridge).
cavu-server axum: /packs/{id}/client.json (client modules only), websocket games.cavu.subscribeSession, one game thread owning every room's VM.
cavu-client wasm: UI kit (taffy, behaviors, skin cache, WebGL2, hidden DOM) + session socket.

Game contract: an entity world (see games/haiku-day, games/rpg-actor-in-space, games/entity-demo; the engine is crates/cavu-world, native, and runs only the classes' Lua).

  • Entities: the world is a tree of entities, each plain data (id, kind, parent, children, fields) whose kind is a Lua table: init, on.<msg> (trusted messages: ctx.send, scheduled ctx.at, effect results), intent.<msg> (player intents, to = an entity id), predict (intents the client re-runs to predict), project(self, viewer) (fields starting with _ stay on the server), and on the client view, synced(new, old) and frame. The engine holds the world natively (the tree, routing, the queue, ctx.at schedules, persistence, projection, the client's mirror and prediction); a handler gets its entity as a plain Lua table and mutates it, and the engine reads the tables back at the end of the action (all or nothing), sending viewers per-entity #world patches. ctx.effect{...} results come back to the entity that asked. The host stamps every message with viewer, serverTime and origin. Lifecycle messages go to the root's on: $join { did?, handle? } when a viewer connects and $leave when their last connection to the room closes.
  • server module: { kinds, root }. The root is spawned with config: date, now_ms, room, the pack's data files, and legacy (the old state of a room saved before its game was an entity world).
  • Rooms (manifest "rooms"): "daily" (one per UTC date), "player" (one per player), "lobby" (one per join code), or one shared main room. Waiting rooms ("lobby", with "lobby": { "min": 2, "max": 8 }) are the engine's: launching makes a room and its code, cavu.games/launch?game=<slug>&join=<code> joins it (the grant names the room; the page can't pick another). The engine seats players (the first in hosts; away seats drop after 90 s), draws the waiting room (code, invite link, who's here, Start, Remove, Leave) and boots the game's root on Start with config.code, config.host and config.players ({ viewer, did?, handle?, name, host, connected }, in seat order) and config.options, then sends $join for everyone there.
    • Options: "lobby": { "options": [{ "key": "rounds", "label": "Rounds", "min": 3, "max": 7, "default": 5 }] } gives the host a stepper for each; the game gets config.options.rounds.
    • Watchers: whoever comes with the code after the start (or finds every seat taken, or taps "Just watch") watches. They get the game's projection for a viewer who isn't one of its players, their intents are dropped, and the game never hears $join/$leave from them. LOBBY.watching on the client lets a game draw a TV layout. The waiting room has an invite QR (on by default for watchers).
    • Hosting: a host away from a started game for 30 s hands over to a player who is here; the root hears $host { host } (the new host's viewer).
    • Game over: the server calls ctx.game_over(); LOBBY.ended is set and the host gets "Play again" (in the engine menu, or the game's own button firing $lobby.again): back to the waiting room with the same code, seats and watchers, and a fresh world on the next Start.
    • TVs: a screen opens play.cavu.games/tv (or a tab cast there) and shows a code and a QR. A player taps "Show on a TV" (waiting room or menu) and enters it; scanning the QR saves the code on the phone so the waiting room offers it. The room's server sends that TV a watcher's link to the room (a guest grant marked watch; a dev node goes through the gateway's TV table). TV is true on the client of a page opened that way. Games write no lobby code; they restyle it with __lobby_* skins in their own skins (see crates/cavu-lua/lua/client.lua). games/lobby-demo is the example.
  • Rhythm tracks (a manifest music track with "rhythm": true, e.g. "music": { "tracks": { "song": { "src": "fife.mp3", "rhythm": true, "bpm": 112, "offset": 0.42 } } }; bpm/offset are for the game to read from GAME.music): decoded and played through Web Audio, only when the game calls music_play(name, at_ms?). music_time() gives the position as heard (the output's latency allowed for), holding while the menu is open, so a game can time play to the beat; sfx(src, vol, rate, at) can put an effect on one. Ordinary music is untouched.
  • State and logic: a game's modules are logic, hot-swapped by a dev node while it runs (open pages pick up new code within a second) and starting their locals over. State lives in entities (synced and local, held by the engine) or, for big fast-changing client state such as a simulation stepped every frame, in keep(name): a client table kept across swaps, never synced or saved. Server state belongs in entities.
  • client module: { kinds, screen, skins?, loading?, menu?(rd), help?, music?(rd) }: the screen and its children are client-only entities (the UI); help is { title, lines, first_visit }.
  • Shared classes: a manifest's classes ({ name: "classes/x.lua" | "at://…/games.cavu.entityClass/…" }) are loaded, sandboxed, before the modules on both sides.
  • Client extras: sfx(src, volume?, rate?) (rate shifts the pitch), vibrate(ms | {ms, pause, ...}), share(text), share_image{ w, h, draw = function(g) ... end, text?, filename? } (a skin-style drawing shared as a PNG, from a tap), and g.qr(text, x, y, size) in skins.
  • The menu is the engine's: Esc, a corner button (manifest "menu": { "corner": "top-right" | "top-left" | "none" }) or ui.menu_button{...} opens it. It shows who is playing (the server's #welcome frame), sign in / sign out, How to play and All games, in the manifest's page palette. Games fire $menu, $help, $signin, $signout from any behavior instead of building host URLs.
  • manifest.json lists which modules each side gets; server-only modules are never served.

Wire: DAG-CBOR event-stream frames (crates/wire), lexicons in lexicons/games/cavu/.

Local dev #

Everything at once: ./dev.sh starts vivarium (a local atmosphere), the cavu.games host, the play.cavu.games gateway and a dev node for games/ (hot reload), creates test accounts and prints the links. Ctrl-C stops it all; state lives in .dev.

./build.sh
./target/release/cavu-server                     # real OAuth via the loopback client
# open http://127.0.0.1:8788/?game=haiku-day     (127.0.0.1, not localhost, or the cookie won't stick)

./target/release/cavu-server --dev-auth --data /tmp/cavu-dev
# open http://127.0.0.1:8788/?game=haiku-day&dev_did=did:plc:alice&dev_handle=alice.test
# --dev-auth trusts the DID in #join and stores records in a local table (signed for real). Never in prod.

Server flags: --host --port --games --web --data --public-url --did --dev-auth --secrets. Everything durable is in <data>/cavu.db: rooms (Lua state as DAG-CBOR), OAuth sessions + client key (auth_*), and the record-signing key ring (records_signing_keys). Losing it signs everyone out and rotates the signing identity's keys (old records still verify only while their keys stay published).

Outside services (the http effect). A game lists the hosts it calls in game.json ("network": [{ "host": "openrouter.ai", "name": "OpenRouter" }]; players see the names before launch) and its keys go in a secrets file, never in the pack:

./target/release/cavu-server --secrets ~/cavu-secrets.json
# { "<game>": { "openrouter": { "value": "sk-or-...", "hosts": ["openrouter.ai"] } } }
# ("env": "OPENROUTER_API_KEY" instead of "value" reads it from the environment)

Requests go only to declared hosts, over HTTPS, never to private addresses, and a key is only ever sent to the hosts listed with it. See crates/cavu-server/src/http.rs.

Local: host + fleet together (the launch flow) #

cargo build --release -p cavu-host && ./build.sh
./target/release/cavu-server --did 'did:web:127.0.0.1%3A8788' --public-url http://127.0.0.1:8788 \
    --host-url http://127.0.0.1:8787 --data /tmp/cavu-play
./target/release/cavu-host --dev-launch-did 'did:web:127.0.0.1%3A8788' --data /tmp/cavu-host
# open http://127.0.0.1:8787/  (catalog) -> Play -> http://127.0.0.1:8788/?game=haiku-day#launch=...

Publishing games to a PDS #

Games ship as records, not inside the image: play.cavu.games and cavu.games both run with --packs-from pardy.at, so publishing (below) is how a game goes live or updates; no deploy needed. A published game is the publisher's games.atmosphere.define/<slug> (the listing), games.cavu.game/<slug> (launch rules) and the games.cavu.pack/<tid> it points at (one immutable version: every file the game runs, one blob each). cavu-publish decides what ships from manifest.json: the listed modules, classes and data files, assets/** and og.png. Art sources, Tiled maps and design notes stay home.

export CAVU_APP_PASSWORD=...                       # an app password for the publisher (pardy.at)
cargo run -p cavu-packs --bin cavu-publish -- games/haiku-day --dry-run   # what would ship, what's new
cargo run -p cavu-packs --bin cavu-publish -- games/haiku-day             # upload new blobs, new pack, point the game at it
cargo run -p cavu-packs --bin cavu-publish -- games/haiku-day --listing   # ...and write define.json as the listing
cargo run -p cavu-packs --bin cavu-publish -- --versions haiku-day
cargo run -p cavu-packs --bin cavu-publish -- --rollback haiku-day <pack rkey>

cavu-server --packs-from pardy.at and cavu-host --packs-from pardy.at run and list what that account published instead of --games. Each syncs into <data>/packs/games/<slug> (same layout as games/, every blob checked against its CID), follows Jetstream for games.cavu.game and games.atmosphere.define, and reloads a game when its record changes (open rooms keep their state). If the PDS is unreachable the cached copy loads. Locally, against vivarium: --packs-from <did> --plc-url http://localhost:2580 --packs-jetstream ws://jetstream.localhost:2580/subscribe (and cavu-publish --as <did> --pds http://localhost:2580 --plc http://localhost:2580).

Deploy: cavu.games (host) + play.cavu.games (fleet) on Fly #

One image (both binaries, no games: see above), two apps, from the repo root (.dockerignore allowlists what the image needs):

fly apps create cavu-host && fly volumes create cavu_host_data --app cavu-host --region iad --size 1
fly apps create cavu-play && fly volumes create cavu_data      --app cavu-play --region iad --size 1
fly deploy -c fly.host.toml --ha=false
fly deploy -c fly.toml      --ha=false
fly certs add cavu.games --app cavu-host        # apex: A/AAAA to the app's IPs
fly certs add play.cavu.games --app cavu-play   # CNAME play -> cavu-play.fly.dev

Check after deploy: https://play.cavu.games/.well-known/did.json (signing keys + #cavu_launch), https://cavu.games/oauth/client-metadata.json and /oauth/jwks.json, then sign in and play. Back up both volumes: the host's holds players' OAuth sessions, the fleet's holds the signing keys.