# AGENTS.md — OpenVibe.Games

## Project Overview

OpenVibe.Games hosts the browser games at `openvibe.games` and `play.openvibe.games`: **Scraplandia** (a persistent
multiplayer physics sandbox with the scored "Haul" mode), **Salvage Rush** (on-foot timed collection),
**creator worlds** (map editor + `/worlds`, sandboxed), the casual line (plan T22, starting with **Vibe Heroes**),
server-run AI draft matches/Bench scoring, and the moved **OpenVibe.Play player pages** (`/achievements`,
`/leaderboards`, `/developers`) which read Play's public API server-side.

- **Domain:** `openvibe.games`, `play.openvibe.games` · **Port:** 8000 (server; Vite dev client 5173) ·
  **Service id:** `games` · **Env prefix:** `GAMES`/`OV_`
- **Stack:** TypeScript everywhere, pnpm 10 monorepo, Babylon.js (WebGPU/WebGL) client, Rapier
  `@dimforge/rapier3d-deterministic-compat` (one pinned build headless on server and in client prediction), WS
  protocol, PostgreSQL 18 + Valkey through `openvibe-sdk`, QuickJS for script mods.
- **Read first:** [README.md](README.md), [ARCHITECTURE.md](ARCHITECTURE.md), [ROADMAP.md](ROADMAP.md),
  [docs/games.md](docs/games.md), [docs/casual.md](docs/casual.md), [docs/mods.md](docs/mods.md),
  [docs/instances.md](docs/instances.md), [docs/ai-matches.md](docs/ai-matches.md), [ADR-0007](docs/adr/), [ADR-0013](docs/adr/).

**Network context:** players are keyed by Network `subject_id` (`usr_…`/`gst_…`); SSO/JWKS/identity/mod grants are
OpenVibe.Network. Events are OpenVibe.Events (transactional outbox). Achievements/scores go to OpenVibe.Play's API;
six built-in achievements grant Live items through OpenVibe.Inventory. Map-editor assets are also copied to
OpenVibe.Media objects. Mod grants' authority is Network (`mods.grant.manage`); Games runs its own bounded
`games-quickjs@1` scripts. The platform boundary is `apps/server/src/platform` and `apps/server/src/mods`; the
simulation packages do not know the platform exists.

## Commands

```bash
corepack enable && pnpm install          # Node ≥22, pnpm 10.6.5
pnpm dev                                 # server + client dev in parallel
pnpm dev:server                          # authoritative server on :8000 (tsx watch)
pnpm dev:client                          # client hot reload on :5173 (proxies /ws to :8000)
pnpm test                                # all vitest files through test/run.js
pnpm typecheck                           # strict TypeScript across every package
pnpm lint                                # ESLint (no-explicit-any)
pnpm format                              # Prettier write (format:check in CI)
pnpm build                               # all packages + client bundle
node test/run.js --index                 # regenerate the flat test/*.test.js pointers after adding/moving a test
tsx apps/server/scripts/sliceTest.ts     # end-to-end vertical slice: real server, protocol clients, restart
pnpm test:editor | test:collab | test:console   # e2e Playwright checks (editor, collaboration, console)
pnpm audit:editor                        # editor architecture audit (vitest config)
```

Production: `pnpm build`, then `DATABASE_URL=… DATABASE_DIRECT_URL=… STATIC_DIR=apps/client/dist PORT=8000 pnpm
--filter @openvibe/server start`. `DATABASE_URL` serves through PgBouncer; migrations run at boot on
`DATABASE_DIRECT_URL` (owner, direct); without both and outside production, PGlite under `DATABASE_DIR`.

## Architecture at a Glance

- **Server entry:** `apps/server/src/main.ts`; authoritative simulation, networking, persistence, platform boundary
  ([apps/server/src/platform](apps/server/src/platform)), mods ([apps/server/src/mods](apps/server/src/mods)),
  maps, worlds, casual, AI matches, Steam lists, observability.
- **Client:** [apps/client/](apps/client/) — rendering, prediction, input, HUD, the map editor (`src/editor/`), e2e
  scripts; Babylon is imported **only** here.
- **Packages:** [packages/shared/](packages/shared/) (math, ids, events, logging, fixed timestep),
  [packages/protocol/](packages/protocol/) (versioned wire messages, zod-validated inbound),
  [packages/content/](packages/content/) (data-driven items/recipes/worlds + validation registry),
  [packages/gameplay/](packages/gameplay/) (pure inventory/crafting/movement/zones/entities),
  [packages/physics/](packages/physics/) (abstraction + Rapier adapter),
  [packages/persistence/](packages/persistence/) (DTOs, repositories, PostgreSQL, migrations),
  [packages/casual/](packages/casual/) (casual rules/auto-battle/Vibe Heroes, engine-free).
- **Dependency graph (ARCHITECTURE.md):** shared → protocol/content/physics → gameplay → persistence → apps; only
  `apps/server` and `packages/persistence` know PostgreSQL; `packages/*` never import browser-only APIs.
- **Simulation:** 30 Hz fixed tick, 15 Hz snapshots; kinematic Source/Quake controller, client prediction + rewind +
  interpolation; physics sleep is first-class (settled props cost nothing on the wire).
- **Data:** [packages/persistence/migrations/](packages/persistence/migrations/) (23 migrations: characters, world,
  props, instances/leases, progress, hauls, inventory rewards, casual, Play sync, telemetry, creator worlds/scripts/
  teams/assets, surf, AI matches, sharing, outbox). A write-behind flusher means the tick never awaits I/O; SIGTERM
  drains it.
- **Pages:** `/` (portal; on play.openvibe.games `/` is the game), `/play`, `/editor`, `/worlds`,
  `/achievements`, `/leaderboards`, `/developers`, `/play/vibe-heroes`, `/healthz`, `/api/ready`, `/metrics`.
- **Deploy:** [deploy/openvibe-games.service](deploy/openvibe-games.service) (PORT 8000, HOST 127.0.0.1,
  `/etc/openvibe/games.env`, `GAMES_MIGRATIONS_DIR`, `MAP_PATH`, `STATIC_DIR`, `TRUST_PROXY=127.0.0.1`,
  `TimeoutStopSec=30`), [deploy/nginx-openvibe-games.conf](deploy/nginx-openvibe-games.conf),
  [deploy/scripts/deploy.sh](deploy/scripts/deploy.sh) wrapping `ovhost deploy games` (strategy `pnpm-build`:
  `pnpm install --frozen-lockfile`, `pnpm build`, restore tracked `dist-types/`, restart). `--wait-idle` holds the
  restart until nobody plays; `DRY_RUN=1` prints `ovhost plan games`; rollback `sudo deploy/scripts/deploy.sh
  --rollback` (rebuilds the previous commit).

## Ownership and Boundaries

Games owns the authoritative simulation (world, characters, inventories, skills, blueprints, props), the
write-behind persistence schema, the map editor and its assets, the mod registry/content/script sandbox and its audit,
the `games.*` events, the WS protocol and the portal/play/editor pages, the casual kit and its server economy, creator
worlds, AI draft matches, and the moved Play player pages. It does **not** own identity (Network subjects), files
beyond the local copy (Media mirrors), event delivery (Events), Play's service/API (Play), Inventory items (Inventory),
or general-purpose executable mods (Host Stage C; Games' QuickJS scripts are bounded and approved per install).

## Platform Integration (the boundary)

- **Identity:** a signed-in player is the token's `subject_id`; a token without one cannot name an account, and a
  guest token that looks like `usr_…` is refused. Never key a row on a display name.
- **Service principal:** calls to Events/Media/Network identity/Inventory/Play carry a client-credentials token for
  the `games` client, one per audience. No shared keys. SSO calls for a player use the player's own token.
- **Events:** `games.player.joined|left`, `games.skill.leveled`, `games.blueprint.unlocked`, `games.world.saved`
  (≤1 per `WORLD_SAVED_EVENT_MINUTES`, plus shutdown), `games.mod.installed|enabled|disabled|grants_changed|revoked`.
  Achievements are **not** events: an unlock is stored in Games and sent to Play; the six inventory-bearing
  achievements grant through Inventory and retry on failure.
- **Play:** `GAMES_PLAY_URL` (unset = scores/unlocks stay local); Play is the network-wide read surface.
- **Media:** only map-editor assets (textures, paint masks, glb) are uploaded; a restart-safe `media_mirrors` queue
  copies them to the `games` tenant. There is no screenshot/blueprint upload.
- **Mods:** manifests follow `mods.mod-manifest@1.1.0` validated against the installed Contracts (pin drift is a
  defect); `games-content@2` packs merge definitions at boot, the client sends its definition digest in `hello` and the
  server rejects a mismatch; each install stores the approved subset of requested capabilities, every runtime binding
  checks it, revocation stops affecting the world on the next tick, and install/grant/use/deny/revoke are audited.
  `games-quickjs@1` runs only with `GAMES_SCRIPT_MODS=1` in a per-mod QuickJS sandbox (defaults `cpuMs` 2/tick,
  `memoryMb` 8, `stackKb` 128; over budget disables the mod for the instance).
- **Frame:** the portal/play/editor load the OpenVibe Frame from this server's own `/shared/` copy, so it keeps its
  frame while Network is down. `GET /api/v1/platform` reports events/Media-mirror state and backlog without secrets.

## Capabilities and Grants

Implemented: `games.mod.manage`, `games.mod.read` (mods API), `games.world.announce`, `games.prop.place`,
`games.def.define` (declarative packs), and for script packs `games.script.run`, `games.players.read`,
`games.player.message`, `games.world.emit`, `games.storage.kv`. Script bindings are absent unless approved for that
install. The `games` principal needs `inventory.item.grant`, `events.event.publish|subscription.manage`,
`media.object.upload` (namespace `games`), `identity.subject.resolve`, `network.modules.write` on
`games.progress.summary`, and Network's `mods.grant.manage`.

## Conventions and Pitfalls

- **The server is the game.** Every gameplay-relevant decision is server-simulated/validated; no client field is
  trusted; inbound messages are zod-validated and flood-controlled.
- **Do not import Babylon into `apps/server`** (the architecture audit fails) or platform modules into `packages/*`;
  keep gameplay engine-free and deterministic (same Rapier build on both sides).
- **Data-driven content:** add definitions in `@openvibe/content`, validate at startup; stable ids, display names are
  cosmetic. A new built-in pack must not bypass the capability check.
- **Migrations** are `packages/persistence/migrations/NNNN_*.sql`, applied at boot with the owner URL; never edit one
  that has run. The tick never awaits I/O — write-behind, then drain on SIGTERM (30 s stop timeout).
- **Instances/leases:** PostgreSQL records each room and a renewable fenced lease; `GAMES_INSTANCES_PER_PLACE` only
  within one process, `GAMES_CREATOR_WORLDS_MAX` caps creator worlds, empty ones stop after the idle timeout. A lease
  that is lost must stop the place (old failure: five places lost leases in one night).
- **`TRUST_PROXY`:** unset means the TCP peer is the client and all forwarded headers are ignored (otherwise a caller
  mints fresh rate-limit buckets); behind nginx it is `127.0.0.1`, and nginx overwrites the headers from
  `$remote_addr`. Never read `X-Forwarded-For` directly.
- **Static serving:** an unknown path is a 404 (HTML page, `{"error":"not_found"}` under `/api`, plain text for a
  missing asset), never the portal with 200. `/api/ready` is 200 only while the database answers a real round trip.
- **Test pointers:** after adding/moving a `*.test.ts`, run `node test/run.js --index`; a missing/stale flat pointer
  fails the suite. Vitest reads the real colocated file.
- **Build:** pnpm's `onlyBuiltDependencies` is `esbuild`; Corepack downloads pnpm with Node's fetch in CI (the image
  bakes it). `pnpm install --frozen-lockfile` and a clean `pnpm build` are the deploy gate.
- **nginx** keeps `/api/ready` off the public vhosts; `/metrics` answers loopback only. Secrets
  (`OV_OAUTH_CLIENT_SECRET`, `GAMES_EVENTS_SECRET`, `OV_NETWORK_AUTH_URL`) live in `/etc/openvibe/games.env` by name
  only.
- **Play's old pages 301 here:** do not re-add `apps/server` player pages under play.openvibe.network; the service and
  API stay there.
- Phone first for casual/portal pages; no Font Awesome; "Calm reduces, only Off removes".

## Testing

`pnpm test` runs every vitest file through [test/run.js](test/run.js) (package and server units incl.
`apps/server/src/game/platformIntegration.test.ts`, which boots the real server twice on one database, and the
architecture audit). `pnpm typecheck`/`pnpm lint` keep strict TS and no `any`; `tsx apps/server/scripts/sliceTest.ts`
drives protocol clients across a restart; `pnpm test:editor|test:collab|test:console` are Playwright e2e checks. Run
the narrowest file first, then the suite.

## Documentation

- [README.md](README.md) — purpose, owns, does-not-own, depends on, layout, development, commands, production,
  platform integration, capabilities, tests, security.
- [ARCHITECTURE.md](ARCHITECTURE.md) — principles, package graph, simulation, networking, server systems, persistence,
  platform boundary, zones, entities, observability, security posture.
- [ROADMAP.md](ROADMAP.md), [docs/games.md](docs/games.md), [docs/casual.md](docs/casual.md),
  [docs/MAP_EDITOR.md](docs/MAP_EDITOR.md), [docs/EDITOR_COMPLETION_STATUS.md](docs/EDITOR_COMPLETION_STATUS.md),
  [docs/instances.md](docs/instances.md), [docs/mods.md](docs/mods.md), [docs/ai-matches.md](docs/ai-matches.md),
  [docs/platform-direction.md](docs/platform-direction.md), [docs/adr/](docs/adr/),
  [docs/capabilities-proposal/](docs/capabilities-proposal/), [docs/service-manifest-proposal.json](docs/service-manifest-proposal.json).
- [SECURITY.md](SECURITY.md), [.env.example](.env.example), [CHANGELOG.md](CHANGELOG.md).