@seayoo-web/pixi-live2d 0.1.0 → 1.0.0

package/README.md

@@ -4,10 +4,10 @@
 
 ## 特性
 
-- **零 Vue 依赖**：纯 TypeScript 实现，可用于任何框架（React, Vue, Vanilla JS）。
-- **自动缩放**：内置适配 1920x1080 设计稿的响应式缩放逻辑。
-- **简单易用**：只需传入 Canvas 元素和模型路径即可。
-- **交互支持**：内置点击交互与动作播放方法。
+- **零框架依赖**：纯 TypeScript 实现，可用于任何框架（React、Vue、Vanilla JS）。
+- **多实例**：每个 `Live2DViewer` 持有独立的 PIXI 应用与 WebGL context，可在页面多处同时渲染、互不干扰。
+- **响应式缩放**：按 canvas 容器尺寸适配设计稿（默认 1920×1080），并可选监听窗口 resize 自动调整。
+- **交互支持**：内置点击播放动作、指针跟随等交互。
 
 ## 安装
 
@@ -15,92 +15,106 @@
 pnpm add @seayoo-web/pixi-live2d
 ```
 
-## 在你的项目中使用：
+## 使用
 
 ### 基础用法
 
 ```typescript
 import { Live2DViewer } from "@seayoo-web/pixi-live2d";
 
-// 方式 1: 传入 Canvas ID
-const viewer1 = new Live2DViewer("live2d-canvas", {
+// 方式 1：传入 canvas 元素的 id
+const viewer = new Live2DViewer("live2d-canvas", {
   modelPath: "https://cdn.example.com/live2d/model.json",
 });
 
-// 方式 2: 传入 HTMLCanvasElement 并配置初始参数
-const canvasElement = document.getElementById("my-canvas") as HTMLCanvasElement;
-const viewer2 = new Live2DViewer(canvasElement, {
+// 方式 2：传入 HTMLCanvasElement 并配置初始参数
+const canvas = document.getElementById("my-canvas") as HTMLCanvasElement;
+const viewer2 = new Live2DViewer(canvas, {
   modelPath: "https://cdn.example.com/live2d/model.json",
-
-  // 初始位置和缩放
   x: 0,
   y: 0,
   scale: 0.2, // 模型缩放比例
-
-  // 设计稿尺寸 (用于自动计算适配比例)
-  designWidth: 1920,
+  designWidth: 1920, // 设计稿尺寸（用于自动计算适配比例）
   designHeight: 1080,
-
   autoResize: true,
-
-  onModelLoaded: (model) => {
-    console.log("模型加载成功:", model);
-  },
-  onModelError: (error) => {
-    console.error("模型加载失败:", error);
-  },
+  onModelLoaded: (model) => console.log("模型加载成功:", model),
+  onModelError: (error) => console.error("模型加载失败:", error),
 });
 ```
 
-### API 说明
+### 多实例
 
-#### `new Live2DViewer(canvas, options)`
+每个实例使用各自的 canvas，可同时存在于页面不同位置、互不干扰：
 
-- `canvas`: `HTMLCanvasElement | string` - 用于渲染的 Canvas 元素或其 ID
-- `options`: `Live2DViewerOptions` - 配置项
+```typescript
+const left = new Live2DViewer("canvas-left", { modelPath: "/a/model.json", scale: 0.2 });
+const right = new Live2DViewer("canvas-right", { modelPath: "/b/model.json", scale: 0.2 });
 
-| 属性 | 类型 | 默认值 | 说明 |
-|Data Type|Type|Default|Description|
-|---|---|---|---|
-| `modelPath` | `string` | (必填) | Live2D 模型配置文件 (.json) 的路径 |
-| `scale` | `number` | - | 初始缩放比例 |
-| `x` | `number` | 0 | 初始 X 轴偏移 |
-| `y` | `number` | 0 | 初始 Y 轴偏移 |
-| `designWidth` | `number` | 1920 | 设计稿宽度（用于适配计算） |
-| `designHeight` | `number` | 1080 | 设计稿高度（用于适配计算） |
-| `autoResize` | `boolean` | `true` | 是否监听窗口 resize 事件并自动调整模型大小 |
-| `onModelLoaded` | `(model) => void` | - | 模型加载完成后的回调函数 |
-| `onModelError` | `(error) => void` | - | 模型加载失败的回调函数 |
-
-#### 实例方法
-
-- **`startMotion(group: string, no: number)`**
-  播放指定分组的动作。
+// 卸载时分别销毁，各自释放 WebGL context
+left.destroy();
+right.destroy();
+```
 
-  ```typescript
-  viewer.startMotion("TapBody", 0);
-  ```
+> 浏览器对同页 WebGL context 数量有上限（通常约 16 个），请按需创建并在不用时调用 `destroy()`。
 
-- **`setScale(scale: number)`**
-  设置模型的缩放比例（基于自动计算的基础比例）。
+### 自定义 Cubism Core 地址
 
-  ```typescript
-  viewer.setScale(0.2);
-  ```
+库默认从内置 CDN 加载 Live2D Cubism Core。可通过 `cubismCoreUrl` 覆盖，或在创建实例前手动预加载：
+
+```typescript
+// 预加载（可选），多次调用会自动去重
+await Live2DViewer.loadCubismCore("https://your-cdn.com/live2dcubismcore.js");
+
+const viewer = new Live2DViewer("canvas", {
+  modelPath: "/model.json",
+  cubismCoreUrl: "https://your-cdn.com/live2dcubismcore.js",
+});
+```
 
-- **`resize()`**
-  手动触发一次重新计算布局（通常在容器大小变化但窗口大小未变时使用）。
+## API
 
-  ```typescript
-  viewer.resize();
-  ```
+### `new Live2DViewer(canvas, options)`
+
+- `canvas`: `HTMLCanvasElement | string` —— 用于渲染的 canvas 元素或其 id
+- `options`: `Live2DViewerOptions` —— 配置项
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelPath` | `string` | （必填） | Live2D 模型配置文件 (.json) 的路径 |
+| `scale` | `number` | `1` | 模型初始缩放比例 |
+| `x` | `number` | `0` | 初始 X 轴偏移 |
+| `y` | `number` | `0` | 初始 Y 轴偏移 |
+| `designWidth` | `number` | `1920` | 设计稿宽度（用于适配计算） |
+| `designHeight` | `number` | `1080` | 设计稿高度（用于适配计算） |
+| `autoResize` | `boolean` | `true` | 是否监听窗口 resize 自动调整模型大小 |
+| `interactive` | `boolean` | `true` | 是否响应指针移动进行跟随；设为 `false` 会同时禁用模型自然晃动 |
+| `enableTapBody` | `boolean` | `true` | 是否在点击时触发 `TapBody` 动作 |
+| `cubismCoreUrl` | `string` | 内置 CDN | Cubism Core 库的加载地址 |
+| `onModelLoaded` | `(model) => void` | - | 模型加载完成后的回调 |
+| `onModelError` | `(error: Error) => void` | - | 模型加载失败的回调 |
+
+### 实例方法
+
+- **`startMotion(group, no, priority?, startTime?)`** —— 播放指定分组的动作。`priority` 默认 `1`；`startTime`（秒）默认 `0`，大于 0 时从该时间点开始播放。返回 `Promise<boolean>`。
 
-- **`destroy()`**
-  销毁实例，清理 PIXI 应用及事件监听。
   ```typescript
-  viewer.destroy();
+  await viewer.startMotion("TapBody", 0);
   ```
 
+- **`expression(name)`** —— 播放指定表情（名称或索引）。
+- **`waitForMotionFinish()`** —— 返回 `Promise<boolean>`，当前动作播放结束后 resolve；无模型时立即 resolve `false`。
+- **`setScale(scale)`** —— 设置模型缩放比例并刷新布局。
+- **`setXY(x, y)`** —— 设置模型偏移并刷新布局。
+- **`resize()`** —— 手动按当前 canvas 尺寸重新计算布局（容器尺寸变化但窗口未变时使用）。
+- **`lockHeadAngle()`** —— 禁用模型的自然晃动（呼吸、身体/头部摇摆等）。注意：尽管命名含 head，实际会关闭**全部**自然动作。
+- **`destroy()`** —— 销毁实例：移除监听、销毁模型，并释放该实例的 PIXI 应用与 WebGL context（不会移除你传入的 canvas）。销毁后该实例不可复用。
+
+### 静态方法
+
+- **`Live2DViewer.loadCubismCore(url?)`** —— 预加载 Cubism Core 库，全局按需去重、只真正加载一次；加载失败会抛出明确错误。
+
 ## 注意事项
 
-本库依赖 `pixi.js` v6 版本（与 `pixi-live2d-display` 兼容），请确保项目中未安装冲突的 PIXI 版本。
+- 本库依赖 `pixi.js` v6（与 `pixi-live2d-display` 兼容），请确保项目中未安装冲突的 PIXI 版本。
+- 模型适配以 **canvas 的显示尺寸** 为基准，请通过 CSS 给 canvas 设定期望的宽高。
+- `interactive: false` 在禁用指针跟随的同时会关闭模型的自然晃动（等同调用 `lockHeadAngle()`）。