mesh-avatar 0.3.1 → 0.5.0

package/README.md

@@ -68,6 +68,9 @@ avatar.setVoiceLevel(0.6);
 avatar.setEmotion('happy', { playMotion: false });
 avatar.setExpression('smile');
 
+// Show optional overlay layers (such as glasses) by name; [] hides them all.
+avatar.setOverlays(['glasses']);
+
 // Apply tracked or posed parameters. Each call replaces the supplied overrides.
 avatar.setParameters({ angleX: 10, gazeX: 0.25 }, 1);
 
@@ -82,7 +85,7 @@ avatar.setParameters({});
 avatar.destroy();
 ```
 
-Emotion tags are `happy`, `sad`, `angry`, `surprised`, `relaxed` and `neutral` (or `null` to reset). Expressions are `neutral`, `smile`, `shy`, `surprise`, `halfLidded`, `angry`, `sad` and `wink`; `LIVE_EXPRESSIONS` exports that list. `PARAMS` exports the parameter IDs, ranges and defaults. Voice methods animate the avatar; your app handles audio playback.
+Emotion tags are `happy`, `sad`, `angry`, `surprised`, `relaxed` and `neutral` (or `null` to reset). Expressions are `neutral`, `smile`, `shy`, `surprise`, `halfLidded`, `angry`, `sad` and `wink`; `LIVE_EXPRESSIONS` exports that list. `PARAMS` exports the parameter IDs, ranges and defaults. Overlay names come from the avatar's optional `built/overlays/overlays.json`; unknown names are ignored. Voice methods animate the avatar; your app handles audio playback.
 
 `loadMeshAvatar` releases archives it opens on `destroy()` or load failure; when passed an existing `AvatarPackage` from `openAvatar`, the caller owns it and must call `release()` after its last user is destroyed.
 

package/dist/engine/arms.d.ts

@@ -0,0 +1,24 @@
+/** Optional hanging arms, with image-left/right joints in source pixels. */
+export function createArms(arms: any, body: any, _legs?: null): {
+    weights: (x: any, y: any) => {
+        arm: number;
+        forearm: number;
+    }[];
+    frame: (P: any, move?: (p: any) => any[]) => {
+        shoulder: any[];
+        elbow: any[];
+        swing: number;
+        bend: number;
+    }[];
+    apply: (p: any, _x: any, _y: any, w: any, P: any, F?: {
+        shoulder: any[];
+        elbow: any[];
+        swing: number;
+        bend: number;
+    }[]) => void;
+} | null;
+export const ARM_DEFAULTS: Readonly<{
+    swing: 4;
+    bend: 6;
+    inward: 0.4;
+}>;

package/dist/engine/cloth-grid.d.ts

@@ -0,0 +1,14 @@
+/** Shared source-space grid for runtime skinning and Studio overlays. */
+export function sampleLine(line: any, fraction: any): any;
+export function clothGrid(c: any): {
+    custom: boolean;
+    cols: any;
+    rows: any;
+    rest: Float64Array<ArrayBuffer>;
+    seams: any;
+    joints: any;
+    fractions: never[][];
+    lengths: any;
+    top: any;
+};
+export function lineLength(line: any): any;

package/dist/engine/cloth-pendulum.d.ts

@@ -0,0 +1,13 @@
+export function solve(matrix: any, rhs: any): number[];
+export function pendulumSystem(lengths: any, gravity: any, zeta: any, highModeDamping?: number): {
+    lengths: any;
+    mass: any;
+    coefficient: any;
+    stiffness: any;
+    damping: any;
+    frequencies: any;
+    angles: any;
+    velocities: any;
+};
+export function pendulumEnergy(s: any, q?: any, v?: any): any;
+export function stepPendulum(s: any, h: any, ax?: number, gravityRatio?: number): void;

package/dist/engine/cloth-tuning.d.ts

@@ -0,0 +1,8 @@
+/** Validate a partial override before applying it to any garment. */
+export function checkClothTuning(tuning: any): void;
+/** @type {Readonly<import('../rig/types').ClothTuning>} */
+export const CLOTH_DEFAULTS: Readonly<import("../rig/types.js").ClothTuning>;
+export const CLOTH_OPTIONAL_DEFAULTS: Readonly<{
+    tierGain: 1;
+    highModeDamping: 1;
+}>;

package/dist/engine/cloth.d.ts

@@ -0,0 +1,62 @@
+/** @param {ReturnType<import('./rig.js').createRig>} engine
+ * @param {import('../rig/types').Rig} rig */
+export function createCloth(engine: ReturnType<typeof import("./rig.js").createRig>, rig: import("../rig/types.js").Rig): {
+    Cloth: {
+        new (): {
+            gain: number;
+            time: number;
+            setTuning(name: any, tuning: any): void;
+            /** Skin a layer mesh (rest/pos arrays in source px) to the named garment. */
+            attach(name: any, mesh: any): void;
+            step(P: any, dt: any, phys: any): void;
+            deform(): void;
+            /** Grid nodes per garment, for debug overlays. */
+            get grids(): {
+                name: string;
+                cols: any;
+                rows: any;
+                nodes: Float64Array<ArrayBuffer>;
+            }[];
+        };
+    };
+    garments: {
+        grid: {
+            custom: boolean;
+            cols: any;
+            rows: any;
+            rest: Float64Array<ArrayBuffer>;
+            seams: any;
+            joints: any;
+            fractions: never[][];
+            lengths: any;
+            top: any;
+        };
+        pendulums: ReturnType<typeof pendulumSystem>[];
+        systemKey: null;
+        c: import("../index.js").Cloth;
+        gravity: number;
+        tuning: {
+            [k: string]: any;
+        };
+        cols: any;
+        rows: any;
+        rest: Float64Array<ArrayBuffer>;
+        top: any;
+        weights: any;
+        target: Float64Array<ArrayBuffer>;
+        previous: null;
+        pivotVelocity: Float64Array<ArrayBuffer>;
+        angle: Float64Array<any>;
+        angularVelocity: Float64Array<any>;
+        lowerAngle: Float64Array<any>;
+        lowerAngularVelocity: Float64Array<any>;
+        bounce: Float64Array<any>;
+        bounceVelocity: Float64Array<any>;
+        out: Float64Array<ArrayBuffer>;
+        physicalOut: Float64Array<ArrayBuffer>;
+        parent: null;
+        parentLoc: null;
+        meshes: never[];
+    }[];
+};
+import { pendulumSystem } from './cloth-pendulum.js';

package/dist/engine/createMeshAvatar.d.ts

@@ -6,7 +6,7 @@ export function createMeshAvatarImpl(canvas: HTMLCanvasElement, options: import(
         label: string;
         idle: boolean;
     }[];
-    setParameters(values: any, weight?: number): void;
+    setParameters(values: any, weight?: number, weights?: {}): void;
     getParameters(): {};
     /** 0..1 loudness of the voice being played (e.g. normalised RMS). */
     setVoiceLevel(v: any): void;
@@ -18,6 +18,8 @@ export function createMeshAvatarImpl(canvas: HTMLCanvasElement, options: import(
     setEmotion(tag: any, opts: any): void;
     /** Live expression layered over tracking (see OVERLAY_EXPRESSIONS); 'neutral' clears it. */
     setExpression(name: any): void;
+    /** Show the named overlay layers (built/overlays/overlays.json) and hide the others. */
+    setOverlays(names: any): void;
     getExpression(): {
         name: "smile" | "shy" | "surprise" | "wink" | "neutral" | "halfLidded" | "angry" | "sad";
         active: boolean;
@@ -45,6 +47,7 @@ export function createMeshAvatarImpl(canvas: HTMLCanvasElement, options: import(
     setAutoMotion(on: any): void;
     /** Hair / tassel sway multiplier (1 = default). */
     setSwayGain(g: any): void;
+    setClothTuning(name: any, tuning: any): void;
     /** Called with the motion id when a motion starts and with null when it ends. */
     onMotion(fn: any): () => boolean;
     /** Advance the simulation by `sec` and draw (for tests / hidden tabs). */

package/dist/engine/index.d.ts

@@ -1,5 +1,5 @@
 import type { LightingSettings } from '../lighting/settings.js';
-import type { Rig } from '../rig/types.js';
+import type { Rig, ClothTuning } from '../rig/types.js';
 import { OVERLAY_EXPRESSIONS } from './expression-overlay.js';
 import type { LipSyncSettings } from './lip-sync.js';
 export type LiveExpression = keyof typeof OVERLAY_EXPRESSIONS;
@@ -27,7 +27,8 @@ export interface MeshAvatar {
         computedLayers: number;
         cachedLayers: number;
     };
-    setParameters(parameters: Record<string, number>, weight?: number): void;
+    /** Optional per-parameter weights multiply weight and blend against underlying motion; null clears them. */
+    setParameters(parameters: Record<string, number>, weight?: number, weights?: Record<string, number> | null): void;
     getParameters(): Record<string, number>;
     setVoiceLevel(value: number): void;
     /** Partial mouth-movement settings; omitted fields retain their current values. */
@@ -37,6 +38,8 @@ export interface MeshAvatar {
         playMotion?: boolean;
     }): void;
     setExpression(name: LiveExpression): void;
+    /** Show the named overlay layers from built/overlays/overlays.json and hide the rest; unknown names are ignored. */
+    setOverlays(names: string[]): void;
     getExpression(): {
         name: LiveExpression;
         active: boolean;
@@ -57,6 +60,8 @@ export interface MeshAvatar {
     setAutoIdle(on: boolean): void;
     setAutoMotion(on: boolean): void;
     setSwayGain(gain: number): void;
+    /** Override garment physics without rebuilding layers; null applies to every garment. */
+    setClothTuning(name: string | null, tuning: Partial<ClothTuning>): void;
     onMotion(listener: (id: string | null) => void): () => void;
     advance(seconds: number, fps?: number): void;
     advanceParameters(seconds: number): void;

package/dist/engine/legs.d.ts

@@ -0,0 +1,25 @@
+/** @param {{pivotX:number, pivotY:number, weightBand:number[]}|null} [head] */
+export function createLegs(legs: any, body: any, head?: {
+    pivotX: number;
+    pivotY: number;
+    weightBand: number[];
+} | null): {
+    frame: (P: any) => any;
+    weights: (x: any, y: any) => {
+        right: number;
+        perBone: {
+            leg: number;
+            shin: number;
+            pin: number;
+        }[];
+    };
+    apply: (p: any, _x: any, y: any, w: any, P: any) => void;
+    pin: (y: any) => number;
+    step: (P: any, dt: any) => void;
+} | null;
+/** Optional planted, two-bone legs. All coordinates are in source pixels. */
+export const LEG_DEFAULTS: Readonly<{
+    spine: 0.7;
+    bob: 2;
+    twist: 0;
+}>;

package/dist/engine/motion.d.ts

@@ -1,3 +1,5 @@
+/** Five-second held transfer:0.9s quintic S,1.6s hold per half-cycle. */
+export function weightTransfer(t: any): number;
 export namespace IDLE_GAIN {
     let amp: number;
     let stiff: number;
@@ -151,8 +153,12 @@ export namespace EXPRESSIONS {
     }
 }
 export class Motion {
-    /** @param {number[]} gazeCenter */
-    constructor(gazeCenter: number[]);
+    /** @param {number[]} gazeCenter @param {boolean} [planted] @param {import('../rig/types').Rig|null} [armRig] */
+    constructor(gazeCenter: number[], planted?: boolean, armRig?: import("../rig/types.js").Rig | null);
+    armRig: import("../index.js").Rig | null;
+    armFollow: number;
+    armVelocity: number;
+    planted: boolean;
     mode: string;
     P: {
         [k: string]: number;
@@ -258,18 +264,6 @@ export class Motion {
     playRandom(ids: any): void;
     playMotion(id: any): void;
     blinkValue(dt: any): number;
-    update(dt: any): {
-        eyeROpen: number;
-        eyeLOpen: number;
-        eyeSmile: any;
-        eyeSmileL: any;
-        mouthOpen: any;
-        mouthForm: any;
-        blush: any;
-        browY: any;
-        browAngle: any;
-        gazeX: any;
-        gazeY: any;
-    };
+    update(dt: any): Record<string, number>;
     talkNod: any;
 }

package/dist/engine/overlays.d.ts

@@ -0,0 +1,15 @@
+/** [x, y, w, h] around the opaque pixels (alpha > 3) plus `pad`, or null when fully transparent. */
+export function opaqueRect(alpha: any, width: any, height: any, pad?: number): number[] | null;
+/**
+ * Builds one layer per overlay. Like the sprites, only the opaque part of each drawing gets a
+ * grid: a grid over the whole image would move every transparent vertex each frame (about
+ * 100k vertices for a 1254 x 1254 image at 4 px, ~12 ms per frame on a mid-range phone).
+ * `crop(img, rect)` returns that part of the image (a canvas, for example) for the texture.
+ * Brows and jaw do not move an accessory, so their weights are zeroed; hair weight is 0 as for
+ * the sprites.
+ */
+export function createOverlayLayers(renderer: any, sheet: any, images: any, buildGrid: any, alphaOf: any, baseWeights: any, cell: number | undefined, width: any, height: any, crop: any): {
+    /** Shows the named overlays and hides the rest. Unknown names are ignored. */
+    set(names: any): void;
+    update(P: any, phys: any, deformBase: any, out: any): void;
+};

package/dist/engine/rig.d.ts

@@ -1,5 +1,20 @@
 /** @param {import('../rig/types').Rig} rig */
 export function createRig(rig: import("../rig/types.js").Rig): {
+    legs: {
+        frame: (P: any) => any;
+        weights: (x: any, y: any) => {
+            right: number;
+            perBone: {
+                leg: number;
+                shin: number;
+                pin: number;
+            }[];
+        };
+        apply: (p: any, _x: any, y: any, w: any, P: any) => void;
+        pin: (y: any) => number;
+        step: (P: any, dt: any) => void;
+    } | null;
+    stepBody: (P: any, dt: any) => void | undefined;
     IMG: {
         w: number;
         h: number;
@@ -21,6 +36,18 @@ export function createRig(rig: import("../rig/types.js").Rig): {
     headWeight: (x: any, y: any) => number;
     turnWeight: (x: any, y: any) => number;
     baseWeights: (x: any, y: any, hair?: number) => {
+        arms?: {
+            arm: number;
+            forearm: number;
+        }[] | undefined;
+        legs?: {
+            right: number;
+            perBone: {
+                leg: number;
+                shin: number;
+                pin: number;
+            }[];
+        } | undefined;
         head: number;
         turn: number;
         strands: any[][];
@@ -40,7 +67,7 @@ export function createRig(rig: import("../rig/types.js").Rig): {
     };
     deformBase: (x: any, y: any, w: any, P: any, phys: any, out: any) => any;
     applyHead: (p: any, w: any, P: any, wTurn?: any) => void;
-    applyBody: (p: any, restY: any, P: any, chest?: number, breathW?: number, shoulder?: number) => void;
+    applyBody: (p: any, restY: any, P: any, chest: number | undefined, breathW: number | undefined, shoulder: number | undefined, legWeights: any) => void;
     handWeights: (x: any, y: any) => {
         arm: number;
         wrist: number;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { createMeshAvatar, LIVE_EXPRESSIONS } from './engine/index.js';
 export type { MeshAvatar, MeshAvatarOptions, LiveExpression } from './engine/index.js';
 export type { LipSyncSettings } from './engine/lip-sync.js';
-export type { Rig, Eye, Strand, Accessory, Hand, Ellipse, Point, Band } from './rig/types.js';
+export type { Rig, Eye, Strand, Accessory, Hand, Arm, Arms, Leg, Legs, Cloth, ClothTuning, Ellipse, Point, Band } from './rig/types.js';
 export { validateRig, parseRig } from './rig/validate.js';
 export { PARAMS } from './engine/rig.js';
 export type { LightingSettings } from './lighting/settings.js';
@@ -12,3 +12,4 @@ export { validateAvatarFiles } from './format/validate.js';
 export { packAvatar, unpackAvatar } from './format/zip.js';
 export { openAvatar, loadMeshAvatar } from './format/open.js';
 export type { AvatarPackage, AvatarSource, OpenAvatarOptions } from './format/open.js';
+export { ARM_DEFAULTS } from './engine/arms.js';