@irtio/server 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -441,10 +441,41 @@ 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;
+    readonly history?: HistoryConfig;
 }
+/**
+ * D72+: one physics collection's declared history channels.
+ *
+ * Method syntax for `read`, so a hook written against its own instance type is accepted: the
+ * values really passed are the schema's records for that collection. Same precedent as
+ * {@link Matter2dIntentHook}.
+ */
+interface HistoryChannelSpec {
+    /** How many f32s per entity per tick, 1..{@link HISTORY_MAX_CHANNELS}. */
+    readonly count: number;
+    /**
+     * Fills `out` (length `count`, pre-zeroed) from the instance's record, once per body per tick.
+     * `instance` is a read-only view: writes through it do not dirty synced state.
+     */
+    read(instance: Record<string, unknown>, out: Float32Array): void;
+}
+/**
+ * D72: the `physics.history` declaration. A bare number is a depth in ticks and means exactly what
+ * it has always meant; the object form adds per-collection channels on the same ring and the same
+ * lifecycle. Keys of `channels` name physics collections.
+ */
+type HistoryConfig = number | {
+    readonly depth: number;
+    readonly channels?: Readonly<Record<string, HistoryChannelSpec>>;
+};
 /** D72: the deepest history a room may declare, in ticks. One second at the maximum tick rate. */
 declare const HISTORY_MAX_TICKS = 240;
+/**
+ * D72+: the most history channels one physics collection may declare. Enough for a crouch phase, a
+ * run phase and a few bone parameters; a room wanting a full skeleton per tick should keep its own
+ * ring rather than push this up.
+ */
+declare const HISTORY_MAX_CHANNELS = 8;
 /**
  * D72: what `room.rewind(tick, fn)` hands `fn`.
  *
@@ -466,6 +497,14 @@ interface RewindView {
      * remember", and a room that would rather refuse a clamped answer can read this and do so.
      */
     readonly clamped: boolean;
+    /**
+     * D72+: the declared history channels for one entity at the answered tick, in declaration order,
+     * length `count`. `undefined` when the collection declares no channels or when the entity was not
+     * present at that tick.
+     *
+     * The array is a view into the ring: read it inside `fn`, do not hold it and do not write to it.
+     */
+    channels(collection: string, id: string): Float32Array | undefined;
     /** rapier3d rooms: a scratch world to `castRay` / `castShape` / `intersectionsWithShape` on. */
     readonly rapier?: {
         readonly world: RapierWorld;
@@ -546,7 +585,7 @@ interface Matter2dPhysicsConfig<S extends AnySchema> {
      */
     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;
+    readonly history?: HistoryConfig;
 }
 /**
  * The rapier2d counterpart to {@link Matter2dIntentHook}: one step of steering for one body, from
@@ -595,7 +634,7 @@ interface Rapier2dPhysicsConfig<S extends AnySchema> {
      */
     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;
+    readonly history?: HistoryConfig;
 }
 /** `room.physicsRapier2d` in a rapier2d room. */
 interface Rapier2dRoomApi<S extends AnySchema> {
@@ -674,6 +713,21 @@ interface ClientInfo {
 type TimerHandle = number;
 interface Room<S extends AnySchema = AnySchema> {
     readonly id: string;
+    /**
+     * The room's tracked state — the very object every handler already gets as its first argument.
+     *
+     * It is here for the one place that has a `room` and no `state` parameter: `physics.setup`.
+     * Static geometry that depends on what the room holds (a level chosen at create, a layout
+     * restored from a snapshot) had no way to read it, and the workaround was a module-level
+     * variable set by `onCreate` — which runs *after* setup on a fresh room, so it was empty
+     * exactly when it mattered.
+     *
+     * What it holds at setup time: on a wake that had to rebuild the world, the snapshot is already
+     * decoded, so restored state is fully readable. On a fresh room it is the schema's defaults with
+     * no entities: `onCreate` has not run yet. Do not reach for `room.physics` inside setup — the
+     * world being built is the one setup is holding.
+     */
+    readonly state: State<S>;
     /** Shareable URL (`?room=<id>`). */
     readonly link: string;
     readonly tick: number;
@@ -683,6 +737,12 @@ interface Room<S extends AnySchema = AnySchema> {
     readonly clients: readonly ClientInfo[];
     /** Seeded, recorded for replay. */
     random(): number;
+    /**
+     * The resolved RNG seed: `options.seed` when given, otherwise derived from the room id.
+     * Stable for the room's whole life, survives hibernation. Use it directly for procedural
+     * generation that every client must be able to reproduce.
+     */
+    readonly seed: number;
     send(target: MessageTarget, bytes: Uint8Array): void;
     /**
      * D70: `room.messages.<name>.send(target, value)` — one of the shapes the schema declares,
@@ -709,6 +769,16 @@ interface Room<S extends AnySchema = AnySchema> {
     call(clientId: string): ServerCallProxy<SchemaRpc<S>>;
     /** Server → client void RPCs to every connected client. */
     readonly broadcast: BroadcastProxy<SchemaRpc<S>>;
+    /**
+     * The same broadcast, minus the client(s) named — `room.broadcastExcept(ctx.clientId).hit({…})`.
+     *
+     * The thing it replaces: a `from` field on the payload, and a filter on receipt in every client.
+     * That shape sends the actor its own echo, costs a schema field per RPC, and gets the comparison
+     * wrong exactly once per game. Typed identically to `broadcast` — void client-direction RPCs
+     * only. An id that is not connected (or never existed) is skipped rather than refused, so
+     * "everyone except the player who just left" is safe to say.
+     */
+    broadcastExcept(clientId: string | readonly string[]): BroadcastProxy<SchemaRpc<S>>;
     /**
      * D24: write a retained, addressable snapshot generation of this room right now and resolve
      * with its save id. Like every promise-returning room API, the continuation runs as its own
@@ -1390,4 +1460,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, 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 };
+export { type Behaviour, type BodyFactories, type BodySpec, type BusConfig, type BusEvent, type BusMessage, type ClientInfo, type Ctx, DEFAULTS, HISTORY_MAX_CHANNELS, HISTORY_MAX_TICKS, type HistoryChannelSpec, type HistoryConfig, 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

@@ -71,6 +71,7 @@ function lobbyConfigProblem(value) {
 
 // src/physics.ts
 var HISTORY_MAX_TICKS = 240;
+var HISTORY_MAX_CHANNELS = 8;
 
 // src/npc.ts
 var ZERO = { x: 0, y: 0 };
@@ -317,11 +318,45 @@ function checkPhysics(schema, config, mode) {
   }
   const history = physics.history;
   if (history !== void 0) {
-    if (!Number.isInteger(history) || history < 0 || history > HISTORY_MAX_TICKS) {
+    const depth = typeof history === "object" && history !== null ? history.depth : history;
+    if (!Number.isInteger(depth) || depth < 0 || depth > HISTORY_MAX_TICKS) {
+      const field = typeof history === "object" && history !== null ? "physics.history.depth" : "physics.history";
       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)}`
+        `defineRoom: ${field} must be an integer in 0..${HISTORY_MAX_TICKS} ticks (0 or absent means no history and no cost), got ${String(depth)}`
       );
     }
+    const channels = typeof history === "object" && history !== null ? history.channels : void 0;
+    if (channels !== void 0) {
+      if (typeof channels !== "object" || channels === null) {
+        throw new Error(
+          `defineRoom: physics.history.channels must be an object keyed by physics collection, got ${String(channels)}`
+        );
+      }
+      const collections = Object.keys(physics.bodies ?? {});
+      for (const [name, spec] of Object.entries(channels)) {
+        if (!collections.includes(name)) {
+          throw new Error(
+            `defineRoom: physics.history.channels.${name} names no physics collection`
+          );
+        }
+        if (typeof spec !== "object" || spec === null) {
+          throw new Error(
+            `defineRoom: physics.history.channels.${name} must be { count, read }, got ${String(spec)}`
+          );
+        }
+        const count = spec.count;
+        if (!Number.isInteger(count) || count < 1 || count > HISTORY_MAX_CHANNELS) {
+          throw new Error(
+            `defineRoom: physics.history.channels.${name}.count must be an integer in 1..${HISTORY_MAX_CHANNELS}, got ${String(count)}`
+          );
+        }
+        if (typeof spec.read !== "function") {
+          throw new Error(
+            `defineRoom: physics.history.channels.${name}.read must be a function (instance, out) => void`
+          );
+        }
+      }
+    }
   }
   assertSyncHandler(physics.setup, "physics.setup");
   const bodies = physics.bodies ?? {};
@@ -367,6 +402,7 @@ function isRoomDefinition(v) {
 }
 export {
   DEFAULTS,
+  HISTORY_MAX_CHANNELS,
   HISTORY_MAX_TICKS,
   LOBBY_MEMBERS,
   LOBBY_MIN_PLAYERS,

package/package.json

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