docs(readme): 최신화 — 노드맵/캐릭터이미지/신규카드 + 생성기 모듈화·메이커 파일럿

- 카드 122→123장(표창 토큰), 신규 메커니즘 exhaust/dex/thorns 추가 - tools/deck 모듈 구조(lib/hud/cb) + tools/verify diffcheck 반영 - 구현 기능 PR범위 #34~#69, 노드맵 UI·캐릭터 이미지 추가 - DefaultGroup ~6.8MB, 아키텍처 메모에 생성기 모듈화·하이브리드 파일럿(PR #70~#72) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-16 08:41:08 +09:00
parent a5388da2cc
commit d1473ad9e2
1 changed files with 13 additions and 9 deletions
--- a/README.md
+++ b/README.md
@@ -44,7 +44,7 @@ git pull
 ```
 slaymaple/
 ├── data/                       # 게임 데이터 단일 소스 (생성기가 읽어 주입). 맵은 정적 데이터 없음(절차 생성)
-│   ├── cards.json              # 카드 122장(클래스·2차전직별 + 저주) + 클래스별 시작 덱
+│   ├── cards.json              # 카드 123장(클래스·2차전직별 + 저주 + 표창 토큰) + 클래스별 시작 덱
 │   ├── enemies.json            # 적 12종(일반/정예/보스, 디버프 인텐트 포함)
 │   ├── potions.json            # 물약 6종 + 드랍률·슬롯·상점가
 │   ├── relics.json             # 유물 19종(StS 효과 × 메이플 장비) + 시작 유물 + 풀
@@ -71,19 +71,19 @@ slaymaple/
 │   ├── lobby.map               # 로비 허브 맵 (마을 배경, NPC 4종, 전투 없음)
 │   └── map01.map ~ map05.map   # 5막 전투/맵 노드 (공식 배경 + STS풍 우측 배치)
 ├── tools/                       # 결정적 생성기·도구 (주체별 폴더, 단일 소스)
-│   ├── deck/                    # gen-slaydeck.mjs(★게임 전체 생성: 카드/덱·전투·맵노드·상점·유물·로비·메뉴 UI + SlayDeckController + common) · gen-cardhand.mjs
+│   ├── deck/                    # ★게임 전체 생성 — gen-slaydeck.mjs(오케스트레이터) + lib/(ui-helpers·data·codeblock 공유) + hud/(화면별 UI emit 15종) + cb/(codeblock 메서드 17종). 출력=DefaultGroup.ui·SlayDeckController·common. gen-cardhand.mjs(보조)
 │   ├── map/                     # gen-maps.mjs(맵 배경/타일) · gen-lobby-map.mjs(로비 맵+NPC) · gen-map-encounters.mjs(노드별 몬스터 그룹) · rogue-map.mjs(절차 생성 JS 미러)+test
 │   ├── camera/                  # gen-camera.mjs(맵별 고정 카메라 codeblock)
 │   ├── player/                  # gen-player-lock.mjs(전투맵 입력 잠금) · freeze-turn-player.mjs(모델 이동 정지) · gen-lobby-npc.mjs(LobbyNpc·LobbyMobility codeblock)
 │   ├── monster/                 # gen-combat-monster.mjs(EnemyId 마커) · freeze-turn-monsters.mjs(필드 AI 정지)
 │   ├── balance/                 # sim-balance.mjs(전투 밸런스 몬테카를로 시뮬) · sim-balance.test.mjs
-│   ├── verify/                  # count.mjs(산출물 카운트 검증 헬퍼 — 경로 내장)
+│   ├── verify/                  # count.mjs(산출물 카운트 검증) · diffcheck.mjs(워킹트리 vs ref 바이트동일 검증 — 리팩터·머지용)
 │   └── git/                     # gitea-pr.mjs(UTF-8 안전 PR 생성/수정/머지 — RULES.md 참조)
-├── ui/                         # UI 그룹 (DefaultGroup 8.3MB 산출물 / PopupGroup / ToastGroup)
+├── ui/                         # UI 그룹 (DefaultGroup ~6.8MB 산출물 / PopupGroup / ToastGroup)
 ├── docs/
 │   ├── slaymaple_basic_framework.md     # 전투 프레임워크 설계 문서
 │   ├── ui-generation-structure.md       # UI 생성 구조 문서
-│   └── superpowers/specs|plans/         # 각 기능 설계·구현 계획 문서(P1~P15)
+│   └── superpowers/specs|plans/         # 각 기능 설계·구현 계획 문서(P1~P15 + 노드맵 UI·캐릭터 이미지·생성기 모듈화·메이커 파일럿)
 ├── RULES.md                    # 협업·AI 에이전트 하네스 규칙 (토큰 가드·검증·PR 절차)
 ├── CLAUDE.md                   # Claude Code 자동 로드 (RULES.md 임포트)
 └── README.md
@@ -106,16 +106,16 @@ slaymaple/

 게임 전체는 `/common` 엔티티에 부착된 **`SlayDeckController` 단일 컴포넌트**로 동작하며, 모든 산출물(`ui/DefaultGroup.ui` · `SlayDeckController.codeblock` · `common.gamelogic`)은 **`tools/deck/gen-slaydeck.mjs` 단일 소스에서 생성**됩니다(결정적 출력, 직접 편집 금지 — `RULES.md` 참조). 게임 데이터는 **`data/*.json`** 가 단일 소스, 맵 구조는 **런타임 절차 생성**(`GenerateMap` Lua ↔ `tools/map/rogue-map.mjs` JS 미러).

-### 구현된 기능 (배포 퀄리티 P1~P15, PR #34~#57)
+### 구현된 기능 (배포 퀄리티 P1~P15 + 이후 개선, PR #34~#69)

 | 영역 | 내용 |
 |---|---|
 | **로비 마을** | 전용 물리 맵 `lobby.map`(마을 배경). **NPC 4종 월드 엔티티** — 모험가(런 시작)·사서(카드 도감)·상인(영혼 상점)·안내원(게시판). 근접 시 머리 위 마크 + `↑`키 **또는 직접 클릭**으로 상호작용. **이동·공격 모션은 로비 맵에서만** 풀림(전투맵은 잠금), 카메라는 로비에서 **플레이어 추종**(전투맵은 고정) |
-| **캐릭터·전직** | 시작 시 **전사(HP80)/도적(HP70)/마법사(HP70)** 3종 선택, 클래스별 시작 덱. 보스 클리어 시 [유물] vs [**2차 전직**] — 각 클래스 3종(전사→파이터/페이지/스피어맨, 법사→위자드불독/위자드썬콜/클레릭, 도적→Shiv/Poison/Trickster). 전용 카드는 해당 클래스 풀만 획득 |
-| **카드 전투** | 에너지 3·드로우·**드래그 사용**(공격=적에 드롭, 스킬=위로 스윕). 카드 **122장** — kind **Attack/Skill/Power/Status**. 메커니즘: 다단히트·방어 무시·자가 디버프·드로·회복·**전체 공격(AoE)**·**독(DoT)**·**retain**(턴 종료 손패 유지)·**sly discard**(버림 트리거) |
+| **캐릭터·전직** | 시작 시 **전사(HP80)/도적(HP70)/마법사(HP70)** 3종 선택(**캐릭터 이미지 카드**, 선택 시 금색 테두리), 클래스별 시작 덱. 보스 클리어 시 [유물] vs [**2차 전직**] — 각 클래스 3종(전사→파이터/페이지/스피어맨, 법사→위자드불독/위자드썬콜/클레릭, 도적→Shiv/Poison/Trickster). 전용 카드는 해당 클래스 풀만 획득 |
+| **카드 전투** | 에너지 3·드로우·**드래그 사용**(공격=적에 드롭, 스킬=위로 스윕). 카드 **123장** — kind **Attack/Skill/Power/Status**. 메커니즘: 다단히트·방어 무시·자가 디버프·드로·회복·**전체 공격(AoE)**·**독(DoT)**·**retain**(턴 종료 손패 유지)·**sly discard**(버림 트리거)·**소멸(exhaust)**·**가시(thorns)**·**민첩(dex)**·**표창 토큰**(손패에 Shiv 생성) |
 | **버프/디버프** | StS 표준 — **힘**(+N 영구)·**약화**(주는 피해 −25%)·**취약**(받는 피해 +50%)·**독**(매 행동 틱). 양방향(적 디버프 인텐트 포함), 인텐트는 최종 예상치 표시 |
 | **전투 연출** | 공격 이펙트·**몬스터 데미지 팝업(자릿수 스킨)**·드래그 타깃 마커·적 개별 차례·**공격/피격/독뎀 모션**(아바타 상태 전이·몬스터 hit 클립·런지/넉백) |
-| **절차 생성 맵** | 막 시작마다 **경로 생성**(런마다 다름, **가로 진행**). 층 규칙: 1~2층 전투만 → 3층~ 상점/휴식 → 4층~ 엘리트/**유물 방** → 보스 수렴. 점선 경로·상태 4단·층 카운터. 노드 타입별 **몬스터 랜덤 구성**(일반 1~3 / 엘리트 / 보스) + intent 랜덤 행동 |
+| **절차 생성 맵** | 막 시작마다 **경로 생성**(런마다 다름, **가로 진행**). 층 규칙: 1~2층 전투만 → 3층~ 상점/휴식 → 4층~ 엘리트/**유물 방** → 보스 수렴. **노드맵 UI**: 타입별 공식 메이플 아이콘 노드(전투=버섯·엘리트=골렘·보스=발록·상점=돈주머니·휴식=모닥불·보물=상자) + scenic 배경 + 우하단 범례. 노드 타입별 **몬스터 랜덤 구성**(일반 1~3 / 엘리트 / 보스) + intent 랜덤 행동 |
 | **유물 19종 / 물약 6종** | 유물: StS 효과 × 메이플 장비 외형, TopBar 아이콘 + 마우스오버 툴팁, 8종 훅. 물약: 승리 40% 드랍·상점·슬롯 메뉴. 보물 방=상자 연출 → 유물+메소 |
 | **카드 프레임·등급** | 커스텀 프레임 3종(전사/마법사/도적 × normal/unique/legend), 카드 5개 사이트 통합 레이아웃. 보상 등급 가중 추첨 70/25/5 |
 | **영혼(Soul) 메타 성장** | 승천과 별개의 영구 강화 화폐. 2차 전직 상태로 보스 클리어 시 적립 → 로비 영혼 상점 4종 해금(시작 메소 +60·HP +15·덱 정제·시작 유물 +1). **UserDataStorage 영구 저장** |
@@ -167,12 +167,16 @@ node tools/monster/gen-combat-monster.mjs   # 몬스터 EnemyId 마커

 현재 게임 전체 로직이 `SlayDeckController` 단일 codeblock에 모여 있습니다. 초기 설계의 3분할(`SlayCardCatalog`/`SlayRunState`/`SlayCombatManager`)은 **기능적으로 모두 구현**됐으나 아직 한 컴포넌트 안에 있습니다. 맵 NPC·카메라·입력 잠금 등 **맵 단위 동작은 별도 codeblock**(LobbyNpc/LobbyMobility/MapCamera/PlayerLock/CombatMonster)으로 분리해 각 맵 루트/엔티티에 부착합니다. 카드/적/맵/유물/프레임/카메라 데이터는 `data/*.json`로 외부화돼 있습니다.

+**생성기 모듈화 (진행 중, PR #70~#72)**: 위 *출력*(단일 `SlayDeckController` 컴포넌트)은 그대로지만 **생성기**는 모듈화됐습니다 — `tools/deck/gen-slaydeck.mjs`(오케스트레이터)가 `lib/`(공유 헬퍼·데이터·codeblock 헬퍼)·`hud/`(화면별 UI emit 15종)·`cb/`(codeblock 메서드 17종)를 조합합니다(출력 바이트동일 순수 리팩터 — `tools/verify/diffcheck.mjs`로 검증, 의존 단방향 orchestrator→{hud,cb}→lib). 특정 화면 UI는 `hud/<name>.mjs`, 특정 메서드는 `cb/<name>.mjs`만 고치면 됩니다. 더해 **캐릭터 선택 화면을 메이커 저작 stock으로 이관**(레이아웃=메이커 시각 편집·재생성에 안 덮임, 이미지·선택은 컨트롤러가 경로로 런타임 주입)하는 **하이브리드 UI 파일럿**이 진행 중입니다(자세한 규칙은 `RULES.md` §1).
+
 > ⚠️ **전투 규칙과 맵 생성은 Lua(gen-slaydeck 내장)와 JS 미러(sim-balance/rogue-map)로 이중 구현**입니다. 한쪽을 고치면 반드시 다른 쪽도 동기화하고 테스트하세요(`RULES.md` §6).

 ---

 ## 향후 개선 계획 (후속 후보)
 - [x] 전투 루프 · 런 루프 · 절차 생성 맵 · 상점/휴식/유물 방 · 유물 19종 · 물약 · 버프/디버프 · Power · 전직(전사/법사/도적 2차) · 승천+개인 저장 · 전투 모션 · 커스텀 프레임 · **반복 런·로비 맵·NPC·영혼·메소·카메라 추종 (P1~P15 완료)**
+- [x] **노드맵 UI 강화(아이콘 노드+배경+범례) · 캐릭터 선택 이미지 · exhaust/dex/thorns·표창 토큰 카드 (PR #58~#69)**
+- [~] **생성기 모듈화(`lib`/`hud`/`cb`, 출력 바이트동일) + 캐릭터 선택 메이커 저작 stock 파일럿 (PR #70~#72 — 리뷰·플레이테스트 대기)**
 - [ ] **도적 카드 아이콘** — Silent 88장에 실 스킬 아이콘(image/fx) 할당, 2차 전직 설명 한글화
 - [ ] **런 이어하기** — 진행 중 런 직렬화 저장(UserDataStorage 확장, 메뉴 "이어하기" 활성화)
 - [ ] **카드 제거/업그레이드** — 상점 카드 제거 슬롯, 휴식 노드에서 카드 강화