@laplace.live/pixijs-live2d 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -3240,6 +3240,14 @@ export declare enum MotionPreloadStrategy {
   /** No preload. */
   NONE = "NONE"
 }
+/**
+ * What plays when nothing else does: a motion to loop, `'idle-group'` for a random motion of
+ * the idle group (the default), or `null` to hold still.
+ */
+export type IdleMotion = {
+  group: string;
+  index: number;
+} | 'idle-group' | null;
 /**
  * Handles the motion playback for Live2D models.
  * Responsible for loading, playing, and managing motion states and audio.
@@ -3322,6 +3330,17 @@ export declare abstract class MotionManager<Motion = unknown, MotionSpec = unkno
    * @type {boolean}
    */
   destroyed: boolean;
+  /** The idle selection; see {@link setIdleMotion}. */
+  idleMotion: IdleMotion;
+  /**
+   * Choose what plays when nothing else does. A running idle gives way at once and a loading one
+   * is dropped; a higher-priority motion in flight hands over to the new selection when it ends.
+   */
+  setIdleMotion(motion: IdleMotion): void;
+  /** Stop the idle so the next update starts the selection. Cubism eases its parameters home too. */
+  protected releaseIdle(): void;
+  /** Start the idle selection at IDLE priority; a chosen motion loops regardless of its own flag. */
+  protected startIdleMotion(): Promise<boolean>;
   /**
    * Reference to the parent InternalModel.
    * @type {InternalModel}
@@ -6917,6 +6936,10 @@ export declare class CubismMotionManager extends MotionManager<CubismMotion, Mot
   expressionManager?: CubismExpressionManager;
   eyeBlinkIds: string[];
   lipSyncIds: string[];
+  /** What each motion's curves write, read once when it is created. */
+  private readonly meta;
+  /** Eases the parameters a released idle animated back to rest; see {@link releaseIdle}. */
+  private release;
   constructor(parent: CubismInternalModel);
   protected init(options?: MotionManagerOptions): void;
   isFinished(): boolean;
@@ -6926,6 +6949,15 @@ export declare class CubismMotionManager extends MotionManager<CubismMotion, Mot
   getMotionFile(definition: Motion): string;
   protected getMotionName(definition: Motion): string;
   protected getSoundFile(definition: Motion): string | undefined;
+  /** Whether the playing motion animates the eyes itself, so the engine's auto-blink must yield to it. */
+  currentMotionBlinks(): boolean;
+  /** The parameters the playing motion writes, for a host driver handing them over to it; null when none plays. */
+  currentMotionParameters(): ReadonlySet<string> | null;
+  private currentMotion;
+  private currentMeta;
+  protected releaseIdle(): void;
+  /** One frame of the ease-to-rest, ahead of the motions so a new idle's fade-in blends from it. */
+  private updateRelease;
   protected updateParameters(model: CubismModel, now: DOMHighResTimeStamp): boolean;
   destroy(): void;
   motionLastFrame(group: string, index: number, { expression }?: {

package/dist/index.js

@@ -3567,6 +3567,10 @@ var MotionState = class {
 	*/
 	start(motion, group, index, priority) {
 		if (priority === 1) {
+			if (group !== this.reservedIdleGroup || index !== this.reservedIdleIndex) {
+				logger.log(this.tag, "Cannot start idle motion because it is no longer reserved.", this.dump(group, index));
+				return false;
+			}
 			this.setReservedIdle(void 0, void 0);
 			if (this.currentPriority !== 0) {
 				logger.log(this.tag, "Cannot start idle motion because another motion is playing.", this.dump(group, index));
@@ -3912,6 +3916,10 @@ let MotionPreloadStrategy = /* @__PURE__ */ function(MotionPreloadStrategy) {
 	MotionPreloadStrategy["NONE"] = "NONE";
 	return MotionPreloadStrategy;
 }({});
+function sameIdleMotion(a, b) {
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return a === b;
+	return a.group === b.group && a.index === b.index;
+}
 /**
 * Handles the motion playback for Live2D models.
 * Responsible for loading, playing, and managing motion states and audio.
@@ -3966,6 +3974,29 @@ var MotionManager = class extends EventEmitter {
 	* @type {boolean}
 	*/
 	destroyed = false;
+	/** The idle selection; see {@link setIdleMotion}. */
+	idleMotion = "idle-group";
+	/**
+	* Choose what plays when nothing else does. A running idle gives way at once and a loading one
+	* is dropped; a higher-priority motion in flight hands over to the new selection when it ends.
+	*/
+	setIdleMotion(motion) {
+		if (sameIdleMotion(this.idleMotion, motion)) return;
+		this.idleMotion = motion;
+		this.state.setReservedIdle(void 0, void 0);
+		if (this.state.currentPriority === 1) this.releaseIdle();
+	}
+	/** Stop the idle so the next update starts the selection. Cubism eases its parameters home too. */
+	releaseIdle() {
+		this.stopAllMotions();
+	}
+	/** Start the idle selection at IDLE priority; a chosen motion loops regardless of its own flag. */
+	startIdleMotion() {
+		const idle = this.idleMotion;
+		if (idle === null) return Promise.resolve(false);
+		if (idle === "idle-group") return this.startRandomMotion(this.groups.idle, 1);
+		return this.startMotion(idle.group, idle.index, 1, { loop: true });
+	}
 	/**
 	* Reference to the parent InternalModel.
 	* @type {InternalModel}
@@ -4264,7 +4295,7 @@ var MotionManager = class extends EventEmitter {
 			}
 			if (this.state.shouldOverrideExpression()) this.expressionManager?.restoreExpression();
 			this.state.complete();
-			if (this.state.shouldRequestIdleMotion()) this.startRandomMotion(this.groups.idle, 1);
+			if (this.idleMotion !== null && this.state.shouldRequestIdleMotion()) this.startIdleMotion();
 		}
 		return this.updateParameters(model, now);
 	}
@@ -14693,6 +14724,10 @@ var CubismMotionManager = class extends MotionManager {
 	expressionManager;
 	eyeBlinkIds;
 	lipSyncIds = ["ParamMouthOpenY"];
+	/** What each motion's curves write, read once when it is created. */
+	meta = /* @__PURE__ */ new WeakMap();
+	/** Eases the parameters a released idle animated back to rest; see {@link releaseIdle}. */
+	release = null;
 	constructor(parent) {
 		super(parent);
 		this.definitions = parent.settings.motions ?? {};
@@ -14722,6 +14757,7 @@ var CubismMotionManager = class extends MotionManager {
 			});
 			motion._motionData.curves = filtered;
 			motion._motionData.curveCount = filtered.length;
+			this.meta.set(motion, motionMeta(motion, this.eyeBlinkIds));
 		}
 		this.queueManager.stopAllMotions();
 		return this.queueManager.startMotion(motion, false);
@@ -14734,6 +14770,7 @@ var CubismMotionManager = class extends MotionManager {
 		const motion = CubismMotion.create(data, data.byteLength, void 0, void 0, shouldCheckMotionConsistency);
 		const json = new CubismMotionJson(data, data.byteLength);
 		motion.setLoop(json.isMotionLoop());
+		this.meta.set(motion, motionMeta(motion, this.eyeBlinkIds));
 		const defaultFadingDuration = (group === this.groups.idle ? config.idleMotionFadingDuration : config.motionFadingDuration) / 1e3;
 		if (json.getMotionFadeInTime() === void 0) motion.setFadeInTime(definition.FadeInTime > 0 ? definition.FadeInTime : defaultFadingDuration);
 		if (json.getMotionFadeOutTime() === void 0) motion.setFadeOutTime(definition.FadeOutTime > 0 ? definition.FadeOutTime : defaultFadingDuration);
@@ -14749,7 +14786,57 @@ var CubismMotionManager = class extends MotionManager {
 	getSoundFile(definition) {
 		return definition.Sound;
 	}
+	/** Whether the playing motion animates the eyes itself, so the engine's auto-blink must yield to it. */
+	currentMotionBlinks() {
+		return this.currentMeta()?.blinks ?? false;
+	}
+	/** The parameters the playing motion writes, for a host driver handing them over to it; null when none plays. */
+	currentMotionParameters() {
+		return this.currentMeta()?.animated ?? null;
+	}
+	currentMotion() {
+		const { currentGroup, currentIndex } = this.state;
+		if (currentGroup === void 0 || currentIndex === void 0) return null;
+		return this.motionGroups[currentGroup]?.[currentIndex] ?? null;
+	}
+	currentMeta() {
+		const motion = this.currentMotion();
+		return motion ? this.meta.get(motion) ?? null : null;
+	}
+	releaseIdle() {
+		const motion = this.currentMotion();
+		super.releaseIdle();
+		if (motion) this.release = {
+			ids: this.meta.get(motion)?.parameterIds ?? [],
+			seconds: motion.getFadeOutTime(),
+			ramp: null
+		};
+	}
+	/** One frame of the ease-to-rest, ahead of the motions so a new idle's fade-in blends from it. */
+	updateRelease(model, now) {
+		const r = this.release;
+		if (!r) return;
+		if (r.ramp === null) {
+			const count = model.getParameterCount();
+			const indices = r.ids.map((id) => model.getParameterIndex(id)).filter((index) => index < count);
+			r.ramp = {
+				indices,
+				from: indices.map((index) => model.getParameterValueByIndex(index)),
+				startedAt: now
+			};
+		}
+		const { indices, from, startedAt } = r.ramp;
+		const t = r.seconds > 0 ? Math.min(1, (now - startedAt) / r.seconds) : 1;
+		const w = CubismMath.getEasingSine(t);
+		for (let i = 0; i < indices.length; i++) {
+			const index = indices[i];
+			const start = from[i];
+			model.setParameterValueByIndex(index, start + (model.getParameterDefaultValue(index) - start) * w);
+		}
+		if (t >= 1) this.release = null;
+	}
 	updateParameters(model, now) {
+		this.updateRelease(model, now);
 		return this.queueManager.doUpdateMotion(model, now);
 	}
 	destroy() {
@@ -14770,6 +14857,23 @@ var CubismMotionManager = class extends MotionManager {
 		return ids.map((id) => idManager.getId(id));
 	}
 };
+function motionMeta(motion, eyeBlinkIds) {
+	const parameterIds = [];
+	const animated = /* @__PURE__ */ new Set();
+	let blinks = false;
+	for (const curve of motion._motionData.curves) {
+		const id = getCurveId$1(curve);
+		if (curve.type === 1) {
+			parameterIds.push(curve.id);
+			if (id !== void 0) animated.add(id);
+		} else if (curve.type === 0 && id === "EyeBlink") blinks = true;
+	}
+	return {
+		parameterIds,
+		animated,
+		blinks: blinks || eyeBlinkIds.some((id) => animated.has(id))
+	};
+}
 function getCurveId$1(curve) {
 	if (!curve || typeof curve !== "object") return;
 	const id = curve.id;
@@ -15322,10 +15426,10 @@ var CubismInternalModel = class extends InternalModel {
 		dt /= 1e3;
 		now /= 1e3;
 		const model = this.coreModel;
-		const motionUpdated = this.updateMotions(model, now);
+		this.updateMotions(model, now);
 		model.saveParameters();
 		this.motionManager.expressionManager?.update(model, now);
-		if (!motionUpdated) this.eyeBlink?.updateParameters?.(model, dt);
+		if (!this.motionManager.currentMotionBlinks()) this.eyeBlink?.updateParameters?.(model, dt);
 		this.updateFocus();
 		this.updateNaturalMovements(dt * 1e3, now * 1e3);
 		if (this.lipSync && this.motionManager.currentAudio) {