live2d-web ドキュメント

サンプル

ビルドを確認済みの4つのサンプルから始められます。

ビルドできるサンプル

リポジトリには Vite JavaScript、Next React、Vue Vite、背景を透過した OBS オーバーレイのサンプルがあります。CI では4つすべての型チェックと本番ビルドを行います。Core は /live2dcubismcore.min.js、モデルは /models/model.model3.json に配置する想定です。

pnpm install
pnpm --filter @live2d-web/example-vanilla-vite dev
pnpm --filter @live2d-web/example-next-react dev
pnpm --filter @live2d-web/example-vue-vite dev
pnpm --filter @live2d-web/example-obs-overlay dev

Vite JavaScript

import { createLive2D } from 'live2d-web'
 
const character = await createLive2D({
  container: document.querySelector('#avatar'),
  coreUrl: '/live2dcubismcore.min.js',
  src: '/models/model.model3.json',
})
 
await character.motion('TapBody', 0)
 
// When the host view is removed:
character.dispose()

Next React

'use client'
 
import { Live2DCanvas, Live2DModel } from 'live2d-web/react'
 
export function Avatar() {
  return (
    <Live2DCanvas coreUrl="/live2dcubismcore.min.js">
      <Live2DModel src="/models/model.model3.json" />
    </Live2DCanvas>
  )
}

Vue Vite

<script setup lang="ts">
import { createLive2D } from 'live2d-web'
import { onBeforeUnmount, onMounted, ref } from 'vue'
 
const host = ref<HTMLElement>()
let character: Awaited<ReturnType<typeof createLive2D>> | undefined
 
onMounted(async () => {
  character = await createLive2D({
    container: host.value!,
    coreUrl: '/live2dcubismcore.min.js',
    src: '/models/model.model3.json',
  })
})
onBeforeUnmount(() => character?.dispose())
</script>
 
<template><div ref="host" class="avatar" /></template>

OBS overlay

import { createLive2D } from 'live2d-web'
 
const query = new URLSearchParams(location.search)
const character = await createLive2D({
  container: document.querySelector('#overlay')!,
  coreUrl: '/live2dcubismcore.min.js',
  fit: query.get('fit') === 'full' ? 'full' : 'upper-body',
  src: query.get('model') ?? '/models/model.model3.json',
})
 
addEventListener('pagehide', () => character.dispose(), { once: true })

用途に合うプロジェクトを選ぶ

Vite JavaScript は、最小構成と createLive2D() の生存期間を確認するための出発点です。
Next React は、Client Component の境界と SSR 時に安全な import を確認できます。
Vue Vite は、専用の Vue binding を使わず component lifecycle に root API を接続する例です。
OBS overlay は、透過背景と query parameter でモデルを差し替えるブラウザソース向けの例です。

アプリの構成に近いものをコピーし、別のフレームワーク用コードを無理に混ぜないでください。どの例も Core とモデルを同梱しません。

ローカルファイルを用意する

各プロジェクトは /live2dcubismcore.min.js と /models/model.model3.json を参照します。利用条件を確認した Core と、自分で配布できるモデルをそれぞれの public ディレクトリに置きます。

public/
├── live2dcubismcore.min.js
└── models/
    ├── model.model3.json
    ├── model.moc3
    └── textures/

ファイル名の大文字・小文字と model3 内の相対パスを保ってください。開発サーバーで動いても、配信環境の CORS と MIME type が異なる場合があります。

production build を確認する

例を変更したあとは development server だけでなく production build も実行します。

pnpm --filter @live2d-web/example-vanilla-vite build
pnpm --filter @live2d-web/example-next-react build
pnpm --filter @live2d-web/example-vue-vite build
pnpm --filter @live2d-web/example-obs-overlay build

デプロイ後は Core と model3 の URL、Canvas の表示、ページを離れたあとの dispose() を確認してください。