@homie-rocks/studio 0.46.6 → 0.48.0

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/tiles.ts

@@ -0,0 +1,58 @@
+import { bakeGridFlow } from './nav/Flow.ts';
+import { charge } from './guard.ts';
+import type { GameMap, MapBox, MapWrap, Vec3 } from './rules.ts';
+export interface Tiles {
+    readonly width: number;
+    readonly height: number;
+    readonly size: number;
+    readonly at: Vec3;
+    readonly solidHeight: number;
+    readonly data: readonly number[];
+    readonly flows: Readonly<Record<string, readonly number[]>>;
+}
+const fields = new WeakMap<object, Map<string, ReturnType<typeof bakeGridFlow>>>();
+export function compileTiles(raw: any, wrap?: MapWrap): {
+    tiles: Tiles;
+    boxes: MapBox[];
+} | undefined {
+    if (raw === undefined)
+        return;
+    const { width, height, size = 1, solidHeight = 1 } = raw, n = width * height, at = raw.at ?? [0, 0, 0];
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1 || !Number.isSafeInteger(n) || !Number.isFinite(size) || size <= 0 || !Number.isFinite(solidHeight) || solidHeight <= 0 || !Array.isArray(at) || at.length < 2 || at.length > 3 || at.some((x: unknown) => typeof x !== 'number' || !Number.isFinite(x)) || !Array.isArray(raw.data) || raw.data.length !== n)
+        throw new Error('map tiles: positive width, height, size, solidHeight, at and one data value per cell');
+    if (!Number.isFinite(at[0] + width * size) || !Number.isFinite(at[1] + height * size) || !Number.isFinite((at[2] ?? 0) + solidHeight))
+        throw new Error('map tiles: finite extent required');
+    const data = raw.data.map((v: unknown) => { if (typeof v !== 'number' || !Number.isInteger(v) || v < 0 || v > 65535)
+        throw new Error('map tile values are integers 0..65535'); return v; });
+    const origin = { x: at[0], y: at[1], z: at[2] ?? 0 }, boxes: MapBox[] = [];
+    for (let y = 0; y < height; y++)
+        for (let x = 0; x < width; x++)
+            if (data[y * width + x]) {
+                const start = x;
+                while (x + 1 < width && data[y * width + x + 1])
+                    x++;
+                boxes.push(Object.freeze({ min: Object.freeze({ x: origin.x + start * size, y: origin.y + y * size, z: origin.z }), max: Object.freeze({ x: origin.x + (x + 1) * size, y: origin.y + (y + 1) * size, z: origin.z + solidHeight }) }));
+            }
+    const flows: Record<string, readonly number[]> = {}, baked = new Map<string, ReturnType<typeof bakeGridFlow>>();
+    for (const [name, goals] of Object.entries(raw.flows ?? {})) {
+        if (!/^[a-z][A-Za-z0-9_]{0,31}$/.test(name) || !Array.isArray(goals))
+            throw new Error('tile flows name lists of goal cell indices');
+        flows[name] = Object.freeze([...goals]);
+        baked.set(name, bakeGridFlow({ width, height, data, wrapX: Boolean(wrap?.x), wrapY: Boolean(wrap?.y) }, goals, charge));
+    }
+    const tiles = Object.freeze({ width, height, size, solidHeight, at: Object.freeze(origin), data: Object.freeze(data), flows: Object.freeze(flows) });
+    fields.set(tiles, baked);
+    return { tiles, boxes };
+}
+export function tileApi(get: () => GameMap) {
+    const cell = (x: unknown, y: unknown) => { const t = get().tiles; if (!t || typeof x !== 'number' || typeof y !== 'number' || !Number.isInteger(x) || !Number.isInteger(y))
+        return -1; const w = get().wrap; if (w?.x)
+        x = ((x % t.width) + t.width) % t.width; if (w?.y)
+        y = ((y % t.height) + t.height) % t.height; return x < 0 || y < 0 || x >= t.width || y >= t.height ? -1 : y * t.width + x; };
+    return {
+        tile: (x: unknown, y: unknown) => { charge(4); const id = cell(x, y); return id < 0 ? 1 : get().tiles!.data[id]; },
+        distance: (name: unknown, x: unknown, y: unknown) => { charge(4); const id = cell(x, y), f = typeof name === 'string' && get().tiles ? fields.get(get().tiles!)?.get(name) : null; return id < 0 || !f ? -1 : f.distance[id]; },
+        flow: (name: unknown, x: unknown, y: unknown) => { charge(8); const id = cell(x, y), t = get().tiles, f = typeof name === 'string' && t ? fields.get(t)?.get(name) : null; if (!t || id < 0 || !f || f.next[id] < 0)
+            return undefined; const next = f.next[id], dx = next % t.width - id % t.width, dy = Math.floor(next / t.width) - Math.floor(id / t.width); return Object.freeze({ x: Math.abs(dx) > 1 ? -Math.sign(dx) : dx, y: Math.abs(dy) > 1 ? -Math.sign(dy) : dy, z: 0 }); },
+    };
+}

package/rules/topology.mjs

@@ -0,0 +1,22 @@
+/** Periodic coordinates. Half-period ties consistently choose the negative way. */
+export const wrapValue = (value, range) => range ? range[0] + ((value - range[0]) % (range[1] - range[0]) + range[1] - range[0]) % (range[1] - range[0]) : value;
+export const periodicDelta = (a, b, range) => range ? wrapValue(b - a, [-(range[1] - range[0]) / 2, (range[1] - range[0]) / 2]) : b - a;
+export const wrapPoint = (p, wrap) => wrap ? {x: wrapValue(p.x, wrap.x), y: wrapValue(p.y, wrap.y), z: wrapValue(p.z ?? 0, wrap.z)} : p;
+export const relativePoint = (p, at, wrap) => wrap ? {x:at.x+periodicDelta(at.x,p.x,wrap.x),y:at.y+periodicDelta(at.y,p.y,wrap.y),z:(at.z??0)+periodicDelta(at.z??0,p.z??0,wrap.z)} : p;
+export const blendPosition = (a,b,t,wrap) => ({x:wrapValue(a.x+periodicDelta(a.x,b.x,wrap?.x)*t,wrap?.x),y:wrapValue(a.y+periodicDelta(a.y,b.y,wrap?.y)*t,wrap?.y),z:wrapValue(a.z+periodicDelta(a.z,b.z,wrap?.z)*t,wrap?.z)});
+export function boundPosition(p, map, radius, height, dims) {
+  const b=map.bounds,w=map.wrap;
+  return {x:w?.x?wrapValue(p.x,w.x):Math.max(b.min.x+radius,Math.min(b.max.x-radius,p.x)),y:w?.y?wrapValue(p.y,w.y):Math.max(b.min.y+radius,Math.min(b.max.y-radius,p.y)),z:dims===3?(w?.z?wrapValue(p.z,w.z):Math.max(b.min.z,Math.min(b.max.z-height,p.z))):0};
+}
+/** Stream periodic images intersecting a query's swept bounds; callers meter each image. */
+export function* imageOffsets(bounds, wrap, p, d, radius, height, dims=3) {
+  const ranges=['x','y','z'].map(k=>{
+    if(!wrap?.[k] || k==='z'&&dims===2)return [0,0,0];
+    const period=wrap[k][1]-wrap[k][0];
+    const lo=Math.min(p[k],p[k]+d[k])-(k==='z'?0:radius),hi=Math.max(p[k],p[k]+d[k])+(k==='z'?height:radius);
+    const first=Math.ceil((lo-bounds.max[k])/period),last=Math.floor((hi-bounds.min[k])/period);
+    if(!Number.isSafeInteger(first)||!Number.isSafeInteger(last))throw new RangeError('periodic query exceeds exact integer coordinates');
+    return [first,last,period];
+  });
+  for(let x=ranges[0][0];x<=ranges[0][1];x++)for(let y=ranges[1][0];y<=ranges[1][1];y++)for(let z=ranges[2][0];z<=ranges[2][1];z++)yield {x:x*ranges[0][2],y:y*ranges[1][2],z:z*ranges[2][2]};
+}

package/rules/types.ts

@@ -24,11 +24,12 @@ export interface RaySnapshot {sweep(body:{pos:Point;grounded?:boolean},delta:Poi
 export interface RayQueries { rays(options?:RayOptions):RaySnapshot; ray(from: Point, direction: Point, max: number, options?: RayOptions): RayHit | undefined; rayAll(from: Point, direction: Point, max: number, options?: RayOptions): readonly RayHit[] }
 export interface EffectAudience { readonly to?: string | readonly string[]; readonly within?: number }
 export type Area = { sphere: { at: Point; r: number } } | { box: { min: Point; max: Point } } | { cone: { at: Point; dir: Point; r: number; angle: number } };
-export interface MapView { readonly name: string; spot(name: string): Vec3 | undefined; spots(name: string): readonly Vec3[] }
+export interface MapView { tile(x:number,y:number):number; distance(flow:string,x:number,y:number):number; flow(name:string,x:number,y:number):Vec3|undefined; readonly name: string; spot(name: string): Vec3 | undefined; spots(name: string): readonly Vec3[] }
 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 tune: ReadonlyState<T>; readonly map: MapView; readonly stage: string; readonly level: number; readonly levelMax: number; readonly guideLevel: number; readonly guideSeats: readonly number[]; readonly kids: boolean; readonly levelSet: boolean;
+  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 } : {});
   /** Budget units the running handler may still spend (0.46.3). */
@@ -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,5 @@
+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';
 import type { RayQueries, RayOptions } from './types.ts';
@@ -72,7 +74,7 @@ export function blendHeading(a: Vec3, b: Vec3, t: number, dims: 2 | 3): Vec3 {
 }
 
 /** What the build hands the view library for one game: its declarations, its public tunables and its map. No code. */
-export interface GameData { vocab?: Vocabulary; id: string; schema: Schema; tune: Record<string, unknown>; map: { name?: string; bounds: { min: unknown; max: unknown }; boxes?: unknown[]; circles?: unknown[]; spheres?: unknown[]; capsules?: unknown[]; heightTiles?: unknown[]; spots?: Record<string, unknown[]> } }
+export interface GameData { vocab?: Vocabulary; id: string; schema: Schema; tune: Record<string, unknown>; map: { name?: string; bounds: { min: unknown; max: unknown }; boxes?: unknown[]; circles?: unknown[]; spheres?: unknown[]; capsules?: unknown[]; heightTiles?: unknown[]; wrap?: Partial<Record<'x'|'y'|'z',true>>; tiles?: unknown; spots?: Record<string, unknown[]> } }
 let current: { game: GameData; move: Record<string, MoveFn>; load?: () => Promise<RulesHostFactory> } | null = null;
 /** Called by the build's own two lines at the top of a view's bundle, before the view's code runs. */
 export function setGame(game: GameData, move: Record<string, MoveFn> = {}, load?: () => Promise<RulesHostFactory>): void { current = { game, move, load }; }
@@ -113,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;
   /**
@@ -159,7 +163,7 @@ export interface Room<R = unknown> extends RayQueries {
   askButtons(id: string, offer?: Record<string, unknown>): AskButton[];
   readonly tune: Readonly<Record<string, unknown>>;
   /** The game's static map: its edges, its solid shapes and its named spots, in metres. */
-  readonly map: { readonly bounds: { min: Vec3; max: Vec3 }; readonly boxes: readonly { min: Vec3; max: Vec3 }[]; readonly circles: readonly { at: Vec3; r: number }[]; readonly heightTiles: readonly import('./rules.ts').MapHeightTile[]; readonly spheres: readonly { at: Vec3; r: number }[]; readonly capsules: readonly { at: Vec3; r: number; height: number }[]; readonly spots: Readonly<Record<string, readonly Vec3[]>> };
+  readonly map: import('./rules.ts').GameMap;
   readonly net: Netplay;
   /** Run the room's clock up to now (called by itself on a timer and whenever the view reads the room). */
   pump(): void;
@@ -191,6 +195,19 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   const emit = (name: string, e: unknown, local = false): void => { if (Boolean(solo) !== local) return; for (const fn of listeners.get(name) ?? []) { try { fn(e); } catch (err) { console.warn(`[room] on('${name}')`, err); } } };
   const map = compileMap(game.map, game.map.name ?? 'main');
   const spots = map.spots;
+  const compiledMaps = new Map<string, typeof map>();
+  const mapOf = (data?: import('./map-state.ts').MapRevision | null) => {
+    if (!data) return map;
+    const key = `${epoch}:${data[0]}`;
+    let value = compiledMaps.get(key);
+    if (!value) {
+      value = compileMap(data[1], map.name);
+      compiledMaps.set(key, value);
+      // Only replay history needs old compiled indexes; saves carry the compact data.
+      if (compiledMaps.size > 64) compiledMaps.delete(compiledMaps.keys().next().value!);
+    }
+    return value;
+  };
   const tune = Object.freeze({ ...(lab.rulesTune({ public: game.tune }).public as Record<string, unknown>) });
 
   let status: RoomStatus = 'connecting';
@@ -259,7 +276,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   const quantile = (list: number[], q: number): number => [...list].sort((a, b) => a - b)[Math.floor((list.length - 1) * q)] ?? 0;
   const targetLead = (): number => 0.5 + Math.max(0, quantile(leads, 0.5) - quantile(leads, 0.05));
   const copyMine = (m: Mine): Mine => ({ ...m, motion: motionOf(m.kind, m.motion) });
-  const distance = (a: Vec3, b: Vec3): number => Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
+  const distance = (a: Vec3, b: Vec3): number => Math.hypot(periodicDelta(b.x,a.x,map.wrap?.x),periodicDelta(b.y,a.y,map.wrap?.y),periodicDelta(b.z,a.z,map.wrap?.z));
   const correction = { count: 0, max: 0, last: 0, catches: 0, snaps: 0, rebases: 0, rebaseReason: '', rebaseError: 0 };
   function visualOffset(now: number, path?: Vec3, settled = false): Vec3 {
     if (predict.blendMs <= 0) { offsets = []; return { x: 0, y: 0, z: 0 }; }
@@ -300,9 +317,21 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   let collisionHistory: CollisionRevision[] = [];
   let cachedCollision: CollisionRevision | undefined;
   let geometry = map as import('./math.ts').MapShapes;
+  const mapAt = (tick:number) => {
+    if (!collisionHistory.at(-1)?.[3]?.map) return map;
+    // Map activation and live collider projection have independent effective ticks.
+    // A lost pending snapshot must not postpone a map already active in its successor.
+    for (let i=collisionHistory.length-1;i>=0;i--) {
+      const metadata=collisionHistory[i][3];
+      if (metadata?.map && metadata.map[0]<=tick) return mapOf(metadata.map);
+      if (metadata?.previousMap && metadata.previousMap[0]<=tick) return mapOf(metadata.previousMap);
+    }
+    return map;
+  };
   const geometryAt = () => {
     const revision = revisionAt(collisionHistory, moveTick);
-    if (revision !== cachedCollision) { geometry = collisionMap(map, revision?.[2] ?? []); cachedCollision = revision; }
+    const activeMap=mapAt(moveTick);
+    if (revision !== cachedCollision || (geometry.staticMap??geometry)!==activeMap) { geometry = collisionMap(activeMap, revision?.[2] ?? []); cachedCollision = revision; }
     return geometry;
   };
   const moveCtx = moveContext({ tick: () => moveTick, tickHz, tune, map, geometry: geometryAt, self: () => mine?.id, name: game.map.name ?? 'main', spots, radius: () => myKind()?.radius ?? 0, shape: () => ({ terrain: myKind()?.terrain, shape: myKind()?.shape ?? 'sphere', radius: myKind()?.radius ?? 0, height: myKind()?.height ?? 0 }), dims });
@@ -342,7 +371,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     const u = mine && latest?.ents.get(mine.id); if (u) adopt(u);
     if (mine) {
       history.set(stepped, copyMine(mine));
-      if (shown) offsets = [{ delta: { x: shown.x - mine.pos.x, y: shown.y - mine.pos.y, z: shown.z - mine.pos.z }, at: clock(), path: mine.pos, fade: 1, last: clock() }];
+      if (shown) offsets = [{ delta: { x: periodicDelta(mine.pos.x,shown.x,map.wrap?.x), y: periodicDelta(mine.pos.y,shown.y,map.wrap?.y), z: periodicDelta(mine.pos.z,shown.z,map.wrap?.z) }, at: clock(), path: mine.pos, fade: 1, last: clock() }];
     }
   }
   /** `motion` as this browser's own `move` may change it in place: what a snapshot carries is frozen, so every list, map and struct in it is copied. */
@@ -351,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;
@@ -361,12 +390,17 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     const out = stepMove(fn, body, input, moveCtx, Math.max(1, Math.floor(schema.settings.budget.tick / 4)), kindOf.get(kindName)?.motion ?? [], dims, (err) => { if (!(err instanceof BudgetError)) console.warn('[room] move', err); });
     const kind = kindOf.get(kindName), r = kind?.radius ?? 0;
     const height = kind?.height || 2 * r;
-    out.pos = vec3({ x: Math.max(map.bounds.min.x + r, Math.min(map.bounds.max.x - r, out.pos.x)), y: Math.max(map.bounds.min.y + r, Math.min(map.bounds.max.y - r, out.pos.y)), z: dims === 3 ? Math.max(map.bounds.min.z, Math.min(map.bounds.max.z - height, out.pos.z)) : 0 }, dims);
+    out.pos = vec3(boundPosition(out.pos,map,r,height,dims), dims);
     return out;
   }
   /* ---------------------------------------------------------------- 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;
@@ -396,11 +430,11 @@ 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],
-      rays: (options) => raySnapshot(map, viewTargets(atTickOf(options)), dims, options, id),
+      rays: (options) => raySnapshot(mapAt(t), viewTargets(atTickOf(options)), dims, options, id),
       rayAll: (from, direction, max, options) => viewRay(from, direction, max, options, true),
       ghost(kindOfGhost, at, data = {}, options = {}) {
         const k = kindOf.get(kindOfGhost);
@@ -425,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];
@@ -528,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; }
   }
@@ -562,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;
@@ -665,7 +707,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
           // Limit the new reconciliation, not an offset already being blended (which
           // can include a clock recalibration). Clipping that carried offset would
           // turn a small new error into a visible snap.
-          const change = { x: shown.x - corrected.x - oldOffset.x, y: shown.y - corrected.y - oldOffset.y, z: shown.z - corrected.z - oldOffset.z };
+          const change = { x: periodicDelta(corrected.x,shown.x,map.wrap?.x) - oldOffset.x, y: periodicDelta(corrected.y,shown.y,map.wrap?.y) - oldOffset.y, z: periodicDelta(corrected.z,shown.z,map.wrap?.z) - oldOffset.z };
           const gap = Math.hypot(change.x, change.y, change.z);
           const ahead = Math.max(0, tickAt(clock()) - f.k) / tickHz;
           const cap = predict.snapM ?? myKind()!.maxSpeed * (2 * ahead + 0.1);
@@ -784,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);
@@ -811,11 +854,19 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
         const free = -mine.vel.z / tickHz, contact = free > 1e-6 ? Math.max(0.05, Math.min(1, (mine.pos.z - next.pos.z) / free)) : 1;
         av = Math.min(1, a / contact); landed = a >= contact;
       }
-      pos = vec3({ x: lerp(mine.pos.x, next.pos.x, a), y: lerp(mine.pos.y, next.pos.y, a), z: lerp(mine.pos.z, next.pos.z, av) }, dims);
+      pos = vec3({...blendPosition(mine.pos,next.pos,a,map.wrap), z:wrapPoint({x:0,y:0,z:mine.pos.z+periodicDelta(mine.pos.z,next.pos.z,map.wrap?.z)*av},map.wrap).z}, dims);
       heading = blendHeading(mine.heading, next.heading, a, dims);
       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.
@@ -832,14 +883,14 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
         // Catch-up can reach the fractional current tick before its next whole step exists.
         // Use the normal drawing preview, including its 3D pose, instead of holding then jumping.
         const t = Math.floor(catchTick), a = history.get(t), b = history.get(t + 1) ?? (t === stepped ? preview : null);
-        if (a && b) { const f = catchTick - t; pos = { x: lerp(a.pos.x, b.pos.x, f), y: lerp(a.pos.y, b.pos.y, f), z: lerp(a.pos.z, b.pos.z, f) }; heading = blendHeading(a.heading, b.heading, f, dims);
+        if (a && b) { const f = catchTick - t; pos = blendPosition(a.pos, b.pos, f, map.wrap); heading = blendHeading(a.heading, b.heading, f, dims);
           velocity = vec3({ x: lerp(a.vel.x, b.vel.x, f), y: lerp(a.vel.y, b.vel.y, f), z: lerp(a.vel.z, b.vel.z, f) }, dims);
           grounded = a.grounded && (f === 0 || b.grounded); motion = a.motion;
         } else if (a) { pos = a.pos; heading = a.heading; velocity = a.vel; grounded = a.grounded; motion = a.motion; }
       }
     }
     const offset = visualOffset(clock(), pos, settled);
-    pos = { x: pos.x + offset.x, y: pos.y + offset.y, z: pos.z + offset.z };
+    pos = wrapPoint({ x: pos.x + offset.x, y: pos.y + offset.y, z: pos.z + offset.z },map.wrap);
     if (headingBlend) {
       const t = predict.blendMs > 0 ? Math.min(1, (clock() - headingBlend.at) / predict.blendMs) : 1;
       heading = blendHeading(headingBlend.from, heading, t, dims);
@@ -859,7 +910,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     if (ea.r !== eb.r || a?.e !== b?.e || !s) return entityOf(eb);
     const t = s.alpha;
     const h = blendHeading(ea.heading, eb.heading, t, dims);
-    return entityOf({ ...(t < 1 ? ea : eb), grounded: t >= 1 ? eb.grounded : ea.grounded && (t === 0 || eb.grounded), pos: vec3({ x: lerp(ea.pos.x, eb.pos.x, t), y: lerp(ea.pos.y, eb.pos.y, t), z: lerp(ea.pos.z, eb.pos.z, t) }, dims), vel: vec3({ x: lerp(ea.vel.x, eb.vel.x, t), y: lerp(ea.vel.y, eb.vel.y, t), z: lerp(ea.vel.z, eb.vel.z, t) }, dims), heading: h });
+    return entityOf({ ...(t < 1 ? ea : eb), grounded: t >= 1 ? eb.grounded : ea.grounded && (t === 0 || eb.grounded), pos: vec3(blendPosition(ea.pos, eb.pos, t, map.wrap), dims), vel: vec3({ x: lerp(ea.vel.x, eb.vel.x, t), y: lerp(ea.vel.y, eb.vel.y, t), z: lerp(ea.vel.z, eb.vel.z, t) }, dims), heading: h });
   }
   function get(id: string): Entity | null { const g = ghosts.get(id); return g ? ghostEntity(g) : drawn(id); }
   function each(kind: string, fn: (e: Entity) => void): void {
@@ -948,8 +999,8 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     let before: Frame | null = null, after: Frame | null = null;
     for (const f of held2) { if (!f.ents.has(id)) continue; if (f.k <= at) before = f; if (f.k >= at && !after) after = f; }
     const a = before?.ents.get(id), b = after?.ents.get(id);
-    if (a && b) { if (before === after || a.r !== b.r) return { pos: b.pos, vel: b.vel, known: true }; const m = (at - before!.k) / (after!.k - before!.k); return { pos: vec3({ x: lerp(a.pos.x, b.pos.x, m), y: lerp(a.pos.y, b.pos.y, m), z: lerp(a.pos.z, b.pos.z, m) }, dims), vel: b.vel, known: true }; }
-    if (a) { const s = Math.min(tickHz, at - before!.k) / tickHz; return { pos: vec3({ x: a.pos.x + a.vel.x * s, y: a.pos.y + a.vel.y * s, z: a.pos.z + a.vel.z * s }, dims), vel: a.vel, known: false }; }
+    if (a && b) { if (before === after || a.r !== b.r) return { pos: b.pos, vel: b.vel, known: true }; const m = (at - before!.k) / (after!.k - before!.k); return { pos: vec3(blendPosition(a.pos, b.pos, m, map.wrap), dims), vel: b.vel, known: true }; }
+    if (a) { const s = Math.min(tickHz, at - before!.k) / tickHz; return { pos: vec3(wrapPoint({ x: a.pos.x + a.vel.x * s, y: a.pos.y + a.vel.y * s, z: a.pos.z + a.vel.z * s },map.wrap), dims), vel: a.vel, known: false }; }
     return b ? { pos: b.pos, vel: b.vel, known: false } : null;
   }
   const atTickOf = (options: unknown): number | undefined => { const v = options !== null && typeof options === 'object' ? (options as { atTick?: unknown }).atTick : undefined; return typeof v === 'number' && Number.isFinite(v) ? v : undefined; };
@@ -963,7 +1014,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   }
   const viewTargets = (atTick?: number) => {
     pump();
-    const targets: QueryTarget[] = collisionTargets(collisionMap(map, collisionHistory.at(-1)?.[2] ?? []));
+    const targets: QueryTarget[] = collisionTargets(collisionMap(mapAt(latest?.k??0), collisionHistory.at(-1)?.[2] ?? []));
     for(const k of schema.kinds) {
       if(k.collider || !k.radius)continue;
       each(k.name,e=>{
@@ -974,7 +1025,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     }
     return targets;
   };
-  const viewRay = (from: unknown, direction: unknown, max: number, options?: RayOptions, all=false) => rayQuery(map,viewTargets(atTickOf(options)),dims,from,direction,max,options,mine?.id,all);
+  const viewRay = (from: unknown, direction: unknown, max: number, options?: RayOptions, all=false) => rayQuery(mapAt(latest?.k??0),viewTargets(atTickOf(options)),dims,from,direction,max,options,mine?.id,all);
   return {
     get viewTick() { return solo ? solo.viewTick : viewTickNow(); },
     get status() { return solo ? 'offline' : status; },
@@ -982,7 +1033,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     get me() { pump(); return meNow(); },
     each, get,
     ray: (from,direction,max,options) => solo ? solo.ray(from,direction,max,options) : viewRay(from,direction,max,options)[0],
-    rays: options => solo ? solo.rays(options) : raySnapshot(map,viewTargets(atTickOf(options)),dims,options,mine?.id),
+    rays: options => solo ? solo.rays(options) : raySnapshot(mapAt(latest?.k??0),viewTargets(atTickOf(options)),dims,options,mine?.id),
     poseAt: (id, tick) => solo ? solo.poseAt(id, tick) : poseAt(id, tick),
     rayAll: (from,direction,max,options) => solo ? solo.rayAll(from,direction,max,options) : viewRay(from,direction,max,options,true),
     on(name, fn) { let set = listeners.get(name); if (!set) { set = new Set(); listeners.set(name, set); } set.add(fn); forwardSolo(name); return () => { set?.delete(fn); }; },
@@ -1015,7 +1066,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
         if (nextShown && distance(shown, nextShown) > 0.00001) {
           const carried = visualOffset(now);
           // Coalesce the carried blend: analogue controls may change every frame.
-          offsets = [{ delta: { x: carried.x + shown.x - nextShown.x, y: carried.y + shown.y - nextShown.y, z: carried.z + shown.z - nextShown.z },
+          offsets = [{ delta: { x: carried.x + periodicDelta(nextShown.x,shown.x,map.wrap?.x), y: carried.y + periodicDelta(nextShown.y,shown.y,map.wrap?.y), z: carried.z + periodicDelta(nextShown.z,shown.z,map.wrap?.z) },
             at: now, last: now, fade: 1, path: { x: nextShown.x - carried.x, y: nextShown.y - carried.y, z: nextShown.z - carried.z } }];
         }
       }
@@ -1027,8 +1078,8 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     probe(x) { extra = { ...extra, ...x }; },
     ask(id, askId, args = {}) { if (solo) return; const e = latest?.ents.get(id); if (e && e.seat !== undefined) agents?.ask(e.seat, askId, args); },
     askButtons(id, offer = {}) { if (solo) return []; const e = latest?.ents.get(id); return e && e.seat !== undefined ? agents?.askButtons(e.seat, offer) ?? [] : []; },
-    tune, map: Object.freeze({ ...map, spots: Object.freeze(spots) }), net: net as Netplay,
+    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.46.6","sha256":"efd3ddbf72033f5d24b8107a41db2bc1a518f1d3f92963f5afd77c5c0e2f5059"});
+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.46.6';
+export const STUDIO_VERSION_TAG = '0.48.0';