From 18729a2047f84802e6c388b943815edab68ca0c7 Mon Sep 17 00:00:00 2001 From: gahusb Date: Thu, 11 Jun 2026 02:35:51 +0900 Subject: [PATCH] =?UTF-8?q?docs(card-visuals):=20=EB=A9=94=EC=9D=B4?= =?UTF-8?q?=ED=94=8C=20=EC=8A=A4=ED=82=AC=20=EC=B9=B4=EB=93=9C=20=EB=B9=84?= =?UTF-8?q?=EC=A3=BC=EC=96=BC=20=EC=84=A4=EA=B3=84=20(P2)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 공식 RUID 렌더 타당성 실측 완료. 카드→전사 스킬 매핑(파워 스트라이크/슬래시 블러스트/아이언 바디), RUID 수확 워크플로, 카드 프레임(Art/NamePlate/Cost), ApplyCardFace 렌더 일원화(5표면). Co-Authored-By: Claude Opus 4.8 (1M context) --- .../specs/2026-06-11-card-visuals-design.md | 77 +++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-11-card-visuals-design.md diff --git a/docs/superpowers/specs/2026-06-11-card-visuals-design.md b/docs/superpowers/specs/2026-06-11-card-visuals-design.md new file mode 100644 index 0000000..80681ba --- /dev/null +++ b/docs/superpowers/specs/2026-06-11-card-visuals-design.md @@ -0,0 +1,77 @@ +# 메이플 스킬 카드 비주얼 (P2) — 설계 + +- 날짜: 2026-06-11 +- 대상: `data/cards.json`, `tools/deck/gen-slaydeck.mjs`(카드 엔티티 구조·ApplyCardVisual류), 생성물 +- 상태: 승인됨 (배포 퀄리티 로드맵 P2/5 — P1 UI 정비 머지됨 #34) + +## 1. 배경 / 타당성 (검증 완료) + +카드가 단색 사각형+텍스트(코스트/이름/설명)뿐이라 게임 정체성이 약하다. 메이플 스킬 이미지를 카드에 넣는다. + +**타당성 검증 완료(메이커 실측)**: `asset_search_resources`(source=maplestory, cat=sprite)로 "파워 스트라이크" 검색 → 공식 RUID 10+개. 그중 `37ed94ffd1a64a22ad91a6ae14774718`를 Play 중 `SpriteGUIRendererComponent.ImageRUID`(Type=0)에 주입 → **로컬 워크스페이스에서 정상 렌더 확인**(흰 박스 아님 — 흰 박스 문제는 클라우드 '계정' 리소스에만 해당, 공식 리소스는 OK). +주의: 검색 결과는 아이콘이 아니라 **스킬 이펙트 컷**일 수 있음 → 후보 중 선별 단계 필요. + +## 2. 카드 → 메이플 스킬 매핑 (데이터) + +`data/cards.json`의 각 카드에 선택 필드 추가: +- `image`: 공식 스프라이트 RUID(string). 없으면 현행 단색 폴백. +- 카드 `name`을 메이플 스킬명으로 변경(효과·코스트·밸런스 불변): + +| 카드 id | 기존 이름 | 새 이름(전사 스킬) | 효과 | +|---|---|---|---| +| Strike | 타격 | 파워 스트라이크 | 피해 6 | +| Bash | 강타 | 슬래시 블러스트 | 피해 10 | +| Defend | 방어 | 아이언 바디 | 방어도 5 | + +(id는 기존 유지 — RunDeck/starterDeck 호환. 표시명만 변경.) + +## 3. RUID 수확 워크플로 (구현 선행 태스크) + +1. `asset_search_resources`(source=maplestory)로 스킬별 후보 수집: "파워 스트라이크", "슬래시 블러스트", "아이언 바디" (+필요시 "워리어", "스킬" 등 보조 질의). +2. 메이커 Play에서 후보 RUID를 카드 Art에 순회 주입 + 스크린샷으로 선별(§1에서 검증한 방법). 카드 일러스트로 보기 좋은 컷 1개/스킬 확정. +3. 확정 RUID를 `data/cards.json`에 기록. (RUID 문자열만 저장 — 공식 콘텐츠 정책 기존 관행과 동일) +4. 적합 컷이 없으면 폴백: 그 카드들은 이펙트 컷 중 베스트, 그래도 없으면 image 필드 생략(단색 유지). + +## 4. 카드 프레임 구조 (upsertUi — 손패 Card1~5 기준) + +기존: 루트(단색 패널) + Cost/Name/Desc 텍스트 3개. +변경(카드 180×250 기준): +``` +Card{i} (루트: 종류색 패널 — 테두리 역할, 기존 ATTACK/DEFEND/SKILL 색 유지) +├─ Art 96×96 중앙상단(pos 0, 52): ImageRUID, Type=0, 흰색 +├─ NamePlate 168×34 (pos 0, -8): 어두운 띠 {0.07,0.08,0.1,0.92} +│ └─ (Name 텍스트를 NamePlate 위치로 이동, fontSize 20) +├─ Cost 44×44 좌상(pos -68, 103): 어두운 원판 패널 + 숫자 26 (기존 위치 강조형) +└─ Desc (pos 0, -62, fontSize 18) 하단 효과 텍스트 +``` +- 구현은 기존 자식 텍스트(Cost/Name/Desc) 위치·크기 조정 + 신규 Art/NamePlate/CostPlate 스프라이트 추가. +- 동일 구조를 **RewardHud/Reward{1~3}**, **ShopHud/Card{1~3}**, **DeckInspectHud/Grid/Card{n}**, **DeckAllHud/Grid/Card{n}** 카드에도 적용(폭이 다른 그리드 카드(158×214)는 비례 축소 좌표). + +## 5. 런타임 렌더 일원화 + +- 신규 헬퍼 `ApplyCardFace(basePath, cardId)`(Lua): Cards[cardId]에서 name/cost/desc/kind/image를 읽어 — 루트 색(kind), Art ImageRUID(있으면 표시·없으면 Art 숨김), Name/Cost/Desc 텍스트 설정. +- 기존 `ApplyCardVisual`(손패)·`ApplyRewardVisual`(보상)·상점 렌더(`RenderShop` 내 카드부)·`ApplyInspectCardVisual`(인스펙터)·모든덱 렌더가 **ApplyCardFace를 호출**하도록 통일(경로만 다름). +- Lua 카드 테이블(`luaCardsTable`)에 `image` 필드 직렬화 추가(없으면 생략). + +## 6. 변경 파일 + +| 파일 | 변경 | +|---|---| +| `data/cards.json` | name 3종 변경 + image RUID 3종 추가 | +| `tools/deck/gen-slaydeck.mjs` | luaCardsTable image, 카드 엔티티 프레임(5표면), ApplyCardFace + 호출부 통일 | +| 생성물 | `ui/DefaultGroup.ui`·`SlayDeckController.codeblock` 재생성 | +| `tools/balance/sim-balance.mjs` | 불변(이름 표시는 data에서 읽음 — 리포트에 새 이름 자동 반영) | + +## 7. 범위 제외 (후속) + +의도 아이콘(P3), 카드 호버 확대·사용 연출(P3), 희귀도 프레임 색(P5), 도적/마법사 카드(후속 콘텐츠). + +## 8. 검증 + +- 생성 결정성·dup id 0·sim 14/14(이름 변경이 테스트에 영향 없는지 확인 — 테스트는 자체 fixture 사용이라 무관). +- 메이커: 손패/보상/상점/덱보기 4표면 스크린샷 — 스킬 이미지·프레임·이름 일관 표시, image 누락 카드 폴백 정상. + +## 9. 리스크 + +- 후보 RUID가 멀티프레임 애니 시트일 수 있음 → SpriteGUIRenderer가 첫 프레임 표시(기존 옵션 FrameColumn/Row 1) — 선별 단계에서 확인. +- 그리드 카드(인스펙터/모든덱)는 ScrollLayoutGroup 셀 — 자식 추가가 셀 레이아웃에 영향 없는지 메이커 확인.