pixi-live2d-display-advanced 1.0.1 → 2.0.0-beta.2

package/README.md

@@ -1,179 +1,233 @@
 # pixi-live2d-display-advanced
 
 ![NPM Version](https://img.shields.io/npm/v/pixi-live2d-display-advanced?style=flat-square&label=version)
-![Cubism version](https://img.shields.io/badge/Cubism-2/3/4-ff69b4?style=flat-square)
+![Cubism version](https://img.shields.io/badge/Cubism-2/3/4/5-ff69b4?style=flat-square)
 
-A Live2D plugin for [PixiJS](https://github.com/pixijs/pixi.js) v7.
+**English (Current)** | [**简体中文**](README-ZH.md)
 
-This project provides a **unified and simplified API** for controlling Live2D models on the web.
-Compared to the official Live2D SDKs, this library is easier to use, more reliable, and more maintainable.
+A Live2D rendering and control plugin designed for **[PixiJS v8](https://pixijs.com/)**.
+
+This project aims to provide a **unified, concise, and highly maintainable** API for loading, rendering, and interacting with Live2D models on the Web.  
+Compared to the official Live2D SDK, this library significantly reduces usage complexity while preserving full functionality, with additional optimizations for stability and long-term maintainability.
+
+This project is based on the  
+[pixi-live2d-display-mulmotion](https://github.com/Sekai-World/pixi-live2d-display) branch.  
+Starting from **v2.0.0**, it is **fully compatible with PixiJS v8 and Live2D Cubism 5.4 SDK**, and further provides:
+
+- Additional practical APIs
+- Stronger TypeScript type safety
+- Optimized internal architecture for extensibility and maintainability
+
+> [!IMPORTANT]
+> The project is currently in the testing phase. If you want to try it out, please install it using the following command:
+> 
+> If you are using PixiJS v7, please install the v1.x version.
+> 
+> ```shell
+> npm install pixi-live2d-display-advanced@prerelease
+> ```
 
-Compared to [pixi-live2d-display-mulmotion](https://www.npmjs.com/package/pixi-live2d-display-mulmotion), this project
-additionally supports **playing the last frame of motions**, which is especially useful in
-**Project SEKAI-like projects** where animations need to be reapplied frequently, and uses `@pixi/sound` as the audio
-backend, fixing many issues such as model update and display anomalies.
 
 ---
 
 ## Features
 
-- Supports all versions of Live2D models (Cubism 2.1, 3, 4)
+- Supports **all versions** of Live2D models (Cubism 2 / 3 / 4 / 5)
 - Compatible with `PIXI.RenderTexture` and `PIXI.Filter`
-- Familiar Pixi.js style transform API: `position`, `scale`, `rotation`, `skew`, `anchor`
-- Automatic interaction: mouse tracking, hit detection on click
-- Enhanced motion reservation logic compared to the official framework
-- Load models from uploaded files or zip archives (experimental)
-- Complete TypeScript type definitions
-- Real-time lip sync
-- Play multiple motions simultaneously
-- Play the last frame of motions
+- Provides a complete **PixiJS-style transform API**
+  - `position`
+  - `scale`
+  - `rotation`
+  - `skew`
+  - `anchor`
+
+- Built-in interaction support
+  - Mouse tracking
+  - Hit area detection
+
+- Improved **motion scheduling and reservation logic** compared to the official SDK
+- Complete and strict **TypeScript type definitions**
+- Real-time lip sync support
+- **Parallel motion playback**
+- Support for **freezing at the last frame of motions**
 
 ---
 
 ## Requirements
 
-- **PixiJS**: 7.x
-- **Cubism Core**: 2.1 or 4
-- **Browser**: WebGL, ES6
+- **PixiJS**: `8.x`
+- **Cubism runtime**: `2.1` or `5`
+- **Browser**: Must support `WebGL` and `ES6`
 
 ---
 
-## Examples
+## Installation
 
-- [Basic Example](#basic-usage)
-- [Interaction Example](https://codepen.io/guansss/pen/KKgXBOP/left?editors=0010)
-- [Render Texture & Filter Example](https://codepen.io/guansss/pen/qBaMNQV/left?editors=1010)
-- [Live2D Viewer Online](https://guansss.github.io/live2d-viewer-web/)
-- [Parallel Motions Example](#parallel-motions)
-- [Play Motion Last Frame](#play-motion-last-frame)
+### Using npm / pnpm
 
-Documentation:
+```bash
+pnpm add pixi-live2d-display-advanced
+# or
+npm install pixi-live2d-display-advanced
+```
 
-- [User Guide](https://guansss.github.io/pixi-live2d-display)
-- [API Reference](https://guansss.github.io/pixi-live2d-display/api/index.html)
+```ts
+import { Live2DModel } from 'pixi-live2d-display-advanced'
 
----
+// Cubism Legacy only (Cubism 2.1)
+import { Live2DModel } from 'pixi-live2d-display-advanced/cubism-legacy'
 
-## Cubism Runtime
+// Cubism Modern only (Cubism 3 / 4 / 5)
+import { Live2DModel } from 'pixi-live2d-display-advanced/cubism'
+```
 
-Cubism is the official name of the Live2D SDK.
-Currently, there are three versions: **Cubism 2.1**, **Cubism 3**, and **Cubism 4** (Cubism 4 is backward-compatible
-with Cubism 3).
+---
 
-This plugin supports **Cubism 2.1 and Cubism 4**, covering all versions of Live2D models.
+## Cubism Runtime Overview
 
-### Load Cubism Core
+This project supports **all versions of Live2D models**, which can be categorized by Cubism architecture:
 
-- **Cubism 4**: `live2dcubismcore.min.js`
+- **Cubism Legacy**: Cubism 2.1
+- **Cubism Modern**: Cubism 3 / 4 / 5
 
-  - Download from the [Cubism 4 SDK](https://www.live2d.com/download/cubism-sdk/download-web/)
-  - Or use this [link](https://cubism.live2d.com/sdk-web/cubismcore/live2dcubismcore.min.js) _(not guaranteed to be
-    always available, do not use in production)_
+Choose the appropriate runtime entry based on the model you are using.
 
-- **Cubism 2.1**: `live2d.min.js`
+### Using Cubism Legacy and Cubism Modern Together
 
-  - The official site no longer provides it since [September 4, 2019](https://help.live2d.com/en/other/other_20/)
-  - Available on [GitHub](https://github.com/dylanNew/live2d/tree/master/webgl/Live2D/lib)
-  - Or via [jsDelivr CDN](https://cdn.jsdelivr.net/gh/dylanNew/live2d/webgl/Live2D/lib/live2d.min.js)
+#### Bundle entry
 
-### Bundled Files
+```text
+index.js
+```
 
-This plugin provides **separate builds** for different Cubism versions:
+> Use this unified entry when your project needs to load both Cubism 2 and Cubism 3+ models.
 
-- `cubism2.js` + `live2d.min.js` → supports Cubism 2.1 models
-- `cubism4.js` + `live2dcubismcore.min.js` → supports Cubism 3 & 4 models
-- `index.js` + both runtimes → supports all versions
+---
 
-> [!WARNING]
-> Do **not** use `cubism2.js` and `cubism4.js` together. Use `index.js` instead if you need both.
+### Cubism Legacy Only (Cubism 2.1)
 
----
+#### Prerequisites
 
-## Installation
+You must manually include `live2d.min.js`:
 
-Via npm:
+- Official distribution was discontinued on
+  [September 4, 2019](https://help.live2d.com/en/other/other_20/)
+- Available from:
+  - GitHub:
+    [https://github.com/dylanNew/live2d/tree/master/webgl/Live2D/lib](https://github.com/dylanNew/live2d/tree/master/webgl/Live2D/lib)
+  - jsDelivr CDN:
+    [https://cdn.jsdelivr.net/gh/dylanNew/live2d/webgl/Live2D/lib/live2d.min.js](https://cdn.jsdelivr.net/gh/dylanNew/live2d/webgl/Live2D/lib/live2d.min.js)
 
-```sh
-npm install pixi-live2d-display-advanced
+#### Bundle entry
+
+```text
+cubism-legacy.js
 ```
 
-Usage:
+---
 
-```ts
-import { Live2DModel } from 'pixi-live2d-display-advanced'
+### Cubism Modern Only (Cubism 3 / 4 / 5)
+
+#### Prerequisites
+
+You must include `live2dcubismcore.min.js`:
 
-// Only Cubism 2.1
-import { Live2DModel } from 'pixi-live2d-display-advanced/cubism2'
+- Downloadable from the official **Cubism 5 SDK**
+  [https://www.live2d.com/download/cubism-sdk/download-web/](https://www.live2d.com/download/cubism-sdk/download-web/)
 
-// Only Cubism 4
-import { Live2DModel } from 'pixi-live2d-display-advanced/cubism4'
+#### Bundle entry
+
+```text
+cubism.js
 ```
 
 ---
 
-## Basic Usage
-
-See example project: [pixi-live2d-display-lipsync](https://github.com/RaSan147/pixi-live2d-display)
+## Quick Start
 
-When using the Cubism 4 module, you need to call configureCubism4() once before loading models.
-This is required to fix potential issues with model updates.
+The following example is based on **PixiJS v8** and supports both Cubism Legacy and Cubism Modern.
 
 ```ts
-import { Live2DModel, configureCubism4 } from 'pixi-live2d-display-advanced/cubism4'
+import { Application } from 'pixi.js'
+import { configureCubism, Live2DModel } from 'pixi-live2d-display-advanced'
+
+const app = new Application({
+  resizeTo: window,
+  preference: 'webgl'
+})
+
+document.body.appendChild(app.view as HTMLCanvasElement)
 
-// Configure Cubism runtime (only needs to be called once)
-configureCubism4({
-  memorySizeMB: 128
+// Configure Cubism Modern work memory (optional, default is 16MB)
+// Increase this value when loading multiple or high-complexity models
+configureCubism({
+  memorySizeMB: 32
 })
 
-// Load a model
-const model = await Live2DModel.from('mymodel.model3.json')
+const model = await Live2DModel.from('model/model3.json')
+model.anchor.set(0.5)
+model.position.set(app.screen.width / 2, app.screen.height / 2)
+
 app.stage.addChild(model)
 ```
 
 ---
 
-## Parallel Motions
+## Common API Examples
+
+### Play a Motion
 
 ```ts
-model.parallelMotion([
-  { group: motion_group1, index: motion_index1, priority: MotionPriority.NORMAL },
-  { group: motion_group2, index: motion_index2, priority: MotionPriority.NORMAL }
-])
+model.motion('group', index)
 ```
 
-For syncing motions with expressions/sounds, use `model.motion` or `model.speak` for one motion, and
-`model.parallelMotion` for others.
-Each item has independent priority control, following the same logic as `model.motion`.
+### Parallel Motions
 
----
+```ts
+model.parallelMotion([
+  { group: group1, index: index1 },
+  { group: group2, index: index2 }
+])
+```
 
-## Play Motion Last Frame
+### Play and Freeze at the Last Frame
 
-Single motion:
+**Single motion:**
 
 ```ts
-await model.motionLastFrame('w-cute12-tilthead', 0)
+model.motionLastFrame('group', index)
 ```
 
-Multiple motions:
+**Multiple motions:**
 
 ```ts
 await model.parallelLastFrame([
-  { group: 'w-cute12-tilthead', index: 0 },
-  { group: 'face_worry_01', index: 0 }
+  { group: group1, index: index1 },
+  { group: group2, index: index2 }
 ])
 ```
 
-Or with manual parallel motion managers:
+### Lip Sync
 
 ```ts
-model.internalModel.extendParallelMotionManager(2)
-const manager1 = model.internalModel.parallelMotionManager[0]!
-const manager2 = model.internalModel.parallelMotionManager[1]!
+model.speak('audio_file_url')
+```
 
-manager1.playMotionLastFrame('w-cute12-tilthead', 0)
-manager2.playMotionLastFrame('face_worry_01', 0)
+### Expressions
+
+```ts
+model.expression('id')
 ```
 
-Both approaches are equivalent — the first is syntactic sugar for the second.
+For more advanced usage, see
+[pixi-live2d-display-lipsync](https://github.com/RaSan147/pixi-live2d-display)
+
+---
+
+## FAQ
+
+### Q: Why do models stop updating when multiple models are loaded?
+
+When using the **Cubism Modern** runtime, this issue is usually caused by insufficient work memory configured via `configureCubism`.
+
+Try increasing `memorySizeMB` during initialization (minimum: 16MB).