@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/tween/timeline.js

@@ -0,0 +1,269 @@
+/**
+ * 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 { DelayTween, PropertyTween, TweenBase, ValueTween, } from './tween.js';
+/** Base of the two groups: takes the children out of the manager and drives them itself. */
+class GroupTween extends TweenBase {
+    children;
+    constructor(children, opts) {
+        super(0, opts);
+        this.children = children.map((c) => {
+            if (!(c instanceof TweenBase))
+                throw new Error('tween: not a tween of this module');
+            if (c.grouped)
+                throw new Error('tween: a tween can join only one group');
+            c.grouped = true;
+            c.owner = null;
+            c.listed = false;
+            return c;
+        });
+        this.duration = this.childDuration();
+    }
+    /** @internal Kill the children whose target is `target`. */
+    killTarget(target) {
+        for (const c of this.children)
+            killTargetIn(c, target);
+    }
+    resetChildren() {
+        for (const c of this.children)
+            c.reset(true);
+    }
+    onIteration() {
+        this.resetChildren();
+        this.capture();
+    }
+    capture() {
+        const rev = this.reversed;
+        for (const c of this.children)
+            c.parentReversed = rev;
+    }
+    applyAt() { }
+    /** Bookkeeping after the children moved: progress, callbacks, loops, completion. */
+    settle(leftover, allDone) {
+        const consumed = this.childConsumed();
+        this.elapsed = Number.isFinite(consumed) ? consumed : this.elapsed;
+        this.progress = this.duration > 0 ? Math.min(1, this.elapsed / this.duration) : 1;
+        if (allDone) {
+            this.elapsed = this.duration;
+            this.progress = 1;
+        }
+        this.onUpdate?.(this);
+        if (this.killed)
+            return 0;
+        if (!allDone)
+            return 0;
+        if (this.canLoop()) {
+            this.nextIteration();
+            return leftover > 0 ? this.run(leftover) : 0;
+        }
+        this.finish();
+        return leftover;
+    }
+}
+/** @internal */
+export function killTargetIn(t, target) {
+    if (t instanceof PropertyTween) {
+        if (t.target === target)
+            t.kill();
+    }
+    else if (t instanceof GroupTween) {
+        t.killTarget(target);
+    }
+}
+export class SequenceTween extends GroupTween {
+    childDuration() {
+        let s = 0;
+        for (const c of this.children)
+            s += c.total;
+        return s;
+    }
+    childConsumed() {
+        let s = 0;
+        for (const c of this.children)
+            s += c.consumed;
+        return s;
+    }
+    run(local) {
+        const kids = this.children;
+        const n = kids.length;
+        const rev = this.reversed;
+        let i = 0;
+        while (local > 0) {
+            while (i < n && kids[rev ? n - 1 - i : i].done)
+                i++;
+            if (i === n)
+                break;
+            const child = kids[rev ? n - 1 - i : i];
+            const rest = child.advance(local);
+            if (this.killed)
+                return 0;
+            if (!child.done)
+                break; // still running: paused, held, or it used the time
+            local = rest;
+        }
+        let allDone = true;
+        for (let j = 0; j < n; j++)
+            if (!kids[j].done)
+                allDone = false;
+        return this.settle(allDone ? local : 0, allDone);
+    }
+}
+export class ParallelTween extends GroupTween {
+    childDuration() {
+        let s = 0;
+        for (const c of this.children)
+            s = Math.max(s, c.total);
+        return s;
+    }
+    childConsumed() {
+        let s = 0;
+        for (const c of this.children)
+            s = Math.max(s, c.consumed);
+        return s;
+    }
+    run(local) {
+        const kids = this.children;
+        let allDone = true;
+        let leftover = local;
+        for (let i = 0; i < kids.length; i++) {
+            const c = kids[i];
+            const rest = c.advance(local);
+            if (this.killed)
+                return 0;
+            if (!c.done)
+                allDone = false;
+            if (rest < leftover)
+                leftover = rest;
+        }
+        return this.settle(allDone ? leftover : 0, allDone);
+    }
+}
+/** Creates and ticks tweens. One per game is plenty; call `update(dt)` from your frame hook. */
+export class Tweens {
+    list = [];
+    updating = false;
+    /** Tweens that have neither completed nor been killed (a group counts once). */
+    get active() {
+        let n = 0;
+        const list = this.list;
+        for (let i = 0; i < list.length; i++)
+            if (!list[i].done)
+                n++;
+        return n;
+    }
+    /** Advance every root tween by `dt` seconds. Negative or NaN counts as 0. */
+    update(dt) {
+        if (this.updating)
+            throw new Error('tween: update called from inside update');
+        this.updating = true;
+        const list = this.list;
+        const n = list.length;
+        // NaN and negative dt both tick by 0.
+        // biome-ignore lint/complexity/useMathMinMax: Math.max(NaN, 0) is NaN.
+        const step = dt > 0 ? dt : 0;
+        try {
+            for (let i = 0; i < n; i++) {
+                const t = list[i];
+                if (!t.grouped)
+                    t.advance(step);
+            }
+        }
+        finally {
+            this.updating = false;
+        }
+        this.compact();
+    }
+    /**
+     * 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, props, seconds, opts = {}) {
+        return this.add(new PropertyTween(target, props, seconds, opts));
+    }
+    /** Animate one number, calling `onUpdate(value, tween)` every step. */
+    value(from, to, seconds, onUpdate, opts = {}) {
+        return this.add(new ValueTween(from, to, seconds, onUpdate, opts));
+    }
+    /** Nothing for `seconds`: a gap in a sequence, or a timer with `then`. */
+    delay(seconds, opts = {}) {
+        return this.add(new DelayTween(seconds, opts));
+    }
+    /**
+     * 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) {
+        const [kids, opts] = splitArgs(tweens);
+        return this.addGroup(new SequenceTween(kids, opts));
+    }
+    /** Run tweens together; ends when the last one has. Options as for `sequence`. */
+    parallel(...tweens) {
+        const [kids, opts] = splitArgs(tweens);
+        return this.addGroup(new ParallelTween(kids, opts));
+    }
+    /** Kill every property tween on `target`, inside groups too. */
+    kill(target) {
+        const list = this.list;
+        for (let i = 0; i < list.length; i++)
+            killTargetIn(list[i], target);
+        if (!this.updating)
+            this.compact();
+    }
+    /** Kill every tween. */
+    killAll() {
+        const list = this.list;
+        for (let i = 0; i < list.length; i++)
+            list[i].kill();
+        if (!this.updating)
+            this.compact();
+    }
+    /** @internal */
+    readd(t) {
+        if (t.listed || t.grouped)
+            return;
+        t.listed = true;
+        this.list.push(t);
+    }
+    add(t) {
+        t.owner = this;
+        t.listed = true;
+        this.list.push(t);
+        return t;
+    }
+    /** A group took its children out of the root list. */
+    addGroup(t) {
+        if (!this.updating)
+            this.compact();
+        return this.add(t);
+    }
+    compact() {
+        const list = this.list;
+        let w = 0;
+        for (let i = 0; i < list.length; i++) {
+            const t = list[i];
+            if (t.done || t.grouped)
+                t.listed = false;
+            else
+                list[w++] = t;
+        }
+        list.length = w;
+    }
+}
+function splitArgs(args) {
+    const last = args[args.length - 1];
+    if (last !== undefined && !(last instanceof TweenBase)) {
+        return [args.slice(0, -1), last];
+    }
+    return [args, {}];
+}
+/** A new tween manager. */
+export function createTweens() {
+    return new Tweens();
+}

package/dist/tween/tween.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Tweens: the `Tween` handle every kind shares, and the three leaf kinds (`PropertyTween`,
+ * `ValueTween`, `DelayTween`). `timeline.ts` adds the groups and the `Tweens` manager.
+ *
+ * A tween is driven through `advance(dt)`, which returns the part of `dt` it did not use (0
+ * while running; the overflow once it finishes), so a sequence carries leftover time into the
+ * next child and a loop into the next iteration. After construction nothing here allocates per
+ * update: property paths are resolved to holders and keys up front, start values are captured
+ * into typed arrays, and callbacks are stored in arrays that only grow in `then`.
+ */
+import { type Ease, type SpringEase } from './ease.js';
+export interface TweenOptions {
+    /** Easing (default `ease.linear`), or `ease.spring(...)` for a duration-free spring. */
+    ease?: Ease | SpringEase;
+    /** Seconds to wait before the first iteration starts. Default 0. */
+    delay?: number;
+    /** Extra iterations after the first: `0` (default) plays once, `2` three times, `-1` forever. */
+    loops?: number;
+    /** Alternate direction on every other iteration (needs `loops`). Default false. */
+    yoyo?: boolean;
+    /** Called once, when the first iteration starts (after `delay`; start values are read then). */
+    onStart?: (tween: Tween) => void;
+    /** Called after every update that moved the tween, including the final one. */
+    onUpdate?: (tween: Tween) => void;
+    /** Called once, when the last iteration ends. Not called on `kill`. */
+    onComplete?: (tween: Tween) => void;
+    /** Multiplies `dt`. Default 1; `0` holds. Settable later through `tween.timeScale`. */
+    timeScale?: number;
+}
+/** The handle every tween kind returns. Read-only fields update on every `Tweens.update`. */
+export interface Tween {
+    /** Linear position of the current iteration, 0..1 (a spring's position, which may overshoot). */
+    readonly progress: number;
+    /** Seconds into the current iteration (excluding the delay). */
+    readonly elapsed: number;
+    /** Seconds one iteration lasts (`Infinity` for a spring). */
+    readonly duration: number;
+    /** True once the last iteration has ended. */
+    readonly complete: boolean;
+    /** True after `kill()`: dropped from its manager or skipped by its group; never completes. */
+    readonly killed: boolean;
+    readonly paused: boolean;
+    /** Multiplies `dt`; settable. */
+    timeScale: number;
+    /** Hold: `update` leaves the tween where it is (a sequence waits on a paused child). */
+    pause(): void;
+    resume(): void;
+    /** Stop and drop: no further callbacks, `complete` stays false. */
+    kill(): void;
+    /** Back to the start (delay included); a finished or killed root tween rejoins its manager. */
+    restart(): void;
+    /** Run `fn` when the tween completes (at once if it already has). Returns the tween. */
+    then(fn: () => void): Tween;
+    /** Resolves when the tween completes. A killed tween's promise never settles. */
+    promise(): Promise<void>;
+}
+/** Internal hooks a `Tweens` manager uses on a root tween. */
+export interface TweenOwner {
+    /** Re-register a root tween that finished or was killed. */
+    readd(t: TweenBase): void;
+}
+export declare abstract class TweenBase implements Tween {
+    progress: number;
+    elapsed: number;
+    duration: number;
+    complete: boolean;
+    killed: boolean;
+    paused: boolean;
+    timeScale: number;
+    /** @internal The manager this tween registered with (roots only). */
+    owner: TweenOwner | null;
+    /** @internal True while the owner's list holds this tween. */
+    listed: boolean;
+    /** @internal True once a group took the tween; it then never talks to the manager. */
+    grouped: boolean;
+    /** @internal Direction imposed by the parent (yoyo on a group). */
+    parentReversed: boolean;
+    protected readonly ease: Ease | null;
+    protected readonly spring: SpringEase | null;
+    protected readonly delay: number;
+    protected readonly loops: number;
+    protected readonly yoyo: boolean;
+    protected readonly onStart: ((t: Tween) => void) | undefined;
+    protected readonly onUpdate: ((t: Tween) => void) | undefined;
+    protected readonly onComplete: ((t: Tween) => void) | undefined;
+    protected delayLeft: number;
+    protected iteration: number;
+    protected started: boolean;
+    /** Start values were read once; a group's loop replays them instead of reading again. */
+    private captured;
+    private keepStart;
+    private thenFns;
+    /** Spring state `[position, velocity]`, springs only. */
+    private readonly springState;
+    constructor(seconds: number, opts: TweenOptions);
+    pause(): void;
+    resume(): void;
+    kill(): void;
+    restart(): void;
+    then(fn: () => void): Tween;
+    promise(): Promise<void>;
+    /** @internal True once the tween no longer moves. */
+    get done(): boolean;
+    /** @internal Seconds the whole tween lasts: delay plus every iteration; `Infinity` if it never ends. */
+    get total(): number;
+    /** @internal Seconds consumed so far, delay and finished iterations included. */
+    get consumed(): number;
+    /**
+     * @internal Back to the initial state without touching the manager. With `keepStart` (a
+     * group looping) the start values read on the first run are kept, so the motion replays.
+     */
+    reset(keepStart?: boolean): void;
+    /** @internal Groups reset their children here. */
+    protected resetChildren(): void;
+    /** @internal The direction of the current iteration: true runs 1 → 0. */
+    protected get reversed(): boolean;
+    /**
+     * @internal Move forward by `dt` seconds (unscaled). Returns the part of `dt` left unused:
+     * 0 while running or paused, the overflow when the tween finishes, all of it when it already
+     * had.
+     */
+    advance(dt: number): number;
+    /** @internal Move by `local` (scaled) seconds past the delay; return the unused part. */
+    protected run(local: number): number;
+    private runSpring;
+    private runTimed;
+    /** @internal Whether another iteration follows the current one. */
+    protected canLoop(): boolean;
+    /** @internal Begin the next iteration. */
+    protected nextIteration(): void;
+    /** @internal A loop boundary was crossed (groups restart their children). */
+    protected onIteration(): void;
+    /** @internal Mark complete and fire the completion callbacks. */
+    protected finish(): void;
+    /** @internal Read start values; runs once per `restart`, after the delay. */
+    protected abstract capture(): void;
+    /** @internal Write the eased position `k` (0..1, may overshoot) to the animated values. */
+    protected abstract applyAt(k: number): void;
+}
+/** Nested number fields by dotted path: `'x'`, `'position.0'`, `'style.opacity'`. */
+export type TweenProps = Record<string, number>;
+/** Animates number fields of an object (nested paths and typed-array indices allowed). */
+export declare class PropertyTween extends TweenBase {
+    readonly target: object;
+    private readonly holders;
+    private readonly keys;
+    private readonly from;
+    private readonly to;
+    constructor(target: object, props: TweenProps, seconds: number, opts: TweenOptions);
+    protected capture(): void;
+    protected applyAt(k: number): void;
+}
+/** Animates one number from `from` to `to`, reporting it through `onUpdate(value, tween)`. */
+export declare class ValueTween extends TweenBase {
+    /** The value from the last update. */
+    value: number;
+    private readonly from;
+    private readonly to;
+    private readonly report;
+    constructor(from: number, to: number, seconds: number, onUpdate: (value: number, tween: Tween) => void, opts: TweenOptions);
+    protected capture(): void;
+    protected applyAt(k: number): void;
+}
+/** Does nothing for `seconds`; a pause inside a sequence. */
+export declare class DelayTween extends TweenBase {
+    protected capture(): void;
+    protected applyAt(): void;
+}