Installation

Install

easy-live2d 1.0.0 uses Pixi.js 8 and Cubism 5 SDK for Web R5. Read the migration guide before upgrading an existing integration.

pnpm

pnpm add easy-live2d pixi.js

npm

npm install easy-live2d pixi.js

yarn

yarn add easy-live2d pixi.js

Application code should import from easy-live2d. @easy-live2d/core is the internal monorepo package, used only during repository development.

Prerequisites

1. Load the Official Cubism Core

The library does not include Live2D Core. You need to download and host live2dcubismcore.js from Cubism 5 SDK for Web R5 yourself per Live2D licensing:

<script src="/Core/live2dcubismcore.js"></script>

2. Browser Environment

Depends on these browser APIs:

• document / fetch / Image
• ResizeObserver
• AudioContext
• WebGL 2 (WebGL 1 and WebGPU are not supported)

Not suitable for SSR. Initialize Live2DSprite after client mount.

Pixi defaults to WebGL 2, so no additional renderer options are required. R5 shaders are bundled with the library.

3. Pixi.js as Host

You create the Pixi Application and add Live2DSprite to the stage. easy-live2d does not create the canvas or own the app lifecycle.

Model Assets

Option 1: modelPath

const sprite = new Live2DSprite({
  modelPath: '/Resources/Hiyori/Hiyori.model3.json',
})

The library uses the model3.json directory as the base path to load moc, textures, motions, expressions, physics, pose, and user data.

Option 2: CubismSetting

const modelJSON = await fetch('/Resources/Hiyori/Hiyori.model3.json').then(r => r.json())

const setting = new CubismSetting({
  modelJSON,
  prefixPath: '/Resources/Hiyori/',
})

Best for:

• model3.json requires authentication
• Assets are on a CDN
• Asset URLs need rule-based rewriting

Smallest Runnable Page

This HTML example assumes a bundler such as Vite for the package imports.

<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>easy-live2d</title>
    <style>
      html,
      body {
        margin: 0;
        width: 100%;
        height: 100%;
      }
      #live2d {
        display: block;
        width: 100vw;
        height: 100vh;
      }
    </style>
  </head>
  <body>
    <canvas id="live2d"></canvas>
    <script src="/Core/live2dcubismcore.js"></script>
    <script type="module">
      import { Application } from 'pixi.js'
      import { Live2DSprite } from 'easy-live2d'

      const canvas = document.getElementById('live2d')
      const app = new Application()

      await app.init({
        canvas,
        backgroundAlpha: 0,
        autoDensity: true,
        resolution: Math.max(window.devicePixelRatio || 1, 1),
      })

      const sprite = new Live2DSprite({
        modelPath: '/Resources/Hiyori/Hiyori.model3.json',
      })

      sprite.width = canvas.clientWidth
      app.stage.addChild(sprite)
      try {
        await sprite.ready
      } catch (error) {
        console.error(error)
        sprite.destroy()
        app.destroy()
      }
    </script>
  </body>
</html>

Next

• Getting Started — Run the minimal example
• Basic Usage — Motions, expressions, dragging, voice
• API Reference — Full public API