mesh-avatar 0.6.1 → 0.7.0

package/README.md

@@ -123,6 +123,11 @@ Avatars saved or exported in Studio carry these settings in `avatar.json.lipSync
 saved values. `setLipSync` is a partial update and works during playback. The optional
 `preset` field records the editor selection only; playback uses the three numbers.
 
+Live expressions can set their resting mouth opening in `avatar.json.expressions` or with the
+`expressions` option, for example `{ surprise: { mouthOpen: 0.45 } }` (the built-in value for
+surprise is 0.6). `loadMeshAvatar` applies the saved values; explicit option fields override them.
+An entry for `neutral` has no effect and is ignored.
+
 ## License
 
 The runtime is MIT licensed; see [LICENSE](./LICENSE). The browser bundle includes [fflate](https://github.com/101arrowz/fflate), with its MIT notice retained in the bundle.

package/dist/engine/expression-overlay.d.ts

@@ -1,4 +1,10 @@
-export function overlayTarget(name: any): {
+/**
+ * @param {string} name
+ * @param {Record<string, { mouthOpen?: number }>} [settings] optional per-expression values (see expression-settings.ts)
+ */
+export function overlayTarget(name: string, settings?: Record<string, {
+    mouthOpen?: number;
+}>): {
     eyeOpen: any;
     eyeOpenL: any;
     eyeSmile: any;
@@ -26,6 +32,10 @@ export namespace OVERLAY_EXPRESSIONS {
 }
 /** Smoothed switching. While neutral and settled the parameters pass through untouched. */
 export class ExpressionOverlay {
+    /** @param {Record<string, { mouthOpen?: number }>} [settings] parsed per-expression settings */
+    constructor(settings?: Record<string, {
+        mouthOpen?: number;
+    }>);
     /** @type {keyof typeof OVERLAY_EXPRESSIONS} */
     name: keyof typeof OVERLAY_EXPRESSIONS;
     mix: {
@@ -42,6 +52,9 @@ export class ExpressionOverlay {
         gy: 0;
         pitch: 0;
     };
+    settings: Record<string, {
+        mouthOpen?: number;
+    }>;
     /** @param {string} name */
     set(name: string): void;
     /** True while an expression is shown or still fading out. */

package/dist/engine/expression-settings.d.ts

@@ -0,0 +1,11 @@
+import { OVERLAY_EXPRESSIONS } from './expression-overlay.js';
+/** Per-expression settings for a live expression shown with `setExpression`. */
+export interface ExpressionMouthSettings {
+    /** Resting mouth opening, 0–1. Replaces the built-in value (surprise 0.6, the others 0). */
+    mouthOpen?: number;
+}
+/** Optional settings keyed by live expression name; an entry for `neutral` is ignored. */
+export type ExpressionSettings = Partial<Record<Exclude<keyof typeof OVERLAY_EXPRESSIONS, 'neutral'>, ExpressionMouthSettings>>;
+export declare function parseExpressionSettings(input: unknown): ExpressionSettings;
+/** Explicit settings override saved ones for each expression and field. */
+export declare function mergeExpressionSettings(saved?: ExpressionSettings, explicit?: ExpressionSettings): ExpressionSettings;

package/dist/engine/index.d.ts

@@ -2,6 +2,7 @@ import type { LightingSettings } from '../lighting/settings.js';
 import type { Rig, ClothTuning } from '../rig/types.js';
 import { OVERLAY_EXPRESSIONS } from './expression-overlay.js';
 import type { LipSyncSettings } from './lip-sync.js';
+import type { ExpressionSettings } from './expression-settings.js';
 export type LiveExpression = keyof typeof OVERLAY_EXPRESSIONS;
 export declare const LIVE_EXPRESSIONS: LiveExpression[];
 export interface MeshAvatarOptions {
@@ -14,6 +15,8 @@ export interface MeshAvatarOptions {
     fit?: 'contain' | 'cover';
     preserveMouthForm?: boolean;
     lipSync?: LipSyncSettings;
+    /** Optional per-expression settings for live expressions, such as `{ surprise: { mouthOpen: 0.45 } }`. */
+    expressions?: ExpressionSettings;
 }
 export interface MeshAvatar {
     readonly motions: {

package/dist/format/manifest.d.ts

@@ -1,4 +1,5 @@
 import { type LipSyncSettings } from '../engine/lip-sync.js';
+import { type ExpressionSettings } from '../engine/expression-settings.js';
 export interface AvatarManifest {
     format: 'mesh-avatar';
     version: 1;
@@ -11,6 +12,7 @@ export interface AvatarManifest {
         version: string;
     };
     lipSync?: LipSyncSettings;
+    expressions?: ExpressionSettings;
 }
 export declare function parseManifest(input: unknown): AvatarManifest;
 export declare function defaultManifest(name: string): AvatarManifest;

package/dist/index.d.ts

@@ -1,6 +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 { ExpressionSettings, ExpressionMouthSettings } from './engine/expression-settings.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';