live2d-web 문서

예제

실제 빌드를 확인한 예제 4개로 바로 시작할 수 있습니다.

실제 빌드되는 프로젝트

저장소에는 Vite JavaScript, Next React, Vue Vite, 투명 OBS 오버레이 예제가 있습니다. CI에서 네 프로젝트의 타입과 배포용 빌드를 매번 확인합니다. 기본적으로 Cubism 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, Client Component 경계는 Next React, Vue 생명주기 연동은 Vue Vite, 투명 브라우저 소스는 OBS overlay에서 시작하세요. 어느 예제도 Cubism Core와 모델을 포함하지 않습니다.

로컬 자산 준비하기

사용 권한이 있는 Core를 /live2dcubismcore.min.js에 두고 모델 디렉터리를 /models 아래에 복사합니다. model3의 상대 경로를 그대로 유지하세요.

수정 전에 build 확인하기

예제를 원본 그대로 실행해 모델 로드와 cleanup을 확인한 뒤 URL과 framing을 바꾸세요. production build까지 성공해야 SSR 경계, Worker URL, asset base path를 확인할 수 있습니다.