@ikijs/engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zeikar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @ikijs/engine
+
+WebGL2 runtime that plays a [`.iki`](../format) puppet model in the browser.
+
+The engine is **host-agnostic**: it depends only on
+[`@ikijs/format`](../format) and knows nothing about any particular app. A host
+drives it by setting parameters (from lip-sync, gaze, blink, expressions); the
+engine renders the result each frame.
+
+## Install
+
+```bash
+npm install @ikijs/engine @ikijs/format
+```
+
+## Usage
+
+```ts
+import { IkiPlayer } from "@ikijs/engine";
+import { loadIkiModel, StandardParameter } from "@ikijs/format";
+
+const player = new IkiPlayer(canvas); // HTMLCanvasElement
+const result = await player.load(loadIkiModel(json));
+if (result.failedTextures.length > 0) {
+  console.warn("some textures failed", result.failedTextures);
+}
+player.start();
+
+player.setParameter(StandardParameter.MouthOpen, 0.7);
+```
+
+`load()` decodes and uploads every texture before swapping the model in, so a
+frame is never half-textured. Parameter writes are clamped to the declared
+range; unknown ids and non-finite values are ignored.
+
+## API
+
+| Export                                           | What it is                                                                                              |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `IkiPlayer`                                      | The renderer: `load` / `start` / `stop` / `setParameter` / `getParameter` / `getParameters` / `destroy` |
+| `IkiLoadResult`                                  | `{ failedTextures, superseded }` returned by `load()`                                                   |
+| `ParameterStore`                                 | The clamped parameter map the player drives                                                             |
+| `IdleMotion`                                     | Auto-blink / breath / gaze-drift driver                                                                 |
+| `PhysicsMotion`                                  | Spring-mass-damper secondary motion (`model.physics`)                                                   |
+| `HairChainMotion`                                | Multi-segment angular chain with gravity (`model.physicsChains`)                                        |
+| `translate` `rotate` `scale` `multiply` `toMat3` | The 2D affine helpers the engine itself uses                                                            |
+
+## Motion drivers
+
+`IdleMotion`, `PhysicsMotion`, and `HairChainMotion` are **peer drivers**, not
+part of the render loop: each is a pure-logic object you `update(nowMs)` once
+per frame, and each writes through a sink you supply. That keeps them testable
+and lets a host override or omit any of them.
+
+```ts
+import { HairChainMotion, IdleMotion, PhysicsMotion } from "@ikijs/engine";
+
+// The drivers read the live pose and write the next one, both through the
+// player — no host-side copy of the parameter state to keep in sync.
+const drive = (id: string, value: number) => player.setParameter(id, value);
+const read = (id: string) => player.getParameter(id);
+
+const idle = new IdleMotion(drive);
+const physics = new PhysicsMotion(
+  model.physics ?? [],
+  model.parameters,
+  read,
+  drive,
+);
+const chains = new HairChainMotion(
+  model.physicsChains ?? [],
+  model.parameters,
+  model.deformers ?? [],
+  read,
+  drive,
+);
+
+const tick = (now: number) => {
+  idle.update(now);
+  physics.update(now); // reads what idle just wrote
+  chains.update(now);
+  requestAnimationFrame(tick);
+};
+requestAnimationFrame(tick);
+```
+
+Both physics drivers integrate on a fixed 1/60 s sub-step with a clamped frame
+delta, so a backgrounded tab or a long hitch cannot snap the rig.
+
+## Rendering notes
+
+- The whole pipeline is **premultiplied alpha** — the canvas is created with
+  `premultipliedAlpha: true` and the shader premultiplies before blending.
+- Clipping masks use the stencil buffer. If the context grants no stencil, the
+  affected parts render unclipped and `load()` logs it.
+- Textures are decoded from `data:` URIs only; external URLs are skipped with a
+  warning (a resolver is not part of v1).
+- Atlas authors should pad / extrude sub-rect borders to avoid LINEAR-filter
+  bleeding.
+
+## License
+
+MIT © Zeikar

package/dist/index.d.mts

@@ -0,0 +1,353 @@
+import { IkiModel, IkiParameter, IkiPhysics, IkiPhysicsChain, IkiDeformer } from '@ikijs/format';
+
+/**
+ * Outcome of {@link IkiPlayer.load}: the indices into `model.textures` that
+ * failed to decode or upload (empty = every declared texture loaded). The model
+ * is still swapped in and rendered; parts using a failed texture are skipped.
+ * A host can inspect this to detect and report a partial load.
+ */
+interface IkiLoadResult {
+    failedTextures: number[];
+    /**
+     * True when a newer `load()` (or `destroy()`) superseded this call before it
+     * adopted anything — the model was NOT loaded and `failedTextures` is empty
+     * because nothing was attempted, not because everything succeeded. Without
+     * this flag a caller awaiting the losing promise cannot tell the two apart.
+     */
+    superseded: boolean;
+}
+/**
+ * Drives a single `.iki` model on a WebGL2 canvas.
+ *
+ * v1 scope: parts are solid-color or atlas-sampled textured quads or meshes,
+ * transformed each frame by their base transform plus the sum of their parameter
+ * bindings. `load()` is async — it decodes and uploads textures before swapping
+ * the model in. Mesh parts additionally carry per-vertex UV and optional warp
+ * keyforms, interpolated each frame on the CPU into a dynamic vertex buffer.
+ */
+declare class IkiPlayer {
+    private readonly canvas;
+    private readonly gl;
+    private readonly program;
+    private readonly quad;
+    private readonly uMatrix;
+    private readonly uColor;
+    private readonly uUseTexture;
+    private readonly uTex;
+    private readonly uUvOffset;
+    private readonly uUvScale;
+    private readonly uUseMeshUv;
+    private readonly uAlphaCutoff;
+    private readonly aPos;
+    private readonly aUv;
+    /** True when the context granted a stencil buffer; clipping needs it. */
+    private readonly stencilAvailable;
+    private model?;
+    private parts;
+    private params;
+    private rafId?;
+    /** Uploaded textures, index-aligned with `model.textures`; `null` = unusable. */
+    private textures;
+    /** Bumped by every `load` and by `destroy`; lets a stale async load bail. */
+    private loadGeneration;
+    private destroyed;
+    /**
+     * Engine-internal mesh buffers, keyed by the part's INDEX in `this.parts`
+     * (NOT by part id — duplicate ids must not swap buffers).
+     */
+    private partMeshes;
+    /**
+     * Clip groups resolved once per `load()`: consumer part index (into `this.parts`)
+     * → its mask part indices. A part absent from this map is unclipped.
+     */
+    private partClipGroups;
+    constructor(canvas: HTMLCanvasElement);
+    /**
+     * Load a model and reset parameters to their defaults. All textures are
+     * decoded and uploaded before the model is swapped in — the swap is atomic,
+     * so you never see a partially-textured frame. `start()` may be called any
+     * time, but nothing renders until the first `load()` resolves. For an
+     * embedded `data:` atlas this is near-instant.
+     *
+     * Individual texture decode/upload failures are non-fatal: they are logged
+     * via `console.error`, the affected parts are skipped, and `load()` still
+     * resolves — the returned {@link IkiLoadResult} lists the indices of any
+     * textures that failed, so a host can detect and report a partial load. The
+     * model is assumed already validated by `@ikijs/format`.
+     *
+     * Mesh buffer allocation failure IS fatal (unlike per-texture skip) because
+     * textures have an `IkiLoadResult.failedTextures` reporting surface and mesh
+     * buffers have none — there is no partial-mesh concept in the format.
+     */
+    load(model: IkiModel): Promise<IkiLoadResult>;
+    /**
+     * Start the render loop. Safe to call more than once, and a no-op after
+     * {@link destroy} — the program and buffers the loop draws with are gone, so
+     * restarting would only spray GL errors.
+     */
+    start(): void;
+    stop(): void;
+    /**
+     * Set a parameter value (clamped to its range). Unknown ids and non-finite
+     * values are ignored — see {@link ParameterStore.set}.
+     */
+    setParameter(id: string, value: number): void;
+    /**
+     * Current value of a parameter, or 0 for an unknown id.
+     *
+     * Hosts need this to avoid shadowing the engine's state: the motion drivers
+     * read the live pose to compute the next one, and without a read accessor
+     * every host has to keep its own mirror of what it last wrote — and keep that
+     * mirror's clamping in step with {@link ParameterStore} by hand.
+     */
+    getParameter(id: string): number;
+    /** The model's parameter descriptors, for building UI or host wiring. */
+    getParameters(): IkiParameter[];
+    destroy(): void;
+    private renderFrame;
+    /**
+     * Draw a clipped part: stencil the union of its masks' alpha coverage, then
+     * draw the part only where the stencil was written. The mask parts also draw
+     * normally in their own `order` slot — this is an EXTRA, color-free pass over
+     * the same per-frame deformed geometry. All stencil/colorMask state the pass
+     * touches is restored before returning so later parts are unaffected.
+     */
+    private drawClipped;
+    /**
+     * Draw a single part with its full per-part material + geometry state. Shared
+     * by the normal pass, the stencil mask-write pass, and the masked consumer
+     * draw — so every path prepares the SAME complete uniform/texture/VBO state
+     * (the caller only sets stencil/colorMask/u_alphaCutoff around it).
+     */
+    private drawPart;
+    /** Resolve a part's effective transform from its base plus active bindings. */
+    private evaluate;
+}
+
+/**
+ * Holds the live value of every model parameter, clamped to its declared
+ * range. This is the single surface a host drives (lip-sync, gaze, blink) and
+ * the engine reads each frame to evaluate bindings.
+ */
+declare class ParameterStore {
+    private readonly params;
+    private readonly values;
+    /**
+     * Resting value per id: the declared default clamped into range, resolved
+     * ONCE here so `reset()` is a straight copy and a malformed descriptor is
+     * reported once rather than on every reset.
+     */
+    private readonly defaults;
+    constructor(parameters: IkiParameter[]);
+    /**
+     * Set a parameter's value, clamped to its range. Unknown ids are ignored, as
+     * are non-finite values: this is the boundary a host drives with live signals,
+     * and `clamp` cannot filter NaN (`Math.max(min, Math.min(max, NaN))` is NaN),
+     * so one bad lip-sync/gaze frame would otherwise poison every binding that
+     * reads the parameter. A dropped write holds the last good pose.
+     */
+    set(id: string, value: number): void;
+    /** Current value, or 0 if the id is unknown. */
+    get(id: string): number;
+    /** Position of a parameter within its range, 0..1. */
+    normalized(id: string): number;
+    /** Reset every parameter to its resting value (see `defaults`). */
+    reset(): void;
+    list(): IkiParameter[];
+}
+
+type Affine = [number, number, number, number, number, number];
+declare function translate(tx: number, ty: number): Affine;
+declare function scale(sx: number, sy: number): Affine;
+declare function rotate(degrees: number): Affine;
+declare function multiply(a: Affine, b: Affine): Affine;
+/** Expand a 2D affine into a column-major mat3 for `uniformMatrix3fv`. */
+declare function toMat3(a: Affine): Float32Array;
+
+interface IdleMotionOptions {
+    /** Inject a deterministic rng for testing. Defaults to Math.random. */
+    rng?: () => number;
+}
+/**
+ * Pure-logic idle-animation driver. Animates the seven "life" parameters
+ * (eyes, breath, gaze, head sway) on an internal clock so tab-backgrounding
+ * or irregular frame delivery can't produce teleports or snap-close blinks.
+ *
+ * Usage:
+ *   const idle = new IdleMotion(player.setParameter.bind(player));
+ *   // inside your rAF loop:
+ *   idle.update(performance.now());
+ *
+ * The host is responsible for scheduling; this class has no timers or rAF.
+ */
+declare class IdleMotion {
+    private readonly sink;
+    private readonly rng;
+    private clockMs;
+    private prevNowMs;
+    private nextBlinkAtMs;
+    private blinkStartMs;
+    private gazeCurrentX;
+    private gazeCurrentY;
+    private gazeTargetX;
+    private gazeTargetY;
+    private nextGazeRetargetMs;
+    constructor(sink: (id: string, value: number) => void, options?: IdleMotionOptions);
+    /**
+     * Advance the idle animation to the given wall-clock timestamp (milliseconds).
+     *
+     * On the first call: record prevNowMs, emit the resting pose, and return —
+     * no animation advance happens so there is no jump from time 0.
+     *
+     * On subsequent calls: compute dt = clamp(nowMs - prevNowMs, 0, MAX_DT_MS)
+     * and advance the internal clock by dt. A non-monotonic nowMs produces a
+     * negative raw delta that the clamp floors to 0 — no rewind.
+     */
+    update(nowMs: number): void;
+    private emitRestingPose;
+    /** Returns the current eye-open value (0..1) and advances blink state. */
+    private advanceBlink;
+    private advanceBreath;
+    /** Horizontal head sway in degrees, pure function of the internal clock. */
+    private swayX;
+    /** Vertical head sway in degrees, pure function of the internal clock. */
+    private swayY;
+    /** Ease gaze current toward target; pick a new target on the internal clock. */
+    private advanceGaze;
+}
+
+/**
+ * Host-agnostic 1D spring-mass-damper secondary-motion driver — the physics
+ * peer of {@link IdleMotion}. For each rig it reads the input parameter,
+ * signed-normalizes it around the input's default × `weight` to form a spring
+ * target, integrates a lagging spring position with semi-implicit (symplectic)
+ * Euler on a fixed 1/60s sub-step accumulator, and writes
+ * `outputDefault + x * scale` onto the output parameter — so the output lags
+ * and overshoots the input (hair/accessory sway).
+ *
+ * Usage:
+ *   const physics = new PhysicsMotion(
+ *     model.physics ?? [],
+ *     model.parameters,
+ *     (id) => currentValue(id),
+ *     player.setParameter.bind(player),
+ *   );
+ *   // inside your rAF loop, right AFTER idle.update(now):
+ *   physics.update(performance.now());
+ *
+ * The host schedules updates; this class has no timers, rAF, DOM, or Date.now.
+ * Writes go through the sink, exactly like IdleMotion; the player renders the
+ * updated params on its own render loop (drivers and rendering are decoupled).
+ */
+declare class PhysicsMotion {
+    private readonly rigs;
+    private readonly read;
+    private readonly sink;
+    private readonly params;
+    private readonly state;
+    private readonly clock;
+    constructor(rigs: IkiPhysics[], params: IkiParameter[], read: (id: string) => number, sink: (id: string, value: number) => void);
+    /**
+     * Advance every rig to the given wall-clock timestamp (milliseconds).
+     *
+     * First call: seed each spring to rest AT its current target (so a model
+     * loaded with a nonzero input does not kick), emit the resting output, and
+     * return without integrating — mirroring IdleMotion's first-frame behavior.
+     *
+     * Subsequent calls: {@link FixedStepClock} folds the clamped frame delta into
+     * its accumulator and returns how many {@link FIXED_DT_S} sub-steps are due;
+     * the spring advances that many semi-implicit Euler steps, then each rig emits
+     * its output once. The clock's dt clamp and sub-step cap plus the symplectic
+     * integrator are what keep it stable across hitches.
+     */
+    update(nowMs: number): void;
+    /** Spring target = signed-normalized input value × weight. */
+    private targetFor;
+    /** One semi-implicit (symplectic) Euler sub-step of FIXED_DT_S seconds. */
+    private step;
+    /** Write outputDefault + x * scale onto the output param via the sink. */
+    private emit;
+}
+
+/**
+ * Host-agnostic multi-segment angular-pendulum-chain secondary-motion driver.
+ * Peer of {@link PhysicsMotion} and {@link IdleMotion}.
+ *
+ * Each chain anchors to a matrix deformer in the model hierarchy. The driver
+ * self-computes the anchor's world rotation via `resolveDeformerWorlds` (a
+ * private `ParameterStore` is filled from `read` ONCE per frame) and integrates
+ * a per-segment angular pendulum with semi-implicit Euler on a fixed 1/60s
+ * sub-step accumulator. Each segment's angular displacement θ (in radians
+ * internally) is emitted in DEGREES on its output parameter, so `rotate = 0`
+ * when the chain is at its authored rest pose.
+ *
+ * Usage:
+ *   const chains = new HairChainMotion(
+ *     model.physicsChains ?? [],
+ *     model.parameters,
+ *     model.deformers ?? [],
+ *     (id) => currentValue(id),
+ *     player.setParameter.bind(player),
+ *   );
+ *   // inside your rAF loop, right AFTER physics.update(now):
+ *   chains.update(performance.now());
+ *
+ * The host schedules updates; this class has no timers, rAF, DOM, or Date.now.
+ */
+declare class HairChainMotion {
+    private readonly chainData;
+    private readonly params;
+    private readonly deformers;
+    private readonly store;
+    private readonly read;
+    private readonly sink;
+    private readonly clock;
+    constructor(chains: IkiPhysicsChain[], params: IkiParameter[], deformers: IkiDeformer[], read: (id: string) => number, sink: (id: string, value: number) => void);
+    /**
+     * Advance every chain to the given wall-clock timestamp (milliseconds).
+     *
+     * First call: seed every segment to θ=0/ω=0 (rest), emit the rest output
+     * (outDefault + 0), and return without integrating — mirrors PhysicsMotion's
+     * first-frame behavior so a model loaded in motion does not kick.
+     *
+     * Subsequent calls: dt = clamp(nowMs - prevNowMs, 0, MAX_DT_MS) → seconds into
+     * accumulator. The per-frame world snapshot (anchor world angles) is taken ONCE
+     * per update() — NOT per chain — so all chains share a consistent frame snapshot.
+     * Fixed FIXED_DT_S sub-steps are run root→tip, capped at MAX_SUBSTEPS; leftover
+     * time is carried to the next frame. Segments emit after substeps (even on zero
+     * substeps) with a non-finite guard.
+     */
+    update(nowMs: number): void;
+    /**
+     * Extract world rotation (radians) from the anchor's Affine tuple.
+     * Affine = [a,b,c,d,e,f]; rotation column = (a,b) → atan2(b,a).
+     *
+     * If the anchor id is absent from the map, THROWS an internal Error — the
+     * format validator guarantees the anchor exists, so absence is an invariant
+     * break (mirrors resolveDeformerWorlds' throw on an unresolved parent,
+     * deform.ts:141).
+     */
+    private anchorWorldAngleRad;
+    /**
+     * One fixed sub-step of FIXED_DT_S seconds for all segments in a chain.
+     *
+     * Segments are integrated ROOT→TIP so each segment can read its upstream
+     * neighbor's current-substep state when computing the world angle Φ_i.
+     * (The chain is causal root-to-tip; reversing the order would use stale θ
+     * values from the previous substep for Φ_i computation.)
+     *
+     * Per-segment semi-implicit (symplectic) Euler:
+     *   Φ_i = anchorWorldAngleRad + Σ_{j≤i}(restAngle_j + θ_j)
+     *   α_i = (−stiffness_i·θ_i − strength·sin(Φ_i − gravityAngle_rad) − damping_i·ω_i) / mass_i
+     *   ω_i += α_i · FIXED_DT_S   (velocity updated FIRST = semi-implicit)
+     *   θ_i += ω_i · FIXED_DT_S   (position updated from NEW velocity)
+     *
+     * The spring term is −stiffness·θ (restoring θ→0); restAngle does NOT appear
+     * in the spring term, only in Φ_i for the gravity torque.
+     */
+    private stepChain;
+    /** Emit outDefault + (θ_i · RAD2DEG) · scale for one segment. */
+    private emitSegment;
+}
+
+export { type Affine, HairChainMotion, IdleMotion, type IdleMotionOptions, type IkiLoadResult, IkiPlayer, ParameterStore, PhysicsMotion, multiply, rotate, scale, toMat3, translate };