@homie-rocks/studio 0.47.0 → 0.48.0

package/CHANGELOG.md

@@ -17,6 +17,45 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.48.0] - 2026-10-13
+
+**Plugin 0.48.0** · Baked physics worlds for server rules and local prediction.
+
+Rules games can sweep capsules through a baked GLB with the same deterministic physics on the server and in local prediction.
+
+### Added
+
+- Rules games can opt into deterministic Rapier collision through
+  `@homie-rocks/physics`: build-time GLB baking, asynchronous initialization before
+  ticking, synchronous metered capsule sweeps, casts, rays, overlaps and solver
+  steps, and complete physics snapshots saved with the room. Browser movement
+  replays against the same baked world. Games without physics retain their
+  existing behavior and budget costs.
+- `ctx.substeps(body, hz, callback)` lets a game choose its own integration rate
+  within a room tick. Server and browser share the callback and budget; the view
+  draws its recorded intermediate poses. The build checks authoritative body
+  fields separately from these temporary drawing traces.
+- Release tests compare 220 complete guarded-room hashes across Node, Chrome and
+  workerd for eight capsules at 300 Hz on a 1,754-triangle level, restore mid-fall,
+  and settle two predictions exactly with 150 ms each way and seeded packet loss.
+  The calibration and real two-Chrome-player Octree trial are recorded in
+  `docs/physics-048-calibration.md` and `docs/receipts/`.
+- Physics 0.1.2 adds a stateless capsule cast for applications that own integration
+  and replay; it uses the package's existing character contact handling.
+
+### Fixed
+
+- Predictor callbacks that inspect the room no longer reenter snapshot replay.
+- Provider discovery recognizes existing Homie fal and ElevenLabs key files,
+  including the legacy workspace location, without copying or exposing keys.
+
+### Upgrade notes
+
+- Physics is opt-in. Install `@homie-rocks/physics` 0.1.2 and name the
+  game's static GLB with `map.physics.level`; see the Physics section of the
+  rules guide. The complete solver save can exceed browser-host checkpoint caps,
+  so the real-mesh example uses server hosting.
+
 ## [0.47.0] - 2026-10-13
 
 **Plugin 0.47.0** · Wrapped worlds and generated collision maps.

package/guides/game/RULES.md

@@ -404,6 +404,46 @@ map.spots, and `world.sweep/support/overlaps` (also on map). Sweeps test static
 `20 + 4S` plus copying, writes body.pos, and returns an optional hit.
 Movement may write pos, vel, heading, grounded and declared motion; never return
 an updated body. Normalize diagonals and respect maxSpeed. Collision movement needs a sweep; setting velocity alone does not move a body.
+
+### Integrating at the game's own rate
+
+Opt in from `move` with `ctx.substeps(body, hz, step)`. For a 20 Hz room,
+300 Hz runs fifteen integrations inside each tick; 60 Hz runs three. The rate
+must be a positive integer multiple of the room rate. Existing movement is
+unchanged unless it calls this method.
+
+```ts
+export const move = defineMove({
+  runner(body, input, ctx) {
+    ctx.substeps(body, 300, step => {
+      if (step.first && input.jump && body.grounded)
+        body.vel = { ...body.vel, z: 8 };
+      body.vel = { ...body.vel, z: body.vel.z - 30 * step.dt };
+      ctx.map.sweep(body, ctx.math.scale(body.vel, step.dt));
+    });
+  }
+});
+```
+
+The callback receives `dt` (seconds), zero-based `index`, `count`, `first`
+and end-of-step `fraction`. Use `step.dt` for integration; `ctx.dt` remains
+the full tick. A pulse belongs to the tick: consume it on `step.first` when
+it should act once. Held inputs retain their existing tick-mean semantics;
+this API does not recover the timestamp of changes within a tick. A game
+that already reconstructs held transitions can keep that policy in the
+callback. It does not change Stormbreak's existing integration.
+
+One body may be integrated once per move. The call charges 8 units plus
+64 per pose (the initial pose and each completed substep), before allocating
+the trace. Guarded callback operations and collision queries charge the
+same movement-handler budget as usual. There is no separate quota or
+implicit rate cap.
+
+The browser predicts the identical callback and draws between the recorded
+substep poses, including a path that leaves and returns to the same tick
+endpoint. The trace is temporary drawing data: it adds no wire fields or
+save fields. The final body and declared motion fields are saved as before.
+This helper does not add triangle collision or a physics world.
 Put freezes, boost expiry and knockback in declared motion. Initialize a late arrival
 in on.arrive too: onRoom.roundStart already happened before it joined.
 
@@ -1078,6 +1118,15 @@ leaves: take the marker down quietly. `ctx.ray/rays/rayAll` query what the
 player sees (`ctx.viewTick`); `ctx.preview` says the run is between ticks. A
 predictor runs often: keep it cheap, and keep per-entity state in `me`.
 
+`ctx.each(kind, fn)` reads frozen entities from the authoritative snapshot this
+prediction started from. Use it for pickups and other snapshot-based decisions;
+it excludes provisional ghosts. Reading `room.each`, `room.get`, `room.me` or
+ray queries inside a predictor cannot advance the clock or start a nested
+preview. Other room entities retain their normal drawn poses; `room.me` reads
+the authoritative own entity during the callback. Use the callback's `me` for
+the predicted own state. Snapshot reconciliation also prevents clock pumping
+through event listeners until replay finishes.
+
 To guess a shot the server will judge with rewind, ask for what the server
 will use (0.46.5). `ctx.judgedTick(aimTick)` is the tick it will pose the others
 at: the `aimTick` the input carries, held to how far back this seat may look
@@ -1245,3 +1294,94 @@ entities remain suitable for independently moving doors, cover and platforms.
 `spawn` exposes a new entity before its deferred `on.arrive` handler. Pass every
 field that must be valid immediately in the spawn data; use `arrive` for subsequent
 work, not for mandatory initialization.
+
+## Physics
+
+Use the opt-in `@homie-rocks/physics` bridge when the level is an arbitrary triangle
+mesh: caves, ramps, stairs and the static environment of a game such as Octree
+Arena. Keep `ctx.map` for the kernel's boxes, circles, capsules and height tiles.
+Install `@homie-rocks/physics` 0.1.2 in the studio. A game that does not
+ask for physics loads no physics engine and pays no physics units.
+
+In `map/main.json`, name a static GLB relative to the game directory:
+
+```json
+{
+  "bounds": { "min": [-100, -100, -100], "max": [100, 100, 100] },
+  "physics": { "level": "assets/level.glb" }
+}
+```
+
+The build bakes the default scene's node transforms and triangles into the
+physics package's indexed mesh format. It converts glTF Y-up to rules Z-up
+(`x, -z, y`), preserves reflected winding, and ships the baked mesh with the
+server rules and the browser movement bundle. Skins, animations and morph targets
+need a separate static collision GLB. The server never loads or parses a GLB.
+
+The smallest moving capsule uses the same guarded movement on both sides:
+
+```ts
+// src/move.ts
+import { defineMove } from '@homie-rocks/studio/rules';
+export const move = defineMove({ runner(body, input, ctx) {
+  ctx.substeps(body, 300, step => {
+    if (step.first && input.jump && body.grounded)
+      body.vel = { x: body.vel.x, y: body.vel.y, z: 10 };
+    body.vel = { x: input.ax * 5, y: 0, z: body.vel.z - 30 * step.dt };
+    ctx.physics.sweep(body, ctx.math.scale(body.vel, step.dt), .35, 1.35);
+  });
+} });
+
+// src/rules.ts
+import { defineRules, f } from '@homie-rocks/studio/rules';
+import { move } from './move';
+export default defineRules({
+  contract: 2, space: { dims: 3 }, move,
+  entities: { runner: {
+    player: true,
+    input: { ax: f.held(), jump: f.press() },
+    body: { shape: 'capsule', radius: .35, height: 1.35, maxSpeed: 30 }
+  } },
+  room: { bots: { keep: 0 }, join() {
+    return { kind: 'runner', at: { x: 0, y: 0, z: 8 } };
+  } }
+});
+```
+
+Use `"room": {"host":"server","offline":false}` in `game.json`. Physics
+initialization is awaited once per isolate before any room can tick; calls inside
+a handler are synchronous. `sweep(body, delta, radius, height)` sweeps and slides
+an upright capsule whose `body.pos` is its centre and whose height includes its
+caps. It writes position, velocity and grounded state. `ctx.physics.cast`,
+`ray`, and `overlap` expose the package's convex shape cast, raycast and overlap
+queries; query shapes are boxes, spheres or capsules. Room/entity handlers have
+these operations at `world.physics` and can call `world.physics.step(seconds)`
+to advance the collision world's solver clock. Movement owns capsule integration;
+its queries do not create persistent physics bodies or advance another player's
+world. This bridge exposes the baked collision world, not rigid-body ownership or
+predicted dynamic-body interactions.
+
+Every operation is charged before its engine work. On a 1,754-triangle level:
+
+| Operation | Budget units |
+| --- | ---: |
+| Capsule/convex cast | 768 |
+| Ray | 640 |
+| Overlap | 640 |
+| Solver step | 8 + 2,400 per 1/300 second |
+| Capsule sweep and slide | 64 + 768 per cast, at most four casts |
+
+Mesh-query and solver charges scale by `ceil(triangles / 1754)`, at least one.
+Substeps retain their usual pose and guarded callback charges. There is no new
+room budget, player cap or rate quota. The reproducible calibration is
+`scripts/calibrate-rules-physics.mjs`; its receipt compares physics on the real
+mesh with kernel operations on a box, since the kernel has no arbitrary-mesh
+or solver-step equivalent.
+
+A room save includes the package's complete binary world snapshot as JSON bytes,
+including solver state and its time remainder. The capsule's position, velocity,
+grounded flag and declared motion are saved by rules as usual. Browser prediction
+creates the same baked world and replays pending guarded movement against it;
+substep drawing traces remain temporary. Physics worlds are disposed when their
+host or view closes. A full solver save can exceed browser-host checkpoint caps;
+the build measures this, and server-hosted rooms retain the full save.

package/guides/game/SKILL.md

@@ -6,6 +6,11 @@ metadata:
   providers: cloudflare github ollama
 ---
 
+For a game with its own fixed integration rate, use the opt-in
+`ctx.substeps(body, hz, step)` facility in `RULES.md` (Integrating at the game's
+own rate). Its callbacks share the tick budget and its recorded poses drive
+local drawing. Keep the game's input-transition policy explicit.
+
 Read the installed toolkit's `node_modules/@homie-rocks/studio/guides/game/{RULES,REWRITE}.md`
 before authoring: these match its runtime even when this plugin is older. Toolkit
 check/build report stale installed plugin copies and the update step. For solid slopes and terrain, use heightTiles with `base` and the source
@@ -451,3 +456,16 @@ nothing is cut off or runs off the side. Fix what you see; build again.
 A whole landing of the studio's own (`site/pages/<id>/index.html`) replaces the generated one: only when
 the person asks for a hand-made page, and start from the generated one's HTML so Play, the TV road and
 "Made with Homie" stay.
+
+## Physics
+
+For movement against a static GLB's triangles, use the opt-in physics bridge in
+[RULES.md](RULES.md#physics). Install `@homie-rocks/physics` 0.1.2, set
+`map/main.json`'s `physics.level` to the game's GLB, and call
+`ctx.physics.sweep(body, delta, radius, height)` inside the game's movement.
+`ctx.substeps(body, 300, step => { ... })` shares its existing handler budget and
+predicts the same baked world in the browser. The full example, cost table and
+save contract are in that section. Prefer kernel collision for its primitive
+maps; use physics for arbitrary static triangle levels. Initialization is awaited
+before the first room tick, calls in handlers are synchronous, and the complete
+physics snapshot is saved with the room. No opt-in means no physics load or cost.

package/lib/doctor.mjs

@@ -1,3 +1,4 @@
+import { providerKey } from './provider-key.mjs';
 /**
  * `homie-studio setup status` (also `homie-studio doctor`): what this computer and this person's accounts have for
  * a studio, as one checklist, before anything is made. For each thing: green, missing, or "do this now", what it
@@ -231,16 +232,17 @@ export async function setupStatus({
         const s = await exec(cliBin, ['auth', 'status', '--format', 'json'], { timeout: 10_000 });
         try { signedIn = Boolean(JSON.parse(s.stdout)?.schemes?.some((x) => x.logged_in)); } catch { signedIn = false; }
       }
-      return { cli: v.code === 0, signedIn, key: Boolean(env.ELEVENLABS_API_KEY), projects: root ? projectsElevenLabs(root) : false };
+      const credential = providerKey('elevenlabs', env);
+      return { cli: v.code === 0, signedIn, key: Boolean(credential.key), source: credential.source, projects: root ? projectsElevenLabs(root) : false };
     })(),
     (async () => {
-      const key = String(env.FAL_KEY ?? '').trim();
+      const { key, source } = providerKey('fal', env);
       if (!key) return { key: false };
       const base = String(env.FAL_API_URL || 'https://api.fal.ai').replace(/\/+$/, '');
       try {
         const res = await fetchFn(`${base}/v1/models/pricing?endpoint_id=fal-ai/flux/dev`, { headers: { Authorization: `Key ${key}` }, signal: AbortSignal.timeout(6000) });
-        return { key: true, valid: res.ok ? true : res.status === 401 || res.status === 403 ? false : null };
-      } catch { return { key: true, valid: null }; }
+        return { key: true, source, valid: res.ok ? true : res.status === 401 || res.status === 403 ? false : null };
+      } catch { return { key: true, source, valid: null }; }
     })(),
   ]);
 
@@ -386,7 +388,7 @@ export async function setupStatus({
   // ElevenLabs.
   rows.push({
     id: 'elevenlabs', label: 'ElevenLabs', need: 'optional', state: eleven.signedIn || eleven.key || eleven.projects ? 'ok' : 'optional',
-    detail: eleven.signedIn ? 'the elevenlabs CLI is signed in' : eleven.key ? 'ELEVENLABS_API_KEY is set' : eleven.projects ? 'through Stripe Projects (its key, in the studio\'s git-ignored .env; never shown)' : eleven.cli ? 'the elevenlabs CLI is here, not signed in' : 'not connected',
+    detail: eleven.signedIn ? 'the elevenlabs CLI is signed in' : eleven.key ? `key from ${eleven.source}` : eleven.projects ? 'through Stripe Projects (its key, in the studio\'s git-ignored .env; never shown)' : eleven.cli ? 'the elevenlabs CLI is here, not signed in' : 'not connected',
     unlocks: 'songs and game scores (the music skill), billed to your own ElevenLabs plan; every render is quoted first',
     fix: eleven.signedIn || eleven.key || eleven.projects ? null : eleven.cli
       ? { who: 'ai', run: 'elevenlabs auth login', say: 'ElevenLabs opens in your browser; sign in once. No key is pasted anywhere.' }
@@ -396,7 +398,7 @@ export async function setupStatus({
   // fal.
   rows.push({
     id: 'fal', label: 'fal', need: 'optional', state: fal.key ? (fal.valid === false ? 'act' : 'ok') : 'optional',
-    detail: !fal.key ? 'no FAL_KEY in this environment' : fal.valid === true ? 'FAL_KEY is set and fal accepts it' : fal.valid === false ? 'fal refused the FAL_KEY that is set (wrong or revoked)' : 'FAL_KEY is set (fal did not answer just now)',
+    detail: !fal.key ? 'no fal key in the environment or Homie key files' : `key from ${fal.source}; ${fal.valid === true ? 'fal accepts it' : fal.valid === false ? 'fal refused it (wrong or revoked)' : 'fal did not answer just now'}`,
     unlocks: 'painted art and backdrops (the art skill) and generated video clips (the video skill), on your own fal account under a budget; covers from a real frame and captured trailers are free',
     fix: fal.key && fal.valid !== false ? null : { who: 'ai', say: 'Use local art and captured footage. Paid fal scripts need an already connected account; never ask the person to find or set a key. Offer the provider browser connection only when generated media is requested.', open: 'https://fal.ai/dashboard' },
   });

package/lib/mcp-tools.mjs

@@ -1,3 +1,4 @@
+import { providerKey } from './provider-key.mjs';
 /**
  * THE LOCAL MCP SERVER'S TOOLS (`homie-studio mcp`, lib/mcp.mjs): the studio toolkit as MCP tools, so the Claude
  * desktop app (through the Homie extension), Claude Code or any MCP client builds games in the SAME chat that shows
@@ -1497,7 +1498,7 @@ export function toolDefs(ctx, avail = {}) {
 
 /** What the media tools need, cheaply (no network): ffmpeg on the PATH, ElevenLabs' CLI or key. */
 export function availability(env = process.env) {
-  return { node: true, ffmpeg: Boolean(which(process.platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg')), elevenlabs: Boolean(env.ELEVENLABS_API_KEY || which(process.platform === 'win32' ? 'elevenlabs.exe' : 'elevenlabs')) };
+  return { node: true, ffmpeg: Boolean(which(process.platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg')), elevenlabs: Boolean(providerKey('elevenlabs', env).key || which(process.platform === 'win32' ? 'elevenlabs.exe' : 'elevenlabs')) };
 }
 
 /** The codex page small enough to hand a card (a tool result over ~150,000 characters is not shown). */

package/lib/physics-mesh.mjs

@@ -0,0 +1,40 @@
+import { NodeIO } from '@gltf-transform/core';
+import { Matrix4, Vector3 } from 'three';
+
+/** Build-time only: bake the default GLB scene, including every node transform.
+ * Rules use Z-up; glTF is Y-up. (x,y,z) -> (x,-z,y) preserves handedness.
+ * Animated, skinned and morphing geometry needs an explicitly authored static collider.
+ */
+export async function bakePhysicsMesh(path) {
+  const document = await new NodeIO().read(path);
+  const root = document.getRoot();
+  const scene = root.getDefaultScene() ?? root.listScenes()[0];
+  if (!scene || root.listAnimations().length) throw new Error('physics mesh: needs a static default scene');
+  const vertices = [], indices = [];
+  scene.traverse(node => {
+    if (node.getSkin()) throw new Error('physics mesh: skinned nodes need a static collider');
+    const matrix = new Matrix4().fromArray(node.getWorldMatrix());
+    const mirrored = matrix.determinant() < 0;
+    for (const primitive of node.getMesh()?.listPrimitives() ?? []) {
+      if (primitive.getMode() !== 4 || primitive.listTargets().length) throw new Error('physics mesh: only static triangles are supported');
+      const positions = primitive.getAttribute('POSITION'), index = primitive.getIndices();
+      if (!positions || positions.getElementSize() !== 3) throw new Error('physics mesh: missing xyz positions');
+      const base = vertices.length / 3;
+      for (let i = 0; i < positions.getCount(); i++) {
+        const p = new Vector3().fromArray(positions.getElement(i, [])).applyMatrix4(matrix);
+        if (![p.x,p.y,p.z].every(Number.isFinite)) throw new Error('physics mesh: nonfinite vertex');
+        vertices.push(Math.fround(p.x), Math.fround(-p.z), Math.fround(p.y));
+      }
+      const count = index?.getCount() ?? positions.getCount();
+      if (count % 3) throw new Error('physics mesh: incomplete triangle');
+      for (let i = 0; i < count; i += 3) {
+        const triangle = [0,1,2].map(j => index ? index.getScalar(i+j) : i+j);
+        if (!triangle.every(n => Number.isSafeInteger(n) && n >= 0 && n < positions.getCount())) throw new Error('physics mesh: index out of range');
+        if (mirrored) [triangle[1],triangle[2]] = [triangle[2],triangle[1]];
+        indices.push(...triangle.map(n => base+n));
+      }
+    }
+  });
+  if (!indices.length) throw new Error('physics mesh: no triangles');
+  return { vertices, indices };
+}

package/lib/provider-key.mjs

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** Read only; callers must expose source, never key. No environment mutation. */
+export function providerKey(provider, env = process.env) {
+  const variable = { fal: 'FAL_KEY', elevenlabs: 'ELEVENLABS_API_KEY' }[provider];
+  if (!variable) throw new TypeError('unknown media provider');
+  const value = String(env[variable] ?? '').trim();
+  if (value) return { key: value, source: variable };
+  // An explicitly supplied environment is also an isolated home in tests/tools.
+  const home = env.HOME || env.USERPROFILE || (env === process.env ? homedir() : null);
+  if (home) for (const relative of [`keys/${provider}-key`, `workspace/${provider}-key`]) {
+    const path = join(home, '.homie', relative);
+    try {
+      const key = readFileSync(path, 'utf8').trim();
+      if (key && !/[\r\n]/.test(key)) return { key, source: `~/.homie/${relative}` };
+    } catch { /* Missing or unreadable files are not credentials. */ }
+  }
+  return { key: null, source: null };
+}

package/lib/rules-build.mjs

@@ -23,8 +23,8 @@ import { seatsOf } from '../worker/seats.mjs';
  */
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { join, resolve, relative, isAbsolute } from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 import { GUARD_MODULE, RULES_MODULE, guardRules, guardedPlugin, problemLine } from './rules-guard.mjs';
 import { capOf, RULES_FRAMES, rulesRates } from '../worker/limits.mjs';
 import { PACKAGE_ROOT, isRulesGame, rulesIndex } from './studio.mjs';
@@ -66,15 +66,15 @@ function readMap(g) {
  * `W` (guard.ts, the wall), `P` (pack.ts) and `M` (math.ts). They are one instance together, apart from any other
  * copy of the runtime in this process, so the guard's budget counter is theirs alone.
  */
-export async function loadRules(esbuild, root, id, code, { bundleOnly = false } = {}) {
+export async function loadRules(esbuild, root, id, code, { bundleOnly = false, physics = false } = {}) {
   const dir = join(root, '.studio', 'rules');
   mkdirSync(dir, { recursive: true });
   const gen = join(dir, `${id}-${process.pid}-${++loads}.linked.mjs`);
   writeFileSync(gen, code);
   const lib = (name) => JSON.stringify(join(PACKAGE_ROOT, 'rules', name));
-  const entry = `import def from ${JSON.stringify(gen)};\nimport * as R from ${lib('rules.ts')};\nimport * as H from ${lib('host.ts')};\nimport * as C from ${lib('core.ts')};\nimport * as W from ${lib('guard.ts')};\nimport * as P from ${lib('pack.ts')};\nimport * as M from ${lib('math.ts')};\nexport { def, R, H, C, W, P, M };\n`;
+  const entry = `import def from ${JSON.stringify(gen)};\nimport * as R from ${lib('rules.ts')};\nimport * as H from ${lib('host.ts')};\nimport * as C from ${lib('core.ts')};\nimport * as W from ${lib('guard.ts')};\nimport * as P from ${lib('pack.ts')};\nimport * as M from ${lib('math.ts')};\nexport { def, R, H, C, W, P, M };\n${physics ? `export { initializePhysics } from ${lib('physics-engine.ts')};` : ''}`;
   try {
-  const res = await esbuild.build({ stdin: { contents: entry, resolveDir: root, loader: 'js' }, bundle: true, format: bundleOnly ? 'cjs' : 'esm', target: 'es2022', platform: 'neutral', write: false, logLevel: 'silent', plugins: [rulesModulesPlugin()] });
+  const res = await esbuild.build({ stdin: { contents: entry, resolveDir: root, loader: 'js' }, bundle: true, format: bundleOnly ? 'cjs' : 'esm', target: 'es2022', platform: 'neutral', ...(physics ? {mainFields: ['module','main']} : {}), write: false, logLevel: 'silent', plugins: [rulesModulesPlugin()] });
   const text = res.outputFiles[0].text;
   if (bundleOnly) { rmSync(gen, { force: true }); return text; }
   const out = join(dir, `${id}.check-${createHash('sha256').update(text).digest('hex').slice(0, 12)}-${process.pid}-${(loads += 1)}.mjs`);
@@ -146,8 +146,15 @@ export async function prepareRules(esbuild, root, g, { log = () => {}, longCheck
   if (!guarded.ok) throw new Error(`${g.kind === 'app' ? 'apps' : 'games'}/${g.id}: its rules were refused.\n${guarded.problems.slice(0, 20).map((p) => `  ${problemLine(p)}`).join('\n')}${guarded.problems.length > 20 ? `\n  … and ${guarded.problems.length - 20} more` : ''}`);
   const tune = readJson(join(g.dir, 'tunables.json')) ?? {};
   const map = readMap(g);
+  if (map.physics !== undefined) {
+    const { bakePhysicsMesh } = await import('./physics-mesh.mjs');
+    if (!map.physics || typeof map.physics.level !== 'string') throw new Error('map.physics.level must name the game’s static GLB');
+    const path = resolve(g.dir, map.physics.level), rel = relative(g.dir, path);
+    if (rel.startsWith('..') || isAbsolute(rel)) throw new Error('physics level must be inside the game');
+    map.physics = await bakePhysicsMesh(path);
+  }
   const seats = seatsOf(g);
-  const bundle = await loadRules(esbuild, root, g.id, guarded.code, { bundleOnly: true });
+  const bundle = await loadRules(esbuild, root, g.id, guarded.code, { bundleOnly: true, physics: Boolean(map.physics) });
   const data = { id: g.id, tune, map, room: g.room, seats, vocab: readJson(join(g.dir, 'agents.json')), sites: guarded.sites };
   // The declarations first, for the type check: a wrong program is named by the compiler before anything is played.
   await typecheckRules(root, g, await runRulesWorker(bundle, data, { declarationsOnly: true }), tune, { log });
@@ -158,7 +165,8 @@ export async function prepareRules(esbuild, root, g, { log = () => {}, longCheck
   const trial = RULES_CAPACITY_TRIAL;
   log(`info: rules runtime reference trial: ${trial.game}, ${trial.seats} players at ${trial.tickHz} Hz for ${trial.minutes} minutes on ${trial.host} (${trial.platform}). Cloudflare capacity and billing are unmeasured.`);
   if (settings.tickHz > trial.tickHz) log(`info: ${g.kind === 'app' ? 'apps' : 'games'}/${g.id} asks for ${settings.tickHz} Hz, above the completed local reference trial's ${trial.tickHz} Hz. This game's generated check does not establish live room capacity.`);
-  const { def, R, H } = await loadRules(esbuild, root, g.id, guarded.code);
+  const { def, R, H, initializePhysics } = await loadRules(esbuild, root, g.id, guarded.code, {physics: Boolean(map.physics)});
+  if (initializePhysics) await initializePhysics(readFileSync(new URL(import.meta.resolve('@homie-rocks/physics/vendor/rapier.wasm'))));
   const compiled = R.compileRules(def, { tune, map: R.compileMap(map, map.name), settings, seats });
   const stats = smokeRun(H, compiled, g.id, { timer: () => 0, vocab: data.vocab });
   const snapshotCap = capOf('snap', seats); const checkpointCap = capOf('ckpt', seats);
@@ -207,8 +215,8 @@ export function viewPlugin(g, rules, entry, { lab = false } = {}) {
         if (a.path === 'homie:rules') return { contents: rules.code, resolveDir: g.dir, loader: 'js' };
         if (a.path === 'homie:host') return { contents: `import def from 'homie:rules';\nimport { browserHost } from ${JSON.stringify(join(PACKAGE_ROOT, 'rules', 'browser.ts'))};\nexport const makeHost = browserHost(def, ${JSON.stringify({ id: g.id, build: rules.build, tune: rules.tune, map: rules.map, settings: rules.settings, seats: rules.seats, vocab: game.vocab })});\n`, resolveDir: g.dir, loader: 'js' };
         return (a.path === 'homie:view'
-        ? { contents: `import 'homie:game';\nimport ${JSON.stringify(entry)};\n`, resolveDir: g.dir, loader: 'js' }
-        : { contents: `${existsSync(move) ? `import { move } from ${JSON.stringify(move)};` : 'const move = {};'}\nimport { setGame${game.vocab ? ', setAgentFactory' : ''} } from '${RULES_MODULE}/view';\n${game.vocab ? `import { useAgents } from ${JSON.stringify(join(PACKAGE_ROOT, 'agents/agents.ts'))}; setAgentFactory(useAgents);` : ''}\n${factory}\nsetGame(${JSON.stringify(game)}, move, loadHost);\n`, resolveDir: g.dir, loader: 'js' });
+        ? { contents: `import 'homie:game';\n${rules.map.physics ? `await import(${JSON.stringify(entry)});` : `import ${JSON.stringify(entry)};`}\n`, resolveDir: g.dir, loader: 'js' }
+        : { contents: `${existsSync(move) ? `import { move } from ${JSON.stringify(move)};` : 'const move = {};'}\nimport { setGame${game.vocab ? ', setAgentFactory' : ''} } from '${RULES_MODULE}/view';\n${game.vocab ? `import { useAgents } from ${JSON.stringify(join(PACKAGE_ROOT, 'agents/agents.ts'))}; setAgentFactory(useAgents);` : ''}\n${factory}\n${rules.map.physics ? `import {initializePhysics} from ${JSON.stringify(join(PACKAGE_ROOT, 'rules', 'physics-engine.ts'))}; import bytes from ${JSON.stringify(fileURLToPath(new URL('./dist/vendor/bytes.js', import.meta.resolve('@homie-rocks/physics/package.json'))))}; await initializePhysics(Uint8Array.from(atob(bytes), c => c.charCodeAt(0)));` : ''}\nsetGame(${JSON.stringify(game)}, move, loadHost);\n`, resolveDir: g.dir, loader: 'js' });
       });
       rulesModulesPlugin().setup(b);
       guarded.setup(b);
@@ -228,7 +236,7 @@ export function writeRules(root, built, ids) {
   mkdirSync(dir, { recursive: true });
   for (const r of built.filter((r) => r.settings.host === 'server')) {
     writeFileSync(join(dir, `${r.id}.mjs`), `${HEADER}// The rules of games/${r.id}, checked and guarded (build ${r.build}).\n${r.code}`);
-    writeFileSync(join(dir, `${r.id}.data.mjs`), `${HEADER}export default ${JSON.stringify({ tune: r.tune, map: r.map, settings: r.settings, seats: r.seats, build: r.build, stateHash: r.stateHash }, null, 2)};\n`);
+    writeFileSync(join(dir, `${r.id}.data.mjs`), `${HEADER}${r.map.physics ? `import {initializePhysics} from '@homie-rocks/studio/rules/physics-engine';\nimport wasm from '@homie-rocks/physics/vendor/rapier.wasm';\n` : ''}export default ${r.map.physics ? '{initialize: () => initializePhysics(wasm), ...' : ''}${JSON.stringify({ tune: r.tune, map: r.map, settings: r.settings, seats: r.seats, build: r.build, stateHash: r.stateHash }, null, 2)}${r.map.physics ? '}' : ''};\n`);
   }
   const have = ids.filter((id) => existsSync(join(dir, `${id}.mjs`)) && existsSync(join(dir, `${id}.data.mjs`)));
   for (const name of readdirSync(dir)) {

package/lib/rules-check-worker.mjs

@@ -20,6 +20,7 @@ import { boundPosition } from '../rules/topology.mjs';
  * units used by the room and by the browsers' `move`, bytes of save rebuilt), never by a clock, so the same source gives
  * the same verdict and the same lines on every computer.
  */
+import { readFileSync } from 'node:fs';
 import { parentPort, workerData } from 'node:worker_threads';
 import { compileFunction } from 'node:vm';
 import { checkDecide } from '../worker/brain.mjs';
@@ -356,6 +357,7 @@ function play(c, companions, allow) {
       const r = kind.body.radius, height = kind.body.height || 2 * r, bounds = c.map.bounds;
       result.pos = L.P.vec3(boundPosition(result.pos,geometry??c.map,r,height,c.dims),c.dims);
       delete result.used;
+      delete result.steps; // Drawing traces are not authoritative body fields.
       if (JSON.stringify(result) !== JSON.stringify(after)) fault ??= `${siteOf(name, 'move')} ${name}.move: prediction and the server produced different bodies from the same input.${when()}`;
     }
     if (A.core.stats.tickUnits > peak) peak = A.core.stats.tickUnits;
@@ -390,6 +392,7 @@ try {
     let at = null; try { const g = linked.exports.W.G; if (g.line) at = `${g.file}:${g.line}`; } catch { /* the guard itself did not load */ }
     throw new Error(`${at ?? here()}: ${diagnostic(String(error?.message ?? error))}`);
   }
+  if (L.initializePhysics) await L.initializePhysics(readFileSync(new URL(import.meta.resolve('@homie-rocks/physics/vendor/rapier.wasm'))));
   const { c, problems } = compile();
   const result = { vocab: data.vocab, schema: L.R.schemaOf(c), publicTune: c.publicTune, settings: c.settings, problems, rounds: c.rounds, stateHash: stateHash(c),
     declarations: { events: c.events, asks: Object.fromEntries(Object.entries(c.asks).map(([n, a]) => [n, { state: a.stateFields, questions: a.questions }])), view: L.def.shapes?.view ?? {} } };

package/lib/rules-check.mjs

@@ -67,5 +67,5 @@ export function runRulesWorker(bundle, data, { declarationsOnly = false, allowan
 export async function checkRules(esbuild, root, id, code, data, options = {}) {
   // Imported here, not at the top: the worker imports this file for `stateHash`, and has no use for the build's tools.
   const { loadRules } = await import('./rules-build.mjs');
-  return runRulesWorker(await loadRules(esbuild, root, id, code, { bundleOnly: true }), { id, ...data }, options);
+  return runRulesWorker(await loadRules(esbuild, root, id, code, { bundleOnly: true, physics: Boolean(data.map?.physics) }), { id, ...data }, options);
 }

package/lib/rules-guard.mjs

@@ -69,9 +69,10 @@ export const HOOK_NAMES = ['valueOf', 'toString', 'toJSON'];
 export const WORLD_METHODS = ['ticks', 'random', 'route', 'label', 'send', 'dispatch', 'sendRoom', 'announce', 'sendArea', 'after', 'emit', 'spawn', 'despawn', 'place', 'near', 'inBox', 'ray', 'rayAll', 'rays', 'sweep', 'ask', 'goalDone', 'finish', 'end', 'restart', 'spot', 'spots', 'replace', 'tile', 'distance', 'flow'];
 export const MATH_METHODS = ['sin', 'cos', 'tan', 'atan', 'atan2', 'asin', 'acos', 'exp', 'log', 'pow', 'hypot', 'rad', 'deg', 'clamp', 'lerp', 'vec', 'add', 'sub', 'scale', 'dot', 'cross', 'len', 'dist', 'norm', 'clampLen', 'lerpVec', 'dir', 'angle'];
 const VALUE_METHODS = new Set([...ARRAY_METHODS, ...STRING_METHODS, ...MAPSET_METHODS]);
-export const MOVE_METHODS = ['support', 'overlaps'];
-const NEW_METHODS = new Set(['route','label','dispatch','rayAll','rays','restart','replace','tile','distance','flow']);
-const CALLABLE = new Set([...VALUE_METHODS, ...WORLD_METHODS, ...MOVE_METHODS, ...MATH_METHODS]);
+export const MOVE_METHODS = ['substeps', 'support', 'overlaps'];
+export const PHYSICS_METHODS = ['step', 'cast', 'overlap'];
+const NEW_METHODS = new Set(['step','cast','overlap','substeps','route','label','dispatch','rayAll','rays','restart','replace','tile','distance','flow']);
+const CALLABLE = new Set([...VALUE_METHODS, ...WORLD_METHODS, ...MOVE_METHODS, ...PHYSICS_METHODS, ...MATH_METHODS]);
 const refusedName = (k) => REFUSED_NAMES.includes(k) || k.startsWith('toLocale');
 /** Operators that turn each operand into a number or a text. (`+` is handled beside them; `==` and `!=` are refused.) */
 const CONVERTING = new Set(['-', '*', '/', '%', '&', '|', '^', '<<', '>>', '>>>', '<', '>', '<=', '>=']);

package/lib/template-history.json

@@ -2943,6 +2943,48 @@
      }
     }
    }
+  },
+  "0.48.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "732894273a32dc3f",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "394cbbe934e80722",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "8596f2b25edda3e2",
+     "## Commands (all through the pinned CLI in node_modules)": "5222e08ca55e326e",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "bb715272fd1a615b",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1ccfd549d2369a60",
+     "## Selling things (the shop)": "9e020d69dd6a954e",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "27881d11d3ff3803",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "611b437f5b3303f0"
+      }
+     }
+    }
+   }
   }
  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",
@@ -92,7 +92,8 @@
     "./functions": {
       "types": "./functions/functions.ts",
       "default": "./functions/functions.ts"
-    }
+    },
+    "./rules/physics-engine": "./rules/physics-engine.ts"
   },
   "files": [
     "docs/",
@@ -165,5 +166,13 @@
   "scripts": {
     "test": "node --test --test-concurrency=2 --test-timeout=1800000 test/*.test.mjs",
     "prepack": "node lib/build-identity.mjs --check && node ../../scripts/authoring-guides.mjs --check"
+  },
+  "peerDependencies": {
+    "@homie-rocks/physics": "0.1.2"
+  },
+  "peerDependenciesMeta": {
+    "@homie-rocks/physics": {
+      "optional": true
+    }
   }
 }

package/rules/core.ts

@@ -1,3 +1,5 @@
+import { physicsWorld } from './physics.ts';
+import { substeps } from './substeps.ts';
 import { prepareMapReplacement, type MapRevision } from './map-state.ts';
 import { tileApi } from './tiles.ts';
 import { boundPosition, periodicDelta, relativePoint, blendPosition, wrapPoint } from './topology.mjs';
@@ -143,6 +145,7 @@ export interface SavedCore {
   v: number; tick: number; epoch: number; rng: number; nextId: number; seq: number;
   round: [number, number, number, number]; overAt: number; match: [number, number]; trips: number;
   shared: unknown[]; policy: CorePolicy; intent?: [number, number, number?];
+  physics?: number[];
   collision?: [number,number];
   maps?: {current:MapRevision|null;pending:MapRevision|null};
   history?: [number, [string, number, number, number, number][]][];
@@ -178,6 +181,7 @@ export interface Core {
   /** What happened since the last call: rounds, effects, a changed roster, changed shared state, a new epoch, a failure. */
   drain(): CoreOut[];
   save(): SavedCore;
+  dispose(): void;
   /** The `world` object rules are handed (a test walks it to prove nothing else is reachable). */
   readonly world: object;
   /**
@@ -195,6 +199,8 @@ export interface Core {
  * `Adjusted`; also `effect`, `think` and `decision`): the handler, what was done, the field's name and what was written.
  */
 export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number) => import('./rules.ts').Character | null | undefined; characterSaved?: (seat: number, character: import('./rules.ts').Character) => void; rewindTicks?: (seat: number)=>number; label?: (seat:number,driver:Driver)=>string; moved?: (kind: string, tick: number, input: Readonly<Record<string, unknown>>, before: import('./pack.ts').MoveBody, after: import('./pack.ts').MoveBody, geometry: import('./math.ts').MapShapes, id: string) => void; observe?: (kind: string, handler: string, error?: string) => void; noted?: (kind: string, handler: string, what: string, at: string, written: string) => void; seed?: number; epoch?: number; restore?: SavedCore | null; restoreEpoch?: number; stage?: string; decisions?: boolean } = {}): Core {
+  if (opts.restore && (c.map.physics !== undefined) !== (opts.restore.physics !== undefined)) throw new Error('physics: save and game differ');
+  const physics = physicsWorld(c.map.physics, opts.restore?.physics);
   let currentMap=c.map;
   let mapRevision:MapRevision|null=null,pendingMap:MapRevision|null=null;
   let pendingGeometry:typeof currentMap|null=null,mapCells=0,currentMapCells=0,pendingMapCells=0;
@@ -553,6 +559,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
     tick: () => tick, dt: () => dt, round: () => roundApi, shared: sharedView, level: () => policy.level, levelMax: () => policy.levelMax, guideLevel: () => policy.guideLevel ?? policy.level, guideSeats: () => policy.guideSeats ?? EMPTY_GUIDE_SEATS, kids: () => Boolean(policy.kids), levelSet: () => Boolean(policy.levelSet),
     // What the running handler may still spend (0.46.3): a handler that plans can stop short of its share instead of being stopped.
     unitsLeft: () => Math.max(0, Math.min(2147483647, Math.floor(G.left))),
+    ...(physics ? {physics: () => physics.api} : {}),
     stage: () => stage, tune: () => c.tune, math: () => math, map: () => mapApi,
   };
   for (const [name, get] of Object.entries(getters)) Object.defineProperty(world, name, { get, enumerable: true });
@@ -824,7 +831,8 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
   let moveShape = { shape: 'sphere', radius: 0, height: 0 };
   const moveCtx = brand({} as Record<string, unknown>);
   for (const [name, get] of Object.entries({ tick: () => tick, dt: () => dt, tune: () => c.publicTune, math: () => math, map: () => moveMap, world: () => moveWorld })) Object.defineProperty(moveCtx, name, { get, enumerable: true });
-  Object.assign(moveCtx, { ticks: (seconds: unknown): number => { charge(1); return ticks(seconds); } });
+  Object.assign(moveCtx, { substeps: substeps(c.settings.tickHz), ticks: (seconds: unknown): number => { charge(1); return ticks(seconds); } });
+  if (physics) Object.assign(moveCtx, {physics: physics.movement});
   Object.freeze(moveCtx);
   const joinCtx = brand({} as Record<string, unknown>);
   for (const [name, get] of Object.entries({ map: () => mapApi, shared: sharedView, tune: () => c.tune, math: () => math, round: () => roundApi })) Object.defineProperty(joinCtx, name, { get, enumerable: true });
@@ -1281,6 +1289,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
   }
   function save(): SavedCore {
     return {
+      ...(physics ? {physics: physics.save()} : {}),
       v: SAVE_REVISION, tick, epoch, rng, nextId, seq, round: [round.n, round.phase === 'live' ? 1 : 0, round.endsAt, round.startedAt], overAt, match: [playing, restartAt], trips,
       ...((hasColliders||mapRevision||pendingMap)?{collision:collisionState().slice(0,2) as [number,number]}:{}),
       ...((mapRevision||pendingMap)?{maps:{current:mapRevision,pending:pendingMap}}:{}),
@@ -1307,7 +1316,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
       for(const [name,value] of Object.entries(r.maps)){if(value===null)continue;check(Array.isArray(value)&&value.length===2&&uint(value[0])&&(name==='pending'?value[0]===r.tick+1:value[0]<=r.tick));prepareMapReplacement(value[1],c.map);}
     }
     if(r.collision!==undefined)check(Array.isArray(r.collision)&&r.collision.length===2&&uint(r.collision[0])&&uint(r.collision[1])&&r.collision[0]<=r.tick&&r.collision[1]===r.collision[0]+1);
-    check(Object.keys(r).every(k => ['v', 'tick', 'epoch', 'rng', 'nextId', 'seq', 'round', 'overAt', 'match', 'trips', 'shared', 'policy', 'intent', 'asks', 'guideViews', 'ents', 'spawns', 'seats', 'queue', 'areas', 'ops', 'history', 'collision', 'maps'].includes(k)));
+    check(Object.keys(r).every(k => ['v', 'tick', 'epoch', 'rng', 'nextId', 'seq', 'round', 'overAt', 'match', 'trips', 'shared', 'policy', 'intent', 'asks', 'guideViews', 'ents', 'spawns', 'seats', 'queue', 'areas', 'ops', 'history', 'collision', 'maps', 'physics'].includes(k)));
     const askNames = new Set();
     check(Array.isArray(r.asks));
     for (const a of r.asks) {
@@ -1429,6 +1438,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
     }
   }
   const r = opts.restore;
+  try {
   if (r) {
     if (r.v !== SAVE_REVISION) throw new Error('this save was written by another version of the runtime');
     validateSave(r);
@@ -1466,6 +1476,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
     ops = r.ops as typeof ops;
     if(hasColliders||mapRevision||pendingMap)collisionState();
   } else startMatch();
+  } catch (error) { physics?.dispose(); throw error; }
 
   function decisionResult(value: unknown): Record<string, unknown> {
     const v = plainData(value, { n: ANSWER_MAX });
@@ -1560,6 +1571,7 @@ export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number
     bodyOf: (seat) => { const s = seats.get(seat); const e = s?.id ? ents.get(s.id) : null; return e ? { id: e.id, kind: e.kind, r: e.r, away: e.away, driver: e.driver } : null; },
     drain: () => { const o = out; out = []; return o; },
     save,
+    dispose: () => physics?.dispose(),
     world,
     stats,
   };

package/rules/host.ts

@@ -932,6 +932,7 @@ export function createHost(o: HostOptions): Host {
   }
   function stop(): void {
     running = false; paused = false; ended = true;
+    core.dispose();
     disarm();
     agents?.stop();
     for (let i = recent.length - 1; i >= 0; i -= 1) if (recent[i].who === self) recent.splice(i, 1);

package/rules/math.ts

@@ -1,3 +1,5 @@
+import { physicsWorld } from './physics.ts';
+import { substeps } from './substeps.ts';
 import { wrapPoint } from './topology.mjs';
 import { tileApi } from './tiles.ts';
 import { nearbyMap } from './map-index.ts';
@@ -299,15 +301,22 @@ export function sweepMap(map: MapShapes, body: unknown, delta: unknown, radius:
  * map. One function, so that the browser (view.ts) and the person the build check plays hold the same one. The
  * server's own (core.ts `moveCtx`) is made beside the rest of its world, and charges as that does.
  */
+const physicsContexts = new WeakMap<object, () => void>();
+export function disposeMoveContext(context: object): void { physicsContexts.get(context)?.(); physicsContexts.delete(context); }
 export function moveContext(o: { tick: () => number; tickHz: number; tune: unknown; map: MapShapes; name: string; spots: Readonly<Record<string, readonly unknown[]>>; radius: () => number; shape?: () => BodyShape; dims: number; geometry?: () => MapShapes; self?: () => string | undefined }): unknown {
+  const physics = physicsWorld((o.map as import('./rules.ts').GameMap).physics);
   const none = Object.freeze([]);
   const currentMap = () => (o.geometry?.()?.staticMap ?? o.geometry?.() ?? o.map) as import('./rules.ts').GameMap;
   const queries = collisionQueries(() => o.geometry?.() ?? o.map, () => o.shape?.() ?? {shape: 'sphere', radius: o.radius(), height: 2 * o.radius()}, o.dims, o.self);
-  return brand(Object.freeze({
+  const context = brand(Object.freeze({
+    ...(physics ? {physics: physics.movement} : {}),
+    substeps: substeps(o.tickHz),
     get tick() { return o.tick(); }, dt: 1 / o.tickHz, tune: o.tune, math,
     // As the server's `ctx.ticks` reads it: a plain number, or nothing.
     ticks: (seconds: unknown): number => { const s = num(seconds); const n = Math.round(s * o.tickHz); return s > 0 && Number.isFinite(n) ? Math.max(1, n) : 0; },
     world: brand(Object.freeze(queries)),
     map: brand(Object.freeze({ ...tileApi(currentMap), name: o.name, spot: (name: string) => (own(currentMap().spots ?? o.spots, name) as readonly unknown[] | undefined)?.[0], spots: (name: string) => own(currentMap().spots ?? o.spots, name) ?? none, ...queries })),
   }));
+  if (physics) physicsContexts.set(context, physics.dispose);
+  return context;
 }

package/rules/pack.ts

@@ -1,3 +1,4 @@
+import { takeSubsteps, type StepPose } from './substeps.ts';
 /*
  * pack.ts — declared state in and out: holding a value to its declared type, and packing it for the wire and the save.
  * =============================================================================
@@ -262,7 +263,7 @@ export interface MoveBody { pos: Vec3; vel: Vec3; heading: Vec3; grounded: boole
  * left rounded to 32-bit floats and held to the declared shapes as the server does it, so both hold the same numbers.
  * `used` is the units it took. What it throws goes to `failed` (the budget's own stop too) and the body is still read.
  */
-export function stepMove(fn: (body: MoveBody, input: unknown, ctx: unknown) => void, body: MoveBody, input: Readonly<Record<string, unknown>>, ctx: unknown, quota: number, motion: FieldList, dims: number, failed: (error: unknown) => void): MoveBody & { used: number } {
+export function stepMove(fn: (body: MoveBody, input: unknown, ctx: unknown) => void, body: MoveBody, input: Readonly<Record<string, unknown>>, ctx: unknown, quota: number, motion: FieldList, dims: number, failed: (error: unknown) => void): MoveBody & { used: number; steps?: readonly StepPose[] } {
   G.queryEpoch++; G.left = quota;
   const bag = coerceFields(motion, body.motion, dims);
   const target: Record<string, unknown> = {};
@@ -296,7 +297,8 @@ export function stepMove(fn: (body: MoveBody, input: unknown, ctx: unknown) => v
   const used = quota - (G.left > 0 ? G.left : 0);
   G.left = Infinity;
   naming('body', 'pos'); const pos = vec3(body.pos, dims); naming('body', 'vel'); const vel = vec3(body.vel, dims); naming('body', 'heading'); const heading = dir(body.heading, dims); naming();
-  return { pos, vel, heading, grounded: body.grounded === true, motion: thawFields(motion, bag), used };
+  const steps = takeSubsteps(body);
+  return { pos, vel, heading, grounded: body.grounded === true, motion: thawFields(motion, bag), used, ...(steps ? {steps} : {}) };
 }
 
 /** How many values `pack` has packed since this was last set to 0: the core reads it to charge a tick for the state it sends. */

package/rules/physics-engine.ts

@@ -0,0 +1,73 @@
+/** Loaded only by games declaring a baked physics level. */
+import { createWorld } from '@homie-rocks/physics/World.js';
+import { initPhysics } from '@homie-rocks/physics/Worker.js';
+import { brand, charge } from './guard.ts';
+import { registerPhysics, type PhysicsMovement, type RulesPhysics } from './physics.ts';
+
+// CPU calibration is recorded in docs/physics-048-calibration.md. Charges precede work.
+export const PHYSICS_UNITS = Object.freeze({ cast: 768, ray: 640, overlap: 640, step: 2400 });
+export async function initializePhysics(source: WebAssembly.Module | BufferSource): Promise<void> {
+  await initPhysics(source);
+  registerPhysics((mesh, saved) => {
+    const world = createWorld({ up: 'z', fixedDt: 1 / 300, maxSubsteps: 128, bounds: null });
+    try {
+      if (saved) world.restore(Uint8Array.from(saved));
+      else world.createBody({ type: 'static', colliders: [{ shape: { kind: 'mesh', vertices: Float32Array.from(mesh.vertices), indices: Uint32Array.from(mesh.indices) } }] });
+      const count = Math.max(1, Math.ceil(mesh.indices.length / (1754 * 3)));
+      const convex = (shape: {kind:string}) => { if (!['box','sphere','capsule'].includes(shape.kind)) throw new Error('rules physics queries use a box, sphere or capsule'); };
+      const movement: PhysicsMovement = {
+        cast(...args) { charge(PHYSICS_UNITS.cast * count); convex(args[0]); return world.castShape(...args); },
+        ray(...args) { charge(PHYSICS_UNITS.ray * count); return world.raycast(...args); },
+        overlap(...args) { charge(PHYSICS_UNITS.overlap * count); convex(args[0]); return world.overlaps(...args); },
+        sweep(body, delta, radius, height) {
+          charge(64);
+          let left = { ...delta }, pos = { ...body.pos }, vel = { ...body.vel };
+          let grounded = false;
+          for (let n = 0; n < 4; n++) {
+            const length = Math.hypot(left.x, left.y, left.z);
+            if (length < 1e-9) break;
+            charge(PHYSICS_UNITS.cast * count);
+            const hit = world.castCapsule(pos, left, radius, height);
+            const fraction = hit ? Math.max(0, hit.fraction) : 1;
+            pos = { x: pos.x + left.x * fraction, y: pos.y + left.y * fraction, z: pos.z + left.z * fraction };
+            if (!hit) break;
+            if (hit.normal.z > .65 && delta.z <= 0) grounded = true;
+            const normal = hit.normal;
+            const dot = left.x * normal.x + left.y * normal.y + left.z * normal.z;
+            const speed = vel.x * normal.x + vel.y * normal.y + vel.z * normal.z;
+            if (normal.z > .65 && delta.z <= 0) {
+              // Lift the requested horizontal travel along a walkable slope.
+              // Projecting gravity onto its normal would make an idle capsule drift.
+              left = { x: left.x * (1-fraction), y: left.y * (1-fraction), z: 0 };
+              left.z = -(left.x * normal.x + left.y * normal.y) / normal.z;
+              vel = { x: vel.x, y: vel.y, z: Math.max(0, vel.z) };
+            } else {
+              left = { x: (left.x-normal.x*Math.min(0,dot))*(1-fraction), y: (left.y-normal.y*Math.min(0,dot))*(1-fraction), z: (left.z-normal.z*Math.min(0,dot))*(1-fraction) };
+              vel = { x:vel.x-normal.x*Math.min(0,speed), y:vel.y-normal.y*Math.min(0,speed), z:vel.z-normal.z*Math.min(0,speed) };
+            }
+          }
+          body.pos = pos; body.vel = vel; body.grounded = grounded;
+        },
+      };
+      const api: RulesPhysics = {
+        ...movement,
+        step(dt) {
+          charge(8);
+          if (!Number.isFinite(dt) || dt < 0) throw new Error('physics: dt must be finite and nonnegative');
+          charge(PHYSICS_UNITS.step * count * Math.max(1, Math.ceil(dt * 300)));
+          while (dt > .1) { world.step(.1); dt -= .1; }
+          world.step(dt);
+        },
+      };
+      let disposed = false, finalSave: number[] | undefined;
+      return { api: brand(Object.freeze(api)), movement: brand(Object.freeze(movement)),
+        save: () => finalSave ? [...finalSave] : Array.from(world.snapshot()),
+        dispose: () => {
+          if (disposed) return;
+          try { finalSave = Array.from(world.snapshot()); } catch { /* A failed engine has no final checkpoint. */ }
+          world.dispose(); disposed = true;
+        },
+      };
+    } catch (error) { world.dispose(); throw error; }
+  });
+}

package/rules/physics.ts

@@ -0,0 +1,26 @@
+/** Opt-in boundary. Importing the rules kernel never imports or initializes WASM. */
+import type { Vec3 } from './rules.ts';
+export interface PhysicsMesh { vertices: readonly number[]; indices: readonly number[] }
+// Structural query types keep the ordinary rules types independent of the optional package.
+export type PhysicsShape = {kind: 'box'; halfExtents: Vec3} | {kind: 'sphere'; radius: number} | {kind: 'capsule'; radius: number; halfHeight: number};
+export interface PhysicsRotation {x: number; y: number; z: number; w: number}
+export interface PhysicsFilter {layers?: {membership: number; filter: number}; excludeBody?: number; excludeCollider?: number; sensors?: boolean}
+export interface PhysicsHit {collider: number; body: number; point: Vec3; normal: Vec3}
+export interface PhysicsMovement {
+  sweep(body: {pos: Vec3; vel: Vec3; grounded: boolean}, delta: Vec3, radius: number, height: number): void;
+  ray(origin: Vec3, direction: Vec3, distance: number, filter?: PhysicsFilter): (PhysicsHit & {distance: number}) | null;
+  overlap(shape: PhysicsShape, position: Vec3, orientation?: PhysicsRotation, filter?: PhysicsFilter): number[];
+  cast(shape: PhysicsShape, position: Vec3, delta: Vec3, orientation?: PhysicsRotation, filter?: PhysicsFilter): (PhysicsHit & {fraction: number}) | null;
+}
+export interface RulesPhysics extends PhysicsMovement {
+  step(seconds: number): void;
+}
+export interface PhysicsBridge { api: RulesPhysics; movement: PhysicsMovement; save(): number[]; dispose(): void }
+let factory: ((mesh: PhysicsMesh, saved?: number[]) => PhysicsBridge) | undefined;
+export function registerPhysics(value: NonNullable<typeof factory>): void { factory = value; }
+export function physicsWorld(mesh?: PhysicsMesh, saved?: number[]): PhysicsBridge | undefined {
+  if (!mesh) { if (saved !== undefined) throw new Error('physics save requires a physics level'); return; }
+  if (saved !== undefined && (!Array.isArray(saved) || saved.some(n => !Number.isInteger(n) || n < 0 || n > 255))) throw new Error('physics: invalid saved bytes');
+  if (!factory) throw new Error('physics: initialize the game before starting its room');
+  return factory(mesh, saved);
+}

package/rules/rules.ts

@@ -291,7 +291,7 @@ export interface MapBox { readonly min: Vec3; readonly max: Vec3 }
 export interface MapCircle { readonly at: Vec3; readonly r: number }
 export interface MapHeightTile { readonly base?: number; readonly diagonal?: '00-11' | '10-01'; readonly at: Vec3; readonly size: Readonly<{ x: number; y: number }>; readonly heights: readonly [number, number, number, number] }
 export type MapWrap = Readonly<Partial<Record<'x' | 'y' | 'z', readonly [number, number]>>>;
-export interface GameMap { readonly tiles?: Tiles; readonly wrap?: MapWrap; readonly name: string; readonly heightTiles: readonly MapHeightTile[]; readonly bounds: MapBox; readonly boxes: readonly MapBox[]; readonly circles: readonly MapCircle[]; readonly spheres: readonly MapCircle[]; readonly capsules: readonly (MapCircle & { height: number })[]; readonly spots: Readonly<Record<string, readonly Vec3[]>> }
+export interface GameMap { readonly physics?: import('./physics.ts').PhysicsMesh; readonly tiles?: Tiles; readonly wrap?: MapWrap; readonly name: string; readonly heightTiles: readonly MapHeightTile[]; readonly bounds: MapBox; readonly boxes: readonly MapBox[]; readonly circles: readonly MapCircle[]; readonly spheres: readonly MapCircle[]; readonly capsules: readonly (MapCircle & { height: number })[]; readonly spots: Readonly<Record<string, readonly Vec3[]>> }
 
 const vecOf = (a: unknown, what: string): Vec3 => {
   const p = Array.isArray(a) ? { x: a[0], y: a[1], z: a[2] ?? 0 } : a as { x?: unknown; y?: unknown; z?: unknown } | null;
@@ -340,7 +340,16 @@ export function compileMap(raw: unknown, name = 'main'): GameMap {
   }
   const tiled=compileTiles(m.tiles,wrap);
   if(tiled) for(const k of ['x','y'] as const) if(wrap?.[k] && (tiled.tiles.at[k]!==bounds.min[k] || tiled.tiles.at[k]+tiled.tiles.size*(k==='x'?tiled.tiles.width:tiled.tiles.height)!==bounds.max[k])) throw new Error(`${where}: tiles must span each wrapped axis`);
+  let physics: import('./physics.ts').PhysicsMesh | undefined;
+  if (m.physics !== undefined) {
+    const {vertices, indices} = m.physics ?? {};
+    if (!Array.isArray(vertices) || !Array.isArray(indices) || !vertices.length || vertices.length % 3 || !indices.length || indices.length % 3 ||
+      vertices.some((n: unknown) => typeof n !== 'number' || !Number.isFinite(n) || !Number.isFinite(Math.fround(n))) ||
+      indices.some((n: unknown) => !Number.isSafeInteger(n) || (n as number) < 0 || (n as number) >= vertices.length / 3)) throw new Error(`${where}: physics needs a build-time baked triangle mesh`);
+    physics = Object.freeze({vertices:Object.freeze([...vertices]),indices:Object.freeze([...indices])});
+  }
   const result = Object.freeze({
+    ...(m.physics ? {physics: physics!} : {}),
     ...(tiled?{tiles:tiled.tiles}:{}),
     name, ...(wrap ? {wrap} : {}),
     heightTiles: Object.freeze((m.heightTiles ?? []).map((t: any, i: number) => {

package/rules/substeps.ts

@@ -0,0 +1,39 @@
+import { brand, charge, own } from './guard.ts';
+
+export interface Substep { readonly dt: number; readonly index: number; readonly count: number; readonly first: boolean; readonly fraction: number }
+export interface StepPose { pos: {x:number;y:number;z:number}; vel: {x:number;y:number;z:number}; heading: {x:number;y:number;z:number}; grounded: boolean }
+const traces = new WeakMap<object, readonly StepPose[]>();
+const running = new WeakSet<object>();
+const scalar = (value: unknown): number => typeof value === 'number' && Number.isFinite(value) ? value : 0;
+const vector = (value: unknown) => ({x:scalar(own(value,'x')),y:scalar(own(value,'y')),z:scalar(own(value,'z'))});
+const pose = (body: object): StepPose => ({pos:vector(own(body,'pos')),vel:vector(own(body,'vel')),heading:vector(own(body,'heading')),grounded:own(body,'grounded') === true});
+
+/** Same integration and trace accounting on authority and prediction; no independent quota. */
+export function substeps(tickHz: number) {
+  return (body: object, hz: number, step: (context: Substep) => void): void => {
+    charge(8);
+    const count = typeof hz === 'number' ? hz / tickHz : NaN;
+    if (typeof hz !== 'number' || !Number.isSafeInteger(count) || count < 1) throw new RangeError('substeps: hz must be a positive integer multiple of room.tickHz');
+    if (!body || typeof body !== 'object' || typeof step !== 'function') throw new TypeError('substeps: expected body, hz, callback');
+    if (running.has(body) || traces.has(body)) throw new Error('substeps: integrate a body only once per move');
+    // Pay before allocation and callbacks. Each pose copies ten scalars and three vectors.
+    charge(64 * (count + 1));
+    const samples: StepPose[] = [pose(body)];
+    running.add(body);
+    traces.delete(body);
+    try {
+      for (let index = 0; index < count; index++) {
+        step(brand(Object.freeze({dt:1/hz,index,count,first:index === 0,fraction:(index+1)/count})));
+        samples.push(pose(body));
+      }
+      traces.set(body, samples);
+    } finally { running.delete(body); }
+  };
+}
+
+/** Runtime-only drawing data, never an extra part of a room save or wire frame. */
+export function takeSubsteps(body: object): readonly StepPose[] | undefined {
+  const samples = traces.get(body);
+  traces.delete(body);
+  return samples;
+}

package/rules/types.ts

@@ -28,6 +28,7 @@ export interface MapView { tile(x:number,y:number):number; distance(flow:string,
 export interface Clock { readonly tick: number; readonly dt: number; ticks(seconds: number): number; readonly math: typeof math }
 export interface Round { readonly n: number; readonly phase: 'live' | 'over'; readonly endsAt: number }
 export type World<E, F, S, V, C, A, T, Room extends boolean = false> = Clock & {
+  readonly physics: import('./physics.ts').RulesPhysics;
   readonly tune: ReadonlyState<T>; readonly map: MapView & (Room extends true ? {replace(data:Record<string,unknown>):void} : {}); readonly stage: string; readonly level: number; readonly levelMax: number; readonly guideLevel: number; readonly guideSeats: readonly number[]; readonly kids: boolean; readonly levelSet: boolean;
   readonly shared: Room extends true ? S : ReadonlyState<S>;
   readonly round: Round & (Room extends true ? { end(): void; restart(): void } : {});
@@ -76,4 +77,4 @@ export type Entity<W, S, I, E, C, V, Answer = BuiltIns['answer'], G = Goal, A =
 };
 export interface MoveBody<M> { get pos(): Vec3; set pos(value: Point); get vel(): Vec3; set vel(value: Point); get heading(): Vec3; set heading(value: Point); grounded: boolean; readonly motion: M }
 export interface MoveCollision<M> extends RayQueries { sweep(body: MoveBody<M>, delta: Point, options?: {ground?: boolean}): Hit | undefined; support(body: MoveBody<M>, distance?: number): (Hit & {dist: number}) | undefined; overlaps(body: MoveBody<M>): boolean }
-export type MoveContext<T, M> = Clock & { readonly tune: ReadonlyState<T>; readonly map: MapView & MoveCollision<M>; readonly world: MoveCollision<M> };
+export type MoveContext<T, M> = Clock & { readonly physics: import('./physics.ts').PhysicsMovement; substeps(body: MoveBody<M>, hz: number, step: (context: import('./substeps.ts').Substep) => void): void; readonly tune: ReadonlyState<T>; readonly map: MapView & MoveCollision<M>; readonly world: MoveCollision<M> };

package/rules/view.ts

@@ -1,3 +1,4 @@
+import { disposeMoveContext } from './math.ts';
 import { boundPosition, periodicDelta, blendPosition, relativePoint, wrapPoint } from './topology.mjs';
 import { rayQuery, raySnapshot, type QueryTarget } from './query.ts';
 import { solidAt } from './collision.ts';
@@ -114,6 +115,8 @@ export interface OpenRoomOptions {
 /** What a predictor (`openRoom({ predict })`) is handed beside the body and the tick's input. */
 export interface PredictContext extends RayQueries {
   readonly tick: number; readonly dt: number;
+  /** Read the authoritative snapshot this prediction started from, without advancing time. */
+  each(kind: string, fn: (e: Entity) => void): void;
   /** The same deterministic `math` a `move` is handed (0.46.5): a helper shared with the rules can be called with `ctx`. */
   readonly math: typeof math;
   /**
@@ -377,7 +380,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     mine = { id: u.id, kind: u.kind, r: u.r, pos: u.pos, vel: u.vel, heading: u.heading, grounded: u.grounded, motion: motionOf(u.kind, u.motion), fields: predictors[u.kind] ? thawFields(kindOf.get(u.kind)?.fields ?? [], u.fields) : u.fields };
   }
   /** The game's guarded `move` for one tick, counted as the server counts it, with the result rounded as the server rounds it. */
-  function runMove(kindName: string, body: { pos: Vec3; vel: Vec3; heading: Vec3; grounded: boolean; motion: Record<string, unknown> }, input: Readonly<Record<string, unknown>>, t: number): typeof body {
+  function runMove(kindName: string, body: { pos: Vec3; vel: Vec3; heading: Vec3; grounded: boolean; motion: Record<string, unknown> }, input: Readonly<Record<string, unknown>>, t: number): typeof body & {steps?: readonly import('./substeps.ts').StepPose[]} {
     const fn = moves[kindName];
     if (!fn || (kindOf.get(kindName)?.control && !body.motion[kindOf.get(kindName)!.control!])) return body;
     moveTick = t;
@@ -393,6 +396,11 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   /* ---------------------------------------------------------------- the own actions, predicted (0.46.3) */
 
   const predictors = opts.predict ?? {};
+  let predicting = false;
+  let predictionFrame: Frame | null = null;
+  function predictionEach(kind: string, fn: (e: Entity) => void): void {
+    for (const u of (predictionFrame ?? latest)?.ents.values() ?? []) if (u.kind === kind) fn(entityOf(u, u.id === mine?.id));
+  }
   interface Ghost { id: string; kind: string; tick: number; pos: Vec3; fields: Record<string, unknown>; until: number; match?: (e: Entity) => boolean; /** The server's entity that confirmed it: the ghost is drawn until that one is. */ real?: string }
   const ghosts = new Map<string, Ghost>();
   let ghostSeq = 0;
@@ -422,7 +430,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     // Branded as a world is (0.46.5): a guarded helper of the rules may call its queries, so the server's own aiming
     // code can be run on it instead of being restated in the view.
     const ctx: PredictContext = brand({
-      tick: t, dt: 1 / tickHz, preview, math,
+      tick: t, dt: 1 / tickHz, preview, math, each: predictionEach,
       judgedTick: (aimTick) => Math.max(t - rewindAllowance(), Math.min(t, Number(aimTick) || 0)),
       get viewTick() { return viewTickNow(); },
       ray: (from, direction, max, options) => viewRay(from, direction, max, options)[0],
@@ -451,7 +459,10 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     });
     const me = Object.assign(fields, { id, kind: kindName }) as Record<string, unknown>;
     for (const [key, value] of Object.entries({ pos: body.pos, vel: body.vel, heading: body.heading, grounded: body.grounded, motion: body.motion })) Object.defineProperty(me, key, { value, enumerable: false, configurable: true, writable: true });
+    const wasPredicting = predicting, previousFrame = predictionFrame;
+    predicting = true; predictionFrame = latest;
     try { fn(me, input, ctx); } catch (err) { console.warn('[room] predict', err); }
+    finally { predicting = wasPredicting; predictionFrame = previousFrame; }
     // What it wrote is held to the declared types, as the server holds its own writes.
     for (const [name, fd] of kind.fields) fields[name] = coerce(fd, fields[name], dims);
     for (const key of Object.keys(fields)) if (!kind.fields.some(([name]) => name === key)) delete fields[key];
@@ -554,7 +565,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   let pumping = false;
   function pump(): void {
     // A predictor's own queries read the room, and reading the room pumps: a step is never begun inside a step.
-    if (closed || pumping) return;
+    if (closed || pumping || predicting) return;
     pumping = true;
     try { pumpOnce(); } finally { pumping = false; }
   }
@@ -588,6 +599,11 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   }
 
   function onSnapshot(s: Snapshot<unknown>): void {
+    const wasPumping = pumping;
+    pumping = true;
+    try { applySnapshot(s); } finally { pumping = wasPumping; }
+  }
+  function applySnapshot(s: Snapshot<unknown>): void {
     const f = frameOf(s);
     if (!f) return;
     const before = latest;
@@ -810,6 +826,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
    * drawn frame, not on the next tick.
    */
   function meNow(): Entity | null {
+    if (predicting) { const u = mine && predictionFrame?.ents.get(mine.id); return u ? entityOf(u, true) : null; }
     if (solo) return solo.me;
     if (!mine || !latest) return null;
     const server = latest.ents.get(mine.id);
@@ -842,6 +859,14 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
       velocity = vec3({ x: lerp(mine.vel.x, next.vel.x, a), y: lerp(mine.vel.y, next.vel.y, a), z: lerp(mine.vel.z, next.vel.z, a) }, dims);
       // A takeoff is airborne as soon as it rises; a landing waits for its contact.
       grounded = landed || mine.grounded && (a === 0 || next.grounded);
+      if (next.steps?.length) {
+        const n = next.steps.length - 1, at = a * n, index = Math.min(n - 1, Math.floor(at)), f = at - index;
+        const before = next.steps[index], after = next.steps[index + 1];
+        pos = vec3(blendPosition(before.pos, after.pos, f, map.wrap), dims);
+        heading = blendHeading(before.heading, after.heading, f, dims);
+        velocity = vec3({x:lerp(before.vel.x,after.vel.x,f),y:lerp(before.vel.y,after.vel.y,f),z:lerp(before.vel.z,after.vel.z,f)},dims);
+        grounded = f === 1 ? after.grounded : before.grounded && after.grounded;
+      }
       preview = next;
       if (predictors[kind.name]) {
         // The own actions between ticks: the predictor on a copy of the fields, for the tick about to be stepped.
@@ -1055,6 +1080,6 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     askButtons(id, offer = {}) { if (solo) return []; const e = latest?.ents.get(id); return e && e.seat !== undefined ? agents?.askButtons(e.seat, offer) ?? [] : []; },
     tune, get map(){return solo ? solo.map : mapAt(latest?.k??0);}, net: net as Netplay,
     pump,
-    close() { stopSolo(); closed = true; if (timer) clearInterval(timer); if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', onShow); agents?.stop(); net.close(); setStatus('closed'); },
+    close() { stopSolo(); disposeMoveContext(moveCtx as object); closed = true; if (timer) clearInterval(timer); if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', onShow); agents?.stop(); net.close(); setStatus('closed'); },
   };
 }

package/worker/build-id.mjs

@@ -1,2 +1,2 @@
 // Generated by lib/build-identity.mjs; identifies the bundled runtime sources.
-export const STUDIO_BUILD = Object.freeze({"version":"0.47.0","sha256":"4e1a1a503557e68e60b55a05dc289e4e688831c429d18c8f13ad2a24c3e05315"});
+export const STUDIO_BUILD = Object.freeze({"version":"0.48.0","sha256":"3c0bdb436a2a600fc529827f340b470cdce1cfa40f7d692ff0b9963b5b07c622"});

package/worker/hosted.mjs

@@ -19,6 +19,7 @@ import { compileMap, compileRules } from '../rules/rules.ts';
 /** game id → { rules, tune, map, settings, seats, build } as the build wrote it, and what compiling each gave. */
 const games = new Map();
 const compiled = new Map();
+const readiness = new WeakMap();
 
 /** The table of this studio's server-hosted games (the build's site/src/rules/index.mjs). Called once, at load. */
 export function hostRules(table) {
@@ -33,6 +34,21 @@ export function hostRules(table) {
 export const hostedGame = (id) => games.has(id);
 export const hostedBuild = (id) => games.get(id);
 
+/** Optional engines load at room start. Ordinary games keep their synchronous startup path. */
+export function prepareHost(id) {
+  const entry = games.get(id);
+  if (!entry?.initialize) return;
+  const previous = readiness.get(entry);
+  if (previous === true) return;
+  if (previous) return previous;
+  const pending = Promise.resolve().then(() => entry.initialize()).then(
+    () => { readiness.set(entry, true); },
+    error => { readiness.delete(entry); throw error; },
+  );
+  readiness.set(entry, pending);
+  return pending;
+}
+
 /** A game's rules, compiled once per isolate. Throws, naming the declaration, when they do not fit the contract. */
 export function compiledFor(id) {
   if (compiled.has(id)) return compiled.get(id);

package/worker/index.mjs

@@ -89,7 +89,7 @@ import { appRole, openPath } from './app-format.mjs';
  */
 import { playerEnabled, EMBED_GAME_JS } from './embed.mjs';
 import { NetRoom, WATCH_POLICIES, departure, errorLine, versionOf } from './room.mjs';
-import { hostedGame, hostedBuild, compiledFor, startHost } from './hosted.mjs';
+import { hostedGame, hostedBuild, compiledFor, prepareHost, startHost } from './hosted.mjs';
 import { roomStore, restoreDelay, LOOSE_SAVE } from './room-store.mjs';
 import { appCors, isAppOrigin } from './standalone.mjs';
 import { ROOM_ID, badRoomPage, embedAncestors, embedPreview, frameAncestors, noWatchPage, playPage, shellKey, shellStandIn, watchPage } from './pages.mjs';
@@ -1592,13 +1592,13 @@ export class Table {
     this.say({ ev: 'persist-failed', build: hostedBuild(this.game)?.build, error: this.storageHealth.message });
   }
 
-  readRoom(validateHost = false) {
+  readRoom(validateHost = false, alreadyRead) {
     if (this.skipSave) { this.skipSave = false; return null; }
     try {
       const boot = this.durable?.boots();
       this.persistentStored = boot?.persistent === true;
       if (boot?.retired === true) { this.clearRoom(); return null; }
-      const saved = this.durable?.read();
+      const saved = alreadyRead ?? this.durable?.read();
       if (!saved) return null;
       if (saved.v !== 1 || typeof saved.game !== 'string' || typeof saved.room !== 'string' ||
           this.game && saved.game !== this.game || this.code && saved.room !== this.code ||
@@ -1759,7 +1759,18 @@ export class Table {
     if (!room || !this.hostRt) {
       if (this.ctx.storage.sql?.exec("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'save'").toArray().length) {
         this.durable ??= this.openStore(false);
-        const saved = this.cleanupPending ? null : this.readRoom(true);
+        let saved = this.cleanupPending ? null : this.readRoom();
+        if (saved) {
+          const generation = this.cleanupGeneration;
+          const preparing = prepareHost(saved.game);
+          if (preparing) {
+            await preparing;
+            // A join or office action can arrive while the optional engine loads.
+            // Re-read that lifecycle instead of writing the pre-await checkpoint.
+            if (this.room !== room || this.hostRt || this.cleanupGeneration !== generation) return this.runRoomAlarm();
+          }
+          saved = this.readRoom(true, saved);
+        }
         if (saved) {
           this.game = saved.game; this.code = saved.room;
           if (this.isPersistent()) return;
@@ -2167,6 +2178,8 @@ export class Table {
     if (url.pathname === '/__recall') {
       const { account } = await request.json();
       return this.withCharacter(account, async () => {
+        const preparing = prepareHost(game);
+        if (preparing) await preparing;
         this.ensureHost(room, true);
         if (!this.hostRt || this.persistentFailed || room.hostFailed) return json({ ok: false }, 503);
         await this.flushCharacters();
@@ -2232,6 +2245,8 @@ export class Table {
     const said = url.searchParams.has('cur');
     if (said) { room.setStall(url.searchParams.get('stall')); room.setCurrent(url.searchParams.get('cur') || null); }
     // Restore before applying the Worker's current policy: a save must not replace a newer policy.
+    const preparing = prepareHost(game);
+    if (preparing) await preparing;
     this.ensureHost(room, url.searchParams.get('host') === 'server');
     // The room's policy (section 17), composed by the Worker for every socket: a newer one than the room's applies.
     const pol = decodeFacts(url.searchParams.get('pol'));

package/worker/version.mjs

@@ -1,2 +1,2 @@
 /** The @homie-rocks/studio version this Worker code is (package.json's; a test keeps them equal). Cache-busts /_homie/site.js. */
-export const STUDIO_VERSION_TAG = '0.47.0';
+export const STUDIO_VERSION_TAG = '0.48.0';