@doki-land/live2d 0.0.22 → 0.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doki-land/live2d",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "description": "Live2D in the browser — load moc2/moc3 models, Stage + multi-actor, motion; WebGPU/WebGL2/Canvas2D. Main entry for live2d.ts.",
   "type": "module",
   "license": "MIT",
@@ -59,9 +59,9 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@doki-land/live2d-core": "0.0.22",
-    "@doki-land/live2d-loader": "0.0.22",
-    "@doki-land/live2d-renderer": "0.0.22"
+    "@doki-land/live2d-core": "0.0.24",
+    "@doki-land/live2d-loader": "0.0.24",
+    "@doki-land/live2d-renderer": "0.0.24"
   },
   "sideEffects": false
 }

package/src/expression/apply-expression.ts

@@ -0,0 +1,41 @@
+import type { Expression3Clip, ExpressionBlendMode } from "./types.js";
+
+export interface ExpressionApplyBinding {
+    readonly value: number;
+}
+
+function blendValue(
+    current: number,
+    target: number,
+    mode: ExpressionBlendMode,
+    weight: number,
+): number {
+    if (weight <= 0) return current;
+    if (weight >= 1) {
+        if (mode === "Add") return current + target;
+        if (mode === "Multiply") return current * target;
+        return target;
+    }
+    const full =
+        mode === "Add"
+            ? current + target
+            : mode === "Multiply"
+              ? current * target
+              : target;
+    return current + (full - current) * weight;
+}
+
+/** Apply expression parameters on top of the current parameter state. */
+export function applyExpression3Clip(
+    clip: Expression3Clip,
+    weight: number,
+    bindings: ReadonlyMap<string, ExpressionApplyBinding>,
+    setParameter: (id: string, value: number) => void,
+): void {
+    if (weight <= 0) return;
+    for (const p of clip.parameters) {
+        const binding = bindings.get(p.id);
+        if (!binding) continue;
+        setParameter(p.id, blendValue(binding.value, p.value, p.blend, weight));
+    }
+}

package/src/expression/index.ts

@@ -0,0 +1,7 @@
+export { applyExpression3Clip } from "./apply-expression.js";
+export { parseExpression3 } from "./parse-expression3.js";
+export type {
+    Expression3Clip,
+    Expression3Parameter,
+    ExpressionBlendMode,
+} from "./types.js";

package/src/expression/parse-expression3.ts

@@ -0,0 +1,45 @@
+import type { Expression3Clip, ExpressionBlendMode } from "./types.js";
+
+const BLENDS = new Set<ExpressionBlendMode>(["Add", "Multiply", "Override"]);
+
+function parseBlend(raw: unknown): ExpressionBlendMode {
+    if (typeof raw !== "string") return "Add";
+    // Cubism official spelling is `Overwrite`; keep `Override` as an alias.
+    if (raw === "Overwrite" || raw === "Override") return "Override";
+    if (BLENDS.has(raw as ExpressionBlendMode)) {
+        return raw as ExpressionBlendMode;
+    }
+    return "Add";
+}
+
+/** Parse Cubism `exp3.json` (FileFormats/exp3.json.md subset). */
+export function parseExpression3(json: unknown): Expression3Clip {
+    if (!json || typeof json !== "object") {
+        throw new Error("@doki-land/live2d: exp3.json root must be an object");
+    }
+    const root = json as Record<string, unknown>;
+    const version = Number(root.Version ?? 3);
+    const paramsRaw = root.Parameters;
+    if (!Array.isArray(paramsRaw)) {
+        throw new Error("@doki-land/live2d: exp3.json missing Parameters");
+    }
+    const parameters = paramsRaw.map((item, index) => {
+        if (!item || typeof item !== "object") {
+            throw new Error(`@doki-land/live2d: Parameters[${index}] invalid`);
+        }
+        const p = item as Record<string, unknown>;
+        const id = p.Id;
+        const value = p.Value;
+        if (typeof id !== "string" || typeof value !== "number") {
+            throw new Error(
+                `@doki-land/live2d: Parameters[${index}] needs Id/Value`,
+            );
+        }
+        return {
+            id,
+            value,
+            blend: parseBlend(p.Blend),
+        };
+    });
+    return { version, parameters };
+}

package/src/expression/types.ts

@@ -0,0 +1,13 @@
+export type ExpressionBlendMode = "Add" | "Multiply" | "Override";
+
+export interface Expression3Parameter {
+    readonly id: string;
+    readonly value: number;
+    readonly blend: ExpressionBlendMode;
+}
+
+/** Parsed Cubism `exp3.json`. */
+export interface Expression3Clip {
+    readonly version: number;
+    readonly parameters: readonly Expression3Parameter[];
+}

package/src/facade/create-live2d.ts

@@ -5,14 +5,18 @@ import {
 } from "@doki-land/live2d-renderer";
 import { allocateActorId } from "../stage/actor.js";
 import {
-    type CreateLive2DOptions,
+    type CreateLive2dOptions,
     createSingleActorFacade,
-    type Live2DRuntime,
+    type Live2dRuntime,
 } from "../stage/single-facade.js";
 import { createLive2dStage } from "../stage/stage.js";
 
 export type {
+    CreateLive2dOptions,
+    Live2dRuntime,
+    /** @deprecated Use `CreateLive2dOptions`. */
     CreateLive2DOptions,
+    /** @deprecated Use `Live2dRuntime`. */
     Live2DRuntime,
 } from "../stage/single-facade.js";
 export {
@@ -21,7 +25,7 @@ export {
 } from "../stage/single-facade.js";
 
 /** Wire moc backends and a renderer into one single-actor session. */
-export function createLive2D(options: CreateLive2DOptions = {}): Live2DRuntime {
+export function createLive2d(options: CreateLive2dOptions = {}): Live2dRuntime {
     const backends = options.backends ?? [
         createMoc2Backend(),
         createMoc3Backend(),
@@ -37,3 +41,6 @@ export function createLive2D(options: CreateLive2DOptions = {}): Live2DRuntime {
     }) as import("../stage/actor.js").Live2dActorImpl;
     return createSingleActorFacade(stage, actor, backends);
 }
+
+/** @deprecated Use `createLive2d`. */
+export const createLive2D = createLive2d;

package/src/index.ts

@@ -2,13 +2,13 @@
  * `@doki-land/live2d` — public facade.
  *
  * Layout:
- * - `facade/`    — `createLive2D()` default stage + actor entry
+ * - `facade/`    — `createLive2d()` default stage + actor entry
  * - `motion/`    — motion3 parse + playback
  * - `stage/`     — multi-actor stage, assets, transforms
  * - `reexports/` — optional subpath `@doki-land/live2d/{core,loader,renderer}`
  *
  * ```ts
- * import { createLive2D } from "@doki-land/live2d";
+ * import { createLive2d } from "@doki-land/live2d";
  * ```
  */
 
@@ -22,8 +22,8 @@ export type {
     FrameProfile,
     FrameSnapshot,
     InternalModel,
-    Live2DSession,
     Live2dActor,
+    Live2dSession,
     Live2dStage,
     Live2dStageAssets,
     LoadProgress,
@@ -67,8 +67,21 @@ export {
     serializeCpuProgram,
 } from "@doki-land/live2d-renderer";
 export {
-    type CreateLive2DOptions,
+    applyExpression3Clip,
+    type Expression3Clip,
+    type Expression3Parameter,
+    type ExpressionBlendMode,
+    parseExpression3,
+} from "./expression/index.js";
+export {
+    type CreateLive2dOptions,
+    createLive2d,
+    type Live2dRuntime,
+    /** @deprecated Use `createLive2d`. */
     createLive2D,
+    /** @deprecated Use `CreateLive2dOptions`. */
+    type CreateLive2DOptions,
+    /** @deprecated Use `Live2dRuntime`. */
     type Live2DRuntime,
     MotionPriority,
     type PlayMotionOptions,
@@ -82,7 +95,22 @@ export {
     MotionPlayer,
     parseMotion3,
 } from "./motion/index.js";
+export {
+    applyPhysics3,
+    type Physics3ApplyBinding,
+    type Physics3Clip,
+    type Physics3Output,
+    type Physics3Setting,
+    parsePhysics3,
+} from "./physics/index.js";
+export {
+    applyPose3Activation,
+    type Pose3Clip,
+    parsePose3,
+} from "./pose/index.js";
+export { allocateActorId } from "./stage/actor.js";
 export { focusParameterUpdates } from "./stage/assets/focus.js";
+export { resolveHitAreaName } from "./stage/hit-area.js";
 export {
     type CreateLive2dStageFullOptions,
     createLive2dStage,

package/src/physics/apply-physics3.ts

@@ -0,0 +1,26 @@
+import type { Physics3Clip } from "./types.js";
+
+export interface Physics3ApplyBinding {
+    readonly value: number;
+}
+
+/**
+ * Minimal Physics3 apply gate — **not** a full Cubism spring / pendulum solver.
+ *
+ * For each output destination parameter id that exists in `bindings`, performs a
+ * trivial identity step (write current value back). Exists so load → update can
+ * exercise the physics clip API; real physics evaluation is a later milestone.
+ */
+export function applyPhysics3(
+    clip: Physics3Clip,
+    _deltaTimeSeconds: number,
+    bindings: ReadonlyMap<string, Physics3ApplyBinding>,
+    setParameter: (id: string, value: number) => void,
+): void {
+    for (const id of clip.outputParameterIds) {
+        const binding = bindings.get(id);
+        if (!binding) continue;
+        // Identity / zero-step: prove the output walk without changing values.
+        setParameter(id, binding.value);
+    }
+}

package/src/physics/index.ts

@@ -0,0 +1,7 @@
+export { applyPhysics3, type Physics3ApplyBinding } from "./apply-physics3.js";
+export { parsePhysics3 } from "./parse-physics3.js";
+export type {
+    Physics3Clip,
+    Physics3Output,
+    Physics3Setting,
+} from "./types.js";

package/src/physics/parse-physics3.ts

@@ -0,0 +1,52 @@
+import type { Physics3Clip, Physics3Output, Physics3Setting } from "./types.js";
+
+/**
+ * Parse Cubism `physics3.json` enough to expose PhysicsSettings output parameter ids.
+ * Tolerates minimal fixtures (missing / empty PhysicsSettings → empty clip).
+ */
+export function parsePhysics3(json: unknown): Physics3Clip {
+    if (!json || typeof json !== "object") {
+        throw new Error(
+            "@doki-land/live2d: physics3 json root must be an object",
+        );
+    }
+    const root = json as Record<string, unknown>;
+    const settingsRaw = root.PhysicsSettings;
+    if (settingsRaw === undefined || settingsRaw === null) {
+        return { settings: [], outputParameterIds: [] };
+    }
+    if (!Array.isArray(settingsRaw)) {
+        throw new Error("@doki-land/live2d: PhysicsSettings must be an array");
+    }
+
+    const settings: Physics3Setting[] = [];
+    const outputParameterIds: string[] = [];
+
+    for (let si = 0; si < settingsRaw.length; si++) {
+        const entry = settingsRaw[si];
+        if (!entry || typeof entry !== "object") {
+            throw new Error(
+                `@doki-land/live2d: PhysicsSettings[${si}] must be an object`,
+            );
+        }
+        const rec = entry as Record<string, unknown>;
+        const id = typeof rec.Id === "string" ? rec.Id : `PhysicsSetting${si}`;
+        const outputsRaw = rec.Output;
+        const outputs: Physics3Output[] = [];
+        if (Array.isArray(outputsRaw)) {
+            for (let oi = 0; oi < outputsRaw.length; oi++) {
+                const out = outputsRaw[oi];
+                if (!out || typeof out !== "object") continue;
+                const dest = (out as Record<string, unknown>).Destination;
+                if (!dest || typeof dest !== "object") continue;
+                const destId = (dest as Record<string, unknown>).Id;
+                if (typeof destId !== "string" || !destId) continue;
+                outputs.push({ destinationId: destId });
+                outputParameterIds.push(destId);
+            }
+        }
+        settings.push({ id, outputs });
+    }
+
+    return { settings, outputParameterIds };
+}

package/src/physics/types.ts

@@ -0,0 +1,20 @@
+/** One physics output destination (parameter id only for the thin gate). */
+export interface Physics3Output {
+    readonly destinationId: string;
+}
+
+/** One PhysicsSettings entry with output destinations. */
+export interface Physics3Setting {
+    readonly id: string;
+    readonly outputs: readonly Physics3Output[];
+}
+
+/**
+ * Parsed Cubism `physics3.json` (minimal).
+ * Full spring / pendulum simulation is intentionally out of scope for this gate.
+ */
+export interface Physics3Clip {
+    readonly settings: readonly Physics3Setting[];
+    /** Flattened destination parameter ids from all outputs. */
+    readonly outputParameterIds: readonly string[];
+}

package/src/pose/apply-pose3.ts

@@ -0,0 +1,19 @@
+import type { Pose3Clip } from "./types.js";
+
+/**
+ * When a part in a pose group becomes visible, hide sibling parts in that group.
+ * Mirrors Cubism Pose minimum semantics for part-opacity switching.
+ */
+export function applyPose3Activation(
+    clip: Pose3Clip,
+    activatedPartId: string,
+    setPartOpacity: (partId: string, opacity: number) => void,
+): void {
+    for (const group of clip.groups) {
+        if (!group.includes(activatedPartId)) continue;
+        for (const partId of group) {
+            setPartOpacity(partId, partId === activatedPartId ? 1 : 0);
+        }
+        return;
+    }
+}

package/src/pose/index.ts

@@ -0,0 +1,3 @@
+export { applyPose3Activation } from "./apply-pose3.js";
+export { parsePose3 } from "./parse-pose3.js";
+export type { Pose3Clip } from "./types.js";

package/src/pose/parse-pose3.ts

@@ -0,0 +1,33 @@
+import type { Pose3Clip } from "./types.js";
+
+/** Parse Cubism pose file (`pose3.json` or legacy `pose.json`). */
+export function parsePose3(json: unknown): Pose3Clip {
+    if (!json || typeof json !== "object") {
+        throw new Error("@doki-land/live2d: pose json root must be an object");
+    }
+    const root = json as Record<string, unknown>;
+    const groupsRaw = root.Groups;
+    if (!Array.isArray(groupsRaw)) {
+        throw new Error("@doki-land/live2d: pose json missing Groups");
+    }
+    const groups = groupsRaw.map((group, gi) => {
+        if (!Array.isArray(group)) {
+            throw new Error(`@doki-land/live2d: Groups[${gi}] must be array`);
+        }
+        return group.map((entry, ei) => {
+            if (!entry || typeof entry !== "object") {
+                throw new Error(
+                    `@doki-land/live2d: Groups[${gi}][${ei}] invalid`,
+                );
+            }
+            const id = (entry as Record<string, unknown>).Id;
+            if (typeof id !== "string" || !id) {
+                throw new Error(
+                    `@doki-land/live2d: Groups[${gi}][${ei}] missing Id`,
+                );
+            }
+            return id;
+        });
+    });
+    return { groups };
+}

package/src/pose/types.ts

@@ -0,0 +1,4 @@
+/** Parsed Cubism `pose3.json` / legacy `pose.json` groups. */
+export interface Pose3Clip {
+    readonly groups: readonly (readonly string[])[];
+}