@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/testing/test-game.js

@@ -0,0 +1,92 @@
+/**
+ * `createTestGame` (ws/core-8): `createGame` itself, headless, on the fake GPU, the fake host
+ * and the fixed clock. `step(n)` runs the game's own loop for `n` frames of one fixed step
+ * each, so a test presses an action, steps and asserts state with the engine's real frame
+ * order. Needs a DOM for the overlay (`// @vitest-environment happy-dom`), unless
+ * `overlay: false`, which is `createGame`'s no-DOM mode (ws/core-9) and runs in plain Node.
+ */
+import { DetachedSurface } from '../core/detached-surface.js';
+import { createGame } from '../core/game.js';
+import { createFakeDevice, fakeRendererGpu, installGpuGlobals, } from '../render/fake-gpu.js';
+import { createFakeHost } from './fake-host.js';
+import { createFixedClock } from './fixed-clock.js';
+/**
+ * `createGame` with the testing kit's fakes: a `FakeDevice` as the GPU, a `FakeHost` as the
+ * host (save storage in memory) and a `FixedClock` as `ctx.clock`, on the step of `opts.sim`
+ * (default 1/60 s). The loop is not started; `step(n)` drives it.
+ */
+export async function createTestGame(opts) {
+    const design = { width: opts.design?.width ?? 1920, height: opts.design?.height ?? 1080 };
+    const view = opts.viewport ?? design;
+    const headless = opts.overlay === false;
+    const doc = globalThis.document;
+    if (!headless && !doc) {
+        throw new Error('createTestGame needs a DOM: add `// @vitest-environment happy-dom`, or pass `overlay: false`');
+    }
+    installGpuGlobals();
+    const device = opts.device ?? createFakeDevice();
+    const host = opts.host ?? createFakeHost();
+    const step = opts.sim ? (opts.sim.step ?? 1 / 60) : 1 / 60;
+    // `step × 1000` is what the loop advances the clock by, so each fixed update is one tick.
+    const clock = createFixedClock(step * 1000);
+    const gpu = {
+        ...fakeRendererGpu(device),
+        adapter: {},
+        timestamps: false,
+    };
+    let root;
+    if (!headless) {
+        root = opts.root ?? doc.body.appendChild(doc.createElement('div'));
+        sizeElement(root, () => ({ left: 0, top: 0, width: view.width, height: view.height }));
+    }
+    const ctx = await createGame({ ...opts, root, gpu, host, clock });
+    if (!ctx)
+        throw new Error('createTestGame: createGame returned null');
+    const surface = ctx.surface;
+    if (surface instanceof DetachedSurface) {
+        // The virtual container is the viewport, so pointers letterbox as on a page of that size.
+        surface.resizeContainer(view.width, view.height);
+    }
+    else {
+        // The canvas reports the box the surface gave it, so a touch zone measures as on a page.
+        sizeElement(surface.canvas, () => {
+            const r = surface.rect;
+            return { left: r.x, top: r.y, width: r.width, height: r.height };
+        });
+    }
+    return {
+        ctx,
+        input: ctx.input,
+        host,
+        clock,
+        device,
+        step(n = 1) {
+            for (let i = 0; i < n; i++)
+                ctx.loop.tickOnce(step);
+        },
+        loseDevice(reason, message) {
+            device.loseDevice(reason, message);
+            // The engine's `lost` handler was attached at boot, so it has run once this one resolves.
+            return device.lost.then(() => undefined);
+        },
+    };
+}
+/** Make `el` report `box()` as its layout box (happy-dom computes none). */
+function sizeElement(el, box) {
+    Object.defineProperty(el, 'clientWidth', { configurable: true, get: () => box().width });
+    Object.defineProperty(el, 'clientHeight', { configurable: true, get: () => box().height });
+    el.getBoundingClientRect = () => {
+        const b = box();
+        return {
+            x: b.left,
+            y: b.top,
+            left: b.left,
+            top: b.top,
+            width: b.width,
+            height: b.height,
+            right: b.left + b.width,
+            bottom: b.top + b.height,
+            toJSON: () => b,
+        };
+    };
+}

package/dist/tween/ease.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Easing functions: map linear progress `t` on 0..1 to eased progress. Every entry of `ease`
+ * is 0 at 0 and 1 at 1; `back`, `elastic` and `cubicBezier` may leave 0..1 in between.
+ *
+ * `ease.spring(stiffness, damping)` is not a function of `t`: a spring has no duration, so it
+ * describes a `SpringEase` the tween engine simulates until it settles (see `tween.ts`).
+ */
+/** Maps linear progress 0..1 to eased progress. */
+export type Ease = (t: number) => number;
+/**
+ * A duration-free spring toward the target (unit mass): `a = stiffness · (1 − x) − damping · v`.
+ * A tween given one ignores its `seconds`, `loops` and `yoyo` and ends when it has settled.
+ */
+export interface SpringEase {
+    readonly kind: 'spring';
+    readonly stiffness: number;
+    readonly damping: number;
+}
+export declare function isSpring(e: Ease | SpringEase | undefined): e is SpringEase;
+/** `n` equal steps: 0 until the first step, 1 at `t = 1`. */
+declare function steps(n: number): Ease;
+/**
+ * The CSS `cubic-bezier(x1, y1, x2, y2)` timing function: the curve from (0,0) through the two
+ * control points to (1,1); `x` is solved for `t` by Newton iteration with a bisection fallback.
+ */
+declare function cubicBezier(x1: number, y1: number, x2: number, y2: number): Ease;
+/**
+ * A duration-free spring (unit mass). Critical damping is `2 · √stiffness`; less overshoots.
+ * Default `170, 22`, which settles in about half a second with a slight overshoot.
+ */
+declare function spring(stiffness?: number, damping?: number): SpringEase;
+/** The easing table. */
+export declare const ease: {
+    readonly linear: Ease;
+    readonly smoothstep: Ease;
+    readonly quadIn: Ease;
+    readonly quadOut: Ease;
+    readonly quadInOut: Ease;
+    readonly cubicIn: Ease;
+    readonly cubicOut: Ease;
+    readonly cubicInOut: Ease;
+    readonly quartIn: Ease;
+    readonly quartOut: Ease;
+    readonly quartInOut: Ease;
+    readonly quintIn: Ease;
+    readonly quintOut: Ease;
+    readonly quintInOut: Ease;
+    readonly sineIn: Ease;
+    readonly sineOut: Ease;
+    readonly sineInOut: Ease;
+    readonly expoIn: Ease;
+    readonly expoOut: Ease;
+    readonly expoInOut: Ease;
+    readonly circIn: Ease;
+    readonly circOut: Ease;
+    readonly circInOut: Ease;
+    readonly backIn: Ease;
+    readonly backOut: Ease;
+    readonly backInOut: Ease;
+    readonly elasticIn: Ease;
+    readonly elasticOut: Ease;
+    readonly elasticInOut: Ease;
+    readonly bounceIn: Ease;
+    readonly bounceOut: Ease;
+    readonly bounceInOut: Ease;
+    readonly steps: typeof steps;
+    readonly cubicBezier: typeof cubicBezier;
+    readonly spring: typeof spring;
+};
+/**
+ * Advance a spring state by `dt` seconds: `s[0]` is the position (0 at the start, 1 at the
+ * target), `s[1]` the velocity. Semi-implicit Euler in substeps of at most `SPRING_STEP` so a
+ * stiff spring stays stable on a slow frame. Returns true once the spring has settled, with
+ * the position snapped to 1 and the velocity to 0.
+ */
+export declare function stepSpring(s: Float64Array, e: SpringEase, dt: number): boolean;
+export {};

package/dist/tween/ease.js

@@ -0,0 +1,192 @@
+/**
+ * Easing functions: map linear progress `t` on 0..1 to eased progress. Every entry of `ease`
+ * is 0 at 0 and 1 at 1; `back`, `elastic` and `cubicBezier` may leave 0..1 in between.
+ *
+ * `ease.spring(stiffness, damping)` is not a function of `t`: a spring has no duration, so it
+ * describes a `SpringEase` the tween engine simulates until it settles (see `tween.ts`).
+ */
+export function isSpring(e) {
+    return typeof e === 'object' && e !== null && e.kind === 'spring';
+}
+const PI = Math.PI;
+const HALF_PI = PI / 2;
+const C1 = 1.70158;
+const C2 = C1 * 1.525;
+const C3 = C1 + 1;
+const C4 = (2 * PI) / 3;
+const C5 = (2 * PI) / 4.5;
+const N1 = 7.5625;
+const D1 = 2.75;
+const linear = (t) => t;
+/** `t² (3 − 2t)`: the smoothstep polynomial, the default of `PostStack.blendTo`. */
+const smoothstep = (t) => t * t * (3 - 2 * t);
+const quadIn = (t) => t * t;
+const quadOut = (t) => 1 - (1 - t) * (1 - t);
+const quadInOut = (t) => (t < 0.5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2);
+const cubicIn = (t) => t * t * t;
+const cubicOut = (t) => 1 - (1 - t) ** 3;
+const cubicInOut = (t) => (t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2);
+const quartIn = (t) => t * t * t * t;
+const quartOut = (t) => 1 - (1 - t) ** 4;
+const quartInOut = (t) => (t < 0.5 ? 8 * t * t * t * t : 1 - (-2 * t + 2) ** 4 / 2);
+const quintIn = (t) => t * t * t * t * t;
+const quintOut = (t) => 1 - (1 - t) ** 5;
+const quintInOut = (t) => (t < 0.5 ? 16 * t ** 5 : 1 - (-2 * t + 2) ** 5 / 2);
+const sineIn = (t) => 1 - Math.cos(t * HALF_PI);
+const sineOut = (t) => Math.sin(t * HALF_PI);
+const sineInOut = (t) => -(Math.cos(PI * t) - 1) / 2;
+const expoIn = (t) => (t <= 0 ? 0 : 2 ** (10 * t - 10));
+const expoOut = (t) => (t >= 1 ? 1 : 1 - 2 ** (-10 * t));
+const expoInOut = (t) => t <= 0 ? 0 : t >= 1 ? 1 : t < 0.5 ? 2 ** (20 * t - 10) / 2 : (2 - 2 ** (-20 * t + 10)) / 2;
+const circIn = (t) => 1 - Math.sqrt(1 - t * t);
+const circOut = (t) => Math.sqrt(1 - (t - 1) * (t - 1));
+const circInOut = (t) => t < 0.5 ? (1 - Math.sqrt(1 - (2 * t) ** 2)) / 2 : (Math.sqrt(1 - (-2 * t + 2) ** 2) + 1) / 2;
+const backIn = (t) => C3 * t * t * t - C1 * t * t;
+const backOut = (t) => 1 + C3 * (t - 1) ** 3 + C1 * (t - 1) ** 2;
+const backInOut = (t) => t < 0.5
+    ? ((2 * t) ** 2 * ((C2 + 1) * 2 * t - C2)) / 2
+    : ((2 * t - 2) ** 2 * ((C2 + 1) * (t * 2 - 2) + C2) + 2) / 2;
+const elasticIn = (t) => t <= 0 ? 0 : t >= 1 ? 1 : -(2 ** (10 * t - 10)) * Math.sin((t * 10 - 10.75) * C4);
+const elasticOut = (t) => t <= 0 ? 0 : t >= 1 ? 1 : 2 ** (-10 * t) * Math.sin((t * 10 - 0.75) * C4) + 1;
+const elasticInOut = (t) => t <= 0
+    ? 0
+    : t >= 1
+        ? 1
+        : t < 0.5
+            ? -(2 ** (20 * t - 10) * Math.sin((20 * t - 11.125) * C5)) / 2
+            : (2 ** (-20 * t + 10) * Math.sin((20 * t - 11.125) * C5)) / 2 + 1;
+const bounceOut = (t) => {
+    if (t < 1 / D1)
+        return N1 * t * t;
+    if (t < 2 / D1) {
+        const u = t - 1.5 / D1;
+        return N1 * u * u + 0.75;
+    }
+    if (t < 2.5 / D1) {
+        const u = t - 2.25 / D1;
+        return N1 * u * u + 0.9375;
+    }
+    const u = t - 2.625 / D1;
+    return N1 * u * u + 0.984375;
+};
+const bounceIn = (t) => 1 - bounceOut(1 - t);
+const bounceInOut = (t) => t < 0.5 ? (1 - bounceOut(1 - 2 * t)) / 2 : (1 + bounceOut(2 * t - 1)) / 2;
+/** `n` equal steps: 0 until the first step, 1 at `t = 1`. */
+function steps(n) {
+    const k = Math.max(1, Math.floor(n));
+    return (t) => (t >= 1 ? 1 : Math.floor(t * k) / k);
+}
+/**
+ * The CSS `cubic-bezier(x1, y1, x2, y2)` timing function: the curve from (0,0) through the two
+ * control points to (1,1); `x` is solved for `t` by Newton iteration with a bisection fallback.
+ */
+function cubicBezier(x1, y1, x2, y2) {
+    const ax = 1 - 3 * x2 + 3 * x1;
+    const bx = 3 * x2 - 6 * x1;
+    const cx = 3 * x1;
+    const ay = 1 - 3 * y2 + 3 * y1;
+    const by = 3 * y2 - 6 * y1;
+    const cy = 3 * y1;
+    const sampleX = (u) => ((ax * u + bx) * u + cx) * u;
+    const sampleY = (u) => ((ay * u + by) * u + cy) * u;
+    const slopeX = (u) => (3 * ax * u + 2 * bx) * u + cx;
+    return (t) => {
+        if (t <= 0)
+            return 0;
+        if (t >= 1)
+            return 1;
+        let u = t;
+        for (let i = 0; i < 8; i++) {
+            const x = sampleX(u) - t;
+            if (Math.abs(x) < 1e-6)
+                return sampleY(u);
+            const d = slopeX(u);
+            if (Math.abs(d) < 1e-6)
+                break;
+            u -= x / d;
+        }
+        let lo = 0;
+        let hi = 1;
+        u = t;
+        for (let i = 0; i < 32 && hi - lo > 1e-7; i++) {
+            if (sampleX(u) < t)
+                lo = u;
+            else
+                hi = u;
+            u = (lo + hi) / 2;
+        }
+        return sampleY(u);
+    };
+}
+/**
+ * A duration-free spring (unit mass). Critical damping is `2 · √stiffness`; less overshoots.
+ * Default `170, 22`, which settles in about half a second with a slight overshoot.
+ */
+function spring(stiffness = 170, damping = 22) {
+    return { kind: 'spring', stiffness, damping };
+}
+/** The easing table. */
+export const ease = {
+    linear,
+    smoothstep,
+    quadIn,
+    quadOut,
+    quadInOut,
+    cubicIn,
+    cubicOut,
+    cubicInOut,
+    quartIn,
+    quartOut,
+    quartInOut,
+    quintIn,
+    quintOut,
+    quintInOut,
+    sineIn,
+    sineOut,
+    sineInOut,
+    expoIn,
+    expoOut,
+    expoInOut,
+    circIn,
+    circOut,
+    circInOut,
+    backIn,
+    backOut,
+    backInOut,
+    elasticIn,
+    elasticOut,
+    elasticInOut,
+    bounceIn,
+    bounceOut,
+    bounceInOut,
+    steps,
+    cubicBezier,
+    spring,
+};
+/**
+ * Advance a spring state by `dt` seconds: `s[0]` is the position (0 at the start, 1 at the
+ * target), `s[1]` the velocity. Semi-implicit Euler in substeps of at most `SPRING_STEP` so a
+ * stiff spring stays stable on a slow frame. Returns true once the spring has settled, with
+ * the position snapped to 1 and the velocity to 0.
+ */
+export function stepSpring(s, e, dt) {
+    let x = s[0];
+    let v = s[1];
+    let left = dt;
+    while (left > 0) {
+        const h = Math.min(left, SPRING_STEP);
+        left -= h;
+        v += (e.stiffness * (1 - x) - e.damping * v) * h;
+        x += v * h;
+    }
+    if (Math.abs(1 - x) < SPRING_EPSILON && Math.abs(v) < SPRING_EPSILON) {
+        s[0] = 1;
+        s[1] = 0;
+        return true;
+    }
+    s[0] = x;
+    s[1] = v;
+    return false;
+}
+const SPRING_STEP = 1 / 240;
+const SPRING_EPSILON = 1e-3;

package/dist/tween/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@thunderclap-engine/engine/tween`: numbers over time. An easing table, property and value tweens,
+ * sequences and parallel groups, loops, yoyo, delays and springs, ticked by `Tweens.update(dt)`
+ * with no allocation after setup. See README.md.
+ */
+export { type Ease, ease, type SpringEase } from './ease.js';
+export { createTweens, Tweens } from './timeline.js';
+export type { Tween, TweenOptions, TweenProps } from './tween.js';

package/dist/tween/index.js

@@ -0,0 +1,7 @@
+/**
+ * `@thunderclap-engine/engine/tween`: numbers over time. An easing table, property and value tweens,
+ * sequences and parallel groups, loops, yoyo, delays and springs, ticked by `Tweens.update(dt)`
+ * with no allocation after setup. See README.md.
+ */
+export { ease } from './ease.js';
+export { createTweens, Tweens } from './timeline.js';

package/dist/tween/timeline.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Groups and the manager. `SequenceTween` runs its children one after another, carrying the
+ * leftover of a child's last step into the next; `ParallelTween` advances all of them and ends
+ * with the last. Both are tweens themselves (delay, loops, yoyo, callbacks), so they nest.
+ *
+ * `Tweens` holds the root tweens and ticks them with `update(dt)`. A tween that completes or is
+ * killed, even inside the update that is running, is compacted out at the end of that update;
+ * tweens created during an update start on the next one.
+ */
+import { type Tween, TweenBase, type TweenOptions, type TweenOwner, type TweenProps } from './tween.js';
+/** Base of the two groups: takes the children out of the manager and drives them itself. */
+declare abstract class GroupTween extends TweenBase {
+    protected readonly children: TweenBase[];
+    constructor(children: Tween[], opts: TweenOptions);
+    /** @internal Kill the children whose target is `target`. */
+    killTarget(target: object): void;
+    /** The length of one iteration, from the children's totals. */
+    protected abstract childDuration(): number;
+    /** Seconds of this iteration consumed, from the children. */
+    protected abstract childConsumed(): number;
+    protected resetChildren(): void;
+    protected onIteration(): void;
+    protected capture(): void;
+    protected applyAt(): void;
+    /** Bookkeeping after the children moved: progress, callbacks, loops, completion. */
+    protected settle(leftover: number, allDone: boolean): number;
+}
+/** @internal */
+export declare function killTargetIn(t: TweenBase, target: object): void;
+export declare class SequenceTween extends GroupTween {
+    protected childDuration(): number;
+    protected childConsumed(): number;
+    protected run(local: number): number;
+}
+export declare class ParallelTween extends GroupTween {
+    protected childDuration(): number;
+    protected childConsumed(): number;
+    protected run(local: number): number;
+}
+/** Creates and ticks tweens. One per game is plenty; call `update(dt)` from your frame hook. */
+export declare class Tweens implements TweenOwner {
+    private readonly list;
+    private updating;
+    /** Tweens that have neither completed nor been killed (a group counts once). */
+    get active(): number;
+    /** Advance every root tween by `dt` seconds. Negative or NaN counts as 0. */
+    update(dt: number): void;
+    /**
+     * Animate number fields of `target` to the values in `props` (`'x'`, `'position.0'`,
+     * `'style.opacity'`; typed-array indices work) over `seconds`. Start values are read when
+     * the tween starts (after its delay).
+     */
+    to(target: object, props: TweenProps, seconds: number, opts?: TweenOptions): Tween;
+    /** Animate one number, calling `onUpdate(value, tween)` every step. */
+    value(from: number, to: number, seconds: number, onUpdate: (value: number, tween: Tween) => void, opts?: TweenOptions): Tween;
+    /** Nothing for `seconds`: a gap in a sequence, or a timer with `then`. */
+    delay(seconds: number, opts?: TweenOptions): Tween;
+    /**
+     * Run tweens one after another, carrying leftover time from one into the next. A
+     * `TweenOptions` object as the last argument applies to the whole (delay, loops, yoyo, …).
+     */
+    sequence(...tweens: (Tween | TweenOptions)[]): Tween;
+    /** Run tweens together; ends when the last one has. Options as for `sequence`. */
+    parallel(...tweens: (Tween | TweenOptions)[]): Tween;
+    /** Kill every property tween on `target`, inside groups too. */
+    kill(target: object): void;
+    /** Kill every tween. */
+    killAll(): void;
+    /** @internal */
+    readd(t: TweenBase): void;
+    private add;
+    /** A group took its children out of the root list. */
+    private addGroup;
+    private compact;
+}
+/** A new tween manager. */
+export declare function createTweens(): Tweens;
+export {};