pixi-live2d-display からの移行

そもそも移るべきか

pixi-live2d-display は最後の公開が2023年12月で、いまも @pixi/core: "^6" を宣言しています。Pixi 7 や 8 のプロジェクトでは使えません。ただ、Pixi を離れることだけが解決策ではありません。

untitled-pixi-live2d-engine がその後を継いでいます。Pixi v8 で動き、Cubism 2 から 5 までを扱い、API も同じなので、移行は書き直しではなく import の変更で済みます。Pixi を使い続けるつもりなら、そちらが適しています。 Cubism 2.1 のモデルを使っているなら、それだけで決まりです。このランタイムは 2.1 を読み込めません。

このページは反対のケースのためのものです。live2d-web は自前の WebGL2 レンダラーを持ち、キャンバスを自分で所有するので、プロジェクトから Pixi が外れます。Live2D モデルのためだけに Pixi を入れていた場合、React コンポーネントが必要な場合、フェイストラッキングまで同じライブラリから受け取りたい場合はこちらです。書き直しになりますし、この先がその費用です。

何が変わるか

pixi-live2d-display は Live2D モデルを PixiJS の Container として描画します。キャンバス、ticker、WebGL コンテキストは Pixi が持ちます。このランタイムはそれらを自分で持ちます。@pixi/* の peer 依存6つがなくなり、Pixi のバージョンに縛られる部分もありません。

<!-- プラグインが動く前に Cubism Core がページにある必要がある -->
<script src="/live2dcubismcore.min.js"></script>

import { Live2DModel } from 'pixi-live2d-display'
import * as PIXI from 'pixi.js'
 
// プラグインが window.PIXI.Ticker を読んでモデルを更新する
window.PIXI = PIXI
 
const app = new PIXI.Application({ view: canvas })
const model = await Live2DModel.from('/models/avatar.model3.json')
app.stage.addChild(model)
model.scale.set(0.3)
model.position.set(200, 100)

import { createLive2D } from 'live2d-web'
 
const character = await createLive2D({
  container: document.querySelector('#stage')!,
  coreUrl: '/live2dcubismcore.min.js',
  src: '/models/avatar.model3.json',
})

application も stage も、登録する ticker もありません。Cubism Core は coreUrl が読み込むので、script タグも順番を合わせる手間もありません。コンテナに CSS のサイズを与えれば、キャンバスがそこを満たします。

関数の対応

名前が変わるだけで済まないのは配置だけです。Pixi の変換は自分で決めた stage 上のピクセル値ですが、fit は画面へのおさめ方を書くもので、リサイズのたびに計算し直します。配置オーバーレイを開けば、好きな位置へドラッグして値をコピーできます。

移せないもの

• Cubism 2.1 のモデル。 このランタイムは Cubism 3/4/5 専用で、.moc ファイルは読み込めません。pixi-live2d-display と上のフォークはどちらも 2.1 に対応しているので、そのバージョンのリグを使っているなら、そちらに留まる理由になります。
• Pixi のシーングラフ。 フィルター、ブレンドモード、ほかのスプライトとの合成はすべて Pixi のものです。このランタイムは自分のキャンバスを持つため、モデルを Pixi のシーンに置くことはできません。このための互換レイヤーはなく、今後も作りません。他人のレンダラーへ描き込むことこそ、このランタイムが避けるために存在する設計だからです。
• 音声の再生。 SoundManager も model.speak(url) もありません。音声はアプリがすでに持っているので、アプリが再生し、リップシンクがその音で口を動かします。

Cubism Core

移行で最初につまずくのはたいていここです。同梱の Framework 5-r.5 アダプターは Cubism Core 5.3 を必要とし、core/06 として配布されています。古い core/05 は moc の読み込みで失敗するので、Pixi で使っていた Core スクリプトを置き換える必要があるかもしれません。入手先は Core とモデルにあります。

進める順番

1. Cubism Core 5.3 を配置し、モデルがともかく描画されることを確認します。
2. 生成のコードを置き換えます。JavaScript は createLive2D()、React は <Live2DCanvas> と <Live2DModel> です。
3. 座標と拡大率を fit に移します。値は配置オーバーレイで探します。
4. 上の表のとおりに呼び出しを置き換えます。
5. pixi-live2d-display と、Pixi 自体に不要な @pixi/* の依存を削除します。

描画されないときは、先にモデル検査を実行してください。moc のバージョンと足りない資産を報告するので、移行中に起きることの多くはそこで分かります。