@origingame/engine 0.3.0 → 0.4.0

package/shell/platform.ts

@@ -43,6 +43,7 @@ export interface PlayerLink {
   readonly framed: boolean;
   readonly hosted: boolean;
   readonly capabilities: readonly string[];
+  readonly time?: number | undefined;
   request(method: string, args?: Record<string, unknown>): Promise<PlayerResult>;
   event(name: string, attrs?: Record<string, string | number | boolean | null>): void;
 }
@@ -169,6 +170,7 @@ export function playerPlatform(player: PlayerLink, local: LocalPersistence): Pla
   return {
     host: "player",
     capabilities,
+    time: player.time,
     handle(calls, answer) {
       // In order: a store write through the save reads it first, so calls never interleave.
       for (const call of calls) {
@@ -201,6 +203,9 @@ export function deferredPlatform(ready: Promise<PlatformHost>, capabilities: rea
   return {
     host: "player",
     capabilities,
+    get time() {
+      return real?.time;
+    },
     handle(calls, answer) {
       if (real) real.handle(calls, answer);
       else held.push([calls, answer]);

package/shell/player.ts

@@ -59,9 +59,9 @@ export type PlayerResult =
   | { readonly ok: true; readonly data: unknown; readonly time?: number }
   | { readonly ok: false; readonly error: { readonly code: string; readonly message: string; readonly retryable: boolean; readonly status?: number; readonly revision?: number }; readonly time?: number };
 
-/** A message's `time` field, when it is a finite number. */
+/** A message's `time` field, when it is finite UTC milliseconds since the epoch. */
 export const timeOf = (m: Record<string, unknown>): { time?: number } =>
-  typeof m["time"] === "number" && Number.isFinite(m["time"]) ? { time: m["time"] } : {};
+  typeof m["time"] === "number" && Number.isFinite(m["time"]) && m["time"] >= 0 ? { time: m["time"] } : {};
 
 /** How long a call waits for its `result` before it fails with `timeout`. */
 export const CALL_TIMEOUT_MS = 15_000;
@@ -93,6 +93,7 @@ export function connectPlayer(events: PlayerEvents) {
   let started = false;
   let paused = false;
   let capabilities: readonly string[] = [];
+  let time: number | undefined;
   let nextCall = 1;
   const calls = new Map<string, (r: PlayerResult) => void>();
 
@@ -116,6 +117,7 @@ export function connectPlayer(events: PlayerEvents) {
         heard = true;
         if (m["started"] === true) started = true;
         paused = m["paused"] === true;
+        time = timeOf(m).time;
         capabilities = Array.isArray(m["capabilities"]) ? (m["capabilities"] as unknown[]).filter((c): c is string => typeof c === "string") : [];
         events.hello?.({ started: m["started"] === true, paused, capabilities });
         break;
@@ -196,6 +198,10 @@ export function connectPlayer(events: PlayerEvents) {
     get capabilities(): readonly string[] {
       return capabilities;
     },
+    /** The most recent hello's clock, before any calls have been answered. */
+    get time(): number | undefined {
+      return time;
+    },
     loading(value: number | null, label?: string) {
       if (readySent) return;
       if (value !== null) {

package/shell/transport.ts

@@ -139,6 +139,7 @@ export interface PageConnection {
   readonly started: boolean;
   readonly paused: boolean;
   readonly capabilities: readonly string[];
+  readonly time: number | undefined;
   readonly page: PageInfo | null;
   /** Resolves once the hello is answered (true) or failed (false). */
   readonly hello: Promise<boolean>;
@@ -249,6 +250,7 @@ export function connectPage(game: PageGame, env: TransportEnv, events: PlayerEve
   // ── hello ──
   let hosted = false;
   let capabilities: readonly string[] = [];
+  let time: number | undefined;
   let page: PageInfo | null = null;
   const str = (v: unknown) => (typeof v === "string" && v ? v : null);
   const hello = serial(async () => {
@@ -256,6 +258,7 @@ export function connectPage(game: PageGame, env: TransportEnv, events: PlayerEve
     const m = r.data;
     if (r.status !== 200 || !m || m["kind"] !== "hello") return false;
     hosted = true;
+    time = timeOf(m).time;
     capabilities = Array.isArray(m["capabilities"]) ? (m["capabilities"] as unknown[]).filter((c): c is string => typeof c === "string") : [];
     const p = (m["page"] ?? null) as Record<string, unknown> | null;
     page = p && typeof p === "object" ? { title: str(p["title"]), cover: str(p["cover"]), backdrop: str(p["backdrop"]), back: str(p["back"]), portal: str(p["portal"]) } : null;
@@ -446,6 +449,9 @@ export function connectPage(game: PageGame, env: TransportEnv, events: PlayerEve
     get capabilities() {
       return capabilities;
     },
+    get time() {
+      return time;
+    },
     get page() {
       return page;
     },

package/src/generated/abi.ts

@@ -29,7 +29,7 @@ export interface HostAbi<A, V> {
   og_engine_take_log(engine: number): string;
   /** Write some fields of a resource as JSON: the runtime's path for a write a publish build refuses (logged once per system). A Result. */
   og_engine_write_resource(world: number, resource: string, value: string): string;
-  /** A resource's packed layout, how the runtime reads and writes its fields as bytes: a Result of `{ epoch, size, fields: [{ name, kind, offset, size, readonly, capacity, variants }] }` (`kind`: f32, f64, u32, i32, bool, Vector2, Vector3, Quaternion, Color, Matrix4, handle, str, enum). Refused for og.Time, og.Rng and og.Input, whose handles are computed, and for what is not a registered resource. */
+  /** A resource's packed layout, how the runtime reads and writes its fields as bytes: a Result of `{ epoch, size, fields: [{ name, kind, offset, size, readonly, capacity, variants, element }] }` (`kind`: f32, f64, u32, i32, bool, Vector2, Vector3, Quaternion, Color, Matrix4, handle, str, enum, or list: `element` one of f32, f64, u32, i32, handle and `capacity` its elements, a count lane first, each lane the element's size). Refused for og.Time, og.Rng and og.Input, whose handles are computed, and for what is not a registered resource. */
   og_engine_resource_layout(world: number, resource: string): string;
   /** A resource's packed bytes, then the layout epoch as a little-endian u32 (it moves when any layout is declared again: a new engine, a reload). Empty when refused (undeclared in the running system, not a resource): the runtime then asks og_world_resource for the reason. */
   og_engine_read_resource(world: number, resource: string): Uint8Array;
@@ -227,6 +227,8 @@ export interface HostAbi<A, V> {
   og_render_set_shader_param(world: number, material: number, name: string, value: string): string;
   /** `og.render.applyLook` */
   og_render_apply_look(world: number, look: number): string;
+  /** `og.render.applyQuality` */
+  og_render_apply_quality(world: number, preset: string): string;
   /** `og.render.look` */
   og_render_look(world: number): string;
   /** `og.render.capabilities` */
@@ -253,6 +255,28 @@ export interface HostAbi<A, V> {
   og_render_circle_geometry(world: number, desc: string | undefined): string;
   /** `og.render.tubeGeometry` */
   og_render_tube_geometry(world: number, desc: string | undefined): string;
+  /** `og.render.shapeGeometry` */
+  og_render_shape_geometry(world: number, desc: string | undefined): string;
+  /** `og.render.extrudeGeometry` */
+  og_render_extrude_geometry(world: number, desc: string | undefined): string;
+  /** `og.render.latheGeometry` */
+  og_render_lathe_geometry(world: number, desc: string | undefined): string;
+  /** `og.render.polyhedronGeometry` */
+  og_render_polyhedron_geometry(world: number, desc: string | undefined): string;
+  /** `og.render.icosahedronGeometry` */
+  og_render_icosahedron_geometry(world: number, desc: string | undefined): string;
+  /** `og.render.dodecahedronGeometry` */
+  og_render_dodecahedron_geometry(world: number, desc: string | undefined): string;
+  /** `og.render.octahedronGeometry` */
+  og_render_octahedron_geometry(world: number, desc: string | undefined): string;
+  /** `og.render.tetrahedronGeometry` */
+  og_render_tetrahedron_geometry(world: number, desc: string | undefined): string;
+  /** `og.render.sweepGeometry` */
+  og_render_sweep_geometry(world: number, desc: string | undefined): string;
+  /** `og.render.csgGeometry` */
+  og_render_csg_geometry(world: number, desc: string | undefined): string;
+  /** `og.render.mergeGeometries` */
+  og_render_merge_geometries(world: number, desc: string | undefined): string;
   /** `og.render.lines` */
   og_render_lines(world: number, desc: string | undefined): string;
   /** `og.render.points` */
@@ -869,6 +893,7 @@ export const SYMBOLS: readonly string[] = [
   "og_render_set_material_shader",
   "og_render_set_shader_param",
   "og_render_apply_look",
+  "og_render_apply_quality",
   "og_render_look",
   "og_render_capabilities",
   "og_render_text",
@@ -882,6 +907,17 @@ export const SYMBOLS: readonly string[] = [
   "og_render_ring_geometry",
   "og_render_circle_geometry",
   "og_render_tube_geometry",
+  "og_render_shape_geometry",
+  "og_render_extrude_geometry",
+  "og_render_lathe_geometry",
+  "og_render_polyhedron_geometry",
+  "og_render_icosahedron_geometry",
+  "og_render_dodecahedron_geometry",
+  "og_render_octahedron_geometry",
+  "og_render_tetrahedron_geometry",
+  "og_render_sweep_geometry",
+  "og_render_csg_geometry",
+  "og_render_merge_geometries",
   "og_render_lines",
   "og_render_points",
   "og_render_raycast",

package/src/geom.ts

@@ -0,0 +1,260 @@
+// Procedural modelling (IDL `shapes` and the og-geom members of `render`):
+// og.Shape and og.Path2, three.js's Shape and Path with its methods and its
+// curve formulas, and the render calls that take them. A shape never
+// crosses the wire: it is flattened to points here (three.js's
+// extractPoints(curveSegments)), so og-geom triangulates the same points
+// three.js would.
+//
+// Determinism: the points may end up in world state through the geometry
+// made from them, so the arcs read sincos (basic arithmetic, the camera
+// systems' series), never Math.sin or Math.cos.
+
+import type * as Api from "@origingame/engine";
+import type { HostAbi } from "./generated/abi.ts";
+import { boundHost } from "./runtime.ts";
+import { sincos } from "./systems/cameras.ts";
+
+type V2 = { x: number; y: number };
+type W = { readonly id: number };
+
+const TAU = 2 * 3.141592653589793;
+const EPSILON = 2.220446049250313e-16;
+const v2 = (x: number, y: number): V2 => ({ x, y });
+const equals = (a: V2, b: V2) => a.x === b.x && a.y === b.y;
+
+// three.js's Interpolations.
+function catmullRom(t: number, p0: number, p1: number, p2: number, p3: number): number {
+  const v0 = (p2 - p0) * 0.5;
+  const v1 = (p3 - p1) * 0.5;
+  const t2 = t * t;
+  const t3 = t * t2;
+  return (2 * p1 - 2 * p2 + v0 + v1) * t3 + (-3 * p1 + 3 * p2 - 2 * v0 - v1) * t2 + v0 * t + p1;
+}
+function quadratic(t: number, p0: number, p1: number, p2: number): number {
+  const k = 1 - t;
+  return k * k * p0 + 2 * (1 - t) * t * p1 + t * t * p2;
+}
+function cubic(t: number, p0: number, p1: number, p2: number, p3: number): number {
+  const k = 1 - t;
+  return k * k * k * p0 + 3 * k * k * t * p1 + 3 * (1 - t) * t * t * p2 + t * t * t * p3;
+}
+
+/** One of three.js's 2D curves, by its getPoint(t) and how finely CurvePath.getPoints divides it. */
+interface Curve {
+  point(t: number): V2;
+  resolution(divisions: number): number;
+}
+
+const line = (a: V2, b: V2): Curve => ({
+  // three.js LineCurve.getPoint: the end exactly at 1.
+  point: (t) => (t === 1 ? v2(b.x, b.y) : v2((b.x - a.x) * t + a.x, (b.y - a.y) * t + a.y)),
+  resolution: () => 1,
+});
+
+const quadraticCurve = (a: V2, c: V2, b: V2): Curve => ({
+  point: (t) => v2(quadratic(t, a.x, c.x, b.x), quadratic(t, a.y, c.y, b.y)),
+  resolution: (d) => d,
+});
+
+const cubicCurve = (a: V2, c1: V2, c2: V2, b: V2): Curve => ({
+  point: (t) => v2(cubic(t, a.x, c1.x, c2.x, b.x), cubic(t, a.y, c1.y, c2.y, b.y)),
+  resolution: (d) => d,
+});
+
+function splineCurve(points: readonly V2[]): Curve {
+  return {
+    point: (t) => {
+      const p = (points.length - 1) * t;
+      const i = Math.floor(p);
+      const w = p - i;
+      const p0 = points[i === 0 ? i : i - 1]!;
+      const p1 = points[i]!;
+      const p2 = points[i > points.length - 2 ? points.length - 1 : i + 1]!;
+      const p3 = points[i > points.length - 3 ? points.length - 1 : i + 2]!;
+      return v2(catmullRom(w, p0.x, p1.x, p2.x, p3.x), catmullRom(w, p0.y, p1.y, p2.y, p3.y));
+    },
+    resolution: (d) => d * points.length,
+  };
+}
+
+function ellipseCurve(x: number, y: number, rx: number, ry: number, start: number, end: number, clockwise: boolean, rotation: number): Curve {
+  return {
+    point: (t) => {
+      let delta = end - start;
+      const same = Math.abs(delta) < EPSILON;
+      while (delta < 0) delta += TAU;
+      while (delta > TAU) delta -= TAU;
+      if (delta < EPSILON) delta = same ? 0 : TAU;
+      if (clockwise && !same) delta = delta === TAU ? -TAU : delta - TAU;
+      const [s, c] = sincos(start + t * delta);
+      let px = x + rx * c;
+      let py = y + ry * s;
+      if (rotation !== 0) {
+        const [rs, rc] = sincos(rotation);
+        const tx = px - x;
+        const ty = py - y;
+        px = tx * rc - ty * rs + x;
+        py = tx * rs + ty * rc + y;
+      }
+      return v2(px, py);
+    },
+    resolution: (d) => d * 2,
+  };
+}
+
+const point = (p: Api.Vector2): V2 => v2(p.x, p.y);
+
+/** three.js's Path: curves from a current point. */
+export class Path2 {
+  #curves: Curve[] = [];
+  #current: V2 = v2(0, 0);
+
+  constructor(points?: readonly Api.Vector2[] | null) {
+    if (points) this.setFromPoints(points);
+  }
+
+  setFromPoints(points: readonly Api.Vector2[]): this {
+    if (points.length === 0) return this;
+    this.moveTo(points[0]!.x, points[0]!.y);
+    for (let i = 1; i < points.length; i++) this.lineTo(points[i]!.x, points[i]!.y);
+    return this;
+  }
+
+  moveTo(x: number, y: number): this {
+    this.#current = v2(x, y);
+    return this;
+  }
+
+  lineTo(x: number, y: number): this {
+    this.#curves.push(line(this.#current, v2(x, y)));
+    this.#current = v2(x, y);
+    return this;
+  }
+
+  quadraticCurveTo(cpX: number, cpY: number, x: number, y: number): this {
+    this.#curves.push(quadraticCurve(this.#current, v2(cpX, cpY), v2(x, y)));
+    this.#current = v2(x, y);
+    return this;
+  }
+
+  bezierCurveTo(cp1X: number, cp1Y: number, cp2X: number, cp2Y: number, x: number, y: number): this {
+    this.#curves.push(cubicCurve(this.#current, v2(cp1X, cp1Y), v2(cp2X, cp2Y), v2(x, y)));
+    this.#current = v2(x, y);
+    return this;
+  }
+
+  splineThru(points: readonly Api.Vector2[]): this {
+    if (points.length === 0) return this;
+    this.#curves.push(splineCurve([this.#current, ...points.map(point)]));
+    this.#current = point(points[points.length - 1]!);
+    return this;
+  }
+
+  arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, clockwise = false): this {
+    return this.absarc(x + this.#current.x, y + this.#current.y, radius, startAngle, endAngle, clockwise);
+  }
+
+  absarc(x: number, y: number, radius: number, startAngle: number, endAngle: number, clockwise = false): this {
+    return this.absellipse(x, y, radius, radius, startAngle, endAngle, clockwise);
+  }
+
+  ellipse(x: number, y: number, xRadius: number, yRadius: number, startAngle: number, endAngle: number, clockwise = false, rotation = 0): this {
+    return this.absellipse(x + this.#current.x, y + this.#current.y, xRadius, yRadius, startAngle, endAngle, clockwise, rotation);
+  }
+
+  absellipse(x: number, y: number, xRadius: number, yRadius: number, startAngle: number, endAngle: number, clockwise = false, rotation = 0): this {
+    const curve = ellipseCurve(x, y, xRadius, yRadius, startAngle, endAngle, clockwise, rotation);
+    if (this.#curves.length > 0) {
+      // A previous curve: join it with a line when the arc starts elsewhere.
+      const first = curve.point(0);
+      if (!equals(first, this.#current)) this.lineTo(first.x, first.y);
+    }
+    this.#curves.push(curve);
+    this.#current = curve.point(1);
+    return this;
+  }
+
+  closePath(): this {
+    if (this.#curves.length === 0) return this;
+    const start = this.#curves[0]!.point(0);
+    const end = this.#curves[this.#curves.length - 1]!.point(1);
+    if (!equals(start, end)) this.#curves.push(line(end, start));
+    return this;
+  }
+
+  getPoints(divisions = 12): Api.Vector2[] {
+    const out: V2[] = [];
+    let last: V2 | undefined;
+    for (const curve of this.#curves) {
+      const resolution = curve.resolution(divisions);
+      for (let d = 0; d <= resolution; d++) {
+        const p = curve.point(d / resolution);
+        if (last && equals(last, p)) continue;
+        out.push(p);
+        last = p;
+      }
+    }
+    return out;
+  }
+}
+
+/** three.js's Shape: a path with holes. */
+export class Shape extends Path2 {
+  readonly holes: Path2[] = [];
+
+  extractPoints(divisions = 12): Api.ShapePoints {
+    return { shape: this.getPoints(divisions), holes: this.holes.map((h) => h.getPoints(divisions)) };
+  }
+}
+
+// ── the render calls ────────────────────────────────────────────────────────
+
+function abi(): HostAbi<Uint32Array, unknown> {
+  const h = boundHost();
+  if (!h) throw new Error("no engine host is loaded: start the game through @origingame/engine's web or node loader");
+  return h.abi;
+}
+
+const parse = <T>(text: string): T => JSON.parse(text) as T;
+const json = (value: unknown): string | undefined => (value === undefined ? undefined : JSON.stringify(value));
+
+type Desc = Record<string, unknown>;
+
+/** A shape as it crosses: its points and its holes' points. */
+function flat(s: Path2, divisions: number): Api.ShapePoints {
+  return s instanceof Shape ? s.extractPoints(divisions) : { shape: s.getPoints(divisions), holes: [] };
+}
+
+/** `shapes` (a Shape, a list of them, or the outline's points) as points. */
+function shapes(desc: unknown): string | undefined {
+  if (desc === undefined || desc === null || typeof desc !== "object") return json(desc);
+  const d: Desc = { ...(desc as Desc) };
+  const divisions = typeof d.curveSegments === "number" ? d.curveSegments : 12;
+  const v = d.shapes;
+  if (v instanceof Path2) d.shapes = [flat(v, divisions)];
+  else if (Array.isArray(v) && v.length > 0 && v[0] instanceof Path2) d.shapes = (v as Path2[]).map((s) => flat(s, divisions));
+  return JSON.stringify(d);
+}
+
+/** A sweep's `section`: a Shape or Path2 flattened, its holes dropped. */
+function section(desc: unknown): string | undefined {
+  if (desc === undefined || desc === null || typeof desc !== "object") return json(desc);
+  const d: Desc = { ...(desc as Desc) };
+  const divisions = typeof d.curveSegments === "number" ? d.curveSegments : 12;
+  if (d.section instanceof Path2) d.section = d.section.getPoints(divisions);
+  return JSON.stringify(d);
+}
+
+export const geomRender = Object.freeze({
+  shapeGeometry: (world: W, desc?: unknown) => parse(abi().og_render_shape_geometry(world.id, shapes(desc))),
+  extrudeGeometry: (world: W, desc?: unknown) => parse(abi().og_render_extrude_geometry(world.id, shapes(desc))),
+  latheGeometry: (world: W, desc?: unknown) => parse(abi().og_render_lathe_geometry(world.id, json(desc))),
+  polyhedronGeometry: (world: W, desc?: unknown) => parse(abi().og_render_polyhedron_geometry(world.id, json(desc))),
+  icosahedronGeometry: (world: W, desc?: unknown) => parse(abi().og_render_icosahedron_geometry(world.id, json(desc))),
+  dodecahedronGeometry: (world: W, desc?: unknown) => parse(abi().og_render_dodecahedron_geometry(world.id, json(desc))),
+  octahedronGeometry: (world: W, desc?: unknown) => parse(abi().og_render_octahedron_geometry(world.id, json(desc))),
+  tetrahedronGeometry: (world: W, desc?: unknown) => parse(abi().og_render_tetrahedron_geometry(world.id, json(desc))),
+  sweepGeometry: (world: W, desc?: unknown) => parse(abi().og_render_sweep_geometry(world.id, section(desc))),
+  csgGeometry: (world: W, desc?: unknown) => parse(abi().og_render_csg_geometry(world.id, json(desc))),
+  mergeGeometries: (world: W, desc?: unknown) => parse(abi().og_render_merge_geometries(world.id, json(desc))),
+});

package/src/index.ts

@@ -28,6 +28,7 @@ import { cameras } from "./systems/cameras.ts";
 import { ai, i18n, nav, net, platform } from "./e6.ts";
 import { path, stream, terrain, timeline } from "./p2.ts";
 import { debug, depthRender } from "./depth.ts";
+import { geomRender, Path2, Shape } from "./geom.ts";
 import { targetsLoad, targetsRender } from "./targets.ts";
 import { lightRender } from "./light.ts";
 import { uiKit } from "./ui-kit/index.ts";
@@ -54,10 +55,14 @@ export const Matrix4 = ((value = { elements: identity() }, options) => spec("Mat
 export const Color = ((value = { r: 0, g: 0, b: 0 }, options) => spec("Color", value, options)) as typeof Api.Color;
 // The capacity crosses with the spec; the engine refuses one outside 1 to 4096 at declaration.
 export const str = ((capacity, value = "", options) => Object.freeze({ ...spec("str", value, options), capacity })) as typeof Api.str;
+// A list of another factory's kind: the engine refuses a kind that is not a number or a handle, and a capacity outside 1 to 1024, at declaration.
+export const list = ((of, capacity, options) =>
+  Object.freeze({ kind: of.kind, default: Object.freeze([]), options: Object.freeze({ ...(options ?? {}) }), list: capacity })) as typeof Api.list;
 export const Entity = ((value = 0 as Api.Entity, options) => spec("Entity", value, options)) as typeof Api.Entity;
 export const Geometry = ((value = 0 as Api.Geometry, options) => spec("Geometry", value, options)) as typeof Api.Geometry;
 export const Material = ((value = 0 as Api.Material, options) => spec("Material", value, options)) as typeof Api.Material;
 export const ToneMapping = ((value = "aces" as Api.ToneMapping, options) => spec("ToneMapping", value, options)) as typeof Api.ToneMapping;
+export const QualityPreset = ((value = "none" as Api.QualityPreset, options) => spec("QualityPreset", value, options)) as typeof Api.QualityPreset;
 export const Texture = ((value = 0 as Api.Texture, options) => spec("Texture", value, options)) as typeof Api.Texture;
 export const Lut = ((value = 0 as Api.Lut, options) => spec("Lut", value, options)) as typeof Api.Lut;
 export const EnvironmentMap = ((value = 0 as Api.EnvironmentMap, options) => spec("EnvironmentMap", value, options)) as typeof Api.EnvironmentMap;
@@ -189,7 +194,9 @@ export const og: typeof Api.og = Object.freeze({
   ...BUILTINS,
   game: (desc?: Api.GameDesc) => defineGame(desc as never),
   transform,
-  render: Object.freeze({ ...render, ...depthRender, ...targetsRender, ...lightRender }),
+  Shape,
+  Path2,
+  render: Object.freeze({ ...render, ...depthRender, ...geomRender, ...targetsRender, ...lightRender }),
   load: Object.freeze({ ...load, ...targetsLoad }),
   commands,
   physics,

package/src/node/playtest-run.ts

@@ -112,6 +112,7 @@ const command = (commands: string, dir: string, clock: number, room?: { url: str
   if (root) c.push("--root", root);
   if (desc!.seed !== undefined) c.push("--seed", String(desc!.seed));
   if (desc!.size) c.push("--size", desc!.size);
+  for (const step of (desc!.setup ?? "").split(";").map((s) => s.trim()).filter((s) => s !== "")) c.push("--setup", step);
   const store = storeOf(room?.place ?? 0);
   if (store) c.push("--platform-store", store);
   return c;

package/src/platform-local.ts

@@ -28,6 +28,8 @@ export interface PlatformHost {
   /** `player`, `local` or `none` (og.platform.info). */
   readonly host: string;
   readonly capabilities: readonly string[];
+  /** The Player hello's UTC milliseconds, sampled when this host attaches. */
+  readonly time?: number | undefined;
   /** Handle calls in order; answer every one but `telemetry`, now or later. */
   handle(calls: readonly PlatformCall[], answer: (request: number, result: PlatformAnswer) => void): void;
 }

package/src/playtest.ts

@@ -127,6 +127,14 @@ export interface PlaytestDesc {
   readonly seed?: number;
   /** The render target, `WIDTHxHEIGHT` (default 1280x720). */
   readonly size?: string;
+  /**
+   * `action[:args];...` run once through the command channel after `start`, before the first
+   * tick (`og run --setup`), in every process of the playtest: the stand-ins for what a host does
+   * around the game, such as `cover:12,12,40,40`, the published page's Back over the play surface
+   * (`Viewport.covered`), so the frames lay out as the page's. Not part of `commands`: the
+   * published page plays a script without it and covers itself.
+   */
+  readonly setup?: string;
   /** Run the script this many times in fresh processes (default 1) and report every end hash in `run.hashes`: a determinism check. The files are the first run's. */
   readonly runs?: number;
   /**