@homie-rocks/studio 0.32.1 → 0.33.1

package/rules/math.ts

@@ -0,0 +1,266 @@
+/*
+ * math.ts — `world.math` and `ctx.math`: the maths rules may not take from `Math`, in plain arithmetic.
+ * =============================================================================
+ *
+ * `Math.sin`, `cos`, `atan2`, `pow`, `exp`, `log` and `hypot` may differ in their last bits between JavaScript engines,
+ * so rules that used them would step differently on the server, in a browser and in the build check. Everything here is
+ * made of `+ - * /`, `Math.sqrt`, `Math.floor`, `Math.abs` and comparisons, each of which has one correct result
+ * (rooms-milestone-1-design.md, section 3.3). They are accurate to about 1e-12, which is far below what a game sees;
+ * what matters is that every engine gets the same bits.
+ *
+ * Vectors are `{ x, y, z }` in metres, `z` up. A helper returns a new frozen vector and never changes its arguments.
+ * Every call is charged 4 units to the running handler's budget (guard.ts), beside what any guarded call costs.
+ * =============================================================================
+ */
+import { brand, charge, own, put } from './guard.ts';
+
+export interface Vec3 { readonly x: number; readonly y: number; readonly z: number }
+
+const PI = 3.141592653589793;
+const TAU = 6.283185307179586;
+const HALF_PI = 1.5707963267948966;
+const LN2 = 0.6931471805599453;
+
+const v = (x: number, y: number, z: number): Vec3 => Object.freeze({ x, y, z });
+const zOf = (a: { z?: number }): number => a.z ?? 0;
+
+/** sin on [-pi/4, pi/4] and cos on the same range, by their Taylor series (terms to x^15 and x^16). */
+function sinK(x: number): number {
+  const x2 = x * x;
+  return x * (1 + x2 * (-1 / 6 + x2 * (1 / 120 + x2 * (-1 / 5040 + x2 * (1 / 362880 + x2 * (-1 / 39916800 + x2 * (1 / 6227020800 + x2 * (-1 / 1307674368000))))))));
+}
+function cosK(x: number): number {
+  const x2 = x * x;
+  return 1 + x2 * (-1 / 2 + x2 * (1 / 24 + x2 * (-1 / 720 + x2 * (1 / 40320 + x2 * (-1 / 3628800 + x2 * (1 / 479001600 + x2 * (-1 / 87178291200 + x2 * (1 / 20922789888000))))))));
+}
+/** x as k quarter turns plus a remainder in [-pi/4, pi/4]. */
+function reduce(x: number): [number, number] {
+  const q = Math.floor(x / HALF_PI + 0.5);
+  return [((q % 4) + 4) % 4, x - q * HALF_PI];
+}
+function sin(x: number): number {
+  if (!Number.isFinite(x)) return NaN;
+  const [q, r] = reduce(x);
+  return q === 0 ? sinK(r) : q === 1 ? cosK(r) : q === 2 ? -sinK(r) : -cosK(r);
+}
+function cos(x: number): number {
+  if (!Number.isFinite(x)) return NaN;
+  const [q, r] = reduce(x);
+  return q === 0 ? cosK(r) : q === 1 ? -sinK(r) : q === 2 ? -cosK(r) : sinK(r);
+}
+/** atan by halving the argument until it is small (atan x = 2 atan(x / (1 + sqrt(1 + x^2)))), then its series. */
+function atan(x: number): number {
+  if (x !== x) return NaN;
+  if (x === Infinity) return HALF_PI;
+  if (x === -Infinity) return -HALF_PI;
+  let a = x;
+  let scale = 1;
+  for (let i = 0; i < 4; i += 1) { a = a / (1 + Math.sqrt(1 + a * a)); scale *= 2; }
+  // The series is a - a^3/3 + a^5/5 - ...: built from the last term in, so each step multiplies by a^2.
+  const a2 = a * a;
+  let s = 0;
+  for (let n = 12; n >= 0; n -= 1) s = (n % 2 === 0 ? 1 : -1) / (2 * n + 1) + a2 * s;
+  return scale * a * s;
+}
+function atan2(y: number, x: number): number {
+  if (x !== x || y !== y) return NaN;
+  if (x > 0) return atan(y / x);
+  if (x < 0) return y >= 0 ? atan(y / x) + PI : atan(y / x) - PI;
+  return y > 0 ? HALF_PI : y < 0 ? -HALF_PI : 0;
+}
+/** exp by taking out whole powers of two (x = k ln 2 + r), then the series of e^r. */
+function exp(x: number): number {
+  if (x !== x) return NaN;
+  if (x > 709.78) return Infinity;
+  if (x < -745.2) return 0;
+  const kq = Math.floor(x / LN2 + 0.5);
+  const r = x - kq * LN2;
+  let sum = 1;
+  for (let n = 18; n >= 1; n -= 1) sum = 1 + (r / n) * sum;
+  let out = sum;
+  let p = kq;
+  while (p > 0) { out *= 2; p -= 1; }
+  while (p < 0) { out /= 2; p += 1; }
+  return out;
+}
+/** log by bringing x into [sqrt(1/2), sqrt 2) with powers of two, then 2 atanh((m - 1) / (m + 1)). */
+function log(x: number): number {
+  if (x !== x || x < 0) return NaN;
+  if (x === 0) return -Infinity;
+  if (x === Infinity) return Infinity;
+  let m = x;
+  let e = 0;
+  while (m >= 1.4142135623730951) { m /= 2; e += 1; }
+  while (m < 0.7071067811865476) { m *= 2; e -= 1; }
+  const y = (m - 1) / (m + 1);
+  const y2 = y * y;
+  let sum = 0;
+  for (let n = 14; n >= 0; n -= 1) sum = 1 / (2 * n + 1) + y2 * sum;
+  return 2 * y * sum + e * LN2;
+}
+/** x to the y. A whole y is repeated multiplication (exact for small powers); otherwise exp(y log x). */
+function pow(x: number, y: number): number {
+  if (y === 0) return 1;
+  if (x !== x || y !== y) return NaN;
+  if (Math.floor(y) === y && Math.abs(y) <= 1024) {
+    let base = x;
+    let n = Math.abs(y);
+    let out = 1;
+    while (n > 0) { if (n % 2 === 1) out *= base; base *= base; n = Math.floor(n / 2); }
+    return y < 0 ? 1 / out : out;
+  }
+  if (x < 0) return NaN;
+  if (x === 0) return y > 0 ? 0 : Infinity;
+  return exp(y * log(x));
+}
+
+const clamp = (x: number, lo: number, hi: number): number => (x < lo ? lo : x > hi ? hi : x);
+const len = (a: Vec3): number => Math.sqrt(a.x * a.x + a.y * a.y + zOf(a) * zOf(a));
+
+/**
+ * One function of the table, charged 4 units a call. `sig` names what each argument is: `n` a number, `o` a number
+ * that may be left out, `v` a vector. Anything else is refused before the function runs: arithmetic on a text would
+ * join texts (and grow one without limit), and arithmetic on a list or an object would have JavaScript turn it into a
+ * text first, at a cost the budget never sees.
+ */
+function paid<A extends unknown[], R>(name: string, sig: string, fn: (...a: A) => R): (...a: A) => R {
+  const wrong = (): never => { throw new TypeError(`math.${name} takes ${sig.split('').map((s) => (s === 'v' ? 'a vector' : 'a number')).join(', ')}: a vector is { x, y, z } of numbers`); };
+  return (...a: A): R => {
+    charge(4);
+    for (let i = 0; i < sig.length; i += 1) {
+      const arg = a[i] as any;
+      if (sig[i] !== 'v') { if (typeof arg !== 'number' && !(sig[i] === 'o' && arg === undefined)) wrong(); continue; }
+      if (arg === null || typeof arg !== 'object') wrong();
+      // Each part is read once and checked, and the function is handed a vector of those very numbers: nothing it reads can be anything else.
+      const x = arg.x; const y = arg.y; const z = arg.z;
+      if (typeof x !== 'number' || typeof y !== 'number' || (z !== undefined && typeof z !== 'number')) wrong();
+      a[i] = { x, y, z: z ?? 0 };
+    }
+    return fn(...a);
+  };
+}
+
+/** `world.math` and `ctx.math`. Frozen; the same object for every room. */
+export const math = brand(Object.freeze({
+  PI, TAU,
+  sin: paid('sin', 'n', sin), cos: paid('cos', 'n', cos), tan: paid('tan', 'n', (x: number) => sin(x) / cos(x)),
+  atan: paid('atan', 'n', atan), atan2: paid('atan2', 'nn', atan2),
+  asin: paid('asin', 'n', (x: number) => (x < -1 || x > 1 ? NaN : atan2(x, Math.sqrt(1 - x * x)))),
+  acos: paid('acos', 'n', (x: number) => (x < -1 || x > 1 ? NaN : atan2(Math.sqrt(1 - x * x), x))),
+  exp: paid('exp', 'n', exp), log: paid('log', 'n', log), pow: paid('pow', 'nn', pow),
+  hypot: paid('hypot', 'nno', (x: number, y: number, z: number = 0) => Math.sqrt(x * x + y * y + z * z)),
+  /** Degrees to radians, and back. */
+  rad: paid('rad', 'n', (deg: number) => (deg * PI) / 180),
+  deg: paid('deg', 'n', (rad: number) => (rad * 180) / PI),
+  clamp: paid('clamp', 'nnn', clamp),
+  lerp: paid('lerp', 'nnn', (a: number, b: number, t: number) => a + (b - a) * t),
+  vec: paid('vec', 'ooo', (x: number = 0, y: number = 0, z: number = 0) => v(x, y, z)),
+  add: paid('add', 'vv', (a: Vec3, b: Vec3) => v(a.x + b.x, a.y + b.y, zOf(a) + zOf(b))),
+  sub: paid('sub', 'vv', (a: Vec3, b: Vec3) => v(a.x - b.x, a.y - b.y, zOf(a) - zOf(b))),
+  scale: paid('scale', 'vn', (a: Vec3, k: number) => v(a.x * k, a.y * k, zOf(a) * k)),
+  dot: paid('dot', 'vv', (a: Vec3, b: Vec3) => a.x * b.x + a.y * b.y + zOf(a) * zOf(b)),
+  cross: paid('cross', 'vv', (a: Vec3, b: Vec3) => v(a.y * zOf(b) - zOf(a) * b.y, zOf(a) * b.x - a.x * zOf(b), a.x * b.y - a.y * b.x)),
+  len: paid('len', 'v', len),
+  dist: paid('dist', 'vv', (a: Vec3, b: Vec3) => len(v(a.x - b.x, a.y - b.y, zOf(a) - zOf(b)))),
+  /** A unit vector the same way; a zero vector stays zero. */
+  norm: paid('norm', 'v', (a: Vec3) => { const l = len(a); return l > 0 ? v(a.x / l, a.y / l, zOf(a) / l) : v(0, 0, 0); }),
+  /** The same direction, no longer than `max`. */
+  clampLen: paid('clampLen', 'vn', (a: Vec3, max: number) => { const l = len(a); return l > max && l > 0 ? v((a.x / l) * max, (a.y / l) * max, (zOf(a) / l) * max) : v(a.x, a.y, zOf(a)); }),
+  lerpVec: paid('lerpVec', 'vvn', (a: Vec3, b: Vec3, t: number) => v(a.x + (b.x - a.x) * t, a.y + (b.y - a.y) * t, zOf(a) + (zOf(b) - zOf(a)) * t)),
+  /** A unit vector on the ground plane at this angle (radians, from +x towards +y). */
+  dir: paid('dir', 'n', (angle: number) => v(cos(angle), sin(angle), 0)),
+  /** The angle of a vector on the ground plane. */
+  angle: paid('angle', 'v', (a: Vec3) => atan2(a.y, a.x)),
+}));
+export type RulesMath = typeof math;
+
+/** The unpaid functions, for the host runtime's own use (and the tests that hold them to `Math`'s). */
+export const exact = Object.freeze({ sin, cos, atan, atan2, exp, log, pow });
+
+/* ------------------------------------------------------------------ the ground plane: a point or a circle against the map */
+
+/** The shapes of a map the sweep reads (rules.ts `GameMap` has them). */
+export interface MapShapes { bounds: { min: Vec3; max: Vec3 }; boxes: readonly { min: Vec3; max: Vec3 }[]; circles: readonly { at: Vec3; r: number }[] }
+/** How close a swept body stops to what it hit, in metres. */
+export const SKIN = 0.001;
+
+export interface Hit { t: number; nx: number; ny: number; id?: string }
+/** A point moving from p along d (t in 0..1) against a circle of radius R: the first touch, or null. Starting inside is no touch. */
+export function rayCircle(px: number, py: number, dx: number, dy: number, cx: number, cy: number, R: number): Hit | null {
+  const ox = px - cx; const oy = py - cy;
+  const a = dx * dx + dy * dy;
+  if (a < 1e-18) return null;
+  const b = ox * dx + oy * dy;
+  const cc = ox * ox + oy * oy - R * R;
+  if (cc <= 0 || b >= 0) return null;
+  const disc = b * b - a * cc;
+  if (disc < 0) return null;
+  const t = (-b - Math.sqrt(disc)) / a;
+  if (t < 0 || t > 1) return null;
+  const hx = ox + dx * t; const hy = oy + dy * t;
+  const l = Math.sqrt(hx * hx + hy * hy) || 1;
+  return { t, nx: hx / l, ny: hy / l };
+}
+/** The same point against a box grown by r with round corners (a circle of radius r against the box). */
+function rayBox(px: number, py: number, dx: number, dy: number, min: Vec3, max: Vec3, r: number): Hit | null {
+  let t0 = 0; let t1 = 1; let nx = 0; let ny = 0;
+  const lo = [min.x - r, min.y - r]; const hi = [max.x + r, max.y + r];
+  const p = [px, py]; const d = [dx, dy];
+  for (let i = 0; i < 2; i += 1) {
+    if (Math.abs(d[i]) < 1e-12) { if (p[i] <= lo[i] || p[i] >= hi[i]) return null; continue; }
+    let ta = (lo[i] - p[i]) / d[i]; let tb = (hi[i] - p[i]) / d[i];
+    if (ta > tb) { const s = ta; ta = tb; tb = s; }
+    if (ta > t0) { t0 = ta; nx = i === 0 ? (d[i] > 0 ? -1 : 1) : 0; ny = i === 1 ? (d[i] > 0 ? -1 : 1) : 0; }
+    if (tb < t1) t1 = tb;
+    if (t0 > t1) return null;
+  }
+  // No entering face: the point started inside the grown box. A body already overlapping is let out, never held.
+  if (nx === 0 && ny === 0) return null;
+  const hx = px + dx * t0; const hy = py + dy * t0;
+  const cornerX = hx < min.x ? min.x : hx > max.x ? max.x : null;
+  const cornerY = hy < min.y ? min.y : hy > max.y ? max.y : null;
+  if (r > 0 && cornerX !== null && cornerY !== null) return rayCircle(px, py, dx, dy, cornerX, cornerY, r);
+  return { t: t0, nx, ny };
+}
+/** The world's edges, as walls facing in. */
+function rayBounds(px: number, py: number, dx: number, dy: number, b: { min: Vec3; max: Vec3 }, r: number): Hit | null {
+  let best: Hit | null = null;
+  const tryWall = (t: number, nx: number, ny: number): void => { if (t >= 0 && t <= 1 && (!best || t < best.t)) best = { t, nx, ny }; };
+  if (dx > 0) tryWall((b.max.x - r - px) / dx, -1, 0);
+  if (dx < 0) tryWall((b.min.x + r - px) / dx, 1, 0);
+  if (dy > 0) tryWall((b.max.y - r - py) / dy, 0, -1);
+  if (dy < 0) tryWall((b.min.y + r - py) / dy, 0, 1);
+  return best;
+}
+/** A circle (or a point, r 0) moved along d against the static map: the first thing in the way, and how many shapes were tested. */
+export function castMap(map: MapShapes, px: number, py: number, dx: number, dy: number, r: number): { hit: Hit | null; tested: number } {
+  let best: Hit | null = rayBounds(Math.max(map.bounds.min.x + r, Math.min(map.bounds.max.x - r, px)), Math.max(map.bounds.min.y + r, Math.min(map.bounds.max.y - r, py)), dx, dy, map.bounds, r);
+  for (const b of map.boxes) { const h = rayBox(px, py, dx, dy, b.min, b.max, r); if (h && (!best || h.t < best.t)) best = h; }
+  for (const c of map.circles) { const h = rayCircle(px, py, dx, dy, c.at.x, c.at.y, c.r + r); if (h && (!best || h.t < best.t)) best = h; }
+  return { hit: best, tested: 4 + map.boxes.length + map.circles.length };
+}
+
+/**
+ * `ctx.map.sweep(body, delta)`: move `body.pos` along `delta` and stop at the first static shape in the way. The server
+ * and a browser both move a body with this, so they agree to the last bit. Returns nothing, or `{ at, normal }`.
+ * Charged 20 units and 4 for each shape of the map. With `dims` 2 a body always rests on the ground.
+ */
+export function sweepMap(map: MapShapes, body: unknown, delta: unknown, radius: number, _dims: number): unknown {
+  // Charged before the cast, for every shape of the map it may test.
+  charge(20 + 4 * (4 + map.boxes.length + map.circles.length));
+  const fr = Math.fround;
+  // Both are whatever `move` handed over: each is read as a plain number or as nothing, and nothing is called to convert it.
+  const num = (a: unknown): number => { const x = typeof a === 'number' ? fr(a) : 0; return Number.isFinite(x) ? x : 0; };
+  if (body === null || typeof body !== 'object') throw new TypeError('ctx.map.sweep(body, delta) takes the body move was handed');
+  const pos = own(body, 'pos');
+  const dx = num(own(delta, 'x')); const dy = num(own(delta, 'y'));
+  const px = num(own(pos, 'x')); const py = num(own(pos, 'y'));
+  const { hit: h } = castMap(map, px, py, dx, dy, radius);
+  put(body, 'grounded', true);
+  if (!h) { put(body, 'pos', v(fr(px + dx), fr(py + dy), 0)); return undefined; }
+  const l = Math.sqrt(dx * dx + dy * dy);
+  const t = l > 0 ? Math.max(0, h.t - SKIN / l) : 0;
+  const at = v(fr(px + dx * t), fr(py + dy * t), 0);
+  put(body, 'pos', at);
+  return Object.freeze({ at, normal: v(h.nx, h.ny, 0) });
+}

package/rules/pack.ts

@@ -0,0 +1,292 @@
+/*
+ * pack.ts — declared state in and out: holding a value to its declared type, and packing it for the wire and the save.
+ * =============================================================================
+ *
+ * All of a rules game's state is in declared fields (rules.ts `f`). Three things follow from the declarations alone,
+ * and all three are here, so neither rules nor a view ever packs or unpacks anything:
+ *
+ *   coerce   a value held to its type as it is written: a whole number to its range, a vector to 32-bit floats, a
+ *            text to its largest length, a list to its largest size. Server, browser and build check all write
+ *            through it, so they hold the same numbers.
+ *   pack     a value as the frames carry it: positional, with no field names (the two ends share one build, so
+ *            they share the declarations). The frames are today's JSON text frames (NETPLAY.md section 5), so the
+ *            packed form is JSON arrays and numbers; a vector is `[x, y]` when `dims` is 2.
+ *   unpack   the reverse.
+ *
+ * The whole room packed into bytes (the save of a later slice, and the rebuilt-every-tick run of the build check) is
+ * `core.save()` through `toBytes` below: the same packing, with the runtime's own bookkeeping beside it.
+ * =============================================================================
+ */
+import { cellsOf } from './rules.ts';
+import type { Field, FieldList, Vec3 } from './rules.ts';
+import { charge, keyCount, own, refusedName } from './guard.ts';
+
+const RANGE: Record<string, [number, number]> = { u8: [0, 255], u16: [0, 65535], u32: [0, 4294967295], i8: [-128, 127], i16: [-32768, 32767], i32: [-2147483648, 2147483647], tick: [0, 4294967295], ticks: [0, 4294967295] };
+/** `f.fix`: steps of 1/4096, to plus or minus 2^31 (a tick count with a fraction fits for the life of any room). */
+export const FIX_STEP = 4096;
+const FIX_MAX = 2147483648;
+const fr = Math.fround;
+
+/*
+ * THE BOUNDARY. Every value that leaves rules code (what a handler returns, what it passes to a `world` call, what it
+ * writes to a field, a list, `motion`, an event or an effect) comes through the functions below and nowhere else. They
+ * hold three promises, and the runtime leans on all three:
+ *
+ *   no code of the rules runs.   A value is read by `typeof`, `Array.isArray` and its own data properties (`own`). A
+ *                                number is never made with `Number(x)` nor a text with `String(x)` from an object, so
+ *                                no `valueOf`, `toString`, `toJSON` or `Symbol.toPrimitive` is called; a property that
+ *                                is a getter reads as absent; nothing is iterated, so no iterator runs. (A `Proxy`
+ *                                would still run its traps here. Rules cannot make one: the build refuses the name.)
+ *   nothing throws.              What is not a plain number, text, true or false, list or object of the declared shape
+ *                                becomes the zero of that shape. The one exception is the budget's own stop, while a
+ *                                handler is running (`charge`, below, for a map's keys).
+ *   the work is bounded.         A list is read to its declared size and no further; a struct by its declared keys. So
+ *                                the cost of holding a value to its shape is bounded by the declaration (`cellsOf`),
+ *                                whatever was handed in, and `est` says in a few steps how much that will be, so the
+ *                                caller charges the running handler before the work is done.
+ *
+ * What comes out is plain data, frozen: a list, a map and a struct are new frozen objects, a vector is a frozen
+ * `{ x, y, z }`. Stored state is therefore read-only everywhere, and a query result or an event can hand it out as it
+ * is, with no copy. A handler that changes a list in place is handed a copy to change (`thaw`), which is held to its
+ * shape again when the handler ends.
+ */
+
+export { own };
+/** A number from a plain number, true or false, or a short text. Anything else, an object above all, is NaN: nothing is called to convert it. */
+export function num(v: unknown): number {
+  return typeof v === 'number' ? v : typeof v === 'boolean' ? (v ? 1 : 0) : typeof v === 'string' && v.length <= 40 ? Number(v) : NaN;
+}
+/** A value for a message, with nothing called to make it: a text as it is, anything else by its kind. */
+export function said(v: unknown): string {
+  return typeof v === 'string' ? v.slice(0, 40) : typeof v === 'number' || typeof v === 'boolean' ? String(v) : v === null ? 'null' : Array.isArray(v) ? 'a list' : `a value of type ${typeof v}`;
+}
+
+/** Vectors and directions this file made: frozen and already 32-bit floats, so they pass through again untouched. */
+const VECS = new WeakSet<object>();
+const DIRS = new WeakSet<object>();
+/** Lists, maps and structs this file made, each with the declaration it was held to: the same value under the same declaration is not read twice. */
+const MADE = new WeakMap<object, Field>();
+const INIT = new WeakMap<Field, { v: unknown }>();
+const mk = (x: number, y: number, z: number): Vec3 => { const p = Object.freeze({ x, y, z }); VECS.add(p); return p; };
+const f32 = (a: unknown): number => { const x = fr(num(a)); return Number.isFinite(x) ? x : 0; };
+
+export const ZERO: Vec3 = mk(0, 0, 0);
+export const AHEAD: Vec3 = mk(1, 0, 0);
+DIRS.add(AHEAD);
+
+/** A position or a velocity, as 32-bit floats; `z` is 0 when `dims` is 2. Anything that is not a number is 0. */
+export function vec3(v: unknown, dims: number): Vec3 {
+  if (v === null || typeof v !== 'object') return ZERO;
+  if (VECS.has(v)) { const p = v as Vec3; return dims === 2 && p.z !== 0 ? mk(p.x, p.y, 0) : p; }
+  return mk(f32(own(v, 'x')), f32(own(v, 'y')), dims === 2 ? 0 : f32(own(v, 'z')));
+}
+/** A unit vector on the ground plane, as 32-bit floats. Too short to have a direction: +x. One that is already a unit vector is kept as it is, so a direction packs and unpacks to itself. */
+export function dir(v: unknown, dims: number): Vec3 {
+  if (v !== null && typeof v === 'object' && DIRS.has(v) && (dims !== 2 || (v as Vec3).z === 0)) return v as Vec3;
+  const p = vec3(v, dims);
+  const l2 = p.x * p.x + p.y * p.y + p.z * p.z;
+  if (!(l2 > 1e-12)) return AHEAD;
+  if (Math.abs(l2 - 1) <= 1e-6) { DIRS.add(p); return p; }
+  const l = Math.sqrt(l2);
+  const d = mk(fr(p.x / l), fr(p.y / l), fr(p.z / l));
+  DIRS.add(d);
+  return d;
+}
+
+const made = <T extends object>(fd: Field, o: T): T => { Object.freeze(o); MADE.set(o, fd); return o; };
+
+/** A value held to its declared type: plain frozen data, made without running any code of the rules. What does not fit becomes the nearest value that does. */
+export function coerce(fd: Field, v: unknown, dims: number): unknown {
+  switch (fd.t) {
+    case 'bit': case 'press': return v === true || v === 1;
+    case 'fix': { const n = Math.round(num(v) * FIX_STEP) / FIX_STEP; return Number.isFinite(n) ? Math.max(-FIX_MAX, Math.min(FIX_MAX, n)) : 0; }
+    case 'vec3': return vec3(v, dims);
+    case 'dir': return dir(v, dims);
+    case 'ref': return typeof v === 'string' ? v.slice(0, 24) : '';
+    case 'text': return (typeof v === 'string' ? v : typeof v === 'number' || typeof v === 'boolean' ? String(v) : '').slice(0, fd.max);
+    case 'list': {
+      if (!Array.isArray(v)) return made(fd, []);
+      if (MADE.get(v) === fd) return v;
+      // An array's length is its own data property. No more than the declared size is read, however long the list is.
+      const n = Math.min(v.length, fd.max as number);
+      const out = new Array(n);
+      for (let i = 0; i < n; i += 1) out[i] = coerce(fd.of as Field, own(v, i), dims);
+      return made(fd, out);
+    }
+    case 'map': {
+      const out: Record<string, unknown> = Object.create(null);
+      if (v === null || typeof v !== 'object') return made(fd, out);
+      if (MADE.get(v) === fd) return v;
+      // The one cost here that the declaration does not bound: how many keys the value handed in has. The running handler
+      // pays for each: before they are listed when the count is known (a module's constant), after when the handler made
+      // the value itself (and so has already paid a unit and more for every key).
+      const known = Array.isArray(v) ? undefined : keyCount(v);
+      if (known !== undefined) charge(16 * known);
+      const keys = Object.keys(v);
+      if (known === undefined) charge(16 * keys.length);
+      let n = 0;
+      for (const key of keys) {
+        if (n >= (fd.max as number)) break;
+        if (key.length > 32 || refusedName(key)) continue;
+        out[key] = coerce(fd.of as Field, own(v, key), dims); n += 1;
+      }
+      return made(fd, out);
+    }
+    case 'struct': {
+      if (v !== null && typeof v === 'object' && MADE.get(v) === fd) return v;
+      const out: Record<string, unknown> = {};
+      for (const [key, sub] of Object.entries(fd.fields ?? {})) out[key] = coerce(sub, own(v, key), dims);
+      return made(fd, out);
+    }
+    default: {
+      const [lo, hi] = RANGE[fd.t];
+      const x = num(v);
+      const n = Math.round(x);
+      return Number.isFinite(n) ? Math.max(lo, Math.min(hi, n)) : x === Infinity ? hi : x === -Infinity ? lo : 0;
+    }
+  }
+}
+/**
+ * How many values holding `v` to its declaration will read, at most, found in a few steps and with no code of the
+ * rules run: a list by its length (never past its declared size) times its entries' declared size, a struct field by
+ * field, a map by its declaration. Never less than the work `coerce` then does, so a caller charges it first.
+ */
+export function est(fd: Field, v: unknown): number {
+  switch (fd.t) {
+    case 'list': return Array.isArray(v) ? (MADE.get(v) === fd ? 1 : 1 + Math.min(v.length, fd.max as number) * cellsOf(fd.of as Field)) : 1;
+    case 'struct': {
+      if (v === null || typeof v !== 'object' || MADE.get(v) === fd) return 1;
+      let n = 1;
+      for (const [key, sub] of Object.entries(fd.fields ?? {})) n += est(sub, own(v, key));
+      return n;
+    }
+    case 'map': return v !== null && typeof v === 'object' && MADE.get(v) !== fd ? cellsOf(fd) : 1;
+    default: return 1;
+  }
+}
+/** `est` for a record of declared fields. */
+export function estFields(list: FieldList, values: unknown): number {
+  if (values === null || typeof values !== 'object') return list.length;
+  let n = 0;
+  for (const [name, fd] of list) n += est(fd, own(values, name));
+  return n;
+}
+/** A copy a handler may change in place, of a value `coerce` made: lists, maps and structs are new and open, all the way down; everything else is shared. */
+export function thaw(fd: Field, v: unknown): unknown {
+  switch (fd.t) {
+    case 'list': { const a = v as unknown[]; const out = new Array(a.length); for (let i = 0; i < a.length; i += 1) out[i] = thaw(fd.of as Field, a[i]); return out; }
+    case 'map': { const out: Record<string, unknown> = Object.create(null); for (const key of Object.keys(v as object)) out[key] = thaw(fd.of as Field, (v as Record<string, unknown>)[key]); return out; }
+    case 'struct': { const out: Record<string, unknown> = {}; for (const [key, sub] of Object.entries(fd.fields ?? {})) out[key] = thaw(sub, (v as Record<string, unknown>)[key]); return out; }
+    default: return v;
+  }
+}
+/** A record of declared fields as `coerce` made them, with every list, map and struct a copy that may be changed in place (a browser's own `motion`). */
+export function thawFields(list: FieldList, values: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [name, fd] of list) out[name] = thaw(fd, values[name]);
+  return out;
+}
+/** The value a field starts with: its `init`, else the zero of its type. Made once for each declaration, and shared: it is frozen. */
+export function initOf(fd: Field, dims: number): unknown {
+  let hit = INIT.get(fd);
+  if (!hit) { hit = { v: coerce(fd, fd.init, dims) }; INIT.set(fd, hit); }
+  return hit.v;
+}
+/** Whether a field's value is changed in place (a list, a map, a struct), so a handler is handed a copy of it and the runtime holds the copy to its type again when the handler ends. */
+export const mutable = (fd: Field): boolean => fd.t === 'list' || fd.t === 'map' || fd.t === 'struct';
+
+/** 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. */
+export const packed = { n: 0 };
+
+export function pack(fd: Field, v: unknown, dims: number): unknown {
+  // One for the value, and for a text one more for every 64 characters: the same count `cellsOf` makes of a declaration.
+  packed.n += fd.t === 'text' ? 1 + ((v as string).length >> 6) : 1;
+  switch (fd.t) {
+    case 'bit': case 'press': return v ? 1 : 0;
+    case 'vec3': case 'dir': { const p = v as Vec3; return dims === 2 ? [p.x, p.y] : [p.x, p.y, p.z]; }
+    case 'list': return (v as unknown[]).map((x) => pack(fd.of as Field, x, dims));
+    case 'map': return Object.keys(v as object).sort().map((key) => [key, pack(fd.of as Field, (v as Record<string, unknown>)[key], dims)]);
+    case 'struct': return Object.entries(fd.fields ?? {}).map(([key, sub]) => pack(sub, (v as Record<string, unknown>)[key], dims));
+    default: return v;
+  }
+}
+export function unpack(fd: Field, w: unknown, dims: number): unknown {
+  switch (fd.t) {
+    case 'vec3': case 'dir': { const a = Array.isArray(w) ? w : []; return coerce(fd, { x: a[0], y: a[1], z: a[2] ?? 0 }, dims); }
+    case 'list': return coerce(fd, Array.isArray(w) ? w.map((x) => unpack(fd.of as Field, x, dims)) : [], dims);
+    case 'map': { const o: Record<string, unknown> = {}; for (const e of Array.isArray(w) ? w : []) if (Array.isArray(e) && typeof e[0] === 'string') o[e[0]] = unpack(fd.of as Field, e[1], dims); return coerce(fd, o, dims); }
+    case 'struct': { const a = Array.isArray(w) ? w : []; const o: Record<string, unknown> = {}; Object.entries(fd.fields ?? {}).forEach(([key, sub], i) => { o[key] = unpack(sub, a[i], dims); }); return coerce(fd, o, dims); }
+    default: return coerce(fd, w, dims);
+  }
+}
+
+/** A record of declared fields, packed in declaration order. */
+export function packFields(list: FieldList, values: Record<string, unknown>, dims: number): unknown[] {
+  const out = new Array(list.length);
+  for (let i = 0; i < list.length; i += 1) out[i] = pack(list[i][1], values[list[i][0]], dims);
+  return out;
+}
+export function unpackFields(list: FieldList, w: unknown, dims: number): Record<string, unknown> {
+  const a = Array.isArray(w) ? w : [];
+  const out: Record<string, unknown> = {};
+  for (let i = 0; i < list.length; i += 1) out[list[i][0]] = unpack(list[i][1], a[i], dims);
+  return out;
+}
+/** A record of declared fields with every value at its `init`. */
+export function initFields(list: FieldList, dims: number): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [name, fd] of list) out[name] = initOf(fd, dims);
+  return out;
+}
+/** A record held to its declarations: every declared field coerced, anything undeclared dropped. The record handed in is read by its own data properties only. */
+export function coerceFields(list: FieldList, values: unknown, dims: number): Record<string, unknown> {
+  const v = values !== null && typeof values === 'object' ? values : null;
+  const out: Record<string, unknown> = {};
+  for (const [name, fd] of list) { const x = v ? own(v, name) : undefined; out[name] = x === undefined ? initOf(fd, dims) : coerce(fd, x, dims); }
+  return out;
+}
+
+export const packVec = (p: Vec3, dims: number): number[] => (dims === 2 ? [p.x, p.y] : [p.x, p.y, p.z]);
+export const unpackVec = (a: unknown, dims: number): Vec3 => { const w = Array.isArray(a) ? a : []; return vec3({ x: w[0], y: w[1], z: w[2] ?? 0 }, dims); };
+
+/** A saved room as bytes, and back. The save is JSON text: every number in it is one a JSON number holds exactly. */
+export function toBytes(state: unknown): Uint8Array { return new TextEncoder().encode(JSON.stringify(state)); }
+export function fromBytes(bytes: Uint8Array): unknown { return JSON.parse(new TextDecoder().decode(bytes)); }
+
+/** A digest of a packed state (FNV-1a over its JSON text), for comparing two runs tick by tick. */
+export function digest(state: unknown): string {
+  const text = typeof state === 'string' ? state : JSON.stringify(state);
+  let h = 2166136261;
+  for (let i = 0; i < text.length; i += 1) h = Math.imul(h ^ text.charCodeAt(i), 16777619) >>> 0;
+  return h.toString(16).padStart(8, '0');
+}
+
+/* ------------------------------------------------------------------ one entity on the wire */
+
+/** What packing an entity needs of its kind: the core's table and the view's schema both have it. */
+export interface KindShape { name: string; player: unknown; fields: FieldList; motion: FieldList }
+export const DRIVERS = Object.freeze(['person', 'bot', 'ai']);
+/** An entity as every side holds it once unpacked. A player's body also has `seat`, `owner`, `driver` and `away`. */
+export interface Unpacked {
+  id: string; kind: string; r: number; pos: Vec3; vel: Vec3; heading: Vec3; grounded: boolean;
+  seat?: number; owner?: string; driver?: string; away?: boolean; goal?: unknown;
+  fields: Record<string, unknown>; motion: Record<string, unknown>;
+}
+
+/** One entity as a snapshot carries it: `[id, kind, r, pos, vel, heading, grounded, fields, motion]`, and for a player's body `seat, driver, away, owner` after. */
+export function packEntity(kind: KindShape & { index: number }, e: { id: string; r: number; pos: Vec3; vel: Vec3; heading: Vec3; grounded: boolean; seat: number; driver: string; away: boolean; owner: string; goal?: unknown; f: Record<string, unknown>; m: Record<string, unknown> }, dims: number): unknown[] {
+  const out: unknown[] = [e.id, kind.index, e.r, packVec(e.pos, dims), packVec(e.vel, dims), packVec(e.heading, dims), e.grounded ? 1 : 0, packFields(kind.fields, e.f, dims), packFields(kind.motion, e.m, dims)];
+  if (kind.player) out.push(e.seat, DRIVERS.indexOf(e.driver), e.away ? 1 : 0, e.owner, e.goal ?? null);
+  return out;
+}
+export function unpackEntity(kinds: readonly KindShape[], w: unknown, dims: number): Unpacked | null {
+  if (!Array.isArray(w)) return null;
+  const kind = kinds[Number(w[1])];
+  if (!kind || typeof w[0] !== 'string') return null;
+  const out: Unpacked = {
+    id: w[0], kind: kind.name, r: Number(w[2]) || 0, pos: unpackVec(w[3], dims), vel: unpackVec(w[4], dims), heading: unpackVec(w[5], dims), grounded: w[6] === 1,
+    fields: unpackFields(kind.fields, w[7], dims), motion: unpackFields(kind.motion, w[8], dims),
+  };
+  if (kind.player) { out.seat = Number(w[9]); out.driver = DRIVERS[Number(w[10])] ?? 'bot'; out.away = w[11] === 1; out.owner = typeof w[12] === 'string' ? w[12] : ''; out.goal = w[13] ?? null; }
+  return out;
+}