Migrating from pixi-live2d-display

Whether to move at all

pixi-live2d-display was last published in December 2023 and still declares @pixi/core: "^6", so a project on Pixi 7 or 8 cannot use it. Leaving Pixi is not the only way out of that.

untitled-pixi-live2d-engine continues it on Pixi v8, covers Cubism 2 through 5, and keeps the same API, which makes moving to it an import change rather than a rewrite. If you want to stay on Pixi, start there. A Cubism 2.1 model settles it on its own: this runtime does not load one.

This page is for the other case. live2d-web brings its own WebGL2 renderer and owns the canvas, so Pixi leaves the project. Take it when Pixi was in the bundle for the Live2D model and nothing else, when you want React components, or when face tracking has to come from the same library. It is a rewrite, and the rest of this page is what that costs.

What changes

pixi-live2d-display renders a Live2D model as a PixiJS Container, so Pixi owns the canvas, the ticker and the WebGL context. This runtime owns them itself. The six @pixi/* peer dependencies go away, and nothing here is tied to a Pixi version.

<!-- Cubism Core has to be in the page before the plugin runs -->
<script src="/live2dcubismcore.min.js"></script>

import { Live2DModel } from 'pixi-live2d-display'
import * as PIXI from 'pixi.js'
 
// the plugin reads window.PIXI.Ticker to update models
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',
})

There is no application, no stage and no ticker to register. coreUrl loads Cubism Core, so the page needs no script tag and nothing has to run in the right order. Give the container a CSS size and the canvas fills it.

Method by method

Placement is the one that is not a rename. Pixi transforms are pixels on a stage you sized; fit describes the framing instead, and recomputes it on every resize. Turn on the placement overlay to drag a model where you want it and copy the value out.

What does not come across

• Cubism 2.1 models. This runtime is Cubism 3/4/5 only, and a .moc file will not load. Both pixi-live2d-display and the fork above cover 2.1, so a rig on that version is a reason to stay with them.
• The Pixi scene graph. Filters, blend modes and mixing a model with other sprites all belong to Pixi. This runtime owns its canvas, so a model cannot be placed inside a Pixi scene. There is no compatibility layer for this and there will not be one: drawing into someone else's renderer is the design this runtime exists to avoid.
• Audio playback. There is no SoundManager and no model.speak(url). The application plays the audio it already owns, and lip sync drives the mouth from it.

Cubism Core

This is where a migration usually stops first. The bundled Framework 5-r.5 adapter needs Cubism Core 5.3, distributed as core/06. An older core/05 file fails while loading the moc, so the Core script you were serving for Pixi may need replacing. Core and models covers where to get it.

Order to do it in

1. Serve Cubism Core 5.3 and confirm a model renders at all.
2. Replace construction: createLive2D() for JavaScript, <Live2DCanvas> with <Live2DModel> for React.
3. Replace transforms with fit, using the placement overlay to find the value.
4. Rename the calls in the table above.
5. Remove pixi-live2d-display and every @pixi/* dependency Pixi itself does not need.

Run the inspector on the model first if it does not render. It reports the moc version and every missing asset, which answers most of what goes wrong on the way over.