@irtio/cli 0.7.0 → 0.8.0

package/dist/bundle.js

@@ -3,7 +3,7 @@ import {
   BundleError,
   EXTERNAL_IMPORTS,
   bundleRoom
-} from "./chunk-OTSFRVJN.js";
+} from "./chunk-NOYGY3HA.js";
 export {
   ALLOWED_IMPORTS,
   BundleError,

package/dist/{chunk-OTSFRVJN.js → chunk-NOYGY3HA.js}

@@ -10,9 +10,16 @@ var ALLOWED_IMPORTS = [
   "@irtio/schema",
   "@dimforge/rapier3d-compat",
   // D45: the second blessed engine. Exactly one import added, as the decision says.
-  "matter-js"
+  "matter-js",
+  // The third: Rapier held in a plane. A separate package from the 3D build, so a separate
+  // import — a room picks one and pays for one.
+  "@dimforge/rapier2d-compat"
+];
+var EXTERNAL_IMPORTS = [
+  "@dimforge/rapier3d-compat",
+  "matter-js",
+  "@dimforge/rapier2d-compat"
 ];
-var EXTERNAL_IMPORTS = ["@dimforge/rapier3d-compat", "matter-js"];
 var BundleError = class extends Error {
   name = "BundleError";
 };
@@ -92,7 +99,7 @@ async function bundleRoom(options) {
   if (!out) throw new BundleError("esbuild produced no output");
   const warnings = result.warnings.map((w) => w.text);
   const importsEngine = Object.values(result.metafile?.outputs ?? {}).some(
-    (o) => o.imports.some((i) => i.path === "@dimforge/rapier3d-compat" || i.path === "matter-js")
+    (o) => o.imports.some((i) => EXTERNAL_IMPORTS.includes(i.path))
   );
   const hash = createHash("sha256").update(out.contents).digest("hex");
   const file = path.join(options.outDir, `room.${hash.slice(0, 16)}.mjs`);

package/dist/deploy.js

@@ -12,7 +12,7 @@ import {
 } from "./chunk-JL235KIE.js";
 import {
   bundleRoom
-} from "./chunk-OTSFRVJN.js";
+} from "./chunk-NOYGY3HA.js";
 import {
   HelpRequested,
   helpFor,

package/dist/{dev-AUZ4OLA3.js → dev-VJ2ATJTF.js}

@@ -30,7 +30,7 @@ import {
 import {
   BundleError,
   bundleRoom
-} from "./chunk-OTSFRVJN.js";
+} from "./chunk-NOYGY3HA.js";
 import {
   HelpRequested,
   helpFor,
@@ -1746,6 +1746,33 @@ var RoomRecord = class {
    * which is the arena case and the common one.
    */
   backfillOpen = true;
+  // ---- M6 lane H: lobby front door ----
+  /**
+   * D75: whether this room is currently in control's public registry, and which queue under.
+   *
+   * On the record for `backfillOpen`'s reasons — out of the hibernation blob, and the supervisor's
+   * own bookkeeping — but NOT reset on a worker ready, and that difference is the whole point.
+   * `lobbyStarted` is a one-way door: a room whose game has started must never be advertised
+   * again, and a reset would re-offer it to a stranger on the first poll after a wake.
+   */
+  lobbyPublic = false;
+  lobbyQueue;
+  lobbyStarted = false;
+  /**
+   * Has this room said anything about its lobby yet?
+   *
+   * This is the difference between "private" and "not in the registry conversation", and getting it
+   * wrong was a real bug rather than a nicety. The first version reported the lobby fields only
+   * when `lobbyPublic` was true, so a `false` never left the box: control's deregister branch was
+   * unreachable, and a host who made a lobby public and then private kept receiving strangers while
+   * their own panel said private.
+   *
+   * The two states still have to stay apart, because absence is what an agent older than this lane
+   * sends for every room on its box and what every room without a lobby sends forever — control
+   * reads it as "leave this room's registry row alone". So the latch: once a room has spoken, every
+   * report carries its current answer, `false` included.
+   */
+  lobbySpoken = false;
   /**
    * The deployment version this room was created under. New rooms take the newest; rooms created
    * before a deploy keep theirs until they idle (per-room drain, plan §3.3).
@@ -1909,7 +1936,18 @@ var RoomRecord = class {
       // only when the room type declared it, so "absent" and "not a candidate" stay the same
       // thing all the way to control's nullable column.
       maxClients: this.config.maxClients,
-      ...this.config.backfill === true ? { backfill: this.backfillNow } : {}
+      ...this.config.backfill === true ? { backfill: this.backfillNow } : {},
+      // ---- M6 lane H: lobby front door ----
+      // Reported by a room that has said something about its lobby, and by no other room, so
+      // "absent" stays "not in the registry conversation at all" — the same shape `backfill` uses,
+      // and what keeps a mixed fleet degrading to "no public rooms from the old boxes".
+      //
+      // Once a room HAS spoken, its current answer goes out on every report including `false`. See
+      // `lobbySpoken` for the bug that came of only ever reporting `true`.
+      ...this.lobbyStarted ? { lobbyStarted: true } : this.lobbySpoken ? {
+        public: this.lobbyPublic,
+        ...this.lobbyQueue !== void 0 ? { queue: this.lobbyQueue } : {}
+      } : {}
     };
   }
 };
@@ -2449,6 +2487,7 @@ var IDENTITY_KEY_WAIT_MS = 2e3;
 var MAX_IDENTITY_KEY_WAITERS = 64;
 var RESUME_TOKEN_TTL_MS = 24 * 60 * 60 * 1e3;
 var BUS_SEEN_MAX = 256;
+var LOBBY_QUEUE_RE = /^[a-z0-9][a-z0-9._-]{0,31}$/;
 var SHARD_ASSIGNMENT_RETRY_MS = [1e3, 3e4];
 var KvUnavailable = class extends Error {
   code = KV_ERRORS.unavailable;
@@ -5679,6 +5718,38 @@ var SupervisorImpl = class {
       case "setBackfill":
         room.backfillOpen = msg.open;
         return;
+      // ---- M6 lane H: lobby front door ----
+      case "setLobby": {
+        if (room.config.lobby !== true) {
+          this.roomLog(
+            room,
+            "warn",
+            "refusing setLobby: this room type declared no lobby, so it cannot enter the public registry"
+          );
+          return;
+        }
+        if (msg.started === true) {
+          room.lobbySpoken = true;
+          room.lobbyStarted = true;
+          room.lobbyPublic = false;
+          return;
+        }
+        if (room.lobbyStarted) return;
+        if (msg.queue !== void 0) {
+          if (!LOBBY_QUEUE_RE.test(msg.queue)) {
+            this.roomLog(
+              room,
+              "warn",
+              `refusing setLobby: queue ${JSON.stringify(msg.queue)} must be 1-32 of a-z 0-9 . _ - and start with a letter or digit`
+            );
+            return;
+          }
+          room.lobbyQueue = msg.queue;
+        }
+        room.lobbySpoken = true;
+        if (msg.public !== void 0) room.lobbyPublic = msg.public;
+        return;
+      }
       case "setAlarm":
         if (isMailboxAlarm(msg.name)) {
           this.roomLog(
@@ -6271,7 +6342,7 @@ async function resolveWorkerEntry2(outDir) {
   }
   const outfile = path.join(outDir, "worker.mjs");
   const runtimeDir = path.join(packagesDir, "runtime");
-  const enginePlugins = ["@dimforge/rapier3d-compat", "matter-js"].map((pkg) => engineAbsolutePlugin(runtimeDir, pkg)).filter((p) => p !== void 0);
+  const enginePlugins = ["@dimforge/rapier3d-compat", "matter-js", "@dimforge/rapier2d-compat"].map((pkg) => engineAbsolutePlugin(runtimeDir, pkg)).filter((p) => p !== void 0);
   await esbuild.build({
     entryPoints: [source],
     bundle: true,
@@ -6290,7 +6361,13 @@ async function resolveWorkerEntry2(outDir) {
     // bundle resolves via node_modules. `rapierPlugin` (above) already externalizes it at an
     // absolute path when `@irtio/runtime`'s own copy can be found; this string entry is the
     // fallback for a published install where that resolution comes for free from node_modules.
-    external: ["node:worker_threads", "node:url", "@dimforge/rapier3d-compat", "matter-js"]
+    external: [
+      "node:worker_threads",
+      "node:url",
+      "@dimforge/rapier3d-compat",
+      "matter-js",
+      "@dimforge/rapier2d-compat"
+    ]
   });
   return outfile;
 }

package/dist/index.js

@@ -135,7 +135,7 @@ switch (command) {
     break;
   }
   case "dev": {
-    const { dev } = await import("./dev-AUZ4OLA3.js");
+    const { dev } = await import("./dev-VJ2ATJTF.js");
     await dev(args);
     break;
   }
@@ -165,7 +165,7 @@ switch (command) {
     break;
   }
   case "migrate": {
-    const { migrate } = await import("./migrate-FMXTRVUV.js");
+    const { migrate } = await import("./migrate-5YCFT63L.js");
     await migrate(args);
     break;
   }

package/dist/init.js

@@ -15,7 +15,7 @@ import { createInterface } from "readline/promises";
 import pc from "picocolors";
 
 // src/agent-guide.generated.ts
-var AGENT_GUIDE = "# irt.io integration guide\n\nThe whole product in one page, written for a context window. Everything below is enough to take a\nsingle-player web game to a deployed, verified multiplayer room without opening a dashboard.\n\n## The mental model\n\nA **room** is a server-side TypeScript file. It owns a small typed **schema**: the state two\nplayers have to agree on, and nothing else about your game. Each client owns its own instances and\nwrites them like local objects. The room's `validate` decides what a write may be. Everything else\nin your game stays where it was. You verify a room the way you verify code. Bots drive real\nsockets, a **scenario** asserts against the server's own recorded timeline, and the same seed gives\nthe same verdict.\n\n## The skeleton\n\nThe smallest project that deploys. Four files, and `irtio init` writes all of them.\n\n```ts\n// irtio/schema.ts\nimport { defineSchema, entity, f32, str, u8 } from '@irtio/schema';\n\nimport { rpc } from './rpc.js';\n\nexport const schema = defineSchema(\n  {\n    // One instance per connected client, owned by that client. Owned means writable on that\n    // client and read-only everywhere else.\n    players: entity({ x: f32, y: f32, name: str(24), color: u8 }),\n  },\n  {\n    project: 'p_c0ffee1234abcd56', // written by `irtio init`; public, domain-locked, not a secret\n    roles: ['player'] as const,\n    rpc,\n  },\n);\n```\n\n```ts\n// irtio/rpc.ts\nimport { server, u8 } from '@irtio/schema';\n\n// Typed calls in both directions. `server(...)` is client to server. Names and signatures are\n// part of the schema hash, so skew is caught as a version error instead of at runtime.\nexport const rpc = {\n  cheer: server({ params: { volume: u8 } }),\n};\n```\n\n```ts\n// irtio/room.ts\nimport { defineRoom } from '@irtio/server';\n\nimport { schema } from './schema.js';\n\nconst WIDTH = 800;\nconst HEIGHT = 500;\n\nexport default defineRoom(schema, {\n  mode: 'tick', // 'event' if nothing moves without a player doing something\n  tickRate: 20,\n\n  onJoin(state, ctx) {\n    if (ctx.reconnecting) return;\n    state.players.add(\n      ctx.clientId,\n      { x: 0, y: 0, name: ctx.name || 'anon', color: (ctx.tick * 37) % 256 },\n      { owner: ctx.clientId }, // the line the whole client-side write model rests on\n    );\n  },\n\n  onLeave(state, ctx) {\n    state.players.remove(ctx.clientId);\n  },\n\n  // Owner writes pass through here before they are accepted. Return `next` to accept, `prev` to\n  // reject, or a clamped object. This is where cheating stops. Delete it and anything that fits\n  // the declared types is accepted.\n  validate: {\n    players(prev, next) {\n      // Refuse what could never be a real value, lock the fields the room assigned at join,\n      // and clamp the rest into the world.\n      if (!Number.isFinite(next.x) || !Number.isFinite(next.y)) return prev;\n      if (next.name !== prev.name || next.color !== prev.color) return prev;\n      return {\n        ...next,\n        x: Math.min(WIDTH, Math.max(0, next.x)),\n        y: Math.min(HEIGHT, Math.max(0, next.y)),\n      };\n    },\n  },\n\n  rpc: {\n    cheer(state, params, ctx) {\n      if (params.volume > 10) throw new Error('too loud'); // the normal way a room says no\n      state.players.get(ctx.clientId)!.color = params.volume;\n    },\n  },\n\n  tick() {}, // tick mode needs one, even empty\n});\n```\n\n```ts\n// your game, three lines added\nimport { joinRoom } from '@irtio/client';\n\nimport { schema } from './irtio/schema.js';\n\nconst room = await joinRoom(schema, { name: 'you' }); // reads ?room=, or creates one\nconst me = room.state.players[room.me]; // yours: write it like a local object\nif (me) me.x = 10;\n\nfor (const [, p] of room.render.players) draw(p); // `render` interpolates everyone else\n```\n\n`room.state` is the authoritative read path for game logic and tests. `room.render` has the same\nshapes and reads non-owned entities a beat behind arrival, interpolated, which is what you draw\nfrom. Writes are batched once per animation frame, and `room.flush()` forces one out now.\n`room.leave()` closes the session. A page rarely needs it; a test with several sessions always\ndoes. `joinRoom`'s options are `{ name, role, url, key, token, physics, transport }`; see\nthe client reference.\n\n`@irtio/client` is a module, so the page that imports it needs whatever bundler your game already\nuses. There is no `irtio build`.\n\n### Write the validate rule your game actually has\n\n`validate` is the one part of the skeleton you cannot copy without thinking. The wrong rule here\nis worse than no rule, because it refuses honest play silently. The server sends a correction, and\nthe thing does not go where the player put it.\n\nA **speed limit** (`if (Math.hypot(next.x - prev.x, next.y - prev.y) > MAX_STEP) return prev;`) is\nright when the thing being moved has a movement speed the game defines: a character, a vehicle, a\ndragged token. It is wrong for a **mouse cursor**. A cursor legitimately teleports when the pointer moves fast,\nor when it leaves the window and comes back. A player gains nothing by putting their cursor\nsomewhere.\n\nAsk what a cheat would actually win. Position, for a cursor, wins nothing, so clamp it and stop.\nPosition for a character wins map knowledge and reach, so limit the step. Score, turn order, hit\ndetection and inventory win the game outright, so they should not be client-owned at all: make\nthem `serverOwned` and change them through an RPC.\n\n## The four commands\n\n```bash\nnpx irtio init                                   # scaffold the four files above plus irtio.json\nnpx irtio dev                                    # bundle irtio/room.ts and run it locally\nnpx irtio simulate --scenario irtio/scenario.ts  # real bots, your assertions, exit code\nnpx irtio deploy                                 # create the project if new, classify, upload\n```\n\n`simulate` drives real clients at a room that is **already running**, so `dev` stays up in another\nterminal while you run it. The four are a loop, not a pipeline.\n\nEvery subcommand takes `--help`, and the per-command help is the complete list; the top-level\nsummary is a map.\n\n`dev` is the whole server, locally: it bundles the room file and runs it the way the hosted\nserver does, so it is what you develop and test against. It does not build or serve your\n**client**. That stays your own bundler's job, the same one your game already uses.\n\n`deploy` is the hosted path and needs `irtio login`. There is no offline `deploy`. Without an\naccount, `dev` plus your own bundler is as far as you get, and that runs everything below.\n\n`deploy` creates the project on first use and classifies the schema change against the last\ndeployment. It refuses breaking changes unless a migration covers them, then prints where the room\nis playable. `simulate` exits non-zero on a violation, so both belong in CI.\n\nWhen the question is \"why is this room using so much bandwidth\", both commands take `--profile`.\n`dev --profile` prints a per-room breakdown by collection and field once a second.\n`simulate --profile` prints one for the whole run as the bots saw it. The answer is usually a\nsingle wide field, or `overhead` telling you the updates are too small and too frequent. See\n[the profiler](/docs/guides/profiler).\n\n**Restart `dev` after editing the room.** With `--no-watch`, a `dev` you forgot to kill keeps\nserving the old bundle. `simulate` connects to it and reports a clean run against code you have\nreplaced. The report header names the bundle hash and how long the server has been up. Compare\nthose two lines between runs: an edit that changed nothing in the header changed nothing in the\ncode under test.\n\nAn agent driving this through MCP calls `project_create`, `origin_add`, `deploy`, `scenario_run`,\nthen `logs` or `metrics`. Sign in once with `npx irtio login`; the MCP config snippet is a command\nand carries no secret.\n\n## Verify a room with a scenario\n\nA scenario is a TypeScript module next to the room file. Assertions run against the recorded\nauthoritative timeline, one frame per server tick. A scenario can prove something about a race no\nclient could observe, and it replays: same seed, same verdict.\n\n```ts\n// irtio/scenario.ts\nimport { defineScenario } from '@irtio/bots';\n\nimport type { schema } from './schema.js';\n\nexport default defineScenario<typeof schema>({\n  bots: 2,\n  seconds: 4,\n  seed: 41,\n\n  // Adversarial in two words: bot 0 lags, and every bot tries illegal writes. `validate` above\n  // is what has to refuse them.\n  conditions: (index) => (index === 0 ? { rttMs: 200 } : undefined),\n  cheat: true,\n\n  script: async (bot) => {\n    await bot.wait(200);\n    await bot.room.call.cheer({ volume: 3 });\n    await bot.wait(500);\n  },\n\n  assert: (timeline) => {\n    timeline.check('nobody left the arena', () => {\n      for (const tick of timeline.ticks) {\n        for (const id of timeline.at(tick).players!.ids()) {\n          const p = timeline.at(tick).players!.get(id)!;\n          if (p.x < 0 || p.x > 800) throw new Error(`player ${id} at x=${p.x} on tick ${tick}`);\n        }\n      }\n    });\n  },\n});\n```\n\n`cheat: true` makes the bots write play-illegal values. If the run reports\n`HOLE bot <n> cheated and drew 0 corrections`, your `validate` accepted them, and that is the\nfinding. `truth: true` additionally saves the room at the end and diffs it against what each client\nactually received.\n\nTwo things to know before you read a result.\n\n**A cheat run that works fails the run by default.** Every refused write is a correction, and the\nbuilt-in `correction-storm` invariant fails above 5 corrections per second per bot. A deliberate\ncheater passes that immediately. Raise it for the run with `--corrections-max 25`, and read the\n`HOLE` line rather than the exit code as the verdict on `validate`.\n\n**The built-in invariants alone prove nothing about `validate`.** They are protocol invariants:\nframes decoded, nobody saw what they should not, bandwidth inside budget, no tick overruns. A room\nthat accepts every illegal write there is passes all of them. Only `cheat` and your own scenario\nassertions test server authority, so a run with neither says nothing about whether your game can be\ncheated.\n\n## One retrofit diff\n\nThe canvas case, the shortest one. The cursors canvas example is this diff as running code; see\n[the retrofit guide](/docs/guides/retrofit).\n\n```diff\n+import { joinRoom } from '@irtio/client';\n+\n+import { schema } from './irtio/schema.js';\n+\n+const room = await joinRoom(schema, { name: 'you' });\n-const player = { x: canvas.width / 2, y: canvas.height / 2, name: 'you', color: 200 };\n-\n canvas.addEventListener('pointermove', (event) => {\n   const bounds = canvas.getBoundingClientRect();\n+  const player = room.state.players[room.me];\n+  if (!player) return;\n   player.x = event.clientX - bounds.left;\n   player.y = event.clientY - bounds.top;\n });\n\n function frame() {\n-  const entries = [['me', player]];\n+  const entries = [...room.render.players];\n   for (const [, p] of entries) draw(p);\n }\n```\n\nThe whole shape is an import, a join, an entity lookup instead of a local object, and one changed\niteration. The camera, particles, input handling, HUD, draw code and level geometry do not\nmove. If your retrofit touches those, it is doing more than a retrofit. Three.js and Phaser follow\nthe same four steps against their own loops; see the retrofit guide.\n\nYour entity does not exist for the first frame or two after the page loads, which is what\n`if (!player) return;` is for. Writing an instance you do not own is a compile error and a\nwarn-once no-op at runtime.\n\n## When it goes wrong\n\nThe codes you will actually meet, with the fix. The full catalogue is at `/docs/reference/errors`.\n\n| Code | Fix |\n|---|---|\n| `E_AUTH` | The project key was rejected. Check `project` in `irtio/schema.ts` matches the project you are deploying to. On localhost with no `irtio init` the client uses the key `dev`, which only `irtio dev` accepts |\n| `E_SCHEMA_MISMATCH` | The client was built with a different schema than the room is running. The hash covers every field, type, order, role and RPC signature. Rebuild the client, or deploy the schema the client has |\n| `E_ORIGIN` | The page's origin is not in the project's origin list. Register it. `localhost` is always allowed, so this only bites on a deployed page |\n| `E_ROOM_FULL` | The room is at `maxClients`, 64 by default. Raise it in `irtio/room.ts`, or join with no `?room=` to get a new room |\n| `E_ROOM_NOT_FOUND` | No such room, or an id that cannot be one. Do not construct ids yourself: let `joinRoom` create one and read `room.link` |\n| `E_WRITE_REJECTED` | Your `validate` refused the write, or the value did not fit its declared type. If this is a legitimate move, `validate` is too strict or the field too narrow |\n| `E_NOT_OWNER` | Something wrote an instance it does not own. `await room.requestOwnership(entity, id)` first, and re-read the instance after a grant |\n| `E_RPC_BAD_PARAMS` | Parameters did not match the declared shape. Types normally prevent this, so it means client and server were built from different `rpc.ts` files |\n| `E_RATE_LIMITED` | Read the message. `rate limited` is too many frames: batch instead of calling `room.flush()` in a loop. `too many connections from this address` is the per-IP cap (`connectionsPerIpPerMin`, default 120), which a load run from one machine has to raise |\n| `E_STARTING` | Not an error. The server was asleep and is waking. `room.status === 'starting'`; show a spinner and keep waiting |\n| `E_SLOW_CONSUMER` | The client was not draining its stream and was dropped; it reconnects itself. If it recurs, the room produces more per tick than the connection carries: lower `tickRate`, narrow field types, or use role visibility |\n| `E_CONNECT_FAILED` | Not a protocol code. The socket failed before the join. Read the URL in the message: `ws://localhost:7070` means `irtio dev` is not running |\n| `deploy refused: N breaking changes` | Snapshots cannot be read under the new schema. `irtio migrate create <name>`, write the transform, then `irtio deploy --allow-breaking`. Additive changes (a new field with `.default(...)` or `.opt`) need none of this |\n| `not logged in` | `deploy`, `logs`, `rooms`, `whoami` and `migrate create` need credentials. Run `irtio login` |\n| `HOLE bot <n> cheated and drew 0 corrections` | Not a failure, and the most important warning here. Illegal writes were accepted. Add rules to `validate` |\n\n## Past the skeleton\n\nThe skeleton above is the smallest thing that deploys. Each of these is one docs page\nand none of them changes the model.\n\n- Server-authoritative physics with client prediction: `irtio init --physics`, a shared\n  `irtio/world.ts` both sides import, Rapier in 3D (`/docs/physics/overview`) or matter.js in 2D\n  (`/docs/physics/matter2d`, `tickRate: 60`). Both predict, and `room.prediction` reads the same\n  either way (`/docs/physics/prediction`).\n- Scripted NPCs that are ordinary client sessions at the protocol level: `room.spawnNPC(...)`\n  (`/docs/guides/npcs`).\n- Player storage that outlives a room (`room.kv`), room saves and restores, hibernation, and the\n  `retention` option that sets how long a room's state survives\n  (`/docs/persistence/player-storage`, `/docs/persistence/saves`, `/docs/concepts/hibernation`).\n- Signed player tokens, roles, and per-role visibility (`/docs/concepts/auth`,\n  `/docs/concepts/visibility`).\n- A player identity that survives reconnects, hibernation and a closed tab\n  (`/docs/concepts/identity`).\n- Ranked boards per project, written only by your room code\n  (`/docs/persistence/leaderboards`).\n- Two strangers matched into a room without either knowing a room code\n  (`/docs/concepts/quick-match`).\n- Voice chat in a room, on its own meter (`/docs/concepts/voice`).\n- One of your rooms sending a message to another (`/docs/concepts/room-bus`).\n- A project split across more than one server when a single one is full\n  (`/docs/deploy/sharding`).\n\n**Starting from an engine.** Build against the engine's own loop from the first line: React and\nreact-three-fiber (`/docs/integrations/react`), Three.js (`/docs/integrations/threejs`), Phaser\n(`/docs/integrations/phaser`), PixiJS (`/docs/integrations/pixijs`), Babylon.js\n(`/docs/integrations/babylonjs`).\n\n**Moving a game that already exists.** Single-player, which is the diff above at full length:\ncanvas (`/docs/guides/retrofit`), Three.js (`/docs/guides/retrofit-threejs`), Phaser\n(`/docs/guides/retrofit-phaser`). Already multiplayer on something else: Colyseus\n(`/docs/migrate/colyseus`), Playroom (`/docs/migrate/playroom`), Socket.IO\n(`/docs/migrate/socket-io`).\n\nEvery term these pages use is defined once in the glossary (`/docs/reference/glossary`).\n\n## Rules of thumb\n\n- Sync the smallest set of facts two players must agree on. Everything else stays local.\n- A player reporting a fact about themselves is an owned write. Anything a player could gain by\n  lying about (scores, deals, turn order, hit detection) is `serverOwned` plus an RPC.\n- Types are budgets, not hints. `f32`, `u8`, `str(24)` are what make an update a handful of bytes.\n- Never import `room.ts` from client code. Shared geometry and constants go in their own module\n  that both sides import.\n- Do not paste a credential into a config file. `irtio login` writes one; MCP and the CLI find it.\n- Believe a room when a scenario with an adversarial pass says so, not when it looks right in two\n  tabs.\n";
+var AGENT_GUIDE = "# irt.io integration guide\n\nThe whole product in one page, written for a context window. Everything below is enough to take a\nsingle-player web game to a deployed, verified multiplayer room without opening a dashboard.\n\n## The mental model\n\nA **room** is a server-side TypeScript file. It owns a small typed **schema**: the state two\nplayers have to agree on, and nothing else about your game. Each client owns its own instances and\nwrites them like local objects. The room's `validate` decides what a write may be. Everything else\nin your game stays where it was. You verify a room the way you verify code. Bots drive real\nsockets, a **scenario** asserts against the server's own recorded timeline, and the same seed gives\nthe same verdict.\n\n## The skeleton\n\nThe smallest project that deploys. Four files, and `irtio init` writes all of them.\n\n```ts\n// irtio/schema.ts\nimport { defineSchema, entity, f32, str, u8 } from '@irtio/schema';\n\nimport { rpc } from './rpc.js';\n\nexport const schema = defineSchema(\n  {\n    // One instance per connected client, owned by that client. Owned means writable on that\n    // client and read-only everywhere else.\n    players: entity({ x: f32, y: f32, name: str(24), color: u8 }),\n  },\n  {\n    project: 'p_c0ffee1234abcd56', // written by `irtio init`; public, domain-locked, not a secret\n    roles: ['player'] as const,\n    rpc,\n  },\n);\n```\n\n```ts\n// irtio/rpc.ts\nimport { server, u8 } from '@irtio/schema';\n\n// Typed calls in both directions. `server(...)` is client to server. Names and signatures are\n// part of the schema hash, so skew is caught as a version error instead of at runtime.\nexport const rpc = {\n  cheer: server({ params: { volume: u8 } }),\n};\n```\n\n```ts\n// irtio/room.ts\nimport { defineRoom } from '@irtio/server';\n\nimport { schema } from './schema.js';\n\nconst WIDTH = 800;\nconst HEIGHT = 500;\n\nexport default defineRoom(schema, {\n  mode: 'tick', // 'event' if nothing moves without a player doing something\n  tickRate: 20,\n\n  onJoin(state, ctx) {\n    if (ctx.reconnecting) return;\n    state.players.add(\n      ctx.clientId,\n      { x: 0, y: 0, name: ctx.name || 'anon', color: (ctx.tick * 37) % 256 },\n      { owner: ctx.clientId }, // the line the whole client-side write model rests on\n    );\n  },\n\n  onLeave(state, ctx) {\n    state.players.remove(ctx.clientId);\n  },\n\n  // Owner writes pass through here before they are accepted. Return `next` to accept, `prev` to\n  // reject, or a clamped object. This is where cheating stops. Delete it and anything that fits\n  // the declared types is accepted.\n  validate: {\n    players(prev, next) {\n      // Refuse what could never be a real value, lock the fields the room assigned at join,\n      // and clamp the rest into the world.\n      if (!Number.isFinite(next.x) || !Number.isFinite(next.y)) return prev;\n      if (next.name !== prev.name || next.color !== prev.color) return prev;\n      return {\n        ...next,\n        x: Math.min(WIDTH, Math.max(0, next.x)),\n        y: Math.min(HEIGHT, Math.max(0, next.y)),\n      };\n    },\n  },\n\n  rpc: {\n    cheer(state, params, ctx) {\n      if (params.volume > 10) throw new Error('too loud'); // the normal way a room says no\n      state.players.get(ctx.clientId)!.color = params.volume;\n    },\n  },\n\n  tick() {}, // tick mode needs one, even empty\n});\n```\n\n```ts\n// your game, three lines added\nimport { joinRoom } from '@irtio/client';\n\nimport { schema } from './irtio/schema.js';\n\nconst room = await joinRoom(schema, { name: 'you' }); // reads ?room=, or creates one\nconst me = room.state.players[room.me]; // yours: write it like a local object\nif (me) me.x = 10;\n\nfor (const [, p] of room.render.players) draw(p); // `render` interpolates everyone else\n```\n\n`room.state` is the authoritative read path for game logic and tests. `room.render` has the same\nshapes and reads non-owned entities a beat behind arrival, interpolated, which is what you draw\nfrom. Writes are batched once per animation frame, and `room.flush()` forces one out now.\n`room.leave()` closes the session. A page rarely needs it; a test with several sessions always\ndoes. `joinRoom`'s options are `{ name, role, url, key, token, physics, transport }`; see\nthe client reference.\n\n`@irtio/client` is a module, so the page that imports it needs whatever bundler your game already\nuses. There is no `irtio build`.\n\n### Write the validate rule your game actually has\n\n`validate` is the one part of the skeleton you cannot copy without thinking. The wrong rule here\nis worse than no rule, because it refuses honest play silently. The server sends a correction, and\nthe thing does not go where the player put it.\n\nA **speed limit** (`if (Math.hypot(next.x - prev.x, next.y - prev.y) > MAX_STEP) return prev;`) is\nright when the thing being moved has a movement speed the game defines: a character, a vehicle, a\ndragged token. It is wrong for a **mouse cursor**. A cursor legitimately teleports when the pointer moves fast,\nor when it leaves the window and comes back. A player gains nothing by putting their cursor\nsomewhere.\n\nAsk what a cheat would actually win. Position, for a cursor, wins nothing, so clamp it and stop.\nPosition for a character wins map knowledge and reach, so limit the step. Score, turn order, hit\ndetection and inventory win the game outright, so they should not be client-owned at all: make\nthem `serverOwned` and change them through an RPC.\n\n## The four commands\n\n```bash\nnpx irtio init                                   # scaffold the four files above plus irtio.json\nnpx irtio dev                                    # bundle irtio/room.ts and run it locally\nnpx irtio simulate --scenario irtio/scenario.ts  # real bots, your assertions, exit code\nnpx irtio deploy                                 # create the project if new, classify, upload\n```\n\n`simulate` drives real clients at a room that is **already running**, so `dev` stays up in another\nterminal while you run it. The four are a loop, not a pipeline.\n\nEvery subcommand takes `--help`, and the per-command help is the complete list; the top-level\nsummary is a map.\n\n`dev` is the whole server, locally: it bundles the room file and runs it the way the hosted\nserver does, so it is what you develop and test against. It does not build or serve your\n**client**. That stays your own bundler's job, the same one your game already uses.\n\n`deploy` is the hosted path and needs `irtio login`. There is no offline `deploy`. Without an\naccount, `dev` plus your own bundler is as far as you get, and that runs everything below.\n\n`deploy` creates the project on first use and classifies the schema change against the last\ndeployment. It refuses breaking changes unless a migration covers them, then prints where the room\nis playable. `simulate` exits non-zero on a violation, so both belong in CI.\n\nWhen the question is \"why is this room using so much bandwidth\", both commands take `--profile`.\n`dev --profile` prints a per-room breakdown by collection and field once a second.\n`simulate --profile` prints one for the whole run as the bots saw it. The answer is usually a\nsingle wide field, or `overhead` telling you the updates are too small and too frequent. See\n[the profiler](/docs/guides/profiler).\n\n**Restart `dev` after editing the room.** With `--no-watch`, a `dev` you forgot to kill keeps\nserving the old bundle. `simulate` connects to it and reports a clean run against code you have\nreplaced. The report header names the bundle hash and how long the server has been up. Compare\nthose two lines between runs: an edit that changed nothing in the header changed nothing in the\ncode under test.\n\nAn agent driving this through MCP calls `project_create`, `origin_add`, `deploy`, `scenario_run`,\nthen `logs` or `metrics`. Sign in once with `npx irtio login`; the MCP config snippet is a command\nand carries no secret.\n\n## Verify a room with a scenario\n\nA scenario is a TypeScript module next to the room file. Assertions run against the recorded\nauthoritative timeline, one frame per server tick. A scenario can prove something about a race no\nclient could observe, and it replays: same seed, same verdict.\n\n```ts\n// irtio/scenario.ts\nimport { defineScenario } from '@irtio/bots';\n\nimport type { schema } from './schema.js';\n\nexport default defineScenario<typeof schema>({\n  bots: 2,\n  seconds: 4,\n  seed: 41,\n\n  // Adversarial in two words: bot 0 lags, and every bot tries illegal writes. `validate` above\n  // is what has to refuse them.\n  conditions: (index) => (index === 0 ? { rttMs: 200 } : undefined),\n  cheat: true,\n\n  script: async (bot) => {\n    await bot.wait(200);\n    await bot.room.call.cheer({ volume: 3 });\n    await bot.wait(500);\n  },\n\n  assert: (timeline) => {\n    timeline.check('nobody left the arena', () => {\n      for (const tick of timeline.ticks) {\n        for (const id of timeline.at(tick).players!.ids()) {\n          const p = timeline.at(tick).players!.get(id)!;\n          if (p.x < 0 || p.x > 800) throw new Error(`player ${id} at x=${p.x} on tick ${tick}`);\n        }\n      }\n    });\n  },\n});\n```\n\n`cheat: true` makes the bots write play-illegal values. If the run reports\n`HOLE bot <n> cheated and drew 0 corrections`, your `validate` accepted them, and that is the\nfinding. `truth: true` additionally saves the room at the end and diffs it against what each client\nactually received.\n\nTwo things to know before you read a result.\n\n**A cheat run that works fails the run by default.** Every refused write is a correction, and the\nbuilt-in `correction-storm` invariant fails above 5 corrections per second per bot. A deliberate\ncheater passes that immediately. Raise it for the run with `--corrections-max 25`, and read the\n`HOLE` line rather than the exit code as the verdict on `validate`.\n\n**The built-in invariants alone prove nothing about `validate`.** They are protocol invariants:\nframes decoded, nobody saw what they should not, bandwidth inside budget, no tick overruns. A room\nthat accepts every illegal write there is passes all of them. Only `cheat` and your own scenario\nassertions test server authority, so a run with neither says nothing about whether your game can be\ncheated.\n\n## One retrofit diff\n\nThe canvas case, the shortest one. The cursors canvas example is this diff as running code; see\n[the retrofit guide](/docs/guides/retrofit).\n\n```diff\n+import { joinRoom } from '@irtio/client';\n+\n+import { schema } from './irtio/schema.js';\n+\n+const room = await joinRoom(schema, { name: 'you' });\n-const player = { x: canvas.width / 2, y: canvas.height / 2, name: 'you', color: 200 };\n-\n canvas.addEventListener('pointermove', (event) => {\n   const bounds = canvas.getBoundingClientRect();\n+  const player = room.state.players[room.me];\n+  if (!player) return;\n   player.x = event.clientX - bounds.left;\n   player.y = event.clientY - bounds.top;\n });\n\n function frame() {\n-  const entries = [['me', player]];\n+  const entries = [...room.render.players];\n   for (const [, p] of entries) draw(p);\n }\n```\n\nThe whole shape is an import, a join, an entity lookup instead of a local object, and one changed\niteration. The camera, particles, input handling, HUD, draw code and level geometry do not\nmove. If your retrofit touches those, it is doing more than a retrofit. Three.js and Phaser follow\nthe same four steps against their own loops; see the retrofit guide.\n\nYour entity does not exist for the first frame or two after the page loads, which is what\n`if (!player) return;` is for. Writing an instance you do not own is a compile error and a\nwarn-once no-op at runtime.\n\n## When it goes wrong\n\nThe codes you will actually meet, with the fix. The full catalogue is at `/docs/reference/errors`.\n\n| Code | Fix |\n|---|---|\n| `E_AUTH` | The project key was rejected. Check `project` in `irtio/schema.ts` matches the project you are deploying to. On localhost with no `irtio init` the client uses the key `dev`, which only `irtio dev` accepts |\n| `E_SCHEMA_MISMATCH` | The client was built with a different schema than the room is running. The hash covers every field, type, order, role and RPC signature. Rebuild the client, or deploy the schema the client has |\n| `E_ORIGIN` | The page's origin is not in the project's origin list. Register it. `localhost` is always allowed, so this only bites on a deployed page |\n| `E_ROOM_FULL` | The room is at `maxClients`, 64 by default. Raise it in `irtio/room.ts`, or join with no `?room=` to get a new room |\n| `E_ROOM_NOT_FOUND` | No such room, or an id that cannot be one. Do not construct ids yourself: let `joinRoom` create one and read `room.link` |\n| `E_WRITE_REJECTED` | Your `validate` refused the write, or the value did not fit its declared type. If this is a legitimate move, `validate` is too strict or the field too narrow |\n| `E_NOT_OWNER` | Something wrote an instance it does not own. `await room.requestOwnership(entity, id)` first, and re-read the instance after a grant |\n| `E_RPC_BAD_PARAMS` | Parameters did not match the declared shape. Types normally prevent this, so it means client and server were built from different `rpc.ts` files |\n| `E_RATE_LIMITED` | Read the message. `rate limited` is too many frames: batch instead of calling `room.flush()` in a loop. `too many connections from this address` is the per-IP cap (`connectionsPerIpPerMin`, default 120), which a load run from one machine has to raise |\n| `E_STARTING` | Not an error. The server was asleep and is waking. `room.status === 'starting'`; show a spinner and keep waiting |\n| `E_SLOW_CONSUMER` | The client was not draining its stream and was dropped; it reconnects itself. If it recurs, the room produces more per tick than the connection carries: lower `tickRate`, narrow field types, or use role visibility |\n| `E_CONNECT_FAILED` | Not a protocol code. The socket failed before the join. Read the URL in the message: `ws://localhost:7070` means `irtio dev` is not running |\n| `deploy refused: N breaking changes` | Snapshots cannot be read under the new schema. `irtio migrate create <name>`, write the transform, then `irtio deploy --allow-breaking`. Additive changes (a new field with `.default(...)` or `.opt`) need none of this |\n| `not logged in` | `deploy`, `logs`, `rooms`, `whoami` and `migrate create` need credentials. Run `irtio login` |\n| `HOLE bot <n> cheated and drew 0 corrections` | Not a failure, and the most important warning here. Illegal writes were accepted. Add rules to `validate` |\n\n## Past the skeleton\n\nThe skeleton above is the smallest thing that deploys. Each of these is one docs page\nand none of them changes the model.\n\n- Server-authoritative physics with client prediction: `irtio init --physics`, a shared\n  `irtio/world.ts` both sides import. Three engines: Rapier in 3D (`/docs/physics/overview`),\n  Rapier in 2D (`/docs/physics/rapier2d`), or matter.js in 2D (`/docs/physics/matter2d`,\n  `tickRate: 60`). Recommend Rapier for a new game and reach for matter2d only for a room already\n  on it. All three predict, and `room.prediction` reads the same either way\n  (`/docs/physics/prediction`).\n- Scripted NPCs that are ordinary client sessions at the protocol level: `room.spawnNPC(...)`\n  (`/docs/guides/npcs`).\n- Player storage that outlives a room (`room.kv`), room saves and restores, hibernation, and the\n  `retention` option that sets how long a room's state survives\n  (`/docs/persistence/player-storage`, `/docs/persistence/saves`, `/docs/concepts/hibernation`).\n- Signed player tokens, roles, and per-role visibility (`/docs/concepts/auth`,\n  `/docs/concepts/visibility`).\n- A player identity that survives reconnects, hibernation and a closed tab\n  (`/docs/concepts/identity`).\n- Ranked boards per project, written only by your room code\n  (`/docs/persistence/leaderboards`).\n- Two strangers matched into a room without either knowing a room code\n  (`/docs/concepts/quick-match`).\n- Voice chat in a room, on its own meter (`/docs/concepts/voice`).\n- One of your rooms sending a message to another (`/docs/concepts/room-bus`).\n- A project split across more than one server when a single one is full\n  (`/docs/deploy/sharding`).\n\n**Starting from an engine.** Build against the engine's own loop from the first line: React and\nreact-three-fiber (`/docs/integrations/react`), Three.js (`/docs/integrations/threejs`), Phaser\n(`/docs/integrations/phaser`), PixiJS (`/docs/integrations/pixijs`), Babylon.js\n(`/docs/integrations/babylonjs`).\n\n**Moving a game that already exists.** Single-player, which is the diff above at full length:\ncanvas (`/docs/guides/retrofit`), Three.js (`/docs/guides/retrofit-threejs`), Phaser\n(`/docs/guides/retrofit-phaser`). Already multiplayer on something else: Colyseus\n(`/docs/migrate/colyseus`), Playroom (`/docs/migrate/playroom`), Socket.IO\n(`/docs/migrate/socket-io`).\n\nEvery term these pages use is defined once in the glossary (`/docs/reference/glossary`).\n\n## Rules of thumb\n\n- Sync the smallest set of facts two players must agree on. Everything else stays local.\n- A player reporting a fact about themselves is an owned write. Anything a player could gain by\n  lying about (scores, deals, turn order, hit detection) is `serverOwned` plus an RPC.\n- Types are budgets, not hints. `f32`, `u8`, `str(24)` are what make an update a handful of bytes.\n- Never import `room.ts` from client code. Shared geometry and constants go in their own module\n  that both sides import.\n- Do not paste a credential into a config file. `irtio login` writes one; MCP and the CLI find it.\n- Believe a room when a scenario with an adversarial pass says so, not when it looks right in two\n  tabs.\n";
 
 // src/init.ts
 var INIT_DEPENDENCIES = [

package/dist/{migrate-FMXTRVUV.js → migrate-5YCFT63L.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-JL235KIE.js";
 import {
   bundleRoom
-} from "./chunk-OTSFRVJN.js";
+} from "./chunk-NOYGY3HA.js";
 import {
   HelpRequested,
   helpFor,

package/dist/simulate.d.ts

@@ -159,6 +159,29 @@ interface LoadedWorld2d {
     readonly smoothingHalfLifeMs?: number | undefined;
     readonly file: string;
 }
+/**
+ * A rapier2d world, as `joinRoom({ physics2d: { engine: 'rapier2d', … } })` wants it.
+ *
+ * The 2D sibling of {@link LoadedWorld2d}, and it differs in exactly the ways the engine does:
+ * there is no `settle` (the world applies gravity, so a crate nobody steers falls on its own —
+ * a rapier2d world that had one would fall twice as fast locally), and the default `epsilon` is
+ * already right, because a Rapier world is metre-scale by construction rather than by convention.
+ */
+interface LoadedWorldRapier2d {
+    readonly engine: 'rapier2d';
+    readonly gravity: {
+        x: number;
+        y: number;
+    };
+    readonly timestep?: number | undefined;
+    readonly setup?: ((world: unknown, rapier: unknown) => void) | undefined;
+    readonly bodies?: Record<string, (...args: never[]) => unknown> | undefined;
+    readonly intents?: Record<string, (...args: never[]) => void> | undefined;
+    readonly epsilon?: number | undefined;
+    readonly maxPredictedBodies?: number | undefined;
+    readonly smoothingHalfLifeMs?: number | undefined;
+    readonly file: string;
+}
 /**
  * A matter2d project this loader recognises and cannot predict from: run it, say why in one
  * sentence, and never pretend to a predictor that does not exist.
@@ -171,29 +194,41 @@ interface LoadedWorld2d {
  * `tick()`, so there is no steering hook to share and its own client does not predict either.
  */
 interface UnpredictedWorld {
-    readonly engine: 'matter2d';
+    /** Which planar engine the room declares. Both can be recognised and refused. */
+    readonly engine: 'matter2d' | 'rapier2d';
     /** One sentence, printed by the run, naming what would have to change. */
     readonly why: string;
     readonly file: string;
 }
-type LoadedAnyWorld = LoadedWorld | LoadedWorld2d | UnpredictedWorld;
+type LoadedAnyWorld = LoadedWorld | LoadedWorld2d | LoadedWorldRapier2d | UnpredictedWorld;
 /** Narrows a loaded world to a matter2d one bots can predict with. */
 declare function is2dWorld(world: LoadedAnyWorld | undefined): world is LoadedWorld2d;
+/** Narrows a loaded world to a rapier2d one bots can predict with. */
+declare function isRapier2dWorld(world: LoadedAnyWorld | undefined): world is LoadedWorldRapier2d;
 declare function isUnpredictedWorld(world: LoadedAnyWorld | undefined): world is UnpredictedWorld;
 /**
- * D73-a: does this project's room declare matter2d?
+ * Which engine does this project's room declare, and in which file?
+ *
+ * D73-a asked this question of matter2d only, and for one reason: a matter2d project whose world
+ * module is not a client world — `games/dive`, whose engine gravity is zero and applied per body,
+ * so there is no `gravity` to export — used to be refused at the door with "does not export a
+ * { x, y, z } gravity", which is why `irtio simulate` had never been run against dive at all.
  *
- * The one question the room module is asked, and the reason it is asked at all: a matter2d project
- * whose world module is not a client world — `games/dive`, whose engine gravity is zero and
- * applied per body, so there is no `gravity` to export and its `physics2d` block is composed in
- * `main.ts` — used to be refused at the door with "does not export a { x, y, z } gravity", which
- * is why `irtio simulate` had never been run against dive at all. Recognising it here turns that
- * refusal into a run with a sentence.
+ * rapier2d widens it from a yes/no to a name, because the old fallback cannot tell the two planar
+ * engines apart: both export a `{ x, y }` gravity, and guessing from that shape alone would run a
+ * rapier2d project's bots on matter.js and blame the mispredictions on netcode. The room's own
+ * declaration is the only thing that actually knows, so it is asked first and the gravity shape is
+ * kept only as the fallback for a project whose room this loader could not read.
  *
  * `undefined` for every other answer: no room module, one that will not build or import, or one
- * declaring another engine. None of those is an error here — the world module's own error is the
- * right one to raise.
+ * whose config declares no physics. None of those is an error here — the world module's own error
+ * is the right one to raise.
  */
+declare function detectRoomEngine(options: LoadSchemaOptions): Promise<{
+    engine: string;
+    file: string;
+} | undefined>;
+/** D73-a's original question, kept as the narrow form of {@link detectRoomEngine}. */
 declare function detectMatter2dRoom(options: LoadSchemaOptions): Promise<string | undefined>;
 /**
  * Bundles and imports the project's shared world-builder module, so the bots predict physics the
@@ -208,6 +243,19 @@ declare function loadProjectWorld(options: LoadSchemaOptions): Promise<LoadedAny
  * description, or `undefined` when the worlds agree.
  */
 declare function checkWorldDeterminism(world: LoadedWorld): Promise<string | undefined>;
+/**
+ * The rapier2d determinism check: the Rapier one, in a plane.
+ *
+ * It is the 3D check rather than the matter2d one, because the 2D build has the same
+ * `takeSnapshot()` the 3D build has — two builds of the same `setup` either produce the same bytes
+ * or the builder is not pure over synced inputs. No stepping is needed to make small randomness
+ * visible: it is already in the snapshot.
+ *
+ * The body factories are exercised too, against each collection's zero record, the way the
+ * matter2d check does it — a `Math.random()` in a factory is exactly as damaging as one in
+ * `setup`, and the snapshot sees it for free.
+ */
+declare function checkWorldRapier2dDeterminism(world: LoadedWorldRapier2d, schema?: AnySchema): Promise<string | undefined>;
 /**
  * D73-a: the matter2d determinism check.
  *
@@ -417,4 +465,4 @@ interface SimulationRun {
 declare function runSimulation(options?: RunSimulationOptions): Promise<SimulationRun>;
 declare function simulate(args: readonly string[]): Promise<void>;
 
-export { type AdversarialRun, type BuildIdentity, type LoadSchemaOptions, type LoadedAnyWorld, type LoadedWorld2d, RunNotPerformedError, type RunSimulationOptions, ScenarioNotRunError, type ScenarioRun, type SimulateArgs, type SimulationEnd, type SimulationRun, type TruthRun, USAGE, type UnpredictedWorld, ceilingFor, checkWorld2dDeterminism, checkWorldDeterminism, detectMatter2dRoom, formatBuildIdentity, is2dWorld, isUnpredictedWorld, loadProjectSchema, loadProjectWorld, loadScenario, parseSimulateArgs, readBuildIdentity, readTickCounters, runSimulation, simulate, stateUrlFor, tickHealthFrom };
+export { type AdversarialRun, type BuildIdentity, type LoadSchemaOptions, type LoadedAnyWorld, type LoadedWorld2d, type LoadedWorldRapier2d, RunNotPerformedError, type RunSimulationOptions, ScenarioNotRunError, type ScenarioRun, type SimulateArgs, type SimulationEnd, type SimulationRun, type TruthRun, USAGE, type UnpredictedWorld, ceilingFor, checkWorld2dDeterminism, checkWorldDeterminism, checkWorldRapier2dDeterminism, detectMatter2dRoom, detectRoomEngine, formatBuildIdentity, is2dWorld, isRapier2dWorld, isUnpredictedWorld, loadProjectSchema, loadProjectWorld, loadScenario, parseSimulateArgs, readBuildIdentity, readTickCounters, runSimulation, simulate, stateUrlFor, tickHealthFrom };

package/dist/simulate.js

@@ -76,7 +76,9 @@ async function loadScenario(options) {
       platform: "node",
       outfile,
       // The physics engine is resolved at runtime by whoever needs it, never bundled twice.
-      external: ["@dimforge/rapier3d-compat"],
+      // All three, not just the 3D one: a 2D scenario's engine is loaded by the runtime the same
+      // way, and bundling a copy here would be a second instance beside it.
+      external: ["@dimforge/rapier3d-compat", "matter-js", "@dimforge/rapier2d-compat"],
       ...Object.keys(alias).length > 0 ? { alias } : {}
     });
   } catch (err) {
@@ -458,6 +460,9 @@ async function loadProjectSchema(options) {
 function is2dWorld(world) {
   return world !== void 0 && world.engine === "matter2d" && !("why" in world);
 }
+function isRapier2dWorld(world) {
+  return world !== void 0 && world.engine === "rapier2d" && !("why" in world);
+}
 function isUnpredictedWorld(world) {
   return world !== void 0 && "why" in world;
 }
@@ -471,7 +476,7 @@ async function bundleAndImport(entry, outfile, options) {
     format: "esm",
     platform: "node",
     outfile,
-    external: ["@dimforge/rapier3d-compat", "matter-js"],
+    external: ["@dimforge/rapier3d-compat", "@dimforge/rapier2d-compat", "matter-js"],
     ...alias !== void 0 ? { alias } : {}
   });
   return await import(`${pathToFileURL2(outfile).href}?v=${Date.now()}-${importSeq2++}`);
@@ -479,7 +484,7 @@ async function bundleAndImport(entry, outfile, options) {
 function hookMap(value) {
   return typeof value === "object" && value !== null ? value : void 0;
 }
-async function detectMatter2dRoom(options) {
+async function detectRoomEngine(options) {
   const entry = ROOM_CANDIDATES.map((c) => path2.resolve(options.cwd, c)).find((f) => existsSync2(f));
   if (entry === void 0) return void 0;
   let module;
@@ -489,16 +494,23 @@ async function detectMatter2dRoom(options) {
     return void 0;
   }
   const definition = module.default ?? module.room;
-  return definition?.config?.physics?.engine === "matter2d" ? entry : void 0;
+  const engine = definition?.config?.physics?.engine;
+  return typeof engine === "string" ? { engine, file: entry } : void 0;
+}
+async function detectMatter2dRoom(options) {
+  const declared = await detectRoomEngine(options);
+  return declared?.engine === "matter2d" ? declared.file : void 0;
 }
 function whyNotPredictable(world) {
   if (world.bodies === void 0 || Object.keys(world.bodies).length === 0) {
     return `${world.file} exports no \`bodies\`, so there are no shapes to build a local world from; bots run without client prediction.
   export the body factories your client passes to \`joinRoom({ physics2d })\`.`;
   }
-  const steered = world.intents !== void 0 || world.settle !== void 0;
+  const settle = world.engine === "matter2d" ? world.settle : void 0;
+  const steered = world.intents !== void 0 || settle !== void 0;
   if (!steered && world.gravity.x === 0 && world.gravity.y === 0) {
-    return `${world.file} exports no \`intents\` and no \`settle\`, and its gravity is zero, so nothing in a local world built from it could ever move a body; bots run without client prediction.
+    const hooks = world.engine === "matter2d" ? "no `intents` and no `settle`" : "no `intents`";
+    return `${world.file} exports ${hooks}, and its gravity is zero, so nothing in a local world built from it could ever move a body; bots run without client prediction.
   export the steering hooks your client passes to \`joinRoom({ physics2d })\` (a room that applies its forces inside \`tick()\` has none to share).`;
   }
   return void 0;
@@ -507,14 +519,12 @@ async function loadProjectWorld(options) {
   const entry = WORLD_CANDIDATES.map((c) => path2.resolve(options.cwd, c)).find(
     (f) => existsSync2(f)
   );
-  const matter2dRoom = async (why) => {
-    const room = await detectMatter2dRoom(options);
-    return room === void 0 ? void 0 : { engine: "matter2d", why: why(room), file: room };
-  };
+  const declared = await detectRoomEngine(options);
+  const planarRoom = (why) => declared === void 0 || declared.engine !== "matter2d" && declared.engine !== "rapier2d" ? void 0 : { engine: declared.engine, why: why(declared.file), file: declared.file };
   if (entry === void 0) {
-    return matter2dRoom(
-      (room) => `${room} declares a matter2d room and there is no shared world module beside it, so bots run without client prediction.
-  export the \`physics2d\` block your client passes to \`joinRoom\` from \`irtio/world.ts\` (gravity, bodies, intents, settle) to predict.`
+    return planarRoom(
+      (room) => `${room} declares a ${declared?.engine ?? "2D"} room and there is no shared world module beside it, so bots run without client prediction.
+  export the \`physics2d\` block your client passes to \`joinRoom\` from \`irtio/world.ts\` to predict.`
     );
   }
   const module = await bundleAndImport(entry, path2.join(options.outDir, "world.mjs"), options);
@@ -525,32 +535,40 @@ async function loadProjectWorld(options) {
   (this is what \`irtio init --physics\` writes)`
   );
   if (typeof gravity !== "object" || gravity === null || typeof gravity.x !== "number") {
-    const recognised = await matter2dRoom(
-      () => `${entry} exports no gravity, so it is not the client world a matter2d room predicts from; bots run without client prediction.
-  export the \`physics2d\` block your client passes to \`joinRoom\` (gravity, bodies, intents, settle) from this module to predict.`
+    const recognised = planarRoom(
+      () => `${entry} exports no gravity, so it is not the client world a ${declared?.engine ?? "2D"} room predicts from; bots run without client prediction.
+  export the \`physics2d\` block your client passes to \`joinRoom\` from this module to predict.`
     );
     if (recognised !== void 0) return recognised;
     throw notAWorld;
   }
-  if (typeof gravity.z !== "number") {
+  const planarEngine = declared?.engine === "rapier2d" ? "rapier2d" : declared?.engine === "matter2d" ? "matter2d" : declared === void 0 && typeof gravity.z !== "number" ? "matter2d" : void 0;
+  if (planarEngine !== void 0) {
     if (typeof gravity.y !== "number") throw notAWorld;
-    const world2d = {
-      engine: "matter2d",
+    const common = {
       gravity: { x: gravity.x, y: gravity.y },
       ...typeof module.timestep === "number" ? { timestep: module.timestep } : {},
-      ...typeof module.setup === "function" ? { setup: module.setup } : {},
       ...hookMap(module.bodies) !== void 0 ? { bodies: module.bodies } : {},
       ...hookMap(module.intents) !== void 0 ? { intents: module.intents } : {},
-      ...hookMap(module.settle) !== void 0 ? { settle: module.settle } : {},
       ...typeof module.epsilon === "number" ? { epsilon: module.epsilon } : {},
       ...typeof module.maxPredictedBodies === "number" ? { maxPredictedBodies: module.maxPredictedBodies } : {},
       ...typeof module.smoothingHalfLifeMs === "number" ? { smoothingHalfLifeMs: module.smoothingHalfLifeMs } : {},
       file: entry
     };
-    const why = whyNotPredictable(world2d);
-    return why === void 0 ? world2d : { engine: "matter2d", why, file: entry };
+    const planar = planarEngine === "rapier2d" ? {
+      engine: "rapier2d",
+      ...common,
+      ...typeof module.setup === "function" ? { setup: module.setup } : {}
+    } : {
+      engine: "matter2d",
+      ...common,
+      ...typeof module.setup === "function" ? { setup: module.setup } : {},
+      ...hookMap(module.settle) !== void 0 ? { settle: module.settle } : {}
+    };
+    const why = whyNotPredictable(planar);
+    return why === void 0 ? planar : { engine: planarEngine, why, file: entry };
   }
-  if (typeof gravity.y !== "number") throw notAWorld;
+  if (typeof gravity.y !== "number" || typeof gravity.z !== "number") throw notAWorld;
   return {
     engine: "rapier3d",
     gravity,
@@ -591,6 +609,38 @@ function canonicalMatterWorld(matter, engine) {
     )
   ).join(";");
 }
+async function checkWorldRapier2dDeterminism(world, schema) {
+  const factories = world.bodies ?? {};
+  const exercised = schema ? schema.collections.filter(
+    (c) => c.physics !== void 0 && factories[c.name] !== void 0
+  ) : [];
+  if (!world.setup && exercised.length === 0) return void 0;
+  const { initRapier2d } = await import("@irtio/runtime");
+  const { defaultRecord } = await import("@irtio/schema");
+  const rapier = await initRapier2d();
+  const build3 = () => {
+    const w = new rapier.World({ x: world.gravity.x, y: world.gravity.y });
+    try {
+      world.setup?.(w, rapier);
+      for (const desc of exercised) {
+        try {
+          const spec = factories[desc.name](rapier, defaultRecord(desc), "irtio-determinism-check");
+          if (spec?.body === void 0) continue;
+          const body = w.createRigidBody(spec.body);
+          for (const collider of spec.colliders ?? []) w.createCollider(collider, body);
+        } catch {
+        }
+      }
+      return w.takeSnapshot();
+    } finally {
+      w.free();
+    }
+  };
+  const first = build3();
+  const second = build3();
+  if (first.length === second.length && everyByteEqual(first, second)) return void 0;
+  return `the world builder is not deterministic: two builds of ${world.file} disagree. It must be pure over synced inputs \u2014 no Math.random(), no clock, no module state; put seeds and level parameters in synced state instead.`;
+}
 async function checkWorld2dDeterminism(world, schema) {
   const factories = world.bodies ?? {};
   const exercised = schema ? schema.collections.filter(
@@ -1043,9 +1093,12 @@ async function runSimulation(options = {}) {
   );
   const loadedWorld = hasPhysics ? await loadProjectWorld({ cwd, outDir, irtioPackages: options.irtioPackages }) : void 0;
   const world2d = is2dWorld(loadedWorld) ? loadedWorld : void 0;
-  const world = is2dWorld(loadedWorld) || isUnpredictedWorld(loadedWorld) ? void 0 : loadedWorld;
+  const worldR2d = isRapier2dWorld(loadedWorld) ? loadedWorld : void 0;
+  const world = is2dWorld(loadedWorld) || isRapier2dWorld(loadedWorld) || isUnpredictedWorld(loadedWorld) ? void 0 : loadedWorld;
   if (world2d !== void 0) {
     log(`physics: ${world2d.file} is a matter2d world; bots predict with physics2d`);
+  } else if (worldR2d !== void 0) {
+    log(`physics: ${worldR2d.file} is a rapier2d world; bots predict with physics2d`);
   } else if (isUnpredictedWorld(loadedWorld)) {
     log(pc.yellow(`physics: ${loadedWorld.why}`));
   }
@@ -1054,6 +1107,8 @@ async function runSimulation(options = {}) {
     worldError = await checkWorldDeterminism(world);
   } else if (world2d) {
     worldError = await checkWorld2dDeterminism(world2d, loaded?.schema);
+  } else if (worldR2d) {
+    worldError = await checkWorldRapier2dDeterminism(worldR2d, loaded?.schema);
   }
   const conditionsSpec = scenario?.conditions ?? conditionsFrom(options);
   const cheatSpec = scenario?.cheat ?? cheatFrom(options);
@@ -1072,7 +1127,7 @@ async function runSimulation(options = {}) {
     ...options.overrunsMax !== void 0 ? { overrunsMax: options.overrunsMax } : {},
     ...options.profile === true ? { profile: true } : {}
   };
-  const predicted = (world !== void 0 || world2d !== void 0) && worldError === void 0;
+  const predicted = (world !== void 0 || world2d !== void 0 || worldR2d !== void 0) && worldError === void 0;
   const projectKey = options.key ?? loaded?.schema?.project;
   if (options.queue !== void 0 && (projectKey === void 0 || projectKey === "")) {
     throw new RunNotPerformedError(
@@ -1124,6 +1179,21 @@ async function runSimulation(options = {}) {
           ...world2d.maxPredictedBodies !== void 0 ? { maxPredictedBodies: world2d.maxPredictedBodies } : {},
           ...world2d.smoothingHalfLifeMs !== void 0 ? { smoothingHalfLifeMs: world2d.smoothingHalfLifeMs } : {}
         }
+      } : {},
+      // The same `physics2d` option, under the engine discriminant: one planar option, two
+      // engines, and the client dispatches on the name rather than on the gravity's shape.
+      ...predicted && worldR2d !== void 0 ? {
+        physics2d: {
+          engine: "rapier2d",
+          gravity: worldR2d.gravity,
+          ...worldR2d.timestep !== void 0 ? { timestep: worldR2d.timestep } : {},
+          ...worldR2d.setup !== void 0 ? { setup: worldR2d.setup } : {},
+          ...worldR2d.bodies !== void 0 ? { bodies: worldR2d.bodies } : {},
+          ...worldR2d.intents !== void 0 ? { intents: worldR2d.intents } : {},
+          ...worldR2d.epsilon !== void 0 ? { epsilon: worldR2d.epsilon } : {},
+          ...worldR2d.maxPredictedBodies !== void 0 ? { maxPredictedBodies: worldR2d.maxPredictedBodies } : {},
+          ...worldR2d.smoothingHalfLifeMs !== void 0 ? { smoothingHalfLifeMs: worldR2d.smoothingHalfLifeMs } : {}
+        }
       } : {}
     }) : await spawnBots(bots, { ...spawn, script: relayEchoScript() });
   } catch (err) {
@@ -1283,10 +1353,10 @@ async function runSimulation(options = {}) {
     log(pc.red(`  FAIL world-builder: ${worldError}`));
   } else if (predicted) {
     const suppressed = report.totals.suppressedCorrections;
-    const engine = world2d !== void 0 ? "matter2d" : "rapier3d";
+    const engine = world2d !== void 0 ? "matter2d" : worldR2d !== void 0 ? "rapier2d" : "rapier3d";
     log(
       pc.dim(
-        `  bots predicted ${engine} physics from ${path2.relative(cwd, world?.file ?? world2d?.file ?? "")} (build-twice check held; ${suppressed} within-epsilon correction(s) suppressed)`
+        `  bots predicted ${engine} physics from ${path2.relative(cwd, world?.file ?? world2d?.file ?? worldR2d?.file ?? "")} (build-twice check held; ${suppressed} within-epsilon correction(s) suppressed)`
       )
     );
   } else if (hasPhysics && isUnpredictedWorld(loadedWorld)) {
@@ -1362,9 +1432,12 @@ export {
   ceilingFor,
   checkWorld2dDeterminism,
   checkWorldDeterminism,
+  checkWorldRapier2dDeterminism,
   detectMatter2dRoom,
+  detectRoomEngine,
   formatBuildIdentity,
   is2dWorld,
+  isRapier2dWorld,
   isUnpredictedWorld,
   loadProjectSchema,
   loadProjectWorld,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "irtio CLI: local dev server, room scaffolding, bot simulation, deploy, logs and rooms",
   "license": "MIT",
   "publishConfig": {
@@ -45,16 +45,17 @@
     "esbuild": "^0.27.3",
     "picocolors": "^1.1.1",
     "ws": "^8.18.0",
-    "@irtio/bots": "0.7.0",
-    "@irtio/client": "0.7.0",
-    "@irtio/protocol": "0.7.0",
-    "@irtio/runtime": "0.7.0",
-    "@irtio/schema": "0.7.0",
-    "@irtio/server": "0.7.0"
+    "@irtio/bots": "0.8.0",
+    "@irtio/client": "0.8.0",
+    "@irtio/runtime": "0.8.0",
+    "@irtio/schema": "0.8.0",
+    "@irtio/server": "0.8.0",
+    "@irtio/protocol": "0.8.0"
   },
   "devDependencies": {
     "@types/ws": "^8.5.13",
     "@dimforge/rapier3d-compat": "0.20.0",
+    "@dimforge/rapier2d-compat": "0.20.0",
     "@irtio/store": "0.0.0",
     "@irtio/supervisor": "0.0.0"
   },