@doki-land/live2d-core 0.0.13 → 0.0.15

package/README.md

@@ -1,3 +1,106 @@
 # @doki-land/live2d-core
 
-live2d.ts package 0.0.13.
+Framework-independent contracts and data structures for the `live2d.ts` runtime.
+
+This is an implementation package. Application developers should normally install `@doki-land/live2d` instead.
+
+## 🧭 Package Role
+
+The core package defines the shared language used by loaders, model runtimes, renderers, and the public facade:
+
+- model sources and normalized settings;
+- session phases and state;
+- runtime events and progress payloads;
+- model programs and instances;
+- frame snapshots and drawable data;
+- asset resolver contracts;
+- format detection shared across packages.
+
+It does not fetch network resources, decode MOC binaries, create a canvas, or issue GPU commands.
+
+## 📦 Installation
+
+```bash
+pnpm add @doki-land/live2d-core
+```
+
+Install this package directly only when implementing a compatible loader, renderer, diagnostic tool, or host integration.
+
+## 🧱 Design Principles
+
+- Contracts remain independent of game engines, blog engines, and UI frameworks.
+- Graphics API types do not leak into model and session contracts.
+- Model-format parsing does not belong in core.
+- Public data uses explicit typed structures rather than hidden runtime globals.
+- Events remain small enough for browsers and lightweight hosts.
+
+## 🧩 Core Contracts
+
+The package exposes types such as:
+
+```ts
+import type {
+  AssetResolver,
+  FrameSnapshot,
+  Live2DSession,
+  ModelSettings,
+  ModelSource,
+} from "@doki-land/live2d-core";
+```
+
+An asset resolver provides model-related resources without prescribing HTTP, file-system, CDN, or package-registry behavior:
+
+```ts
+const resolver: AssetResolver = {
+  async fetchJson(url) {
+    const response = await fetch(url);
+    return response.json();
+  },
+  async fetchBytes(url) {
+    const response = await fetch(url);
+    return response.arrayBuffer();
+  },
+};
+```
+
+Use the exact exported interface as the source of truth; the example illustrates the ownership boundary rather than guaranteeing every method name across versions.
+
+## 🔄 Session Lifecycle
+
+A runtime session moves through explicit phases rather than relying on DOM state:
+
+```text
+idle -> mounting -> ready -> loading -> live
+                               \-> error
+```
+
+Consumers should listen to phase and error events instead of inferring readiness from a non-null canvas or model reference.
+
+## 📸 Frame Data
+
+`FrameSnapshot` represents evaluated CPU-side model output. It is useful for:
+
+- renderer input;
+- deterministic fixtures;
+- diagnostic capture;
+- regression fingerprints;
+- model inspection tools.
+
+Frame data must not contain host-specific UI state or require a renderer to reload source assets.
+
+## 🧪 Development
+
+```bash
+pnpm --filter @doki-land/live2d-core typecheck
+pnpm --filter @doki-land/live2d-core test
+```
+
+Contract changes should include compatibility notes in the change itself and update all workspace consumers in the same change set.
+
+## 🤝 Contributing
+
+Avoid adding convenience APIs that belong to the facade. A core abstraction should be shared by at least two implementation layers and remain meaningful without a browser UI framework.
+
+## 📄 License
+
+See the repository license.

package/dist/index.d.ts

@@ -182,6 +182,24 @@ interface FrameSnapshot {
     readonly drawables: readonly FrameDrawable[];
 }
 
+/**
+ * Read-only model resources shared across actors on one stage
+ * (settings, decoded topology, textures, motion definitions).
+ */
+interface ModelAsset {
+    readonly key: string;
+    readonly settings: ModelSettings;
+}
+/** Stage-scoped model resource cache (`stage.assets`). */
+interface Live2dStageAssets {
+    load(source: ModelSource, resolver?: AssetResolver): Promise<ModelAsset>;
+}
+/** Per-actor mutable runtime bound to a shared {@link ModelAsset}. */
+interface ActorInstance {
+    readonly asset: ModelAsset;
+    readonly model: InternalModel;
+}
+
 /**
  * CPU model program / instance shapes (format adapters fill these).
  */
@@ -300,6 +318,14 @@ type StageUpdateMode = "auto" | "manual";
 interface CreateLive2dStageOptions {
     updateMode?: StageUpdateMode;
 }
+interface PlayMotionActorOptions {
+    priority?: number;
+    slot?: string;
+    queue?: boolean;
+    loop?: boolean;
+    fadeInTime?: number;
+    fadeOutTime?: number;
+}
 /** Read-only actor surface exposed by the stage. */
 interface Live2dActor {
     readonly id: string;
@@ -312,17 +338,44 @@ interface Live2dActor {
     getTransform(): ActorTransform;
     setTransform(patch: Partial<ActorTransform>): void;
     load(source: ModelSource, resolver?: AssetResolver): Promise<InternalModel>;
+    /** Attach a stage-cached {@link ModelAsset} without re-fetching resources. */
+    loadAsset(asset: ModelAsset): Promise<InternalModel>;
     setParameter(id: string, value: number): void;
+    listParameters(): ReadonlyArray<{
+        id: string;
+        min: number;
+        max: number;
+        defaultValue: number;
+        value: number;
+    }>;
+    listMotionGroups(): Record<string, readonly MotionDefinition[]>;
+    playMotion(group: string, index?: number, options?: PlayMotionActorOptions): Promise<boolean>;
+    stopMotion(opts?: {
+        fade?: boolean;
+        slot?: string;
+    }): void;
+    listPlayingMotions(): ReadonlyArray<{
+        slot: string;
+        group: string;
+        index: number;
+        time: number;
+        priority: number;
+    }>;
     lookAt(stageX: number, stageY: number): void;
     destroy(): void;
 }
 /** Multi-character stage owning one canvas surface and shared renderer. */
 interface Live2dStage {
     readonly actors: readonly Live2dActor[];
+    /** Shared model resource cache for multi-actor reuse. */
+    readonly assets: Live2dStageAssets;
     mount(canvas: HTMLCanvasElement): Promise<void>;
     createActor(options?: CreateActorOptions): Live2dActor;
+    getActor(id: string): Live2dActor | null;
     removeActor(actor: Live2dActor | string): void;
     defineLayers(layers: readonly string[]): void;
+    /** Sync canvas backing store and renderer to CSS or explicit pixel size. */
+    resize(width?: number, height?: number): void;
     update(deltaTimeSeconds: number): void;
     render(): void;
     start(): void;
@@ -343,4 +396,4 @@ interface Live2dStage {
 
 declare const LIVE2D_CORE_VERSION: "0.0.0";
 
-export { type ActorHit, type ActorTransform, type AssetKey, type AssetResolver, type CreateActorOptions, type CreateLive2dStageOptions, DEFAULT_ACTOR_TRANSFORM, type DrawableProgram, EventEmitter, type ExpressionDefinition, FrameBlendMode, type FrameDrawable, type FrameProfile, type FrameSnapshot, type HitAreaDefinition, type InternalModel, LIVE2D_CORE_VERSION, type Live2DEventMap, type Live2DEventName, type Live2DListener, type Live2DSession, type Live2dActor, type Live2dStage, type LoadProgress, type LoadProgressStage, type ModelFormat, type ModelInstance, type ModelProgram, type ModelSettings, type ModelSource, type MotionDefinition, type ParameterProgram, type PointerTrackingMode, type PointerTrackingPolicy, type SessionPhase, type SessionState, type StagePointerEvent, type StageUpdateMode, createSessionStub, detectModelSettingsFormat, modelSourceUrl };
+export { type ActorHit, type ActorInstance, type ActorTransform, type AssetKey, type AssetResolver, type CreateActorOptions, type CreateLive2dStageOptions, DEFAULT_ACTOR_TRANSFORM, type DrawableProgram, EventEmitter, type ExpressionDefinition, FrameBlendMode, type FrameDrawable, type FrameProfile, type FrameSnapshot, type HitAreaDefinition, type InternalModel, LIVE2D_CORE_VERSION, type Live2DEventMap, type Live2DEventName, type Live2DListener, type Live2DSession, type Live2dActor, type Live2dStage, type Live2dStageAssets, type LoadProgress, type LoadProgressStage, type ModelAsset, type ModelFormat, type ModelInstance, type ModelProgram, type ModelSettings, type ModelSource, type MotionDefinition, type ParameterProgram, type PlayMotionActorOptions, type PointerTrackingMode, type PointerTrackingPolicy, type SessionPhase, type SessionState, type StagePointerEvent, type StageUpdateMode, createSessionStub, detectModelSettingsFormat, modelSourceUrl };

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@doki-land/live2d-core",
-  "version": "0.0.13",
-  "description": "Live2D types, events, and session contracts",
+  "version": "0.0.15",
+  "description": "Shared TypeScript contracts for live2d.ts — ModelSource, Live2dStage/Actor, ModelAsset, events (no DOM/GPU).",
   "type": "module",
   "license": "MIT",
-  "author": "Doki Land",
+  "homepage": "https://github.com/doki-land/live2d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doki-land/live2d.ts.git",
+    "directory": "projects/live2d-core"
+  },
   "keywords": [
     "live2d",
     "doki-land"
@@ -16,7 +21,8 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "README.md"
   ],
   "publishConfig": {
     "access": "public",
@@ -34,9 +40,5 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests"
   },
-  "sideEffects": false,
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/doki-land/live2d.ts.git"
-  }
+  "sideEffects": false
 }

package/src/index.ts

@@ -33,6 +33,11 @@ export type {
     ModelSettings,
     MotionDefinition,
 } from "./model.js";
+export type {
+    ActorInstance,
+    Live2dStageAssets,
+    ModelAsset,
+} from "./model-asset.js";
 export type {
     DrawableProgram,
     ModelInstance,
@@ -50,6 +55,7 @@ export type {
     CreateLive2dStageOptions,
     Live2dActor,
     Live2dStage,
+    PlayMotionActorOptions,
     PointerTrackingMode,
     PointerTrackingPolicy,
     StagePointerEvent,

package/src/model-asset.ts

@@ -0,0 +1,22 @@
+import type { AssetResolver, ModelSource } from "./contracts.js";
+import type { InternalModel, ModelSettings } from "./model.js";
+
+/**
+ * Read-only model resources shared across actors on one stage
+ * (settings, decoded topology, textures, motion definitions).
+ */
+export interface ModelAsset {
+    readonly key: string;
+    readonly settings: ModelSettings;
+}
+
+/** Stage-scoped model resource cache (`stage.assets`). */
+export interface Live2dStageAssets {
+    load(source: ModelSource, resolver?: AssetResolver): Promise<ModelAsset>;
+}
+
+/** Per-actor mutable runtime bound to a shared {@link ModelAsset}. */
+export interface ActorInstance {
+    readonly asset: ModelAsset;
+    readonly model: InternalModel;
+}

package/src/stage.ts

@@ -1,4 +1,6 @@
-import type { InternalModel } from "./model.js";
+import type { AssetResolver, ModelSource } from "./contracts.js";
+import type { InternalModel, MotionDefinition } from "./model.js";
+import type { ModelAsset } from "./model-asset.js";
 
 /** Normalized stage placement for one actor (0,0) top-left → (1,1) bottom-right. */
 export interface ActorTransform {
@@ -77,6 +79,15 @@ export interface CreateLive2dStageOptions {
     updateMode?: StageUpdateMode;
 }
 
+export interface PlayMotionActorOptions {
+    priority?: number;
+    slot?: string;
+    queue?: boolean;
+    loop?: boolean;
+    fadeInTime?: number;
+    fadeOutTime?: number;
+}
+
 /** Read-only actor surface exposed by the stage. */
 export interface Live2dActor {
     readonly id: string;
@@ -91,13 +102,39 @@ export interface Live2dActor {
 
     setTransform(patch: Partial<ActorTransform>): void;
 
-    load(
-        source: import("./contracts.js").ModelSource,
-        resolver?: import("./contracts.js").AssetResolver,
-    ): Promise<InternalModel>;
+    load(source: ModelSource, resolver?: AssetResolver): Promise<InternalModel>;
+
+    /** Attach a stage-cached {@link ModelAsset} without re-fetching resources. */
+    loadAsset(asset: ModelAsset): Promise<InternalModel>;
 
     setParameter(id: string, value: number): void;
 
+    listParameters(): ReadonlyArray<{
+        id: string;
+        min: number;
+        max: number;
+        defaultValue: number;
+        value: number;
+    }>;
+
+    listMotionGroups(): Record<string, readonly MotionDefinition[]>;
+
+    playMotion(
+        group: string,
+        index?: number,
+        options?: PlayMotionActorOptions,
+    ): Promise<boolean>;
+
+    stopMotion(opts?: { fade?: boolean; slot?: string }): void;
+
+    listPlayingMotions(): ReadonlyArray<{
+        slot: string;
+        group: string;
+        index: number;
+        time: number;
+        priority: number;
+    }>;
+
     lookAt(stageX: number, stageY: number): void;
 
     destroy(): void;
@@ -107,14 +144,22 @@ export interface Live2dActor {
 export interface Live2dStage {
     readonly actors: readonly Live2dActor[];
 
+    /** Shared model resource cache for multi-actor reuse. */
+    readonly assets: import("./model-asset.js").Live2dStageAssets;
+
     mount(canvas: HTMLCanvasElement): Promise<void>;
 
     createActor(options?: CreateActorOptions): Live2dActor;
 
+    getActor(id: string): Live2dActor | null;
+
     removeActor(actor: Live2dActor | string): void;
 
     defineLayers(layers: readonly string[]): void;
 
+    /** Sync canvas backing store and renderer to CSS or explicit pixel size. */
+    resize(width?: number, height?: number): void;
+
     update(deltaTimeSeconds: number): void;
 
     render(): void;