@doki-land/live2d 0.0.22 → 0.0.24

package/src/stage/actor-model-slot.ts

@@ -11,12 +11,28 @@ import type {
     ParameterBinding,
     Renderer,
 } from "@doki-land/live2d-renderer";
+import {
+    applyExpression3Clip,
+    type Expression3Clip,
+    parseExpression3,
+} from "../expression/index.js";
 import {
     MotionPlayer,
     MotionPriority,
     type PlayMotionOptions,
     parseMotion3,
 } from "../motion/index.js";
+import {
+    applyPhysics3,
+    type Physics3Clip,
+    parsePhysics3,
+} from "../physics/index.js";
+import {
+    applyPose3Activation,
+    type Pose3Clip,
+    parsePose3,
+} from "../pose/index.js";
+import { resolveHitAreaName } from "./hit-area.js";
 import type {
     ModelAssetLease,
     ModelAssetRegistry,
@@ -54,6 +70,14 @@ export class ActorModelSlot {
     #loadGeneration = 0;
     readonly #paramById = new Map<string, ParameterBinding>();
     readonly #paramIndexById = new Map<string, number>();
+    #expressionCache = new Map<string, Expression3Clip>();
+    #activeExpression: {
+        name: string;
+        clip: Expression3Clip;
+        weight: number;
+    } | null = null;
+    #poseClip: Pose3Clip | null = null;
+    #physicsClip: Physics3Clip | null = null;
 
     constructor(options: ActorModelSlotOptions) {
         this.#assets = options.assets;
@@ -95,16 +119,9 @@ export class ActorModelSlot {
             if (s.weight <= 0) continue;
             if (s.target === "PartOpacity") {
                 if (!this.#backend.setPartOpacity) continue;
-                if (s.weight >= 1) {
-                    this.#backend.setPartOpacity(this.#model, s.id, s.value);
-                } else {
-                    const cur = 1;
-                    this.#backend.setPartOpacity(
-                        this.#model,
-                        s.id,
-                        cur + (s.value - cur) * s.weight,
-                    );
-                }
+                const value =
+                    s.weight >= 1 ? s.value : 1 + (s.value - 1) * s.weight;
+                this.#setPartOpacityWithPose(s.id, value);
                 continue;
             }
             if (s.target !== "Parameter" || !this.#backend.setParameter)
@@ -120,6 +137,84 @@ export class ActorModelSlot {
                 cur + (s.value - cur) * s.weight,
             );
         }
+        this.#syncParamCacheFromBackend();
+    }
+
+    #setPartOpacityWithPose(partId: string, opacity: number): void {
+        if (!this.#model || !this.#backend?.setPartOpacity) return;
+        if (this.#poseClip && opacity > 0) {
+            applyPose3Activation(this.#poseClip, partId, (id, value) => {
+                this.#backend?.setPartOpacity?.(this.#model!, id, value);
+            });
+            return;
+        }
+        this.#backend.setPartOpacity(this.#model, partId, opacity);
+    }
+
+    #syncParamCacheFromBackend(): void {
+        if (!this.#model || !this.#backend?.listParameters) return;
+        for (const p of this.#backend.listParameters(this.#model)) {
+            const cached = this.#paramById.get(p.id);
+            if (cached) (cached as { value: number }).value = p.value;
+        }
+    }
+
+    #tickExpression(deltaTimeSeconds: number): void {
+        if (!this.#activeExpression) return;
+        const fadeSeconds = 0.25;
+        const step = deltaTimeSeconds / Math.max(0.001, fadeSeconds);
+        this.#activeExpression.weight = Math.min(
+            1,
+            this.#activeExpression.weight + step,
+        );
+    }
+
+    #applyExpressionLayer(): void {
+        if (!this.#activeExpression || !this.#model || !this.#backend) return;
+        applyExpression3Clip(
+            this.#activeExpression.clip,
+            this.#activeExpression.weight,
+            this.#paramById,
+            (id, value) =>
+                this.#backend?.setParameter?.(this.#model!, id, value),
+        );
+        this.#syncParamCacheFromBackend();
+    }
+
+    async #loadPoseClip(): Promise<void> {
+        this.#poseClip = null;
+        const posePath = this.#model?.settings.pose;
+        if (!posePath || !this.#lease) return;
+        try {
+            const json = await this.#lease.resolver.fetchJson(posePath);
+            this.#poseClip = parsePose3(json);
+        } catch {
+            this.#poseClip = null;
+        }
+    }
+
+    async #loadPhysicsClip(): Promise<void> {
+        this.#physicsClip = null;
+        const physicsPath = this.#model?.settings.physics;
+        if (!physicsPath || !this.#lease) return;
+        try {
+            const json = await this.#lease.resolver.fetchJson(physicsPath);
+            this.#physicsClip = parsePhysics3(json);
+        } catch {
+            this.#physicsClip = null;
+        }
+    }
+
+    #applyPhysicsLayer(deltaTimeSeconds: number): void {
+        if (!this.#physicsClip || !this.#model || !this.#backend) return;
+        applyPhysics3(
+            this.#physicsClip,
+            deltaTimeSeconds,
+            this.#paramById,
+            (id, value) =>
+                this.#backend?.setParameter?.(this.#model!, id, value),
+        );
+        this.#syncParamCacheFromBackend();
     }
 
     #rebuildParamCache(): void {
@@ -158,8 +253,17 @@ export class ActorModelSlot {
     async load(
         source: ModelSource,
         resolver?: AssetResolver,
+        options?: { signal?: AbortSignal },
     ): Promise<InternalModel> {
         const gen = ++this.#loadGeneration;
+        const signal = options?.signal;
+        if (signal?.aborted) {
+            throw new Error("@doki-land/live2d: load cancelled");
+        }
+        const onAbort = () => {
+            this.#loadGeneration += 1;
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
         this.#report({
             stage: "mounting",
             progress: 0.01,
@@ -167,15 +271,22 @@ export class ActorModelSlot {
         });
         const drawPass = this.ensureDrawPass();
 
-        const lease = await this.#assets.acquire(source, resolver, (p) =>
-            this.#report(p),
-        );
-        if (gen !== this.#loadGeneration) {
-            lease.release();
-            throw new Error("@doki-land/live2d: load cancelled");
-        }
+        try {
+            const lease = await this.#assets.acquire(
+                source,
+                resolver,
+                (p) => this.#report(p),
+                { signal },
+            );
+            if (gen !== this.#loadGeneration) {
+                lease.release();
+                throw new Error("@doki-land/live2d: load cancelled");
+            }
 
-        return await this.#attachLease(lease, drawPass, gen);
+            return await this.#attachLease(lease, drawPass, gen);
+        } finally {
+            signal?.removeEventListener("abort", onAbort);
+        }
     }
 
     async loadAsset(asset: ModelAsset): Promise<InternalModel> {
@@ -208,6 +319,9 @@ export class ActorModelSlot {
         gen: number,
     ): Promise<InternalModel> {
         this.#motionPlayer.clear();
+        this.#activeExpression = null;
+        this.#poseClip = null;
+        this.#physicsClip = null;
         this.#releaseLease();
 
         const { model, backend } = await lease.createInstance(this.#renderer);
@@ -226,6 +340,8 @@ export class ActorModelSlot {
         this.#model = model;
         this.#backend = backend;
         this.#rebuildParamCache();
+        await this.#loadPoseClip();
+        await this.#loadPhysicsClip();
         this.#report({
             stage: "ready",
             progress: 1,
@@ -251,6 +367,30 @@ export class ActorModelSlot {
         return this.#model?.settings.motionGroups ?? {};
     }
 
+    listExpressions(): readonly import("@doki-land/live2d-core").ExpressionDefinition[] {
+        return this.#model?.settings.expressions ?? [];
+    }
+
+    async setExpression(name: string | null): Promise<boolean> {
+        if (!this.#model || !this.#lease) return false;
+        if (name === null) {
+            this.#activeExpression = null;
+            return true;
+        }
+        const def = this.#model.settings.expressions.find(
+            (item) => item.name === name,
+        );
+        if (!def) return false;
+        let clip = this.#expressionCache.get(def.file);
+        if (!clip) {
+            const json = await this.#lease.resolver.fetchJson(def.file);
+            clip = parseExpression3(json);
+            this.#expressionCache.set(def.file, clip);
+        }
+        this.#activeExpression = { name, clip, weight: 0 };
+        return true;
+    }
+
     async playMotion(
         group: string,
         index = 0,
@@ -301,6 +441,9 @@ export class ActorModelSlot {
     update(deltaTimeSeconds: number): DrawableMesh[] | null {
         if (!this.#model || !this.#backend || !this.#drawPass) return null;
         this.#applyMotionSamples(this.#motionPlayer.update(deltaTimeSeconds));
+        this.#tickExpression(deltaTimeSeconds);
+        this.#applyExpressionLayer();
+        this.#applyPhysicsLayer(deltaTimeSeconds);
         this.#backend.updateModel(this.#model, deltaTimeSeconds);
         return this.#backend.getDrawables(this.#model);
     }
@@ -332,10 +475,15 @@ export class ActorModelSlot {
                     (s >= 0 && s1 >= 0 && s2 >= 0) ||
                     (s <= 0 && s1 <= 0 && s2 <= 0)
                 ) {
-                    const hitArea = this.#model.settings.hitAreas.find(
-                        (h) => h.id === `D_${d.index}` || h.id === `${d.index}`,
+                    const artMeshId = this.#backend.getDrawableArtMeshId?.(
+                        this.#model,
+                        d.index,
                     );
-                    return hitArea?.name ?? `drawable:${d.index}`;
+                    return resolveHitAreaName({
+                        hitAreas: this.#model.settings.hitAreas,
+                        drawableIndex: d.index,
+                        artMeshId,
+                    });
                 }
             }
         }
@@ -345,6 +493,9 @@ export class ActorModelSlot {
     destroy(): void {
         this.#loadGeneration += 1;
         this.#motionPlayer.clear();
+        this.#activeExpression = null;
+        this.#poseClip = null;
+        this.#physicsClip = null;
         if (this.#model && this.#backend) {
             this.#backend.destroyModel(this.#model);
         }

package/src/stage/actor.ts

@@ -53,9 +53,35 @@ export class Live2dActorImpl implements Live2dActor {
         this.#slot = new ActorModelSlot({
             assets: shared.assets,
             renderer: shared.renderer,
+            onMotionStart: (payload) => this.#onMotionStart?.(payload),
+            onMotionFinish: (payload) => this.#onMotionFinish?.(payload),
         });
     }
 
+    #onMotionStart:
+        | ((payload: { group: string; index: number; slot: string }) => void)
+        | null = null;
+    #onMotionFinish:
+        | ((payload: { group: string; index: number; slot: string }) => void)
+        | null = null;
+
+    /** Bridge MotionPlayer lifecycle into Stage/facade event buses. */
+    setMotionEventHandlers(handlers: {
+        onStart?: (payload: {
+            group: string;
+            index: number;
+            slot: string;
+        }) => void;
+        onFinish?: (payload: {
+            group: string;
+            index: number;
+            slot: string;
+        }) => void;
+    }): void {
+        this.#onMotionStart = handlers.onStart ?? null;
+        this.#onMotionFinish = handlers.onFinish ?? null;
+    }
+
     get model(): InternalModel | null {
         return this.#slot.model;
     }
@@ -106,11 +132,12 @@ export class Live2dActorImpl implements Live2dActor {
     async load(
         source: Parameters<Live2dActor["load"]>[0],
         resolver?: Parameters<Live2dActor["load"]>[1],
+        options?: { signal?: AbortSignal },
     ): Promise<InternalModel> {
         if (this.#destroyed) {
             throw new Error("@doki-land/live2d: actor destroyed");
         }
-        return await this.#slot.load(source, resolver);
+        return await this.#slot.load(source, resolver, options);
     }
 
     async loadAsset(asset: ModelAsset): Promise<InternalModel> {
@@ -160,6 +187,14 @@ export class Live2dActorImpl implements Live2dActor {
         return this.#slot.listPlayingMotions();
     }
 
+    listExpressions() {
+        return this.#slot.listExpressions();
+    }
+
+    setExpression(name: string | null) {
+        return this.#slot.setExpression(name);
+    }
+
     lookAt(stageX: number, stageY: number): void {
         const { dragX, dragY } = stageFocusDrag(
             stageX,

package/src/stage/hit-area.ts

@@ -0,0 +1,24 @@
+import type { HitAreaDefinition } from "@doki-land/live2d-core";
+
+export interface ResolveHitAreaInput {
+    readonly hitAreas: readonly HitAreaDefinition[];
+    readonly drawableIndex: number;
+    /** Art-mesh / drawable id from MOC when available. */
+    readonly artMeshId?: string | null;
+}
+
+/**
+ * Resolve a triangle hit to a named HitArea when settings id matches the drawable.
+ * Falls back to `drawable:N` when no mapping exists.
+ */
+export function resolveHitAreaName(input: ResolveHitAreaInput): string {
+    const { hitAreas, drawableIndex, artMeshId } = input;
+    const candidates = new Set<string>();
+    if (artMeshId) candidates.add(artMeshId);
+    candidates.add(`D_${drawableIndex}`);
+    candidates.add(`${drawableIndex}`);
+    for (const area of hitAreas) {
+        if (candidates.has(area.id)) return area.name;
+    }
+    return `drawable:${drawableIndex}`;
+}

package/src/stage/index.ts

@@ -1,8 +1,12 @@
 export { allocateActorId, Live2dActorImpl } from "./actor.js";
 export { ActorModelSlot } from "./actor-model-slot.js";
 export {
-    type CreateLive2DOptions,
+    type CreateLive2dOptions,
     createSingleActorFacade,
+    type Live2dRuntime,
+    /** @deprecated Use `CreateLive2dOptions`. */
+    type CreateLive2DOptions,
+    /** @deprecated Use `Live2dRuntime`. */
     type Live2DRuntime,
 } from "./single-facade.js";
 export { createLive2dStage, Live2dStageImpl } from "./stage.js";

package/src/stage/model-asset-registry.ts

@@ -103,8 +103,14 @@ export class ModelAssetRegistry implements Live2dStageAssets {
         source: ModelSource,
         resolver: AssetResolver | undefined,
         onProgress?: (payload: LoadProgress) => void,
+        options?: { signal?: AbortSignal },
     ): Promise<ModelAssetLease> {
-        const entry = await this.#ensureEntry(source, resolver, onProgress);
+        const entry = await this.#ensureEntry(
+            source,
+            resolver,
+            onProgress,
+            options,
+        );
         entry.refCount += 1;
         return this.#leaseFromEntry(entry);
     }
@@ -166,6 +172,7 @@ export class ModelAssetRegistry implements Live2dStageAssets {
         source: ModelSource,
         resolver?: AssetResolver,
         onProgress?: (payload: LoadProgress) => void,
+        options?: { signal?: AbortSignal },
     ): Promise<SharedModelAssetEntry> {
         const key = resolveModelAssetKey(source);
         const existing = this.#entries.get(key);
@@ -173,7 +180,13 @@ export class ModelAssetRegistry implements Live2dStageAssets {
 
         let pending = this.#inFlight.get(key);
         if (!pending) {
-            pending = this.#compileEntry(key, source, resolver, onProgress);
+            pending = this.#compileEntry(
+                key,
+                source,
+                resolver,
+                onProgress,
+                options,
+            );
             this.#inFlight.set(key, pending);
         }
         try {
@@ -190,8 +203,13 @@ export class ModelAssetRegistry implements Live2dStageAssets {
         source: ModelSource,
         resolver: AssetResolver | undefined,
         onProgress?: (payload: LoadProgress) => void,
+        options?: { signal?: AbortSignal },
     ): Promise<SharedModelAssetEntry> {
         const notify = (payload: LoadProgress) => onProgress?.(payload);
+        const signal = options?.signal;
+        if (signal?.aborted) {
+            throw new Error("@doki-land/live2d: load cancelled");
+        }
 
         notify({
             stage: "resolve",
@@ -231,23 +249,31 @@ export class ModelAssetRegistry implements Live2dStageAssets {
                 progress: 0.05,
                 detail: fetchUrl,
             });
-            json = await fetchModelJson(fetchUrl, (u) => {
-                const ratio =
-                    u.bytesTotal && u.bytesTotal > 0
-                        ? u.bytesLoaded / u.bytesTotal
-                        : 0;
-                notify({
-                    stage: "settings",
-                    progress: lerp(0.05, 0.22, ratio),
-                    detail: fetchUrl,
-                    bytesLoaded: u.bytesLoaded,
-                    bytesTotal: u.bytesTotal,
-                });
-            });
+            json = await fetchModelJson(
+                fetchUrl,
+                (u) => {
+                    const ratio =
+                        u.bytesTotal && u.bytesTotal > 0
+                            ? u.bytesLoaded / u.bytesTotal
+                            : 0;
+                    notify({
+                        stage: "settings",
+                        progress: lerp(0.05, 0.22, ratio),
+                        detail: fetchUrl,
+                        bytesLoaded: u.bytesLoaded,
+                        bytesTotal: u.bytesTotal,
+                    });
+                },
+                { signal },
+            );
             baseUrl = fetchUrl;
             settingsUrl = fetchUrl;
         }
 
+        if (signal?.aborted) {
+            throw new Error("@doki-land/live2d: load cancelled");
+        }
+
         const settings = normalizeModelSettings(json, settingsUrl);
         notify({
             stage: "moc",
@@ -258,6 +284,7 @@ export class ModelAssetRegistry implements Live2dStageAssets {
         const assetResolver =
             resolver ??
             createUrlAssetResolver(baseUrl, {
+                signal,
                 onBytesProgress: (assetKey, u) => {
                     const isMoc = assetKey === settings.moc;
                     const ratio =
@@ -292,6 +319,9 @@ export class ModelAssetRegistry implements Live2dStageAssets {
         });
 
         const mocBytes = await assetResolver.fetchBytes(settings.moc);
+        if (signal?.aborted) {
+            throw new Error("@doki-land/live2d: load cancelled");
+        }
         const sharedCompile = compileSharedModelCompile(settings, mocBytes);
 
         const textures: TextureData[] = [];
@@ -317,6 +347,10 @@ export class ModelAssetRegistry implements Live2dStageAssets {
             );
         }
 
+        if (signal?.aborted) {
+            throw new Error("@doki-land/live2d: load cancelled");
+        }
+
         notify({
             stage: "ready",
             progress: 1,

package/src/stage/single-facade.ts

@@ -1,6 +1,6 @@
 import type {
     FrameSnapshot,
-    Live2DSession,
+    Live2dSession,
     LoadProgress,
     ModelSource,
     SessionPhase,
@@ -18,14 +18,14 @@ import { MotionPriority } from "../motion/index.js";
 import type { Live2dActorImpl } from "./actor.js";
 import type { Live2dStageImpl } from "./stage.js";
 
-export interface CreateLive2DOptions {
+export interface CreateLive2dOptions {
     backends?: ModelBackend[];
     renderer?: Renderer;
     prefer?: RendererKind[];
     updateMode?: "auto" | "manual";
 }
 
-export interface Live2DRuntime extends Live2DSession {
+export interface Live2dRuntime extends Live2dSession {
     readonly renderer: Renderer;
     readonly backends: readonly ModelBackend[];
     readonly stage: Live2dStageImpl;
@@ -54,6 +54,10 @@ export interface Live2DRuntime extends Live2DSession {
         time: number;
         priority: number;
     }>;
+    listExpressions(): ReadonlyArray<
+        import("@doki-land/live2d-core").ExpressionDefinition
+    >;
+    setExpression(name: string | null): Promise<boolean>;
     capturePng(opts?: {
         mimeType?: "image/png";
         quality?: number;
@@ -69,7 +73,7 @@ export function createSingleActorFacade(
     stage: Live2dStageImpl,
     actor: Live2dActorImpl,
     backends: readonly ModelBackend[],
-): Live2DRuntime {
+): Live2dRuntime {
     const events = new EventEmitter();
     let canvas: HTMLCanvasElement | null = null;
     let phase: SessionPhase = "idle";
@@ -88,7 +92,7 @@ export function createSingleActorFacade(
         generation,
     });
 
-    const runtime: Live2DRuntime = {
+    const runtime: Live2dRuntime = {
         events,
         backends,
         renderer: stage.renderer,
@@ -113,10 +117,10 @@ export function createSingleActorFacade(
                 },
             );
         },
-        async loadModel(source: ModelSource, resolver) {
+        async loadModel(source: ModelSource, resolver, options) {
             setPhase("loading");
             try {
-                const model = await actor.load(source, resolver);
+                const model = await actor.load(source, resolver, options);
                 lastError = null;
                 setPhase("live");
                 events.emit("ready", { modelId: model.id });
@@ -162,6 +166,12 @@ export function createSingleActorFacade(
         listPlayingMotions() {
             return actor.listPlayingMotions();
         },
+        listExpressions() {
+            return actor.listExpressions();
+        },
+        setExpression(name) {
+            return actor.setExpression(name);
+        },
         async capturePng(opts = {}) {
             if (!canvas) {
                 throw new Error(
@@ -224,7 +234,17 @@ export function createSingleActorFacade(
         },
     };
 
+    actor.setMotionEventHandlers({
+        onStart: (payload) => events.emit("motion:start", payload),
+        onFinish: (payload) => events.emit("motion:finish", payload),
+    });
+
     return runtime;
 }
 
 export { MotionPriority, type PlayMotionOptions };
+
+/** @deprecated Use `CreateLive2dOptions`. */
+export type CreateLive2DOptions = CreateLive2dOptions;
+/** @deprecated Use `Live2dRuntime`. */
+export type Live2DRuntime = Live2dRuntime;

package/src/stage/stage.ts

@@ -67,6 +67,7 @@ export class Live2dStageImpl implements Live2dStage {
     ]);
     readonly #drawScratch = new StageDrawableScratch();
     readonly #sortedActors: Live2dActorImpl[] = [];
+    readonly #frameListeners = new Set<(deltaTimeSeconds: number) => void>();
 
     #canvas: HTMLCanvasElement | null = null;
     #initPromise: Promise<void> | null = null;
@@ -182,12 +183,22 @@ export class Live2dStageImpl implements Live2dStage {
 
     update(deltaTimeSeconds: number): void {
         if (this.#destroyed) return;
+        for (const listener of this.#frameListeners) {
+            listener(deltaTimeSeconds);
+        }
         for (const actor of this.#actors.values()) {
             actor.update(deltaTimeSeconds);
         }
         this.#applyPointerTracking();
     }
 
+    onFrame(listener: (deltaTimeSeconds: number) => void): () => void {
+        this.#frameListeners.add(listener);
+        return () => {
+            this.#frameListeners.delete(listener);
+        };
+    }
+
     render(): void {
         if (this.#destroyed || !this.#canvas) return;
         const sorted = this.#sortedActors;
@@ -291,6 +302,7 @@ export class Live2dStageImpl implements Live2dStage {
         if (this.#destroyed) return;
         this.#destroyed = true;
         this.stop();
+        this.#frameListeners.clear();
         this.#detachPointerListeners();
         for (const actor of this.#actors.values()) {
             actor.destroy();