@irtio/server 0.5.1 → 0.6.0

package/dist/index.d.ts

@@ -1,5 +1,181 @@
-import { AnySchema, PhysicsKeys, DeepReadonly, SchemaDefs, InstanceOf, RoleOf, ServerCallProxy, SchemaRpc, BroadcastProxy, State, OwnableKeys, Implementations, ServerRpcs } from '@irtio/schema';
+import { AnySchema, RoleOf, VisibleKeys, SchemaDefs, EntityDef, ReadonlyCollection, DeepReadonly, InferFields, Owned, SingletonDef, PhysicsKeys, InstanceOf, State, ServerCallProxy, SchemaRpc, BroadcastProxy, OwnableKeys, Implementations, ServerRpcs } from '@irtio/schema';
 import RAPIER from '@dimforge/rapier3d-compat';
+import * as MATTER from 'matter-js';
+
+/**
+ * D44: scripted NPCs — the room-side surface.
+ *
+ * **One runtime, two hats.** An NPC is the bot runtime (`@irtio/bots`) wearing its server hat: the
+ * script it runs is the same shape a simulation script has, and the session it drives is an
+ * ordinary client session at the protocol level. Nothing here executes; this file is the types
+ * room code writes against, plus the steering maths so an author never writes a normalize.
+ *
+ * ## Where the script actually runs
+ *
+ * Not in the room worker. `spawnNPC` is called from room code, which runs inside the worker
+ * sandbox, and a script running there would sit on the authoritative side of the seam — it could
+ * touch room state without a session, which is exactly what "a real client session" forbids. So
+ * the brain is declared as a **named entry in the room definition's `npcs` map** and `spawnNPC`
+ * names it. The supervisor already imports the room bundle (it reads the config out of it), so the
+ * function is right there on the other side of the boundary, and the session it drives enters
+ * beside the WebSocket accept.
+ *
+ * That is why `brain.script` is a name and not a function: a function would have to cross a
+ * `postMessage`, and functions do not.
+ */
+
+/**
+ * The client-side state shape, mirrored here so room code can name it without importing
+ * `@irtio/client` — which is not on the room bundle's import menu, and should not be: a room file
+ * that could import the SDK could open a socket.
+ *
+ * It is character for character `@irtio/client`'s `ClientState`, and both are built out of
+ * `@irtio/schema` exports only, so the real object stays structurally assignable to this one. The
+ * load-bearing part is the ownership split: instances of an instance-owned collection are
+ * **writable** (whether this session owns a given instance is a runtime fact the compiler cannot
+ * decide), while `serverOwned` collections and singletons are read-only.
+ */
+type NpcCollection<T> = ReadonlyCollection<T> & {
+    readonly [id: string]: T | undefined;
+};
+type NpcState<S, Role extends string = RoleOf<S> & string> = {
+    [K in VisibleKeys<S, Role>]: SchemaDefs<S>[K] extends EntityDef<infer F, infer O> ? O extends {
+        serverOwned: true;
+    } ? NpcCollection<DeepReadonly<InferFields<F>>> : NpcCollection<Owned<InferFields<F>>> : SchemaDefs<S>[K] extends SingletonDef<infer F, any> ? DeepReadonly<InferFields<F>> : never;
+};
+/**
+ * What an NPC script sees: the client-side room, structurally. The real object is
+ * `@irtio/client`'s `Room<S>` — the supervisor hands the script the very object a browser gets —
+ * and this is the subset room code can name without importing the client SDK, which is not on the
+ * room bundle's import menu.
+ *
+ * Reads go through `state` exactly as they do in a browser, and so do writes: an NPC owns its
+ * entities the way a client owns them, and the server validates them the way it validates a
+ * player's.
+ */
+interface NpcRoom<S extends AnySchema> {
+    /** This NPC's client id. */
+    readonly me: string;
+    readonly id: string;
+    /** The last server tick this session saw. */
+    readonly tick: number;
+    readonly state: NpcState<S, RoleOf<S> & string>;
+    /** Sends pending owned writes now instead of at the next flush window. */
+    flush(): void;
+}
+/**
+ * The object an NPC script receives. `@irtio/bots`' `Bot<S>` satisfies it structurally, because it
+ * *is* a `Bot<S>`: the members left out here are the ones that only mean something inside a
+ * simulation report (traces, injected network conditions, shot records), and an NPC has no report.
+ */
+interface Npc<S extends AnySchema> {
+    /** 0 for every NPC: each one is its own single-bot runner. */
+    readonly index: number;
+    readonly room: NpcRoom<S>;
+    /** The client id, repeated because scripts reach for it constantly. */
+    readonly id: string;
+    readonly role: string;
+    /** Seeded per NPC, so a spawn order replays the same way. */
+    random(): number;
+    /** Sleeps, or returns immediately once the NPC has been asked to stop. */
+    wait(ms: number): Promise<void>;
+    /** Polls; never a fixed sleep. Returns early once the NPC is stopped. */
+    until(predicate: () => boolean | Promise<boolean>, options?: {
+        label?: string;
+        timeoutMs?: number;
+        everyMs?: number;
+    }): Promise<void>;
+    /** Asks this script to wind down. `despawn()` sets it. */
+    stop(): void;
+    readonly stopped: boolean;
+}
+/** An entry in the room definition's `npcs` map. Async, and expected to loop until `stopped`. */
+type NpcScript<S extends AnySchema> = (npc: Npc<S>) => void | Promise<void>;
+/**
+ * `config.brain` (D44). One shape in v1, and the discriminant exists so act two's LLM and voiced
+ * brains have somewhere to land without a breaking change. Anything other than `'script'` is
+ * refused at the call, by name.
+ */
+interface NpcScriptBrain {
+    readonly kind: 'script';
+    /** A key of the room definition's `npcs` map. */
+    readonly script: string;
+}
+interface NpcConfig {
+    /** Presence name, as a player's. Defaults to the script name. */
+    readonly name?: string;
+    /** Joins with this role, as a player does. */
+    readonly role?: string;
+    readonly brain: NpcScriptBrain;
+    /** Seeds `npc.random()`. Defaults to a draw from the room's own seeded rng, so runs replay. */
+    readonly seed?: number;
+}
+/** What `room.spawnNPC` hands back. */
+interface NpcHandle {
+    /** The client id this NPC will hold. Present immediately; the session settles a tick or two later. */
+    readonly clientId: string;
+    /** Stops the script and closes the session. Idempotent. */
+    despawn(): void;
+}
+/**
+ * The steering primitives, in the plane. They are pure functions returning a **velocity**, so a
+ * script's whole movement step is `p.vx = v.x` — there is no controller object to own, nothing to
+ * tick, and nothing that has to survive a hibernation.
+ *
+ * Two dimensions on purpose. A 3D game steers on the ground plane and keeps its own vertical, and
+ * a Vec3 variant of each of these would double the surface to serve the case that already works.
+ */
+interface Vec2 {
+    readonly x: number;
+    readonly y: number;
+}
+/** Straight at the target, at full speed. */
+declare function seek(from: Vec2, to: Vec2, speed: number): Vec2;
+/** Straight away from it. */
+declare function flee(from: Vec2, threat: Vec2, speed: number): Vec2;
+/**
+ * Seek, but easing to a stop inside `slowRadius`. Without it a chaser at speed orbits its target
+ * forever, which reads as a bug in the game and is a bug in the steering.
+ */
+declare function arrive(from: Vec2, to: Vec2, speed: number, slowRadius: number): Vec2;
+/** The `wander` state a script keeps between steps: one angle, in radians. */
+interface WanderState {
+    angle: number;
+}
+/** A fresh wander heading. */
+declare function newWander(random: () => number): WanderState;
+/**
+ * A random walk that looks like a walk: the heading turns by at most `turn` radians per step
+ * rather than being redrawn, so the path curves instead of jittering on the spot. Mutates `state`.
+ */
+declare function wander(state: WanderState, speed: number, turn: number, random: () => number): Vec2;
+/** What `patrol` returns: where to go now, and the waypoint index to keep for the next step. */
+interface PatrolStep {
+    readonly velocity: Vec2;
+    readonly index: number;
+}
+/**
+ * Walks a waypoint ring. `index` is the waypoint being walked to; feed back the one this returns.
+ * An empty list stands still rather than throwing, because a patrol with no waypoints is a level
+ * that has not been finished, not a crash worth taking the room down for.
+ */
+declare function patrol(from: Vec2, waypoints: readonly Vec2[], index: number, speed: number, reachedRadius: number): PatrolStep;
+/** One named behaviour in a priority list. */
+interface Behaviour {
+    readonly name: string;
+    /** Chosen when this returns true and nothing earlier did. */
+    when(): boolean;
+}
+/**
+ * A priority selector: the first behaviour whose `when()` holds, or `undefined`.
+ *
+ * This is deliberately a helper and not an engine. "Flee if hurt, else chase if close, else
+ * patrol" is what NPC scripts actually write, it is four lines of `if` without this, and a
+ * behaviour tree with decorators and blackboards would be a second product hiding inside the
+ * first one. The value here is the *name*: a script can log or publish which behaviour is running
+ * without keeping a parallel string.
+ */
+declare function choose<B extends Behaviour>(behaviours: readonly B[]): B | undefined;
 
 /**
  * The room-side physics surface (D22): `physics:` on the room config, and `room.physics` inside
@@ -21,6 +197,14 @@ type RapierWorld = RAPIER.World;
 type RapierRigidBody = RAPIER.RigidBody;
 type RapierRigidBodyDesc = RAPIER.RigidBodyDesc;
 type RapierColliderDesc = RAPIER.ColliderDesc;
+type MatterModule = typeof MATTER;
+type MatterEngine = MATTER.Engine;
+type MatterBody = MATTER.Body;
+type MatterConstraint = MATTER.Constraint;
+interface Vector2 {
+    readonly x: number;
+    readonly y: number;
+}
 interface Vector3 {
     readonly x: number;
     readonly y: number;
@@ -32,6 +216,16 @@ interface BodySpec {
     /** Attached to the body in order. A body with none is a valid (invisible) point mass. */
     readonly colliders?: readonly RapierColliderDesc[];
 }
+/**
+ * D45: what a matter2d body factory returns. matter.js has no separate collider concept — a body
+ * *is* its geometry — so this is one body plus any constraints pinning it, and there is no second
+ * shape list to keep in step with the first.
+ */
+interface Matter2dBodySpec {
+    readonly body: MatterBody;
+    /** Added to the world with the body, and removed with it. */
+    readonly constraints?: readonly MatterConstraint[];
+}
 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
@@ -42,8 +236,12 @@ 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;
 };
-interface PhysicsConfig<S extends AnySchema> {
-    /** The one blessed engine in M2 (D22). */
+/** `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;
+};
+interface RapierPhysicsConfig<S extends AnySchema> {
+    /** The 3D engine (D22). */
     readonly engine: 'rapier3d';
     readonly gravity: Vector3;
     /** Seconds per world step. Defaults to the tick interval; one step per tick, no substeps. */
@@ -56,7 +254,79 @@ interface PhysicsConfig<S extends AnySchema> {
     setup?(world: RapierWorld, rapier: RapierModule, room: Room<S>): void;
     readonly bodies: BodyFactories<S>;
 }
-/** `room.physics` — what handlers use to turn intents into forces. */
+/**
+ * D57: the matter-flavoured counterpart to `@irtio/client`'s `ClientIntent2dHook` — one step of
+ * steering for one body, from the fields a client may write.
+ *
+ * A room's `tick()` already calls a per-collection steering function of exactly this shape; see
+ * `games/dive/irtio/world.ts`'s `intents` and `room.ts`'s `tick()`. Naming the type here, and
+ * letting the config carry the map, is what lets a client-side matter2d predictor pull the very
+ * same functions out of the shared world module and replay them, instead of the two sides wiring
+ * up their own imports and drifting.
+ *
+ * Method syntax, so a hook written against its own instance type is accepted: the values really
+ * passed are the schema's records for that collection.
+ */
+type Matter2dIntentHook = {
+    hook(body: MatterBody, instance: Record<string, unknown>, matter: MatterModule, engine: MatterEngine, timestep: number): void;
+}['hook'];
+/**
+ * D45: the second blessed engine. `matter-js` is 2D, pure JavaScript, and blessed on the same
+ * terms Rapier is — room code gets the real `Matter` namespace and the real `Engine`, so every
+ * matter.js tutorial applies unchanged, and irtio invents no syntax for a shape.
+ *
+ * The reason to have it at all is that the documented way to hold Rapier in a plane has a trap in
+ * it (locking one translation axis and the two rotations across that plane silently removes
+ * friction on box-shaped bodies), and a 2D engine makes the whole recipe unnecessary.
+ *
+ * Its determinism story is weaker than Rapier's and the measurement is in the docs rather than an
+ * adjective. See the physics reference for what that means for client-side prediction.
+ */
+interface Matter2dPhysicsConfig<S extends AnySchema> {
+    readonly engine: 'matter2d';
+    /** In the plane. matter.js's own convention is y-down; 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, constraints, world tuning. Same lifecycle rules as Rapier's `setup`. */
+    setup?(engine: MatterEngine, matter: MatterModule, room: Room<S>): void;
+    readonly bodies: Matter2dBodyFactories<S>;
+    /**
+     * D57: the shared per-collection steering functions, alongside `bodies`.
+     *
+     * **The runtime does not call these.** Declaring a hook here does not make the room run it; the
+     * room's `tick()` runs it, exactly as it did before this field existed, and `RapierPhysicsConfig`
+     * has no equivalent. What the field buys is a single naming: `joinRoom({ physics2d: { intents } })`
+     * on the client and `physics: { intents }` here point at the same function in the same shared
+     * module, so "same code both sides" is checkable rather than a convention.
+     *
+     * Partial, unlike `bodies`: every physics collection needs a shape, and only the ones whose
+     * schema declares `intents` can be steered. `defineRoom` refuses a key that names a collection
+     * with no declared intents, which is the check the type cannot make.
+     */
+    readonly intents?: Readonly<Partial<Record<PhysicsKeys<S> & string, Matter2dIntentHook>>>;
+}
+type PhysicsConfig<S extends AnySchema> = RapierPhysicsConfig<S> | Matter2dPhysicsConfig<S>;
+/**
+ * `room.physics2d` in a matter2d room.
+ *
+ * Two accessors rather than one narrowing union, and the reason is compatibility rather than
+ * taste: `room.physics` is D22's surface and every Rapier room in existence reads through it
+ * without a narrowing step. A union would have made all of them stop compiling to serve a room
+ * that has not been written yet. Each accessor throws a sentence naming the other when the room's
+ * engine is the other one, so the mistake costs one line of reading rather than a debugging
+ * session.
+ */
+interface Matter2dRoomApi<S extends AnySchema> {
+    /** The `matter-js` namespace: `Bodies`, `Body`, `Composite`, `Constraint`, `Vector`, … */
+    readonly matter: MatterModule;
+    /** The live `Matter.Engine`. `engine.world` is the composite everything lives in. */
+    readonly engine: MatterEngine;
+    /** Seconds per step. */
+    readonly timestep: number;
+    body(collection: PhysicsKeys<S> & string, id: string): MatterBody | undefined;
+}
+/** `room.physics` — what handlers use to turn intents into forces (rapier3d rooms). */
 interface PhysicsRoomApi<S extends AnySchema> {
     /** The `@dimforge/rapier3d-compat` namespace: descs, shapes, enums, `QueryFilterFlags`, … */
     readonly rapier: RapierModule;
@@ -86,6 +356,8 @@ interface ClientInfo {
     readonly role: string;
     readonly name: string;
     readonly connected: boolean;
+    /** D44: a scripted NPC spawned by this room, rather than a session dialled from outside. */
+    readonly npc: boolean;
 }
 type TimerHandle = number;
 interface Room<S extends AnySchema = AnySchema> {
@@ -126,6 +398,14 @@ interface Room<S extends AnySchema = AnySchema> {
     save(): Promise<string>;
     /** D25: per-player key/value storage that outlives the room. */
     readonly kv: PlayerKv;
+    /** D53: post scores to this project's leaderboards. Server-authoritative by construction —
+     *  this is the only path a score can take. */
+    readonly leaderboard: RoomLeaderboard;
+    /** D63: report match results to this project's skill ratings. Like the leaderboard, this is
+     *  the only path a rating can move on, and a client cannot reach it. */
+    readonly ratings: RoomRatings;
+    /** D63-e: open or close this room to backfill from the matchmaker, right now. */
+    readonly backfill: RoomBackfill;
     /**
      * D26: arm a durable alarm named `name` to fire at or after `atMs`, **on `room.now`'s clock** —
      * `room.alarm('round', room.now + 15_000)` is the shape to write. (The host translates that to
@@ -149,6 +429,127 @@ interface Room<S extends AnySchema = AnySchema> {
      * config declares no `physics:` throws — that is a mistake worth naming at the call site.
      */
     readonly physics: PhysicsRoomApi<S>;
+    /**
+     * D45: the matter.js engine and the bodies behind physics entities, in a room whose config
+     * declares `engine: 'matter2d'`. Reading it in a Rapier room throws and says so, and so does
+     * reading `room.physics` here.
+     */
+    readonly physics2d: Matter2dRoomApi<S>;
+    /**
+     * 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
+     * `room.clients`, owns entities the way a client does, is judged by the same validators, and
+     * counts toward `maxClients`. It skips only the per-IP connection bucket, which exists to stop
+     * strangers and would otherwise make every NPC room rate-limit itself.
+     *
+     * The handle's `clientId` is available immediately; the session settles a tick or two later, so
+     * an NPC is not in `room.clients` on the line after the call. A spawn into a full room is
+     * refused exactly as a player's join is, with `E_ROOM_FULL` on the room's log.
+     *
+     * NPCs do not keep a room awake: a room whose only occupants are NPCs hibernates as an empty
+     * room does, and room code respawns them in `onWake`.
+     */
+    spawnNPC(config: NpcConfig): NpcHandle;
+    /** D44: despawn by client id. Unknown ids are a warning, not a throw. */
+    despawnNPC(clientId: string): void;
+    /**
+     * D59: the tenant-local bus. Lets one of this project's rooms reach another without bouncing
+     * the message off a client, which was the only way before and is both a latency tax and a trust
+     * bug (a client can lie, drop, or die mid-relay).
+     *
+     * Scoped to this project, always. There is no way to name another project from here, at any
+     * depth: it is not that a cross-project message is refused, it is that the API cannot express
+     * one.
+     */
+    readonly bus: RoomBus;
+}
+/**
+ * D59: two verbs with deliberately unequal guarantees. Read them as a pair, because picking the
+ * wrong one is the mistake this API invites.
+ *
+ * `publish` is the broadcast tier: cheap, best-effort, and it reaches only rooms that happen to be
+ * awake and subscribed right now. `send` is the delivery tier: durable, at-least-once, and it
+ * wakes a hibernated room to run its handler.
+ *
+ * Both are weak on purpose, and will stay weak. Sharding turns `send` into a network hop and
+ * `publish` into a cross-shard fan-out, and a stronger promise made now would be one the platform
+ * had to break later.
+ */
+interface RoomBus {
+    /**
+     * Fan out to every awake room of this project currently subscribed to `channel`. The sender is
+     * never delivered its own publish.
+     *
+     * Nothing queues and nothing wakes. A subscriber that is hibernated simply misses the message,
+     * the same way it misses wall-clock time, and resyncs from state when it wakes. There is no
+     * ordering promise across channels, and none is coming.
+     *
+     * Returns nothing and never throws: a refused publish (an oversized payload, a rate limit) lands
+     * on the room's log. A room that needs to know its message arrived wants `send`.
+     */
+    publish(channel: string, payload: string): void;
+    /**
+     * Join `channel`'s subscriber set. Messages are delivered to the handler declared for that
+     * channel in the room definition's `bus.channels` map; publishing to a channel this room has no
+     * handler for is legal and does nothing here.
+     *
+     * Every declared channel is subscribed automatically when the room starts *and* when it wakes,
+     * so a room that only wants its declared channels never calls this. Call it to leave and rejoin
+     * a channel during a room's life.
+     */
+    subscribe(channel: string): void;
+    /** Leave `channel`'s subscriber set. Leaving one this room is not in is a no-op. */
+    unsubscribe(channel: string): void;
+    /**
+     * Deliver `payload` to one named room of this project, waking it from hibernation if it is
+     * asleep. Resolves when the message is accepted for delivery, and rejects with a named error
+     * when the room does not exist, its mailbox is full, the payload is too big, or this room has
+     * outrun its bus budget.
+     *
+     * **At-least-once, which means the handler can run twice for one send.** Write it idempotent.
+     * The resolve says the message was accepted, not that it was handled.
+     *
+     * The handler is `bus.onMessage` in the target room definition's config, and it is told which
+     * room the message came from. That `from` is stamped by the platform from the sending room's own
+     * record, so a sender cannot forge it.
+     */
+    send(roomId: string, payload: string): Promise<void>;
+}
+/** D59: what a directed `room.bus.send` delivers to the target's `bus.onMessage`. */
+interface BusMessage {
+    /**
+     * The roomId that sent this, stamped by the platform from the sending room's own record. A
+     * sender cannot set it, so a receiver may trust it as far as it trusts its own project.
+     */
+    readonly from: string;
+    readonly payload: string;
+}
+/** D59: what a `publish` delivers to the subscribing room's channel handler. */
+interface BusEvent {
+    readonly channel: string;
+    /** The publishing room. Platform-stamped, like `BusMessage.from`. */
+    readonly from: string;
+    readonly payload: string;
+}
+/** D59: the declared half of the bus. See `RoomConfigBase.bus`. */
+interface BusConfig<S extends AnySchema> {
+    /**
+     * Channel handlers, by channel name. Declaring one subscribes the room to that channel on start
+     * and on every wake.
+     */
+    readonly channels?: Readonly<Record<string, (state: State<S>, event: BusEvent, room: Room<S>) => void>>;
+    /**
+     * The handler for a directed `room.bus.send` to this room.
+     *
+     * **Delivery is at-least-once, so this can run twice for one send.** Write it idempotent: check
+     * before you add, and treat a repeat as normal rather than as a bug. A room with no handler
+     * declared drops what it is sent, with a warning, the same way an alarm with no handler is lost.
+     *
+     * A throw here counts toward the room's crash threshold, as every handler throw does. That is
+     * deliberate and it composes with the delivery bound: a message that always throws is retried a
+     * few times, logged, and dropped, rather than closing the room on every wake forever.
+     */
+    onMessage?(state: State<S>, message: BusMessage, room: Room<S>): void;
 }
 /**
  * D25: player key/value storage, scoped to the project and keyed by a player identity the room
@@ -175,6 +576,145 @@ interface PlayerKv {
     /** Idempotent: deleting a key that is not there still resolves. */
     delete(playerId: string, key: string): Promise<void>;
 }
+/**
+ * D53: the room's half of the leaderboard primitive — one method, and no read.
+ *
+ * ## Why there is no client-side submit, ever
+ *
+ * A score that a client can post is a score a client can forge, and no amount of signing fixes
+ * that: the client is the attacker's machine. So the only path to a board is this one — the room
+ * calls it, the supervisor checks the player is actually in the room, the host agent adds the
+ * project confinement from its own token, and control writes the row. A game that wants a score
+ * on a board computes it in room code.
+ *
+ * What that does and does not buy you is stated plainly, here and in the docs: it means a score
+ * can only come from *your server code*, so a player cannot post 999999 from the console. It does
+ * not mean cheat-proof. If your room code trusts a number a client wrote into its own owned
+ * entity, the board will faithfully record it. Anti-abuse on this platform is server authority
+ * plus rate limits, and there are no hidden heuristics behind that sentence.
+ *
+ * ## Semantics
+ *
+ * **Best score wins**, in the direction the board is configured with (`higher` by default,
+ * `lower` for times and stroke counts). A submit worse than the player's stored score is accepted
+ * and changes nothing; a submit *equal* to it also changes nothing, which is what makes a
+ * duplicate or replayed submit idempotent rather than a fresh tie-break position.
+ *
+ * Scores are whole numbers. Reads are public HTTP on the control plane (top-N and around-me),
+ * so there is deliberately no read here to keep in step with them.
+ */
+/**
+ * D63-e: whether this room is currently willing to take a late joiner from the matchmaker.
+ *
+ * Two states and one verb, because there is nothing else to say. The room type declares
+ * `backfill: true` to be eligible at all; this is how a room that is eligible says "not during a
+ * round". A room that never declared it can call `set(true)` all it likes and will still never be
+ * offered — the declaration is the ceiling, and the report says so.
+ *
+ * The pattern, written out:
+ *
+ * ```ts
+ * // an arena: always open
+ * defineRoom(schema, { backfill: true })
+ *
+ * // a versus game: open between rounds
+ * defineRoom(schema, {
+ *   backfill: true,
+ *   rpc: {
+ *     startRound(state, _params, ctx) { ctx.room.backfill.set(false); ... },
+ *   },
+ *   alarms: { endRound(state, room) { room.backfill.set(true); ... } },
+ * })
+ * ```
+ *
+ * The value rides the room list the host agent already polls, so it reaches the matchmaker within
+ * one poll interval (3 s by default) rather than instantly. That lag is why a backfilled join can
+ * still lose the race for the last seat, and why the client retries the queue once when it does.
+ */
+interface RoomBackfill {
+    /** Open (`true`) or close (`false`) this room to backfill. Idempotent. */
+    set(open: boolean): void;
+    /** The current value. Starts at the declared `backfill` and survives hibernation. */
+    readonly open: boolean;
+}
+interface RoomRatingResult {
+    /** The player id the room was handed (`ctx.playerId`). Anything else is refused. */
+    readonly playerId: string;
+    /** 1-based finishing position. Equal places are a draw; places need not be dense. */
+    readonly place: number;
+}
+/**
+ * D63: the room's half of skill ratings — report a result, or set a number you computed yourself.
+ *
+ * ## Why there is no client-side report, ever
+ *
+ * The same sentence `RoomLeaderboard` opens with. A result a client can post is a result a client
+ * can forge, so the only path to a rating is this one: the room calls it, the supervisor checks
+ * every named player is one this room has actually held, the host agent adds the project
+ * confinement from its own token, and control applies the update.
+ *
+ * What that does and does not buy you, said plainly: it means a rating can only move because
+ * *your server code* said a match happened. It does not mean unriggable. A room that decides the
+ * loser won will be believed, because deciding who won is your game's job and the platform has no
+ * view into it. Anti-abuse here is server authority, and there are no hidden heuristics behind
+ * that sentence.
+ *
+ * ## Semantics
+ *
+ * One `report` is one **rating period**. The placements decompose into every unordered pair
+ * exactly once, each pair reading as a win, a loss or a draw, and every player is updated against
+ * the field as it stood *before* the report — so the answer does not depend on the order you list
+ * them in. The algorithm is Glicko-2 with the paper's seed for a player who has never played
+ * (1500, deviation 350).
+ *
+ * A player whose id is not namespaced (`irt:<subject>` from a platform identity, or `<iss>:<sub>`
+ * from your own JWT) cannot carry a rating: a key-join client id is gone with the socket. Such a
+ * player is accepted in the report and then ignored — they get no rating and nobody is rated
+ * against them.
+ */
+interface RoomRatings {
+    /**
+     * Report one match. `results` names between 2 and 64 players with their finishing places.
+     *
+     * Every `playerId` must be one this room has held since it was created — `ctx.playerId` is the
+     * id to pass. A loser who has already left still counts, which is why the check is "has held"
+     * rather than "currently holds". Anything else rejects with `E_RATING_NOT_IN_ROOM`.
+     *
+     * A malformed report is refused whole rather than in part: `E_RATING_BAD_RESULTS` for a
+     * duplicate player, an out-of-range place, or a list that is too short or too long, and
+     * `E_RATING_BAD_QUEUE` for a queue name that is not one. Like every promise-returning room API,
+     * the continuation runs as its own event between ticks.
+     */
+    report(queue: string, results: readonly RoomRatingResult[]): Promise<void>;
+    /**
+     * Set a rating your own code computed, for a player this room has held.
+     *
+     * `deviation` is optional. Omit it and a player who already has a rating **keeps the deviation
+     * they had**, while a player who does not gets the seed's 350. Volatility is never taken from
+     * here at all.
+     *
+     * Both of those are properties of how a player's results have actually gone, which code handing
+     * over a rating has no view of. Resetting a settled player's deviation to 350 because you did
+     * not mention it would quietly make them provisional again and change who the queue is willing
+     * to match them with. Pass one when you mean to change it.
+     */
+    set(queue: string, playerId: string, value: {
+        readonly rating: number;
+        readonly deviation?: number;
+    }): Promise<void>;
+}
+interface RoomLeaderboard {
+    /**
+     * Post `score` for `playerId` on `board`.
+     *
+     * `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.
+     */
+    submit(board: string, playerId: string, score: number): Promise<void>;
+}
 interface Ctx<S extends AnySchema = AnySchema> {
     readonly clientId: string;
     /**
@@ -218,6 +758,76 @@ interface RoomConfigBase<S extends AnySchema> {
     readonly reconnectGraceMs?: number;
     /** Default 64. */
     readonly maxClients?: number;
+    /**
+     * D63-e: may the matchmaker send a late joiner into this room while it is already running?
+     *
+     * Default false, which is what every room that predates this option is and stays. A room that
+     * says nothing is never offered to a queue, because "a stranger may walk into your game
+     * halfway through" is not a thing to opt anybody into by accident.
+     *
+     * This is the room type's *declaration*. Whether the room is accepting one right now is
+     * `room.backfill.set(open)`, which a versus game closes at round start and opens at round end.
+     * The declaration is the ceiling: a room that never declared it cannot open itself.
+     *
+     * What this flag does NOT do is admit anybody. `maxClients` is still enforced in the worker,
+     * so a backfilled join that loses the race for the last seat is refused with `E_ROOM_FULL`
+     * exactly as any other join would be, and the client retries the queue once. There is no
+     * reservation and no admission hook; the room's own state is the room's business.
+     */
+    readonly backfill?: boolean;
+    /**
+     * D58: how much worker heap this room type declares it needs, in MB.
+     *
+     * Declared rather than inferred. A tenant VM's memory has to be divided between the rooms that
+     * are awake in it, and without a declaration the supervisor can only give every room the same
+     * derived cap, which means a notifications room that holds a few hundred bytes is sized like the
+     * physics room next to it. With one, the VM budget becomes arithmetic the supervisor can check
+     * at boot: the declared budgets of the awake mix, plus its own baseline, plus a native reserve.
+     *
+     * Omit it and the room keeps the cap derived from the VM (or the generous dev default). Declare
+     * it and this is the worker's old-generation limit, which is a hard ceiling: a room that exceeds
+     * it dies as a room crash rather than taking its siblings' VM down with it.
+     */
+    readonly memoryMb?: number;
+    /**
+     * M5 part 3.5: how many rooms of this type may be awake at the same time in one tenant.
+     *
+     * This is the second half of `memoryMb`, and without it the first half cannot size anything. A
+     * declared heap says what one room costs; a tenant VM has to hold every room that is awake in
+     * it, and until this existed nothing could turn "96 MB per arena" into "how big is the machine".
+     * Part 2 summed every declared type exactly once and wrote the pessimism down as a debt; this is
+     * the number that discharges it.
+     *
+     * It is **enforced, not advisory**: the supervisor refuses to start room N+1 of a type with an
+     * error naming the type, the limit and this field. That refusal is what makes the arithmetic
+     * true rather than optimistic. Raising it is a declaration change, so it takes effect at the
+     * tenant's next placement rather than immediately, and it grows the VM.
+     *
+     * Omit it and the type is counted at one awake room, which is the conservative reading and what
+     * an undeclared project has always effectively been given.
+     */
+    readonly maxAwake?: number;
+    /**
+     * How long a room of this type outlives its last activity, as `'<n>m'`, `'<n>h'` or `'<n>d'`.
+     *
+     * Omit it and the room's state is kept forever, which is what every room has always had and
+     * stays the default. Declare it and the platform deletes the room's stored state once that long
+     * has passed since the room last went to sleep: its snapshot, its save generations and its
+     * durable alarms. Player KV and leaderboards are keyed to the player rather than to the room and
+     * are never touched.
+     *
+     * This is the one declaration in a room file that deletes data, so it is deliberately awkward to
+     * write by accident: the value is a duration string rather than a number of milliseconds, the
+     * grammar takes one integer and one unit (no `'1h30m'`, no seconds, no fractions), and the floor
+     * is one minute. Anything else is refused here by name rather than rounded into something
+     * plausible.
+     *
+     * The window is a floor, not a deadline. The platform sweeps for expired rooms on a fixed
+     * cadence, so `'10m'` means "at least ten minutes, then deleted on the next sweep". Declare it
+     * on room types whose state is worth nothing once the players have gone: a match, a lobby, a
+     * draft. Do not declare it on a room holding anything a player expects to come back to.
+     */
+    readonly retention?: string;
     /**
      * D22: run a Rapier world on the fixed timestep. Tick mode only. Every collection whose schema
      * declares `physics` needs an entry in `bodies`, and vice versa.
@@ -233,6 +843,31 @@ interface RoomConfigBase<S extends AnySchema> {
      * surviving hibernation is the entire point of D26. This map is code, so it is always there.
      */
     readonly alarms?: Readonly<Record<string, (state: State<S>, room: Room<S>) => void>>;
+    /**
+     * D59: the room's bus handlers.
+     *
+     * They live in the config for the same reason `alarms` does, and it is the load-bearing reason
+     * rather than a stylistic one: a `send` wakes a hibernated room to deliver, and a handler
+     * registered at runtime would not have survived the hibernation. This map is code, so it is
+     * always there, including on the first tick after a wake.
+     *
+     * Declaring a channel in `channels` also subscribes the room to it, on start and on every wake.
+     * That is what makes the common case require no `room.bus.subscribe` call and what makes the
+     * subscription come back after a hibernation the bus deliberately dropped it across.
+     */
+    readonly bus?: BusConfig<S>;
+    /**
+     * D44: NPC brains, by name. `room.spawnNPC({ brain: { kind: 'script', script: 'chaser' } })`
+     * runs the entry called `chaser`.
+     *
+     * They live in the config, like `alarms`, for a sharper reason than symmetry: the script runs in
+     * the **supervisor** process, driving a real client session, and the only thing that crosses the
+     * worker boundary is its name. A callback passed to `spawnNPC` could not make that trip.
+     *
+     * These are the only handlers in a room definition that may be async, because a bot script is a
+     * loop that awaits: `while (!npc.stopped) { …; await npc.wait(100) }`.
+     */
+    readonly npcs?: Readonly<Record<string, NpcScript<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;
@@ -254,6 +889,7 @@ interface ResolvedRoomConfig<S extends AnySchema> extends RoomConfigBase<S> {
     readonly idleMs: number;
     readonly reconnectGraceMs: number;
     readonly maxClients: number;
+    readonly backfill: boolean;
     readonly rpc: RpcImplementations<S>;
 }
 interface RoomDefinition<S extends AnySchema = AnySchema> {
@@ -269,7 +905,52 @@ declare const DEFAULTS: {
     readonly idleMs: 30000;
     readonly reconnectGraceMs: 30000;
     readonly maxClients: 64;
+    readonly backfill: false;
 };
+/**
+ * The ceiling on a declared `maxAwake`.
+ *
+ * Kept as a literal here rather than imported from `@irtio/protocol`'s `MAX_AWAKE_MAX`, which is
+ * the same number for the same reason. `@irtio/server` is on the room-bundle side of the fence:
+ * everything it imports is bundled into every deployed room, and taking a dependency on the fleet
+ * protocol module to read one integer would put the whole of it there. The two are pinned equal by
+ * `packages/protocol/test/sizing.test.ts`'s companion assertion in the server's own tests, so a
+ * drift is a failing test rather than a silently different limit.
+ */
+declare const MAX_AWAKE_MAX = 256;
+/**
+ * The bounds on a declared `memoryMb`.
+ *
+ * Literals here for the same fence reason as {@link MAX_AWAKE_MAX}: `@irtio/server` is on the
+ * room-bundle side, so it may not import `@irtio/protocol`'s `ROOM_MEMORY_MB_MIN` /
+ * `ROOM_MEMORY_MB_MAX` to read two integers. `packages/supervisor/test/declaration-doors.test.ts`
+ * asserts the pairs equal from a package that legitimately depends on both, so a drift is a failing
+ * test rather than two doors with different opinions about the same number.
+ *
+ * The floor is the one `deriveWorkerHeapCaps` uses: below it a worker cannot boot a room at all, so
+ * accepting a smaller declaration would only move the failure later. The ceiling is M5 part 3.6's:
+ * 1024 is Large's advertised and priced 1 GiB basis, and a declaration above it would be a room
+ * paying Large's rate for memory no class covers.
+ */
+declare const MEMORY_MB_MIN = 32;
+declare const MEMORY_MB_MAX = 1024;
+/**
+ * The grammar and the bounds on a declared `retention`.
+ *
+ * Literals here for the same fence reason as {@link MEMORY_MB_MIN}: `@irtio/server` is bundled
+ * into every deployed room, so it may not import `@irtio/protocol`'s `RETENTION_RE`,
+ * `RETENTION_MIN_MS` and `RETENTION_MAX_MS` to read one pattern and two integers.
+ * `packages/supervisor/test/declaration-doors.test.ts` asserts the pairs equal from a package that
+ * legitimately depends on both, so a drift is a failing test rather than two doors with different
+ * opinions about which declarations delete data.
+ *
+ * A whole minute is the floor because the platform sweeps for expired rooms on a cadence measured
+ * in minutes: a shorter window would be a number the platform could not honour. Ten years is the
+ * ceiling because a longer one is asking for "forever", which is written by leaving the field out.
+ */
+declare const RETENTION_RE: RegExp;
+declare const RETENTION_MIN_MS = 60000;
+declare const RETENTION_MAX_MS: number;
 /**
  * Validates a room config and returns the definition the runtime loads. Throws on: unknown
  * mode, bad tickRate, `tick` missing in tick mode or present in event mode, `async`/generator
@@ -280,4 +961,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 BodyFactories, type BodySpec, type ClientInfo, type Ctx, DEFAULTS, type LeaveReason, type MessageTarget, type PhysicsConfig, type PhysicsRoomApi, type PlayerKv, ROOM_DEFINITION_VERSION, type RapierColliderDesc, type RapierModule, type RapierRigidBody, type RapierRigidBodyDesc, type RapierWorld, type ResolvedRoomConfig, type Room, type RoomConfig, type RoomConfigBase, type RoomDefinition, type RoomMode, type RpcImplementations, type TimerHandle, type Validators, type Vector3, defineRoom, isRoomDefinition };
+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 };

package/dist/index.js

@@ -1,3 +1,47 @@
+// src/npc.ts
+var ZERO = { x: 0, y: 0 };
+function scaleTo(dx, dy, speed) {
+  const len = Math.hypot(dx, dy);
+  if (len === 0 || speed === 0) return ZERO;
+  return { x: dx / len * speed, y: dy / len * speed };
+}
+function seek(from, to, speed) {
+  return scaleTo(to.x - from.x, to.y - from.y, speed);
+}
+function flee(from, threat, speed) {
+  return scaleTo(from.x - threat.x, from.y - threat.y, speed);
+}
+function arrive(from, to, speed, slowRadius) {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const dist = Math.hypot(dx, dy);
+  if (dist === 0) return ZERO;
+  const wanted = slowRadius > 0 && dist < slowRadius ? speed * dist / slowRadius : speed;
+  return scaleTo(dx, dy, wanted);
+}
+function newWander(random) {
+  return { angle: random() * Math.PI * 2 };
+}
+function wander(state, speed, turn, random) {
+  state.angle += (random() * 2 - 1) * turn;
+  return { x: Math.cos(state.angle) * speed, y: Math.sin(state.angle) * speed };
+}
+function patrol(from, waypoints, index, speed, reachedRadius) {
+  if (waypoints.length === 0) return { velocity: ZERO, index: 0 };
+  let at = (index % waypoints.length + waypoints.length) % waypoints.length;
+  const target = waypoints[at];
+  if (Math.hypot(target.x - from.x, target.y - from.y) <= reachedRadius) {
+    at = (at + 1) % waypoints.length;
+  }
+  return { velocity: seek(from, waypoints[at], speed), index: at };
+}
+function choose(behaviours) {
+  for (const b of behaviours) {
+    if (b.when()) return b;
+  }
+  return void 0;
+}
+
 // src/index.ts
 var ROOM_DEFINITION_VERSION = 1;
 var DEFAULTS = {
@@ -5,8 +49,29 @@ var DEFAULTS = {
   tickRate: 20,
   idleMs: 3e4,
   reconnectGraceMs: 3e4,
-  maxClients: 64
+  maxClients: 64,
+  // D63-e: off. A room is not offered to strangers unless it says so.
+  backfill: false
+};
+var MAX_AWAKE_MAX = 256;
+var MEMORY_MB_MIN = 32;
+var MEMORY_MB_MAX = 1024;
+var RETENTION_RE = /^[1-9][0-9]{0,4}(m|h|d)$/;
+var RETENTION_MIN_MS = 6e4;
+var RETENTION_MAX_MS = 3650 * 24 * 60 * 60 * 1e3;
+var RETENTION_UNIT_MS = {
+  m: 6e4,
+  h: 60 * 60 * 1e3,
+  d: 24 * 60 * 60 * 1e3
 };
+function parseRetentionDeclaration(raw) {
+  if (typeof raw !== "string" || !RETENTION_RE.test(raw)) return void 0;
+  const scale = RETENTION_UNIT_MS[raw.slice(-1)];
+  if (scale === void 0) return void 0;
+  const ms = Number(raw.slice(0, -1)) * scale;
+  if (ms < RETENTION_MIN_MS || ms > RETENTION_MAX_MS) return void 0;
+  return ms;
+}
 var HANDLER_KEYS = [
   "onCreate",
   "onJoin",
@@ -29,6 +94,28 @@ function defineRoom(schema, config) {
   if (!Number.isInteger(tickRate) || tickRate < 1 || tickRate > 240) {
     throw new Error(`defineRoom: tickRate must be an integer in 1..240, got ${String(tickRate)}`);
   }
+  if (config.memoryMb !== void 0) {
+    if (!Number.isInteger(config.memoryMb) || config.memoryMb < MEMORY_MB_MIN || config.memoryMb > MEMORY_MB_MAX) {
+      throw new Error(
+        `defineRoom: memoryMb must be an integer in ${MEMORY_MB_MIN}..${MEMORY_MB_MAX} MB, got ${String(config.memoryMb)}`
+      );
+    }
+  }
+  if (config.maxAwake !== void 0) {
+    if (!Number.isInteger(config.maxAwake) || config.maxAwake < 1 || config.maxAwake > MAX_AWAKE_MAX) {
+      throw new Error(
+        `defineRoom: maxAwake must be an integer in 1..${MAX_AWAKE_MAX}, got ${String(config.maxAwake)}`
+      );
+    }
+  }
+  if (config.retention !== void 0) {
+    const ms = parseRetentionDeclaration(config.retention);
+    if (ms === void 0) {
+      throw new Error(
+        `defineRoom: retention must be a duration like '10m', '6h' or '30d' between 1m and 3650d, got ${JSON.stringify(config.retention)}`
+      );
+    }
+  }
   for (const k of ["idleMs", "reconnectGraceMs", "maxClients"]) {
     const v = config[k];
     if (v !== void 0 && (!Number.isFinite(v) || v < 0)) {
@@ -63,6 +150,7 @@ function defineRoom(schema, config) {
     }
   }
   checkPhysics(schema, config, mode);
+  checkNpcs(config);
   const resolved = {
     ...config,
     mode,
@@ -70,6 +158,7 @@ function defineRoom(schema, config) {
     idleMs: config.idleMs ?? DEFAULTS.idleMs,
     reconnectGraceMs: config.reconnectGraceMs ?? DEFAULTS.reconnectGraceMs,
     maxClients: config.maxClients ?? DEFAULTS.maxClients,
+    backfill: config.backfill === true,
     rpc
   };
   return Object.freeze({
@@ -79,6 +168,19 @@ function defineRoom(schema, config) {
     config: Object.freeze(resolved)
   });
 }
+function checkNpcs(config) {
+  const npcs = config.npcs;
+  if (npcs === void 0) return;
+  if (typeof npcs !== "object" || npcs === null || Array.isArray(npcs)) {
+    throw new Error("defineRoom: npcs must be an object mapping a name to a script function");
+  }
+  for (const [name, fn] of Object.entries(npcs)) {
+    if (name === "") throw new Error("defineRoom: an npcs key must not be empty");
+    if (typeof fn !== "function") {
+      throw new Error(`defineRoom: npcs.${name} must be a function taking the npc object`);
+    }
+  }
+}
 function checkPhysics(schema, config, mode) {
   const declared = schema.collections.filter((c) => c.physics !== void 0).map((c) => c.name);
   const physics = config.physics;
@@ -100,14 +202,19 @@ 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") {
+  if (physics.engine !== "rapier3d" && physics.engine !== "matter2d") {
     throw new Error(
-      `defineRoom: physics.engine must be 'rapier3d' (got ${JSON.stringify(physics.engine)}); matter.js is not in M2`
+      `defineRoom: physics.engine must be 'rapier3d' or 'matter2d', got ${JSON.stringify(
+        physics.engine
+      )}`
     );
   }
   const g = physics.gravity;
-  if (!g || typeof g !== "object" || !Number.isFinite(g.x) || !Number.isFinite(g.y) || !Number.isFinite(g.z)) {
-    throw new Error("defineRoom: physics.gravity must be { x, y, z } finite numbers");
+  const planar = physics.engine === "matter2d";
+  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"
+    );
   }
   if (physics.timestep !== void 0 && (!Number.isFinite(physics.timestep) || physics.timestep <= 0)) {
     throw new Error(
@@ -128,6 +235,20 @@ function checkPhysics(schema, config, mode) {
       parts.push(`physics.bodies names collections without schema physics: ${extra.join(", ")}`);
     throw new Error(`defineRoom: ${parts.join("; ")}`);
   }
+  const intents = physics.intents;
+  if (intents !== void 0) {
+    if (typeof intents !== "object" || intents === null) {
+      throw new Error("defineRoom: physics.intents must be an object of collection -> hook");
+    }
+    for (const [k, fn] of Object.entries(intents)) assertSyncHandler(fn, `physics.intents.${k}`);
+    const steerable = schema.collections.filter((c) => c.physics !== void 0 && c.physics.intents.length > 0).map((c) => c.name);
+    const unsteerable = Object.keys(intents).filter((n) => !steerable.includes(n));
+    if (unsteerable.length) {
+      throw new Error(
+        `defineRoom: physics.intents names ${unsteerable.join(", ")}, which declare no intents in the schema. A steering hook turns the fields a client may write into forces, so the collection has to declare them: entity(fields, { physics: { body, intents: [...] } }). Collections that do: ${steerable.length ? steerable.join(", ") : "none"}`
+      );
+    }
+  }
 }
 function assertSyncHandler(fn, name) {
   if (fn === void 0) return;
@@ -144,7 +265,20 @@ function isRoomDefinition(v) {
 }
 export {
   DEFAULTS,
+  MAX_AWAKE_MAX,
+  MEMORY_MB_MAX,
+  MEMORY_MB_MIN,
+  RETENTION_MAX_MS,
+  RETENTION_MIN_MS,
+  RETENTION_RE,
   ROOM_DEFINITION_VERSION,
+  arrive,
+  choose,
   defineRoom,
-  isRoomDefinition
+  flee,
+  isRoomDefinition,
+  newWander,
+  patrol,
+  seek,
+  wander
 };

package/package.json

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