@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/tween/tween.js

@@ -0,0 +1,320 @@
+/**
+ * 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 { isSpring, stepSpring } from './ease.js';
+export class TweenBase {
+    progress = 0;
+    elapsed = 0;
+    duration;
+    complete = false;
+    killed = false;
+    paused = false;
+    timeScale;
+    /** @internal The manager this tween registered with (roots only). */
+    owner = null;
+    /** @internal True while the owner's list holds this tween. */
+    listed = false;
+    /** @internal True once a group took the tween; it then never talks to the manager. */
+    grouped = false;
+    /** @internal Direction imposed by the parent (yoyo on a group). */
+    parentReversed = false;
+    ease;
+    spring;
+    delay;
+    loops;
+    yoyo;
+    onStart;
+    onUpdate;
+    onComplete;
+    delayLeft;
+    iteration = 0;
+    started = false;
+    /** Start values were read once; a group's loop replays them instead of reading again. */
+    captured = false;
+    keepStart = false;
+    thenFns = null;
+    /** Spring state `[position, velocity]`, springs only. */
+    springState;
+    constructor(seconds, opts) {
+        const e = opts.ease;
+        if (isSpring(e)) {
+            this.spring = e;
+            this.ease = null;
+            this.duration = Number.POSITIVE_INFINITY;
+            this.springState = new Float64Array(2);
+            this.loops = 0;
+            this.yoyo = false;
+        }
+        else {
+            this.spring = null;
+            this.ease = e ?? null;
+            this.duration = Math.max(0, Number.isFinite(seconds) ? seconds : 0);
+            this.springState = null;
+            this.loops = opts.loops ?? 0;
+            this.yoyo = opts.yoyo ?? false;
+        }
+        this.delay = Math.max(0, opts.delay ?? 0);
+        this.delayLeft = this.delay;
+        this.timeScale = opts.timeScale ?? 1;
+        this.onStart = opts.onStart;
+        this.onUpdate = opts.onUpdate;
+        this.onComplete = opts.onComplete;
+    }
+    pause() {
+        this.paused = true;
+    }
+    resume() {
+        this.paused = false;
+    }
+    kill() {
+        this.killed = true;
+    }
+    restart() {
+        this.reset();
+        if (!this.grouped && this.owner && !this.listed)
+            this.owner.readd(this);
+    }
+    // biome-ignore lint/suspicious/noThenProperty: intentionally thenable, so `await tween` works too.
+    then(fn) {
+        if (this.complete) {
+            fn();
+            return this;
+        }
+        if (!this.thenFns)
+            this.thenFns = [];
+        this.thenFns.push(fn);
+        return this;
+    }
+    promise() {
+        return new Promise((resolve) => {
+            this.then(resolve);
+        });
+    }
+    /** @internal True once the tween no longer moves. */
+    get done() {
+        return this.complete || this.killed;
+    }
+    /** @internal Seconds the whole tween lasts: delay plus every iteration; `Infinity` if it never ends. */
+    get total() {
+        return this.loops < 0
+            ? Number.POSITIVE_INFINITY
+            : this.delay + this.duration * (this.loops + 1);
+    }
+    /** @internal Seconds consumed so far, delay and finished iterations included. */
+    get consumed() {
+        if (this.done)
+            return this.total;
+        return this.delay - this.delayLeft + this.duration * this.iteration + this.elapsed;
+    }
+    /**
+     * @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 = false) {
+        this.keepStart = keepStart && this.captured;
+        this.progress = 0;
+        this.elapsed = 0;
+        this.complete = false;
+        this.killed = false;
+        this.delayLeft = this.delay;
+        this.iteration = 0;
+        this.started = false;
+        if (this.springState) {
+            this.springState[0] = 0;
+            this.springState[1] = 0;
+        }
+        this.resetChildren();
+    }
+    /** @internal Groups reset their children here. */
+    resetChildren() { }
+    /** @internal The direction of the current iteration: true runs 1 → 0. */
+    get reversed() {
+        return this.parentReversed !== (this.yoyo && (this.iteration & 1) === 1);
+    }
+    /**
+     * @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) {
+        if (this.done)
+            return dt;
+        if (this.paused || dt <= 0)
+            return 0;
+        const scale = this.timeScale;
+        if (scale <= 0)
+            return 0;
+        let local = dt * scale;
+        if (this.delayLeft > 0) {
+            if (local < this.delayLeft) {
+                this.delayLeft -= local;
+                return 0;
+            }
+            local -= this.delayLeft;
+            this.delayLeft = 0;
+        }
+        if (!this.started) {
+            this.started = true;
+            if (!this.keepStart) {
+                this.capture();
+                this.captured = true;
+            }
+            this.onStart?.(this);
+            if (this.killed)
+                return 0;
+        }
+        return this.run(local) / scale;
+    }
+    /** @internal Move by `local` (scaled) seconds past the delay; return the unused part. */
+    run(local) {
+        if (this.spring)
+            return this.runSpring(local);
+        return this.runTimed(local);
+    }
+    runSpring(local) {
+        const s = this.springState;
+        const settled = stepSpring(s, this.spring, local);
+        this.elapsed += local;
+        this.progress = s[0];
+        this.applyAt(this.progress);
+        this.onUpdate?.(this);
+        if (settled && !this.killed)
+            this.finish();
+        return 0;
+    }
+    runTimed(local) {
+        const duration = this.duration;
+        let t = this.elapsed + local;
+        // Each loop boundary crossed applies its end value, so callbacks see every extreme.
+        while (t >= duration && this.canLoop()) {
+            this.applyAt(this.reversed ? 0 : 1);
+            this.nextIteration();
+            t -= duration;
+            if (duration === 0) {
+                // A zero-length looping tween would spin forever; one boundary is enough.
+                t = 0;
+                break;
+            }
+        }
+        let leftover = 0;
+        if (t >= duration) {
+            leftover = t - duration;
+            t = duration;
+        }
+        this.elapsed = t;
+        this.progress = duration > 0 ? t / duration : 1;
+        const p = this.reversed ? 1 - this.progress : this.progress;
+        // The endpoints bypass the ease: every ease is 0 at 0 and 1 at 1 by contract, but floating
+        // point may land at 0.9999999999999999, and the end value must be exactly the target.
+        this.applyAt(this.ease && p > 0 && p < 1 ? this.ease(p) : p);
+        this.onUpdate?.(this);
+        if (this.killed)
+            return 0;
+        if (t >= duration) {
+            this.finish();
+            return leftover;
+        }
+        return 0;
+    }
+    /** @internal Whether another iteration follows the current one. */
+    canLoop() {
+        return this.loops < 0 || this.iteration < this.loops;
+    }
+    /** @internal Begin the next iteration. */
+    nextIteration() {
+        this.iteration++;
+        this.elapsed = 0;
+        this.progress = 0;
+        this.onIteration();
+    }
+    /** @internal A loop boundary was crossed (groups restart their children). */
+    onIteration() { }
+    /** @internal Mark complete and fire the completion callbacks. */
+    finish() {
+        this.complete = true;
+        this.onComplete?.(this);
+        const fns = this.thenFns;
+        if (fns)
+            for (let i = 0; i < fns.length; i++)
+                fns[i]();
+    }
+}
+/** Animates number fields of an object (nested paths and typed-array indices allowed). */
+export class PropertyTween extends TweenBase {
+    target;
+    holders;
+    keys;
+    from;
+    to;
+    constructor(target, props, seconds, opts) {
+        super(seconds, opts);
+        this.target = target;
+        const paths = Object.keys(props);
+        const n = paths.length;
+        this.holders = new Array(n);
+        this.keys = new Array(n);
+        this.from = new Float64Array(n);
+        this.to = new Float64Array(n);
+        for (let i = 0; i < n; i++) {
+            const path = paths[i];
+            const parts = path.split('.');
+            let holder = target;
+            for (let j = 0; j < parts.length - 1; j++) {
+                holder = holder[parts[j]];
+                if (holder === null || typeof holder !== 'object') {
+                    throw new Error(`tween: '${path}' does not exist on the target`);
+                }
+            }
+            const key = parts[parts.length - 1];
+            if (typeof holder[key] !== 'number') {
+                throw new Error(`tween: '${path}' is not a number on the target`);
+            }
+            this.holders[i] = holder;
+            this.keys[i] = key;
+            this.to[i] = props[path];
+        }
+    }
+    capture() {
+        for (let i = 0; i < this.keys.length; i++)
+            this.from[i] = this.holders[i][this.keys[i]];
+    }
+    applyAt(k) {
+        const { holders, keys, from, to } = this;
+        for (let i = 0; i < keys.length; i++) {
+            const a = from[i];
+            holders[i][keys[i]] = k === 1 ? to[i] : a + (to[i] - a) * k;
+        }
+    }
+}
+/** Animates one number from `from` to `to`, reporting it through `onUpdate(value, tween)`. */
+export class ValueTween extends TweenBase {
+    /** The value from the last update. */
+    value;
+    from;
+    to;
+    report;
+    constructor(from, to, seconds, onUpdate, opts) {
+        super(seconds, opts);
+        this.from = from;
+        this.to = to;
+        this.value = from;
+        this.report = onUpdate;
+    }
+    capture() { }
+    applyAt(k) {
+        this.value = k === 1 ? this.to : this.from + (this.to - this.from) * k;
+        this.report(this.value, this);
+    }
+}
+/** Does nothing for `seconds`; a pause inside a sequence. */
+export class DelayTween extends TweenBase {
+    capture() { }
+    applyAt() { }
+}

package/dist/ui/anchor.d.ts

@@ -0,0 +1,206 @@
+import { type Vec2 } from '../platform/letterbox.js';
+/** A rectangle: origin top-left, y down (the shape of `Camera.screen` and `Surface.rect`). */
+export interface AnchorRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * What anchors read from a camera: `Camera` from `@thunderclap-engine/engine/render` fits. `screen` is
+ * in logical px, or a fraction of the canvas when it lies inside the unit square (the renderer's
+ * viewport rule).
+ */
+export interface AnchorCamera {
+    readonly viewProjection: ArrayLike<number>;
+    readonly screen: Readonly<AnchorRect>;
+}
+/**
+ * Where the canvas is: `rect` in CSS px relative to the overlay's parent and the logical (design)
+ * size it shows. `Surface` fits; `overlay.anchors` passes its own frame and design size.
+ */
+export interface AnchorSurface {
+    readonly rect: Readonly<AnchorRect>;
+    readonly logicalWidth: number;
+    readonly logicalHeight: number;
+}
+export interface AnchorOptions {
+    /** CSS px added to the projected point. Default `[0, 0]`. */
+    offset?: readonly [number, number];
+    /**
+     * The point of the element's box placed on the anchor, as fractions of its size. Default
+     * `[0.5, 0.5]` (centred); `[0.5, 1]` sits the element on top of the point.
+     */
+    align?: readonly [number, number];
+    /**
+     * Keep the element inside the camera's viewport, `margin` CSS px from its edges, when the point
+     * leaves it or goes behind the camera (an off-screen marker). A clamped anchor is never hidden;
+     * while pinned to an edge it carries `data-anchor-clamped`. Default false.
+     */
+    clamp?: boolean;
+    /** Edge margin for `clamp`, CSS px. Default 16. */
+    margin?: number;
+    /**
+     * `'distance'` scales the element by `distance / w` (w is the clip w: the view depth under a
+     * perspective camera, 1 under an orthographic one), kept within `min`..`max`. Default `'none'`.
+     */
+    scale?: 'none' | 'distance';
+    /** The depth at which `scale: 'distance'` draws at 1. Default 10. */
+    distance?: number;
+    /** Scale bounds for `scale: 'distance'`. Default 0.25 and 2. */
+    min?: number;
+    max?: number;
+    /**
+     * Hide the element (`hidden` attribute) when the point is behind the camera or outside clip
+     * space. Default true; ignored when `clamp` is on.
+     */
+    hideBehind?: boolean;
+    /** The layer to place the element in (a key of `AnchorsOptions.layers`). Default: `root`. */
+    layer?: string;
+}
+/** One anchored element. */
+export interface AnchorHandle {
+    readonly el: HTMLElement;
+    /** False while hidden by `hideBehind`, as of the last `update()`. */
+    readonly visible: boolean;
+    /** True while `clamp` holds the element at the viewport's edge. */
+    readonly clamped: boolean;
+    /** The anchor point in the layer, CSS px, as of the last `update()` (offset included). */
+    readonly x: number;
+    readonly y: number;
+    /** The scale applied, as of the last `update()` (1 unless `scale: 'distance'`). */
+    readonly scale: number;
+    /** Move the anchor to a world point (copied). */
+    set(world: ArrayLike<number>): void;
+    /** Stop placing the element and take it out of the layer. */
+    remove(): void;
+}
+/**
+ * The frame anchors project into (ws/ui-4): the logical (design) size the camera's `screen` is
+ * in and the CSS rect it fills, relative to the overlay's parent. `Anchors.frame` is kept current
+ * with the surface, so tooltips, the cursor, float numbers and the minimap read one source.
+ */
+export interface AnchorFrame {
+    readonly width: number;
+    readonly height: number;
+    readonly rect: Readonly<AnchorRect>;
+}
+export interface AnchorsOptions {
+    /** The default layer. It should be laid over the frame (the canvas rect), like `ui.layers.hud`. */
+    root: HTMLElement;
+    surface: AnchorSurface;
+    /** The camera to project through, read on every `update()`. */
+    camera: () => AnchorCamera;
+    /** Other layers by name, for `AnchorOptions.layer`. */
+    layers?: Readonly<Record<string, HTMLElement>>;
+    /**
+     * Is the named layer laid over the frame (true) or over the frame's parent (false, so the
+     * frame's offset is added)? Default: every layer is on the frame.
+     */
+    onFrame?: (layer: string) => boolean;
+}
+/** Typed OM parts reused for one element, so a move allocates nothing where the API exists. */
+export interface TypedTransform {
+    x: CSSUnitValue;
+    y: CSSUnitValue;
+    s: CSSUnitValue;
+    value: CSSTransformValue;
+}
+declare class Anchor implements AnchorHandle {
+    readonly el: HTMLElement;
+    private readonly owner;
+    readonly world: Float32Array<ArrayBuffer>;
+    visible: boolean;
+    clamped: boolean;
+    x: number;
+    y: number;
+    scale: number;
+    removed: boolean;
+    readonly ax: number;
+    readonly ay: number;
+    readonly ox: number;
+    readonly oy: number;
+    readonly clamp: boolean;
+    readonly margin: number;
+    readonly byDistance: boolean;
+    readonly distance: number;
+    readonly min: number;
+    readonly max: number;
+    readonly hideBehind: boolean;
+    readonly layer: string | null;
+    readonly typed: TypedTransform | null;
+    /** The string fallback's tail: `scale(…)` is written in front of it. */
+    readonly alignCss: string;
+    constructor(el: HTMLElement, world: ArrayLike<number>, opts: AnchorOptions, owner: Anchors);
+    set(world: ArrayLike<number>): void;
+    remove(): void;
+    /** Write the element's place; only what changed touches the DOM. */
+    place(x: number, y: number, s: number, visible: boolean, clamped: boolean): void;
+}
+/**
+ * CSS Typed OM where the browser has it (Chromium, WebKit); null elsewhere (string fallback).
+ * `translate3d(x, y, 0) scale(s) translate(-ax%, -ay%)` with its three values reusable.
+ * @internal shared with the float numbers.
+ */
+export declare function typedTransform(el: HTMLElement, ax: number, ay: number): TypedTransform | null;
+/**
+ * DOM elements that follow world points: a name over a character, a damage number, a hint on a
+ * tile, a marker that stays on screen for something off it. Each `update()` projects every point
+ * through the camera (`viewProjection`), maps clip space onto the camera's `screen` and that onto
+ * the canvas rect in CSS px, and writes `transform` on the element (layout never reflows). A
+ * point behind the camera or outside clip space hides its element (`hidden`) unless it is
+ * clamped. `update()` allocates nothing in steady state where CSS Typed OM exists; elsewhere a
+ * moved element gets one transform string.
+ *
+ * In a game, `ctx.ui.anchors(camera)` builds the overlay's one `Anchors` on `ui.layers.hud`, and
+ * `createGame` updates it after every frame.
+ */
+export declare class Anchors {
+    private readonly opts;
+    private readonly list;
+    private readonly clip;
+    private readonly pt;
+    private cam;
+    private readonly frameState;
+    private m;
+    private sc;
+    private kx;
+    private ky;
+    private vx0;
+    private vy0;
+    private vx1;
+    private vy1;
+    /** The clip w of the last projected point (view depth under a perspective camera). */
+    private depth;
+    constructor(opts: AnchorsOptions);
+    /** Anchored elements. */
+    get size(): number;
+    /** The logical size and CSS rect projected into, as the surface has them now (one reused object). */
+    get frame(): AnchorFrame;
+    /**
+     * Project a world point into frame CSS px (the hud layer's coordinates), written to `out`, the
+     * way an anchor is placed before its offset and clamp. Returns whether the point is in view: a
+     * point behind the camera is pushed far out along its direction, one outside the viewport
+     * lands where it would. Allocates nothing.
+     */
+    project(x: number, y: number, z: number, out: Vec2): boolean;
+    /** Project through another camera from the next `update()` on. */
+    setCamera(camera: () => AnchorCamera): void;
+    /**
+     * Place `el` at the world point `world` (copied) from the next `update()` on. The element is
+     * appended to its layer (`opts.layer`, else `root`) and positioned absolutely at the layer's
+     * top-left, moved by `transform` only.
+     */
+    add(el: HTMLElement, world: ArrayLike<number>, opts?: AnchorOptions): AnchorHandle;
+    /** Remove every anchored element. */
+    clear(): void;
+    /** @internal */
+    drop(a: Anchor): void;
+    /** Place every element for the camera as it is now. Call once a frame, after the camera moved. */
+    update(): void;
+    /** Read the camera and the viewport (camera.screen in frame CSS px) for the projections after. */
+    private prepare;
+    /** One point through the prepared camera: `out` gets frame CSS px, `depth` the clip w. */
+    private projectPrepared;
+}
+export {};