@laplace.live/pixijs-live2d

PixiJS v8 Live2D engine for Cubism 3/4/5 models — motions, expressions, physics, pose, lip sync with motion sounds, parallel motions, and hit-area picking. The 2D-object engine of LAPLACE Persona; its WebGPU sibling for three.js is @laplace.live/three-live2d.

Forked from untitled-pixi-live2d-engine v1.3.5 (itself a PixiJS v8 continuation of the pixi-live2d-display line). Diverges deliberately: Cubism 2 support removed, the CubismWebFramework mirrored pristine at tag 5-r.5, and moc3 v6 (Cubism 5.3 offscreens + new blend modes) rendering verified.

Install

npm i @laplace.live/pixijs-live2d pixi.js
npm i @pixi/sound   # optional — motion sounds / audio lip sync

pixi.js ≥ 8.13 is a peer dependency. @pixi/sound is an optional peer, dynamic-imported the first time audio is used.

Cubism Core

Live2D Cubism Core (live2dcubismcore.js) is Live2D's proprietary runtime and is not bundled. Download it with the Cubism SDK for Web, serve it yourself, and load it before this package is imported — the entry throws immediately when window.Live2DCubismCore is missing. A <script> tag ahead of your bundle works; so does evaluating Core first and pulling the engine in with a dynamic import(). Adding the SDK's live2dcubismcore.d.ts to your project completes the typings.

Usage

import { Live2DModel } from '@laplace.live/pixijs-live2d'
import { Application, Ticker } from 'pixi.js'

const app = new Application()
await app.init({ backgroundAlpha: 0 })

Live2DModel.registerTicker(Ticker) // drive motion updates from pixi's shared ticker

const model = await Live2DModel.from('https://example.com/hiyori/hiyori.model3.json')
app.stage.addChild(model)
model.scale.set(0.25)

model.on('hit', (hitAreas) => {
  if (hitAreas.includes('Body')) model.motion('TapBody')
})

@laplace.live/pixijs-live2d/extra ships HitAreaFrames, a debug overlay that draws the model's hit areas.

License

The engine (src/) is MIT, carrying the upstream fork's copyright alongside ours. It compiles in a pristine mirror of Live2D/CubismWebFramework, covered by the Live2D Open Software License — its license text ships in this package at vendor/cubism/LICENSE.md. Live2D Cubism Core is not included; it is distributed by Live2D under the Live2D Proprietary Software License, and businesses above the revenue threshold also need a Cubism SDK Release License. Review Live2D's terms before shipping a product.