pixi-live2d-display에서 옮겨오기

Pixi 위의 모델을 캔버스를 직접 소유하는 런타임으로 옮깁니다.

옮길지부터 정하기

pixi-live2d-display는 마지막 발행이 2023년 12월이고 @pixi/core: "^6"을 그대로 선언합니다. Pixi 7이나 8을 쓰는 프로젝트는 못 씁니다. 그렇다고 Pixi를 떠나는 것만이 답은 아닙니다.

untitled-pixi-live2d-engine이 그 자리를 이어받아 Pixi v8에서 동작하고, Cubism 2부터 5까지 다루며, API가 같습니다. 옮기는 일이 다시 쓰기가 아니라 import 경로 변경으로 끝납니다. Pixi를 계속 쓸 생각이라면 그쪽이 맞습니다. Cubism 2.1 모델을 쓴다면 고민할 것도 없습니다. 이 런타임은 2.1을 못 읽습니다.

이 문서는 그 반대 경우를 위한 것입니다. live2d-web은 자체 WebGL2 렌더러를 갖고 캔버스를 직접 소유하므로, 프로젝트에서 Pixi가 빠집니다. Live2D 모델 하나 때문에 Pixi를 넣고 있었다면, React 컴포넌트가 필요하다면, 얼굴 트래킹까지 같은 라이브러리에서 받아야 한다면 이쪽입니다. 다시 쓰는 일이고, 이 아래가 그 비용입니다.

무엇이 달라지나

pixi-live2d-display는 Live2D 모델을 PixiJS Container로 그립니다. 캔버스와 ticker, WebGL 컨텍스트를 Pixi가 소유합니다. 이 런타임은 그것들을 직접 소유합니다. @pixi/* peer 의존 여섯 개가 사라지고, Pixi 버전에 묶이는 부분이 없습니다.

index.html, 이전

<!-- 플러그인이 돌기 전에 Cubism Core가 페이지에 있어야 한다 -->
<script src="/live2dcubismcore.min.js"></script>

import { Live2DModel } from 'pixi-live2d-display'
import * as PIXI from 'pixi.js'
 
// 플러그인이 window.PIXI.Ticker를 읽어 모델을 갱신한다
window.PIXI = PIXI
 
const app = new PIXI.Application({ view: canvas })
const model = await Live2DModel.from('/models/avatar.model3.json')
app.stage.addChild(model)
model.scale.set(0.3)
model.position.set(200, 100)

이후

import { createLive2D } from 'live2d-web'
 
const character = await createLive2D({
  container: document.querySelector('#stage')!,
  coreUrl: '/live2dcubismcore.min.js',
  src: '/models/avatar.model3.json',
})

application도, stage도, 등록할 ticker도 없습니다. Cubism Core는 coreUrl이 불러오므로 script 태그도, 순서를 맞출 일도 없습니다. 컨테이너에 CSS 크기만 주면 캔버스가 그 안을 채웁니다.

함수 대응

pixi-live2d-display	live2d-web
`Live2DModel.from(url)`, `stage.addChild()`	`createLive2D({ container, coreUrl, src })`
페이지에 `<script src="live2dcubismcore.min.js">`	`coreUrl`
`addChild()` 한 번 더	`addModel()` 또는 `<Live2DModel>` 하나 더
`model.motion(group, index, priority)`	`motion(group, index, { priority })`
`MotionPriority.NORMAL` / `FORCE` / `IDLE`	`'normal'` / `'force'` / `'idle'`
`model.expression(id)`	`expression(id)`
`model.focus(x, y)`	`focus(x, y)`, `focusAt(clientX, clientY)`
`model.tap(x, y)`, `model.hitTest(x, y)`	`hitTest(clientX, clientY)`
`model.x`, `y`, `scale`, `anchor`	`fit`
`autoUpdate`, ticker 등록	자동
`autoInteract`	`followPointer`, `onTap`
`coreModel.setParameterValueById()`	`setParameter(id, value)`
`model.destroy()`	`dispose()`

이름만 바뀌지 않는 건 배치 하나입니다. Pixi의 변환은 직접 정한 stage 위의 픽셀 값이지만, fit은 화면에 어떻게 담을지를 적고 리사이즈마다 다시 계산합니다. 배치 오버레이를 켜면 원하는 자리로 끌어다 놓고 값을 복사할 수 있습니다.

넘어오지 않는 것

Cubism 2.1 모델. 이 런타임은 Cubism 3/4/5 전용이라 .moc 파일이 로드되지 않습니다. pixi-live2d-display와 위의 포크는 둘 다 2.1을 다루므로, 그 버전 리그를 쓴다면 그쪽에 남을 이유가 됩니다.
Pixi 씬 그래프. 필터, 블렌드 모드, 다른 스프라이트와 섞기는 전부 Pixi의 몫입니다. 이 런타임은 자체 캔버스를 소유하므로 모델을 Pixi 씬 안에 넣을 수 없습니다. 이걸 위한 호환 계층은 없고 앞으로도 만들지 않습니다. 남의 렌더러 안으로 그리는 것이 이 런타임이 피하려고 만들어진 설계이기 때문입니다.
오디오 재생. SoundManager도 model.speak(url)도 없습니다. 오디오는 이미 앱이 갖고 있으니 앱이 재생하고, 립싱크가 그 소리로 입을 움직입니다.

Cubism Core

옮기다 대개 처음 막히는 자리입니다. 번들된 Framework 5-r.5 어댑터는 Cubism Core 5.3이 필요하고, core/06으로 배포됩니다. 예전 core/05 파일은 moc를 읽는 중에 실패하므로, Pixi 때 쓰던 Core 스크립트를 바꿔야 할 수 있습니다. 받는 곳은 Core와 모델에 있습니다.

옮기는 순서

Cubism Core 5.3을 배치하고 모델이 일단 그려지는지 확인합니다.
생성 코드를 바꿉니다. JavaScript는 createLive2D(), React는 <Live2DCanvas>와 <Live2DModel>입니다.
좌표·배율을 fit으로 옮깁니다. 값은 배치 오버레이로 찾습니다.
위 표대로 호출을 바꿉니다.
pixi-live2d-display와, Pixi 자체에 필요하지 않은 @pixi/* 의존을 지웁니다.

모델이 안 그려지면 모델 검사를 먼저 돌리세요. moc 버전과 빠진 자산을 알려주는데, 옮기는 중에 생기는 문제는 대개 거기서 답이 나옵니다.