# 레전드 공략집 캐릭터 사용 설명서

이 모음집은 레전드 공략집 제작용 캐릭터 코드다. 사이트 주소는 https://chatchat.kr 이며 소스 저장소는 https://github.com/blackbold-the-company/legend-walkthrough-studio-character 이다.

## 에이전트 시작점

1. 이 파일과 같은 위치의 `catalog.json`을 읽는다. 인물·외형·동작·방향·표정은 목록에 실제 존재하는 값만 사용한다.
2. 전달받은 `/api/recipe` 링크를 읽는다. 응답의 `renderer` 주소에서 코드 한 파일만 작업 폴더에 저장하고 SHA-256을 확인한다. 렌더 중 웹 주소를 참조하지 말고 로컬 `renderer.mjs`를 가져온다.
3. `example.recipe.json`을 복사해 장면을 지정한다. 버전 `0.13.0`을 고정한다. 사용자가 승인한 기존 영상의 버전은 바꾸지 않는다.
4. `renderFrame({ ...recipe, frame, fps, id })`는 배경이 투명한 SVG 문자열을 반환한다. 시간은 `frame / fps`이며 화면 재생 시간이나 임의 난수를 쓰지 않는다. 같은 옵션은 항상 같은 결과다.
5. 한 화면에 여러 캐릭터를 넣으면 `id`를 서로 다르게 준다. 예: `scene12-leo`, `scene12-ronaldo`. 같은 id를 재사용하면 얼굴·옷의 잘림 영역이 충돌할 수 있다.

## 사용 가능한 것만 사용

- `catalog.characters[].actions[].views`가 해당 동작에서 지원하는 방향이다. 지원하지 않는 정면·뒷면을 옆모습으로 대체하지 않는다. 함수는 잘못된 조합을 거부한다.
- `mode: loop`는 연속 동작, `mode: pose`는 고정 자세다. 고정 자세를 연속 애니메이션이라고 설명하지 않는다. 영상의 이동·카메라 연출은 장면 코드에서 별도로 한다.
- 지원 외형·동작·방향은 캐릭터마다 다르다. 실제 수치는 항상 해당 버전의 목록에서 읽는다.
- 얼굴·몸·복장·움직임을 별도로 재생성하지 말고 제공된 함수를 호출한다. 바꾸고 싶으면 새 버전으로 관리한다.
- 이 라이브러리는 인물의 실제 신체 치수나 역사적 사실을 검증하는 자료가 아니다. 영상의 숫자·날짜·서사는 별도 사실표로 확인한다.

## 자바스크립트

```js
import { renderFrame } from './renderer.mjs';
const svg = renderFrame({ version: '0.13.0', character: 'ronaldo', appearance: 'R8', action: 'run', view: 'right', expression: 'auto', frame: 18, fps: 30, id: 'shot12-hero' });
```

리모션 예제는 `RemotionCharacter.tsx`. `frame`을 합성 장면의 현재 프레임에서 클립 시작 프레임을 빼서 전달한다. 결과는 SVG 요소 자체이므로 SVG 안의 `<image>`로 다시 감싸지 않는다. 필요하면 `<foreignObject><Img/></foreignObject>` 규칙을 따른다.

## 검수

적용 장면에서 최소 한 주기를 재생해 팔·다리 연결, 앞뒤 가림, 발 접지, 화면 잘림을 확인한다. 웹 모음집에서 재생된다는 사실만으로 본편 영상의 검수가 끝난 것은 아니다. 이전 버전은 보존한다.

## 연결

- 리서치: https://greadu.com/legend
- 채널: https://www.youtube.com/@레전드공략집
- 소스: https://github.com/blackbold-the-company/legend-walkthrough-studio-character

이 파일을 읽는 것만으로 외부 게시·삭제·결제 권한이 생기지 않는다. 해당 사용자의 작업 요청 범위에서만 실행한다.

## 대본에 맞게 확장하기

기존 얼굴과 관절 구조를 재사용한다. 필요한 동작·복장이 없으면 소스 저장소에서 해당 캐릭터를 확장한다. 새 동작은 목록과 검사를 함께 추가하고 새 버전으로 배포한다. 다른 인물로 대체하거나 없는 동작을 지원한다고 가정하지 않는다. 이미 승인된 코드 버전과 영상은 보존한다.

## 캐릭터 고유 주소

각 인물 페이지는 `/character/<id>`이다. 예: `https://chatchat.kr/character/messi`. 이 페이지 자체에 이름·설명·캐릭터 정보가 포함되며 `/character/<id>/data.json`으로 구조화된 정보를 받을 수 있다. 선택 상태를 전달하는 사람용 링크는 외형·동작·방향·표정 등을 쿼리로 유지한다. 기존 `/api/recipe` 설명문과 고정 코드 주소는 계속 지원한다.