@irtio/server 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -1,7 +1,168 @@
-import { AnySchema, RoleOf, VisibleKeys, SchemaDefs, EntityDef, ReadonlyCollection, DeepReadonly, InferFields, Owned, SingletonDef, PhysicsKeys, InstanceOf, State, ServerCallProxy, SchemaRpc, BroadcastProxy, OwnableKeys, Implementations, ServerRpcs } from '@irtio/schema';
+import * as _irtio_schema from '@irtio/schema';
+import { SingletonDef, EntityDef, AnySchema, RoleOf, VisibleKeys, SchemaDefs, ReadonlyCollection, DeepReadonly, InferFields, Owned, PhysicsKeys, InstanceOf, State, ServerMessageChannels, ServerCallProxy, SchemaRpc, BroadcastProxy, OwnableKeys, MessageNames, MessageValue, Implementations, ServerRpcs } from '@irtio/schema';
+import RAPIER2D from '@dimforge/rapier2d-compat';
 import RAPIER from '@dimforge/rapier3d-compat';
 import * as MATTER from 'matter-js';
 
+/** The singleton the platform keeps the lobby's own state in. */
+declare const LOBBY_STATE = "irtLobby";
+/** The per-player collection the ready flag lives in, one instance per connected player. */
+declare const LOBBY_MEMBERS = "irtLobbyMembers";
+/** Phases a lobby room passes through. There are two, and it never goes back. */
+type LobbyPhase = 'lobby' | 'started';
+/**
+ * The lobby's own state, as every client sees it.
+ *
+ * `readyUi` is here rather than derived on the client because the start policy is the room's
+ * declaration and the element must not have to be told it twice. `present`, `ready` and `capacity`
+ * are the three numbers a lobby panel renders ("2/4 players, 1 ready"), published rather than
+ * counted client-side so that every client counts them the same way the room did.
+ */
+declare const lobbyStateSingleton: SingletonDef<{
+    phase: _irtio_schema.Type<"lobby" | "started", false>;
+    /** Whether the room is currently in the public registry. The room owns this truth. */
+    public: _irtio_schema.Type<boolean, false>;
+    /** True only under `start: 'when-ready'`. The element draws readiness only when this is set. */
+    readyUi: _irtio_schema.Type<boolean, false>;
+    /** Connected players the lobby is counting. */
+    present: _irtio_schema.Type<number, false>;
+    /** How many of them are ready. Always 0 outside `'when-ready'`. */
+    ready: _irtio_schema.Type<number, false>;
+    /** The number `'when-full'` starts at: the room's `maxClients`. */
+    capacity: _irtio_schema.Type<number, false>;
+}, {}>;
+/** One player's lobby record, owned by that player so their own ready flag is an owner write. */
+declare const lobbyMemberEntity: EntityDef<{
+    ready: _irtio_schema.Type<boolean, false>;
+}, {}>;
+/**
+ * Spread this into a schema to give the room a lobby.
+ *
+ * ```ts
+ * export const schema = defineSchema({ ...lobbyCollections, players: entity({ x: f32, y: f32 }) });
+ * ```
+ */
+declare const lobbyCollections: {
+    readonly [LOBBY_STATE]: typeof lobbyStateSingleton;
+    readonly [LOBBY_MEMBERS]: typeof lobbyMemberEntity;
+};
+/**
+ * When a lobby room starts its game.
+ *
+ * - `'when-full'` (**default**) starts the moment the room reaches `maxClients`. There is no ready
+ *   button: everyone who landed here asked to play, which is exactly true of the quick-match path
+ *   and is why this is the default rather than the polite-looking one.
+ * - `'when-ready'` starts when every present player is ready and `min` is met. This is the one
+ *   that surfaces a ready button.
+ * - `'manual'` never starts by itself. The room's own code calls `room.lobby.start()` on whatever
+ *   it likes: a timer, a host's click, a paid-up check.
+ */
+type LobbyStart = 'when-full' | 'when-ready' | 'manual';
+/** The floor on a `min`, and on a `'when-full'` capacity. One player is not a lobby. */
+declare const LOBBY_MIN_PLAYERS = 2;
+interface LobbyConfig<S = unknown> {
+    /** Default `'when-full'`. */
+    readonly start?: LobbyStart;
+    /**
+     * The fewest players `'when-ready'` will start with. Default 2.
+     *
+     * Ignored by the other two policies: `'when-full'` has {@link LobbyConfig.size} and `'manual'`
+     * has the room's own judgement.
+     */
+    readonly min?: number;
+    /**
+     * How many players `'when-full'` counts as full. Defaults to the room's `maxClients`.
+     *
+     * The design (`docs/lobby-quick-match-plan.md` §5) words this as "`maxClients`, or the queue's
+     * party size when smaller", and the platform cannot supply the second half: a room is created by
+     * the ordinary join path and never learns which queue sent the player, by construction. That is
+     * the property the whole quick-match design rests on ("the room neither knows nor cares that a
+     * matchmaker filled it"), so making it knowable would cost more than this field does.
+     *
+     * So the room declares it. A game whose `duo` queue seats two but whose room type allows eight
+     * spectators writes `lobby: { size: 2 }`, and the lobby starts at two rather than at eight.
+     * Clamped to `maxClients`: a lobby cannot wait for more players than the room will admit.
+     */
+    readonly size?: number;
+    /**
+     * The queue this room is filed under when it is public. Default `'default'`.
+     *
+     * A public room has to be findable under some queue name, and the room is the only thing that
+     * knows which game it is. A room that came from `mode: "public"` keeps the queue it was minted
+     * under regardless of this — the players already inside came from that queue, and moving a
+     * half-full lobby elsewhere would advertise it to people the first ones did not ask to play
+     * with. This is what a room that went public any other way is filed as.
+     */
+    readonly queue?: string;
+    /**
+     * Called once, when the game starts, whichever policy started it.
+     *
+     * In the config rather than registered at runtime, for the reason `alarms` is: a room that
+     * hibernated and woke would have lost a registered callback, and this map is code.
+     */
+    onStart?(state: S, room: unknown): void;
+    /**
+     * The veto on `room.lobby.setPublic(value)`.
+     *
+     * Return `false` to refuse. The registry is not touched, the singleton keeps the value it had,
+     * and every client's panel goes on rendering the room's state rather than the click — which is
+     * the property §4 of the design asks for and the reason the toggle reads the room rather than
+     * its own button.
+     *
+     * A room with no hook accepts every toggle, and a handler that returns nothing accepts too: the
+     * convention is `onMessage`'s, where only an explicit `false` refuses. A handler that THROWS
+     * refuses, because a hook that said nothing at all has not agreed to expose the game.
+     *
+     * There is no client id here, and that is a consequence of there being no built-in RPC: the
+     * platform never receives a toggle from a client. A game that wants one declares its own RPC and
+     * calls `room.lobby.setPublic` from it, where it has `ctx.clientId` and can decide whether that
+     * player is the host. See the panel's `public` event.
+     */
+    onSetPublic?(state: S, value: boolean): boolean | undefined | void;
+}
+/**
+ * `room.lobby` — the room's half of the convention.
+ *
+ * Reading it in a room whose schema does not spread `lobbyCollections` throws and says so, the way
+ * `room.physics` does in a room with no physics: a lobby API that silently did nothing would be a
+ * ready button nobody could debug.
+ */
+interface RoomLobby {
+    readonly phase: LobbyPhase;
+    /** Per-player readiness, by client id, in join order. */
+    readonly ready: readonly {
+        readonly clientId: string;
+        readonly ready: boolean;
+    }[];
+    /** Whether this room is currently in the public registry. */
+    readonly public: boolean;
+    /**
+     * Start the game now. Idempotent: a room already `'started'` is unchanged and no handler runs
+     * twice. Legal under every policy, not only `'manual'` — a `'when-ready'` room with a host
+     * button is an ordinary thing to build.
+     */
+    start(): void;
+    /**
+     * Register a start handler from `onCreate`. Additive to the declared `lobby.onStart`, and the
+     * declared one is the one that survives a hibernation; this is for a handler a room wires up
+     * itself and is dropped when the room sleeps.
+     */
+    onStart(cb: () => void): void;
+    /**
+     * Put this room in, or take it out of, the public registry.
+     *
+     * Server-authoritative: a client asks through the panel's toggle, the room's `onSetPublic` may
+     * refuse, and what every panel renders is the answer rather than the request. Deregistration on
+     * start is automatic and terminal — no backfill into started games in v1 — so this is only ever
+     * about a lobby.
+     */
+    setPublic(value: boolean): void;
+}
+/** Does this schema carry the lobby fragment? The runtime and `defineRoom` ask the same way. */
+declare function schemaHasLobby(schema: unknown): boolean;
+/** Validates a `lobby:` config on its way into `defineRoom`. Returns the problem, or `undefined`. */
+declare function lobbyConfigProblem(value: unknown): string | undefined;
+
 /**
  * D44: scripted NPCs — the room-side surface.
  *
@@ -195,8 +356,20 @@ declare function choose<B extends Behaviour>(behaviours: readonly B[]): B | unde
 type RapierModule = typeof RAPIER;
 type RapierWorld = RAPIER.World;
 type RapierRigidBody = RAPIER.RigidBody;
+type RapierCollider = RAPIER.Collider;
 type RapierRigidBodyDesc = RAPIER.RigidBodyDesc;
 type RapierColliderDesc = RAPIER.ColliderDesc;
+/**
+ * The 2D build of the same engine. Its namespace is a separate module with its own WASM, so the
+ * types are separate too: a `rapier2d` `World` is not a `rapier3d` `World` with a field removed,
+ * and letting the two share a name would make every accessor lie.
+ */
+type Rapier2dModule = typeof RAPIER2D;
+type Rapier2dWorld = RAPIER2D.World;
+type Rapier2dRigidBody = RAPIER2D.RigidBody;
+type Rapier2dCollider = RAPIER2D.Collider;
+type Rapier2dRigidBodyDesc = RAPIER2D.RigidBodyDesc;
+type Rapier2dColliderDesc = RAPIER2D.ColliderDesc;
 type MatterModule = typeof MATTER;
 type MatterEngine = MATTER.Engine;
 type MatterBody = MATTER.Body;
@@ -226,6 +399,16 @@ interface Matter2dBodySpec {
     /** Added to the world with the body, and removed with it. */
     readonly constraints?: readonly MatterConstraint[];
 }
+/**
+ * What a rapier2d body factory returns. Structurally the 3D {@link BodySpec} with 2D descs: the
+ * engine is the same one, so a body still has colliders attached to it rather than *being* its
+ * geometry the way a matter.js body does.
+ */
+interface Rapier2dBodySpec {
+    readonly body: Rapier2dRigidBodyDesc;
+    /** Attached to the body in order. A body with none is a valid (invisible) point mass. */
+    readonly colliders?: readonly Rapier2dColliderDesc[];
+}
 type Instance$1<S extends AnySchema, K extends keyof SchemaDefs<S>> = InstanceOf<SchemaDefs<S>[K]>;
 /**
  * `physics.bodies.<collection>` — how one instance becomes a rigid body. Called when the runtime
@@ -236,6 +419,10 @@ type Instance$1<S extends AnySchema, K extends keyof SchemaDefs<S>> = InstanceOf
 type BodyFactories<S extends AnySchema> = {
     readonly [K in PhysicsKeys<S>]: (rapier: RapierModule, instance: DeepReadonly<Instance$1<S, K & keyof SchemaDefs<S>>>, id: string) => BodySpec;
 };
+/** `physics.bodies.<collection>` for rapier2d. Same lifecycle as {@link BodyFactories}. */
+type Rapier2dBodyFactories<S extends AnySchema> = {
+    readonly [K in PhysicsKeys<S>]: (rapier: Rapier2dModule, instance: DeepReadonly<Instance$1<S, K & keyof SchemaDefs<S>>>, id: string) => Rapier2dBodySpec;
+};
 /** `physics.bodies.<collection>` for matter2d. Same lifecycle as {@link BodyFactories}. */
 type Matter2dBodyFactories<S extends AnySchema> = {
     readonly [K in PhysicsKeys<S>]: (matter: MatterModule, instance: DeepReadonly<Instance$1<S, K & keyof SchemaDefs<S>>>, id: string) => Matter2dBodySpec;
@@ -253,6 +440,59 @@ interface RapierPhysicsConfig<S extends AnySchema> {
      */
     setup?(world: RapierWorld, rapier: RapierModule, room: Room<S>): void;
     readonly bodies: BodyFactories<S>;
+    /** D72: how many ticks of body poses to keep for `room.rewind`. See {@link HISTORY_DOC}. */
+    readonly history?: number;
+}
+/** D72: the deepest history a room may declare, in ticks. One second at the maximum tick rate. */
+declare const HISTORY_MAX_TICKS = 240;
+/**
+ * D72: what `room.rewind(tick, fn)` hands `fn`.
+ *
+ * Exactly one of `rapier`, `rapier2d` and `matter` is present, decided by the room's engine.
+ *
+ * What a rewound query **can** see: every tracked body's pose at that tick, and the world's static
+ * geometry as it stands now. What it **cannot**: colliders as they were then (shapes are not
+ * historied, only poses), joints and contacts, bodies created since that tick, and anything the
+ * caller had not been told about yet.
+ */
+interface RewindView {
+    /** The tick actually answered from, after clamping. */
+    readonly tick: number;
+    /** The tick that was asked for, unclamped, so a room can log or refuse the difference. */
+    readonly requested: number;
+    /**
+     * `true` when `requested` fell outside the buffer and was pulled to its nearest edge. Not an
+     * error: the oldest pose the room still holds is the honest answer to "further back than I
+     * remember", and a room that would rather refuse a clamped answer can read this and do so.
+     */
+    readonly clamped: boolean;
+    /** rapier3d rooms: a scratch world to `castRay` / `castShape` / `intersectionsWithShape` on. */
+    readonly rapier?: {
+        readonly world: RapierWorld;
+        /** Which entity a collider in the scratch world belongs to; `undefined` for static geometry. */
+        who(collider: RapierCollider): {
+            readonly collection: string;
+            readonly id: string;
+        } | undefined;
+    };
+    /** rapier2d rooms: a scratch world to `castRay` / `castShape` / `intersectionsWithShape` on. */
+    readonly rapier2d?: {
+        readonly world: Rapier2dWorld;
+        /** Which entity a collider in the scratch world belongs to; `undefined` for static geometry. */
+        who(collider: Rapier2dCollider): {
+            readonly collection: string;
+            readonly id: string;
+        } | undefined;
+    };
+    /** matter2d rooms: the body array `Matter.Query.ray/point/region/collides` takes. */
+    readonly matter?: {
+        readonly bodies: readonly MatterBody[];
+        /** Which entity a body in the array belongs to; `undefined` for the world's static bodies. */
+        who(body: MatterBody): {
+            readonly collection: string;
+            readonly id: string;
+        } | undefined;
+    };
 }
 /**
  * D57: the matter-flavoured counterpart to `@irtio/client`'s `ClientIntent2dHook` — one step of
@@ -305,8 +545,69 @@ interface Matter2dPhysicsConfig<S extends AnySchema> {
      * with no declared intents, which is the check the type cannot make.
      */
     readonly intents?: Readonly<Partial<Record<PhysicsKeys<S> & string, Matter2dIntentHook>>>;
+    /** D72: how many ticks of body poses to keep for `room.rewind`. See {@link HISTORY_DOC}. */
+    readonly history?: number;
+}
+/**
+ * The rapier2d counterpart to {@link Matter2dIntentHook}: one step of steering for one body, from
+ * the fields a client may write.
+ *
+ * Same contract, different engine handles — and one real difference in what the hook has to do.
+ * A matter2d hook applies the room's gravity itself, because matter's `engine.gravity` is often
+ * not what a game wants per body; a rapier2d hook must not, because the world already did. See
+ * {@link Rapier2dPhysicsConfig}.
+ */
+type Rapier2dIntentHook = {
+    hook(body: Rapier2dRigidBody, instance: Record<string, unknown>, rapier: Rapier2dModule, world: Rapier2dWorld, timestep: number): void;
+}['hook'];
+/**
+ * D45's third engine: Rapier, in the plane.
+ *
+ * It is `rapier3d` minus a dimension rather than `matter2d` with different names, and the
+ * difference matters in three places a room author will feel:
+ *
+ * - **The world applies gravity.** `gravity` goes into the `World` and every dynamic body falls
+ *   without the room doing anything. matter2d rooms apply it per body from their own hooks;
+ *   a rapier2d room that does the same falls twice as fast.
+ * - **Velocities are per second.** `body.linvel()` is metres per second, not matter's per-step
+ *   displacement, so a hook writes the speed it means.
+ * - **The world snapshots.** `world.takeSnapshot()` rides inside the hibernation blob, so a woken
+ *   room is the world that went to sleep, contacts included — a settled pile does not re-settle
+ *   with a jolt the way a rebuilt matter2d one can.
+ *
+ * What it keeps from matter2d is the plane itself: `{ x, y }` gravity, no `z` channel, and the
+ * 2D shapes. The friction trap that made a 2D engine worth having (bug 6, the axis-lock recipe)
+ * cannot arise here — there is no third axis to lock.
+ */
+interface Rapier2dPhysicsConfig<S extends AnySchema> {
+    readonly engine: 'rapier2d';
+    /** In the plane. Rapier's convention is y-up; irtio does not flip it for you. */
+    readonly gravity: Vector2;
+    /** Seconds per world step. Defaults to the tick interval; one step per tick, no substeps. */
+    readonly timestep?: number;
+    /** Static geometry, joints, world tuning. Same lifecycle rules as rapier3d's `setup`. */
+    setup?(world: Rapier2dWorld, rapier: Rapier2dModule, room: Room<S>): void;
+    readonly bodies: Rapier2dBodyFactories<S>;
+    /**
+     * The shared per-collection steering functions, alongside `bodies`. **The runtime does not call
+     * these** — see {@link Matter2dPhysicsConfig.intents} for the whole of what the field buys and
+     * what `defineRoom` checks about it. The rule is identical here.
+     */
+    readonly intents?: Readonly<Partial<Record<PhysicsKeys<S> & string, Rapier2dIntentHook>>>;
+    /** D72: how many ticks of body poses to keep for `room.rewind`. See {@link HISTORY_DOC}. */
+    readonly history?: number;
+}
+/** `room.physicsRapier2d` in a rapier2d room. */
+interface Rapier2dRoomApi<S extends AnySchema> {
+    /** The `@dimforge/rapier2d-compat` namespace: descs, shapes, enums, `QueryFilterFlags`, … */
+    readonly rapier: Rapier2dModule;
+    /** The live world. Ray casts, static colliders added later, joints. */
+    readonly world: Rapier2dWorld;
+    /** Seconds per step (`world.timestep`). */
+    readonly timestep: number;
+    body(collection: PhysicsKeys<S> & string, id: string): Rapier2dRigidBody | undefined;
 }
-type PhysicsConfig<S extends AnySchema> = RapierPhysicsConfig<S> | Matter2dPhysicsConfig<S>;
+type PhysicsConfig<S extends AnySchema> = RapierPhysicsConfig<S> | Matter2dPhysicsConfig<S> | Rapier2dPhysicsConfig<S>;
 /**
  * `room.physics2d` in a matter2d room.
  *
@@ -351,6 +652,17 @@ interface PhysicsRoomApi<S extends AnySchema> {
 type MessageTarget = 'all' | string | {
     readonly role: string;
 };
+/**
+ * D70: what `onMessage`'s sixth argument carries for a typed message, and nothing at all for a
+ * raw one. A discriminated union over the declared names, so `if (typed?.name === 'emote')`
+ * narrows `typed.value` to that shape.
+ */
+type TypedMessage<S> = {
+    [K in MessageNames<S>]: {
+        readonly name: K;
+        readonly value: MessageValue<S, K>;
+    };
+}[MessageNames<S>];
 interface ClientInfo {
     readonly clientId: string;
     readonly role: string;
@@ -372,6 +684,16 @@ interface Room<S extends AnySchema = AnySchema> {
     /** Seeded, recorded for replay. */
     random(): number;
     send(target: MessageTarget, bytes: Uint8Array): void;
+    /**
+     * D70: `room.messages.<name>.send(target, value)` — one of the shapes the schema declares,
+     * encoded for you. `{}` on a schema that declares none, so game code can be written before the
+     * schema has anything to say.
+     *
+     * There is no `on` here: a room observes messages through `onMessage`, which is also where it
+     * can drop one. A second way in would be a second place to see a message the room had already
+     * declined.
+     */
+    readonly messages: ServerMessageChannels<S, MessageTarget>;
     setRole(clientId: string, role: RoleOf<S> & string): void;
     kick(clientId: string, reason?: string): void;
     close(reason?: string): void;
@@ -435,6 +757,47 @@ interface Room<S extends AnySchema = AnySchema> {
      * reading `room.physics` here.
      */
     readonly physics2d: Matter2dRoomApi<S>;
+    /**
+     * The rapier2d world and the bodies behind physics entities, in a room whose config declares
+     * `engine: 'rapier2d'`. A third accessor rather than a narrowing of `physics2d`, for the same
+     * reason there were two: the two 2D engines hand back different namespaces (`.rapier`/`.world`
+     * against `.matter`/`.engine`), and a union would make every existing matter2d room narrow
+     * before it could read a field it has always read. Each of the three throws a sentence naming
+     * the right one.
+     */
+    readonly physicsRapier2d: Rapier2dRoomApi<S>;
+    /**
+     * D72: run `fn` against the world as it stood at `tick`.
+     *
+     * A shot fired at 200 ms of latency was aimed at where the target was drawn on the shooter's
+     * screen, a round trip ago. `ctx.clientTick` says which tick that was; this puts every tracked
+     * body back where it was then, on a scratch world, and lets the room's own query answer there:
+     *
+     * ```ts
+     * rpc: {
+     *   fire(state, { dx, dy, dz }, ctx) {
+     *     const { rapier, world } = ctx.room.physics;
+     *     const from = ctx.room.physics.body('players', ctx.clientId)?.translation();
+     *     if (!from) return { hit: false };
+     *     return ctx.room.rewind(ctx.clientTick ?? ctx.tick, (past) => {
+     *       const hit = past.rapier?.world.castRay(new rapier.Ray(from, { x: dx, y: dy, z: dz }), 100, true);
+     *       return { hit: hit ? past.rapier?.who(hit.collider) !== undefined : false };
+     *     });
+     *   },
+     * }
+     * ```
+     *
+     * `fn` runs synchronously and whatever it returns is returned. The live world is never touched:
+     * this is stored poses on a second world, not a re-simulation, and nothing a player can see is
+     * stepped. A tick outside the buffer is clamped to its nearest edge and `past.clamped` says so,
+     * which is a fallback rather than an error.
+     *
+     * Throws when the room declares no `physics.history`, when the buffer is still empty (a room
+     * that has just woken), and when called from inside another `rewind`.
+     *
+     * @see irt.io/docs/concepts/lag-compensation
+     */
+    rewind<T>(tick: number, fn: (past: RewindView) => T): T;
     /**
      * D44: spawn a scripted NPC. `config.brain.script` names an entry in the room definition's
      * `npcs` map; the session it opens is an ordinary client session — it appears in
@@ -462,6 +825,15 @@ interface Room<S extends AnySchema = AnySchema> {
      * one.
      */
     readonly bus: RoomBus;
+    /**
+     * D75: the lobby convention — who is here, who is ready, when the game starts, and whether
+     * strangers can find this room.
+     *
+     * Present on every `Room` type, and reading it in a room whose schema does not spread
+     * `lobbyCollections` throws with that sentence, exactly as `room.physics` does in a room with no
+     * physics. A lobby API that silently did nothing would be a ready button nobody could debug.
+     */
+    readonly lobby: RoomLobby;
 }
 /**
  * D59: two verbs with deliberately unequal guarantees. Read them as a pair, because picking the
@@ -703,6 +1075,19 @@ interface RoomRatings {
         readonly deviation?: number;
     }): Promise<void>;
 }
+/** D69-c: what a submit may say about the board beyond the score. One field, and it is optional. */
+interface LeaderboardSubmitOptions {
+    /**
+     * Which cohort of a bucketed board this score belongs to: a region, a platform, a league —
+     * whatever your game means by it. 1 to 64 characters of `a-z 0-9 . _ -`.
+     *
+     * Required on a board configured with `buckets: true`, and refused on a board that is not
+     * (`E_LB_BUCKET_REQUIRED` / `E_LB_NO_BUCKETS`). Neither is guessed at: a bucket that was
+     * silently dropped would put a cohort's scores on the wrong ranking, and a read that silently
+     * merged every cohort would be a ranking nobody asked for.
+     */
+    readonly bucket?: string;
+}
 interface RoomLeaderboard {
     /**
      * Post `score` for `playerId` on `board`.
@@ -710,10 +1095,15 @@ interface RoomLeaderboard {
      * `playerId` must be a player currently in this room — `ctx.playerId` is the id to pass, and
      * anything else rejects with `E_LB_NOT_IN_ROOM`. Board names are 1-64 of `a-z 0-9 . _ -`.
      * Rejections name what they hit: `E_LB_BAD_BOARD`, `E_LB_BAD_SCORE`, `E_LB_NOT_IN_ROOM`,
-     * `E_LB_PROJECT_FULL`, `E_LB_UNAVAILABLE`. Like every promise-returning room API, the
-     * continuation runs as its own event between ticks.
+     * `E_LB_PROJECT_FULL`, `E_LB_UNAVAILABLE`, `E_LB_BAD_BUCKET`, `E_LB_BUCKET_REQUIRED`,
+     * `E_LB_NO_BUCKETS`. Like every promise-returning room API, the continuation runs as its own
+     * event between ticks.
+     *
+     * D69: there is no period argument and there will not be one. A rotating board's current period
+     * is computed on the control plane from its own clock at the moment the score lands, so a room
+     * needs no change to start rotating and cannot write into a period that has closed.
      */
-    submit(board: string, playerId: string, score: number): Promise<void>;
+    submit(board: string, playerId: string, score: number, options?: LeaderboardSubmitOptions): Promise<void>;
 }
 interface Ctx<S extends AnySchema = AnySchema> {
     readonly clientId: string;
@@ -730,6 +1120,23 @@ interface Ctx<S extends AnySchema = AnySchema> {
     readonly name: string;
     /** Server tick this join/call/write is applied at. */
     readonly tick: number;
+    /**
+     * D72: RPCs only. The newest authoritative tick the caller had applied when it sent the `CALL`,
+     * which is the tick whose world it was looking at. `undefined` for a join, a write, or a `CALL`
+     * from a client that sends no stamp.
+     *
+     * It is what `room.rewind` is meant to be given:
+     *
+     * ```ts
+     * const hit = ctx.room.rewind(ctx.clientTick ?? ctx.tick, (past) => …);
+     * ```
+     *
+     * **It is a number a client chose.** The history depth bounds how far into the past a lie can
+     * reach and `rewind` clamps anything outside the buffer, but a room that wants to distrust it
+     * compares it with `ctx.tick` and refuses a gap it does not like. See
+     * irt.io/docs/concepts/lag-compensation.
+     */
+    readonly clientTick: number | undefined;
     /** Joins only: a resumed session. */
     readonly reconnecting: boolean;
     readonly room: Room<S>;
@@ -868,6 +1275,17 @@ interface RoomConfigBase<S extends AnySchema> {
      * loop that awaits: `while (!npc.stopped) { …; await npc.wait(100) }`.
      */
     readonly npcs?: Readonly<Record<string, NpcScript<S>>>;
+    /**
+     * D75: this room holds players at a lobby until the game starts.
+     *
+     * The opt-in is the schema's — `defineSchema({ ...lobbyCollections, ... })`, so both sides of
+     * the wire read the same fragment from the same module — and this is the room's policy for it:
+     * when to start, how few players will do, which queue it is public under, and the two handlers.
+     *
+     * Declaring it against a schema that does not carry the fragment is a `defineRoom` error rather
+     * than a room that quietly never starts.
+     */
+    readonly lobby?: LobbyConfig<State<S>>;
     onCreate?(state: State<S>, room: Room<S>): void;
     onJoin?(state: State<S>, ctx: Ctx<S>): void;
     onLeave?(state: State<S>, ctx: Ctx<S>, reason: LeaveReason): void;
@@ -878,8 +1296,19 @@ interface RoomConfigBase<S extends AnySchema> {
     readonly validate?: Validators<S>;
     /** Implements the built-in `requestOwnership` RPC. Default: grant if unowned. */
     onOwnershipRequest?(state: State<S>, entity: OwnableKeys<S> & string, id: string, ctx: Ctx<S>): boolean;
-    /** Raw relay messages; return `false` to drop. */
-    onMessage?(state: State<S>, from: string, target: MessageTarget, bytes: Uint8Array, ctx: Ctx<S>): boolean | undefined | void;
+    /**
+     * Peer messages, raw and typed alike; return `false` to drop.
+     *
+     * `bytes` is what the peer sent: opaque for `room.message(target, bytes)`, and the encoded
+     * payload for a typed message. D70 adds the sixth argument: present, with the declared name and
+     * the decoded value, exactly when the message was typed. The decode happens **before** this
+     * handler runs, so a malformed payload never arrives here at all — it is counted and dropped —
+     * and `typed.value` is always a well-formed value of a shape this schema declares.
+     *
+     * Returning `false` drops a typed message exactly as it drops a raw one. That is the room's
+     * veto, and it is the only one it needs.
+     */
+    onMessage?(state: State<S>, from: string, target: MessageTarget, bytes: Uint8Array, ctx: Ctx<S>, typed?: TypedMessage<S>): boolean | undefined | void;
 }
 type RoomConfig<S extends AnySchema> = RoomConfigBase<S> & RpcConfig<S>;
 /** Config with defaults filled and `rpc` always present. */
@@ -961,4 +1390,4 @@ declare function defineRoom<S extends AnySchema>(schema: S, config: RoomConfig<S
 /** Type guard for what a bundle's default export should be. */
 declare function isRoomDefinition(v: unknown): v is RoomDefinition;
 
-export { type Behaviour, type BodyFactories, type BodySpec, type BusConfig, type BusEvent, type BusMessage, type ClientInfo, type Ctx, DEFAULTS, type LeaveReason, MAX_AWAKE_MAX, MEMORY_MB_MAX, MEMORY_MB_MIN, type Matter2dBodyFactories, type Matter2dBodySpec, type Matter2dIntentHook, type Matter2dPhysicsConfig, type Matter2dRoomApi, type MatterBody, type MatterConstraint, type MatterEngine, type MatterModule, type MessageTarget, type Npc, type NpcCollection, type NpcConfig, type NpcHandle, type NpcRoom, type NpcScript, type NpcScriptBrain, type NpcState, type PatrolStep, type PhysicsConfig, type PhysicsRoomApi, type PlayerKv, RETENTION_MAX_MS, RETENTION_MIN_MS, RETENTION_RE, ROOM_DEFINITION_VERSION, type RapierColliderDesc, type RapierModule, type RapierPhysicsConfig, type RapierRigidBody, type RapierRigidBodyDesc, type RapierWorld, type ResolvedRoomConfig, type Room, type RoomBackfill, type RoomBus, type RoomConfig, type RoomConfigBase, type RoomDefinition, type RoomLeaderboard, type RoomMode, type RoomRatingResult, type RoomRatings, type RpcImplementations, type TimerHandle, type Validators, type Vec2, type Vector2, type Vector3, type WanderState, arrive, choose, defineRoom, flee, isRoomDefinition, newWander, patrol, seek, wander };
+export { type Behaviour, type BodyFactories, type BodySpec, type BusConfig, type BusEvent, type BusMessage, type ClientInfo, type Ctx, DEFAULTS, HISTORY_MAX_TICKS, LOBBY_MEMBERS, LOBBY_MIN_PLAYERS, LOBBY_STATE, type LeaderboardSubmitOptions, type LeaveReason, type LobbyConfig, type LobbyPhase, type LobbyStart, MAX_AWAKE_MAX, MEMORY_MB_MAX, MEMORY_MB_MIN, type Matter2dBodyFactories, type Matter2dBodySpec, type Matter2dIntentHook, type Matter2dPhysicsConfig, type Matter2dRoomApi, type MatterBody, type MatterConstraint, type MatterEngine, type MatterModule, type MessageTarget, type Npc, type NpcCollection, type NpcConfig, type NpcHandle, type NpcRoom, type NpcScript, type NpcScriptBrain, type NpcState, type PatrolStep, type PhysicsConfig, type PhysicsRoomApi, type PlayerKv, RETENTION_MAX_MS, RETENTION_MIN_MS, RETENTION_RE, ROOM_DEFINITION_VERSION, type Rapier2dBodyFactories, type Rapier2dBodySpec, type Rapier2dCollider, type Rapier2dColliderDesc, type Rapier2dIntentHook, type Rapier2dModule, type Rapier2dPhysicsConfig, type Rapier2dRigidBody, type Rapier2dRigidBodyDesc, type Rapier2dRoomApi, type Rapier2dWorld, type RapierCollider, type RapierColliderDesc, type RapierModule, type RapierPhysicsConfig, type RapierRigidBody, type RapierRigidBodyDesc, type RapierWorld, type ResolvedRoomConfig, type RewindView, type Room, type RoomBackfill, type RoomBus, type RoomConfig, type RoomConfigBase, type RoomDefinition, type RoomLeaderboard, type RoomLobby, type RoomMode, type RoomRatingResult, type RoomRatings, type RpcImplementations, type TimerHandle, type TypedMessage, type Validators, type Vec2, type Vector2, type Vector3, type WanderState, arrive, choose, defineRoom, flee, isRoomDefinition, lobbyCollections, lobbyConfigProblem, lobbyMemberEntity, lobbyStateSingleton, newWander, patrol, schemaHasLobby, seek, wander };

package/dist/index.js

@@ -1,3 +1,77 @@
+// src/lobby.ts
+import {
+  bool,
+  entity,
+  enumOf,
+  singleton,
+  u8
+} from "@irtio/schema";
+var LOBBY_STATE = "irtLobby";
+var LOBBY_MEMBERS = "irtLobbyMembers";
+var lobbyStateSingleton = singleton({
+  phase: enumOf("lobby", "started"),
+  /** Whether the room is currently in the public registry. The room owns this truth. */
+  public: bool,
+  /** True only under `start: 'when-ready'`. The element draws readiness only when this is set. */
+  readyUi: bool,
+  /** Connected players the lobby is counting. */
+  present: u8,
+  /** How many of them are ready. Always 0 outside `'when-ready'`. */
+  ready: u8,
+  /** The number `'when-full'` starts at: the room's `maxClients`. */
+  capacity: u8
+});
+var lobbyMemberEntity = entity({ ready: bool });
+var lobbyCollections = {
+  [LOBBY_STATE]: lobbyStateSingleton,
+  [LOBBY_MEMBERS]: lobbyMemberEntity
+};
+var LOBBY_MIN_PLAYERS = 2;
+function schemaHasLobby(schema) {
+  const collections = schema?.collections;
+  if (!Array.isArray(collections)) return false;
+  const names = new Set(collections.map((c) => c.name));
+  return names.has(LOBBY_STATE) && names.has(LOBBY_MEMBERS);
+}
+function lobbyConfigProblem(value) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return 'lobby must be an object like { start: "when-ready" }';
+  }
+  const config = value;
+  if (config.start !== void 0 && config.start !== "when-full" && config.start !== "when-ready" && config.start !== "manual") {
+    return `lobby.start must be 'when-full', 'when-ready' or 'manual', got ${JSON.stringify(
+      config.start
+    )}`;
+  }
+  if (config.min !== void 0) {
+    if (!Number.isInteger(config.min) || config.min < LOBBY_MIN_PLAYERS || config.min > 255) {
+      return `lobby.min must be a whole number from ${LOBBY_MIN_PLAYERS} to 255, got ${String(
+        config.min
+      )}`;
+    }
+  }
+  if (config.size !== void 0) {
+    if (!Number.isInteger(config.size) || config.size < LOBBY_MIN_PLAYERS || config.size > 255) {
+      return `lobby.size must be a whole number from ${LOBBY_MIN_PLAYERS} to 255, got ${String(
+        config.size
+      )}`;
+    }
+  }
+  if (config.queue !== void 0 && !/^[a-z0-9][a-z0-9._-]{0,31}$/.test(config.queue)) {
+    return `lobby.queue ${JSON.stringify(config.queue)} must be 1-32 of a-z 0-9 . _ - and start with a letter or digit`;
+  }
+  for (const key of Object.keys(config)) {
+    if (key !== "start" && key !== "min" && key !== "size" && key !== "queue" && key !== "onStart" && key !== "onSetPublic") {
+      return `lobby has an unknown field ${JSON.stringify(key)}`;
+    }
+  }
+  return void 0;
+}
+
+// src/physics.ts
+var HISTORY_MAX_TICKS = 240;
+
 // src/npc.ts
 var ZERO = { x: 0, y: 0 };
 function scaleTo(dx, dy, speed) {
@@ -151,6 +225,7 @@ function defineRoom(schema, config) {
   }
   checkPhysics(schema, config, mode);
   checkNpcs(config);
+  checkLobby(schema, config);
   const resolved = {
     ...config,
     mode,
@@ -168,6 +243,24 @@ function defineRoom(schema, config) {
     config: Object.freeze(resolved)
   });
 }
+function checkLobby(schema, config) {
+  const problem = lobbyConfigProblem(config.lobby);
+  if (problem) throw new Error(`defineRoom: ${problem}`);
+  const carried = schemaHasLobby(schema);
+  if (config.lobby !== void 0 && !carried) {
+    throw new Error(
+      "defineRoom: lobby: is configured but the schema does not carry the lobby collections \u2014 add them with defineSchema({ ...lobbyCollections, ... }) from '@irtio/server'. Both sides of the wire read the fragment from that module, which is what stops a client and a room disagreeing about the lobby state"
+    );
+  }
+  if (config.lobby === void 0 && carried) {
+    throw new Error(
+      "defineRoom: the schema spreads lobbyCollections but the room config has no lobby: \u2014 add lobby: true-equivalent config (lobby: {}) to take the defaults, or drop the spread"
+    );
+  }
+  const lobby = config.lobby;
+  assertSyncHandler(lobby?.onStart, "lobby.onStart");
+  assertSyncHandler(lobby?.onSetPublic, "lobby.onSetPublic");
+}
 function checkNpcs(config) {
   const npcs = config.npcs;
   if (npcs === void 0) return;
@@ -202,15 +295,16 @@ function checkPhysics(schema, config, mode) {
       "defineRoom: physics needs mode: 'tick' \u2014 the world steps on the fixed timestep, and an event-mode room has no timestep to step on"
     );
   }
-  if (physics.engine !== "rapier3d" && physics.engine !== "matter2d") {
+  const ENGINES = ["rapier3d", "matter2d", "rapier2d"];
+  if (!ENGINES.includes(physics.engine)) {
     throw new Error(
-      `defineRoom: physics.engine must be 'rapier3d' or 'matter2d', got ${JSON.stringify(
+      `defineRoom: physics.engine must be one of ${ENGINES.map((e) => `'${e}'`).join(", ")}, got ${JSON.stringify(
         physics.engine
       )}`
     );
   }
   const g = physics.gravity;
-  const planar = physics.engine === "matter2d";
+  const planar = physics.engine === "matter2d" || physics.engine === "rapier2d";
   if (!g || typeof g !== "object" || !Number.isFinite(g.x) || !Number.isFinite(g.y) || !planar && !Number.isFinite(g.z)) {
     throw new Error(
       planar ? "defineRoom: physics.gravity must be { x, y } finite numbers" : "defineRoom: physics.gravity must be { x, y, z } finite numbers"
@@ -221,6 +315,14 @@ function checkPhysics(schema, config, mode) {
       `defineRoom: physics.timestep must be a positive number of seconds, got ${String(physics.timestep)}`
     );
   }
+  const history = physics.history;
+  if (history !== void 0) {
+    if (!Number.isInteger(history) || history < 0 || history > HISTORY_MAX_TICKS) {
+      throw new Error(
+        `defineRoom: physics.history must be an integer in 0..${HISTORY_MAX_TICKS} ticks (0 or absent means no history and no cost), got ${String(history)}`
+      );
+    }
+  }
   assertSyncHandler(physics.setup, "physics.setup");
   const bodies = physics.bodies ?? {};
   for (const [k, fn] of Object.entries(bodies)) assertSyncHandler(fn, `physics.bodies.${k}`);
@@ -265,6 +367,10 @@ function isRoomDefinition(v) {
 }
 export {
   DEFAULTS,
+  HISTORY_MAX_TICKS,
+  LOBBY_MEMBERS,
+  LOBBY_MIN_PLAYERS,
+  LOBBY_STATE,
   MAX_AWAKE_MAX,
   MEMORY_MB_MAX,
   MEMORY_MB_MIN,
@@ -277,8 +383,13 @@ export {
   defineRoom,
   flee,
   isRoomDefinition,
+  lobbyCollections,
+  lobbyConfigProblem,
+  lobbyMemberEntity,
+  lobbyStateSingleton,
   newWander,
   patrol,
+  schemaHasLobby,
   seek,
   wander
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/server",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "irtio room-file API: defineRoom, handler and ctx types",
   "license": "MIT",
   "publishConfig": {
@@ -20,13 +20,17 @@
     "dist"
   ],
   "dependencies": {
-    "@irtio/schema": "0.6.0"
+    "@irtio/schema": "0.8.0"
   },
   "peerDependencies": {
+    "@dimforge/rapier2d-compat": ">=0.20.0",
     "@dimforge/rapier3d-compat": ">=0.20.0",
     "matter-js": ">=0.20.0"
   },
   "peerDependenciesMeta": {
+    "@dimforge/rapier2d-compat": {
+      "optional": true
+    },
     "@dimforge/rapier3d-compat": {
       "optional": true
     },
@@ -37,7 +41,8 @@
   "devDependencies": {
     "@dimforge/rapier3d-compat": "0.20.0",
     "@types/matter-js": "0.20.2",
-    "matter-js": "0.20.0"
+    "matter-js": "0.20.0",
+    "@dimforge/rapier2d-compat": "0.20.0"
   },
   "scripts": {
     "build": "tsup",