@driftengine/core 3.61.0

package/src/behavior/behaviorTree.ts

@@ -0,0 +1,346 @@
+/**
+ * A behaviour tree that is data, so it can be looked at, paused and stepped.
+ *
+ * **The complaint this answers is not "a routine cannot be written".** It can, and a consumer
+ * reported theirs: a table of places and a loop that decides where to send everybody once an
+ * in-game hour. It works. What they also reported is what it is — a hand-written behaviour tree
+ * that cannot be inspected, paused or stepped — and where it gets expensive, which is the moment a
+ * routine needs **interrupting**: an agent dropping what it is doing because it started raining,
+ * and picking it up again afterwards.
+ *
+ * So the two things here are the two things a hand-rolled loop does not give you.
+ *
+ * **The tree is data.** Nodes are arrays of integers and names resolved once at build time; the
+ * consumer's own functions live in a table beside it. A running tree can therefore say which node
+ * it is in, by name, without anything having been instrumented — `activePath` walks it — and a
+ * `paused` character can be advanced one node at a time.
+ *
+ * **A preempted branch is suspended, not reset**, which is the whole of "picking it up again". A
+ * selector that switches to a higher-priority child leaves the lower one's cursors exactly where
+ * they were, so when the interruption ends the agent resumes at the step it had reached rather than
+ * at the start of its errand. State is reset only when a branch *finishes* — succeeds or fails —
+ * because that is when starting again is what starting again means. Every behaviour-tree
+ * implementation has to choose here, most reset on abort, and the difference is a villager who
+ * walks back to the shop after a shower against one who walks home and starts the day over.
+ *
+ * **Nothing allocates during a tick and nothing reads a clock.** A tick is a function of the tree,
+ * the character's own cursors, and whatever the consumer's context object holds.
+ */
+
+export const FAILURE = 0;
+export const SUCCESS = 1;
+export const RUNNING = 2;
+export type BehaviorStatus = 0 | 1 | 2;
+
+const SEQUENCE = 0;
+const SELECTOR = 1;
+const ACTION = 2;
+const CONDITION = 3;
+const GUARD = 4;
+
+/**
+ * A node, as a consumer writes one.
+ *
+ * Names are the point of the whole shape: they are what an inspector shows and what a log line
+ * says, and a tree whose nodes are anonymous is one you can watch running and still not read.
+ */
+export type BehaviorSpec =
+  | { readonly name: string; readonly sequence: readonly BehaviorSpec[] }
+  | { readonly name: string; readonly selector: readonly BehaviorSpec[] }
+  | { readonly name: string; readonly action: string }
+  | { readonly name: string; readonly condition: string }
+  /**
+   * Run the child only while the condition holds.
+   *
+   * **The interruption primitive.** A selector of guards is a list of priorities: the first guard
+   * whose condition is true runs its branch, and a branch that was running under a lower-priority
+   * guard is suspended rather than abandoned. That is how "stop what you are doing because it
+   * started raining" is expressed, and how the errand survives it.
+   */
+  | { readonly name: string; readonly whileTrue: string; readonly does: BehaviorSpec };
+
+/** What a running tree calls: the consumer's own verbs, by the names the tree uses. */
+export interface BehaviorTasks {
+  /** Something that takes time. Returns `RUNNING` until it is done. */
+  readonly actions: Readonly<Record<string, (context: never) => BehaviorStatus>>;
+  /** Something with an answer now. */
+  readonly conditions: Readonly<Record<string, (context: never) => boolean>>;
+}
+
+/** The tree, flattened. Built once; a character per agent shares it. */
+export interface BehaviorTree {
+  readonly kind: Uint8Array;
+  /** For a composite: where its children start in `child`. Length `nodeCount + 1`. */
+  readonly childStart: Uint32Array;
+  readonly child: Uint32Array;
+  /** For an action, condition or guard: which function in the table. */
+  readonly slot: Int32Array;
+  readonly names: readonly string[];
+  readonly nodeCount: number;
+  /** The functions, in the order `slot` indexes them. */
+  readonly actions: readonly ((context: never) => BehaviorStatus)[];
+  readonly conditions: readonly ((context: never) => boolean)[];
+}
+
+/**
+ * Flatten a spec, resolving every name against the tables.
+ *
+ * **A name with no function is refused here rather than at the moment the agent needs it.** A tree
+ * is authored once and run for hours; a typo that surfaces the first time a villager reaches the
+ * market is a typo that surfaces in front of somebody playing.
+ */
+export function buildBehaviorTree(root: BehaviorSpec, tasks: BehaviorTasks): BehaviorTree {
+  const kind: number[] = [];
+  const names: string[] = [];
+  const slot: number[] = [];
+  const childLists: number[][] = [];
+  const actions: ((context: never) => BehaviorStatus)[] = [];
+  const conditions: ((context: never) => boolean)[] = [];
+  const actionSlot = new Map<string, number>();
+  const conditionSlot = new Map<string, number>();
+
+  const resolveAction = (name: string, node: string): number => {
+    const found = actionSlot.get(name);
+    if (found !== undefined) return found;
+    const fn = tasks.actions[name];
+    if (fn === undefined) {
+      throw new Error(
+        `buildBehaviorTree: node "${node}" does an action "${name}" nothing provides`,
+      );
+    }
+    actions.push(fn);
+    actionSlot.set(name, actions.length - 1);
+    return actions.length - 1;
+  };
+  const resolveCondition = (name: string, node: string): number => {
+    const found = conditionSlot.get(name);
+    if (found !== undefined) return found;
+    const fn = tasks.conditions[name];
+    if (fn === undefined) {
+      throw new Error(`buildBehaviorTree: node "${node}" asks "${name}", which nothing answers`);
+    }
+    conditions.push(fn);
+    conditionSlot.set(name, conditions.length - 1);
+    return conditions.length - 1;
+  };
+
+  const visit = (spec: BehaviorSpec): number => {
+    const at = kind.length;
+    names.push(spec.name);
+    kind.push(0);
+    slot.push(-1);
+    childLists.push([]);
+
+    if ('sequence' in spec || 'selector' in spec) {
+      const children = 'sequence' in spec ? spec.sequence : spec.selector;
+      if (children.length === 0) {
+        throw new Error(`buildBehaviorTree: "${spec.name}" is a composite with no children`);
+      }
+      kind[at] = 'sequence' in spec ? SEQUENCE : SELECTOR;
+      const list = childLists[at] as number[];
+      for (const each of children) list.push(visit(each));
+    } else if ('action' in spec) {
+      kind[at] = ACTION;
+      slot[at] = resolveAction(spec.action, spec.name);
+    } else if ('condition' in spec) {
+      kind[at] = CONDITION;
+      slot[at] = resolveCondition(spec.condition, spec.name);
+    } else {
+      kind[at] = GUARD;
+      slot[at] = resolveCondition(spec.whileTrue, spec.name);
+      (childLists[at] as number[]).push(visit(spec.does));
+    }
+    return at;
+  };
+  visit(root);
+
+  const nodeCount = kind.length;
+  const childStart = new Uint32Array(nodeCount + 1);
+  for (let i = 0; i < nodeCount; i++) {
+    childStart[i + 1] = (childStart[i] ?? 0) + (childLists[i]?.length ?? 0);
+  }
+  const child = new Uint32Array(childStart[nodeCount] ?? 0);
+  for (let i = 0; i < nodeCount; i++) {
+    const list = childLists[i] ?? [];
+    for (let k = 0; k < list.length; k++) child[(childStart[i] ?? 0) + k] = list[k] ?? 0;
+  }
+
+  return {
+    kind: Uint8Array.from(kind),
+    childStart,
+    child,
+    slot: Int32Array.from(slot),
+    names,
+    nodeCount,
+    actions,
+    conditions,
+  };
+}
+
+/**
+ * One agent running one tree.
+ *
+ * A character per agent and one tree between them: the tree is read-only after building, and
+ * everything that differs between two villagers following the same routine is here.
+ */
+export class BehaviorRunner<Context> {
+  readonly tree: BehaviorTree;
+  /** How far through each composite this agent is. The state a suspension preserves. */
+  private readonly cursor: Uint32Array;
+  /** Which node each composite last handed control to, so a switch can be noticed. */
+  private readonly running: Int32Array;
+  /** The chain of nodes entered on the last tick, root first. */
+  private readonly path: Uint32Array;
+  private pathLength = 0;
+  private lastStatus: BehaviorStatus = RUNNING;
+
+  /**
+   * When true, `tick` does nothing and reports the last status.
+   *
+   * Paused rather than not-called, so a debugger can hold one agent while the world runs — and so
+   * `stepOnce` has something to mean.
+   */
+  paused = false;
+
+  constructor(tree: BehaviorTree) {
+    this.tree = tree;
+    this.cursor = new Uint32Array(tree.nodeCount);
+    this.running = new Int32Array(tree.nodeCount).fill(-1);
+    this.path = new Uint32Array(tree.nodeCount);
+  }
+
+  get status(): BehaviorStatus {
+    return this.lastStatus;
+  }
+
+  /** Advance one tick, unless paused. */
+  tick(context: Context): BehaviorStatus {
+    if (this.paused) return this.lastStatus;
+    return this.run(context);
+  }
+
+  /** Advance one tick even while paused. What a step button is wired to. */
+  stepOnce(context: Context): BehaviorStatus {
+    return this.run(context);
+  }
+
+  /** Forget everything: the next tick starts the routine from the beginning. */
+  reset(): void {
+    this.cursor.fill(0);
+    this.running.fill(-1);
+    this.pathLength = 0;
+    this.lastStatus = RUNNING;
+  }
+
+  /**
+   * The chain of nodes the last tick was inside, root first, filled into `out`.
+   *
+   * **This is the inspection the report asked for**, and it costs nothing to keep: the chain is
+   * recorded as the tick descends, so asking for it later is a copy rather than a second walk.
+   * `nameOf` turns the indices into the names the tree was written with.
+   */
+  activePath(out: Uint32Array): number {
+    const count = Math.min(this.pathLength, out.length);
+    for (let i = 0; i < count; i++) out[i] = this.path[i] ?? 0;
+    return count;
+  }
+
+  nameOf(node: number): string {
+    return this.tree.names[node] ?? '?';
+  }
+
+  private run(context: Context): BehaviorStatus {
+    this.pathLength = 0;
+    this.lastStatus = this.visit(0, context);
+    return this.lastStatus;
+  }
+
+  private visit(node: number, context: Context): BehaviorStatus {
+    if (this.pathLength < this.path.length) this.path[this.pathLength++] = node;
+    const tree = this.tree;
+    switch (tree.kind[node]) {
+      case ACTION: {
+        const fn = tree.actions[tree.slot[node] ?? 0];
+        return fn === undefined ? FAILURE : fn(context as never);
+      }
+      case CONDITION: {
+        const fn = tree.conditions[tree.slot[node] ?? 0];
+        return fn !== undefined && fn(context as never) ? SUCCESS : FAILURE;
+      }
+      case GUARD: {
+        const fn = tree.conditions[tree.slot[node] ?? 0];
+        /*
+         * The condition has stopped holding. The child keeps every cursor it had: this is the node
+         * that makes an interruption resumable, and clearing here is the single change that would
+         * turn a villager who returns to their errand into one who starts the day again.
+         */
+        if (fn === undefined || !fn(context as never)) return FAILURE;
+        return this.visit(tree.child[tree.childStart[node] ?? 0] ?? 0, context);
+      }
+      case SEQUENCE:
+        return this.sequence(node, context);
+      default:
+        return this.selector(node, context);
+    }
+  }
+
+  private sequence(node: number, context: Context): BehaviorStatus {
+    const tree = this.tree;
+    const start = tree.childStart[node] ?? 0;
+    const end = tree.childStart[node + 1] ?? 0;
+    const count = end - start;
+    /* Resumed from the cursor, which is what makes a sequence a routine rather than a list of
+       things attempted from the top every tick. */
+    for (let i = this.cursor[node] ?? 0; i < count; i++) {
+      const status = this.visit(tree.child[start + i] ?? 0, context);
+      if (status === RUNNING) {
+        this.cursor[node] = i;
+        return RUNNING;
+      }
+      if (status === FAILURE) {
+        this.clear(node);
+        return FAILURE;
+      }
+      /* Succeeded: on to the next, and the child starts clean the next time it is entered. */
+      this.clear(tree.child[start + i] ?? 0);
+    }
+    this.clear(node);
+    return SUCCESS;
+  }
+
+  private selector(node: number, context: Context): BehaviorStatus {
+    const tree = this.tree;
+    const start = tree.childStart[node] ?? 0;
+    const end = tree.childStart[node + 1] ?? 0;
+
+    for (let i = start; i < end; i++) {
+      const branch = tree.child[i] ?? 0;
+      const status = this.visit(branch, context);
+      if (status === FAILURE) continue;
+      /*
+       * **A different branch has taken over, and the one it displaced is left exactly as it was.**
+       * Nothing is cleared here, which is the whole feature: the displaced branch's cursors say
+       * which step of the errand it had reached, and it resumes there when this one stops being
+       * eligible. Resetting instead is the version of this that most implementations ship, and it
+       * is why interrupting an agent usually costs the thing it was doing.
+       */
+      this.running[node] = branch;
+      if (status === SUCCESS) {
+        this.clear(branch);
+        this.running[node] = -1;
+      }
+      return status;
+    }
+    this.clear(node);
+    return FAILURE;
+  }
+
+  /** Forget a subtree's progress, so it is entered fresh. Called when a branch finishes. */
+  private clear(node: number): void {
+    this.cursor[node] = 0;
+    this.running[node] = -1;
+    const start = this.tree.childStart[node] ?? 0;
+    const end = this.tree.childStart[node + 1] ?? 0;
+    for (let i = start; i < end; i++) this.clear(this.tree.child[i] ?? 0);
+  }
+}

package/src/cinematic/player.ts

@@ -0,0 +1,209 @@
+import { lerp } from '../math/scalar.ts';
+import type { ShotKind, ShotParams } from '../render/cinematicCamera.ts';
+import { validateCinematic } from './script.ts';
+import type { CameraKeyframe, CinematicLine, CinematicScript } from './script.ts';
+
+/**
+ * Plays a `CinematicScript`: a clock, the shot it is currently in, and the line
+ * that is currently up.
+ *
+ * It knows about time, camera placements and timed strings, and nothing else.
+ * Which shot suits which moment is the script's business, what a `look` means
+ * is the presentation's, and what any of it is *about* is the game's.
+ *
+ * Everything is derived from accumulated time rather than advanced per frame,
+ * so a script plays identically on a 144 Hz desktop and a phone dropping frames
+ * — a playback that steps an index per frame tells a different story at a
+ * different frame rate, and only one of the two was ever written down.
+ *
+ * The caller drives a `CinematicCamera` from it:
+ *
+ * ```ts
+ * player.update(dt);
+ * if (player.shotChanged) camera.cut(player.shot, player.timeSec);
+ * camera.update(dt, x, y, z, yaw);
+ * ```
+ *
+ * `shotChanged` is true only at a *cut*. A keyframed shot moves while it holds,
+ * and the object handed out by `shot` is a live view that keeps moving — so the
+ * rig damps its way along the authored path instead of snapping to it every
+ * frame. Copy it if you need to keep it past the next `update`.
+ */
+export class CinematicPlayer {
+  private readonly script: CinematicScript;
+  private time = 0;
+  private shotIndex = -1;
+  private lineIndex = -1;
+  private cut = false;
+  private current: ShotParams | null = null;
+  /**
+   * Scratch for keyframed shots, reused every frame. A cinematic is not a hot
+   * path in the sim sense, but it runs over a live world and a per-frame object
+   * is a per-frame collection somewhere later.
+   */
+  private readonly moving: MovingShot = { kind: 'chase', distance: 6, height: 2, fovDeg: 70 };
+  private readonly movingAnchor: [number, number, number] = [0, 0, 0];
+
+  constructor(script: CinematicScript, name = 'cinematic') {
+    // Even a script that came through `defineCinematic` is checked again: the
+    // ordering and non-overlap rules are what make "the line right now" a
+    // single answer, and this is the object that relies on them.
+    validateCinematic(name, script);
+    this.script = script;
+  }
+
+  get timeSec(): number {
+    return this.time;
+  }
+
+  get finished(): boolean {
+    return this.time >= this.script.durationSec;
+  }
+
+  /** The placement the camera should be holding, or null before the first shot. */
+  get shot(): ShotParams | null {
+    return this.current;
+  }
+
+  /** True on the frame a cut lands — the cue to `cut` the rig. */
+  get shotChanged(): boolean {
+    return this.cut;
+  }
+
+  /** The one line on screen, or null. Never two: the script cannot express it. */
+  get line(): CinematicLine | null {
+    return this.lineIndex < 0 ? null : this.script.lines[this.lineIndex];
+  }
+
+  update(frameDt: number): void {
+    this.cut = false;
+    if (this.finished) return;
+    this.time = Math.min(this.time + Math.max(0, frameDt), this.script.durationSec);
+    this.selectShot();
+    this.selectLine();
+  }
+
+  /**
+   * Straight to the end, holding nothing.
+   *
+   * Every returning player takes this path, so it has to leave the player inert
+   * rather than merely finished: a skip that leaves a cinematic shot behind
+   * hands somebody a run they cannot see.
+   */
+  skip(): void {
+    this.time = this.script.durationSec;
+    this.clear();
+  }
+
+  /** Back to the top, for a replay from the menu. */
+  reset(): void {
+    this.time = 0;
+    this.clear();
+  }
+
+  private clear(): void {
+    this.shotIndex = -1;
+    this.lineIndex = -1;
+    this.current = null;
+    this.cut = false;
+  }
+
+  /**
+   * Scanned from the start rather than advanced from the last index: the answer
+   * is then a function of the clock alone, which is what survives a `reset`, a
+   * long frame that crosses two cuts, and a script short enough that the scan
+   * costs less than the branch saving it would.
+   */
+  private selectShot(): void {
+    const shots = this.script.shots;
+    let index = -1;
+    for (let i = 0; i < shots.length; i++) {
+      if (shots[i].atSec > this.time) break;
+      index = i;
+    }
+    if (index < 0) {
+      this.current = null;
+      return;
+    }
+    if (index !== this.shotIndex) {
+      this.shotIndex = index;
+      this.cut = true;
+    }
+
+    const camera = shots[index].camera;
+    this.current = 'kind' in camera ? camera : this.sample(camera, this.time - shots[index].atSec);
+  }
+
+  private selectLine(): void {
+    const lines = this.script.lines;
+    let index = -1;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (line.atSec > this.time) break;
+      // The window is closed at its end, so a line and its successor cannot
+      // both claim the instant one hands over to the other.
+      if (this.time < line.atSec + line.holdSec) {
+        index = i;
+        break;
+      }
+    }
+    this.lineIndex = index;
+  }
+
+  /**
+   * The placement `localSec` into a keyframed shot.
+   *
+   * Linear between keyframes, and deliberately not eased: the rig already damps
+   * its own motion, and easing each segment would stall the move at every key —
+   * a push-in that pulses instead of pushing.
+   */
+  private sample(frames: readonly CameraKeyframe[], localSec: number): ShotParams {
+    let index = 0;
+    for (let i = 0; i < frames.length; i++) {
+      if (frames[i].atSec > localSec) break;
+      index = i;
+    }
+    const from = frames[index].camera;
+    const fromSec = frames[index].atSec;
+    const hasNext = index + 1 < frames.length;
+    const to = hasNext ? frames[index + 1].camera : from;
+    const span = hasNext ? frames[index + 1].atSec - fromSec : 0;
+    // Past the last keyframe a shot holds its final placement rather than
+    // running on; the timeline says when it ends.
+    const t = span > 0 ? Math.min(1, (localSec - fromSec) / span) : 1;
+
+    const moving = this.moving;
+    moving.kind = from.kind;
+    moving.distance = lerp(from.distance, to.distance, t);
+    moving.height = lerp(from.height, to.height, t);
+    moving.fovDeg = lerp(from.fovDeg, to.fovDeg, t);
+
+    const fromRate = from.orbitRate;
+    const toRate = to.orbitRate;
+    moving.orbitRate =
+      fromRate === undefined || toRate === undefined ? fromRate : lerp(fromRate, toRate, t);
+
+    const fromAnchor = from.anchor;
+    const toAnchor = to.anchor;
+    if (fromAnchor === undefined || toAnchor === undefined) {
+      moving.anchor = fromAnchor;
+    } else {
+      const anchor = this.movingAnchor;
+      anchor[0] = lerp(fromAnchor[0], toAnchor[0], t);
+      anchor[1] = lerp(fromAnchor[1], toAnchor[1], t);
+      anchor[2] = lerp(fromAnchor[2], toAnchor[2], t);
+      moving.anchor = anchor;
+    }
+    return moving;
+  }
+}
+
+/** `ShotParams` with the readonly taken off, for the one instance we mutate. */
+interface MovingShot {
+  kind: ShotKind;
+  distance: number;
+  height: number;
+  fovDeg: number;
+  orbitRate?: number | undefined;
+  anchor?: readonly [number, number, number] | undefined;
+}