@driftengine/core 3.61.0

package/src/core/tickTrace.ts

@@ -0,0 +1,129 @@
+/**
+ * What a fixed-step simulation produced, tick by tick.
+ *
+ * Replaying a recorded run means re-running the simulation, which is far too
+ * expensive to do inside a frame and cannot be seeked into at all — an intent
+ * stream has no keyframes, so reaching tick 4,000 means running the four
+ * thousand before it. Running it *once*, up front, and keeping what each tick
+ * produced turns a replay from a simulation into a lookup.
+ *
+ * A flat `Float32Array` of `channels` values per tick, plus one byte of flags for
+ * the booleans that would otherwise cost four bytes each. Preallocate with
+ * `capacity` when the length is known — a caller replaying a recording always
+ * knows it — and nothing reallocates while the simulation is running.
+ */
+export interface TickTraceLike {
+  readonly length: number;
+  readonly channels: number;
+  sample(tick: number, out: Float32Array): void;
+  flagsAt(tick: number): number;
+  channelAt(tick: number, channel: number): number;
+  tickAtOrBefore(channel: number, value: number): number;
+}
+
+export class TickTrace implements TickTraceLike {
+  readonly channels: number;
+
+  private values: Float32Array;
+  private flags: Uint8Array;
+  private count = 0;
+
+  constructor(channels: number, capacity = 256) {
+    this.channels = Math.max(1, channels | 0);
+    const slots = Math.max(1, capacity | 0);
+    this.values = new Float32Array(slots * this.channels);
+    this.flags = new Uint8Array(slots);
+  }
+
+  get length(): number {
+    return this.count;
+  }
+
+  push(values: ArrayLike<number>, flags = 0): void {
+    if ((this.count + 1) * this.channels > this.values.length) this.grow();
+    const at = this.count * this.channels;
+    for (let i = 0; i < this.channels; i++) this.values[at + i] = values[i] ?? 0;
+    this.flags[this.count] = flags & 0xff;
+    this.count++;
+  }
+
+  /**
+   * The state at a tick, clamped to the range that exists.
+   *
+   * Clamped rather than refused because both ends are ordinary rather than
+   * exceptional: a caller one tick past the end is a character who has finished, and
+   * holding their last state is exactly what they should look like.
+   */
+  sample(tick: number, out: Float32Array): void {
+    const at = this.clamp(tick) * this.channels;
+    for (let i = 0; i < this.channels; i++) out[i] = this.values[at + i] ?? 0;
+  }
+
+  channelAt(tick: number, channel: number): number {
+    return this.values[this.clamp(tick) * this.channels + channel] ?? 0;
+  }
+
+  flagsAt(tick: number): number {
+    return this.flags[this.clamp(tick)] ?? 0;
+  }
+
+  /**
+   * The last tick at which a non-decreasing channel was at or below `value`.
+   *
+   * This is how two runs of the same course are compared **at the same point on
+   * the course** rather than at the same moment in time. Comparing by time drifts
+   * the instant one character takes a wider line; comparing by distance does not,
+   * which is what makes the difference a split rather than a guess.
+   *
+   * The **last** tick of a run of equal values, not the first, and that matters
+   * wherever the channel can stall: a character who stopped for half a second has a
+   * plateau, and answering its first tick would report them ahead by the whole
+   * length of the stall.
+   *
+   * The channel must be non-decreasing. Binary search over anything else returns
+   * an answer that is merely arbitrary rather than obviously wrong, so a caller
+   * whose channel can go backwards must clamp it on the way in.
+   *
+   * `-1` on an empty trace: there is no tick to name, and 0 would be a lie about
+   * a tick that does not exist.
+   */
+  tickAtOrBefore(channel: number, value: number): number {
+    if (this.count === 0) return -1;
+
+    let low = 0;
+    let high = this.count - 1;
+    if (this.channelAt(low, channel) > value) return 0;
+
+    while (low < high) {
+      // Biased upward, so `low` can actually reach `high` and the loop ends.
+      const mid = (low + high + 1) >> 1;
+      if (this.channelAt(mid, channel) <= value) low = mid;
+      else high = mid - 1;
+    }
+    return low;
+  }
+
+  private clamp(tick: number): number {
+    if (this.count === 0) return 0;
+    if (tick < 0) return 0;
+    return tick >= this.count ? this.count - 1 : tick | 0;
+  }
+
+  /**
+   * Both arrays double together.
+   *
+   * They are parallel and they are separate allocations, which is exactly how
+   * they come apart: a values array that grew while the flags one did not would
+   * read every flag past the old boundary as zero, and zero is a legal flag
+   * rather than an error anybody would notice.
+   */
+  private grow(): void {
+    const values = new Float32Array(this.values.length * 2);
+    values.set(this.values);
+    this.values = values;
+
+    const flags = new Uint8Array(this.flags.length * 2);
+    flags.set(this.flags);
+    this.flags = flags;
+  }
+}

package/src/core/timeCurve.ts

@@ -0,0 +1,175 @@
+import { TAU, clamp } from '../math/scalar.ts';
+
+/**
+ * Re-timing a stretch of playback: how much *source* time one second of clip
+ * time is worth.
+ *
+ * A curve is a reparameterisation, not an animation. It answers exactly one
+ * question — "given `localSec` into this segment, how far has the source
+ * advanced?" — which is what lets a caller drive a fixed-timestep simulation, a
+ * recorded stream or a video from the same maths.
+ *
+ * **Every curve is speed-neutral over its own segment**: whatever it steals it
+ * pays back, so `curveSpanSec` equals `durationSec` for every kind. That is the
+ * property that keeps a re-timed clip the length it was asked for. A curve that
+ * slowed time without catching up would quietly shorten the footage a fixed
+ * clip length can cover, and the clip would stop before the thing it was cut
+ * for.
+ *
+ * Pure, closed-form and allocation-free: evaluated once per rendered frame.
+ */
+export type TimeCurveKind = 'linear' | 'hold' | 'ramp' | 'stutter' | 'reverse';
+
+export interface TimeCurve {
+  readonly kind: TimeCurveKind;
+  /** Length of the segment on the clip's own clock, seconds. */
+  readonly durationSec: number;
+  /**
+   * How much of the segment the effect claims, 0–1.
+   *
+   * `hold`: the fraction frozen. `ramp`: the depth of the rate swing.
+   * `stutter`: the frozen fraction of each step. `reverse`: the fraction run
+   * backwards. Zero makes every kind behave as `linear`, which is the honest
+   * neutral rather than a special case to branch on.
+   */
+  readonly amount: number;
+  /** `stutter` only: one freeze-and-catch-up cycle, seconds. */
+  readonly stepSec: number;
+  /**
+   * `reverse` only: how far back the *caller* can actually go, in source
+   * seconds.
+   *
+   * Running a re-simulated stream backwards is impossible without keeping the
+   * states to go back to, so the reversible window is a property of the
+   * consumer's buffer and has to be supplied rather than assumed. A curve never
+   * returns an offset below `-reversibleSec`; a consumer with no buffer passes
+   * zero and gets no reversal at all.
+   */
+  readonly reversibleSec: number;
+}
+
+export interface TimeCurveOptions {
+  readonly amount?: number;
+  readonly stepSec?: number;
+  readonly reversibleSec?: number;
+}
+
+/**
+ * Ceiling on `amount`.
+ *
+ * Every kind pays its debt back by running the rest of the segment at
+ * `1 / (1 - amount)`, so an amount at 1 asks for infinite speed in zero time.
+ * Capped rather than merely documented: this is the kind of value a tuning pass
+ * pushes to its limit.
+ */
+export const MAX_TIME_CURVE_AMOUNT = 0.9;
+
+const LINEAR_STEP_SEC = 1;
+
+/**
+ * Build a curve, validating at construction.
+ *
+ * Fail-fast here rather than per-frame in `curveOffsetSec`: a curve is built
+ * once when a clip is planned, and a plan is a fine place to throw.
+ */
+export function timeCurve(
+  kind: TimeCurveKind,
+  durationSec: number,
+  options: TimeCurveOptions = {},
+): TimeCurve {
+  if (!Number.isFinite(durationSec) || durationSec <= 0) {
+    throw new Error(`A time curve needs a positive duration, got ${durationSec}`);
+  }
+  const amount = clamp(options.amount ?? 0, 0, MAX_TIME_CURVE_AMOUNT);
+  const requested = options.stepSec ?? LINEAR_STEP_SEC;
+  if (!Number.isFinite(requested) || requested <= 0) {
+    throw new Error(`A stutter step must be positive, got ${requested}`);
+  }
+
+  /*
+   * Snap the stutter step so a whole number of cycles fits the segment. A
+   * trailing part-cycle would leave the curve mid-freeze at its own end, which
+   * breaks neutrality by exactly the frozen remainder — small, and therefore
+   * the sort of drift that accumulates over a dozen shots without ever looking
+   * like a bug.
+   */
+  const cycles = Math.max(1, Math.round(durationSec / requested));
+
+  return {
+    kind,
+    durationSec,
+    amount,
+    stepSec: kind === 'stutter' ? durationSec / cycles : requested,
+    reversibleSec: Math.max(0, options.reversibleSec ?? 0),
+  };
+}
+
+/** A curve that does nothing, for a segment that is played straight. */
+export function linearCurve(durationSec: number): TimeCurve {
+  return timeCurve('linear', durationSec);
+}
+
+/**
+ * Source seconds elapsed by `localSec` into the curve.
+ *
+ * Monotonically non-decreasing for every kind except `reverse`, continuous
+ * everywhere, and clamped to the segment — outside it, the neighbouring
+ * segments own the clock.
+ */
+export function curveOffsetSec(curve: TimeCurve, localSec: number): number {
+  const duration = curve.durationSec;
+  const local = clamp(localSec, 0, duration);
+  const amount = curve.amount;
+  if (amount === 0) return local;
+
+  switch (curve.kind) {
+    case 'linear':
+      return local;
+
+    case 'hold': {
+      // Freeze on the cut, then run fast enough to arrive on time.
+      const frozen = amount * duration;
+      return local <= frozen ? 0 : (local - frozen) / (1 - amount);
+    }
+
+    case 'ramp': {
+      /*
+       * Slow, fast, slow — an "ease-in-out-in". The rate is
+       * `1 - amount * cos(TAU * t / duration)`, whose integral closes the loop
+       * exactly at the segment's end because a whole cosine period integrates
+       * to zero. Chosen over a hand-tuned easing precisely for that: neutrality
+       * is a consequence of the shape rather than something to correct for.
+       */
+      // determinism: build-time — presentation: remaps a cinematic's playback time, not a tick
+      return local - ((amount * duration) / TAU) * Math.sin((TAU * local) / duration);
+    }
+
+    case 'stutter': {
+      const step = curve.stepSec;
+      const cycles = Math.floor(local / step);
+      const into = local - cycles * step;
+      const frozen = amount * step;
+      const moving = into <= frozen ? 0 : (into - frozen) / (1 - amount);
+      return cycles * step + moving;
+    }
+
+    case 'reverse': {
+      // Only as far back as the caller kept states for. With no buffer this is
+      // zero and the segment plays straight.
+      const back = Math.min(amount * duration, curve.reversibleSec);
+      if (back <= 0) return local;
+      if (local <= back) return -local;
+      // Then recover the ground given up *and* the segment itself.
+      return -back + ((local - back) * (duration + back)) / (duration - back);
+    }
+  }
+}
+
+/**
+ * Source seconds a whole segment consumes — `durationSec` for every kind, and
+ * worth asking for rather than assuming: a caller composing segments needs the
+ * answer the curve actually gives, not the one it promises.
+ */
+export function curveSpanSec(curve: TimeCurve): number {
+  return curveOffsetSec(curve, curve.durationSec);
+}

package/src/core/withDefaults.ts

@@ -0,0 +1,28 @@
+/**
+ * Fill a defaults object from a partial one, ignoring keys whose value is `undefined`.
+ *
+ * **`{ ...DEFAULTS, ...given }` is the obvious spelling and it destroys the default it was
+ * written to preserve.** A spread copies every own key, including one explicitly set to
+ * `undefined` — so a caller writing `{ retractLambda: settings.lambda }`, where `settings.lambda`
+ * is `number | undefined`, does not fall back to the default. It overwrites it with `undefined`,
+ * and what comes out of the arithmetic downstream is `NaN`.
+ *
+ * That is not a hypothetical: measured on `Boom`, a timing of `{ retractLambda: undefined }` takes
+ * the arm's fraction from 0.96 to `NaN` on the first step, which is a camera that never recovers.
+ * And it is invisible to TypeScript here, because this repository does not run
+ * `exactOptionalPropertyTypes` — the flag that separates "absent" from "present and undefined".
+ * Under it, forty call sites in this tree pass an optional straight into an optional slot; the
+ * pattern is ordinary and the hazard is only in what receives it.
+ *
+ * So the merge is a function rather than a spread, and every `Partial<T>` over a `T` of defaults
+ * goes through it. One implementation, for the reason `Boom`'s own header gives about the arm it
+ * smooths: a third caller must not be able to get this wrong again.
+ */
+export function withDefaults<T extends object>(defaults: T, given: Partial<T>): T {
+  const merged = { ...defaults };
+  for (const key of Object.keys(given) as (keyof T)[]) {
+    const value = given[key];
+    if (value !== undefined) merged[key] = value as T[keyof T];
+  }
+  return merged;
+}

package/src/dev/contactProbe.ts

@@ -0,0 +1,115 @@
+import type { Aabb } from '@driftengine/physics';
+import type { ColliderSet } from '@driftengine/physics';
+
+/**
+ * What is around a box, in numbers a person can check.
+ *
+ * A development tool, not a physics path: `collide.ts` already resolves contacts and
+ * is tuned to do it without allocating. This answers a different question — *which
+ * colliders are here, and by how much* — for a diagnostic that runs when somebody
+ * presses a key, so it favours being readable over being fast.
+ *
+ * Signed depth per axis rather than a single distance, because the two failures worth
+ * telling apart look identical otherwise: a body 5 cm inside a deck and a body 5 cm
+ * above one are both "5 cm from a collider".
+ */
+export interface ContactReport {
+  index: number;
+  /** True where the collider is a hull; its box is then the broad phase only. */
+  hull: boolean;
+  minX: number;
+  minY: number;
+  minZ: number;
+  maxX: number;
+  maxY: number;
+  maxZ: number;
+  /** Overlap along the axis. Positive is penetration, negative is the gap. */
+  depthX: number;
+  depthY: number;
+  depthZ: number;
+  /** Straight line between the boxes. Zero exactly when all three axes overlap. */
+  distanceM: number;
+}
+
+export const CONTACT_LIMIT = 32;
+
+export function createContactReports(count = CONTACT_LIMIT): ContactReport[] {
+  const out: ContactReport[] = [];
+  for (let i = 0; i < count; i++) {
+    out.push({
+      index: -1,
+      hull: false,
+      minX: 0,
+      minY: 0,
+      minZ: 0,
+      maxX: 0,
+      maxY: 0,
+      maxZ: 0,
+      depthX: 0,
+      depthY: 0,
+      depthZ: 0,
+      distanceM: 0,
+    });
+  }
+  return out;
+}
+
+const SCRATCH_BOUNDS: Aabb = { minX: 0, minY: 0, minZ: 0, maxX: 0, maxY: 0, maxZ: 0 };
+
+/**
+ * Describe every collider overlapping `box` or within `radius` of it.
+ *
+ * Returns how many entries of `out` were written. Reports are in query order, which is
+ * spatial-hash order and therefore arbitrary: sort by `distanceM` at the point of
+ * display if order matters, rather than paying for it here.
+ */
+export function describeContacts(
+  colliders: ColliderSet,
+  box: Aabb,
+  radius: number,
+  scratch: Int32Array,
+  out: ContactReport[],
+): number {
+  const found = colliders.query(
+    box.minX - radius,
+    box.minY - radius,
+    box.minZ - radius,
+    box.maxX + radius,
+    box.maxY + radius,
+    box.maxZ + radius,
+    scratch,
+  );
+
+  let written = 0;
+  for (let k = 0; k < found && written < out.length; k++) {
+    const index = scratch[k] as number;
+    colliders.bounds(index, SCRATCH_BOUNDS);
+
+    const depthX =
+      Math.min(box.maxX, SCRATCH_BOUNDS.maxX) - Math.max(box.minX, SCRATCH_BOUNDS.minX);
+    const depthY =
+      Math.min(box.maxY, SCRATCH_BOUNDS.maxY) - Math.max(box.minY, SCRATCH_BOUNDS.minY);
+    const depthZ =
+      Math.min(box.maxZ, SCRATCH_BOUNDS.maxZ) - Math.max(box.minZ, SCRATCH_BOUNDS.minZ);
+
+    const gapX = Math.max(0, -depthX);
+    const gapY = Math.max(0, -depthY);
+    const gapZ = Math.max(0, -depthZ);
+
+    const report = out[written] as ContactReport;
+    report.index = index;
+    report.hull = colliders.shapeAt(index) !== undefined;
+    report.minX = SCRATCH_BOUNDS.minX;
+    report.minY = SCRATCH_BOUNDS.minY;
+    report.minZ = SCRATCH_BOUNDS.minZ;
+    report.maxX = SCRATCH_BOUNDS.maxX;
+    report.maxY = SCRATCH_BOUNDS.maxY;
+    report.maxZ = SCRATCH_BOUNDS.maxZ;
+    report.depthX = depthX;
+    report.depthY = depthY;
+    report.depthZ = depthZ;
+    report.distanceM = Math.hypot(gapX, gapY, gapZ);
+    written++;
+  }
+  return written;
+}

package/src/dev/fpsMeter.ts

@@ -0,0 +1,101 @@
+/** Throttled DOM frame profiler for development builds. */
+
+export interface FpsMeterOptions {
+  parent?: HTMLElement;
+  id?: string;
+  updateIntervalMs?: number;
+  sampleWindow?: number;
+  frameBudgetMs?: number;
+  overBudgetClass?: string;
+}
+
+export class FpsMeter {
+  private readonly element: HTMLElement;
+  private readonly samples: Float32Array;
+  private readonly updateIntervalMs: number;
+  private readonly frameBudgetMs: number;
+  private readonly overBudgetClass: string;
+  private index = 0;
+  private filled = 0;
+  private lastUpdate = 0;
+  private lastText = '';
+  private lastFps = 0;
+  private lastMeanMs = 0;
+  private lastWorstMs = 0;
+
+  constructor(options: FpsMeterOptions = {}) {
+    const sampleWindow = options.sampleWindow ?? 60;
+    if (!Number.isInteger(sampleWindow) || sampleWindow <= 0) {
+      throw new Error(`FpsMeter.sampleWindow must be a positive integer, got ${sampleWindow}`);
+    }
+    this.samples = new Float32Array(sampleWindow);
+    this.updateIntervalMs = options.updateIntervalMs ?? 250;
+    this.frameBudgetMs = options.frameBudgetMs ?? 16.7;
+    this.overBudgetClass = options.overBudgetClass ?? 'over-budget';
+
+    const element = document.createElement('div');
+    element.id = options.id ?? 'fps-meter';
+    (options.parent ?? document.body).append(element);
+    this.element = element;
+  }
+
+  /**
+   * The rate this meter last computed, for a caller that wants the number as well as the panel.
+   *
+   * **Reported from outside**, by a consumer that had to keep its own average beside this one to
+   * say "the preview is below rate, the export is unaffected". A class that owns an element and
+   * refuses to say what it wrote in it makes every caller measure the same thing twice.
+   *
+   * These are what was last *displayed*, so they move at `updateIntervalMs` rather than per frame,
+   * which is the point: a figure that changes sixty times a second is not one a person reads, and
+   * a caller comparing against a budget wants the same smoothed number the panel shows.
+   *
+   * Zero until the first update, which is a real state and not a rate.
+   */
+  get fps(): number {
+    return this.lastFps;
+  }
+
+  /** Mean frame time in milliseconds over the window, as last displayed. See `fps`. */
+  get meanMs(): number {
+    return this.lastMeanMs;
+  }
+
+  /** The slowest frame in the window in milliseconds, as last displayed. See `fps`. */
+  get worstMs(): number {
+    return this.lastWorstMs;
+  }
+
+  /** Call once per rendered frame with duration in seconds. */
+  sample(frameDt: number, nowMs: number): void {
+    this.samples[this.index] = frameDt * 1000;
+    this.index = (this.index + 1) % this.samples.length;
+    if (this.filled < this.samples.length) this.filled++;
+
+    if (nowMs - this.lastUpdate < this.updateIntervalMs) return;
+    this.lastUpdate = nowMs;
+
+    let total = 0;
+    let worst = 0;
+    for (let sample = 0; sample < this.filled; sample++) {
+      const ms = this.samples[sample] ?? 0;
+      total += ms;
+      if (ms > worst) worst = ms;
+    }
+    const meanMs = total / Math.max(this.filled, 1);
+    const fps = meanMs > 0 ? 1000 / meanMs : 0;
+    this.lastFps = fps;
+    this.lastMeanMs = meanMs;
+    this.lastWorstMs = worst;
+    // Throttled and change-gated: the one sanctioned hot-path string/DOM write.
+    const text = `${fps.toFixed(0)} fps · ${meanMs.toFixed(1)} ms · worst ${worst.toFixed(1)} ms`;
+    if (text === this.lastText) return;
+    this.lastText = text;
+    this.element.textContent = text;
+    this.element.classList.toggle(this.overBudgetClass, worst > this.frameBudgetMs * 1.5);
+  }
+
+  dispose(): void {
+    this.element.remove();
+  }
+}