pixi-live2d-display

If you are using on-demand/modular PixiJS packages (e.g., @pixi/app, @pixi/ticker), you must manually register the necessary components to enable Live2D features like automatic updates and interaction.

• For automatic updates: Register the Ticker with Live2DModel.registerTicker(Ticker).
• For Application integration: Register the TickerPlugin with Application.registerPlugin(TickerPlugin).
• For interaction/hit detection: Register the InteractionManager with the renderer using Renderer.registerPlugin('interaction', InteractionManager).

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

// Register Ticker for Live2DModel
Live2DModel.registerTicker(Ticker);

// Register Ticker for Application
Application.registerPlugin(TickerPlugin);

// Register InteractionManager to support automatic interaction
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);
})();

You can load models from .zip files by providing a URL or an uploaded File.

Protocol: If the URL does not end in .zip, you must prepend it with the zip:// protocol (e.g., zip://http://example.com/model).

Implementation Requirement: Because the library does not include a zipping library by default, you must implement the static methods of ZipLoader before attempting to load a zip file, otherwise a "Not implemented" error will be thrown. You can use libraries like jszip to provide these implementations.

// Load via URL
Live2DModel.from('path/to/shizuku.zip');

// Load via fake protocol
Live2DModel.from('zip://path/to/shizuku');

// Load via uploaded file
document.getElementById("zippicker").addEventListener("change", async function(event) {
    const files = event.target.files;
    if (files.length) {
        const model = await Live2DModel.from(files);
    }
});

To animate a Live2D model, it must be updated every frame using model.update(deltaTime). You can choose between automatic or manual updates.

Automatic Updates (Default)

By default, models attempt to use PIXI.Ticker.shared. To enable this, you must ensure PIXI is available in the global scope:

import * as PIXI from 'pixi.js';
window.PIXI = PIXI;

If you are using a modular setup, you must manually register the Ticker:

import { Application } from '@pixi/app';
import { Ticker, TickerPlugin } from '@pixi/ticker';

Application.registerPlugin(TickerPlugin);
Live2DModel.registerTicker(Ticker);

Manual Updates

To control the update loop yourself, set autoUpdate: false in the creation options and call .update() in your own loop.

Using Ticker

const model = await Live2DModel.from('shizuku.model.json', { autoUpdate: false });
const ticker = new Ticker();

ticker.add(() => model.update(ticker.elapsedMS));

Using requestAnimationFrame

const model = await Live2DModel.from('shizuku.model.json', { autoUpdate: false });
let then = performance.now();

function tick(now) {
    model.update(now - then);
    then = now;
    requestAnimationFrame(tick);
}
requestAnimationFrame(tick);

To clone the repository with submodules included, use SSH. If you clone via HTTPS, submodules will not be included automatically and must be installed manually.

Cloning via SSH (Recommended)

git clone git@github.com:guansss/pixi-live2d-display.git --recursive

Cloning via HTTPS

git clone https://github.com/guansss/pixi-live2d-display.git

If you used HTTPS, you must manually install the submodules using one of these methods:

Method 1: Git Config Redirect

git config --global url."https://github.com/guansss/CubismWebFramework.git".insteadOf "git@github.com:guansss/CubismWebFramework.git"

git submodule sync
git submodule update --init

Method 2: Manual .gitmodules Edit

1. Edit .gitmodules and replace git@github.com:guansss/CubismWebFramework.git with https://github.com/guansss/CubismWebFramework.git.
2. Run:

git submodule sync
git submodule update --init

Note: Do not commit changes to .gitmodules if you are contributing to the project.