hayao 0.4.0 → 0.4.1

package/dist/anim/blend.d.ts

@@ -0,0 +1,68 @@
+import { type ClipDef } from './clip';
+/** A sampled pose: "target/channel" → value. Plain object; order-insensitive. */
+export type Pose = Record<string, number>;
+/** Compose a pose key from a track's target + channel. */
+export declare const poseKey: (target: string, channel: string) => string;
+/**
+ * Sample a whole clip into a Pose at NORMALIZED phase `phase` in [0,1) — the
+ * blend-space entry point. `phase * duration` is the clip-local time (so two
+ * clips of different length stay in step). Pure; allocates one fresh Pose.
+ */
+export declare function samplePose(def: ClipDef, phase: number): Pose;
+/**
+ * Linear blend of two poses: `out[k] = lerp(a[k], b[k], t)`. Keys present in only
+ * one pose pass through unblended (the other side has no opinion). When `out` is
+ * supplied it is reused (cleared then filled) — the allocation-free path
+ * ClipPlayer takes during a crossfade. Returns `out`.
+ */
+export declare function mixPose(a: Pose, b: Pose, t: number, out?: Pose): Pose;
+/** One entry of a blend space: a clip pinned at a parameter position. */
+export interface BlendSample {
+    clip: ClipDef;
+    /** Parameter position of this sample (e.g. speed). Blend1D reads `.x` only. */
+    x: number;
+    /** Second parameter (Blend2D only). */
+    y?: number;
+}
+/**
+ * A 1-D blend space (e.g. idle→walk→run along speed). Samples are sorted by `x`
+ * on construction; `sample(param, phase)` finds the bracketing pair and mixes
+ * them by the normalized distance, all clips sampled at the SAME phase (foot-lock).
+ * Below the first / above the last sample it clamps to the end clip.
+ */
+export declare class Blend1D {
+    readonly samples: BlendSample[];
+    constructor(samples: BlendSample[]);
+    /** The clip weights at parameter `param` (sums to 1; empty space → {}). */
+    weights(param: number): {
+        clip: ClipDef;
+        weight: number;
+    }[];
+    /** Blend the neighbor clips at `param`, all sampled at normalized `phase`. */
+    sample(param: number, phase: number): Pose;
+}
+/**
+ * A 2-D blend space (e.g. a locomotion pad: forward/back × left/right). No
+ * triangulation library — we pick the NEAREST THREE samples to the query point
+ * and blend them barycentrically; if the point is outside their triangle the
+ * barycentric weights are clamped to >= 0 and renormalized (a documented
+ * approximation: no Delaunay, so a sparse/concave set can pick a non-ideal trio).
+ */
+export declare class Blend2D {
+    readonly samples: Required<BlendSample>[];
+    constructor(samples: BlendSample[]);
+    /** Clip weights at (px,py): nearest-3 barycentric, clamped + renormalized. */
+    weights(px: number, py: number): {
+        clip: ClipDef;
+        weight: number;
+    }[];
+    private barycentric;
+    /** Blend the nearest-3 clips at (px,py), all sampled at normalized `phase`. */
+    sample(px: number, py: number, phase: number): Pose;
+}
+/**
+ * Validate a blend space's samples (levelIssues idiom). Catches empty spaces,
+ * duplicate parameter positions (a degenerate bracket / triangle), and non-finite
+ * coordinates. `dims` selects which axes must be finite.
+ */
+export declare function blendIssues(samples: BlendSample[], dims?: 1 | 2): string[];

package/dist/anim/clip.d.ts

@@ -0,0 +1,87 @@
+import { EASINGS } from '../scene/tween';
+/** Which transform channel a track drives. */
+export type ClipChannel = 'x' | 'y' | 'rotation' | 'scaleX' | 'scaleY' | 'opacity';
+export declare const CLIP_CHANNELS: readonly ClipChannel[];
+/** How the playhead behaves past `duration`. */
+export type ClipLoop = 'loop' | 'once' | 'pingpong';
+/** One keyframe: value `v` at time `t` (seconds), with the ease used to reach it FROM the previous key. */
+export interface Keyframe {
+    t: number;
+    v: number;
+    /** EASINGS name applied over the segment ENDING at this key. Default 'linear'. */
+    ease?: keyof typeof EASINGS;
+}
+/** One track: a channel of one target node, driven by an ordered keyframe list. */
+export interface TrackDef {
+    /** '/'-separated path from the rig root to the target node (matched by Node.name). */
+    target: string;
+    channel: ClipChannel;
+    /** Keyframes, ascending in `t`. At least one. */
+    keys: Keyframe[];
+}
+/** A discrete event fired as the playhead crosses `t` (half-open (t0,t1] window). */
+export interface ClipEvent {
+    t: number;
+    name: string;
+}
+/** A full clip: duration, loop mode, tracks, optional events. Plain data. */
+export interface ClipDef {
+    /** Clip length in seconds (> 0). */
+    duration: number;
+    loop: ClipLoop;
+    tracks: TrackDef[];
+    events?: ClipEvent[];
+    /** RESERVED — root motion is not implemented (see file header). */
+    rootMotion?: never;
+}
+/**
+ * Map a raw elapsed time to a clip-local time in [0, duration], honoring the
+ * loop mode. `once` clamps at both ends; `loop` wraps; `pingpong` folds so the
+ * playhead ping-pongs 0→d→0. Pure and total (guards duration <= 0 → 0).
+ */
+export declare function clipTime(def: ClipDef, elapsed: number): number;
+/** True once a `once` clip has run past its end (used by ClipPlayer to fire `finished`). */
+export declare function clipFinished(def: ClipDef, elapsed: number): boolean;
+/**
+ * Binary-search the keyframe segment containing local time `t` and return the
+ * eased-interpolated value. Before the first key → first value; after the last →
+ * last value (clips are sampled at a clamped clipTime, so this only bites at the
+ * exact ends). Allocation-free: no array building, no closures.
+ */
+export declare function sampleTrack(keys: Keyframe[], t: number): number;
+/**
+ * A sampled pose channel: which target/channel and the value. `sampleClip`
+ * returns one per track. Kept flat (not a nested object) so ClipPlayer can bind
+ * each to a resolved node once and apply in O(tracks) with no lookups.
+ */
+export interface SampledChannel {
+    target: string;
+    channel: ClipChannel;
+    value: number;
+}
+/**
+ * PURE sample of the whole clip at raw `elapsed` seconds → one SampledChannel per
+ * track. Never mutates `def`. Two calls with the same args are deep-equal. This
+ * is the reference sampler; ClipPlayer uses a prebound, allocation-free variant
+ * of the same math for the hot path.
+ */
+export declare function sampleClip(def: ClipDef, elapsed: number): SampledChannel[];
+/**
+ * Events crossed as the playhead advances from raw `prev` to raw `next`, in the
+ * order they fire. FIXED SEMANTICS:
+ *  - half-open window `(t0, t1]` in clip-local time (an event exactly at the new
+ *    time fires; one exactly at the old time does NOT re-fire);
+ *  - `loop` wrap emits the TAIL segment (prevLocal, duration] then the HEAD
+ *    segment (0, nextLocal];
+ *  - `once` never re-fires an event once the playhead is at/after duration;
+ *  - order within a segment is ascending by `t`, tail before head on a wrap.
+ * Pure; returns event names in fire order.
+ */
+export declare function clipEvents(def: ClipDef, prev: number, next: number): string[];
+/**
+ * Validate a clip's DATA, in the levelIssues/tuningIssues idiom: return ALL
+ * problems as human-readable strings (empty = clean), never throw. Optionally
+ * pass the set of valid target paths (`knownTargets`) to catch tracks that point
+ * at a node the rig doesn't contain.
+ */
+export declare function clipIssues(def: ClipDef, knownTargets?: readonly string[]): string[];

package/dist/anim/ik.d.ts

@@ -0,0 +1,40 @@
+import type { Vec2 } from '../core/math';
+/** Result of a 2-bone solve: absolute WORLD-space angles (radians) for each joint. */
+export interface TwoBoneResult {
+    /** Absolute angle of bone 0 (root→mid). */
+    angle0: number;
+    /** Absolute angle of bone 1 (mid→end). */
+    angle1: number;
+    /** True if the target was in range; false → chain clamped to full extension toward it. */
+    reachable: boolean;
+}
+/**
+ * Analytic two-bone IK. `root` is the base joint (world), `l0`/`l1` the bone
+ * lengths, `target` the desired end-effector position (world). `bendDir` is +1
+ * or −1 to choose which side the middle joint bends to (elbow up/down). Returns
+ * the two ABSOLUTE bone angles (add to nothing — they are world angles; convert
+ * to local by subtracting the parent's world angle at the call site).
+ */
+export declare function solveTwoBoneIK(root: Vec2, l0: number, l1: number, target: Vec2, bendDir?: 1 | -1): TwoBoneResult;
+export interface FabrikResult {
+    /** Joint positions (world), joints[0] === root, joints[n] === end effector. */
+    joints: Vec2[];
+    /** Absolute bone angles (radians), one per bone (length joints.length - 1). */
+    angles: number[];
+    reachable: boolean;
+    /** Iterations actually run before convergence (or the cap). */
+    iterations: number;
+}
+/**
+ * FABRIK N-bone solver. `root` anchors joint 0; `lengths` are the bone lengths
+ * (n bones → n+1 joints); `target` is the desired end position. Alternates a
+ * backward reach (pull the end to the target, propagate inward) and a forward
+ * reach (pin the root, propagate outward) until the end is within `tolerance` of
+ * the target or `maxIter` is hit. When the target is unreachable the chain is
+ * laid out straight toward it (reachable=false). Pure; deterministic (dmath).
+ */
+export declare function solveFabrik(root: Vec2, lengths: number[], target: Vec2, opts?: {
+    maxIter?: number;
+    tolerance?: number;
+    initial?: Vec2[];
+}): FabrikResult;

package/dist/anim/skeleton.d.ts

@@ -0,0 +1,64 @@
+import { Node, type NodeConfig } from '../scene/node';
+import type { ClipChannel, ClipDef, Keyframe } from './clip';
+export interface Bone2DConfig extends NodeConfig {
+    /** Bone reach in local px (root→tip along +x at rotation 0). Default 0. */
+    length?: number;
+}
+/**
+ * A rig joint: a Node with a `length`. Rotation is the joint angle; children
+ * inherit the transform, so a chain of Bone2Ds nested tip-to-root forms a limb.
+ * Registered (`Bone2D`) so a serialized rig round-trips — `length` persists.
+ */
+export declare class Bone2D extends Node {
+    readonly type = "Bone2D";
+    /** Reach in local px along +x. Used by IK, skinning, and the debug overlay. */
+    length: number;
+    constructor(config?: Bone2DConfig);
+    /** Tip position in LOCAL space (root is the node origin; tip is `length` along +x). */
+    get tip(): {
+        x: number;
+        y: number;
+    };
+    protected serializeProps(): Record<string, unknown>;
+    applyProps(props: Record<string, unknown>): void;
+}
+/**
+ * An index of a rig subtree: '/'-separated name path → node. Paths are relative
+ * to the rig root passed to `buildSkeleton` (the root itself is '' and its direct
+ * children are just their names). Ordered iteration only (a plain Map, built by a
+ * deterministic DFS).
+ */
+export declare class Skeleton {
+    readonly root: Node;
+    readonly byPath: Map<string, Node>;
+    constructor(root: Node);
+    private index;
+    /** Resolve a track/IK target path to a node (null if the rig lacks it). */
+    resolve(path: string): Node | null;
+    /** All target paths in the rig — feed to `clipIssues(def, skeleton.targets())`. */
+    targets(): string[];
+    /** Only the Bone2D joints, by path (for IK / skinning). */
+    bones(): Bone2D[];
+}
+/** Build a skeleton index from a rig root. */
+export declare function buildSkeleton(root: Node): Skeleton;
+/**
+ * A track prebound to its target node: the resolved Node, the channel, and the
+ * clip's keyframes captured by reference. ClipPlayer holds an array of these and
+ * applies each with a single write in the hot path — no path lookup, no find().
+ */
+export interface BoundTrack {
+    node: Node;
+    channel: ClipChannel;
+    keys: Keyframe[];
+    /** The track's path, kept for diagnostics / rebind. */
+    target: string;
+}
+/**
+ * Resolve every track of a clip against a skeleton ONCE. Tracks whose target the
+ * rig doesn't contain are dropped (surfaced separately by clipIssues) so the hot
+ * path never guards for a null node. Returns bound tracks in clip order.
+ */
+export declare function resolveTracks(def: ClipDef, skeleton: Skeleton): BoundTrack[];
+/** Apply one channel's value to a node's transform (the single hot-path write). */
+export declare function applyChannel(node: Node, channel: ClipChannel, value: number): void;