@genex-ai/cli-demo 1.38.0 → 1.38.1-dev.1097

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.38.0",
+  "version": "1.38.1-dev.1097",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/skills/genex-authoritative-multiplayer/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: genex-authoritative-multiplayer
+description: Server-authoritative multiplayer for Genex games — the game's own room module runs on Genex's servers, players only send input, and the server decides every move and hit (lag-compensated). Use for competitive play where cheating matters: ranked PvP, arenas, shooters (first-person, hitscan or dodgeable projectiles), car football, "so nobody can cheat". Casual co-op and hangouts use genex-threejs-multiplayer instead. Load before writing the room module or any networking code.
+---
+
+# Genex Server-Authoritative Multiplayer
+
+In a server-authoritative game the **server runs the game's rules**. The game ships a **room
+module** — one script, `server/room.ts` or `server/room.js` — that Genex runs in a sandbox at a
+fixed tick. Players send typed input (`moveX`, `moveY`, `yaw`, `buttons`, …); the server moves
+every body, judges every shot against where the shooter saw its target, and writes the state every
+client renders. A modified client can lie only about its own stick and buttons.
+
+The client half is `connectAuthority` from `@genex-ai/multiplayer/authority`: it predicts the
+player's own body with the same movement preset the server runs (so moving feels instant), draws
+everything else 100 ms in the past, and reconciles when the server's truth arrives.
+
+## Casual or server-authoritative
+
+| | Casual — `$genex-threejs-multiplayer` | Server-authoritative — this skill |
+|---|---|---|
+| Who runs the rules | Each player's browser; Genex's relay passes messages | Genex's servers run the game's room module |
+| Cheating | A modified client can say where it is and what it hit | The server decides every move and every hit |
+| Fits | Co-op, hangouts, party, turn-based, casual races | Competitive shooters, arenas, ranked play — anything with a winner worth faking |
+| On Genex's servers | Free | Needs Genex Pro for the game's owner |
+| Building and testing | Free | Free, on this machine, with no account |
+
+"Competitive", "ranked", "PvP", "esports", "so nobody can cheat" or "server-authoritative" mean
+this skill; everything else is casual. When the person has not said which, ask in one line and say
+what each costs. Never mix the two in one game: an authority game has no relay `Session`, no host
+and no shared objects — the server owns all state.
+
+## What you write
+
+1. **The room module**, `server/room.ts` (or `.js`): `export default` a room with `contract: 1`,
+   `config`, `init`, `onJoin`, `onLeave`, `onInput` and `step`. It is server code: keep it and
+   everything only it uses in `server/`. Shared pure code (a movement step the client also runs)
+   may live in `src/` and be imported by both. The full API and the sandbox's rules are in
+   [references/module-api.md](references/module-api.md); four complete games to start from (an
+   arena with instant shots, one with bolts players can dodge, a car arena with a ball, and the car
+   arena on server physics with crates) are in
+   [references/room-template.md](references/room-template.md).
+2. **The manifest block**, in package.json:
+
+   ```json
+   { "genex": { "authority": { "module": "server/room.ts", "tickHz": 30, "maxPlayers": 8, "preset": "topdown" } } }
+   ```
+
+   A game without a package.json (one made from Studio's template) puts the same object in
+   `genex.json` as `{ "authority": { … } }`. `module` is a plain relative path to a `.js` or `.ts`
+   file inside the game folder. The rest is optional: `maxPlayers` (1 to 64) is the most a room
+   seats (the module may ask for fewer), `tickHz` (20, 30, 60 or 120) is the rate for a module whose
+   `config` names none (120 only for a module that asks for physics), and `preset` names its movement preset. Left out, each comes from the
+   module's own `config`. A malformed block is not ignored — `genex preview` refuses it and says why.
+3. **The client**: `connectAuthority` with the identity from `$genex-threejs-embed-auth`, input
+   written to `session.input`, `session.frame(now)` once per render frame, and the scene drawn
+   from `session.entities()`.
+4. **The packages**: `npm i @genex-ai/multiplayer@latest @genex-ai/embed-sdk@latest` and
+   `npm i -D @genex-ai/authority-dev`. The game needs a `@genex-ai/multiplayer` that exports
+   `@genex-ai/multiplayer/authority` and an embed SDK at 0.35.0 or newer (it has
+   `getAuthorityUrls`). If the import does not resolve after installing `@latest`, the release with
+   server-authoritative rooms is not out yet: tell the person plainly and stop, rather than writing a
+   server of your own. Projectiles need `@genex-ai/multiplayer` 0.17.4 or newer.
+
+## Rules that decide whether it plays well
+
+1. **The server decides; the client asks.** Health, score, pickups, kills, respawns and round
+   state change only in the room module, and the client draws them from `session.entities()` and
+   the module's events. Show a muzzle flash or play a sound at once if you like, but never draw a
+   hit, a kill or a score the server has not sent.
+2. **Never move your own body yourself.** Write the stick and aim into `session.input`; the session
+   predicts your body with the room's preset and corrects it. A game whose movement is not the
+   preset passes its own step as `predict: { step }` — the exact step the module runs
+   ([references/presets.md](references/presets.md)).
+3. **The module must be deterministic.** The same seed and inputs must give the same room: no
+   clock, no timers, and randomness only from `ctx.random()` (`Math.random` is the same seeded
+   generator inside the sandbox). `validate` and `replay` check this, and a publish refuses a
+   module that fails.
+4. **Bump `epoch` to teleport.** A respawn or a teleport that does not bump the entity's `epoch`
+   slides across the map on every other screen.
+5. **Keep per-tick work bounded.** Each tick has a CPU and memory budget; a runaway loop ends the
+   room for everyone in it. Loops run over entities or players, never "until something happens".
+6. **The server's plane is x/y, and +z is up.** `yaw` turns from +x toward +y. For `firstperson`
+   and `vehicle`, draw at three.js `(x, z, -y)` with `rotation.y = yaw`: their input's "right" is
+   the server's, and a mirrored drawing steers the car the wrong way. The topdown templates draw the
+   server's `y` as three's `z`, which works there because they read input in the same drawn axes.
+
+## Movement: pick a preset
+
+| The game | `config.preset` | Notes |
+|---|---|---|
+| Seen from above (twin-stick, top-down shooter) | `topdown` | 30 Hz is enough |
+| On foot through a level (a first-person or third-person shooter) | `firstperson` | Source-engine-style movement through a world of boxes and ramps; `tickHz: 60` |
+| Cars (car football, a derby, a track of ramps) | `vehicle` | Rocket League's handling, kept level, through the same kind of world; `tickHz: 60` |
+| Anything else | none: your own step | Shared by the module and the client, `predict: { step }` |
+
+`firstperson` and `vehicle` move through a fixed collision world the module exports
+(`defineRoom({ world })`) and the client hands its session (`connectAuthority({ …, world })`),
+from one file both import: the session predicts only while the two hash the same. Their inputs,
+parameters, units and CPU budget are in [references/presets.md](references/presets.md); read it
+before writing either side. A ball the cars knock about is one projectile the module re-launches
+(template 3, and "Running a ball" in presets.md).
+
+## Feel settings: contacts, inputs, lifts, tick rate, regions, fast channel
+
+Seats that touch (standing on heads, shoving, passing through), starved inputs, moving platforms, 120 Hz,
+regions and the UDP fast channel are **settings in `config`**, picked by genre (`shooter`, `platformer`,
+`party`, `physics-sandbox`, `vehicle-arena`), never code that names the game. Read
+[references/settings.md](references/settings.md) for a worked config per genre before writing any of them.
+
+## Physics: crates, balls, doors
+
+When things must collide with each other (a stack that topples, a ball between cars and walls, a
+door a player shoves), the module asks for server physics (`config.physics`) and spawns bodies with
+`ctx.physics`; clients only draw them. It is new: check physics.md for when the servers run it. Read
+[references/physics.md](references/physics.md) first; template 4 is the car arena with a physics ball
+and crate stacks.
+
+## Shots: hitscan or projectile
+
+- **Instant** (a rifle, a laser): `ctx.rewind.hitscan` in `onInput`, lag-compensated with
+  `config.lagComp`. Template 1.
+- **Something players see travel and can dodge** (a bolt, a rocket, a grenade, an arrow, a
+  dodgeball): a projectile. The module launches it once with `ctx.projectiles.launch` and judges it
+  with `ctx.projectiles.sweep`; the shooter's client calls `session.predictProjectile` while staging
+  the input that fires, and every client draws it from `session.entities()`. Template 2. Read
+  [references/projectiles.md](references/projectiles.md) before writing either side.
+
+Never make a travelling shot a plain entity the module moves in `step`: it costs an update every
+tick and every client draws it 100 ms late. Every client in a room whose module launches
+projectiles must support them; one that does not draws each projectile frozen where it was
+launched.
+
+## The client in one screen
+
+```ts
+import { connectAuthority } from "@genex-ai/multiplayer/authority";
+import { getAuthorityUrls, getColyseusAuth, waitForPlayer } from "@genex-ai/embed-sdk";
+import { GENEX } from "./genex.config";
+
+await waitForPlayer();
+const session = await connectAuthority({
+  urls: getAuthorityUrls(),
+  room: GENEX.slug,
+  auth: () => getColyseusAuth(),
+});
+
+function loop(now: number) {
+  session.input.moveX = stick.x; // [-1, 1] on the server's x axis
+  session.input.moveY = stick.y; // [-1, 1] on the server's y axis
+  session.input.yaw = aimAngle; // radians, 0 along +x
+  session.input.buttons = firing ? FIRE : 0;
+  session.frame(now); // sends the due inputs, predicts you, interpolates everyone else
+  for (const [id, e] of session.entities()) drawBody(id, e.x, e.y, e.yaw, e.epoch);
+  requestAnimationFrame(loop);
+}
+requestAnimationFrame(loop);
+session.on("shot", (data) => showTracer(data)); // an event the room module emitted
+session.on("disconnect", (code) => showLeft(code));
+```
+
+A refused join rejects with a `code`: 402 (the owner's plan does not include Genex servers — final),
+424 (no room module is published for this build yet), 426 (the SDK is too old), 429 (the owner's
+server time or room limit is used up — try later) or 503 (no server free — the session already retried). Say each
+in the player's words; never loop on 402 or 424. The whole client, with three.js, is in
+[references/room-template.md](references/room-template.md).
+
+## Shipping it
+
+`npx genex preview` and `npx genex publish` ship the room module with the build, and refuse to
+ship one that is not ready:
+
+- **Before anything is built**, the module is bundled and validated with the game's own
+  `@genex-ai/authority-dev` (the same check as `npx genex-authority-dev validate`). Any failure stops
+  the deploy and prints its typed reason; the full report is kept at `.genex/authority/report.json`.
+- **Before any game file uploads**, the module and its report go to a private store that the game's
+  address never serves, and `server/` is left out of the public build.
+- **On Genex's servers the owner needs Genex Pro.** A free account is refused with
+  `authority_requires_pro` and nothing is uploaded; it can still build and test everything locally.
+  Say so before the person publishes.
+- A preview link plays in rooms apart from the live game, as casual multiplayer's does, and
+  `npx genex promote` / `npx genex rollback` move the module together with the build — a rollback can
+  restore the previous module alone when only `server/` changed.
+
+## Test it on this machine — CLI lane
+
+Everything above holds in every lane. This section is how the server runs while you build: when the
+app you run in loads this skill under its own preface, with its own local server tool, that preface
+replaces this section wherever they differ.
+
+```sh
+npx genex-authority-dev validate --module server/room.ts --root .
+npx genex-authority-dev start --module server/room.ts --root . --bots 3 --latency 75 --report
+```
+
+`start` prints `LISTEN ws://127.0.0.1:<port>`. Open the dev server with that address —
+`http://localhost:5173/?genex_local_test=1&genex_authority_url=ws://127.0.0.1:<port>` — and
+`getAuthorityUrls()` returns it, so the same client code joins the local room as a local player
+next to the bots. `--latency 75` is 75 ms each way, the ping real players feel; test there, not at
+zero. `--root .` lets the module import shared files outside `server/`. What each command checks,
+the REPORT line and every failure reason are in [references/testing.md](references/testing.md).
+
+Before calling it done: `validate` passes, `replay` says the hashes are equal, two people (a normal
+and a private window both count) have moved and fired at 75 ms, and nobody slides after a respawn.
+With projectiles, also the checks at the end of
+[references/projectiles.md](references/projectiles.md). With `firstperson` or `vehicle`,
+`session.prediction.predicting` is true while you play (never `world_mismatch`), and a full room
+stays under budget in the REPORT line. Say plainly what was not exercised.

package/templates/skills/genex-authoritative-multiplayer/references/module-api.md

@@ -0,0 +1,172 @@
+# Room module API
+
+The room module is one ES module whose default export is a room. Its types are published at
+`@genex-ai/multiplayer/authority/module`: `GenexRoomModule`, `RoomContext`, `InitContext`,
+`EntityApi`, `EntityData`, `EntityInit`, `RewindApi`, `ProjectileApi`, `ProjectileInit`,
+`ProjectileFlight`, `ProjectileHit`, `InputData`, `PlayerInfo`, `ModuleConfig`,
+`ResolvedModuleConfig`, `PresetSpec`, `LeaveReason`, `Vec3`, `Json`, `MODULE_CONTRACT` and the
+identity helper `defineRoom`.
+
+A TypeScript module imports the types with `import type` (they are erased when it is bundled). A
+module imports **nothing at runtime from a package**: the bundle runs in a sandbox and every byte it
+needs must be inside the game folder. A plain-JavaScript module therefore writes its own one-line
+`defineRoom`, as [the template](room-template.md) does. Relative imports of your own files are
+fine — a movement step in `src/` that the client also runs is the usual one.
+
+```ts
+import type { GenexRoomModule, InputData, PlayerInfo, RoomContext } from "@genex-ai/multiplayer/authority/module";
+
+interface State {
+  score: Record<string, number>;
+}
+
+const room: GenexRoomModule<State> = {
+  contract: 1,
+  config: { tickHz: 30, maxPlayers: 8, preset: { name: "topdown" }, lagComp: { buttons: 1 } },
+  init: () => ({ score: {} }),
+  onJoin(ctx, player) { ctx.entities.spawn({ kind: "player", owner: player.id, hp: 3 }); },
+  onLeave(ctx, player) { const me = ctx.entities.ownedBy(player.id); if (me) ctx.entities.remove(me.id); },
+  onInput(ctx, playerId, input) { /* one input, after the preset moved the player's body */ },
+  step(ctx) { /* once per tick, after the tick's inputs */ },
+};
+export default room;
+```
+
+## The room
+
+| Field | What it is |
+|---|---|
+| `contract` | Always `1`. A bundle whose default export has another contract does not load. |
+| `config` | Optional, and the one place to set these. `tickHz` (20, 30, 60 or 120), 120 only with `physics`; `maxPlayers` (a room never seats more than the game's manifest allows), `preset` (`{ name, params? }` with `name` one of `topdown`, `firstperson` or `vehicle`, see [presets.md](presets.md)) and `lagComp: { buttons }` — the bitmask of input buttons that ask for lag compensation. What the room runs with is `ctx.config` in `init`. `physics` asks for server physics (crates, balls, doors): see [physics.md](physics.md), which also says when Genex's servers run it. |
+| `world` | The `firstperson` and `vehicle` presets' collision world, `{ boxes, ramps }`, fixed for the room's life. Validated when the module loads; its hash becomes the preset's `params.world`, and the client hands its session the same object (`session.setWorld`). Left out, the world is empty: no floor. See [presets.md](presets.md). |
+| `init(ctx)` | Runs once. Returns the module's own state, `ctx.state` from then on. Clients never see it. |
+| `onJoin(ctx, player)` | A player took a seat. Spawn their body here. |
+| `onLeave(ctx, player, reason)` | A seat ended. Remove what they owned. `reason` is a `LeaveReason`: `left`, `dropped` (the reconnect grace ran out), `superseded` (a newer session of the same player took the seat), `revoked` or `closing`. |
+| `onInput(ctx, playerId, input)` | One call per input, in each player's order, before `step`. |
+| `step(ctx)` | Once per tick, after the tick's inputs. |
+
+`player` is a `PlayerInfo`: `id` is the **seat** (an entity's `owner`, and what `emit(…, to)` takes);
+`uid` is the player's stable id for this game across visits — key saves and scores by it; `name`;
+`team` (`''` for none). A hook that throws costs only itself — the tick's other hooks still run —
+but it is a fault (below).
+
+`input` is an `InputData`, already cleaned by the server: `moveX`, `moveY`, `moveZ` in [-1, 1],
+`yaw` and `pitch` in [-π, π), `buttons` an integer bitmask below 2^24. With a `preset`, the server
+has already moved the player's first owned entity by this input when `onInput` runs; `onInput` is
+where buttons become actions.
+
+## The context
+
+| Member | What it is |
+|---|---|
+| `ctx.state` | What `init` returned. |
+| `ctx.tick` | The fixed-step tick, from 0. |
+| `ctx.dt` | Seconds per tick (1 / tickHz). |
+| `ctx.random()` | The room's seeded generator: the only randomness there is. `Math.random` is the same generator. |
+| `ctx.entities` | The entities: the only state clients see. |
+| `ctx.rewind` | Lag-compensated hit tests. |
+| `ctx.projectiles` | Shots on a ballistic flight that every client draws from one launch (below, and [projectiles.md](projectiles.md)). |
+| `ctx.emit(type, data?, to?)` | A game event to every client, or only to the seat `to`. Clients receive it with `session.on(type, handler)`. |
+| `ctx.log(...values)` | A server log line, rate limited. |
+
+`init` gets `ctx.config`, `ctx.seed`, `ctx.random()`, `ctx.entities`, `ctx.projectiles` and
+`ctx.log` (no tick, no rewind, no emit yet). A projectile launch in `init` throws, and the module
+does not load: launch from a hook that runs in a tick.
+
+## Entities
+
+Each entity is an `EntityData`: `id`, `kind`, `owner` (a seat, or `''`), `x` `y` `z`, `vx` `vy`
+`vz`, `yaw`, `hp`, `flags` (an integer bitmask below 2^24), `epoch` and `data` (any JSON), plus
+three projectile fields that only `ctx.projectiles.launch` writes and `update` ignores: `t0` (the
+launch tick; 0 = not a projectile), `g` (its gravity) and `src` (the seat that fired it, `''` for
+none). Numbers are float32 on the wire. Only fields that changed this tick go out.
+
+The movement presets add their own fields, which the preset writes from each input and the module
+may write too (a respawn, a refuel):
+
+| Field | Preset | What it is |
+|---|---|---|
+| `pitch` | `firstperson` | The aim's pitch, radians, positive up. |
+| `duck` | `firstperson` | 0 standing to 1 fully ducked: derive the eye height from it. |
+| `mstate` | `firstperson`, `vehicle` | Movement bits: 1 on the ground, 2 ducking, 4 jump held. Write 0 on a respawn. |
+| `cap` | `firstperson`, `vehicle` | A speed multiplier from 0 to 4, default 1, that only the module writes (a weapon's weight, a wound, a slow zone); a car's applies to both top speeds. |
+| `spin` | `vehicle` | The car's turn rate, rad/s, positive toward +yaw. Write 0 on a respawn. |
+| `fuel` | `vehicle` | The boost tank, 0 to 1, default 0. The preset only burns it: write it to refuel. |
+
+| Call | Does |
+|---|---|
+| `ctx.entities.spawn({ kind, ...fields })` | Adds one and returns its id (the `id` you pass when it is free, else a fresh one). |
+| `ctx.entities.get(id)` | The entity, or `undefined`. Assigning to its fields updates it. |
+| `ctx.entities.update(id, patch)` | Changes several fields at once. |
+| `ctx.entities.remove(id)` | Removes it. |
+| `ctx.entities.ownedBy(seat)` | The first entity that seat owns: a player's body. |
+| `ctx.entities.all()` | Every entity. |
+
+**Bump `epoch` when an entity jumps** (a respawn, a teleport): clients snap to it instead of sliding
+across the map. Clients predict the first entity a player owns that is not a projectile, so give
+each player one body, spawn everything else (pickups, props) unowned, and launch shots with
+`ctx.projectiles.launch`, never as plain entities moved in `step`.
+
+## Lag compensation
+
+`ctx.rewind.hitscan(origin, dir, { range, radius, kinds })` returns the nearest `{ id, dist }` along
+the ray, or `null`; `ctx.rewind.overlapAt(center, radius)` returns every id within the radius. While
+`onInput` handles an input whose `buttons` intersect `config.lagComp.buttons`, both test the
+positions **that player saw** when they pressed it (at most 500 ms back); otherwise they test the
+current positions. During that input the shooter's own entities are never its target. A shot judged
+this way lands when it looked right on the shooter's screen.
+
+## Projectiles
+
+A projectile's launch is written once; every client computes its flight, so it costs nothing per
+tick on the wire and is drawn at the server's present. The whole guide, the client side included, is
+[projectiles.md](projectiles.md).
+
+| Call | Does |
+|---|---|
+| `ctx.projectiles.launch({ kind, x, y, z, vx, vy, vz, g?, hp?, flags?, data?, id? })` | Launches at the tick being stepped, `owner` `''`, and returns the id. In `onInput` the id is `<seat>.<seq>.<n>` (the one the shooter's client predicted) and `src` the seat; passing `id` there throws. Elsewhere `id` is required and `src` is `''`. An existing id is re-launched, replaced whole: a bounce. `g` is downward along −z, 0 to 1000 units/s². Throws a `RangeError`, writing nothing, past the launch budget. |
+| `ctx.projectiles.at(id, tick?)` | `{ x, y, z, vx, vy, vz }` at that tick (default: this one), or `undefined` for an id that is not a projectile. |
+| `ctx.projectiles.sweep(id, { kinds, radius })` | `{ id, dist }[]`, nearest first: the entities of those kinds whose sphere of `radius` the path crossed since the previous tick. The shooter's own body can be among them (a launch point inside it): skip it. Costs the number of entities of those kinds. |
+
+Projectiles take no part in lag compensation: `ctx.rewind` skips them, and a sweep tests bodies
+where they are now. The server never removes one: the module does, on a hit, at the walls or after a
+maximum age. Change a flight by re-launching; `update` on its `x`…`vz` keeps the old launch tick, so
+it jumps. The launches waiting to go out may hold at most 224 entities and 28 KiB of output, about a
+hundred new projectiles in one tick.
+
+## What the sandbox has, and what it refuses
+
+The module runs with no clock, no timers, no network, no files and no shared memory. Absent:
+`Date`, `SharedArrayBuffer`, `Atomics`, `WebAssembly`, `console`, `WeakRef`, `FinalizationRegistry`,
+`Intl`, `setTimeout`, `setInterval`, `setImmediate`, `clearTimeout`, `clearInterval`,
+`queueMicrotask`, `fetch`, `require`, `process`, `performance`. Reaching the global object
+(`globalThis`) instead of `ctx` fails validation too. Everything the module needs arrives through
+`ctx`.
+
+Its output is checked every tick, and each of these is a **fault**:
+
+- a hook that throws;
+- a number that is not finite, or past 1e9 in magnitude;
+- at most 256 entity updates, and at most 256 removals, in one tick — more is a fault;
+- at most 64 events in one tick;
+- at most 1024 entities in the room at once;
+- one event at most 16 KiB as JSON;
+- entity `data` at most 256 characters as JSON;
+- an id that is empty, longer than 64 characters, or `__proto__`, `constructor` or `prototype`.
+
+The third fault ends the room (close code 4501, and every player sees `disconnect`). So does a tick
+that runs past its deadline or a module whose CPU or memory use stays over budget. Keep per-tick
+work small, bounded and the same every run: `validate` holds it to a local CPU budget so a module
+that passes here fits Genex's servers.
+
+## Determinism
+
+The same seed and the same inputs must give the same room. That is what makes a validation report
+mean something and what `replay` checks. Rules that keep it true:
+
+- randomness only from `ctx.random()`;
+- iterate in a fixed order (`Object.keys` of objects you built in a fixed order, arrays, the entity
+  list) and never depend on timing;
+- round what you store with `Math.fround` when it comes from `Math.sin`, `Math.cos`, `Math.atan2` or
+  `Math.exp`: their last bit may differ between Genex's servers and the local one, and float32
+  hides that difference, as the wire does.

package/templates/skills/genex-authoritative-multiplayer/references/physics.md

@@ -0,0 +1,150 @@
+# Server physics: crates, balls, doors
+
+A room module can ask Genex's servers to simulate rigid bodies — crates that topple, a ball that
+bounces off cars, doors on hinges — with the Genex Physics core. The server alone steps them. Every
+client only **draws** them: at the server's present, smoothed when a correction arrives. A client
+never moves a body itself.
+
+**New, and not on Genex's servers until the release that carries the physics core is deployed.**
+`genex-authority-dev validate` runs a physics module on that same core; a validator without it fails
+`physics_unavailable` (update `@genex-ai/authority-dev`). Until the servers run it, a game that must
+ship today keeps to presets and projectiles ([presets.md](presets.md),
+[projectiles.md](projectiles.md)).
+
+Reach for physics when things must collide with each other: a stack, a pile, a ball between cars
+and walls, a door a player shoves. A player's own movement stays a preset, so it is predicted and
+feels instant; a lone flying shot stays a projectile.
+
+## Asking for it
+
+```js
+config: {
+  tickHz: 60,
+  preset: { name: "vehicle", params: { radius: 50, height: 36 } },
+  physics: { subscribe: ["ball"], player: { events: true } },
+},
+```
+
+`physics: true` takes every default. The keys:
+
+| Key | Default | What it is |
+|---|---|---|
+| `lengthUnit` | 100 with `vehicle`, 39.37 with `firstperson`, else 1 | Your units per metre. |
+| `gravity` | The preset's `gravity`, else 9.81 × `lengthUnit` | Units/s² along −z. |
+| `iterations` | 4 | Solver iterations, 1 to 16. |
+| `limits` | The defaults below | Lower any limit; higher ones are clamped. |
+| `subscribe` | `[]` | Up to 8 physics kinds whose body states `ctx.physics.body(key)` returns. |
+| `player` | `{ events: false }` | `events: true` reports the players' hulls touching bodies. A `topdown` room also gives `radius` and `height` here, or its players have no hulls. |
+
+Any other key is a bad config. A room's limits: 512 bodies, 64 joints, 16 bodies with continuous
+collision (`ccd`), 64 queries a tick, 64 events a tick, at most 256 commands a tick.
+
+## A body is an entity
+
+Every body belongs to one entity with the same id. Spawn the entity, then its body:
+
+```js
+init(ctx) {
+  ctx.entities.spawn({ id: "ball", kind: "ball", z: 92 });
+  ctx.physics.spawn({
+    key: "ball", kind: "ball", type: "dynamic", ccd: true,
+    pose: { p: { x: 0, y: 0, z: 92 }, q: { x: 0, y: 0, z: 0, w: 1 } },
+    colliders: [{ key: "ball", shape: { kind: "sphere", radius: 92 }, restitution: 0.65 }],
+  });
+  return {};
+},
+```
+
+- **Ids**: 1 to 64 of `A-Z a-z 0-9 _ . : -`, never starting `static:`. Ids the room makes up
+  (`e1`, `e2`, …) qualify. A body's `kind` (`"ball"`, `"crate"`) is its own, 1 to 32 of the same.
+- **The server writes a body entity's `x y z`, orientation and velocities.** Your module must never
+  write those fields on a body entity: the write throws. Every other field is yours: `kind`,
+  `owner`, `hp`, `data`, `epoch`.
+- **A teleport** (a kickoff, a respawn): `ctx.physics.setPose(key, pose, { resetVelocity: true, wake: true })`
+  and bump the entity's `epoch` in the same tick, so every client snaps instead of sliding there.
+- **Removing** the entity removes its body. `ctx.physics.remove(key)` removes only the body.
+- A player's own entity never gets a body, and a projectile never does.
+
+Vectors are `{ x, y, z }` and rotations `{ x, y, z, w }`. Shapes: `box` (`half`), `sphere`
+(`radius`), `capsule` (`halfHeight`, `radius`, `axis`), `hull` (`points`), `trimesh` and
+`heightfield` (fixed bodies only).
+
+**Put a body's origin at its centre of mass.** Clients extrapolate a body's origin by its centre's
+velocity, so a spinning body whose colliders are offset from its origin is drawn off until the next
+update. Swing a door by posing its middle around the hinge, or join it to the world with a hinge
+joint, rather than giving it an offset collider.
+
+## Commands, queries, events
+
+Commands take effect in this tick's step, and every hook may call them (`init` too):
+
+| Call | Does |
+|---|---|
+| `ctx.physics.spawn(desc)` | Adds a body to an existing entity. |
+| `ctx.physics.remove(key)` | Removes the body; the entity stays. |
+| `ctx.physics.impulse(key, j, at?)` | A push, in mass × units/s. |
+| `ctx.physics.setVelocity(key, linvel?, angvel?)` | Sets a dynamic body's velocities. |
+| `ctx.physics.setPose(key, pose, options?)` | Moves it (bump the epoch with it). |
+| `ctx.physics.setNextKinematicPose(key, pose)` | Where a kinematic body (a lift, a door you drive) is at the end of this tick. |
+| `ctx.physics.addJoint(desc)` / `ctx.physics.removeJoint(key)` | Hinges, sliders, ropes; `b: null` is the world. |
+| `ctx.physics.setMotor(jointKey, motor)` | Drives a joint. |
+| `ctx.physics.areaPush(center, radius, strength, falloff, groups?)` | An explosion. |
+| `ctx.physics.wake(key)` / `ctx.physics.sleep(key)` | |
+
+Each returns its command number, or `'invalid-key'` for a bad id. A command the core refuses
+changes nothing and is listed next tick in `ctx.physics.refused` (`{ n, code }`). It is never a
+fault.
+
+Queries (`ctx.physics.ray`, `ctx.physics.shapeCast`, `ctx.physics.overlap`) return an index; the
+answer is `ctx.physics.answers[index]` on the **next** tick. Queries throw in `init`.
+
+What the last step did: `ctx.physics.events` (`contactBegin`, `contactEnd`, `triggerEnter`,
+`triggerExit`, for colliders with `events: true`), `ctx.physics.escaped` (ids whose bodies left the
+world; the server removed those entities), and `ctx.physics.body(key)` (`{ p, q, v, w, sleeping }`
+for a subscribed kind).
+
+## Players push bodies
+
+With `firstperson` or `vehicle` (or `topdown` with `player.radius` and `player.height`), each
+player's own entity carries a hull the server moves with it. Hulls push dynamic bodies; bodies never
+block a player, who still moves only through the preset's world. With `player: { events: true }`,
+`contactBegin` events name the player's entity id, so a module sees who touched the ball:
+
+```js
+for (const ev of ctx.physics.events) {
+  if (ev.kind !== "contactBegin" || (ev.a !== "ball" && ev.b !== "ball")) continue;
+  const car = ctx.entities.get(ev.a === "ball" ? ev.b : ev.a);
+  if (car && car.kind === "car") ctx.state.lastTouch = car.owner;
+}
+```
+
+## Drawing bodies on the client
+
+Nothing to set up: `connectAuthority` joins physics rooms and draws bodies. In
+`session.entities()`, a body has `body: true`, its orientation in `qx qy qz qw` (z up) and `sleep`.
+Its `x y z` are already where the server has it now: extrapolated past the last update, never
+100 ms behind like other players. A correction eases out over about 100 ms, and a jump over one
+metre (or an `epoch` bump) snaps. With three.js, z up becomes y up for both:
+
+```ts
+mesh.position.set(e.x, e.z, -e.y);
+if (e.body) mesh.quaternion.set(e.qx, e.qz, -e.qy, e.qw);
+else mesh.rotation.set(0, e.yaw, 0);
+```
+
+A body far from the player may update less often: each player gets the 100 nearest awake bodies
+every update and the rest in turns. A body that has not updated for a while is held where it was.
+
+## Costs and limits
+
+The server measures physics time apart from your module's. A tick over 8 ms per 1/60 s of game
+time, or an average over 1 ms per 1/60 s, is a strike; the third ends the room. At 120 Hz a tick
+gets a 60 Hz tick's 8 ms and 1 ms average, and the room counts twice toward the server's capacity. Asleep bodies cost
+almost nothing, so let piles settle: `canSleep` is on by default.
+
+## Testing
+
+`npx genex-authority-dev validate --module server/room.js` fuzzes a physics module like any other,
+on the physics core. Play it at a real ping (`--latency 75`) and judge it there, not at zero: a
+fast ball drawn from the server is a little behind the moment a car hits it, by about the one-way
+latency, and one that bounces off a wall is drawn a little into it before it comes back.