@doki-land/live2d 0.0.10 → 0.0.12

package/src/motion/evaluate-curve.ts

@@ -0,0 +1,119 @@
+import type { Motion3Clip, MotionCurve, MotionSegment } from "./types.js";
+
+/**
+ * Sample all curves of a clip at `timeSeconds` (clamped to [0, duration]
+ * unless looping — caller should wrap time for loops).
+ */
+export function evaluateMotion3(
+    clip: Motion3Clip,
+    timeSeconds: number,
+): Array<{ target: MotionCurve["target"]; id: string; value: number }> {
+    const t = clamp(timeSeconds, 0, clip.duration);
+    const out: Array<{
+        target: MotionCurve["target"];
+        id: string;
+        value: number;
+    }> = [];
+    for (const curve of clip.curves) {
+        out.push({
+            target: curve.target,
+            id: curve.id,
+            value: evaluateCurve(curve, t, clip.areBeziersRestricted),
+        });
+    }
+    return out;
+}
+
+export function evaluateCurve(
+    curve: MotionCurve,
+    timeSeconds: number,
+    areBeziersRestricted: boolean,
+): number {
+    const segs = curve.segments;
+    if (segs.length === 0) return 0;
+
+    if (timeSeconds <= segs[0]!.p0.time) return segs[0]!.p0.value;
+    const last = segs[segs.length - 1]!;
+    if (timeSeconds >= last.p3.time) return last.p3.value;
+
+    for (let i = 0; i < segs.length; i += 1) {
+        const seg = segs[i]!;
+        const isLast = i === segs.length - 1;
+        // At a segment boundary, hand off to the next segment so stepped ends
+        // expose their end value as the next key.
+        if (
+            timeSeconds < seg.p3.time ||
+            (isLast && timeSeconds <= seg.p3.time)
+        ) {
+            return evaluateSegment(seg, timeSeconds, areBeziersRestricted);
+        }
+    }
+    return last.p3.value;
+}
+
+function evaluateSegment(
+    seg: MotionSegment,
+    time: number,
+    areBeziersRestricted: boolean,
+): number {
+    const { p0, p3 } = seg;
+    switch (seg.kind) {
+        case "linear": {
+            const span = p3.time - p0.time;
+            if (span <= 0) return p3.value;
+            const u = (time - p0.time) / span;
+            return p0.value + (p3.value - p0.value) * u;
+        }
+        case "stepped":
+            return p0.value;
+        case "inverseStepped":
+            return p3.value;
+        case "bezier": {
+            const p1 = seg.p1!;
+            const p2 = seg.p2!;
+            if (areBeziersRestricted) {
+                const span = p3.time - p0.time;
+                if (span <= 0) return p3.value;
+                const u = (time - p0.time) / span;
+                return cubic(p0.value, p1.value, p2.value, p3.value, u);
+            }
+            // Unrestricted: solve cubic for time, then sample value.
+            const u = solveBezierTime(p0.time, p1.time, p2.time, p3.time, time);
+            return cubic(p0.value, p1.value, p2.value, p3.value, u);
+        }
+        default:
+            return p3.value;
+    }
+}
+
+function cubic(a: number, b: number, c: number, d: number, t: number): number {
+    const u = 1 - t;
+    return (
+        u * u * u * a + 3 * u * u * t * b + 3 * u * t * t * c + t * t * t * d
+    );
+}
+
+/** Binary-search parameter u in [0,1] so cubic(time) ~= targetTime. */
+function solveBezierTime(
+    t0: number,
+    t1: number,
+    t2: number,
+    t3: number,
+    target: number,
+): number {
+    let lo = 0;
+    let hi = 1;
+    for (let i = 0; i < 20; i += 1) {
+        const mid = (lo + hi) * 0.5;
+        const x = cubic(t0, t1, t2, t3, mid);
+        if (x < target) lo = mid;
+        else hi = mid;
+    }
+    return (lo + hi) * 0.5;
+}
+
+function clamp(n: number, min: number, max: number): number {
+    if (n < min) return min;
+    if (n > max) return max;
+    return n;
+}

package/src/motion/index.ts

@@ -0,0 +1,20 @@
+export { evaluateCurve, evaluateMotion3 } from "./evaluate-curve.js";
+export {
+    blendMotionLayers,
+    MotionPlayer,
+    type MotionPlayerHandlers,
+} from "./motion-player.js";
+export { parseMotion3 } from "./parse-motion3.js";
+export type {
+    Motion3Clip,
+    MotionApplySample,
+    MotionCurve,
+    MotionCurveTarget,
+    MotionPoint,
+    MotionPriorityLevel,
+    MotionSegment,
+    MotionSegmentKind,
+    MotionUserData,
+    PlayMotionOptions,
+} from "./types.js";
+export { MotionPriority } from "./types.js";

package/src/motion/motion-player.ts

@@ -0,0 +1,389 @@
+import { evaluateMotion3 } from "./evaluate-curve.js";
+import type {
+    Motion3Clip,
+    MotionApplySample,
+    MotionPriorityLevel,
+    PlayMotionOptions,
+} from "./types.js";
+import { MotionPriority } from "./types.js";
+
+export interface MotionPlayerHandlers {
+    onStart?: (info: { group: string; index: number; slot: string }) => void;
+    onFinish?: (info: { group: string; index: number; slot: string }) => void;
+    onEvent?: (info: {
+        group: string;
+        index: number;
+        slot: string;
+        time: number;
+        value: string;
+    }) => void;
+}
+
+interface ActiveMotion {
+    slot: string;
+    group: string;
+    index: number;
+    clip: Motion3Clip;
+    priority: MotionPriorityLevel;
+    loop: boolean;
+    fadeInTime: number;
+    fadeOutTime: number;
+    time: number;
+    fadingOut: boolean;
+    fadeOutElapsed: number;
+    lastEventIndex: number;
+    started: boolean;
+}
+
+interface QueuedMotion {
+    group: string;
+    index: number;
+    clip: Motion3Clip;
+    options: PlayMotionOptions;
+}
+
+/**
+ * Multi-slot motion player with per-slot queue.
+ *
+ * Default slot is `priority:{n}` so idle (1) and normal (2) can run together.
+ * Same slot replaces (with fade-out) unless `queue: true`.
+ */
+export class MotionPlayer {
+    #slots = new Map<string, ActiveMotion>();
+    #queues = new Map<string, QueuedMotion[]>();
+    #handlers: MotionPlayerHandlers;
+
+    constructor(handlers: MotionPlayerHandlers = {}) {
+        this.#handlers = handlers;
+    }
+
+    get isPlaying(): boolean {
+        return this.#slots.size > 0;
+    }
+
+    listPlaying(): ReadonlyArray<{
+        slot: string;
+        group: string;
+        index: number;
+        time: number;
+        priority: MotionPriorityLevel;
+    }> {
+        return [...this.#slots.values()].map((a) => ({
+            slot: a.slot,
+            group: a.group,
+            index: a.index,
+            time: a.time,
+            priority: a.priority,
+        }));
+    }
+
+    /** @deprecated Prefer {@link listPlaying}; returns highest-priority slot. */
+    get current(): {
+        group: string;
+        index: number;
+        time: number;
+        priority: MotionPriorityLevel;
+    } | null {
+        const list = [...this.listPlaying()];
+        if (!list.length) return null;
+        list.sort((a, b) => b.priority - a.priority);
+        const top = list[0]!;
+        return {
+            group: top.group,
+            index: top.index,
+            time: top.time,
+            priority: top.priority,
+        };
+    }
+
+    /**
+     * Start a clip on a slot. Returns false if rejected by priority
+     * (and not queued).
+     */
+    start(
+        group: string,
+        index: number,
+        clip: Motion3Clip,
+        options: PlayMotionOptions = {},
+    ): boolean {
+        const priority = options.priority ?? MotionPriority.normal;
+        const slot = options.slot ?? `priority:${priority}`;
+        const existing = this.#slots.get(slot);
+
+        if (existing && priority < existing.priority) {
+            if (options.queue) {
+                this.#enqueue(slot, { group, index, clip, options });
+                return true;
+            }
+            return false;
+        }
+
+        if (existing && options.queue && !existing.fadingOut) {
+            this.#enqueue(slot, { group, index, clip, options });
+            return true;
+        }
+
+        if (existing) {
+            // Replace: fade out current, then start — or hard-swap if no fade.
+            if (existing.fadeOutTime > 0 && !existing.fadingOut) {
+                existing.fadingOut = true;
+                existing.fadeOutElapsed = 0;
+                this.#enqueueFront(slot, { group, index, clip, options });
+                return true;
+            }
+            this.#finish(existing, false);
+        }
+
+        this.#slots.set(
+            slot,
+            this.#createActive(slot, group, index, clip, options),
+        );
+        return true;
+    }
+
+    /** Fade out (default) or hard-stop; `slot` omits → all slots. */
+    stop(fade = true, slot?: string): void {
+        if (slot !== undefined) {
+            const a = this.#slots.get(slot);
+            if (!a) return;
+            this.#stopOne(a, fade);
+            return;
+        }
+        for (const a of [...this.#slots.values()]) {
+            this.#stopOne(a, fade);
+        }
+    }
+
+    clear(): void {
+        this.#slots.clear();
+        this.#queues.clear();
+    }
+
+    /**
+     * Advance all slots and return blended samples (weight baked in; apply as absolute).
+     */
+    update(deltaTimeSeconds: number): MotionApplySample[] {
+        const dt = Math.max(0, deltaTimeSeconds);
+        const layerSamples: Array<{
+            priority: number;
+            samples: MotionApplySample[];
+        }> = [];
+
+        for (const a of [...this.#slots.values()]) {
+            const samples = this.#tick(a, dt);
+            if (samples) {
+                layerSamples.push({ priority: a.priority, samples });
+            }
+        }
+
+        layerSamples.sort((a, b) => a.priority - b.priority);
+        return blendMotionLayers(layerSamples);
+    }
+
+    #tick(a: ActiveMotion, dt: number): MotionApplySample[] | null {
+        if (!a.started) {
+            a.started = true;
+            this.#handlers.onStart?.({
+                group: a.group,
+                index: a.index,
+                slot: a.slot,
+            });
+        }
+
+        a.time += dt;
+
+        if (a.fadingOut) {
+            a.fadeOutElapsed += dt;
+            if (a.fadeOutElapsed >= a.fadeOutTime) {
+                this.#finish(a, true);
+                return null;
+            }
+        } else if (!a.loop && a.time >= a.clip.duration) {
+            if (a.fadeOutTime > 0) {
+                a.fadingOut = true;
+                a.fadeOutElapsed = 0;
+            } else {
+                const samples = this.#sample(a, a.clip.duration, 1);
+                this.#finish(a, true);
+                return samples;
+            }
+        }
+
+        let playTime = a.time;
+        if (a.loop && a.clip.duration > 0) {
+            playTime = a.time % a.clip.duration;
+        } else {
+            playTime = Math.min(playTime, a.clip.duration);
+        }
+
+        this.#emitEvents(a, playTime);
+        return this.#sample(a, playTime, this.#fadeWeight(a));
+    }
+
+    #createActive(
+        slot: string,
+        group: string,
+        index: number,
+        clip: Motion3Clip,
+        options: PlayMotionOptions,
+    ): ActiveMotion {
+        const fadeIn =
+            options.fadeInTime ?? (clip.fadeInTime > 0 ? clip.fadeInTime : 0);
+        const fadeOut =
+            options.fadeOutTime ??
+            (clip.fadeOutTime > 0 ? clip.fadeOutTime : 0);
+        return {
+            slot,
+            group,
+            index,
+            clip,
+            priority: options.priority ?? MotionPriority.normal,
+            loop: options.loop ?? clip.loop,
+            fadeInTime: Math.max(0, fadeIn),
+            fadeOutTime: Math.max(0, fadeOut),
+            time: 0,
+            fadingOut: false,
+            fadeOutElapsed: 0,
+            lastEventIndex: -1,
+            started: false,
+        };
+    }
+
+    #enqueue(slot: string, item: QueuedMotion): void {
+        const q = this.#queues.get(slot) ?? [];
+        q.push(item);
+        this.#queues.set(slot, q);
+    }
+
+    #enqueueFront(slot: string, item: QueuedMotion): void {
+        const q = this.#queues.get(slot) ?? [];
+        q.unshift(item);
+        this.#queues.set(slot, q);
+    }
+
+    #stopOne(a: ActiveMotion, fade: boolean): void {
+        if (!fade || a.fadeOutTime <= 0) {
+            this.#finish(a, true);
+            return;
+        }
+        a.fadingOut = true;
+        a.fadeOutElapsed = 0;
+    }
+
+    #finish(a: ActiveMotion, promoteQueue: boolean): void {
+        if (this.#slots.get(a.slot) !== a) return;
+        this.#slots.delete(a.slot);
+        this.#handlers.onFinish?.({
+            group: a.group,
+            index: a.index,
+            slot: a.slot,
+        });
+        if (!promoteQueue) return;
+        const q = this.#queues.get(a.slot);
+        const next = q?.shift();
+        if (next) {
+            this.#slots.set(
+                a.slot,
+                this.#createActive(
+                    a.slot,
+                    next.group,
+                    next.index,
+                    next.clip,
+                    next.options,
+                ),
+            );
+        }
+    }
+
+    #sample(
+        a: ActiveMotion,
+        playTime: number,
+        weight: number,
+    ): MotionApplySample[] {
+        const values = evaluateMotion3(a.clip, playTime);
+        return values.map((v) => ({
+            target: v.target,
+            id: v.id,
+            value: v.value,
+            weight,
+        }));
+    }
+
+    #fadeWeight(a: ActiveMotion): number {
+        let w = 1;
+        if (a.fadeInTime > 0 && a.time < a.fadeInTime) {
+            w = sineEase(a.time / a.fadeInTime);
+        }
+        if (a.fadingOut && a.fadeOutTime > 0) {
+            const u = 1 - a.fadeOutElapsed / a.fadeOutTime;
+            w *= sineEase(Math.max(0, u));
+        }
+        return w;
+    }
+
+    #emitEvents(a: ActiveMotion, playTime: number): void {
+        const events = a.clip.userData;
+        for (let i = a.lastEventIndex + 1; i < events.length; i += 1) {
+            const e = events[i]!;
+            if (e.time > playTime) break;
+            a.lastEventIndex = i;
+            this.#handlers.onEvent?.({
+                group: a.group,
+                index: a.index,
+                slot: a.slot,
+                time: e.time,
+                value: e.value,
+            });
+        }
+        if (a.loop && a.clip.duration > 0) {
+            const prevMod =
+                ((a.time - 1e-6) % a.clip.duration) +
+                (a.time - 1e-6 < 0 ? a.clip.duration : 0);
+            if (playTime < prevMod - 1e-4) {
+                a.lastEventIndex = -1;
+            }
+        }
+    }
+}
+
+/** Blend layers low→high priority; later layers lerp over earlier by their weight. */
+export function blendMotionLayers(
+    layers: ReadonlyArray<{
+        priority: number;
+        samples: readonly MotionApplySample[];
+    }>,
+): MotionApplySample[] {
+    const map = new Map<
+        string,
+        {
+            target: MotionApplySample["target"];
+            id: string;
+            value: number;
+            weight: number;
+        }
+    >();
+    for (const layer of layers) {
+        for (const s of layer.samples) {
+            const key = `${s.target}\0${s.id}`;
+            const w = Math.min(1, Math.max(0, s.weight));
+            const prev = map.get(key);
+            if (!prev) {
+                map.set(key, {
+                    target: s.target,
+                    id: s.id,
+                    value: s.value,
+                    weight: w,
+                });
+            } else {
+                prev.value = prev.value + (s.value - prev.value) * w;
+                prev.weight = Math.min(1, prev.weight + w * (1 - prev.weight));
+            }
+        }
+    }
+    return [...map.values()];
+}
+
+function sineEase(t: number): number {
+    const x = Math.min(1, Math.max(0, t));
+    return 0.5 - 0.5 * Math.cos(x * Math.PI);
+}

package/src/motion/parse-motion3.ts

@@ -0,0 +1,164 @@
+import type {
+    Motion3Clip,
+    MotionCurve,
+    MotionCurveTarget,
+    MotionPoint,
+    MotionSegment,
+    MotionSegmentKind,
+    MotionUserData,
+} from "./types.js";
+
+const SEGMENT_KIND: Record<number, MotionSegmentKind> = {
+    0: "linear",
+    1: "bezier",
+    2: "stepped",
+    3: "inverseStepped",
+};
+
+/**
+ * Parse Cubism `motion3.json` (FileFormats/motion3.json.md).
+ */
+export function parseMotion3(json: unknown): Motion3Clip {
+    if (!json || typeof json !== "object") {
+        throw new Error(
+            "@doki-land/live2d: motion3.json root must be an object",
+        );
+    }
+    const root = json as Record<string, unknown>;
+    const version = Number(root.Version ?? 3);
+    const meta = root.Meta;
+    if (!meta || typeof meta !== "object") {
+        throw new Error("@doki-land/live2d: motion3.json missing Meta");
+    }
+    const m = meta as Record<string, unknown>;
+    const duration = num(m.Duration, "Meta.Duration");
+    const fps = num(m.Fps, "Meta.Fps");
+    const loop = m.Loop === true;
+    const areBeziersRestricted = m.AreBeziersRestricted !== false;
+    const fadeInTime = optionalNum(m.FadeInTime) ?? 0;
+    const fadeOutTime = optionalNum(m.FadeOutTime) ?? 0;
+
+    const curvesRaw = root.Curves;
+    if (!Array.isArray(curvesRaw)) {
+        throw new Error("@doki-land/live2d: motion3.json missing Curves");
+    }
+    const curves = curvesRaw.map((c, i) => parseCurve(c, i));
+
+    const userData: MotionUserData[] = [];
+    if (Array.isArray(root.UserData)) {
+        for (const item of root.UserData) {
+            if (!item || typeof item !== "object") continue;
+            const u = item as Record<string, unknown>;
+            if (typeof u.Time === "number" && typeof u.Value === "string") {
+                userData.push({ time: u.Time, value: u.Value });
+            }
+        }
+        userData.sort((a, b) => a.time - b.time);
+    }
+
+    return {
+        version,
+        duration,
+        fps,
+        loop,
+        areBeziersRestricted,
+        fadeInTime,
+        fadeOutTime,
+        curves,
+        userData,
+    };
+}
+
+function parseCurve(raw: unknown, index: number): MotionCurve {
+    if (!raw || typeof raw !== "object") {
+        throw new Error(`@doki-land/live2d: Curves[${index}] invalid`);
+    }
+    const c = raw as Record<string, unknown>;
+    const target = c.Target;
+    const id = c.Id;
+    if (typeof target !== "string" || typeof id !== "string") {
+        throw new Error(`@doki-land/live2d: Curves[${index}] needs Target/Id`);
+    }
+    if (
+        target !== "Parameter" &&
+        target !== "PartOpacity" &&
+        target !== "Model"
+    ) {
+        throw new Error(
+            `@doki-land/live2d: Curves[${index}] unknown Target ${target}`,
+        );
+    }
+    const segmentsFlat = c.Segments;
+    if (!Array.isArray(segmentsFlat) || segmentsFlat.length < 2) {
+        throw new Error(`@doki-land/live2d: Curves[${index}] empty Segments`);
+    }
+    const numbers = segmentsFlat.map((n, j) => {
+        if (typeof n !== "number" || !Number.isFinite(n)) {
+            throw new Error(
+                `@doki-land/live2d: Curves[${index}].Segments[${j}] not a number`,
+            );
+        }
+        return n;
+    });
+
+    return {
+        target: target as MotionCurveTarget,
+        id,
+        fadeInTime: optionalNum(c.FadeInTime),
+        fadeOutTime: optionalNum(c.FadeOutTime),
+        segments: parseSegments(numbers, index),
+    };
+}
+
+function parseSegments(
+    flat: readonly number[],
+    curveIndex: number,
+): MotionSegment[] {
+    let i = 0;
+    const p0: MotionPoint = { time: flat[i++]!, value: flat[i++]! };
+    const out: MotionSegment[] = [];
+    let prev = p0;
+
+    while (i < flat.length) {
+        const kindId = flat[i++]!;
+        const kind = SEGMENT_KIND[kindId];
+        if (!kind) {
+            throw new Error(
+                `@doki-land/live2d: Curves[${curveIndex}] unknown segment ${kindId}`,
+            );
+        }
+        if (kind === "bezier") {
+            if (i + 5 >= flat.length) {
+                throw new Error(
+                    `@doki-land/live2d: Curves[${curveIndex}] truncated bezier`,
+                );
+            }
+            const p1: MotionPoint = { time: flat[i++]!, value: flat[i++]! };
+            const p2: MotionPoint = { time: flat[i++]!, value: flat[i++]! };
+            const p3: MotionPoint = { time: flat[i++]!, value: flat[i++]! };
+            out.push({ kind, p0: prev, p1, p2, p3 });
+            prev = p3;
+        } else {
+            if (i + 1 >= flat.length) {
+                throw new Error(
+                    `@doki-land/live2d: Curves[${curveIndex}] truncated ${kind}`,
+                );
+            }
+            const p3: MotionPoint = { time: flat[i++]!, value: flat[i++]! };
+            out.push({ kind, p0: prev, p3 });
+            prev = p3;
+        }
+    }
+    return out;
+}
+
+function num(v: unknown, label: string): number {
+    if (typeof v !== "number" || !Number.isFinite(v)) {
+        throw new Error(`@doki-land/live2d: motion3 ${label} must be a number`);
+    }
+    return v;
+}
+
+function optionalNum(v: unknown): number | undefined {
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}