Documentation | 中文

• Single-call integration — createWidget() handles canvas creation, WebGL context initialization, model loading, and interaction bindng in one call
• Cubism 2 & 6 runtime — built on l2d, auto-detects model version and loads the correct Cubism runtime
• Lip-sync via parameter driving — character-by-character typing animation drives mouth open/close parameters (PARAM_MOUTH_OPEN_Y) in real time with configurable value ranges
• Full lifecycle control — switchModel() runs exit transition → WebGL teardown → re-init → entrance transition as one atomic async operation; destroy() guarantees resource cleanup
• ~500 lines, zero runtime deps — pure DOM + CSS Animation, no framework. Outputs ESM and IIFE, tree-shakeable

npm install l2d-widget

Or use a CDN:

<script src="https://unpkg.com/l2d-widget/dist/index.min.js"></script>

import { createWidget } from 'l2d-widget';

const widget = createWidget({
  model: {
    path: 'https://model.hacxy.cn/cat-black/model.json',
  },
});

A Live2D model appears in the bottom-left corner of the page with a hover menu and tip bubbles. The returned widget object gives you programmatic control (switch models, sleep, destroy).

createWidget({
  model: [
    { path: '/models/cat-black/model.json' },
    { path: '/models/cat-white/model.json' },
  ],
});

A shuffle button appears automatically in the menu when multiple models are provided.

createWidget({
  model: {
    path: '/models/cat-black/model.json',
    tips: {
      typing: {
        param: 'PARAM_MOUTH_OPEN_Y',
        speed: 200,
      },
      welcomeMessage: ['Hello!', 'Nice to meet you!'],
      messages: ['Take a break~', 'Stay hydrated!'],
      duration: 4000,
      interval: 6000,
    },
  },
});

createWidget() returns a Widget object:

For the full options reference (WidgetOptions, ModelOptions, MenusOptions, TipsOptions), see the documentation.

MIT

中文文档请见 README.zh.md