@irtio/server 0.7.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, ServerMessageChannels, ServerCallProxy, SchemaRpc, BroadcastProxy, OwnableKeys, MessageNames, MessageValue, 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.
  *
@@ -198,6 +359,17 @@ 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;
@@ -227,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
@@ -237,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;
@@ -262,7 +448,7 @@ declare const HISTORY_MAX_TICKS = 240;
 /**
  * D72: what `room.rewind(tick, fn)` hands `fn`.
  *
- * Exactly one of `rapier` and `matter` is present, decided by the room's engine.
+ * 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
@@ -289,6 +475,15 @@ interface RewindView {
             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[];
@@ -353,7 +548,66 @@ interface Matter2dPhysicsConfig<S extends AnySchema> {
     /** D72: how many ticks of body poses to keep for `room.rewind`. See {@link HISTORY_DOC}. */
     readonly history?: number;
 }
-type PhysicsConfig<S extends AnySchema> = RapierPhysicsConfig<S> | Matter2dPhysicsConfig<S>;
+/**
+ * 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> | Rapier2dPhysicsConfig<S>;
 /**
  * `room.physics2d` in a matter2d room.
  *
@@ -503,6 +757,15 @@ 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`.
      *
@@ -562,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
@@ -1003,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;
@@ -1107,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, HISTORY_MAX_TICKS, type LeaderboardSubmitOptions, 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 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 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, 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,74 @@
+// 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;
 
@@ -154,6 +225,7 @@ function defineRoom(schema, config) {
   }
   checkPhysics(schema, config, mode);
   checkNpcs(config);
+  checkLobby(schema, config);
   const resolved = {
     ...config,
     mode,
@@ -171,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;
@@ -205,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"
@@ -277,6 +368,9 @@ function isRoomDefinition(v) {
 export {
   DEFAULTS,
   HISTORY_MAX_TICKS,
+  LOBBY_MEMBERS,
+  LOBBY_MIN_PLAYERS,
+  LOBBY_STATE,
   MAX_AWAKE_MAX,
   MEMORY_MB_MAX,
   MEMORY_MB_MIN,
@@ -289,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.7.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.7.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",