@irtio/server 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AnySchema, RoleOf, VisibleKeys, SchemaDefs, EntityDef, ReadonlyCollection, DeepReadonly, InferFields, Owned, SingletonDef, PhysicsKeys, InstanceOf, State, ServerCallProxy, SchemaRpc, BroadcastProxy, OwnableKeys, Implementations, ServerRpcs } from '@irtio/schema';
+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 RAPIER from '@dimforge/rapier3d-compat';
 import * as MATTER from 'matter-js';
 
@@ -195,6 +195,7 @@ 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;
 type MatterModule = typeof MATTER;
@@ -253,6 +254,50 @@ 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` 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;
+    };
+    /** 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,6 +350,8 @@ 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;
 }
 type PhysicsConfig<S extends AnySchema> = RapierPhysicsConfig<S> | Matter2dPhysicsConfig<S>;
 /**
@@ -351,6 +398,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 +430,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 +503,38 @@ interface Room<S extends AnySchema = AnySchema> {
      * reading `room.physics` here.
      */
     readonly physics2d: Matter2dRoomApi<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
@@ -703,6 +803,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 +823,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 +848,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>;
@@ -878,8 +1013,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 +1107,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, 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 };

package/dist/index.js

@@ -1,3 +1,6 @@
+// src/physics.ts
+var HISTORY_MAX_TICKS = 240;
+
 // src/npc.ts
 var ZERO = { x: 0, y: 0 };
 function scaleTo(dx, dy, speed) {
@@ -221,6 +224,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 +276,7 @@ function isRoomDefinition(v) {
 }
 export {
   DEFAULTS,
+  HISTORY_MAX_TICKS,
   MAX_AWAKE_MAX,
   MEMORY_MB_MAX,
   MEMORY_MB_MIN,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/server",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "irtio room-file API: defineRoom, handler and ctx types",
   "license": "MIT",
   "publishConfig": {
@@ -20,7 +20,7 @@
     "dist"
   ],
   "dependencies": {
-    "@irtio/schema": "0.6.0"
+    "@irtio/schema": "0.7.0"
   },
   "peerDependencies": {
     "@dimforge/rapier3d-compat": ">=0.20.0",