@lovelace_lol/embody 0.0.8 → 0.0.9

package/dist/three/character.d.ts

@@ -0,0 +1,243 @@
+import { AnimationClip } from 'three';
+import type { Mesh, Object3D } from 'three';
+import { ThreeFrameApplier } from './index';
+import type { ThreeModelInspection } from './index';
+import type { ThreeModelReferencePose } from './reference-pose';
+import type { ThreeNativePlaybackEvent } from './nativePlayback';
+type JsonObject = Record<string, any>;
+export type RustEmbodyHostConfig = {
+    profileMode?: 'preset' | 'profile';
+    presetId?: string;
+    presetType?: string;
+    profile?: JsonObject;
+    meshes?: Mesh[];
+    referencePose?: ThreeModelReferencePose;
+};
+export type CharacterPlaybackOptions = JsonObject;
+export type CharacterPlaybackEvent = ThreeNativePlaybackEvent & {
+    actionId: string;
+    clipName: string;
+};
+export interface CharacterPlaybackHandle {
+    readonly name: string;
+    actionId?: string;
+    promise: Promise<CharacterPlaybackEvent>;
+    readonly finished: Promise<CharacterPlaybackEvent>;
+    play(): CharacterPlaybackHandle;
+    stop(): CharacterPlaybackHandle;
+    cancel(): CharacterPlaybackHandle;
+    pause(): CharacterPlaybackHandle;
+    resume(): CharacterPlaybackHandle;
+    setWeight(value: number): CharacterPlaybackHandle;
+    setIntensity(value: number): CharacterPlaybackHandle;
+    setSpeed(value: number): CharacterPlaybackHandle;
+    setPlaybackRate(value: number): CharacterPlaybackHandle;
+    setTime(value: number): CharacterPlaybackHandle;
+    seek(value: number): CharacterPlaybackHandle;
+    updateParams(value: CharacterPlaybackOptions): CharacterPlaybackHandle;
+    setParams(value: CharacterPlaybackOptions): CharacterPlaybackHandle;
+    subscribe(listener: ((event: CharacterPlaybackEvent) => void) | {
+        next(event: CharacterPlaybackEvent): void;
+    }): () => void;
+}
+export interface CharacterTransitionHandle {
+    promise: Promise<void>;
+    pause(): void;
+    resume(): void;
+    cancel(): void;
+}
+export declare function supportsRustEmbodyPreset(value?: string): boolean;
+/** Character commands compile in Rust and play exclusively on the native connector. */
+export declare class Embody {
+    private readonly config;
+    readonly meshes: Mesh[];
+    meshByName: Map<string, Mesh<import("three").BufferGeometry<import("three").NormalBufferAttributes, import("three").BufferGeometryEventMap>, import("three").Material<import("three").MaterialEventMap> | import("three").Material<import("three").MaterialEventMap>[], import("three").Object3DEventMap>>;
+    bones: ThreeModelInspection['bones'];
+    private readonly wasm;
+    private core;
+    private readonly inspector;
+    private readonly applier;
+    private readonly references;
+    private referenceBindings;
+    private boundModel?;
+    get model(): Object3D | undefined;
+    private inspection?;
+    private connector?;
+    private profile;
+    private profileSource;
+    private readonly profileMode;
+    private readonly preset;
+    private readonly sources;
+    private readonly playbacks;
+    private readonly current;
+    private playDepth;
+    private readonly pendingEvents;
+    private bindingGeneration;
+    private disposed;
+    private rendering;
+    private timeScale;
+    private nextLiveTarget;
+    private readonly liveTargets;
+    private readonly hairObjects;
+    private hairConfig;
+    private hairAppearance;
+    constructor(config?: RustEmbodyHostConfig);
+    static create(config?: RustEmbodyHostConfig): Promise<Embody>;
+    private assertAlive;
+    private requireModel;
+    private requireConnector;
+    private validateProfile;
+    private resolveProfile;
+    onReady(options: {
+        model: Object3D;
+        meshes?: Mesh[];
+        animations?: AnimationClip[];
+        referencePose?: ThreeModelReferencePose;
+    }): void;
+    private bind;
+    bindModel(meshes?: Mesh[]): void;
+    extendReferencePose(): ThreeModelReferencePose;
+    setProfile(value: JsonObject): void;
+    getProfile(): JsonObject;
+    getProfileMode(): 'preset' | 'profile';
+    getPresetId(): string | null;
+    supportsPreset(value?: string): boolean;
+    private onPlaybackEvent;
+    private compile;
+    private restValues;
+    private materialize;
+    private applyEasing;
+    private nativeOptions;
+    private validateEasing;
+    private handle;
+    private forget;
+    private updatePlayback;
+    registerAnimationClips(clips: AnimationClip[]): void;
+    loadAnimationClips(clips: AnimationClip[]): void;
+    removeAnimationClip(name: string): boolean;
+    getAnimationClips(): any[];
+    playAnimation(name: string, options?: CharacterPlaybackOptions): CharacterPlaybackHandle;
+    private build;
+    buildClip(name: string, curves: JsonObject, options?: CharacterPlaybackOptions): CharacterPlaybackHandle;
+    snippetToClip(name: string, curves: JsonObject, options?: CharacterPlaybackOptions): CharacterPlaybackHandle;
+    buildTypedClip(name: string, channels: any[], options?: CharacterPlaybackOptions): CharacterPlaybackHandle;
+    typedSnippetToClip(name: string, channels: any[], options?: CharacterPlaybackOptions): CharacterPlaybackHandle;
+    semanticAnimationToClip(name: string, animation: JsonObject, options?: CharacterPlaybackOptions): CharacterPlaybackHandle;
+    playSnippet(snippet: string | {
+        name: string;
+        curves: JsonObject;
+    }, curvesOrOptions?: JsonObject, options?: CharacterPlaybackOptions): CharacterPlaybackHandle;
+    playTypedSnippet(snippet: {
+        name: string;
+        channels: any[];
+    }, options?: CharacterPlaybackOptions): CharacterPlaybackHandle;
+    playClip(value: string | CharacterPlaybackHandle): CharacterPlaybackHandle;
+    supportsClipCurves(): boolean;
+    cleanupSnippet(name: string): void;
+    crossfadeTo(name: string, seconds: number, options?: CharacterPlaybackOptions): CharacterPlaybackHandle;
+    stopAnimation(name: string): void;
+    stopAllAnimations(): void;
+    pauseAnimation(name: string): void;
+    resumeAnimation(name: string): void;
+    pauseAllAnimations(): void;
+    resumeAllAnimations(): void;
+    updateClipParams(name: string, options: CharacterPlaybackOptions): void;
+    setAnimationSpeed(name: string, value: number): void;
+    setAnimationIntensity(name: string, value: number): void;
+    setAnimationLoop(name: string, value: boolean): void;
+    setAnimationLoopMode(name: string, value: string): void;
+    setAnimationRepeatCount(name: string, value: number | null): void;
+    setAnimationReverse(name: string, value: boolean): void;
+    setAnimationBlendMode(name: string, value: string): void;
+    setAnimationEasing(name: string, value: string): void;
+    seekAnimation(name: string, value: number): void;
+    setAnimationTime(name: string, value: number): void;
+    setSnippetTime(name: string, value: number): void;
+    seekSnippet(name: string, value: number): void;
+    seek(name: string, value: number): void;
+    setAnimationTimeScale(value: number): void;
+    getAnimationState(name: string): JsonObject;
+    getPlayingAnimations(): string[];
+    private commitLive;
+    private mutateLive;
+    private transition;
+    setAU(id: number, value: number, balance?: number): void;
+    getAU(id: number): number;
+    getAUBalance(id: number): number;
+    getBodyControls(): any[];
+    getSemanticPoseCatalog(): any[];
+    captureSemanticPose(): JsonObject;
+    validateSemanticPose(pose: JsonObject): JsonObject;
+    applySemanticPose(pose: JsonObject): void;
+    validateSemanticAnimation(animation: JsonObject, options?: JsonObject): void;
+    resetBodyControls(): void;
+    setContinuum(negative: number, positive: number, value: number, balance?: number): void;
+    getContinuum(negative: number, positive: number): number;
+    transitionAU(id: number, value: number, durationMs?: number, balance?: number): CharacterTransitionHandle;
+    setViseme(index: number, value: number, jawScale?: number): void;
+    getViseme(index: number): number;
+    getVisemeJawScale(index: number): number;
+    setVisemeById(id: string, value: number, jawScale?: number): void;
+    transitionViseme(index: number, value: number, durationMs?: number, jawScale?: number): CharacterTransitionHandle;
+    transitionVisemeById(id: string, value: number, durationMs?: number, jawScale?: number): CharacterTransitionHandle;
+    setAUMixWeight(id: number, value: number): void;
+    getAUMixWeight(id: number): number;
+    hasLeftRightBones(id: number): boolean;
+    setMorph(key: string | number, value: number, meshNames?: string[]): void;
+    setMorphOnMeshes(meshNames: string[], key: string | number, value: number): void;
+    releaseMorph(key: string | number, meshNames?: string[]): void;
+    transitionMorph(key: string | number, value: number, durationMs?: number, meshNames?: string[]): CharacterTransitionHandle;
+    getMorphTargets(): Record<string, string[]>;
+    getMorphTargetIndices(): Record<string, {
+        name: string;
+        index: number;
+    }[]>;
+    addMorphTarget(target: Parameters<ThreeFrameApplier['addMorphTarget']>[1], options?: Parameters<ThreeFrameApplier['addMorphTarget']>[2]): number;
+    addMorphTargets(targets: Parameters<ThreeFrameApplier['addMorphTargets']>[1], options?: Parameters<ThreeFrameApplier['addMorphTargets']>[2]): Record<string, number>;
+    private meshCategory;
+    getMeshList(): JsonObject[];
+    getBones(): ThreeModelInspection['bones'];
+    private meshProfile;
+    setMeshVisible(name: string, visible: boolean): void;
+    highlightMesh(name: string | null, color?: number, value?: number): void;
+    getMeshMaterialConfig(name: string): Record<string, unknown> | null;
+    setMeshMaterialConfig(name: string, value: Parameters<ThreeFrameApplier['setMeshMaterialConfig']>[2]): void;
+    registerHairObjects(objects: Object3D[]): {
+        name: string;
+        isMesh: boolean;
+        isEyebrow: boolean;
+    }[];
+    getRegisteredHairObjects(): Object3D[];
+    getHairMorphTargets(name?: string): string[];
+    getHairAppearance(): JsonObject;
+    private setHairAppearance;
+    setHairColor(value: string | JsonObject): void;
+    setEyebrowColor(value: string | JsonObject): void;
+    setHairBaseColor(value: string): void;
+    setEyebrowBaseColor(value: string): void;
+    setHairGlow(color: string, value: number): void;
+    setEyebrowGlow(color: string, value: number): void;
+    setHairOutline(value: {
+        show: boolean;
+        color?: string;
+        opacity?: number;
+    }): void;
+    private restartHair;
+    setHairPhysicsEnabled(value: boolean): void;
+    isHairPhysicsEnabled(): boolean;
+    setHairPhysicsConfig(value: JsonObject): void;
+    getHairPhysicsConfig(): JsonObject;
+    validateHairMorphTargets(): string[];
+    applyHairStateToObject(name: string, state: JsonObject): void;
+    private authoredHeadMotion;
+    private setHairGravity;
+    playHairImpulse(horizontal: number, vertical: number): CharacterPlaybackHandle | undefined;
+    start(): void;
+    stop(): void;
+    clear(): void;
+    resetToNeutral(): void;
+    dispose(): void;
+}
+export declare function createRustEmbodyHostUnbound(config?: RustEmbodyHostConfig): Embody;
+export declare function createRustEmbodyHost(model: Object3D, config?: RustEmbodyHostConfig): Promise<Embody>;
+export {};

package/dist/three/characterHost.d.ts

@@ -0,0 +1,48 @@
+import type { Camera, Scene } from 'three';
+import { Embody } from './character';
+import type { RustEmbodyHostConfig } from './character';
+import type { CharacterModelLoadOptions, CharacterModelLoadResult, CharacterModelTransform } from './model';
+import type { CharacterSceneBackend, CharacterSceneRenderer, CharacterSceneRenderingController, DefaultCharacterSceneAsyncOptions, ReadyDefaultCharacterScene } from './scene';
+import type { Profile } from './authoringTypes';
+export interface CharacterHostCharacterOptions extends CharacterModelTransform {
+    modelUrl: string;
+    presetType?: string;
+    profile?: Profile;
+}
+export interface CharacterHostExternalScene {
+    scene: Scene;
+    renderer: CharacterSceneRenderer;
+    backend?: CharacterSceneBackend;
+    rendering?: CharacterSceneRenderingController;
+    camera: Camera;
+    mountCanvas?: boolean;
+    manageResize?: boolean;
+}
+export interface CharacterHostOptions {
+    signal?: AbortSignal;
+    container: HTMLElement;
+    character: CharacterHostCharacterOptions;
+    embody?: RustEmbodyHostConfig;
+    scene?: Omit<DefaultCharacterSceneAsyncOptions, 'signal'>;
+    external?: CharacterHostExternalScene;
+    loader?: CharacterModelLoadOptions;
+    autoStart?: boolean;
+    renderLoop?: boolean;
+    autoFrame?: boolean;
+}
+export interface CharacterHost extends Omit<CharacterModelLoadResult, 'gltf'> {
+    engine: Embody;
+    scene: Scene;
+    readonly renderer: CharacterSceneRenderer | null;
+    readonly backend: CharacterSceneBackend | null;
+    readonly rendering: CharacterSceneRenderingController | null;
+    camera: Camera;
+    lighting: ReadyDefaultCharacterScene['lighting'] | null;
+    ownsScene: boolean;
+    container: HTMLElement;
+    setCharacter(character: CharacterHostCharacterOptions, loader?: CharacterModelLoadOptions): Promise<void>;
+    resize(): void;
+    dispose(): Promise<void>;
+}
+/** Acquire a character and bind it to the existing Three rendering integration. */
+export declare function createCharacterHost(options: CharacterHostOptions): Promise<CharacterHost>;

package/dist/three/clipBindings.d.ts

@@ -0,0 +1,6 @@
+import type { AnimationClip } from 'three';
+import type { ClipIRTrack, ThreeModelInspection } from './index';
+/** One PropertyMixer cache key for every concrete renderer destination. */
+export declare function concreteTrackName(target: ClipIRTrack['target'] | undefined, inspection: ThreeModelInspection): string | undefined;
+/** Retain authored samples and interpolants; normalize only cloned binding names. */
+export declare function cloneWithConcreteTrackNames(clip: AnimationClip, tracks: readonly ClipIRTrack[], inspection: ThreeModelInspection): AnimationClip;

package/dist/three/index.d.ts

@@ -1,11 +1,15 @@
 import { AnimationClip } from 'three';
 export * from './annotations/index';
+export * from './authoring';
+export * from './character';
+export * from './characterHost';
+export { renderScenePlayback, createScenePlaybackFrame } from './playbackRendering';
 import type { ThreeModelReferencePose } from './reference-pose';
 export { captureModelReferencePose, bindModelReferencePose, extendModelReferencePose } from './reference-pose';
 export type { ThreeModelReferencePose, ThreeReferencePoseNode } from './reference-pose';
+export { ThreeNativePlaybackConnector } from './nativePlayback';
+export type { ThreeNativeLoop, ThreeNativePlaybackOptions, ThreeNativePlaybackControl, ThreeNativePlaybackEvent, ThreeNativePlaybackBinding, } from './nativePlayback';
 import type { Material, Mesh, Object3D } from 'three';
-export { ThreeGazeFocus } from './gaze';
-export type { ThreeGazeFocusOptions, ThreeGazeFocusRequest, ThreeGazeFocusControls, ThreeGazeFocusDiagnostic } from './gaze';
 export declare const THREE_BLENDING_MODES: {
     readonly Normal: 1;
     readonly Additive: 2;
@@ -13,6 +17,13 @@ export declare const THREE_BLENDING_MODES: {
     readonly Multiply: 4;
     readonly None: 0;
 };
+export declare const BLENDING_MODES: {
+    readonly Normal: 1;
+    readonly Additive: 2;
+    readonly Subtractive: 3;
+    readonly Multiply: 4;
+    readonly None: 0;
+};
 type BoneEntry = {
     obj: Object3D;
     basePos: {
@@ -43,7 +54,15 @@ type AddMorphTargetOptions = {
     resetInfluence?: boolean;
 };
 export type ThreeModelInspection = {
-    descriptor: Record<string, unknown>;
+    descriptor: Record<string, unknown> & {
+        morphTargets: Array<{
+            id: number;
+            meshId: number | undefined;
+            name: string;
+            hostIndex: number;
+            initialValue: number;
+        }>;
+    };
     meshByName: Map<string, Mesh>;
     allMeshes: Mesh[];
     morphMeshes: Mesh[];
@@ -86,6 +105,11 @@ export type ClipIRTrack = {
 export type ClipIR = {
     name: string;
     durationSeconds?: number;
+    channels?: Array<{
+        id: number;
+        kind: string;
+        name?: string;
+    }>;
     tracks: ClipIRTrack[];
 };
 /**
@@ -107,7 +131,7 @@ export declare function serializeAnimationClips(model: Object3D, clips: readonly
         kind: string;
         name: string;
     }[];
-    tracks: Record<string, unknown>[];
+    tracks: ClipIRTrack[];
 }[];
 type MaterialConfig = {
     renderOrder?: number;

package/dist/three/nativePlayback.d.ts

@@ -0,0 +1,121 @@
+import { AnimationMixer } from 'three';
+import type { AnimationAction, AnimationClip, Object3D } from 'three';
+import type { NativePlaybackSession } from '../wasm/index';
+import type { ClipIR, ThreeModelInspection } from './index';
+export type ThreeNativeLoop = {
+    mode: 'once' | 'repeat' | 'pingPong';
+    count?: number | null;
+};
+export type ThreeNativePlaybackOptions = {
+    replace?: string;
+    startSeconds?: number;
+    speed?: number;
+    /** Native contribution only; semantic intensity belongs in the compiled clip. */
+    weight?: number;
+    blendMode?: 'normal' | 'additive';
+    loop?: ThreeNativeLoop;
+    finalPose?: 'release' | 'hold';
+};
+export type ThreeNativePlaybackControl = {
+    type: 'pause' | 'resume' | 'stop';
+} | {
+    type: 'seek';
+    seconds: number;
+} | {
+    type: 'setSpeed';
+    speed: number;
+} | {
+    type: 'setWeight';
+    weight: number;
+} | {
+    type: 'setBlendMode';
+    blendMode: 'normal' | 'additive';
+} | {
+    type: 'setLoop';
+    loop: ThreeNativeLoop;
+} | {
+    type: 'setFinalPose';
+    finalPose: 'release' | 'hold';
+} | {
+    type: 'fadeIn' | 'fadeOut';
+    seconds: number;
+};
+export type ThreeNativePlaybackEvent = {
+    type: 'completed';
+    handle: string;
+} | {
+    type: 'cancelled';
+    handle: string;
+    reason: string;
+} | {
+    type: 'error';
+    handle: string;
+    message: string;
+};
+export type ThreeNativePlaybackBinding = {
+    model: Object3D;
+    inspection: ThreeModelInspection;
+    /** Optional existing native mixer. Otherwise the connector owns one. */
+    mixer?: AnimationMixer;
+};
+/**
+ * Execute validated Rust commands on the native mixer. There is no
+ * clock or update API. Each play owns a unique clip/action; other mixer users
+ * remain untouched by stop, replacement, rebind and disposal.
+ *
+ * The connector owns the supplied Wasm session and frees it after successful
+ * disposal. A failed release retains ownership and can be retried by dispose.
+ */
+export declare class ThreeNativePlaybackConnector {
+    private readonly session;
+    private binding;
+    private rendering;
+    private renderingEnabled;
+    private readonly resources;
+    private readonly actionHandles;
+    private readonly listeners;
+    private readonly pending;
+    private readonly notifications;
+    private depth;
+    private flushingNotifications;
+    private notificationScheduled;
+    private sessionDisposed;
+    private disposed;
+    private readonly onError?;
+    private readonly onRelease?;
+    constructor(session: NativePlaybackSession, binding: ThreeNativePlaybackBinding & {
+        onError?: (error: Error) => void;
+        onRelease?: (handle: string) => void;
+    });
+    /** Prepare bindings first; old actions are released before the new binding is exposed. */
+    rebind(modelKey: string, profileKey: string, binding?: ThreeNativePlaybackBinding): void;
+    play(clip: ClipIR, options?: ThreeNativePlaybackOptions): string;
+    /**
+     * Validate native track bindings through the existing serializer, then retain
+     * the native clone's interpolants and authored/additive sample values. Concrete
+     * binding names match compiled tracks so Three shares their PropertyMixer.
+     */
+    playNativeClip(clip: AnimationClip, options?: ThreeNativePlaybackOptions): string;
+    control(handle: string, control: ThreeNativePlaybackControl): void;
+    setRendering(enabled: boolean): void;
+    setTimeScale(value: number): void;
+    fadeIn(handle: string, seconds: number): void;
+    fadeOut(handle: string, seconds: number): void;
+    /** Edit authored samples, retaining the native action and its loop/fade progress. */
+    replaceClip(handle: string, clip: AnimationClip): void;
+    /** Native state for the owning adapter; never exposed through Polymer. */
+    getAction(handle: string): AnimationAction | undefined;
+    /** Deliver native completion after the borrowed mixer has finished sampling. */
+    flushEvents(): void;
+    subscribe(listener: (event: ThreeNativePlaybackEvent) => void): () => void;
+    dispose(): void;
+    private pauseFade;
+    private resumeFade;
+    private beforeOperation;
+    private retryPending;
+    private dispatch;
+    private drain;
+    private execute;
+    private readonly finished;
+    private flushNotifications;
+}

package/dist/three/playbackRendering.d.ts

@@ -0,0 +1,14 @@
+import { Timer } from 'three';
+import type { AnimationMixer, Object3D } from 'three';
+/** Register native playback with the existing scene renderer; never starts a loop. */
+export declare function bindPlaybackRendering(model: Object3D, mixer: AnimationMixer, afterFrame: () => void): {
+    setEnabled(enabled: boolean): void;
+    dispose(): void;
+};
+/** Called once by the Three render integration, using its native Timer. */
+export declare function renderScenePlayback(scene: Object3D, timer: Timer): void;
+/** Frame hook for an existing Three/R3F renderer. Does not create a render loop. */
+export declare function createScenePlaybackFrame(scene: Object3D, document?: Document): {
+    onFrame(timestamp?: number): void;
+    dispose(): void;
+};