### Project Setup

Source: https://github.com/guansss/pixi-live2d-display/wiki/Development

Installs project dependencies and sets up the development environment.

```sh
yarn setup
```

--------------------------------

### Starting Live2D Motions

Source: https://github.com/guansss/pixi-live2d-display/wiki/Complete-Guide

Provides examples of how to start specific motions or random motions from a given group using shorthand methods or the underlying motion manager.

```javascript
// start the first motion in the "tap_body" group
model.motion('tap_body', 0);
```

```javascript
// when the index is omitted, it starts a random motion in given group
model.motion('tap_body');
```

```javascript
// the above calls are shorthands of these methods
model.internalModel.motionManager.startMotion('tap_body', 0);
model.internalModel.motionManager.startRandomMotion('tap_body');
```

--------------------------------

### Project Setup

Source: https://github.com/guansss/pixi-live2d-display/blob/master/DEVELOPMENT.md

Commands to install project dependencies using npm and download Live2D core files.

```sh
npm install
```

```sh
npm run setup
```

--------------------------------

### Install pixi-live2d-display via npm

Source: https://github.com/guansss/pixi-live2d-display/blob/master/README.md

Command to install the pixi-live2d-display package using npm.

```sh
npm install pixi-live2d-display
```

--------------------------------

### Running the Playground

Source: https://github.com/guansss/pixi-live2d-display/wiki/Development

Starts a development server with hot-reloading for the playground, facilitating quick debugging of changes.

```sh
yarn playground
```

--------------------------------

### Install Submodules

Source: https://github.com/guansss/pixi-live2d-display/blob/master/DEVELOPMENT.md

Methods for manually installing git submodules, either by configuring URL replacements or editing the .gitmodules file.

```sh
git config --global url."https://github.com/guansss/CubismWebFramework.git".insteadOf "git@github.com:guansss/CubismWebFramework.git"
git submodule sync
git submodule update --init
```

```sh
git submodule sync
git submodule update --init
```

--------------------------------

### Handling Motion Sound Events

Source: https://github.com/guansss/pixi-live2d-display/wiki/Complete-Guide

Provides an example of listening to the `motionStart` event to handle audio playback, such as displaying subtitles when a motion with sound begins.

```javascript
model.internalModel.motionManager.on('motionStart', (group, index, audio) => {
    if (audio) {
        // assume you've implemented a feature to show subtitles
        showSubtitle(group, index);

        audio.addEventListener('ended', () => dismissSubtitle());
    }
});
```

--------------------------------

### Basic Usage

Source: https://github.com/guansss/pixi-live2d-display/blob/master/README.zh.md

A basic example demonstrating how to initialize a PixiJS application, load a Live2D model, add it to the stage, and apply transformations and interactions. It also shows how to expose PIXI to the window for automatic model updates via Ticker.

```js
import * as PIXI from 'pixi.js';
import { Live2DModel } from 'pixi-live2d-display';

// Expose PIXI to the window so the plugin can automatically update the model via PIXI.Ticker
window.PIXI = PIXI;

(async function () {
    const app = new PIXI.Application({
        view: document.getElementById('canvas'),
    });

    const model = await Live2DModel.from('shizuku.model.json');

    app.stage.addChild(model);

    // Transformations
    model.x = 100;
    model.y = 100;
    model.rotation = Math.PI;
    model.skew.x = Math.PI;
    model.scale.set(2, 2);
    model.anchor.set(0.5, 0.5);

    // Interaction
    model.on('hit', (hitAreas) => {
        if (hitAreas.includes('body')) {
            model.motion('tap_body');
        }
    });
})();
```

--------------------------------

### Automatic Model Update Setup

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/models.md

Explains how to set up automatic model updates using `PIXI.Ticker`. This involves either exposing `PIXI` globally or manually registering the `Ticker` and `TickerPlugin`.

```javascript
import * as PIXI from 'pixi.js';

window.PIXI = PIXI;
```

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

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

--------------------------------

### Starting Motions

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/motions_expressions.md

Initiates a motion playback on the Live2D model. You can start a specific motion by its index within a group or a random motion from a group. These actions are shorthands for more detailed methods on the internal motion manager.

```js
// start the first motion in "tap_body" group
model.motion('tap_body', 0);

// start a random motion in "tap_body" group
model.motion('tap_body');

// the above calls are shorthands of these methods
model.internalModel.motionManager.startMotion('tap_body', 0);
model.internalModel.motionManager.startRandomMotion('tap_body');
```

--------------------------------

### On-Demand PixiJS Package Importing with Live2D

Source: https://github.com/guansss/pixi-live2d-display/blob/master/README.md

Illustrates how to import PixiJS packages on demand and register necessary plugins for Live2D model integration. This includes registering the Ticker for Live2DModel and Application, and the InteractionManager for interactivity. It shows a minimal setup for loading a model after these registrations.

```javascript
import { Application } from '@pixi/app';
import { Ticker, TickerPlugin } 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 make Live2D models interactive
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);
})();
```

--------------------------------

### Install via npm

Source: https://github.com/guansss/pixi-live2d-display/blob/master/README.zh.md

Install the pixi-live2d-display package using npm. You can import the main package or specific Cubism versions for smaller bundle sizes.

```sh
npm install pixi-live2d-display
```

--------------------------------

### Setting Motion Priority

Source: https://github.com/guansss/pixi-live2d-display/wiki/Complete-Guide

Demonstrates how to play a motion with a specific priority using the `model.motion()` method. It shows examples for a named motion and a random motion with normal priority.

```javascript
import { MotionPriority } from 'pixi-live2d-display';

model.motion('tap_body', 0, MotionPriority.NORMAL);

// a random motion as normal priority
model.motion('tap_body', undefined, MotionPriority.NORMAL);
```

--------------------------------

### ChromeDriver Compatibility

Source: https://github.com/guansss/pixi-live2d-display/blob/master/DEVELOPMENT.md

Instructions for resolving ChromeDriver version compatibility issues by installing a specific version.

```sh
npm install chromedriver@<version>
```

--------------------------------

### Starting Motions with Priority

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/motions_expressions.md

Allows starting motions with different priority levels: IDLE (low), NORMAL (medium, default), and FORCE (high). Priority determines how motions are handled when multiple are queued or playing, ensuring critical animations are displayed.

```js
import { MotionPriority } from 'pixi-live2d-display';

model.motion('tap_body', 0, MotionPriority.NORMAL);

// start a random motion
model.motion('tap_body', undefined, MotionPriority.NORMAL);
```

--------------------------------

### Loading Live2D Model from Uploaded Zip File

Source: https://github.com/guansss/pixi-live2d-display/wiki/Additional-Features

Provides an example of loading a Live2D model from a zip file selected by the user via an HTML file input. It listens for the 'change' event on the file input, retrieves the selected zip file, and passes it as a source to `Live2DModel.from()`.

```html
<input type="file" id="zippicker" accept=".zip">
```

```js
document.getElementById("zippicker").addEventListener("change", function(event) {
  const files = event.target.files;

  if (files.length) {
    const zipSource = [files[0]];

    const model = await Live2DModel.from(zipSource);
  }
});
```

--------------------------------

### Loading Live2D Models from Uploaded Files

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/additional.md

Provides an example of how to load a Live2D model using an array of File objects, typically obtained from a directory picker. This experimental feature uses an internal FileLoader to find and resolve model resources.

```html
<input type="file" id="filepicker" webkitdirectory multiple />
```

```javascript
document.getElementById("filepicker").addEventListener("change", async (event) => {
    const files = event.target.files;

    if (files.length) {
        const model = await Live2DModel.from(files);
    }
});
```

```javascript
const files = [
    // collected files:
    // shizuku-normal.model.json
    // shizuku-special.model.json
    // shizuku.moc
    // texture_0.png
    // ...
];

const settingsFile = files.find(file => file.name === 'shizuku-special.model.json');

// read JSON from the file
const settingsJSON = await fetch(URL.createObjectURL(settingsFile)).then(res => res.json());

// don't forget to specify url!
settingsJSON.url = settingsFile.webkitRelativePath;

// attach the settings to the array
files.settings = new Cubism2ModelSettings(settingsJSON);

const model = await Live2DModel.from(files);
```

--------------------------------

### Package Importing and Plugin Registration

Source: https://github.com/guansss/pixi-live2d-display/blob/master/README.zh.md

When using PixiJS with module bundlers, you need to manually register components for optional features. This example shows how to register Ticker for Live2DModel and the Application, and InteractionManager for automatic interaction.

```js
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 for Live2D models
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);
})();
```

--------------------------------

### Loading Model from Uploaded Zip File

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/additional.md

Provides an example of loading a Live2D model from a zip file selected by the user via an HTML file input. It attaches an event listener to the file input to handle the file selection and load the model asynchronously.

```html
<input type="file" id="zippicker" accept=".zip">
```

```javascript
document.getElementById("zippicker").addEventListener("change", async function(event) {
    const files = event.target.files;

    if (files.length) {
        const model = await Live2DModel.from(files);
    }
});
```

--------------------------------

### Handling Motion Start Events

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/motions_expressions.md

Listens for the 'motionStart' event on the model's internal motion manager to perform actions like displaying subtitles when a motion begins. It also sets up an event listener for the audio to dismiss subtitles when playback ends.

```javascript
model.internalModel.motionManager.on('motionStart', (group, index, audio) => {
  if (audio) {
    // e.g. show subtitle for this audio
    showSubtitle(group, index);

    audio.addEventListener('ended', () => dismissSubtitle());
  }
});
```

--------------------------------

### Building the Library

Source: https://github.com/guansss/pixi-live2d-display/wiki/Development

Compiles the project into a production-ready bundle, necessary for running browser-based tests.

```sh
yarn build
```

--------------------------------

### Creating a Live2D Model from ModelSettings Instance

Source: https://github.com/guansss/pixi-live2d-display/wiki/Complete-Guide

Illustrates creating a Live2D model by passing an instance of `ModelSettings` (e.g., `Cubism2ModelSettings`) to the `Live2DModel.from` method. This requires pre-loading and parsing the model settings JSON.

```javascript
const url = 'path/to/shizuku.model.json'
const json = await loadJSON(url);

json.url = url;

const settings = new Cubism2ModelSettings(json);
const model = await Live2DModel.from(settings);
```

--------------------------------

### Build and Test

Source: https://github.com/guansss/pixi-live2d-display/blob/master/DEVELOPMENT.md

Commands for building the project for production and running tests, including updating snapshots.

```sh
npm run build
```

```sh
npm run test
```

```sh
npm run test:u
```

--------------------------------

### Creating a Live2D Model from URL

Source: https://github.com/guansss/pixi-live2d-display/wiki/Complete-Guide

Demonstrates how to asynchronously create a Live2D model by providing the URL to its settings file. This is the most common method for loading models.

```javascript
const model = await Live2DModel.from('path/to/shizuku.model.json');
```

--------------------------------

### Live2DModel Creation Methods

Source: https://github.com/guansss/pixi-live2d-display/wiki/Changes-in-v0.3.0

Demonstrates the consolidation of prior Live2D model creation methods into a single, unified `Live2DModel.from()` method for simplified model instantiation.

```js
Live2DModel.fromModelSettingsFile();
Live2DModel.fromModelSettingsJSON();
Live2DModel.fromModelSettings();
Live2DModel.fromResources();

// Merged into:
Live2DModel.from();
```

--------------------------------

### Clone Repository

Source: https://github.com/guansss/pixi-live2d-display/blob/master/DEVELOPMENT.md

Instructions for cloning the pixi-live2d-display repository using SSH or HTTPS. Includes steps for handling submodules.

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

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

--------------------------------

### Basic Live2D Model Display

Source: https://github.com/guansss/pixi-live2d-display/blob/master/README.md

Demonstrates how to initialize a PixiJS application, load a Live2D model from a JSON file, add it to the stage, and apply various transformations like position, rotation, scale, and anchor. It also shows how to handle user interactions, specifically tapping on the model's 'body'.

```javascript
import * as PIXI from 'pixi.js';
import { Live2DModel } from 'pixi-live2d-display';

// expose PIXI to window so that this plugin is able to
// reference window.PIXI.Ticker to automatically update Live2D models
window.PIXI = PIXI;

(async function () {
  const app = new PIXI.Application({
    view: document.getElementById('canvas'),
  });

  const model = await Live2DModel.from('shizuku.model.json');

  app.stage.addChild(model);

  // transforms
  model.x = 100;
  model.y = 100;
  model.rotation = Math.PI;
  model.skew.x = Math.PI;
  model.scale.set(2, 2);
  model.anchor.set(0.5, 0.5);

  // interaction
  model.on('hit', (hitAreas) => {
    if (hitAreas.includes('body')) {
      model.motion('tap_body');
    }
  });
})();
```

--------------------------------

### Model Ready and Load Events

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/models.md

Illustrates the use of `ready` and `load` events. The `ready` event fires when essential resources are loaded, allowing for immediate display, while the `load` event fires after all resources, including optional ones, are loaded.

```javascript
const model = Live2DModel.fromSync('shizuku.model.json');

model.once('ready', () => {
    // now it's safe to display the model, though not recommended because
    // it's likely to look weird due to missing optional resources
    app.stage.addChild(model);
    model.motion('tap_body');
});
```

--------------------------------

### Create Live2D Model from URL

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/models.md

Demonstrates how to create a Live2D model by providing the URL to its model settings file (e.g., `.model.json` or `.model3.json`). This is the most common way to load a model.

```js
const model = await Live2DModel.from('path/to/shizuku.model.json');
```

--------------------------------

### Motion Preloading Strategies

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/motions_expressions.md

Controls how motions are preloaded during model creation. Options include preloading all motions, only idle motions, or none. Preloading helps avoid delays when starting motions for the first time, but loading too many can impact performance.

```js
import { MotionPreloadStrategy } from 'pixi-live2d-display';

// MotionPreloadStrategy.ALL
// MotionPreloadStrategy.IDLE
// MotionPreloadStrategy.NONE

const model = await Live2DModel.from('shizuku.model.json', { motionPreload: MotionPreloadStrategy.NONE });
```

--------------------------------

### Loading Model from Zip URL

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/additional.md

Demonstrates how to load a Live2D model directly from a zip file URL using `Live2DModel.from()`. It also shows how to handle URLs that do not explicitly end with `.zip` by prepending a `zip://` protocol.

```javascript
Live2DModel.from('path/to/shizuku.zip');

Live2DModel.from('zip://path/to/shizuku');

Live2DModel.from('zip://http://example.com/give-me-a-random-model');
```

--------------------------------

### Synchronous Live2D Model Creation

Source: https://github.com/guansss/pixi-live2d-display/wiki/Complete-Guide

Demonstrates the synchronous creation of a Live2D model using `Live2DModel.fromSync`. This method returns an instance immediately, but resources are not yet loaded. The model can only be manipulated or rendered after the 'load' event is emitted. It also shows how to hook into other events like 'settingsJSONLoaded' and 'settingsLoaded' for customization.

```js
const model = Live2DModel.fromSync('shizuku.model.json', { onError: console.warn });

// these will cause errors!
// app.stage.addChild(model);
// model.motion('tap_body');

model.once('load', () => {
    // now it's safe
    app.stage.addChild(model);
    model.motion('tap_body');
});
```

```js
const model = Live2DModel.fromSync('shizuku.model.json');

model.once('settingsJSONLoaded', json => {
    // e.g. customize the layout before they are applied to the model
    Object.assign(json, {
        layout: {
            width: 2,
            height: 2
        }
    });
});

model.once('settingsLoaded', settings => {
    // e.g. set another URL to the model
    settings.url = 'path/to/model';
});
```

```js
const model = Live2DModel.fromSync('shizuku.model.json');

model.once('ready', () => {
    // it's also safe to do these now, though not recommended because
    // a model will typically look weird when rendered without optional resources 
    app.stage.addChild(model);
    model.motion('tap_body');
});
```

--------------------------------

### Create Live2D Model from ModelSettings Instance

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/models.md

Illustrates creating a Live2D model by passing an instance of `ModelSettings` (either `Cubism2ModelSettings` or `Cubism4ModelSettings`). This method requires pre-parsing the model settings JSON.

```js
const url = 'path/to/shizuku.model.json';
const json = await fetch(url).then((res) => res.json());

json.url = url;

const settings = new Cubism2ModelSettings(json);
const model = await Live2DModel.from(settings);
```

--------------------------------

### Loading Live2D Model with Fake Protocol

Source: https://github.com/guansss/pixi-live2d-display/wiki/Additional-Features

Shows how to load a Live2D model from a URL that might not explicitly end with `.zip` by prepending a `zip://` protocol. This is useful when the file is known to be a zip archive but lacks the correct extension.

```js
Live2DModel.from('zip://path/to/shizuku');

Live2DModel.from('zip://http://example.com/give-me-a-random-model');
```

--------------------------------

### Include pixi-live2d-display via CDN

Source: https://github.com/guansss/pixi-live2d-display/blob/master/README.md

Shows how to include the pixi-live2d-display library using CDN links, with options for including all versions or specific Cubism versions.

```html
<script src="https://cdn.jsdelivr.net/npm/pixi-live2d-display/dist/index.min.js"></script>

<!-- if only Cubism 2.1 -->
<script src="https://cdn.jsdelivr.net/npm/pixi-live2d-display/dist/cubism2.min.js"></script>

<!-- if only Cubism 4 -->
<script src="https://cdn.jsdelivr.net/npm/pixi-live2d-display/dist/cubism4.min.js"></script>
```

--------------------------------

### Global Configuration Options

Source: https://github.com/guansss/pixi-live2d-display/wiki/Complete-Guide

Illustrates how to import and modify global configuration settings for pixi-live2d-display. This includes setting the log level, enabling/disabling sound for motions, synchronizing motion and sound loading, defining default fading durations for motions and expressions, and enabling experimental support for Cubism 4 mask divisions.

```javascript
import { config } from 'pixi-live2d-display';

// Log level
config.logLevel = config.LOG_LEVEL_WARNING;

// Play sound for motions
config.sound = true;

// Defer playback until loaded
config.motionSync = true;

// Default fading durations
config.motionFadingDuration = 500;
config.idleMotionFadingDuration = 500;
config.expressionFadingDuration = 500;

// Experimental Cubism 4 feature
config.cubism4.supportMoreMaskDivisions = true;
```

--------------------------------

### Synchronous Model Creation

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/models.md

Demonstrates how to create a Live2D model synchronously using `Live2DModel.fromSync`. This method returns an instance immediately, but resources are not yet loaded. The `load` event must be handled before manipulating or rendering the model.

```javascript
const model = Live2DModel.fromSync('shizuku.model.json', { onError: console.warn });

// these will cause errors!
// app.stage.addChild(model);
// model.motion('tap_body');

model.once('load', () => {
    // now it's safe
    app.stage.addChild(model);
    model.motion('tap_body');
});
```

--------------------------------

### Run Playground

Source: https://github.com/guansss/pixi-live2d-display/blob/master/DEVELOPMENT.md

Command to run the playground for debugging and testing, and how to prevent changes to playground/index.ts from being committed.

```sh
npm run playground
```

```sh
git update-index --skip-worktree playground/index.ts
```

--------------------------------

### ModelSettings Iteration and File Handling (v0.3.0)

Source: https://github.com/guansss/pixi-live2d-display/wiki/Changes-in-v0.3.0

This code snippet demonstrates new methods added to ModelSettings for iterating through defined files and replacing them. It also includes the addition of load events for motions and expressions.

```javascript
// Methods in ModelSettings
getDefinedFiles()
replaceFiles()

// Load events
motionLoaded
motionLoadError
expressionLoaded
expressionLoadError
```

--------------------------------

### Running Tests

Source: https://github.com/guansss/pixi-live2d-display/wiki/Development

Executes the test suite. `test` runs headless tests, while `test:debug` runs tests with a visible browser for debugging.

```sh
yarn test
yarn test:debug
```

--------------------------------

### Loading via CDN

Source: https://github.com/guansss/pixi-live2d-display/blob/master/README.zh.md

Load the pixi-live2d-display library using CDN links. The `index.min.js` includes support for all versions, while `cubism2.min.js` and `cubism4.min.js` are for specific Cubism versions. When loaded via CDN, all members are exported to the `PIXI.live2d` namespace.

```html
<script src="https://cdn.jsdelivr.net/npm/pixi-live2d-display/dist/index.min.js"></script>

<!-- If you only need Cubism 2.1 -->
<script src="https://cdn.jsdelivr.net/npm/pixi-live2d-display/dist/cubism2.min.js"></script>

<!-- If you only need Cubism 4 -->
<script src="https://cdn.jsdelivr.net/npm/pixi-live2d-display/dist/cubism4.min.js"></script>
```

--------------------------------

### Import Live2DModel with Cubism Versions (npm)

Source: https://github.com/guansss/pixi-live2d-display/blob/master/README.md

Demonstrates how to import the Live2DModel class from the pixi-live2d-display package using npm, with specific imports for Cubism 2.1 or Cubism 4.

```javascript
import { Live2DModel } from 'pixi-live2d-display';

// if only Cubism 2.1
import { Live2DModel } from 'pixi-live2d-display/cubism2';

// if only Cubism 4
import { Live2DModel } from 'pixi-live2d-display/cubism4';
```

--------------------------------

### Creating a Live2D Model from JSON Object

Source: https://github.com/guansss/pixi-live2d-display/wiki/Complete-Guide

Shows how to create a Live2D model using a JSON object containing the model settings. The `url` property must be included in the JSON object to resolve resource files correctly.

```javascript
const url = 'path/to/shizuku.model.json'
const json = await loadJSON(url);

json.url = url;

const model = await Live2DModel.from(json);
```

--------------------------------

### Create Live2D Model from JSON Object

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/models.md

Shows how to create a Live2D model using a JSON object that contains the model's settings. It's crucial to include the `url` property in the JSON object for correct resource loading.

```js
const url = 'path/to/shizuku.model.json';
const json = await fetch(url).then((res) => res.json());

json.url = url;

const model = await Live2DModel.from(json);
```

--------------------------------

### API Documentation Reference

Source: https://github.com/guansss/pixi-live2d-display/blob/master/README.zh.md

This section provides a link to the detailed API documentation for the pixi-live2d-display library. It covers all available methods, properties, and events for controlling Live2D models within a PixiJS application.

```APIDOC
Live2DModel:
  from(jsonPath: string, options?: object): Promise<Live2DModel>
    Loads a Live2D model from a JSON file path.
    options: Optional configuration object.

  registerTicker(ticker: PIXI.Ticker): void
    Registers a PixiJS Ticker for automatic model updates.

  registerPlugin(pluginName: string, plugin: any): void
    Registers a PixiJS plugin for extended functionality.

  // Properties
  x: number
    The x position of the model.
  y: number
    The y position of the model.
  rotation: number
    The rotation of the model in radians.
  scale: PIXI.Point
    The scale of the model.
  anchor: PIXI.Point
    The anchor point of the model.

  // Methods
  motion(name: string, priority?: string): void
    Plays a Live2D animation motion.
    name: The name of the motion to play.
    priority: Optional priority for the motion.

  // Events
  'hit'(hitAreas: string[]): void
    Emitted when the model is interacted with and hit areas are detected.
```

--------------------------------

### Loading Live2D Model from Zip File Path

Source: https://github.com/guansss/pixi-live2d-display/wiki/Additional-Features

Demonstrates how to load a Live2D model directly from a zip file using its path. The `Live2DModel.from()` method handles the loading process.

```js
Live2DModel.from('path/to/shizuku.zip');
```

--------------------------------

### Basic Live2D Model Loading and Display

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/index.md

Demonstrates how to load a Live2D model and display it using the pixi-live2d-display plugin. Requires a Live2D model in the appropriate format.

```javascript
import * as PIXI from 'pixi.js';
import { Live2DModel } from 'pixi-live2d-display';

const app = new PIXI.Application({
    view: document.getElementById('myCanvas'),
    width: 800,
    height: 600,
    backgroundColor: 0x1099bb,
});

Live2DModel.from('path/to/your/model.json').then(model => {
    app.stage.addChild(model);

    // Optional: Set model position, scale, etc.
    model.x = app.screen.width / 2;
    model.y = app.screen.height / 2;
    model.scale.set(0.5);

    // Optional: Interact with the model
    model.on('pointerdown', () => {
        model.playAnimation('tap');
    });
}).catch(error => {
    console.error('Failed to load Live2D model:', error);
});

```

```typescript
import * as PIXI from 'pixi.js';
import { Live2DModel } from 'pixi-live2d-display';

const app = new PIXI.Application<HTMLCanvasElement>({
    view: document.getElementById('myCanvas') as HTMLCanvasElement,
    width: 800,
    height: 600,
    backgroundColor: 0x1099bb,
});

Live2DModel.from('path/to/your/model.json').then((model: Live2DModel) => {
    app.stage.addChild(model);

    // Optional: Set model position, scale, etc.
    model.x = app.screen.width / 2;
    model.y = app.screen.height / 2;
    model.scale.set(0.5);

    // Optional: Interact with the model
    model.on('pointerdown', () => {
        model.playAnimation('tap');
    });
}).catch((error: Error) => {
    console.error('Failed to load Live2D model:', error);
});

```

--------------------------------

### Live2D Model Creation Flow

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/graphs.md

Visual representation of the model creation process. It shows the different sources for model data (URL, settingsJSON, ModelSettings), the middleware functions used for transformation (urlToJSON, jsonToSettings, setupOptionals, setupLive2DModel, createInternalModel), and the events that signal completion of each stage (settingsJSONLoaded, settingsLoaded, poseLoaded, physicsLoaded, textureLoaded, modelLoaded).

```plantuml
@startuml

skinparam handwritten true
skinparam monochrome true
skinparam packageStyle rectangle

object "Live2DModel"

object "(source)" as Source
object "URL"
object "settingsJSON"
object "ModelSettings"
object "Pose"
object "Physics"
object "Texture[]"
object "InternalModel"

Source --> URL : artifacts
Source --> settingsJSON : artifacts
Source --> ModelSettings : artifacts

URL --> Live2DModel : Live2DModel.fromSync(source)
settingsJSON --> Live2DModel : Live2DModel.fromSync(source)
ModelSettings --> Live2DModel : Live2DModel.fromSync(source)

Live2DModel --> Pose : "load"
Live2DModel --> Physics : "load"
Live2DModel --> Texture[] : "load"
Live2DModel --> InternalModel : "load"

Live2DModel --> "ready" : "ready"

settingsJSON --> "settingsJSONLoaded" : events
settingsJSON --> "settingsLoaded" : events
ModelSettings --> "settingsLoaded" : events
Pose --> "poseLoaded" : events
Physics --> "physicsLoaded" : events
Texture[] --> "textureLoaded" : events
InternalModel --> "modelLoaded" : events

URL --> "urlToJSON()" : middlewares
settingsJSON --> "jsonToSettings()" : middlewares
ModelSettings --> "setupOptionals()" : middlewares
Pose --> "setupLive2DModel()" : middlewares
Physics --> "setupLive2DModel()" : middlewares
Texture[] --> "setupLive2DModel()" : middlewares
InternalModel --> "createInternalModel()" : middlewares

urlToJSON() --> jsonToSettings()
jsonToSettings() --> setupOptionals()
setupOptionals() --> setupLive2DModel()
setupLive2DModel() --> createInternalModel()

@enduml
```

--------------------------------

### Customizing Model Loading Events

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/models.md

Shows how to hook into specific loading events like `settingsJSONLoaded` and `settingsLoaded` to customize model properties before they are applied.

```javascript
const model = Live2DModel.fromSync('shizuku.model.json');

model.once('settingsJSONLoaded', (json) => {
    // e.g. customize the layout before it's applied to the model
    json.layout = {
        ...json.layout,
        width: 2,
        height: 2,
    };
});

model.once('settingsLoaded', (settings) => {
    // e.g. set another URL to the model
    settings.url = 'alternative/path/to/model';
});
```

--------------------------------

### Registering Interaction Plugin

Source: https://github.com/guansss/pixi-live2d-display/wiki/Complete-Guide

Explains how to manually register Pixi's interaction plugin if a full PixiJS build is not imported, enabling interaction features for Live2D models.

```javascript
import { Renderer } from '@pixi/core';
import { InteractionManager } from '@pixi/interaction';

Renderer.registerPlugin('interaction', InteractionManager);
```

--------------------------------

### Importing Live2DModel (npm)

Source: https://github.com/guansss/pixi-live2d-display/blob/master/README.zh.md

Import the Live2DModel class from the pixi-live2d-display package. Choose the specific import based on the Cubism version you intend to use (Cubism 2.1 or Cubism 4) to optimize your bundle.

```js
import { Live2DModel } from 'pixi-live2d-display';

// If you only need Cubism 2.1
import { Live2DModel } from 'pixi-live2d-display/cubism2';

// If you only need Cubism 4
import { Live2DModel } from 'pixi-live2d-display/cubism4';
```

--------------------------------

### Error Handling and Resource Management Fixes (v0.3.0)

Source: https://github.com/guansss/pixi-live2d-display/wiki/Changes-in-v0.3.0

This section lists various bug fixes related to error handling, resource management, and model loading/rendering. It addresses issues with invalid JSON, Cubism 4 motions, destroyed models, and WebGL context.

```javascript
// Fixes:
- isValidJSON() allows empty texture array
- User events in cubism4 motions are not handled
- Duplicated XHRLoader in Live2DLoader middlewares
- Rendering to framebuffer doesn't work properly for certain cubism2 models
- Motion parsing fails on certain models
- Errors when destroying Live2DModel without ever being rendered
- Loading tasks are not correctly canceled when destroying loading targets
- Error when a motion is loaded in destroyed MotionManager
- Audio still plays when motion is loaded but rejected to play
- Framebuffer binding reset to null when rendering cubism2 model in different WebGL context
- Live2DModel updated by Ticker before initialized
- Drawing offset when rendering in a viewport with different size than render texture
- reserveExpressionIndex not reset when expression is loaded
- Load pose and physics in parallel
- Throw error when creating core model with invalid moc data (Cubism 2)
- Do not choose active motions/expressions for random choice
```

--------------------------------

### ZipLoader Static Methods Implementation

Source: https://github.com/guansss/pixi-live2d-display/wiki/Additional-Features

Defines the required static methods for the `ZipLoader` class. These methods need to be implemented to handle zip file operations, such as reading zip data, retrieving file paths, extracting files, reading file content as text, and releasing zip readers. The `ZipReader` type is an alias for `any`.

```ts
ZipLoader.zipReader(data: Blob, url: string): Promise<ZipReader>

ZipLoader.getFilePaths(reader: ZipReader): Promise<string[]>

ZipLoader.getFiles(reader: ZipReader, paths: string[]): Promise<File[]>

ZipLoader.readText(reader: ZipReader, path: string): Promise<string>

ZipLoader.releaseReader(reader: ZipReader): void
```

--------------------------------

### Git Configuration for Local Changes

Source: https://github.com/guansss/pixi-live2d-display/wiki/Development

Configures git to ignore changes to a specific file (`test/playground/index.ts`) during local development, preventing accidental commits of playground modifications.

```git
git update-index --skip-worktree test/playground/index.ts
```

--------------------------------

### Loading Live2D Model from Uploaded Files

Source: https://github.com/guansss/pixi-live2d-display/wiki/Additional-Features

Loads a Live2D model from an array of `File` objects. The `FileLoader` identifies the model settings file and creates a lookup table for resources. An error is thrown if no settings file is found.

```js
document.getElementById("filepicker").addEventListener("change", function(event) {
  const files = event.target.files;

  if (files.length) {
    const model = await Live2DModel.from(files);
  }
});
```

--------------------------------

### Manual Live2D Model Update Registration

Source: https://github.com/guansss/pixi-live2d-display/wiki/Complete-Guide

Demonstrates how to manually register the PixiJS Ticker for automatic Live2D model updates if `window.PIXI` is not globally available. This involves registering the `TickerPlugin` with the `Application` and then registering the `Ticker` with `Live2DModel`.

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

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

--------------------------------

### Configuring Motion Preload Strategy

Source: https://github.com/guansss/pixi-live2d-display/wiki/Complete-Guide

Demonstrates how to control which motions are preloaded by setting the `motionPreload` option. Options include loading all motions, only idle motions, or no motions.

```javascript
import { MotionPreloadStrategy } from 'pixi-live2d-display';

// MotionPreloadStrategy.ALL
// MotionPreloadStrategy.IDLE
// MotionPreloadStrategy.NONE

const model = await Live2DModel.from('shizuku.model.json', { motionPreload: MotionPreloadStrategy.NONE });
```

--------------------------------

### Pixi Live2D Display Configuration Options

Source: https://github.com/guansss/pixi-live2d-display/blob/master/docs/docs/configs.md

This snippet demonstrates how to configure various aspects of the pixi-live2d-display library. It covers setting the log level, enabling sound playback, synchronizing motion and sound, defining default fading durations for motions and expressions, and enabling experimental support for Cubism 4 mask divisions.

```js
import { config } from 'pixi-live2d-display';

// log level
config.logLevel = config.LOG_LEVEL_WARNING; // LOG_LEVEL_VERBOSE, LOG_LEVEL_ERROR, LOG_LEVEL_NONE

// play sound for motions
config.sound = true;

// defer the playback of a motion and its sound until both are loaded
config.motionSync = true;

// default fade-in/fade-out durations in milliseconds, will be applied to
// motions/expressions that don't have these values specified
config.motionFadingDuration = 500;
config.idleMotionFadingDuration = 500;
config.expressionFadingDuration = 500;

// unofficial and experimental support for 4x4 mask division in Cubism 4
config.cubism4.supportMoreMaskDivisions = true;
```