- Rust 54%
- Lua 39%
- Python 3%
- HTML 2%
- Jinja-like 1%
- 5 more languages 1%
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, scheduledctx.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 clientview,synced(new, old)andframe. The engine holds the world natively (the tree, routing, the queue,ctx.atschedules, 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#worldpatches.ctx.effect{...}results come back to the entity that asked. The host stamps every message withviewer,serverTimeandorigin. Lifecycle messages go to the root'son:$join { did?, handle? }when a viewer connects and$leavewhen their last connection to the room closes. - server module:
{ kinds, root }. The root is spawned withconfig:date,now_ms,room, the pack'sdatafiles, andlegacy(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 sharedmainroom. 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 withconfig.code,config.hostandconfig.players({ viewer, did?, handle?, name, host, connected }, in seat order) andconfig.options, then sends$joinfor everyone there.- Options:
"lobby": { "options": [{ "key": "rounds", "label": "Rounds", "min": 3, "max": 7, "default": 5 }] }gives the host a stepper for each; the game getsconfig.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/$leavefrom them.LOBBY.watchingon 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.endedis 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 markedwatch; a dev node goes through the gateway's TV table).TVis true on the client of a page opened that way. Games write no lobby code; they restyle it with__lobby_*skins in their ownskins(seecrates/cavu-lua/lua/client.lua).games/lobby-demois the example.
- Options:
- 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/offsetare for the game to read fromGAME.music): decoded and played through Web Audio, only when the game callsmusic_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);helpis{ 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), andg.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" }) orui.menu_button{...}opens it. It shows who is playing (the server's#welcomeframe), sign in / sign out, How to play and All games, in the manifest's page palette. Games fire$menu,$help,$signin,$signoutfrom 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.