npm - pixi-live2d-display-advanced - Versions diffs - 0.5.6 → 1.0.0 - Mend

pixi-live2d-display-advanced 0.5.6 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md CHANGED Viewed

@@ -3,104 +3,135 @@
 ![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)
-A Live2D plugin for [PixiJS](https://github.com/pixijs/pixi.js) v7
+A Live2D plugin for [PixiJS](https://github.com/pixijs/pixi.js) v7.
-This project aims to be a universal Live2D framework for the web platform.
-Since the official Live2D frameworks are very complex and unreliable, this project rewrites them to provide a unified and simple API,
-allowing you to control Live2D models at a high level without needing to understand the internals.
+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.
-Compared to [pixi-live2d-display-mulmotion](https://www.npmjs.com/package/pixi-live2d-display-mulmotion), this project adds support for
-playing the last frame of motions. In Project SEKAI-like projects, this greatly shortens the time to reapply animations.
+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.
-Additionally, this branch refactors some of the original code, which may improve performance in some areas, but most importantly greatly increases code readability and maintainability.
+---
-#### Features
+## Features
-- Supports all versions of Live2D models
-- Supports PIXI.RenderTexture and PIXI.Filter
-- Pixi.js style transform API: position, scale, rotation, skew, anchor
+- Supports all versions of Live2D models (Cubism 2.1, 3, 4)
+- 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
-- Better motion reservation logic than the official framework
-- Load from uploaded files or zip files (experimental)
-- Complete type definitions - we all love types!
+- 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
-#### Requirements
+---
-- PixiJS: 7.x
-- Cubism core: 2.1 or 4
-- Browser: WebGL, ES6
+## Requirements
-#### Examples
+- **PixiJS**: 7.x
+- **Cubism Core**: 2.1 or 4
+- **Browser**: WebGL, ES6
-- [Basic Example](https://codepen.io/guansss/pen/oNzoNoz/left?editors=1010)
+---
+## Examples
+- [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)
-#### Documentation
+Documentation:
+- [User Guide](https://guansss.github.io/pixi-live2d-display)
+- [API Reference](https://guansss.github.io/pixi-live2d-display/api/index.html)
-- [Documentation](https://guansss.github.io/pixi-live2d-display) (No Chinese translation available yet)
-- [API Docs](https://guansss.github.io/pixi-live2d-display/api/index.html)
+---
-## Cubism
+## Cubism Runtime
-Cubism is the name of the Live2D SDK. There are currently three versions: Cubism 2.1, Cubism 3, and Cubism 4. Cubism 4 is compatible with Cubism 3 models.
+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, thus supporting all versions of Live2D models.
+This plugin supports **Cubism 2.1 and Cubism 4**, covering all versions of Live2D models.
-#### Cubism Core
+### Load Cubism Core
-Before using this plugin, you need to load the Cubism runtime, also known as Cubism Core.
+- **Cubism 4**: `live2dcubismcore.min.js`
-For Cubism 4, load `live2dcubismcore.min.js`.
-You can extract it from the [Cubism 4 SDK](https://www.live2d.com/download/cubism-sdk/download-web/),
-or directly reference [this link](https://cubism.live2d.com/sdk-web/cubismcore/live2dcubismcore.min.js)
-(_Note: this link may occasionally be unavailable, do not use it in production!_)
+  - 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)_
-For Cubism 2.1, load `live2d.min.js`. [Since September 4, 2019](https://help.live2d.com/en/other/other_20/),
-the official website no longer provides this version of the SDK, but you can find it [here](https://github.com/dylanNew/live2d/tree/master/webgl/Live2D/lib),
-or use this [CDN link](https://cdn.jsdelivr.net/gh/dylanNew/live2d/webgl/Live2D/lib/live2d.min.js).
+- **Cubism 2.1**: `live2d.min.js`
-#### Separate Bundled Files
+  - 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)
-This plugin provides separate bundled files for each Cubism version to reduce the file size when you only need one version.
+### Bundled Files
-Specifically, there is a `cubism2.js` and `cubism4.js` for the two versions, and a combined `index.js` that supports both.
+This plugin provides **separate builds** for different Cubism versions:
-**Note:** If you want to support both Cubism 2.1 and Cubism 4, please use `index.js` and _do not use_ `cubism2.js` and `cubism4.js` together.
+- `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
-To be more clear, here are the ways to use these files:
+> [!WARNING]
+> Do **not** use `cubism2.js` and `cubism4.js` together. Use `index.js` instead if you need both.
-- Use `cubism2.js` + `live2d.min.js` to support Cubism 2.1 models
-- Use `cubism4.js` + `live2dcubismcore.min.js` to support Cubism 3 and Cubism 4 models
-- Use `index.js` + `live2d.min.js` + `live2dcubismcore.min.js` to support all versions of models
+---
 ## Installation
-#### Via npm
+Via npm:
 ```sh
 npm install pixi-live2d-display-advanced
 ```
-```js
+Usage:
+```ts
 import { Live2DModel } from 'pixi-live2d-display-advanced'
-// If you only need Cubism 2.1
+// Only Cubism 2.1
 import { Live2DModel } from 'pixi-live2d-display-advanced/cubism2'
-// If you only need Cubism 4
+// Only Cubism 4
 import { Live2DModel } from 'pixi-live2d-display-advanced/cubism4'
 ```
+---
 ## Basic Usage
-See here: [pixi-live2d-display-lipsync](https://github.com/RaSan147/pixi-live2d-display)
+See example project: [pixi-live2d-display-lipsync](https://github.com/RaSan147/pixi-live2d-display)
+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.
+```ts
+import { Live2DModel, configureCubism4 } from 'pixi-live2d-display-advanced/cubism4'
+// Configure Cubism runtime (only needs to be called once)
+configureCubism4({
+  memorySizeMB: 128
+})
+// Load a model
+const model = await Live2DModel.from('mymodel.model3.json')
+app.stage.addChild(model)
+```
+---
 ## Parallel Motions
@@ -111,18 +142,21 @@ model.parallelMotion([
 ])
 ```
-If you need to play expressions, sounds, etc. in sync, use `model.motion`/`model.speak` to play one of the motions, and use `model.parallelMotion` for the other motions.
-Each item in the list (by index) has independent priority control, following the same logic as `model.motion`.
+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`.
+---
 ## Play Motion Last Frame
-For a single motion, you can simply do:
+Single motion:
 ```ts
 await model.motionLastFrame('w-cute12-tilthead', 0)
 ```
-For multiple motions, use:
+Multiple motions:
 ```ts
 await model.parallelLastFrame([
@@ -131,24 +165,15 @@ await model.parallelLastFrame([
 ])
 ```
-Or:
+Or with manual parallel motion managers:
 ```ts
 model.internalModel.extendParallelMotionManager(2)
 const manager1 = model.internalModel.parallelMotionManager[0]!
 const manager2 = model.internalModel.parallelMotionManager[1]!
 manager1.playMotionLastFrame('w-cute12-tilthead', 0)
 manager2.playMotionLastFrame('face_worry_01', 0)
 ```
-Essentially, these two approaches are equivalent. The first usage is just syntactic sugar for the second.
-## v1.0.0 TODOs
-- [ ] Improve documentation
-- [ ] Update tests
-- [ ] Automate build scripts
-In v2.0.0, the project plans to upgrade to pixi.js v8.
-# For more documentation, please refer to: [Documentation](https://guansss.github.io/pixi-live2d-display/)
+Both approaches are equivalent — the first is syntactic sugar for the second.

package/README.zh.md CHANGED Viewed

@@ -1,108 +1,116 @@
-# pixi-live2d-display-advanced
+# 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)
+![NPM 版本](https://img.shields.io/npm/v/pixi-live2d-display-advanced?style=flat-square&label=version)
+![Cubism 版本](https://img.shields.io/badge/Cubism-2/3/4-ff69b4?style=flat-square)
-为 [PixiJS](https://github.com/pixijs/pixi.js) v7 提供的 Live2D 插件
+一款适用于 [PixiJS](https://github.com/pixijs/pixi.js) v7 的 Live2D 插件。
-此项目旨在成为 Web 平台上的通用 Live2D 框架。
-由于 Live2D 的官方框架非常复杂且不可靠，这个项目已将其重写以提供统一且简单的 API，
-使你可以从较高的层次来控制 Live2D 模型而无需了解其内部的工作原理
+该项目为在网页端控制 Live2D 模型提供了**统一且简化的 API**。与官方 Live2D SDK 相比，本库使用更简便、稳定性更高且更易于维护。
-相较于 [pixi-live2d-display-mulmotion](https://www.npmjs.com/package/pixi-live2d-display-mulmotion), 本项目增加了对
-播放动作最末帧的支持。在 Project SEKAI like 项目中大幅地缩短了再次应用动作的时间。
+与 [pixi-live2d-display-mulmotion](https://www.npmjs.com/package/pixi-live2d-display-mulmotion) 相比，该项目额外支持**播放动作的最后一帧**——这在**类 Project SEKAI（世界计划）项目**中尤为实用（此类项目需频繁重新应用动画）；同时，本项目采用 `@pixi/sound` 作为音频后端，修复了模型更新、显示异常等诸多问题。
-此外，本分支还重构了一些本项目的原始代码，可能提升了部分性能，但大幅提高了代码可读性，利于维护。
+## 功能特性
-#### 特性
-- 支持所有版本的 Live2D 模型
-- 支持 PIXI.RenderTexture 和 PIXI.Filter
-- Pixi.js 风格的变换 API：position, scale, rotation, skew, anchor
-- 自动交互：鼠标跟踪, 点击命中检测
-- 比官方框架更好的动作预约逻辑
-- 从上传的文件或 zip 文件中加载 (实验性功能)
-- 完善的类型定义 - 我们都喜欢类型！
+- 支持所有版本的 Live2D 模型（Cubism 2.1、3、4）
+- 兼容 `PIXI.RenderTexture`（渲染纹理）与 `PIXI.Filter`（滤镜）
+- 熟悉的 Pixi.js 风格变换 API：`position`（位置）、`scale`（缩放）、`rotation`（旋转）、`skew`（倾斜）、`anchor`（锚点）
+- 自动交互功能：鼠标追踪、点击命中检测
+- 相比官方框架，优化了动作预约逻辑
+- 支持从上传文件或压缩包中加载模型（实验性功能）
+- 完整的 TypeScript 类型定义
 - 实时口型同步
-- 同时播放多个动作
-- 播放动作最末帧
+- 支持同时播放多个动作
+- 支持播放动作的最后一帧
-#### 要求
+## 依赖要求
-- PixiJS：7.x
-- Cubism core: 2.1 or 4
-- 浏览器：WebGL， ES6
+- **PixiJS**：7.x 版本
+- **Cubism 核心**：2.1 或 4 版本
+- **浏览器**：需支持 WebGL 和 ES6 语法
-#### 示例
+## 示例演示
-- [基础示例](https://codepen.io/guansss/pen/oNzoNoz/left?editors=1010)
+- [基础示例](#基础用法)
 - [交互示例](https://codepen.io/guansss/pen/KKgXBOP/left?editors=0010)
 - [渲染纹理与滤镜示例](https://codepen.io/guansss/pen/qBaMNQV/left?editors=1010)
-- [Live2D Viewer Online](https://guansss.github.io/live2d-viewer-web/)
-- [多动作同步播放](#多动作同步播放)
-- [播放动作最末帧](#播放动作最末帧)
-#### 文档
+- [在线 Live2D 查看器](https://guansss.github.io/live2d-viewer-web/)
+- [并行动作示例](#并行动作)
+- [播放动作最后一帧示例](#播放动作最后一帧)
-- [文档](https://guansss.github.io/pixi-live2d-display)（暂无中文翻译）
-- [API 文档](https://guansss.github.io/pixi-live2d-display/api/index.html)
+文档资料：
-## Cubism
+- [用户指南](https://guansss.github.io/pixi-live2d-display)
+- [API 参考](https://guansss.github.io/pixi-live2d-display/api/index.html)
-Cubism 是 Live2D SDK 的名称，目前有 3 个版本：Cubism 2.1、Cubism 3、Cubism 4，其中 Cubism 4 可以与 Cubism 3 的模型兼容
+## Cubism 运行时
-该插件使用 Cubism 2.1 和 Cubism 4，从而支持所有版本的 Live2D 模型
+Cubism 是 Live2D SDK 的官方名称。目前共有三个版本：**Cubism 2.1**、**Cubism 3** 和 **Cubism 4**（其中 Cubism 4 向下兼容 Cubism 3）。
-#### Cubism Core
+本插件支持 **Cubism 2.1 和 Cubism 4**，可覆盖所有版本的 Live2D 模型。
-在使用该插件之前，你需要加载 Cubism 运行时，也就是 Cubism Core
+### 加载 Cubism 核心文件
-Cubism 4 需要加载 `live2dcubismcore.min.js`
-，可以从 [Cubism 4 SDK](https://www.live2d.com/download/cubism-sdk/download-web/)
-里解压出来，或者直接引用[这个链接](https://cubism.live2d.com/sdk-web/cubismcore/live2dcubismcore.min.js)
-（_链接偶尔会挂掉，不要在生产版本中使用！_）
+- **Cubism 4**：`live2dcubismcore.min.js`
-Cubism 2.1 需要加载 `live2d.min.js`，[从 2019/9/4 起](https://help.live2d.com/en/other/other_20/)
-，官方已经不再提供该版本 SDK 的下载，但是可以从 [这里](https://github.com/dylanNew/live2d/tree/master/webgl/Live2D/lib)
-找到，以及你大概想要的 [CDN 链接](https://cdn.jsdelivr.net/gh/dylanNew/live2d/webgl/Live2D/lib/live2d.min.js)
+  - 可从 [Cubism 4 SDK](https://www.live2d.com/download/cubism-sdk/download-web/) 下载
+  - 也可使用此链接（[link](https://cubism.live2d.com/sdk-web/cubismcore/live2dcubismcore.min.js)）_（不保证长期可用，请勿用于生产环境）_
-#### 单独的打包文件
+- **Cubism 2.1**：`live2d.min.js`
+  - 官方网站自 [2019 年 9 月 4 日](https://help.live2d.com/en/other/other_20/) 起不再提供该文件
+  - 可在 [GitHub](https://github.com/dylanNew/live2d/tree/master/webgl/Live2D/lib) 上获取
+  - 也可通过 [jsDelivr 内容分发网络](https://cdn.jsdelivr.net/gh/dylanNew/live2d/webgl/Live2D/lib/live2d.min.js) 获取
-该插件为每个 Cubism 版本提供了单独的打包文件，从而在你只想使用其中一个版本的时候减少需要加载文件的大小。
+### 打包文件
-具体来说，为两种版本分别提供了 `cubism2.js` 和 `cubism4.js`，以及一个同时包含了两种版本的 `index.js`
+本插件为不同 Cubism 版本提供了**独立的构建文件**：
-注意，如果你想同时支持 Cubism 2.1 和 Cubism 4 的话，请使用 `index.js`，_而不要同时使用_ `cubism2.js` 和 `cubism4.js`
+- `cubism2.js` + `live2d.min.js` → 支持 Cubism 2.1 模型
+- `cubism4.js` + `live2dcubismcore.min.js` → 支持 Cubism 3 和 4 模型
+- `index.js` + 两种运行时 → 支持所有版本的模型
-为了更明确一点，这里列出使用这些文件的方法：
+> [!Warning]
+> 请勿同时使用 `cubism2.js` 和 `cubism4.js`。若需同时支持两种版本，请使用 `index.js`。
-- 使用 `cubism2.js`+`live2d.min.js` 以支持 Cubism 2.1 模型
-- 使用 `cubism4.js`+`live2dcubismcore.min.js` 以支持 Cubism 3 和 Cubism 4 模型
-- 使用 `index.js`+`live2d.min.js`+`live2dcubismcore.min.js` 以支持所有版本的模型
+## 安装方式
-## 安装
-#### 通过 npm
+通过 npm 安装：
 ```sh
 npm install pixi-live2d-display-advanced
 ```
-```js
+使用方式：
+```ts
 import { Live2DModel } from 'pixi-live2d-display-advanced'
-// 如果只需要 Cubism 2.1
+// 仅支持 Cubism 2.1
 import { Live2DModel } from 'pixi-live2d-display-advanced/cubism2'
-// 如果只需要 Cubism 4
+// 仅支持 Cubism 4
 import { Live2DModel } from 'pixi-live2d-display-advanced/cubism4'
 ```
-## 基础使用
+## 基础用法
+参考示例项目：[pixi-live2d-display-lipsync](https://github.com/RaSan147/pixi-live2d-display)
+使用 Cubism 4 模块时，需在加载模型前调用一次 `configureCubism4()` 方法。此操作是修复模型更新潜在问题的必要步骤。
+```ts
+import { Live2DModel, configureCubism4 } from 'pixi-live2d-display-advanced/cubism4'
+// 配置 Cubism 运行时（仅需调用一次）
+configureCubism4({
+  memorySizeMB: 128 // 内存大小（单位：MB）
+})
-参阅此处: [pixi-live2d-display-lipsync](https://github.com/RaSan147/pixi-live2d-display)
+// 加载模型
+const model = await Live2DModel.from('mymodel.model3.json')
+app.stage.addChild(model)
+```
-## 多动作同步播放
+## 并行动作
 ```ts
 model.parallelMotion([
@@ -111,18 +119,17 @@ model.parallelMotion([
 ])
 ```
-若需要同步播放表情、声音等请使用`model.motion`/`model.speak`播放其中一个动作，其余动作用`model.parallelMotion`播放。
-列表中按照 index 每一项都有独立的优先级控制，和`model.motion`逻辑一致。
+若需将动作与表情/声音同步：单个动作可使用 `model.motion` 或 `model.speak` 方法，其他动作可使用 `model.parallelMotion` 方法。每个动作项都拥有独立的优先级控制，其逻辑与 `model.motion` 一致。
-## 播放动作最末帧
+## 播放动作最后一帧
-对于单个动作，可以采用简单的:
+单个动作：
 ```ts
 await model.motionLastFrame('w-cute12-tilthead', 0)
 ```
-对于多个动作，可以使用:
+多个动作：
 ```ts
 await model.parallelLastFrame([
@@ -131,24 +138,15 @@ await model.parallelLastFrame([
 ])
 ```
-或者:
+或使用手动并行动作管理器：
 ```ts
 model.internalModel.extendParallelMotionManager(2)
 const manager1 = model.internalModel.parallelMotionManager[0]!
 const manager2 = model.internalModel.parallelMotionManager[1]!
 manager1.playMotionLastFrame('w-cute12-tilthead', 0)
 manager2.playMotionLastFrame('face_worry_01', 0)
 ```
-实质上，这两个方法是等价的。第一种用法只是第二种用法的语法糖。
-## v1.0.0 TODOs
-- [ ] 完善文档
-- [ ] 更改测试
-- [ ] 自动化构建脚本
-拟在 v2.0.0 中，项目升级到 pixi.js v8
-# 请参阅此处了解更多文档： [文档](https://guansss.github.io/pixi-live2d-display/)
+以上两种方式效果相同——第一种是第二种的语法糖（简化写法）。

package/dist/cubism2.es.js CHANGED Viewed

@@ -78,7 +78,7 @@ const config = {
   preserveExpressionOnMotion: true,
   cubism4: CubismConfig
 };
-const VERSION = "v0.5.6";
+const VERSION = "v1.0.0";
 const logger = {
   log(tag, ...messages) {
     if (config.logLevel <= config.LOG_LEVEL_VERBOSE) {

package/dist/cubism2.js CHANGED Viewed

@@ -79,7 +79,7 @@ var __async = (__this, __arguments, generator) => {
     preserveExpressionOnMotion: true,
     cubism4: CubismConfig
   };
-  const VERSION = "v0.5.6";
+  const VERSION = "v1.0.0";
   const logger = {
     log(tag, ...messages) {
       if (config.logLevel <= config.LOG_LEVEL_VERBOSE) {