@genex-ai/multiplayer 0.17.1 → 0.17.8

package/README.md

@@ -213,7 +213,9 @@ self-heal on the next publish, and lost `send()` events / inputs are counted in
 Render `reconnecting`/`reconnected` as an overlay and keep your loop running. `disconnect` is terminal
 (server restart, revoked session `4401`, or the link never recovered `4003`): read a fresh token and
 `connect()` again. A deliberate `leave()` never reconnects. The relay also broadcasts `server:restart` right before
-a deploy — flush saves when you see it.
+a deploy — flush saves when you see it. An authority session (`connectAuthority`) does more: a deploy or a dead server
+moves its seat to a fresh room by itself, on the same session object, saying `draining`, `rejoining` and `rejoined`
+(PROTOCOL.md §17.13), and its `disconnect` means it is over for good.
 
 **One seat per player:** the relay enforces a single session per identity per room — a
 second tab / device / reloaded page supersedes the previous session (old one gets
@@ -605,6 +607,288 @@ for (const e of JSON.parse(drainEventsJson(h))) { /* { type: 'playerJoined', id
 Pages with no bundler load `dist/bridge.global.js` (the SDK and embed-sdk bundled in), which sets
 `window.GenexMultiplayerBridge`. A JS game should use the SDK directly, not the bridge.
 
+*(0.17.3, contract version 2)* A server-authoritative game (below) drives its room through the
+bridge's authority calls instead — `openAuthority`, `setInput`, `predictProjectile` (your shot, drawn
+the frame you fire it; `''` without a seat or while it reconnects), `setWorld` (a `firstperson` or
+`vehicle` room's collision world, 0.17.4), `frame` (your predicted entity and every other one,
+interpolated, as one JSON string per render frame), `authorityJson`,
+`drainAuthorityEventsJson`, `closeAuthority`, `disposeAuthority` — from
+`@genex-ai/multiplayer/bridge/authority`, or on a page from `dist/bridge-authority.global.js`, which is
+`bridge.global.js` plus these calls (a relay game keeps loading the smaller script).
+
+```js
+const h = GenexMultiplayerBridge.openAuthority(JSON.stringify({ gameId: 'my-game', urls: [] }));
+// every render frame:
+GenexMultiplayerBridge.setInput(h, JSON.stringify({ moveX: 1, moveY: 0, yaw: aim, buttons: 0 }));
+const { me, entities } = JSON.parse(GenexMultiplayerBridge.frame(h));
+for (const e of JSON.parse(GenexMultiplayerBridge.drainAuthorityEventsJson(h))) { /* joined, message, … */ }
+```
+
+## Server-authoritative rooms — `@genex-ai/multiplayer/authority` *(0.17.2; firstperson, vehicle and projectiles 0.17.4)*
+
+Protocol 4 ([`PROTOCOL.md` §17](./PROTOCOL.md#17-authority-rooms-protocol-4)): the server runs the
+game's own room module at a fixed tick, clients send typed input and render what the server writes.
+Use it when cheating matters (competitive play); everything above is the relay and is unchanged by it.
+Genex's authority servers serve these rooms in production (Asia, EU and US); `npx genex-authority-dev start` serves the same module locally.
+
+```ts
+import { connectAuthority } from '@genex-ai/multiplayer/authority';
+import * as genexEmbed from '@genex-ai/embed-sdk';
+
+await genexEmbed.waitForPlayer();
+const s = await connectAuthority({
+  urls: genexEmbed.getAuthorityUrls(),       // the authority cluster, NOT getColyseusUrls()
+  regions: genexEmbed.getAuthorityRegions(), // its regions: the nearest is joined (PROTOCOL.md §17.1)
+  room: 'my-game',
+  auth: () => genexEmbed.getColyseusAuth(),
+});
+
+function loop(now: number) {
+  s.input.moveX = right - left;              // [-1, 1]
+  s.input.moveY = up - down;
+  s.input.yaw = aimAngle;                    // radians
+  s.input.buttons = firing ? 1 : 0;          // your bitmask, < 2^24
+  s.frame(now);                              // FIRST: sends due inputs, predicts, interpolates
+  const me = s.me();                         // your entity, predicted (no input delay)
+  for (const e of s.entities().values()) draw(e.id, e.x, e.y, e.yaw);   // others ~100 ms behind
+  requestAnimationFrame(loop);
+}
+requestAnimationFrame(loop);
+s.on('hit', (data) => flash(data));          // events your room module emits
+```
+
+- **Input, not state.** `s.input` is sent once per fixed step (the room's tick rate) while you call
+  `frame()`; nothing is sent while you do not. There is no heartbeat.
+- **Prediction.** When the room runs a movement preset (`topdown`, `firstperson` or `vehicle`), your own entity
+  moves the instant you press, with the same step the server runs, and is corrected smoothly when the
+  server disagrees.
+  Pass `predict: { step, fields }` for your own step, or `predict: false` to render the server's state.
+  When your entity respawns (its `epoch` changes) it snaps to the server's new pose and keeps the
+  inputs still in flight, which the server applies to the new life, so moving through a death costs no
+  correction. `s.telemetry` counts `inputsSent`, `inputsDropped`, `reconciles`, `visibleCorrections`
+  (a move of your place past 5 cm: 0.05 × the room's `lengthUnit`, else the preset's implied unit), `peakCorrection`
+  (the largest such move, room units; velocity and angles are never in it), `peakStateCorrection` (the largest
+  correction of any other mirrored field, each in its own unit: only zero or not says anything) and `reseeds` (respawns of your entity and reconnects, never counted
+  as corrections). `s.prediction` says whether your entity is predicted right now, and why not
+  (`off`, `no_entity`, `no_preset`, `world_mismatch`).
+- **`firstperson`** ([§17.7](./PROTOCOL.md#177-movement-presets)) is Source-engine movement through a
+  static world of boxes and ramps, z up: friction, ground and air acceleration (air-strafing), jump,
+  duck and crouch-jump, a free step up ledges, staying on the ground down slopes and stairs, sliding
+  along walls; a ramp too steep to stand on is a wall. Ask for `tickHz: 60`: air-strafing turns the
+  wish direction once per input, so at 30 Hz a perfect strafe gains less than half of what it does at
+  60 (sub-steps do not change that). Send `moveX`/`moveY` in WORLD axes (turn your
+  camera-relative keys by your view yaw yourself; the step has no trigonometry), `yaw`/`pitch` as the
+  aim, and jump / duck / walk on `buttons` (1, 2, 4 by default). Give the session the module's world —
+  `connectAuthority({ …, world })` or `s.setWorld(world)` before the first `frame()` — the same
+  `{ boxes: [[minX, minY, minZ, maxX, maxY, maxZ], …], ramps: [[…, axis, lo, hi], …] }` the module
+  exports: it is validated (`WorldError` when §17.7 refuses it) and hashed, and your entity is
+  predicted only while that hash is the room's `params.world`. Otherwise it renders from the server's
+  state, and `s.prediction.reason` is `world_mismatch`. Entities then also carry `pitch` (within the
+  preset's ±`pitchLimit`), `duck` (0 standing .. 1 ducked; derive the eye height from it), `mstate`
+  (`MoveState` bits: 1 onGround, 2 ducking, 4 jumpHeld) and `cap` (the speed multiplier the module
+  writes: a ceiling on the speed, never a weaker push, so a wound cannot freeze a player), predicted
+  for yours and interpolated for others. `firstpersonWorld(spec)` validates and
+  hashes a world, and `stepFirstperson` is the step itself.
+- **`vehicle`** ([§17.7](./PROTOCOL.md#177-movement-presets)) is an arcade car on Rocket League's
+  ground and air handling, kept level (no pitch or roll): throttle, braking and coasting, boost from a
+  fuel tank, grip that turns the velocity with the heading (`driftGrip` while drift is held, so the
+  tail slides), a turn rate that grows with speed up to `turnSpeed` and mirrors in reverse, a jump and
+  steering in the air. It drives the same hull through the same world as `firstperson` (walls clip
+  the velocity along them, nothing bounces), so it takes the same `world` / `setWorld` and predicts
+  only while the hashes match. Axes: x/y is the ground, z is up, and `yaw` is the heading,
+  counterclockwise seen from above (+yaw turns left; yaw 0 faces +x). The heading is the BODY's
+  state, not input: send `moveY` as the throttle (below 0 reverses) and `moveX` as the steer, where
+  **+1 turns right, toward −yaw** (your steer-right key is `moveX = +1`, as for any other right input),
+  and jump / boost / drift on `buttons` (1, 2, 4 by default); `yaw`, `pitch` and `moveZ` are unused.
+  Ask for `tickHz: 60`. Entities then also carry `spin` (the yaw rate, rad/s, positive toward +yaw:
+  for wheels and skid marks) and `fuel` (the tank, 0..1), predicted for yours and the server's latest
+  for others; your own heading draws along the short arc across ±π. The module writes `fuel` to
+  refuel (a boost pad, a respawn: `fuel: 1, spin: 0, mstate: 0` with an `epoch` bump) and `cap` to
+  scale both top speeds; the step only burns fuel. `stepVehicle` is the step itself. It turns the
+  heading with `psin` / `pcos`, §17.7's portable sine and cosine (exported here), which every engine
+  computes to the same bits; the platform's `Math.sin` / `Math.cos` differ in the last bit between
+  engines and would desynchronize prediction.
+- **Entities** carry `kind`, `owner`, `x y z yaw` (rendered), `vx vy vz`, `hp`, `flags`, `epoch`,
+  `data` (JSON text), the projectile fields `t0`, `g`, `src`, the firstperson fields `pitch`,
+  `duck`, `mstate`, `cap` and the vehicle fields `spin`, `fuel`. A changed `epoch` is a teleport: it snaps, never glides. Another player's snap
+  lands when its render time (100 ms behind) reaches the bump, the time lag compensation judges a shot
+  at; until then it is drawn where it was, and `epoch` reports the life drawn.
+- **Projectiles** ([§17.9](./PROTOCOL.md#179-projectiles)) are entities with a launch tick `t0 > 0`,
+  a gravity `g` and their shooter's seat `src` (`''` for a server one). Each is drawn from its
+  closed-form flight (`projectileAt`), never interpolated: another player's at the server's present,
+  not 100 ms behind. Fire your own with `s.predictProjectile({ kind, x, y, z, vx, vy, vz, g })` while
+  staging the input that fires: it is drawn that same frame under the id the room module's launch
+  gets (`<seat>.<seq>.<n>`), keeps that id when the server's projectile confirms it, and flies on
+  from where the prediction was; one the server re-launches as its own (a bounce) is drawn at the
+  server's present from then on. One no state ever shows (refused, or removed by a hit before a patch
+  carried it) is dropped as soon as the server acknowledges the input that fired it, one whose input
+  a drop lost at the reconnect's first state (the next shot reuses its id), and at the latest after
+  max(2·RTT, 600 ms). While the socket is down (`reconnecting` until `reconnected`) it predicts
+  nothing and answers `''`: no input goes out then. Every client in a room that launches projectiles must implement §17.9: an
+  older one draws each projectile frozen at its launch point.
+  A projectile is never `me()`. `s.telemetry` counts `projectilesPredicted`, `projectilesConfirmed`,
+  `projectilesRejected` and the latest `lastProjectileLeadMs`. The module side is
+  `ctx.projectiles.launch / at / sweep`.
+- **Physics rooms** ([§17.10](./PROTOCOL.md#1710-physics)): the server simulates rigid bodies and
+  this session draws them; nothing on the client steps physics. Every join sends the `physics@1`
+  capability, which a physics room requires (426 without it). A body entity (one with a descriptor in
+  the state's `bodies`) comes out of `entities()` with `body: true`, its drawn orientation in
+  `qx qy qz qw` (z up) and the server's `sleep` flag; its `x y z` are the server's present, not
+  100 ms behind: the latest state (the body at the patch's tick + 1) extrapolated on the room clock
+  by its velocities (at most 250 ms, back a tick at most before its tick, not at all while asleep), and a newer state eased in from where
+  the older one was drawn (the offset decaying as e^(−age / 100 ms)). An `epoch` bump, a correction
+  over one metre or a body's first state snaps. A body out of this client's view is still listed,
+  held at its last state, until its descriptor goes. `vx vy vz` on a body are its linear velocity in
+  room units/s. `s.telemetry` counts `bodyStates`, `bodySnaps` and `peakBodyCorrection`. The drawing
+  is `physics-draw.ts` (`bodyStateOf`, `extrapolateBody`, `receiveBodyState`, `drawBody`), held to
+  the netcode bench's `physics-draw.json` vectors. A body entity is never `me()`. The module side is
+  `config.physics` and `ctx.physics` (commands, queries answered next tick, events, `body(key)` for
+  subscribed kinds); the wire and the reference tables are `wire.ts` and `physics.ts`. Genex's authority
+  servers run these rooms on the pinned core. `s.setPhysics(hash)` (or `connectAuthority({ …, physics })`)
+  names a physics world your client runs a copy of; `s.physics.reason` is `physics_mismatch` while the
+  room's hash differs.
+- **Physics prediction** ([§17.11](./PROTOCOL.md#1711-physics-prediction)): give the session the core,
+  `connectAuthority({ …, world, physicsCore: async () => { const p = await import('@genex-ai/physics');
+  await p.init(); return p; } })`, and in a predicting room (the default for physics rooms) it steps the
+  bodies near you in a world of its own and draws them at your present (`predicted: true` on their
+  view); the core loads only once the room sends keyframes, and `wasmSimdSupported()` says when to pass
+  the non-SIMD module instead. `predictPhysics: false` turns it off; `s.physicsPrediction` reports
+  `status` (`on`, `off`, `loading`, `unavailable`, `mismatch`, `self_test`, `diverged`, `cpu`), how
+  keyframes were adopted, the slowest and latest replay and how many held a 60 Hz frame back
+  (`peakResimMs`, `lastResimMs`, `slowResims`), and how often the replay budget fell back to `cpu` and came back
+  (`fallbacks`, `recoveries`: `cpu` probes a replay every 500 ms and turns prediction on again after
+  four calm ones). The budget is the device's (4 ms desktop, 5 mobile); `physicsBudgetMs` overrides it
+  when it is a finite number over 0 (benches and CI on a slow host; a game leaves it unset). Remote players move by their velocity or, in a room asking
+  `remotePredict: 'inputDecay'`, by their last input repeated with decay (`'hold'`: held). Module commands are not
+  predicted, except the rules the module writes as pure functions and hands the client too:
+  `contacts(a, b)`, a seat contact rule (a car-to-car bump) run in your own entity's prediction
+  against the other seats, and `bodyRule({ tick, seats, body })`, a body rule (a scripted hit on a
+  ball) run before every step of the client world, and `kinematicRule(key, tick)`, where the module
+  poses its kinematic bodies (a door, a moving floor) at each tick, so the client world moves them as
+  the room does and draws them as predicted bodies (and by the rule on the server's timeline whenever
+  it does not predict them: no core, `cpu`); the module must run the same functions. Held to
+  the netcode bench's `physics-predict.json` (tolerance 0 on the client stateHash) and
+  `seat-contacts.json`. With `contacts`, `seatDrawing` chooses how other seats are drawn:
+  `predicted` (default, the Rocket League model) on your car's clock, every other seat stepped by the
+  room preset under its last input (`remotePredict: 'hold'` holds it) with the module's whole contact
+  pass (`contactPass`, else `contacts` on every pair) run on every seat and yours, each correction
+  eased in as a decaying offset that keeps the drawn velocity and never pulls a seat back against its
+  motion (`drawTick()`, `drawLead()` say where they were drawn); `separate` on
+  the render timeline but moved out of your drawn entity by the rule and taken round it, never across
+  it (draw-only); `timeline` on the render timeline only (a seat that missed yours on the server can
+  be drawn through it). `predicted` and `separate` keep every seat out of yours and out of each other
+  ([§17.11 *Drawing other seats*](./PROTOCOL.md#1711-physics-prediction)). A room whose module
+  declares `config.contacts` (the universal contact policy: a genre preset such as `shooter` or
+  `vehicle-arena`, a contact shape and per-pair rules by tag, §17.11 *Contact policy*) needs no
+  `contacts` or `contactPass`: given neither, the session runs the declared policy the state carries
+  as both, in your prediction, the seat prediction, the physics replay and the drawing guard. The
+  authority host runs the same pass on the server after each tick's preset steps and before the
+  module's `step`, so the module writes no contact code at all (and must not run a pass of its own).
+- **Letting a held body go.** A module that holds a body with `cap` 0 and lifts it unannounced lifts it for inputs on their
+  way, so a held stick lurches by about speed × round trip. Announce the tick (a countdown does anyway) and give the session a
+  `seatRule` that sets `cap` on it (§17.11 *Seat rules*): every seat starts on one tick, and no correction, measured on UDP.
+- **Input repeat** is a room setting ([§17.11 *Input pacing*](./PROTOCOL.md#1711-physics-prediction),
+  *The setting*): `config.inputs: { preset?, repeat?, settleMs? }` (`settleMs`: §17.11 *A quiet seat*), `repeat` (`'on'` or `'off'`) as given, else
+  the genre preset's (`inputs.preset`, else `config.contacts.preset`), else on; `vehicle-arena` is off,
+  `shooter`, `platformer`, `party` and `physics-sandbox` on (`INPUT_PRESETS`). On, a starved seat's
+  held input is repeated and the session compares your prediction at
+  `reconcileThrough(held, ack, inRep, sent)` (`ack + inRep` once sent; past the inputs sent, a hitch,
+  it waits at the input it compared at last) and throttles after a starve; off, the room holds a starved seat
+  and the session reads the plain ack and never throttles. The session reads the room's setting from
+  the state's preset text (`presetInputRepeat`); a bad `config.inputs` is refused by its path.
+- **Reconnection** is automatic and in place, as for `connect()`; `reconnecting`, `reconnected` and
+  `disconnect` fire as there. An input that came due while the socket was down is dropped, never
+  replayed. `leave()` during an outage still leaves: it stops reconnecting, and a retry already under
+  way leaves the moment it lands.
+- **The fast channel** ([§17.12](./PROTOCOL.md#1712-the-fast-channel-fast1)), on by default: over UDP for Node
+  clients (bots, the netcode bench, tests) and over WebTransport in a browser, with nothing to pass.
+  `connectAuthority({ … })` asks for `fast@1`, `fast: false` turns it off,
+  and `openUdpFastSocket` from `@genex-ai/multiplayer/authority/fast-udp` is there to wrap. One line per join
+  names the transport and any fallback (`session.fast.line`; stderr, or `fastLog`). In a room that
+  offers it your inputs go by UDP datagram, each one in several (a lost datagram costs nothing), and the
+  room's motion comes back as per-seat ack-delta snapshots written into the same state a patch writes,
+  so prediction, reconcile and interpolation run unchanged; a WebSocket held up by a lost TCP segment
+  no longer holds them. Join, events and the rest of the state stay on the WebSocket. The seat moves only
+  once the path is proven, with the WebSocket carrying everything until then, so a network that blocks UDP
+  loses no input. With no snapshot 1 s after the first datagram or 2 s after the last, a binding it cannot
+  use, or the server's `__fast:off`, the seat goes on by WebSocket, every input sent stepped once and every
+  motion field at the WebSocket's latest value, and comes back by itself when the path does (retrying from
+  1 s up to every minute, with jitter). A seat with nothing to send keeps its channel with an empty datagram
+  every 250 ms, and a NAT rebinding or a Wi-Fi to mobile move keeps it on UDP. `s.fast` says `live`,
+  `snapshots`, `fallbacks`, `returns` and `fallback`: why the seat is on the WebSocket now (`no-webtransport`,
+  `no-relay`, `not-offered`, `unreachable`, `handshake`, `stall`, `server`). A room without the channel plays
+  exactly as before.
+- **Lag compensation.** Every input tells the server what you saw: other entities `renderDelayMs`
+  (default 100) in the past, whether or not your own entity is predicted.
+- **Every server message** also reaches `onEvent(type, data)` when you pass it, in order and with no
+  name withheld (`on(type)` skips the session's own event names) — for a facade forwarding them all.
+- **Refusals** reject `connectAuthority` with the server's error; branch on `err.code` (`JoinError`):
+  402 the game's owner is not entitled to authority rooms (final; not retried), 424 no room module is
+  published, 429 the owner's room quota refused a new room, 426 this package is too old for the
+  server (update and republish). 503 (no capacity) is retried after 1, 2 and 4 s (`capacityRetryMs`).
+
+A game's server code is one module typed by `@genex-ai/multiplayer/authority/module`, which has no
+dependencies so it can be bundled alone:
+
+```ts
+import { defineRoom } from '@genex-ai/multiplayer/authority/module';
+
+export default defineRoom({
+  contract: 1,
+  config: { tickHz: 30, preset: { name: 'topdown' } },
+  init: () => ({}),
+  onJoin: (ctx, player) => { ctx.entities.spawn({ kind: 'player', owner: player.id }); },
+  onLeave: (ctx, player) => { const e = ctx.entities.ownedBy(player.id); if (e) ctx.entities.remove(e.id); },
+  onInput: () => {},
+  step: () => {},
+});
+```
+
+A `firstperson` room exports its collision world beside its config; the server validates it at init
+and writes its hash into the resolved preset's `params.world`, and the game client passes the same
+world to `setWorld`:
+
+```ts
+import { defineRoom } from '@genex-ai/multiplayer/authority/module';
+import world from './world.json';            // { boxes: [[…6], …], ramps: [[…9], …] }, shared with the client
+
+export default defineRoom({
+  contract: 1,
+  config: { tickHz: 60, preset: { name: 'firstperson' } },
+  world,
+  init: () => ({}),
+  onJoin: (ctx, player) => { ctx.entities.spawn({ kind: 'player', owner: player.id, z: 0 }); },
+  onLeave: (ctx, player) => { const e = ctx.entities.ownedBy(player.id); if (e) ctx.entities.remove(e.id); },
+  onInput: () => {},
+  step: () => {},
+});
+```
+
+A `vehicle` room exports its world the same way, and refuels on a respawn:
+
+```ts
+import { defineRoom } from '@genex-ai/multiplayer/authority/module';
+import world from './arena.json';            // the floor, walls and ramps, shared with the client
+
+export default defineRoom({
+  contract: 1,
+  config: { tickHz: 60, preset: { name: 'vehicle' } },
+  world,
+  init: () => ({}),
+  onJoin: (ctx, player) => { ctx.entities.spawn({ kind: 'car', owner: player.id, z: 0, fuel: 1 }); },
+  onLeave: (ctx, player) => { const e = ctx.entities.ownedBy(player.id); if (e) ctx.entities.remove(e.id); },
+  onInput: () => {},
+  step: () => {},
+});
+```
+
+### A level as a world: `@genex-ai/multiplayer/world-fit`
+
+A world for `firstperson` or `vehicle` from a real level, at build time: `readGltfLevel(path)` reads a glb or glTF and
+`sceneFromThree(scene)` (`@genex-ai/multiplayer/world-fit/three`, no Node in it) reads a three.js scene, both into the same scene
+file ([WORLD-SCENE.md](WORLD-SCENE.md)) for `genex world fit`. Node names or `extras.genex` say what collides, on which channel and
+where a spawn is; a file is hostile input and a refusal names what to change: [WORLD-GLTF.md](WORLD-GLTF.md).
+
 ## Rules of thumb
 
 - **`me` / `shared` are synced; everything else is local.** Movement input → mutate a local object → `me.set` it on the tick.

package/WORLD-GLTF.md

@@ -0,0 +1,109 @@
+# A level from a glb, a glTF or a three.js scene
+
+Two doors to the same [scene file](WORLD-SCENE.md), so a level from any engine with a glTF exporter reaches `genex world fit`:
+
+```sh
+genex world gltf level.glb level.scene.json    # no flags: a level says what it needs in its own extras
+```
+
+```ts
+import { sceneFromThree } from "@genex-ai/multiplayer/world-fit/three";
+const { json, notes } = sceneFromThree(gltf, { scale: 39.37 });   // a THREE.Scene, an Object3D or what GLTFLoader gave you
+```
+
+One level gives one scene by either door: `packages/netcode-bench/test/authority/world-gltf-three.test.ts` holds a level
+through `GLTFLoader` and `sceneFromThree` to the reader's scene, value for value. Same file, same bytes and hash on Mac, Linux
+and Windows (`world-gltf.yml`). Library: `readGltfLevel(path)` and `runWorldGltf(args)` in `@genex-ai/multiplayer/world-fit`. `genex world gltf` exits 0, 1 on a call
+that is not one and 3 on a refused level, as `genex world fit` does.
+
+## Space and units
+A glTF is metres, y up, right-handed. A three.js scene is y up too. Everything comes out in the room's axes, z up, handedness
+kept: drawing space `(X, Y, Z)` is the room's `(X, −Z, Y)`, the same turn as drawing a room's body at `(x, z, −y)`. Coordinates land
+on a grid of 1/256 of a unit, then float32, so no path to a number shows.
+
+- **The reader** scales metres by `unitsPerMeter`, 39.37 (Source units) unless the glTF scene's `extras.genex.unitsPerMeter` says
+  otherwise. A game in metres sets it to 1.
+- **The helper** scales by its `scale` option, default 1: a game that draws the server's numbers as they are. A model loaded in
+  metres and not scaled in the scene is `{ scale: 39.37 }`; a model with `model.scale.setScalar(39.37)` is already there.
+- **Hull**: `extras.genex.hull` on the scene (`radius`, `height`, `crouchHeight`, `step`, `jump`, `leap`, room units). Left out, the
+  fit sizes the Source defaults from `unitsPerMeter`. Make it your room's own parameters if they differ.
+
+## Marks
+A mesh collides, on both channels, unless it is marked. Any exporter can say all of these in a node's name; Blender, three.js and
+anything that writes custom properties can say them in `extras.genex` (`userData.genex` in three.js), and those win. A parent passes
+its mark to what hangs under it; a child's own mark wins.
+
+| Name starts with | `extras.genex` | Meaning |
+|---|---|---|
+| | | Collides: stops a hull and a bullet |
+| `nocol_` | `{ "collide": "none" }` | Only drawn: art beside a collision proxy, a sky dome, a banner, a character |
+| `clip_` | `{ "collide": "move" }` | Clip wall: stops a hull, a bullet passes |
+| `shot_` | `{ "collide": "shot" }` | Stops a bullet, a hull passes |
+| `box_` | `{ "shape": "box" }` | Its bounds as one box |
+| `hull_` | `{ "shape": "hull" }` | The convex hull of its points, up to 4,096 |
+| | `{ "shape": "mesh" }` | Triangles, no box looked for |
+| `movable_` | `{ "movable": true }` | Moves or disappears at run time: named in the fit's report, never in the world |
+| `prop_` | `{ "prop": true }` | May be cut when a budget runs out |
+| `spawn_` | `{ "spawn": true }` | Where a player starts: the node's origin, on or just over the floor. Its own mesh does not collide. `spawn_Red_1` is the spawn `Red_1` |
+| | `{ "tags": ["red"] }` | Carried to the actor or spawn for the game |
+
+Prefixes stack in any case: `CLIP_box_Fence.001`. A misspelled mark is refused rather than ignored.
+Hidden objects still collide: that is what a collision proxy usually is. Mark what is only for show.
+
+What else it works out, so an exporter never has to:
+- **A closed cube is an exact box**, on the world's axes or turned, even inside a merged mesh, and under negative scale. A cube
+  sheared by a non-uniform parent is the exact hull of its corners. A cube flattened by a scale of zero is the plane left.
+- **A node an animation moves is movable**, with what hangs under it. In three.js, pass the loaded `gltf`, not `gltf.scene`, so it can see the animations.
+- **An instanced mesh is every instance** (`EXT_mesh_gpu_instancing`, `THREE.InstancedMesh`). **An LOD is its nearest level.**
+- **Quantized positions** (`KHR_mesh_quantization`) read as the numbers they mean. **Strips and fans** are triangles; points and lines are no surface.
+
+## Refusals
+A file is hostile input. Every refusal is a `LevelRefusal` with a `code` and a message naming the node or field and what to do; the
+scene is not written and an existing one stays. The reader's table is `packages/multiplayer/test/world-gltf-hostile.test.ts`.
+
+| Code | What it says |
+|---|---|
+| `not_gltf`, `bad_container`, `bad_version` | Not a glb or glTF 2; chunks that do not add up |
+| `bad_reference`, `bad_accessor`, `bad_index`, `bad_value`, `not_finite` | An index naming nothing; an accessor that does not fit or is sparse; an index past its vertices; a bad transform; NaN or infinity |
+| `node_cycle` | A cycle, or a node with two parents |
+| `too_large` | Past a limit below |
+| `compressed` | Draco (`KHR_draco_mesh_compression`) or meshopt (`EXT_meshopt_compression`, `KHR_meshopt_compression`) on something that collides. Not decoded here: re-export without it, or load it in three.js and use `sceneFromThree`, whose loader decodes it. Compressed art marked `nocol_` is no problem |
+| `unknown_extension` | A required extension this cannot honour, by name |
+| `uri_refused` | A buffer URI that leaves the input's folder or is not a plain file: a parent segment, an absolute path, a scheme, a host, a backslash, an encoded trick, a link leading outside (by realpath), a FIFO. Nothing outside the folder is read and nothing touches the network. Image URIs are never read at all |
+| `skinned`, `morphed` | A skinned or morph-posed mesh that collides: a world is static. Mark it `nocol_` beside a static proxy, or `movable_` |
+| `unsupported` | A `THREE.BatchedMesh` that collides |
+| `degenerate` | A mesh with no triangle of any area left. A few among real ones are dropped and counted in `notes` |
+| `non_manifold` | More than 64 triangles on one edge, which no surface has. Ordinary non-manifold edges are kept and counted in `notes`: the scene format reads a surface, open or closed |
+| `no_spawn`, `no_surface`, `bad_mark` | What it says |
+
+Limits, each checked before anything is decoded for it: 1 GiB a file or buffer and for all buffers together, 8,000,000 triangles with
+instances counted, 24,000,000 vertices an accessor, 1,000,000 nodes, depth 1,024. Past them, give what no one walks on a `nocol_` mark
+or a collision proxy.
+
+## The whole path
+```sh
+genex world gltf level.glb level.scene.json          # or write sceneFromThree's json to that file
+genex world fit level.scene.json world.json          # the §17.7 world, and what it cost and changed
+```
+Then the world is one file both sides import: `defineRoom({ …, world })` in the module, `connectAuthority({ …, world })` on the
+client. Draw the glb as it is, in the same units: the world is made from it, not drawn. A spawn from the scene is where `onJoin` puts a seat.
+
+`packages/netcode-bench/demo/level-walk/` is this path on a real page: `courtyard.glb` (`conformance/authority/world-scene/`,
+written by its `courtyard.reference.mjs`), fitted, in a local `genex-authority-dev` room, two three.js seats and a Rust seat walking it.
+`packages/netcode-bench/test/authority/world-gltf-route.test.ts` walks the same routes with no browser.
+
+### three.js in a game
+Run the helper wherever the level already exists. A Node build script needs no browser: `new GLTFLoader().parse(arrayBuffer, "", …)`
+for a glb with embedded buffers, or a `Scene` built in code. In a page, hand a creator the file:
+```ts
+const url = URL.createObjectURL(new Blob([sceneFromThree(gltf, { scale: 39.37 }).json], { type: "application/json" }));
+```
+Do this once, at build time, and import what the fit wrote: never fit or re-export in a player's page, or one float's difference
+turns prediction off (`world_mismatch`).
+
+### Rust, or any engine with a glTF exporter
+1. Export the level as a glb in metres, with the marks above. Blender: *Include > Custom Properties* writes `extras`; names are always kept.
+2. `genex world gltf level.glb level.scene.json`, then `genex world fit level.scene.json world.json`.
+3. Rust: `FirstpersonWorld::from_json_str(include_str!("../assets/world.json"))` and `session.set_world(world)`; the module exports the
+   same file. Draw with `engine = (g.x, g.z, −g.y)`. `sdks/rust/genex-multiplayer/examples/level_walk.rs` does this against a room:
+   hash equal to the room's, predicted, no correction. A game in metres sets `unitsPerMeter` to 1 and every distance in its params.

package/WORLD-SCENE.md

@@ -0,0 +1,135 @@
+# The world scene format
+
+What an engine's exporter writes and `genex world fit` reads: a level as collision surfaces, in world space, with no
+engine in it. Reader and checks: `src/world-fit/scene.ts` (`parseWorldScene`); a small example every exporter can
+compare with: `../netcode-bench/conformance/authority/world-scene/sample.json`. A glb, a glTF or a three.js scene becomes this
+file with no exporter to write: [WORLD-GLTF.md](WORLD-GLTF.md).
+
+Exporters: Unity (`sdks/unity/README.md`, *From a level to a world*).
+
+```json
+{
+  "format": "genex-world-scene",
+  "version": 1,
+  "unitsPerMeter": 39.37,
+  "source": { "engine": "unity", "level": "Yard" },
+  "hull": { "radius": 16, "height": 72, "crouchHeight": 54, "step": 18, "jump": 57, "leap": 189 },
+  "actors": [
+    { "name": "Ground", "surfaces": [
+        { "kind": "box", "center": [0, 0, -16], "half": [2000, 2000, 16] } ] },
+    { "name": "Fence_3", "tags": ["fence"], "surfaces": [
+        { "kind": "box", "center": [100, 40, 44], "axes": [[0.8, 0.6, 0], [-0.6, 0.8, 0], [0, 0, 1]], "half": [32, 2, 44],
+          "channels": ["move"] } ] },
+    { "name": "Rock_1", "tags": ["prop"], "surfaces": [
+        { "kind": "mesh", "vertices": [0, 0, 0, 90, 0, 0, 0, 90, 0, 0, 0, 60], "indices": [0, 1, 2, 0, 1, 3, 1, 2, 3, 2, 0, 3] } ] }
+  ],
+  "spawns": [ { "at": [0, 0, 8], "name": "Red_1", "tags": ["red"] } ]
+}
+```
+
+## Space
+- World space, the room's units, the same axes the game hands the step: **z up**, x and y as §17.7 moves them. An engine
+  with y up converts here, the way it converts everything else it sends the room.
+- `unitsPerMeter` says what a unit is. It sizes the report's areas and, when `hull` is left out, scales the Source
+  defaults. It rescales nothing else.
+- `hull` is the room's own hull: `radius`, `height` (stand), `crouchHeight`, `step`, `jump` (how high a standing jump
+  lifts the feet, `jumpImpulse² / (2·gravity)`) and `leap` (how far a run jump carries, `maxSpeed · 2·jumpImpulse / gravity`).
+  Every tolerance the fit uses comes from these; a scene has no tuning values to set.
+
+## Actors and surfaces
+An actor is what a creator knows by name: a refusal says `Wreck_12`. Write the engine's own name, a path when names repeat.
+Each surface is one of:
+
+| `kind` | Fields | Meaning |
+|---|---|---|
+| `box` | `center`, `half`, `axes?` | An oriented box. `axes` are three orthonormal rows; left out means the world's. A box on the axes stays exact in the fit |
+| `hull` | `points` | The convex hull of up to 4,096 points |
+| `sphere` | `center`, `radius` | |
+| `capsule` | `a`, `b`, `radius` | Any direction |
+| `mesh` | `vertices`, `indices` | Triangles: x y z per vertex, three indices per triangle, wound either way, open or closed |
+| `heightfield` | `origin`, `cell`, `cols`, `rows`, `heights` | `heights[row·cols + col]` at `origin + (col·cell[0], row·cell[1])`, solid below. `null` (NaN in binary) is a hole |
+
+Big arrays may be `{ "f32le": "<base64>" }` (`vertices`, `heights`) and `{ "u32le": "<base64>" }` (`indices`).
+
+Write everything that collides: the fit decides what a hull can reach and drops the rest, so an exporter never prunes.
+
+## Channels
+`channels` on a surface says which traces it answers, and left out means both. `move` stops a hull. `shot` stops a bullet.
+
+| Engine says | Write |
+|---|---|
+| Blocks pawns and traces | leave it out |
+| Clip wall: blocks pawns, not traces | `["move"]` |
+| Shot-only mesh: bullets stop, characters pass | `["shot"]` |
+| Neither | leave the surface out |
+
+`genex world fit` reads `move`, `genex world shots` reads `shot`, from the same file.
+
+## Where a level ends
+`bound` is optional: `{ "min": [x, y], "max": [x, y], "ceiling": z }`, `ceiling` optional. Write it when the level is meant to stop
+somewhere its geometry alone doesn't stop a hull. The fit adds solid of its own, `move` only, named `Bound` in the report and counted
+in the budget: walls outside those edges, tall enough that nothing in the level lifts a hull over, and a lid whose underside is
+at `ceiling`, so a hull's head stays under it. A spawn outside the bound or over the ceiling is refused at its path. Leave it out and
+the level's reach is whatever its geometry gives; the fit doesn't guess where a creator meant it to end.
+
+## Tags
+Free strings on an actor or a surface, carried for the game. The fit reads two:
+- `movable`: moves or disappears at run time. Never in a static world; the report names it.
+- `prop`: may be cut when a budget runs out, as one box a surface, before anything else that costs reach. An exporter tags
+  only what its engine or creator already calls a prop: an actor no wider than eight hull radii counts as one with no tag.
+
+## The shot world
+`genex world shots <scene.json> <shots.json> [--max-boxes <n>] [--max-bytes <n>] [--report <file>] [--json]` writes what a module
+exports as `shotWorld`, `{ boxes, ramps, tolerance }`, or exits 3 and writes none. `fitShotWorld` is the same thing in code. It keeps
+what a muzzle can see from where a hull can be: a surface no hull reaches and a line reaches stays, one no line reaches goes, and that
+is sound on the lattice. A straight line moves one way on each axis, so it stays in the flood of its own octant, which from a yard open
+to the sky does not come back down outside the wall. A source box on the axes stays one box. Anything else gets boxes cut round the
+surface they hold, so a stop is off by less than a cell. The cell is the finest of a ladder (a quarter of the hull's radius, doubling) the
+budget holds. Boxes only: no ramps yet. The report reads rays from where a hull stands, against the source's own triangles: `accuracy`
+(hit or miss, along the ray, and `surface`, how far the fit's stops are from a real surface: along a ray a near miss of an edge
+reads as the whole way to the next wall) and `claims`, what a tolerance is worth by the rule of `ctx.world.claim`: honest claims refused or
+capped, and how far past a real surface the most a claim may say reaches. The world's `tolerance` is `surface` at the 99th percentile.
+It names what moves at run time and what no muzzle sees. It is not fed to any client.
+
+## What `genex world fit` reads and says
+`genex world fit <scene.json> <world.json> [--max-boxes <n>] [--max-ramps <n>] [--report <file>] [--json]` writes the §17.7
+world, or exits 3 and writes none. `@genex-ai/multiplayer/world-fit`'s `fitScene` is the same thing in code. The report gives
+reach lost and extra against the source, how far floors really are from the source's (`floor`: the highest surface under a
+hull's whole footprint, with no cell rounding, at the lattice's points, with the worst ones named), how far walls may recede, how far the reach runs past the level (`reachExtent`, below), the costliest
+actors and, on a refusal, what each would lose as one box. What it models: a square hull walking, stepping, dropping, jumping, crouch jumping and leaping off
+edges. What it does not: a slope a room can't stand on reads as walkable if its steps are, up to a steep one. Steeper, a column a cell
+wide with a face rising a crouching hull's height or more beside it and falling two cells or more on its other side is no floor:
+closed up the face's height and counted in `leanLedges`, so a tall leaning wall is its outer envelope, as wide at its top as at its
+widest, and a true lip under a cell wide goes the same way. Held to leans up to 12 degrees off the vertical; past that a hull can still
+stand on some of a face, because its lips can be a step apart. The floor figures skip the part of that top past the real wall. A door a hull clears by under a
+cell is found on a finer lattice of its own, down to a thirty-second of a cell: open between exact boxes, shut and named in
+`narrowDoorsShut` between walls the fit can't keep exact. The rule for the other way: a gap too narrow for the
+hull in the source never opens, at any rung, and stays shut by `gapMarginUnits`, an eighth of a cell on the radius.
+
+Floors win over budget. Where a coarser rung leaves feet past a radius from the source's floor, repair rounds spend boxes there; if
+feet stay past a radius at worst or half a radius at the 99th percentile, the fit refuses with `floor_over`, writes no world, and
+names who costs the most, as `over_budget` does. `open_slits` is the same for a gap left open: a report with either is never `ok`.
+
+What the floor numbers say, in the scene's units, all against the same reading of the highest surface under a hull's footprint:
+
+| Field | What it is | What can pass it |
+|---|---|---|
+| `floor.p99Units`, `floor.maxUnits` | Source against fit at the lattice's points. These are what the fit holds itself to: half a radius and a radius, or `floor_over` | A real hull rests between lattice points, so a seat's feet can read more than `maxUnits` at an edge, resting on a ledge by a hair |
+| `floor.upperBoundUnits` | The same with the footprint half a cell wider and narrower, which holds every position between the points | Nothing: a seat's feet stay under it. It is a ledge's height wherever a footprint can overlap a ledge by a hair more in one world than the other, so it says little of how a level looks |
+| `floor.edgeFreeUnits` | How far apart the two ranges of height are: nothing if a shift of half a cell can make them read alike | |
+
+So compare a seat's worst feet with `upperBoundUnits`, and its 99th percentile with `p99Units`. A seat over `maxUnits` at an edge rest
+is not a broken fit; a seat over `upperBoundUnits` is.
+
+`reachExtent` says how far the source's reach runs past what the level holds, and is measured whether or not anything is wrong:
+`coreMin` and `coreMax` are the plan of the spawns and every actor but flat ground as wide as the level; `outsideCoreM2` and
+`outsideCorePct` the reach further than a run jump past that, `farthestFromCoreM` how far it gets; `walkedM2` what a hull gets to from
+a spawn with no jump, `beyondWalkPct` the share of the reach only a jump gets to, and `outsideWalkedPct` the share further than a run
+jump past the plan of what walking gets to. `flagged` is true at 25% of either `outsideCorePct` or `outsideWalkedPct`, with no `bound`.
+It never refuses: whether the reach is what the creator meant is theirs to say, with a `bound`.
+
+Spawns are where the hull's reach starts: `at`, with optional `name` and `tags`. A level with no spawn cannot be fitted.
+
+## Compatibility
+`version` is checked and a new meaning is a new version. A reader refuses a bad value with its path (`WorldSceneError`,
+`$.actors[3].surfaces[0].half[1] is below zero`).

package/dist/authority/fast-udp.d.ts

@@ -0,0 +1,15 @@
+import { F as FastSocketOpener } from '../fast-client--A88q0kk.js';
+import '../module-CSpXrzFc.js';
+import '../shot-world-D22tqOUT.js';
+
+/** The host (an IPv6 host unbracketed) and port of a `udp://host:port` url, else null: the url is
+ *  server-supplied, so anything more than a host and a port in 1..65535 is refused. */
+declare function udpEndpoint(url: string): {
+    host: string;
+    port: number;
+} | null;
+
+/** A {@link FastSocketOpener} for `udp://` urls on node:dgram; null for any other url. */
+declare const openUdpFastSocket: FastSocketOpener;
+
+export { openUdpFastSocket, udpEndpoint };

package/dist/authority/fast-udp.js

@@ -0,0 +1,14 @@
+import {
+  udpEndpoint,
+  udpFastOpener
+} from "../chunk-YWQ3ALYY.js";
+
+// src/authority/fast-udp.ts
+import { createSocket } from "dgram";
+import { lookup } from "dns";
+import { isIP } from "net";
+var openUdpFastSocket = udpFastOpener({ createSocket, lookup, isIP });
+export {
+  openUdpFastSocket,
+  udpEndpoint
+};