pixi-live2d-display-advanced

English (Current) | 简体中文

A Live2D plugin for PixiJS v7.

Tip

For PixiJS v8 support, please use untitled-pixi-live2d-engine.

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, 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.

---

Features

• 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
• 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

---

Examples

• Basic Example
• Interaction Example
• Render Texture & Filter Example
• Live2D Viewer Online
• Parallel Motions Example
• Play Motion Last Frame

Documentation:

• User Guide
• API Reference

---

Cubism Runtime

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, covering all versions of Live2D models.

Load Cubism Core

• Cubism 4: live2dcubismcore.min.js

  • Download from the Cubism 4 SDK
  • Or use this link (not guaranteed to be always available, do not use in production)

• Cubism 2.1: live2d.min.js

  • The official site no longer provides it since September 4, 2019
  • Available on GitHub
  • Or via jsDelivr CDN

Bundled Files

This plugin provides separate builds for different Cubism versions:

• 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

Warning

Do not use cubism2.js and cubism4.js together. Use index.js instead if you need both.

---

Installation

Via npm:

npm install pixi-live2d-display-advanced

Usage:

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

// Only Cubism 2.1
import { Live2DModel } from 'pixi-live2d-display-advanced/cubism2'

// Only Cubism 4
import { Live2DModel } from 'pixi-live2d-display-advanced/cubism4'

---

Basic Usage

See example project: pixi-live2d-display-lipsync

Cubism 4 models are auto-configured when first encountered. Call configureCubism4() yourself if you want to customize options (e.g., memory size) or ensure setup happens before any loading.

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

model.parallelMotion([
  { group: motion_group1, index: motion_index1, priority: MotionPriority.NORMAL },
  { group: motion_group2, index: motion_index2, priority: MotionPriority.NORMAL }
])

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

Single motion:

await model.motionLastFrame('w-cute12-tilthead', 0)

Multiple motions:

await model.parallelLastFrame([
  { group: 'w-cute12-tilthead', index: 0 },
  { group: 'face_worry_01', index: 0 }
])

Or with manual parallel motion managers:

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)

Both approaches are equivalent — the first is syntactic sugar for the second.