Merge pull request 'feat: 노드 맵 UI 강화 — 아이콘 노드 + 다크 배경 (nodeicons.json 외부화)' (#58) from feature/node-map-ui into main

Reviewed-on: #58
2026-06-15 23:05:25 +09:00
parent 9966065409 6c35d959ac
commit 5377112826
6 changed files with 5260 additions and 7130 deletions
--- a/RootDesk/MyDesk/SlayDeckController.codeblock
+++ b/RootDesk/MyDesk/SlayDeckController.codeblock
--- a/data/nodeicons.json
+++ b/data/nodeicons.json
@@ -0,0 +1,11 @@
+{
+  "icons": {
+    "combat":   "f98db6823e894a4f90308d61f75894ac",
+    "elite":    "793ed8a757534b89a82f460747d2df24",
+    "boss":     "423056cdbbc04f4da131b9721c404d96",
+    "shop":     "da37e1fac55d455b9ade08569f09f798",
+    "rest":     "b86c1b0568bd45f3ae4a4b97e1b4a594",
+    "treasure": "f8a6d58e20f54e2ca899485055df1ce4"
+  },
+  "background": "ef89906dd9844fcbaafc0b2313812eca"
+}
--- a/docs/superpowers/plans/2026-06-15-node-map-ui.md
+++ b/docs/superpowers/plans/2026-06-15-node-map-ui.md
@@ -0,0 +1,227 @@
+# 노드 맵 UI 강화 구현 계획
+
+> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:executing-plans. 설계: `docs/superpowers/specs/2026-06-15-node-map-ui-design.md`. 산출물(`ui/DefaultGroup.ui`·`*.codeblock`)은 Read/Edit 금지 — `tools/deck/gen-slaydeck.mjs` 소스·`data/*.json`만 수정 후 재생성. 검증은 `node tools/verify/count.mjs`(카운트)와 메이커 플레이테스트.
+
+**Goal:** 맵 노드 선택 화면(MapHud)을 단색 박스+텍스트 → 공식 메이플 아이콘 노드 + 배경 이미지로 강화하고, 아이콘/배경 RUID를 `data/nodeicons.json`로 외부화해 교체를 쉽게 한다.
+
+**Architecture:** 단일 소스(`data/nodeicons.json` + `tools/deck/gen-slaydeck.mjs`) → 산출물 재생성. 노드 = 아이콘 스프라이트(타입별 ImageRUID 런타임 주입, 상태는 Color 틴트), 배경 = MapHud 루트 이미지 + 반투명 오버레이. 절차 랜덤 배치·간선·버튼 바인딩 불변.
+
+**Tech Stack:** Node.js ESM 생성기, MSW Lua(codeblock).
+
+**확정 RUID** (공식 maplestory, 썸네일 검수): combat=`f98db6823e894a4f90308d61f75894ac`, elite=`793ed8a757534b89a82f460747d2df24`, boss=`423056cdbbc04f4da131b9721c404d96`, shop=`da37e1fac55d455b9ade08569f09f798`, rest=`b86c1b0568bd45f3ae4a4b97e1b4a594`, treasure=`f8a6d58e20f54e2ca899485055df1ce4`, background=`d84241f17de344a097f5b96ac914f1d2`.
+
+**현재 코드 기준선**(gen-slaydeck.mjs): MapHud emit `1662~1763`(루트 `1664`, pushMapNode `1696`, 그리드 `1727`, 도트 displayOrder 1), RenderMapNode `5615~5677`, luaFramesTable `72`, OnBeginPlay 주입 `2906`, StartRun 주입 `3361`, CardFrames prop `2854`, CHEST 상수 `84`, sprite 헬퍼 `297`(dataId→ImageRUID, type 0=이미지).
+
+---
+
+### Task 1: `data/nodeicons.json` + 생성기 로드·검증·직렬화
+
+**Files:** Create `data/nodeicons.json` · Modify `tools/deck/gen-slaydeck.mjs`
+
+- [ ] **Step 1:** `data/nodeicons.json` 생성:
+
+```json
+{
+  "icons": {
+    "combat":   "f98db6823e894a4f90308d61f75894ac",
+    "elite":    "793ed8a757534b89a82f460747d2df24",
+    "boss":     "423056cdbbc04f4da131b9721c404d96",
+    "shop":     "da37e1fac55d455b9ade08569f09f798",
+    "rest":     "b86c1b0568bd45f3ae4a4b97e1b4a594",
+    "treasure": "f8a6d58e20f54e2ca899485055df1ce4"
+  },
+  "background": "d84241f17de344a097f5b96ac914f1d2"
+}
+```
+
+- [ ] **Step 2:** `gen-slaydeck.mjs` CHEST 상수(`85`) 아래에 로드+검증 추가:
+
+```js
+// 노드 맵 아이콘/배경 (공식 maplestory RUID, data/nodeicons.json 단일 소스 — 교체 시 이 파일만 수정 후 재생성)
+const NODEICONS = JSON.parse(readFileSync('data/nodeicons.json', 'utf8'));
+for (const t of ['combat', 'elite', 'boss', 'shop', 'rest', 'treasure']) {
+  if (!/^[0-9a-f]{32}$/.test((NODEICONS.icons || {})[t] || '')) throw new Error(`[gen-slaydeck] nodeicons.json icons.${t} RUID 누락/형식오류`);
+}
+if (!/^[0-9a-f]{32}$/.test(NODEICONS.background || '')) throw new Error('[gen-slaydeck] nodeicons.json background RUID 누락/형식오류');
+```
+
+- [ ] **Step 3:** `luaFramesTable`(`77`) 직후에 직렬화 헬퍼 추가:
+
+```js
+function luaNodeIconsTable() {
+  const rows = Object.entries(NODEICONS.icons).map(([t, ruid]) => `\t${t} = ${luaStr(ruid)},`).join('\n');
+  return `self.NodeIcons = {\n${rows}\n}`;
+}
+```
+
+- [ ] **Step 4:** prop 선언 추가 — `prop('any', 'CardFrames'),`(`2854`) 아래에 `prop('any', 'NodeIcons'),`.
+
+- [ ] **Step 5:** OnBeginPlay 주입 — `2906`의 `${luaFramesTable()}` 줄 **아래**에 `${luaNodeIconsTable()}` 추가. StartRun 주입(`3361`)의 `${luaFramesTable()}` 아래에도 동일 추가.
+
+- [ ] **Step 6:** 로드 검증(아직 산출물 미변경이라 생성만 확인):
+
+```bash
+node -e "const n=require('./data/nodeicons.json'); console.log('icons',Object.keys(n.icons).join(','),'| bg',n.background.length)"
+```
+기대: `icons combat,elite,boss,shop,rest,treasure | bg 32`
+
+- [ ] **Step 7:** 커밋:
+
+```bash
+git add data/nodeicons.json tools/deck/gen-slaydeck.mjs
+git commit -m "feat(node-map): nodeicons.json 외부화 + 생성기 로드·검증·NodeIcons 직렬화"
+```
+
+---
+
+### Task 2: MapHud emit — 배경 이미지 + 오버레이 + 아이콘 노드
+
+**Files:** Modify `tools/deck/gen-slaydeck.mjs`
+
+- [ ] **Step 1:** MapHud 루트 sprite(`1673`)를 **배경 이미지**로 변경:
+
+```js
+      sprite({ dataId: NODEICONS.background, color: { r: 1, g: 1, b: 1, a: 1 }, type: 0, raycast: false }),
+```
+
+- [ ] **Step 2:** 루트 push(`1677` `map.push(mapHud);`) 직후, Title push 앞에 **반투명 오버레이 자식** 추가:
+
+```js
+  map.push(entity({
+    id: guid('map', 990),
+    path: '/ui/DefaultGroup/MapHud/Overlay',
+    modelId: 'uisprite', entryId: 'UISprite',
+    componentNames: 'MOD.Core.UITransformComponent,MOD.Core.SpriteGUIRendererComponent',
+    displayOrder: 0,
+    components: [
+      transform({ parentW: 1920, parentH: 1080, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size: { x: 1920, y: 1080 }, pos: { x: 0, y: 0 }, align: ALIGN_CENTER }),
+      sprite({ color: { r: 0.04, g: 0.05, b: 0.09, a: 0.5 }, type: 1, raycast: true }),
+    ],
+  }));
+```
+(guid 'map',990 은 노드 그리드·도트가 쓰는 mapN(2~약189)보다 충분히 높아 충돌 없음. 빌드 끝 id 유일성 검증이 잡아줌.)
+
+- [ ] **Step 3:** Title displayOrder를 오버레이(0) 위로 — Title 엔티티(`1684` `displayOrder: 0,`)를 `displayOrder: 2,`로 변경.
+
+- [ ] **Step 4:** `pushMapNode`(`1696~1726`) — 노드 본체를 **아이콘**으로 + Label 자식 제거:
+  - 본체 sprite(`1707`)를 `sprite({ color: { r: 1, g: 1, b: 1, a: 1 }, type: 0, raycast: true }),`로 변경(단색 박스 → 이미지, 런타임에 ImageRUID 주입).
+  - Label 자식 push 블록(`1713~1725`, `map.push(entity({ ... /Label ... }))` 전체)을 **삭제**.
+
+- [ ] **Step 5:** 노드 크기 키움 — 그리드 호출(`1729`)의 `{ x: 56, y: 56 }`을 `{ x: 64, y: 64 }`로, 보스 호출(`1732`)의 `{ x: 72, y: 72 }`을 `{ x: 88, y: 88 }`로 변경.
+
+- [ ] **Step 6:** 커밋(아직 RenderMapNode 미수정 — 다음 Task와 함께 재생성/검증):
+
+```bash
+git add tools/deck/gen-slaydeck.mjs
+git commit -m "feat(node-map): MapHud 배경 이미지+오버레이, 노드 아이콘화(라벨 제거·확대)"
+```
+
+---
+
+### Task 3: RenderMapNode Lua — ImageRUID + 상태 틴트
+
+**Files:** Modify `tools/deck/gen-slaydeck.mjs`
+
+- [ ] **Step 1:** `RenderMapNode` 메서드 본문(`5615~5677`)을 아래로 **교체**(타입별 박스색/라벨 → 아이콘 ImageRUID + 상태 틴트). Lua 들여쓰기는 기존과 동일하게 실제 탭:
+
+```lua
+local base = "/ui/DefaultGroup/MapHud/Node_" .. id
+local e = _EntityService:GetEntityByPath(base)
+if e == nil then
+	return
+end
+local node = self.MapNodes[id]
+if node == nil then
+	e.Enable = false
+	return
+end
+e.Enable = true
+local ruid = self.NodeIcons[node.type]
+if ruid == nil then
+	ruid = self.NodeIcons["combat"]
+end
+if e.SpriteGUIRendererComponent ~= nil and ruid ~= nil then
+	e.SpriteGUIRendererComponent.ImageRUID = ruid
+end
+local reachable = self:IsReachable(id)
+local visited = false
+if self.VisitedNodes ~= nil then
+	for i = 1, #self.VisitedNodes do
+		if self.VisitedNodes[i] == id then visited = true end
+	end
+end
+if e.SpriteGUIRendererComponent ~= nil then
+	if id == self.CurrentNodeId then
+		e.SpriteGUIRendererComponent.Color = Color(1, 0.82, 0.3, 1)
+	elseif visited == true then
+		e.SpriteGUIRendererComponent.Color = Color(0.5, 0.5, 0.55, 0.9)
+	elseif reachable == true then
+		e.SpriteGUIRendererComponent.Color = Color(1, 1, 1, 1)
+	else
+		e.SpriteGUIRendererComponent.Color = Color(0.4, 0.4, 0.45, 0.45)
+	end
+end
+if e.ButtonComponent ~= nil then
+	e.ButtonComponent.Enable = reachable
+end
+```
+(메서드 시그니처 `[{Type:'string',...,Name:'id'}]`는 유지. `self:SetText(base.."/Label", ...)` 호출은 라벨 제거로 사라짐 — RenderMapDots/RenderMap는 불변.)
+
+- [ ] **Step 2:** 재생성:
+
+```bash
+node tools/deck/gen-slaydeck.mjs
+```
+기대: "Slay deck UI and combat codeblocks generated."
+
+- [ ] **Step 3:** 카운트 검증(내용 출력 금지, node fs):
+
+```bash
+node -e "const fs=require('fs');const cb=fs.readFileSync('RootDesk/MyDesk/SlayDeckController.codeblock','utf8');const ui=fs.readFileSync('ui/DefaultGroup.ui','utf8');const c=(s,p)=>(s.match(new RegExp(p,'g'))||[]).length;console.log('NodeIcons inject:',c(cb,'self.NodeIcons ='),'(>=2: OnBeginPlay+StartRun)','| ImageRUID in RenderMapNode:',c(cb,'NodeIcons\\\\[node.type\\\\]'),'| UI MapHud/Overlay:',c(ui,'MapHud/Overlay'),'(1)','| UI Label nodes(0 기대):',c(ui,'Node_r1c1/Label'),'| bg RUID:',c(ui,'d84241f17de344a097f5b96ac914f1d2'));"
+```
+기대: NodeIcons inject ≥2, ImageRUID ≥1, Overlay 1, Label 0, bg RUID ≥1.
+
+- [ ] **Step 4:** 커밋:
+
+```bash
+git add tools/deck/gen-slaydeck.mjs ui/DefaultGroup.ui RootDesk/MyDesk/SlayDeckController.codeblock
+git commit -m "feat(node-map): RenderMapNode 아이콘 ImageRUID+상태 틴트, 재생성"
+```
+
+---
+
+### Task 4: 미러/회귀 테스트
+
+- [ ] **Step 1:** 전투/맵그래프 미러 미변경 확인 — 테스트 실행:
+
+```bash
+node --test tools/balance/sim-balance.test.mjs tools/map/rogue-map.test.mjs
+```
+기대: 전부 PASS(이 변경은 UI만, 전투/맵그래프 무관).
+
+- [ ] **Step 2:** `git status --short`로 의도치 않은 산출물 변경 없는지 확인.
+
+---
+
+### Task 5: 메이커 플레이테스트
+
+- [ ] **Step 1:** `maker_refresh_workspace` → `maker_logs build`로 빌드 에러 0 확인(기존 BuySoulUnlock Info 경고는 무관).
+
+- [ ] **Step 2:** `maker_play` → 런 시작(`SelectClass`+`StartNewGame`) → 맵 화면 `maker_screenshot`. 검증:
+  - 배경 이미지(리스항구) + 어두운 오버레이 위에 노드들.
+  - 노드가 **타입별 아이콘**(주황버섯/골렘/발록/돈주머니/모닥불/상자)으로 표시, 라벨 텍스트 없음.
+  - 상태 틴트: 현재=금색, 도달가능=원색(밝게), 잠김=어둡고 흐릿.
+  - 도달 가능 노드 클릭 시 진행(`PickNode`/마우스). 랜덤 배치 정상.
+  - 아이콘 잘림/왜곡 점검(특히 보스 발록·골렘). 잘리면 해당 노드 size 또는 아이콘 RUID 조정.
+
+- [ ] **Step 2b:** 실패 시 디버깅 — 흰박스→RUID/리로드 확인, 아이콘 안 뜸→ImageRUID 주입·NodeIcons 시드 확인, 가독성→오버레이 알파/틴트 튜닝. 생성기 수정→재생성→refresh→재플레이.
+
+- [ ] **Step 3:** `maker_stop`. 스크린샷 사용자 공유.
+
+---
+
+### Task 6: PR
+
+- [ ] **Step 1:** `git push -u origin feature/node-map-ui`(인증 실패 시 `GCM_INTERACTIVE=never GIT_TERMINAL_PROMPT=0 git push`로 재시도).
+- [ ] **Step 2:** UTF-8 spec JSON 작성 후 `node tools/git/gitea-pr.mjs create <spec.json>`. 제목 "feat: 노드 맵 UI 강화 — 아이콘 노드 + 배경 이미지(nodeicons.json 외부화)".
+- [ ] **Step 3:** 사용자에게 PR 번호 보고. (변경 용이성: `data/nodeicons.json` RUID만 바꾸고 `node tools/deck/gen-slaydeck.mjs` 재실행하면 교체됨을 명시.)
--- a/docs/superpowers/specs/2026-06-15-node-map-ui-design.md
+++ b/docs/superpowers/specs/2026-06-15-node-map-ui-design.md
@@ -0,0 +1,96 @@
+# 노드 맵 UI 강화 설계
+
+작성일: 2026-06-15
+브랜치: `feature/node-map-ui`
+
+## 목표
+
+맵 노드 선택 화면(`MapHud`)을 **단색 박스+텍스트** → **공식 메이플 아이콘 노드 + 배경 이미지**로 강화한다.
+절차 랜덤 배치·간선·진행 로직은 그대로. 아이콘/배경은 **`data/nodeicons.json` 한 파일로 외부화**해 나중에 RUID만 바꿔 재생성하면 교체되도록 한다.
+
+요청 원문: "노드 창이 단순 네모 박스안에 텍스트 … 백그라운드 이미지 삽입하고 특정 아이콘을 지정해서 노드로 … 랜덤 배치 … 노드 맵 UI 강화. 내가 나중에 변경할 수도 있으니 변경이 쉽게 가능하도록."
+
+## 확정된 결정 (브레인스토밍)
+
+| 항목 | 결정 |
+|---|---|
+| 노드 표현 | **아이콘만**(박스 제거). 상태는 아이콘 틴트로 |
+| 배경 | **공식 메이플 배경 이미지** + 반투명 어두운 오버레이 |
+| 아이콘 세트 | 사용자 확정(아래 표). 공식 maplestory RUID, 썸네일 검수 완료 |
+| 변경 용이성 | 모든 RUID를 `data/nodeicons.json`로 외부화 → 편집+재생성으로 교체 |
+
+### 확정 아이콘/배경 (공식 maplestory, 흰박스 위험 없음)
+
+| 노드 타입 | 아이콘 | RUID |
+|---|---|---|
+| combat(전투) | 주황버섯 | `f98db6823e894a4f90308d61f75894ac` |
+| elite(엘리트) | 돌골렘(Stumpy) | `793ed8a757534b89a82f460747d2df24` |
+| boss(보스) | 주니어 발록 | `423056cdbbc04f4da131b9721c404d96` |
+| shop(상점) | 보라 돈주머니 | `da37e1fac55d455b9ade08569f09f798` |
+| rest(휴식) | 모닥불 | `b86c1b0568bd45f3ae4a4b97e1b4a594` |
+| treasure(보물) | 금별 보물상자 | `f8a6d58e20f54e2ca899485055df1ce4` |
+| **background** | 리스항구 | `d84241f17de344a097f5b96ac914f1d2` |
+
+## 현재 구조 (조사 결과)
+
+- `MapHud` 루트 = 1920×1080 **단색** 패널(`gen-slaydeck.mjs:1664`, 배경 이미지 없음) + 타이틀.
+- 노드 = `pushMapNode(id,pos,size,label)`(`:1696`) — `Node_{id}` 단색 박스(56×56, 보스 72×72) + `Label` 텍스트 자식. 그리드 `r1c1~r6c4`(24) + `boss`(`:1727`).
+- 타입 6종: combat/elite/shop/rest/treasure/boss. 타입→색/라벨은 **Lua `RenderMapNode`**(`:5626~5677`)가 런타임에 박스 `Color` + Label 텍스트로 채움. 상태 4단(현재 금색/방문 회색/도달 타입색/잠김 어둡게).
+- 절차 생성 `GenerateMap`(`:5505`) → `self.MapNodes[id]={type,row,col,next}`, id `r{r}c{c}`가 UI 엔티티와 1:1. 버튼 바인딩(`:3597`)은 경로 기반.
+- 이미지 주입 패턴: emit `sprite({dataId: RUID, type:0})`(`sprite()` 헬퍼 `:297`) / 런타임 `e.SpriteGUIRendererComponent.ImageRUID = "<ruid>"`(`ApplyCardFace :4089`, chest `:5874`). 카드 프레임은 `data/cardframes.json`→`luaFramesTable()`(`:72`)→`self.CardFrames` Lua 테이블.
+
+## 상세 설계
+
+### 1) `data/nodeicons.json` (신설 — 단일 소스)
+```json
+{
+  "icons": {
+    "combat":   "f98db6823e894a4f90308d61f75894ac",
+    "elite":    "793ed8a757534b89a82f460747d2df24",
+    "boss":     "423056cdbbc04f4da131b9721c404d96",
+    "shop":     "da37e1fac55d455b9ade08569f09f798",
+    "rest":     "b86c1b0568bd45f3ae4a4b97e1b4a594",
+    "treasure": "f8a6d58e20f54e2ca899485055df1ce4"
+  },
+  "background": "d84241f17de344a097f5b96ac914f1d2"
+}
+```
+- 사용자가 나중에 RUID만 바꾸고 `node tools/deck/gen-slaydeck.mjs` 재실행하면 교체됨. (README/주석에 명시.)
+
+### 2) `gen-slaydeck.mjs` — 로드·검증·직렬화
+- 상단에서 `NODEICONS = JSON.parse(readFileSync('data/nodeicons.json'))` 로드.
+- **fail-fast 검증**: `icons`에 6타입(combat/elite/boss/shop/rest/treasure) 전부 존재 + 32hex RUID, `background` 존재. 누락 시 throw(카드프레임 검증과 동일 패턴).
+- `luaNodeIconsTable()` 헬퍼: `self.NodeIcons = { combat="...", ... }` Lua 테이블 문자열. OnBeginPlay init에 주입(CardFrames 패턴, `:2906/3361` 인접). `prop('any','NodeIcons')` 선언.
+
+### 3) MapHud emit 변경
+- **배경 자식 `MapHud/Bg`**: 루트 직후 push. `uisprite`, 1920×1080, `dataId = NODEICONS.background`, `type:0`, 흰색, `raycast:false`, displayOrder 최하(0). 항상 enable.
+- **루트 오버레이**: 기존 루트 단색을 **반투명 어두운 오버레이**로(예: `{r:0.04,g:0.05,b:0.08,a:0.55}`)— 배경이 비치되 노드 가독성 확보. raycast 유지(뒤 월드 클릭 차단).
+- **`pushMapNode` → 아이콘 노드**: `Node_{id}` 본체를 박스 대신 **아이콘 스프라이트**로 — `sprite({ color:{1,1,1,1}, type:0, raycast:true })`(emit 시 dataId 미지정, 런타임에 타입별 ImageRUID 주입) + `button()`. **`Label` 자식 제거**(아이콘만). 노드 크기 키움: 그리드 64×64, 보스 88×88. (좌표 헬퍼 `nodeX/nodeY`·그리드 생성 루프·버튼 바인딩은 불변.)
+
+### 4) RenderMapNode Lua 변경
+- 타입→박스색/라벨 매핑(`:5630~5656`) 제거. 대신:
+  - `e.SpriteGUIRendererComponent.ImageRUID = self.NodeIcons[type]` (없으면 combat 폴백).
+  - 상태별 `Color` 틴트(박스가 아니라 **아이콘**에):
+    - 현재(`CurrentNodeId`): `Color(1, 0.82, 0.3, 1)` 금색
+    - 도달가능: `Color(1, 1, 1, 1)` 원색 + `ButtonComponent.Enable=true`
+    - 방문: `Color(0.5, 0.5, 0.55, 0.9)` 회색
+    - 잠김: `Color(0.4, 0.4, 0.45, 0.45)` 어둡고 반투명 + 버튼 비활성
+- `SetText(.../Label ...)` 호출 제거(라벨 없음). 간선 도트(`RenderMapDots`)·`RenderMap` 루프는 불변.
+
+### 5) 미러/테스트 영향
+- 전투 규칙·맵 그래프 알고리즘 **미변경** → `sim-balance`/`rogue-map` 미러 동기화 불필요.
+- 검증(카운트): `MapHud/Bg` 1개, `NodeIcons` 주입, 노드 ImageRUID 주입 코드 존재, 6 RUID 등장. 내용 출력 금지(`tools/verify/count.mjs`).
+- 동작: 메이커 플레이테스트(아이콘 렌더·상태 틴트·랜덤 배치·노드 클릭 진행).
+
+## 리스크
+- **아이콘 비정사각/큰 스프라이트** → 64px UI에서 잘림/왜곡 가능(보스 발록은 확인됨, 골렘·버섯은 정사각 양호). type 0 렌더의 aspect 처리 확인, 필요 시 노드별 size 패딩 조정.
+- **아이콘만 상태 가독성**: 잠김/방문 틴트 대비가 약하면 플레이테스트로 알파/명도 튜닝.
+- **배경 오버레이 알파**: 너무 밝으면 노드가 묻힘 — 0.5~0.65 사이 튜닝.
+- 흰박스: 전부 공식 maplestory(검증) — 위험 없음. 단 로컬 워크스페이스 reload 필요.
+
+## 변경 파일 요약
+| 파일 | 변경 |
+|---|---|
+| `data/nodeicons.json` | **신설** — 아이콘 6 + 배경 RUID (단일 소스) |
+| `tools/deck/gen-slaydeck.mjs` | 로드·검증·luaNodeIconsTable, MapHud Bg/오버레이, pushMapNode 아이콘화, RenderMapNode ImageRUID+틴트 |
+| `ui/DefaultGroup.ui`·`SlayDeckController.codeblock` | 재생성 산출물 |
--- a/tools/deck/gen-slaydeck.mjs
+++ b/tools/deck/gen-slaydeck.mjs
@@ -75,6 +75,10 @@ function luaFramesTable() {
  const cls = Object.entries(CARDFRAMES.classToFrame).map(([c, f]) => `\t${c} = ${luaStr(f)},`).join('\n');
  return `self.CardFrames = {\n${frames}\n}\nself.ClassToFrame = {\n${cls}\n}`;
 }
+function luaNodeIconsTable() {
+  const rows = Object.entries(NODEICONS.icons).map(([t, ruid]) => `\t${t} = ${luaStr(ruid)},`).join('\n');
+  return `self.NodeIcons = {\n${rows}\n}`;
+}

 // 맵은 런타임 절차 생성(GenerateMap Lua ↔ tools/map/rogue-map.mjs 미러). 정적 data/map.json 제거됨.
 const MAP_ROWS = 6; // 걷는 행 1..6, 보스 row 7 (depth 최대 7)
@@ -84,6 +88,13 @@ const MAP_COLS = 4;
 const CHEST_CLOSED_RUID = '43df67920c0d43298e0d93c02c6afa71';
 const CHEST_OPEN_RUID = '09c5cee56fd640bf8ae3a18ce50f4759';

+// 노드 맵 아이콘/배경 (공식 maplestory RUID, data/nodeicons.json 단일 소스 — 교체 시 이 파일만 수정 후 재생성)
+const NODEICONS = JSON.parse(readFileSync('data/nodeicons.json', 'utf8'));
+for (const t of ['combat', 'elite', 'boss', 'shop', 'rest', 'treasure']) {
+  if (!/^[0-9a-f]{32}$/.test((NODEICONS.icons || {})[t] || '')) throw new Error(`[gen-slaydeck] nodeicons.json icons.${t} RUID 누락/형식오류`);
+}
+if (!/^[0-9a-f]{32}$/.test(NODEICONS.background || '')) throw new Error('[gen-slaydeck] nodeicons.json background RUID 누락/형식오류');
+
 const RELICS = JSON.parse(readFileSync('data/relics.json', 'utf8'));
 if (!RELICS.relics[RELICS.startingRelic]) throw new Error(`[gen-slaydeck] startingRelic 없음: ${RELICS.startingRelic}`);
 for (const id of RELICS.relicPool) {
@@ -1670,18 +1681,33 @@ function upsertUi() {
    displayOrder: 7,
    components: [
      transform({ parentW: 1920, parentH: 1080, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size: { x: 1920, y: 1080 }, pos: { x: 0, y: 0 }, align: ALIGN_CENTER }),
-      sprite({ color: { r: 0.05, g: 0.06, b: 0.09, a: 0.9 }, type: 1, raycast: true }),
+      // 불투명 다크 배경(게임 월드 가림 보장). 그 위 BgImage 자식이 배경 스프라이트를 얹는다.
+      sprite({ color: { r: 0.06, g: 0.07, b: 0.11, a: 1 }, type: 1, raycast: true }),
    ],
  });
  mapHud.jsonString.enable = false;
  map.push(mapHud);
+  // 배경 이미지(displayOrder 0 = 도트/타이틀/노드 아래). nodeicons.json background는 SPRITE RUID여야 렌더됨
+  // — 메이플 BackgroundComponent 리소스는 UI 스프라이트로 안 뜬다. 유효 스프라이트면 풀스크린 표시, 아니면 투명(다크 배경 노출).
+  map.push(entity({
+    id: guid('map', 990),
+    path: '/ui/DefaultGroup/MapHud/BgImage',
+    modelId: 'uisprite',
+    entryId: 'UISprite',
+    componentNames: 'MOD.Core.UITransformComponent,MOD.Core.SpriteGUIRendererComponent',
+    displayOrder: 0,
+    components: [
+      transform({ parentW: 1920, parentH: 1080, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size: { x: 1920, y: 1080 }, pos: { x: 0, y: 0 }, align: ALIGN_CENTER }),
+      sprite({ dataId: NODEICONS.background, color: { r: 0.5, g: 0.52, b: 0.58, a: 1 }, type: 0, raycast: false }),
+    ],
+  }));
  map.push(entity({
    id: guid('map', 1),
    path: '/ui/DefaultGroup/MapHud/Title',
    modelId: 'uitext',
    entryId: 'UIText',
    componentNames: 'MOD.Core.UITransformComponent,MOD.Core.SpriteGUIRendererComponent,MOD.Core.TextComponent',
-    displayOrder: 0,
+    displayOrder: 2,
    components: [
      transform({ parentW: 1920, parentH: 1080, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size: { x: 700, y: 60 }, pos: { x: 0, y: 510 } }),
      sprite({ color: TRANSPARENT }),
@@ -1704,32 +1730,19 @@ function upsertUi() {
      displayOrder: 5,
      components: [
        transform({ parentW: 1920, parentH: 1080, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size, pos }),
-        sprite({ color: { r: 0.2, g: 0.22, b: 0.26, a: 1 }, type: 1, raycast: true }),
+        sprite({ color: { r: 1, g: 1, b: 1, a: 1 }, type: 0, raycast: true }),
        button(),
      ],
    });
    nodeEnt.jsonString.enable = false;
    map.push(nodeEnt);
-    map.push(entity({
-      id: guid('map', mapN++),
-      path: `${nodePath}/Label`,
-      modelId: 'uitext',
-      entryId: 'UIText',
-      componentNames: 'MOD.Core.UITransformComponent,MOD.Core.SpriteGUIRendererComponent,MOD.Core.TextComponent',
-      displayOrder: 0,
-      components: [
-        transform({ parentW: size.x, parentH: size.y, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size: { x: size.x + 20, y: 30 }, pos: { x: 0, y: 0 } }),
-        sprite({ color: TRANSPARENT }),
-        text({ value: label, fontSize: id === 'boss' ? 18 : 15, bold: true, color: { r: 1, g: 1, b: 1, a: 1 }, alignment: 4 }),
-      ],
-    }));
  };
  for (let r = 1; r <= MAP_ROWS; r++) {
    for (let c = 1; c <= MAP_COLS; c++) {
-      pushMapNode(`r${r}c${c}`, { x: nodeX(r), y: nodeY(c) }, { x: 56, y: 56 }, '');
+      pushMapNode(`r${r}c${c}`, { x: nodeX(r), y: nodeY(c) }, { x: 64, y: 64 }, '');
    }
  }
-  pushMapNode('boss', BOSS_POS, { x: 72, y: 72 }, '보스');
+  pushMapNode('boss', BOSS_POS, { x: 88, y: 88 }, '보스');
  const pushDots = (dotId, from, to) => {
    for (let k = 1; k <= 3; k++) {
      const t = k / 4;
@@ -1760,6 +1773,59 @@ function upsertUi() {
  for (let c = 1; c <= MAP_COLS; c++) {
    pushDots(`r${MAP_ROWS}c${c}_b`, { x: nodeX(MAP_ROWS), y: nodeY(c) }, BOSS_POS);
  }
+  // 노드 종류 범례 (우측 하단) — 각 타입 아이콘 + 이름
+  const LEGEND = [['combat', '전투'], ['elite', '엘리트'], ['boss', '보스'], ['shop', '상점'], ['rest', '휴식'], ['treasure', '보물']];
+  const lgW = 300, lgH = 312;
+  map.push(entity({
+    id: guid('map', 991),
+    path: '/ui/DefaultGroup/MapHud/Legend',
+    modelId: 'uisprite', entryId: 'UISprite',
+    componentNames: 'MOD.Core.UITransformComponent,MOD.Core.SpriteGUIRendererComponent',
+    displayOrder: 4,
+    components: [
+      transform({ parentW: 1920, parentH: 1080, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size: { x: lgW, y: lgH }, pos: { x: 760, y: -334 } }),
+      sprite({ color: { r: 0.08, g: 0.09, b: 0.14, a: 0.86 }, type: 1, raycast: false }),
+    ],
+  }));
+  map.push(entity({
+    id: guid('map', 992),
+    path: '/ui/DefaultGroup/MapHud/Legend/LegendTitle',
+    modelId: 'uitext', entryId: 'UIText',
+    componentNames: 'MOD.Core.UITransformComponent,MOD.Core.SpriteGUIRendererComponent,MOD.Core.TextComponent',
+    displayOrder: 1,
+    components: [
+      transform({ parentW: lgW, parentH: lgH, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size: { x: lgW - 20, y: 32 }, pos: { x: 0, y: lgH / 2 - 26 } }),
+      sprite({ color: TRANSPARENT }),
+      text({ value: '노드 종류', fontSize: 22, bold: true, color: GOLD, alignment: 4 }),
+    ],
+  }));
+  let lgId = 993;
+  LEGEND.forEach(([t, ko], i) => {
+    const rowY = lgH / 2 - 78 - i * 38;
+    map.push(entity({
+      id: guid('map', lgId++),
+      path: `/ui/DefaultGroup/MapHud/Legend/Icon_${t}`,
+      modelId: 'uisprite', entryId: 'UISprite',
+      componentNames: 'MOD.Core.UITransformComponent,MOD.Core.SpriteGUIRendererComponent',
+      displayOrder: 2,
+      components: [
+        transform({ parentW: lgW, parentH: lgH, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size: { x: 36, y: 36 }, pos: { x: -lgW / 2 + 38, y: rowY } }),
+        sprite({ dataId: NODEICONS.icons[t], color: { r: 1, g: 1, b: 1, a: 1 }, type: 0, raycast: false }),
+      ],
+    }));
+    map.push(entity({
+      id: guid('map', lgId++),
+      path: `/ui/DefaultGroup/MapHud/Legend/Label_${t}`,
+      modelId: 'uitext', entryId: 'UIText',
+      componentNames: 'MOD.Core.UITransformComponent,MOD.Core.SpriteGUIRendererComponent,MOD.Core.TextComponent',
+      displayOrder: 2,
+      components: [
+        transform({ parentW: lgW, parentH: lgH, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size: { x: lgW - 110, y: 30 }, pos: { x: 32, y: rowY } }),
+        sprite({ color: TRANSPARENT }),
+        text({ value: ko, fontSize: 19, bold: false, color: { r: 0.9, g: 0.92, b: 0.96, a: 1 }, alignment: 4 }),
+      ],
+    }));
+  });
  emit('MapHud', map);

  const shop = [];
@@ -2852,6 +2918,7 @@ function writeCodeblocks() {
    prop('boolean', 'DeckAllOpen', 'false'),
    prop('any', 'Cards'),
    prop('any', 'CardFrames'),
+    prop('any', 'NodeIcons'),
    prop('any', 'ClassToFrame'),
    prop('number', 'PlayerHp', '0'),
    prop('number', 'PlayerMaxHp', '80'),
@@ -2904,6 +2971,7 @@ function writeCodeblocks() {
  ], [
    method('OnBeginPlay', `${luaCardsTable(CARDS.cards)}
 ${luaFramesTable()}
+${luaNodeIconsTable()}
 ${luaSoulShopTable(SOUL_UNLOCKS)}
 self.SoulUnlocks = {}
 self.SoulPoints = self.SoulPoints or 0
@@ -3359,6 +3427,7 @@ self.CurrentEnemyId = ""
 self.PlayerJob = ""
 ${luaJobsTable(JOBS)}
 ${luaFramesTable()}
+${luaNodeIconsTable()}
 self:GenerateMap()
 self:BindButtons()
 self:AddRelic("${RELICS.startingRelic}")
@@ -5623,37 +5692,13 @@ if node == nil then
 	return
 end
 e.Enable = true
-local tname = "전투"
-local r0 = 0.78
-local g0 = 0.36
-local b0 = 0.32
-if node.type == "elite" then
-	tname = "엘리트"
-	r0 = 0.62
-	g0 = 0.4
-	b0 = 0.85
-elseif node.type == "shop" then
-	tname = "상점"
-	r0 = 0.9
-	g0 = 0.75
-	b0 = 0.35
-elseif node.type == "rest" then
-	tname = "휴식"
-	r0 = 0.4
-	g0 = 0.75
-	b0 = 0.45
-elseif node.type == "treasure" then
-	tname = "보물"
-	r0 = 0.35
-	g0 = 0.7
-	b0 = 0.75
-elseif node.type == "boss" then
-	tname = "보스"
-	r0 = 0.85
-	g0 = 0.25
-	b0 = 0.25
+local ruid = self.NodeIcons[node.type]
+if ruid == nil then
+	ruid = self.NodeIcons["combat"]
+end
+if e.SpriteGUIRendererComponent ~= nil and ruid ~= nil then
+	e.SpriteGUIRendererComponent.ImageRUID = ruid
 end
-self:SetText(base .. "/Label", tname)
 local reachable = self:IsReachable(id)
 local visited = false
 if self.VisitedNodes ~= nil then
@@ -5663,13 +5708,13 @@ if self.VisitedNodes ~= nil then
 end
 if e.SpriteGUIRendererComponent ~= nil then
 	if id == self.CurrentNodeId then
-		e.SpriteGUIRendererComponent.Color = Color(0.95, 0.8, 0.3, 1)
+		e.SpriteGUIRendererComponent.Color = Color(1, 0.82, 0.3, 1)
 	elseif visited == true then
-		e.SpriteGUIRendererComponent.Color = Color(0.18, 0.19, 0.22, 0.9)
+		e.SpriteGUIRendererComponent.Color = Color(0.5, 0.5, 0.55, 0.9)
 	elseif reachable == true then
-		e.SpriteGUIRendererComponent.Color = Color(r0, g0, b0, 1)
+		e.SpriteGUIRendererComponent.Color = Color(1, 1, 1, 1)
 	else
-		e.SpriteGUIRendererComponent.Color = Color(r0 * 0.45, g0 * 0.45, b0 * 0.45, 0.55)
+		e.SpriteGUIRendererComponent.Color = Color(0.68, 0.68, 0.72, 0.85)
 	end
 end
 if e.ButtonComponent ~= nil then
--- a/ui/DefaultGroup.ui
+++ b/ui/DefaultGroup.ui