@irtio/server 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,75 @@
-import { AnySchema, RoleOf, ServerCallProxy, SchemaRpc, BroadcastProxy, State, OwnableKeys, DeepReadonly, SchemaDefs, InstanceOf, Implementations, ServerRpcs } from '@irtio/schema';
+import { AnySchema, PhysicsKeys, DeepReadonly, SchemaDefs, InstanceOf, RoleOf, ServerCallProxy, SchemaRpc, BroadcastProxy, State, OwnableKeys, Implementations, ServerRpcs } from '@irtio/schema';
+import RAPIER from '@dimforge/rapier3d-compat';
+
+/**
+ * The room-side physics surface (D22): `physics:` on the room config, and `room.physics` inside
+ * handlers.
+ *
+ * Two rules shape this file. **Colliders are code, not config** (D15's spirit): static geometry
+ * is built by `setup(world, rapier, room)` and a body's shape comes from a per-collection factory
+ * — irtio never invents a schema syntax for a capsule. And **the engine is blessed, not
+ * abstracted**: room code gets the real `@dimforge/rapier3d-compat` `World` and the real
+ * namespace, so every Rapier tutorial on the internet applies unchanged.
+ *
+ * The rapier import here is `import type` only — it erases at build time, so `@irtio/server`
+ * carries no runtime dependency on it and a non-physics game never installs it (the package is an
+ * *optional* peer dependency; `skipLibCheck` keeps the unresolved type quiet when it is absent).
+ */
+
+type RapierModule = typeof RAPIER;
+type RapierWorld = RAPIER.World;
+type RapierRigidBody = RAPIER.RigidBody;
+type RapierRigidBodyDesc = RAPIER.RigidBodyDesc;
+type RapierColliderDesc = RAPIER.ColliderDesc;
+interface Vector3 {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/** What a body factory returns: the rigid body, plus the colliders attached to it. */
+interface BodySpec {
+    readonly body: RapierRigidBodyDesc;
+    /** Attached to the body in order. A body with none is a valid (invisible) point mass. */
+    readonly colliders?: readonly RapierColliderDesc[];
+}
+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
+ * first sees an instance (and again after a wake that had to rebuild the world). The pose and
+ * velocity the schema's body fields already hold are applied *after* the desc, so `add()` places
+ * the body: a factory only has to describe shape and material.
+ */
+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). */
+    readonly engine: 'rapier3d';
+    readonly gravity: Vector3;
+    /** Seconds per world step. Defaults to the tick interval; one step per tick, no substeps. */
+    readonly timestep?: number;
+    /**
+     * Static geometry, joints, world tuning. Runs once per world — at room create, and on a wake
+     * that had to rebuild (a pre-physics snapshot, or a schema migration). It does **not** run on
+     * an ordinary wake: the world came back from the snapshot with its static colliders in it.
+     */
+    setup?(world: RapierWorld, rapier: RapierModule, room: Room<S>): void;
+    readonly bodies: BodyFactories<S>;
+}
+/** `room.physics` — what handlers use to turn intents into forces. */
+interface PhysicsRoomApi<S extends AnySchema> {
+    /** The `@dimforge/rapier3d-compat` namespace: descs, shapes, enums, `QueryFilterFlags`, … */
+    readonly rapier: RapierModule;
+    /** The live world. Ray casts, static colliders added later, joints. */
+    readonly world: RapierWorld;
+    /** Seconds per step (`world.timestep`). */
+    readonly timestep: number;
+    /**
+     * The rigid body backing an instance. Created on demand, so an entity added earlier in this
+     * same handler already has one. `undefined` only when the instance does not exist.
+     */
+    body(collection: PhysicsKeys<S> & string, id: string): RapierRigidBody | undefined;
+}
 
 /**
  * `@irtio/server` — what `irtio/room.ts` imports. `defineRoom(schema, config)` validates the
@@ -44,9 +115,77 @@ 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>>;
+    /**
+     * 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
+     * event between ticks — see `PlayerKv` for what that costs you.
+     *
+     * A failed save rejects and changes nothing: the room's live hibernation snapshot is never
+     * touched by `save()`, so a room can never be left worse off than if it had not saved.
+     */
+    save(): Promise<string>;
+    /** D25: per-player key/value storage that outlives the room. */
+    readonly kv: PlayerKv;
+    /**
+     * 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
+     * wall clock on the way out, because an alarm outlives the process `room.now` is monotonic
+     * within; a room never has to think about it, but it does have to compute `atMs` from
+     * `room.now` rather than from anything else.) Arming a name that is already armed replaces its
+     * due time, which is what makes re-arming from inside an alarm handler the way to build a
+     * repeating timer.
+     *
+     * The handler is the entry for `name` in the room definition's `alarms` map — arming a name
+     * with no handler is a warning and does nothing. Alarms survive hibernation *and* a tenant
+     * stop; the guaranteed resolution is seconds, and an alarm fires at-or-after `atMs`, never
+     * before. See the room reference at irt.io/docs/reference/room for the worst-case lateness a
+     * game should design for.
+     */
+    alarm(name: string, atMs: number): void;
+    /** D26: cancel the alarm named `name`. Cancelling an unarmed name is a no-op. */
+    cancelAlarm(name: string): void;
+    /**
+     * D22: the Rapier world and the bodies behind physics entities. Reading it in a room whose
+     * config declares no `physics:` throws — that is a mistake worth naming at the call site.
+     */
+    readonly physics: PhysicsRoomApi<S>;
+}
+/**
+ * D25: player key/value storage, scoped to the project and keyed by a player identity the room
+ * chooses. It is the first state irtio keeps that is *not* room state: it lives in the control
+ * plane, it outlives the room, and another room of the same project reads back what this one
+ * wrote.
+ *
+ * **Every method returns a Promise whose continuation runs as its own event between ticks** —
+ * exactly the shape `room.call(clientId)` already has. Room handlers are synchronous and there
+ * is no way to block one on I/O, so a KV read is *not* available in the handler that asked for
+ * it. State mutated in the continuation is tracked and flushed normally.
+ *
+ * Confinement is per **project**, not per player: a room may pass any `playerId` and can read
+ * another player's row on purpose. A cross-project read is refused by the gateway.
+ *
+ * Values are strings (JSON-encode structured data yourself), at most 16 KiB of UTF-8. Rejections
+ * name the limit they hit — `E_KV_VALUE_TOO_LARGE`, `E_KV_TOO_MANY_KEYS`,
+ * `E_KV_PROJECT_FULL`, `E_KV_BAD_KEY`, `E_KV_UNAVAILABLE` — and the room keeps running.
+ */
+interface PlayerKv {
+    /** Resolves `undefined` for a key that was never written — a miss is not an error. */
+    get(playerId: string, key: string): Promise<string | undefined>;
+    set(playerId: string, key: string, value: string): Promise<void>;
+    /** Idempotent: deleting a key that is not there still resolves. */
+    delete(playerId: string, key: string): Promise<void>;
 }
 interface Ctx<S extends AnySchema = AnySchema> {
     readonly clientId: string;
+    /**
+     * D25: the identity `room.kv` is meant to be keyed by. For a **key join** it is the
+     * resume-token identity — the client id a resume token carries across a reconnect — so it is
+     * stable only as long as that token is, and a player who comes back after it expires is a new
+     * `playerId`. For a **JWT join** (D27, week 13) it is the durable `"<iss>:<sub>"` the verified
+     * token asserted, namespaced by issuer so two issuers can never collide. Adopting JWT starts a
+     * player's storage over: old client-id-keyed rows stay where they are, by decision.
+     */
+    readonly playerId: string;
     readonly role: RoleOf<S> & string;
     readonly name: string;
     /** Server tick this join/call/write is applied at. */
@@ -79,6 +218,21 @@ interface RoomConfigBase<S extends AnySchema> {
     readonly reconnectGraceMs?: number;
     /** Default 64. */
     readonly maxClients?: number;
+    /**
+     * 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.
+     */
+    readonly physics?: PhysicsConfig<S>;
+    /**
+     * D26: durable alarm handlers, by name. `room.alarm(name, atMs)` arms one; the entry here runs
+     * when it fires, as its own event between ticks — the same scheduling class as an RPC, so a
+     * tick-mode room never runs a half-alarmed `tick`.
+     *
+     * Handlers live in the **config**, not in a runtime registration, precisely because an alarm
+     * outlives the room: a callback handed to the runtime would be gone after a hibernation, and
+     * 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>>;
     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;
@@ -126,4 +280,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 ClientInfo, type Ctx, DEFAULTS, type LeaveReason, type MessageTarget, ROOM_DEFINITION_VERSION, type ResolvedRoomConfig, type Room, type RoomConfig, type RoomConfigBase, type RoomDefinition, type RoomMode, type RpcImplementations, type TimerHandle, type Validators, defineRoom, isRoomDefinition };
+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 };

package/dist/index.js

@@ -62,6 +62,7 @@ function defineRoom(schema, config) {
       throw new Error(`defineRoom: validate.${k} must name an instance-owned entity collection`);
     }
   }
+  checkPhysics(schema, config, mode);
   const resolved = {
     ...config,
     mode,
@@ -78,6 +79,56 @@ function defineRoom(schema, config) {
     config: Object.freeze(resolved)
   });
 }
+function checkPhysics(schema, config, mode) {
+  const declared = schema.collections.filter((c) => c.physics !== void 0).map((c) => c.name);
+  const physics = config.physics;
+  if (!physics) {
+    if (declared.length > 0) {
+      throw new Error(
+        `defineRoom: ${declared.join(", ")} declare${declared.length === 1 ? "s" : ""} physics in the schema, but the room config has no physics: { engine: 'rapier3d', gravity, bodies } \u2014 body fields would never move`
+      );
+    }
+    return;
+  }
+  if (declared.length === 0) {
+    throw new Error(
+      "defineRoom: physics: is configured but no collection declares physics in its schema \u2014 add entity(fields, { physics: { body: { x: 'x', \u2026 } } }) to the collection the world simulates"
+    );
+  }
+  if (mode !== "tick") {
+    throw new Error(
+      "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") {
+    throw new Error(
+      `defineRoom: physics.engine must be 'rapier3d' (got ${JSON.stringify(physics.engine)}); matter.js is not in M2`
+    );
+  }
+  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");
+  }
+  if (physics.timestep !== void 0 && (!Number.isFinite(physics.timestep) || physics.timestep <= 0)) {
+    throw new Error(
+      `defineRoom: physics.timestep must be a positive number of seconds, got ${String(physics.timestep)}`
+    );
+  }
+  assertSyncHandler(physics.setup, "physics.setup");
+  const bodies = physics.bodies ?? {};
+  for (const [k, fn] of Object.entries(bodies)) assertSyncHandler(fn, `physics.bodies.${k}`);
+  const given = Object.keys(bodies).sort();
+  const expected = [...declared].sort();
+  const missing = expected.filter((n) => !given.includes(n));
+  const extra = given.filter((n) => !expected.includes(n));
+  if (missing.length || extra.length) {
+    const parts = [];
+    if (missing.length) parts.push(`missing body factories: ${missing.join(", ")}`);
+    if (extra.length)
+      parts.push(`physics.bodies names collections without schema physics: ${extra.join(", ")}`);
+    throw new Error(`defineRoom: ${parts.join("; ")}`);
+  }
+}
 function assertSyncHandler(fn, name) {
   if (fn === void 0) return;
   if (typeof fn !== "function") throw new Error(`defineRoom: ${name} must be a function`);

package/package.json

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