스킨 편집기 조작 설명서

1. 편집기가 하는 일

• 게임의 기본 파츠로 만든 캐릭터(작업)의 머리(head)·몸(body) 점을 옮기고, 세 부위(head·body·face)의 텍스처를 칠하거나 그림으로 바꿉니다. 얼굴 판(face)은 게임 공용 모양이라 옮길 수 없고 색과 그림만 바꿉니다.
• 작업은 /studio/editor/<id> 에서 열립니다. ?mode=ai 를 붙이면 AI 편집 배치(원본·현재 3면 띠 + 상태 텍스트)가 되고, 두 배치는 같은 상태를 보여 줍니다.
• 편집은 로그인한 계정의 작업만 열립니다. AI가 쓰는 브라우저에 그 사람의 계정으로 로그인돼 있어야 하고, 주소만으로는 남의 작업이 열리지 않습니다.
• 조작 경로는 둘입니다. ① 화면의 패널·버튼(모두 이름이 붙어 있습니다) ② WebMCP 사이트 도구 editor_*(브라우저가 지원하면 페이지가 자동 등록). 둘 다 같은 엔진을 움직이므로 섞어 써도 됩니다.
• 캐릭터가 어떤 파츠로 만들어졌는지는 나중에도 바꿀 수 있습니다(「파츠」 패널 · editor_parts·editor_change_parts). 바꾸는 파츠는 원래 모습으로 들어오므로 그 파츠에 한 편집은 사라지고, 나머지 파츠의 편집은 남습니다.
• 게임이 받지 않는 파츠가 몇 가지 있어 목록에서 빼 두었습니다. 그 파츠로 만들어진 예전 캐릭터는 그대로 열리지만, 「파츠」 패널과 editor_parts 가 그 사실을 알려 주고, 바꾸지 않으면 게임에서 열리지 않습니다.
• 결과 파일은 사람이 [스킨 파일 받기]로 받습니다(게시판에 올릴지는 그때 고릅니다). AI는 저장까지만 합니다.

2. 좌표계와 이름

• 단위는 모델 좌표입니다. 캐릭터 키가 약 0.58이고, 모든 좌표는 |값| ≤ 4 안에 있어야 합니다(저장할 때 검사).
• 축: 위가 +y, 얼굴이 향하는 쪽이 −z, 정면에서 봤을 때 화면 오른쪽이 +x (캐릭터 자신의 왼손 쪽).
• 점은 「용접점」입니다: 같은 자리에 겹친 정점들을 한 점으로 묶은 것. id는 0부터 N−1이고 editor_status·editor_points·editor_select·editor_set_points 가 모두 이 id를 씁니다. 분리(editor_separate)로 나뉜 뒤에는 한 자리에 id가 둘 이상 있을 수 있습니다.
• 이름 붙은 대상: head:piece:N(이어진 머리 조각, N은 큰 조각부터 0), body:slot:<이름>(몸 부위, 예 body:slot:body_part_3), face(얼굴 판 전체). 목록은 editor_targets 또는 「선택」 패널에 있습니다.
• 몸 부위 가운데 body_part_0·body_part_7 과 left_hand_1·right_hand_1·left_hand_2·right_hand_2 는 손 모양(handPose 0·1·2)에 따라 하나씩만 보입니다.

3. 보기(카메라)

• yaw는 캐릭터를 세로축으로 돌린 각(도)입니다. 양수면 카메라가 정면에서 화면 오른쪽으로 돕니다. pitch는 음수면 위에서 내려다보고 양수면 아래에서 올려다봅니다(±90°까지).
• zoom은 확대 배율입니다: 1 = 화면에 맞춤, 2 = 두 배 크게, 0.25~4. pan은 화면 평면에서 모델을 미는 양(모델 단위, 오른쪽·위가 양수)입니다.
• editor_view 로 프리셋·각도·확대·이동·표정(faceFrame 0~6: 기본·공격·피격 1·2·3·다운·승리)·손 모양(handPose 0~2)·원본 보기(showOriginal)를 바꿉니다. 화면에서는 「보기」 패널의 버튼과 숫자 필드, 마우스(오른쪽 버튼 드래그 회전, 휠 확대, Shift 드래그 이동)입니다.
• 「보기 → 얼굴 표시」 또는 editor_face_visibility {visible: true|false}로 얼굴을 켜고 끕니다. 동물형 헤어는 기본 꺼짐이며, 선택은 저장·버전 복원·다운로드에 반영됩니다. 꺼도 얼굴 그림은 지워지지 않습니다. 켜도 헤어의 불투명한 면에 가려진 부분은 그대로 가려집니다. 일부 동물형 헤어는 얼굴을 켜서 내보낼 때 선택한 게임 서버에서만 제대로 보입니다.
• 자세(pose): 기본은 rest, 곧 파일이 담고 있는 T포즈이고 편집은 여기에서만 합니다. idle(대기)·walk(걷기)·run(달리기)은 게임이 그 몸통에 실제로 쓰는 동작으로 캐릭터를 움직여 보는 **보기 전용** 자세입니다: 옷자락이 팔에 박히는지, 머리카락이 달릴 때 어떻게 보이는지 확인할 때 씁니다.
• 동작은 몸통이 정합니다. 대부분은 사람의 걸음이지만 동물 룩(고릴라·개·돼지·쥐·닭)은 게임에서 전용 동작을 써서 네발로 걷거나 날개를 펴고 걷습니다. 그 몸통을 골랐으면 여기에서도 그 동작이 나오고, editor_status 의 view.poseMotion 이 어느 룩의 동작인지 알려 줍니다.
• editor_view {pose} 로 고르면 게임 속도로 재생됩니다. poseFrame 을 주면 그 프레임에서 멈추고, posePlay 로 다시 재생·정지합니다. 프레임 번호는 게임 모션 파일의 번호라 몸통마다 다릅니다(사람은 대기 0~2·걷기 5~9·달리기 10~14). 지금 자세의 범위는 editor_status 의 view.poseRange 에 있습니다. 움직이는 자세에서는 화면을 끌어도 회전만 되고, 도구를 고르면 T포즈로 돌아옵니다. 좌표를 다루는 도구(editor_set_points·editor_transform)는 자세와 상관없이 언제나 T포즈 좌표로 움직입니다.
• AI 편집 배치의 3면 띠는 원본(열었을 때)과 현재를 나란히 그립니다. 세트는 둘입니다: basic = 정면·측면·후면, angles = 대각·반대 측면·위 (editor_view {strip} 또는 띠 위의 버튼).
• 어느 각도든 그림으로 보려면 editor_capture 입니다. 결과는 「보기」 패널의 「마지막 캡처」에 표시되고, returnData: true 면 PNG data URL도 돌려줍니다. parts 로 부위만 골라 그릴 수 있습니다.

4. 편집 흐름

1. editor_status 로 저장 상태·선택·보기를, editor_targets 로 조각·부위 목록을 읽습니다. 무엇을 고칠지는 사람이 적은 요청이 정합니다.
2. editor_select 로 대상을 고릅니다: "all"·"none"·이름·좌표 범위·점 id. mode는 replace·add·remove.
3. 옮깁니다: editor_transform(이동·회전·크기, pivot 기본은 선택 중심, falloff로 주변 점을 부드럽게) 또는 editor_set_points(점마다 절대 좌표). 얼굴 판은 옮길 수 없습니다.
4. 붙어 있던 면이 따라오면 editor_separate: 떼어낼 부분의 점을 모두 선택한 뒤 부르면 그 부분만 움직입니다. editor_join 은 나뉜 점을 선택한 점 자리로 다시 붙입니다.
5. 색은 editor_recolor(선택한 부위의 텍스처만), 그림 전체는 editor_texture(data:image URL 또는 https 주소), 지금 그림을 읽으려면 editor_texture_read.
6. 확인합니다: 3면 띠, editor_capture, editor_status 의 selection(범위·중심). 잘못됐으면 editor_undo/editor_redo.
7. editor_save {note} 로 저장합니다. note는 이 버전의 한 줄 설명(약 150자)입니다. 게시는 하지 않습니다.

5. 사이트 도구(WebMCP) 목록

지원되는 브라우저에서 편집기 페이지가 등록합니다. 입력은 JSON 객체이고 결과도 JSON입니다. 모든 도구는 화면의 버튼과 같은 엔진 메서드를 부르므로 되돌리기·저장에 그대로 잡힙니다.

6. 텍스처(그림) 규칙

• 텍스처는 셋입니다: 머리·몸은 정사각형 한 장, 얼굴은 표정 7칸(기본·공격·피격 1·2·3·다운·승리)을 가로로 이어 붙인 7:1 아틀라스. 표정 칸 안의 눈·코·입 위치는 게임이 정한 것이라 그 자리에 맞춰 그립니다.
• 허용 크기: 머리 64·128·256, 몸 128·256, 표정 한 칸 64·128·256 (최대 256). 그림을 넣으면 그림이 담기는 가장 작은 허용 크기가 되고, 그보다 크면 256으로 줄입니다. 크기가 파일 종류를 정합니다: 머리·얼굴이 128을 넘으면 .hhskin, 64를 넘거나 몸이 128을 넘으면 .hskin, 아니면 .skin.
• 비율: 머리·몸 1:1, 얼굴은 7:1(아틀라스 전체) 또는 1:1(보고 있는 표정 한 칸만 교체). 둘레에 단색 여백이 붙은 그림은 여백을 잘라 쓰고, 그 밖의 비율은 거절합니다(늘리면 UV가 어긋납니다).
• https 주소의 그림은 서버가 대신 받습니다(사설 주소·localhost 불가, 12MB, PNG/JPG/WEBP/GIF). data:image URL은 브라우저가 바로 읽습니다.
• 그릴 때: 알파 10% 미만 텍셀은 그려지지 않지만 외곽선 껍질은 알파를 무시하므로, 투명한 부분이 넓은 삼각형은 뒤에서 보면 어두운 테두리로 남습니다. 불투명한 그림은 삼각형 안에 맞춥니다. UV에서 맞닿은 영역은 경계 1텍셀이 서로 번지니 한 텍셀 여유를 둡니다. 「아틀라스」 패널의 UV 선(주황 = 선택한 부위)으로 어느 텍셀이 어느 면인지 봅니다.

7. 저장·버전

• 저장은 바뀐 것이 있을 때만 서버에 갑니다. 서버 버전은 r1, r2…로 오르고 최근 20개를 보관합니다. 「저장한 버전」 패널의 [복원]은 새 버전으로 되돌립니다(되돌리기 단계가 아닙니다).
• 저장하지 않은 상태는 새로고침하면 사라집니다. 다른 탭에서 먼저 저장했으면 버전이 어긋나 저장이 거절되니, 새로고침한 뒤 다시 합니다.
• editor_change_parts 로 파츠를 바꾸면 그 자리에서 새 버전이 됩니다. 바꾸기 전 버전에는 그때의 파츠가 적혀 있어, [복원]하면 파츠도 함께 돌아옵니다.
• 저장된 상태는 GET /api/editor?model=<id>(JSON: head·body·face 의 positions·unique·uvs·groups, versions)와 GET /api/editor?texture=<part>&id=<id>(PNG, &which=original 은 열었을 때 그림)로도 읽을 수 있습니다. 저장 전의 상태는 editor_points·editor_texture_read 로 읽습니다.

8. 화면으로만 조작할 때 (WebMCP 없이)

• 패널 id: #editor-status(상태 텍스트, JSON 펼침), #editor-selection(목록·범위 선택), #editor-separate, #editor-transform(dx·dy·dz / rx·ry·rz / sx·sy·sz + [이동][회전][크기], 기준점), #editor-color, #editor-atlas(그림 붙여넣기·주소로 넣기·PNG 내려받기), #editor-tools, #editor-view(프리셋·각도·확대·캡처), #editor-parts(지금의 파츠 · [파츠 바꾸기]), #editor-versions, #editor-help. 마지막 동작은 #editor-last-action, 저장 상태는 #editor-save-state.
• 단축키: 도구 Q 선택 · W 이동 · E 회전 · R 크기 · T 칠하기 · C 카메라. 보기 1~8. V 분리. Esc 선택 지우기. 화살표·PageUp/PageDown 은 선택을 0.005씩 옮깁니다(Shift 0.02). Ctrl+Z / Ctrl+Y 되돌리기·다시 실행, Ctrl+S 저장.
• 화면 선택: 클릭 = 가까운 점 하나, 드래그 = 상자 안의 보이는 점, 더블클릭 = 이어진 조각·부위, Shift 추가, Alt 제외. 「뒷면 점도 선택」을 켜면 상자가 가려진 점도 고릅니다.
• 그림 넣기: 파일 선택 창을 못 쓰면 「아틀라스」 패널의 주소 필드에 data:image URL이나 https 주소를 넣고 Enter, 또는 페이지에 붙여넣기(Ctrl+V).

9. 주의

• 스킨 파일 받기와 게시판 게시·삭제는 사람이 합니다. 로그인 정보나 API 키는 어디에도 넣지 않습니다.
• 스킨 파일(.skin·.hskin·.hhskin)이나 OBJ는 편집기에 넣을 수 없습니다. 그림(PNG/JPG/WEBP)만 들어갑니다.
• 큰 편집은 저장 사이에 나눠 되돌릴 수 있게 하고, 저장할 때 note에 무엇을 했는지 적습니다.
• 긴 머리·앞머리·땋은 머리를 투명 종이카드로 만들 때는 먼저 /guide/hair-cards(긴 머리 종이 헤어카드 가이드)를 읽습니다. 파츠 고르기, 원본 그림 투영, 얼굴 외곽선 틈을 피하는 규칙이 있습니다.