babavoss 0.0.1 → 0.12.0

package/src/ecs/scheduler.ts

@@ -0,0 +1,75 @@
+// The runtime's clock and timers, behind one interface, so a state can run
+// on the machine's time (the running baba) or on a virtual time a driver
+// advances (a testbed, a live simulation in the page). Every timer the
+// runtime sets goes through here: a round due, a source listing again, a
+// scheduled effect. Nothing in the runtime reads Date or sets a timeout
+// itself.
+
+export type Handle = { cancel(): void };
+
+export interface Scheduler {
+  /** The time, ms since the epoch or since a virtual zero. */
+  now(): number;
+  /** Runs `fn` once `now()` reaches `at`; at once when it already has. */
+  at(when: number, fn: () => void): Handle;
+  /** Runs `fn` on the next turn, after everything already queued: a round that takes every message already in flight. */
+  soon(fn: () => void): Handle;
+}
+
+/** The machine's time: what the running baba uses. Timers are unref'd so a runtime never keeps a process alive on its own. */
+export function realScheduler(): Scheduler {
+  const unref = (t: unknown) => { (t as { unref?: () => void }).unref?.(); };
+  return {
+    now: () => Date.now(),
+    at(when, fn) { const t = setTimeout(fn, Math.max(0, when - Date.now())); unref(t); return { cancel: () => clearTimeout(t) }; },
+    soon(fn) { const t = setTimeout(fn, 0); unref(t); return { cancel: () => clearTimeout(t) }; },
+  };
+}
+
+/**
+ * A time a driver advances. `advance(to)` runs every timer due up to `to`
+ * in time order, each at its own moment, so a round due at 200 and a
+ * listing due at 150 happen as they would on the machine, only faster
+ * and reproducibly. `soon` runs at the current moment, before any timer
+ * due later, at the next advance (or `flush`).
+ */
+export interface VirtualScheduler extends Scheduler {
+  /** Runs what is due up to and including `to`, then sets the time to `to`. */
+  advance(to: number): void;
+  /** Runs what is queued for now, without moving time. */
+  flush(): void;
+  /** The earliest moment anything is due, or null. */
+  next(): number | null;
+}
+
+export function virtualScheduler(start = 0): VirtualScheduler {
+  let now = start;
+  let seq = 0;
+  type Timer = { at: number; seq: number; fn: () => void; live: boolean };
+  const timers: Timer[] = [];
+  const add = (at: number, fn: () => void): Handle => { const t: Timer = { at, seq: seq++, fn, live: true }; timers.push(t); return { cancel: () => { t.live = false; } }; };
+  const takeDue = (upTo: number): Timer | undefined => {
+    let best: Timer | undefined;
+    for (const t of timers) if (t.live && t.at <= upTo && (!best || t.at < best.at || (t.at === best.at && t.seq < best.seq))) best = t;
+    if (best) timers.splice(timers.indexOf(best), 1);
+    return best;
+  };
+  const sweep = () => { for (let i = timers.length - 1; i >= 0; i--) if (!timers[i]!.live) timers.splice(i, 1); };
+  const run = (upTo: number) => {
+    for (let guard = 0; guard < 100_000; guard++) {
+      const t = takeDue(upTo);
+      if (!t) break;
+      if (t.at > now) now = t.at;
+      t.fn();
+    }
+    sweep();
+  };
+  return {
+    now: () => now,
+    at: (when, fn) => add(Math.max(when, now), fn),
+    soon: (fn) => add(now, fn),
+    advance(to) { if (to < now) to = now; run(to); now = to; },
+    flush() { run(now); },
+    next() { let n: number | null = null; for (const t of timers) if (t.live && (n === null || t.at < n)) n = t.at; return n; },
+  };
+}

package/src/ecs/snapshot.ts

@@ -0,0 +1,102 @@
+// The state as JSON, whole or as a delta, and the functions that move a
+// whole by a delta. Pure, browser-safe: the runtime makes them, the node,
+// the replica and the doors apply them.
+import type { Snapshot } from "./state.ts";
+
+/**
+ * What changed between round `since` and round `round`. Per entity that
+ * changed: the components written since, by name, each its value, or null
+ * for one taken away; null for an entity that is gone. A new entity's every
+ * part is in. Every resource that changed. The jobs, settlements and
+ * remembered answers, each only when it changed since. A follower at
+ * `since` applies it to its whole.
+ */
+export interface Delta {
+  kind: "delta";
+  round: number;
+  since: number;
+  entities: Record<string, Record<string, unknown> | null>;
+  resources: Record<string, unknown>;
+  jobs?: Snapshot["jobs"];
+  next?: number;
+  settled?: Snapshot["settled"];
+  keys?: Snapshot["keys"];
+  /** The makers of the entities in `entities`, those a system made. */
+  made?: Record<string, string>;
+  /** The parts that arrived since, by entity: a follower that tracks presence alone needs these and not the writes. */
+  added?: Record<string, string[]>;
+  /** The round's time, as `w.now` had it. */
+  now?: number;
+  /** The state of `w.random()`, so a kept state draws on as it would have. */
+  rng?: number;
+}
+
+export type StateAnswer = Snapshot | Delta;
+
+/** In place of a value a follower asked only the presence of: the part is there, its value is not held. */
+export const PRESENT: unknown = Object.freeze({ present: true });
+
+export const isDelta = (x: unknown): x is Delta => typeof x === "object" && x !== null && (x as { kind?: unknown }).kind === "delta";
+
+/** The whole at `delta.round`, from the whole at `delta.since`, changed in place: a keeper pays for what changed, not for what exists. A delta from another round than the whole's is refused. */
+export function patchSnapshot(whole: Snapshot, delta: Delta): Snapshot {
+  if (delta.since !== whole.round) throw new Error(`a delta since round ${delta.since} does not apply to round ${whole.round}`);
+  const made = whole.made ?? (whole.made = {});
+  for (const [id, patch] of Object.entries(delta.entities)) {
+    if (patch === null) { delete whole.entities[id]; delete made[id]; continue; }
+    // A patched entity gets a new parts object, so a whole copied shallowly before shares nothing with it after.
+    const parts = { ...(whole.entities[id] ?? {}) };
+    for (const [name, v] of Object.entries(patch)) { if (v === null) delete parts[name]; else parts[name] = v; }
+    whole.entities[id] = parts;
+    if (delta.made?.[id] !== undefined) made[id] = delta.made[id]!;
+  }
+  Object.assign(whole.resources, delta.resources);
+  whole.round = delta.round;
+  if (delta.jobs !== undefined) whole.jobs = delta.jobs;
+  if (delta.next !== undefined) whole.next = delta.next;
+  if (delta.settled !== undefined) whole.settled = delta.settled;
+  if (delta.keys !== undefined) whole.keys = delta.keys;
+  if (delta.now !== undefined) whole.now = delta.now;
+  if (delta.rng !== undefined) whole.rng = delta.rng;
+  return whole;
+}
+
+/** The same move on a copy: the input is not changed. */
+export function applyDelta(whole: Snapshot, delta: Delta): Snapshot {
+  return patchSnapshot({ ...whole, entities: { ...whole.entities }, resources: { ...whole.resources }, made: { ...(whole.made ?? {}) } }, delta);
+}
+
+/** Several consecutive deltas as one, from the first's `since` to the last's `round`: what a follower a few rounds behind applies at once. */
+export function mergeDeltas(deltas: Delta[]): Delta {
+  const first = deltas[0]!, last = deltas[deltas.length - 1]!;
+  const out: Delta = { kind: "delta", round: last.round, since: first.since, entities: {}, resources: {} };
+  const made: Record<string, string> = {};
+  let anyMade = false;
+  for (const [i, d] of deltas.entries()) {
+    if (i > 0 && d.since !== deltas[i - 1]!.round) throw new Error("deltas to merge are not consecutive");
+    for (const [id, patch] of Object.entries(d.entities)) {
+      if (patch === null) { out.entities[id] = null; delete made[id]; continue; }
+      const had = out.entities[id];
+      out.entities[id] = had ? { ...had, ...patch } : { ...patch };
+      if (d.made?.[id] !== undefined) made[id] = d.made[id]!;
+    }
+    if (d.made) anyMade = true;
+    Object.assign(out.resources, d.resources);
+    if (d.jobs !== undefined) out.jobs = d.jobs;
+    if (d.next !== undefined) out.next = d.next;
+    if (d.settled !== undefined) out.settled = d.settled;
+    if (d.keys !== undefined) out.keys = d.keys;
+    if (d.now !== undefined) out.now = d.now;
+    if (d.rng !== undefined) out.rng = d.rng;
+    if (d.added) { out.added ??= {}; for (const [id, names] of Object.entries(d.added)) { const have = out.added[id] ?? []; out.added[id] = [...new Set([...have, ...names])]; } }
+  }
+  if (anyMade) out.made = made;
+  return out;
+}
+
+/** A whole or a delta applied to the whole a follower holds; a whole replaces it. */
+export function follow(whole: Snapshot | null, answer: StateAnswer): Snapshot {
+  if (!isDelta(answer)) return answer;
+  if (!whole) throw new Error("a delta arrived before any whole");
+  return applyDelta(whole, answer);
+}