live2d-web 문서

모델 검사

URL과 로컬 모델 ZIP을 불러오기 전에 검사합니다.

렌더링 전에 검사

live2d-web/inspect는 React, Cubism Core, Framework, MediaPipe, JSZip을 불러오지 않고 model3.json이 참조하는 파일을 검사합니다. 모델 내용의 문제는 findings에 모아 반환하며, 잘못된 API 인자나 중단 요청만 Promise를 거부합니다.

import {
  inspectModelCapabilities,
  inspectModelSource,
} from 'live2d-web/inspect'
 
const report = await inspectModelSource({
  src: 'https://example.com/model.model3.json',
})
 
if (report.status === 'compatible') {
  console.log(report.motions, report.expressions)
}

URL로 검사하면 모델에 적힌 HTTP(S) 참조를 실제로 요청합니다. 브라우저에서는 CORS가 적용되지만 Node 서버에는 브라우저와 같은 CORS나 사설망 접근 차단이 없습니다. 서버가 신뢰할 수 없는 모델 URL을 받는다면 허용할 호스트 목록과 네트워크 정책을 앱에서 반드시 적용하세요. 라이브러리는 서버가 접근해도 되는 사설 IP 범위를 알 수 없습니다. 로컬 파일 연결자를 사용하는 검사는 압축 파일에 적힌 외부 URL을 요청하지 않습니다.

브라우저 ZIP 검사기

Inspector는 ZIP 파일을 현재 브라우저 탭 안에서만 엽니다. 파일 크기, 개수, 경로, 모델 참조를 확인하며 업로드하거나 저장하지 않고 사용 정보도 전송하지 않습니다. 호환되지 않는 압축 파일은 모델로 렌더링하지 않습니다.

검사 결과 해석하기

compatible은 finding이 없고, warning은 검토 후 렌더링할 수 있으며, incompatible에는 하나 이상의 오류가 있습니다. model3가 정상이어도 moc3, 텍스처, 모션이 빠질 수 있으므로 asset type과 path를 함께 확인하세요.

한도와 취소 설정하기

사용자가 제공한 source라면 maxAssetBytes, maxTotalBytes, maxReferences를 서비스에 맞게 낮추세요. 화면 이동이나 모델 교체가 있다면 AbortSignal을 전달합니다. abort는 reject되고 일반 모델 문제는 여러 finding으로 함께 반환됩니다.