pixi-live2d-display

GitHub package.json 版本 GitHub 工作流状态

English | 中文

PixiJS v6 的 Live2D 集成。

本项目旨在成为网络平台上的通用 Live2D 框架。虽然官方的 Live2D 框架复杂且存在问题，但本项目重写了它以统一和简化 API，使您能够在高层次上控制 Live2D 模型，无需了解内部系统的工作原理。

特性

支持所有版本的 Live2D 模型
支持 PIXI.RenderTexture 和 PIXI.Filter
Pixi 风格的变换 API：位置、缩放、旋转、倾斜、锚点
自动交互：聚焦、碰撞检测
与官方框架相比，增强了动作预约逻辑
从上传文件/zip 文件加载（实验性）
完全类型化 - 我们都喜欢类型！

要求

PixiJS：6.x
Cubism core：2.1 或 4
浏览器：WebGL，ES6

演示

文档

Cubism

Cubism 是 Live2D SDK 的名称。目前有三个版本：Cubism 2.1、Cubism 3 和 Cubism 4；其中 Cubism 4 向后兼容 Cubism 3 模型。

本插件通过使用 Cubism 2.1 和 Cubism 4 支持所有类型的 Live2D 模型。

Cubism Core

在使用插件之前，您需要包含 Cubism 运行时库，即 Cubism Core。

对于 Cubism 4，您需要 live2dcubismcore.min.js，可以从 Cubism 4 SDK 中提取，或通过直接链接引用（但直接链接不太可靠，请勿在生产环境中使用！）。

对于 Cubism 2.1，您需要 live2d.min.js。自 2019年9月4日起，官方网站已不再提供下载，但可以在这里找到，并有一个CDN 链接可能会用到。

独立包

插件为每个 Cubism 版本提供独立的包，以减少您的应用程序大小，当您只想使用其中一个版本时。

具体来说，有 cubism2.js 和 cubism4.js 分别用于相应的运行时，以及包含两者的 index.js。

请注意，如果您想同时支持 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 和 Cubism 4 模型
使用 index.js+live2d.min.js+live2dcubismcore.min.js 支持所有版本的模型

安装

通过 npm

npm install pixi-live2d-display

import { Live2DModel } from 'pixi-live2d-display';

// 如果仅使用 Cubism 2.1
import { Live2DModel } from 'pixi-live2d-display/cubism2';

// 如果仅使用 Cubism 4
import { Live2DModel } from 'pixi-live2d-display/cubism4';

通过 CDN

<script src="https://cdn.jsdelivr.net/npm/pixi-live2d-display/dist/index.min.js"></script>

<!-- 如果仅使用 Cubism 2.1 -->
<script src="https://cdn.jsdelivr.net/npm/pixi-live2d-display/dist/cubism2.min.js"></script>

<!-- 如果仅使用 Cubism 4 -->
<script src="https://cdn.jsdelivr.net/npm/pixi-live2d-display/dist/cubism4.min.js"></script>

通过这种方式，所有导出的成员都可以在 PIXI.live2d 命名空间下使用，例如 PIXI.live2d.Live2DModel。

基本用法

import * as PIXI from 'pixi.js';
import { Live2DModel } from 'pixi-live2d-display';

// 将 PIXI 暴露给 window，以便插件能够引用 window.PIXI.Ticker 自动更新 Live2D 模型
window.PIXI = PIXI;

(async function () {
  const app = new PIXI.Application({
    view: document.getElementById('canvas'),
  });

  const model = await Live2DModel.from('shizuku.model.json');

  app.stage.addChild(model);

  // 变换
  model.x = 100;
  model.y = 100;
  model.rotation = Math.PI;
  model.skew.x = Math.PI;
  model.scale.set(2, 2);
  model.anchor.set(0.5, 0.5);

  // 交互
  model.on('hit', (hitAreas) => {
    if (hitAreas.includes('body')) {
      model.motion('tap_body');
    }
  });
})();

包导入

当按需导入 Pixi 包时，您可能需要手动注册一些插件以启用可选功能。

import { Application } from '@pixi/app';
import { Ticker, TickerPlugin } from '@pixi/ticker';
import { InteractionManager } from '@pixi/interaction';
import { Live2DModel } from 'pixi-live2d-display';

// 为 Live2DModel 注册 Ticker
Live2DModel.registerTicker(Ticker);

// 为 Application 注册 Ticker
Application.registerPlugin(TickerPlugin);

// 注册 InteractionManager 使 Live2D 模型可交互
Renderer.registerPlugin('interaction', InteractionManager);

(async function () {
  const app = new Application({
    view: document.getElementById('canvas'),
  });

  const model = await Live2DModel.from('shizuku.model.json');

  app.stage.addChild(model);
})();