From 4c866f3cd9fba1477f585b4d1aa5928fdc9a249b Mon Sep 17 00:00:00 2001 From: gahusb Date: Tue, 9 Jun 2026 03:53:38 +0900 Subject: [PATCH] =?UTF-8?q?docs(E5):=20=EC=9C=A0=EB=AC=BC=20=EC=84=A4?= =?UTF-8?q?=EA=B3=84=C2=B7=EA=B5=AC=ED=98=84=20=EA=B3=84=ED=9A=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/superpowers/plans/2026-06-09-relics.md | 400 ++++++++++++++++++ .../specs/2026-06-09-relics-design.md | 69 +++ 2 files changed, 469 insertions(+) create mode 100644 docs/superpowers/plans/2026-06-09-relics.md create mode 100644 docs/superpowers/specs/2026-06-09-relics-design.md diff --git a/docs/superpowers/plans/2026-06-09-relics.md b/docs/superpowers/plans/2026-06-09-relics.md new file mode 100644 index 0000000..4513ac0 --- /dev/null +++ b/docs/superpowers/plans/2026-06-09-relics.md @@ -0,0 +1,400 @@ +# 유물 (TODO E5) Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 훅 기반 유물 패시브 + 3획득 경로(시작/엘리트/상점)를 추가한다. + +**Architecture:** `data/relics.json`을 생성기가 주입(self.Relics). `ApplyRelics(hook)`을 전투시작/턴시작/카드사용/보상 4지점에서 호출. `AddRelic`을 3경로가 공유. ShopHud 유물 슬롯·상단 유물 바 UI. 모두 `gen-slaydeck.mjs`에서 생성. + +**Tech Stack:** Node.js ESM 생성기, MSW Lua codeblock/UI. 검증은 node --check+재생성+결정성+메이커 Play. + +--- + +## File Structure +- Create: `data/relics.json`. +- Modify: `tools/gen-slaydeck.mjs` — 로드/검증/직렬화, 상수, 속성, 훅 메서드(ApplyRelics/AddRelic/RenderRelics), 4지점 통합, 상점 유물(BuyRelic), UI(유물 바·상점 유물 슬롯). + +검증: MSW Lua 단위테스트 불가 → 생성기 문법·재생성·결정성·메이커 Play. + +--- + +### Task 1: 데이터 + 로드/직렬화 + 상수/속성 + 훅 메서드 + +**Files:** Create `data/relics.json`; Modify `tools/gen-slaydeck.mjs` + +- [ ] **Step 1: `data/relics.json` 작성** + +```json +{ + "relics": { + "ironHeart": { "name": "강철 심장", "desc": "전투 시작 시 방어도 +6", "hook": "combatStart", "effect": "block", "value": 6 }, + "energyCore": { "name": "에너지 코어", "desc": "턴 시작 시 에너지 +1", "hook": "turnStart", "effect": "energy", "value": 1 }, + "vampire": { "name": "흡혈 송곳니", "desc": "공격 카드 사용 시 HP +1", "hook": "cardPlayed", "effect": "healOnAttack", "value": 1 }, + "goldIdol": { "name": "황금 우상", "desc": "전투 승리 시 골드 +10", "hook": "combatReward", "effect": "gold", "value": 10 } + }, + "startingRelic": "ironHeart", + "relicPool": ["energyCore", "vampire", "goldIdol"] +} +``` + +- [ ] **Step 2: 로드·검증·직렬화 헬퍼** — `const MAP = ...` 로드 블록 다음(MAX_ROW 정의 뒤)에 추가: + +```js +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) { + if (!RELICS.relics[id]) throw new Error(`[gen-slaydeck] relicPool에 없는 유물 id: ${id}`); +} +function luaRelicsTable(relics) { + const lines = Object.entries(relics).map(([id, r]) => + `\t${id} = { name = ${luaStr(r.name)}, desc = ${luaStr(r.desc)}, hook = ${luaStr(r.hook)}, effect = ${luaStr(r.effect)}, value = ${r.value} },`); + return `self.Relics = {\n${lines.join('\n')}\n}`; +} +``` + +- [ ] **Step 3: RELIC_PRICE 상수** — `const REST_HEAL = 30;` 다음에: + +```js + const RELIC_PRICE = 60; +``` + +- [ ] **Step 4: 속성 추가** — `prop('any', 'ShopBought'),` 다음에: + +```js + prop('any', 'Relics'), + prop('any', 'RunRelics'), + prop('any', 'RelicPool'), + prop('string', 'ShopRelic', '""'), + prop('boolean', 'ShopRelicBought', 'false'), +``` + +- [ ] **Step 5: 훅 메서드 추가** — PickReward 메서드 다음(ShowMap 앞 아무 곳, 마지막 `]);` 전 임의 위치)에 삽입: + +```js + method('ApplyRelics', `if self.RunRelics == nil then + return +end +for i = 1, #self.RunRelics do + local r = self.Relics[self.RunRelics[i]] + if r ~= nil and r.hook == hook then + if r.effect == "block" then + self.PlayerBlock = self.PlayerBlock + r.value + elseif r.effect == "energy" then + self.Energy = self.Energy + r.value + elseif r.effect == "healOnAttack" then + self.PlayerHp = self.PlayerHp + r.value + if self.PlayerHp > self.PlayerMaxHp then + self.PlayerHp = self.PlayerMaxHp + end + elseif r.effect == "gold" then + self.Gold = self.Gold + r.value + end + end +end`, [{ Type: 'string', DefaultValue: null, SyncDirection: 0, Attributes: [], Name: 'hook' }]), + method('AddRelic', `if self.RunRelics == nil then + self.RunRelics = {} +end +table.insert(self.RunRelics, id) +self:RenderRelics()`, [{ Type: 'string', DefaultValue: null, SyncDirection: 0, Attributes: [], Name: 'id' }]), + method('RenderRelics', `local names = "" +if self.RunRelics ~= nil then + for i = 1, #self.RunRelics do + local r = self.Relics[self.RunRelics[i]] + if r ~= nil then + if names == "" then + names = r.name + else + names = names .. ", " .. r.name + end + end + end +end +if names == "" then + names = "없음" +end +self:SetText("/ui/DefaultGroup/CombatHud/Relics", "유물: " .. names)`), +``` + +- [ ] **Step 6: JSON·문법 검사** + +Run: `node -e "JSON.parse(require('fs').readFileSync('data/relics.json','utf8')); console.log('JSON OK')" && node --check tools/gen-slaydeck.mjs` +Expected: `JSON OK` + 오류 없음 + +- [ ] **Step 7: 커밋** + +```bash +git add data/relics.json tools/gen-slaydeck.mjs +git commit -m "data(E5): 유물 데이터 + 훅 시스템(ApplyRelics/AddRelic/RenderRelics)" +``` + +--- + +### Task 2: 훅 4지점 통합 + 시작/엘리트 획득 + +**Files:** Modify `tools/gen-slaydeck.mjs` + +- [ ] **Step 1: StartRun에 유물 주입·시작 유물** — StartRun 코드에서 `self.RunActive = true` 다음에 삽입: + +``` +self.RunRelics = {} +${luaRelicsTable(RELICS.relics)} +self.RelicPool = { ${RELICS.relicPool.map(luaStr).join(', ')} } +``` +그리고 StartRun의 `self:ShowMap()` **직전**에 삽입: +``` +self:AddRelic("${RELICS.startingRelic}") +``` + +- [ ] **Step 2: StartCombat에 combatStart 훅** — StartCombat 끝 `self:StartPlayerTurn()`를 아래로 교체: + +``` +self:StartPlayerTurn() +self:ApplyRelics("combatStart") +self:RenderCombat() +``` + +- [ ] **Step 3: StartPlayerTurn에 turnStart 훅** — `self.Energy = self.MaxEnergy` 다음 줄에 삽입: + +``` +self:ApplyRelics("turnStart") +``` + +- [ ] **Step 4: PlayCard Attack 분기에 cardPlayed 훅** — PlayCard의 Attack 분기를 교체: + +``` +if c.kind == "Attack" then + if c.damage ~= nil then + self:DealDamageToEnemy(c.damage) + end + self:ApplyRelics("cardPlayed") +elseif c.kind == "Skill" then +``` +(기존: `if c.kind == "Attack" then\n\tif c.damage ~= nil then\n\t\tself:DealDamageToEnemy(c.damage)\n\tend\nelseif c.kind == "Skill" then` 에서 `end` 다음에 `\n\tself:ApplyRelics("cardPlayed")` 추가) + +- [ ] **Step 5: CheckCombatEnd에 combatReward 훅 + 엘리트 유물** — CheckCombatEnd 승리부를 교체: + +``` +if self.EnemyHp <= 0 then + self.CombatOver = true + self.Gold = self.Gold + ${GOLD_PER_WIN} + self:ApplyRelics("combatReward") + self:RenderRun() + local node = self.MapNodes[self.CurrentNodeId] + if node ~= nil and node.type == "elite" then + self:AddRelic(self.RelicPool[math.random(1, #self.RelicPool)]) + end + if node ~= nil and node.type == "boss" then + self:ShowResult("런 클리어!") + self.RunActive = false + else + self:OfferReward() + end +elseif self.PlayerHp <= 0 then + self.CombatOver = true + self:ShowResult("패배...") + self.RunActive = false +end +``` + +- [ ] **Step 6: 문법 검사** + +Run: `node --check tools/gen-slaydeck.mjs` +Expected: 오류 없음 + +- [ ] **Step 7: 커밋** + +```bash +git add tools/gen-slaydeck.mjs +git commit -m "gen-slaydeck(E5): 훅 4지점 통합·시작/엘리트 유물 획득" +``` + +--- + +### Task 3: 상점 유물 (ShowShop/RenderShop/BuyRelic) + 바인딩 + +**Files:** Modify `tools/gen-slaydeck.mjs` + +- [ ] **Step 1: ShowShop에 유물 선택 추가** — ShowShop의 `self.ShopBought = { false, false, false }` 다음에: + +``` +self.ShopRelic = self.RelicPool[math.random(1, #self.RelicPool)] +self.ShopRelicBought = false +``` + +- [ ] **Step 2: RenderShop 끝에 유물 슬롯 렌더 + BuyRelic 메서드** — RenderShop 코드의 마지막 카드 for-loop `end` 다음(닫는 백틱 직전)에 추가: + +``` +local rr = self.Relics[self.ShopRelic] +if rr ~= nil then + self:SetText("/ui/DefaultGroup/ShopHud/Relic/Label", rr.name .. " — " .. rr.desc) + self:SetText("/ui/DefaultGroup/ShopHud/Relic/Price", string.format("%d", ${RELIC_PRICE}) .. " 골드") + local e = _EntityService:GetEntityByPath("/ui/DefaultGroup/ShopHud/Relic") + if e ~= nil and e.SpriteGUIRendererComponent ~= nil then + if self.ShopRelicBought == true then + e.SpriteGUIRendererComponent.Color = Color(0.2, 0.22, 0.26, 0.6) + else + e.SpriteGUIRendererComponent.Color = Color(0.7, 0.55, 0.85, 1) + end + end +end +``` +그리고 RenderShop 메서드 다음에 BuyRelic 메서드 추가: + +```js + method('BuyRelic', `if self.ShopRelicBought == true then + return +end +if self.Gold < ${RELIC_PRICE} then + return +end +self.Gold = self.Gold - ${RELIC_PRICE} +self:AddRelic(self.ShopRelic) +self.ShopRelicBought = true +self:RenderShop() +self:RenderRun()`), +``` + +- [ ] **Step 3: BindButtons에 유물 슬롯 바인딩** — BindButtons의 shopLeave 바인딩 다음(restLeave 앞)에 삽입: + +``` +local shopRelic = _EntityService:GetEntityByPath("/ui/DefaultGroup/ShopHud/Relic") +if shopRelic ~= nil and shopRelic.ButtonComponent ~= nil then + shopRelic:ConnectEvent(ButtonClickEvent, function() self:BuyRelic() end) +end +``` + +- [ ] **Step 4: 문법 검사** + +Run: `node --check tools/gen-slaydeck.mjs` +Expected: 오류 없음 + +- [ ] **Step 5: 커밋** + +```bash +git add tools/gen-slaydeck.mjs +git commit -m "gen-slaydeck(E5): 상점 유물 슬롯·BuyRelic·바인딩" +``` + +--- + +### Task 4: UI — 유물 바 + 상점 유물 슬롯 + +**Files:** Modify `tools/gen-slaydeck.mjs` (`upsertUi`) + +- [ ] **Step 1: CombatHud 유물 바 추가** — CombatHud의 Floor/Gold for-loop 다음(`const result = entity({` 앞)에 삽입: + +```js + combat.push(entity({ + id: guid('cmb', cmbN++), + path: '/ui/DefaultGroup/CombatHud/Relics', + modelId: 'uitext', + entryId: 'UIText', + componentNames: 'MOD.Core.UITransformComponent,MOD.Core.SpriteGUIRendererComponent,MOD.Core.TextComponent', + displayOrder: 9, + components: [ + transform({ parentW: 1920, parentH: 1080, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size: { x: 1000, y: 40 }, pos: { x: 0, y: 430 } }), + sprite({ color: TRANSPARENT }), + text({ value: '유물: 없음', fontSize: 22, bold: true, color: { r: 0.8, g: 0.7, b: 0.95, a: 1 }, alignment: 4 }), + ], + })); +``` + +- [ ] **Step 2: ShopHud 유물 슬롯 추가** — ShopHud의 Leave 버튼 push 직전에 삽입: + +```js + shop.push(entity({ + id: guid('shp', shpN++), + path: '/ui/DefaultGroup/ShopHud/Relic', + modelId: 'uisprite', + entryId: 'UISprite', + componentNames: 'MOD.Core.UITransformComponent,MOD.Core.SpriteGUIRendererComponent,MOD.Core.ButtonComponent', + displayOrder: 9, + components: [ + transform({ parentW: 1920, parentH: 1080, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size: { x: 560, y: 76 }, pos: { x: 0, y: -190 } }), + sprite({ color: { r: 0.7, g: 0.55, b: 0.85, a: 1 }, type: 1, raycast: true }), + button(), + ], + })); + shop.push(entity({ + id: guid('shp', shpN++), + path: '/ui/DefaultGroup/ShopHud/Relic/Label', + modelId: 'uitext', + entryId: 'UIText', + componentNames: 'MOD.Core.UITransformComponent,MOD.Core.SpriteGUIRendererComponent,MOD.Core.TextComponent', + displayOrder: 0, + components: [ + transform({ parentW: 560, parentH: 76, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size: { x: 540, y: 40 }, pos: { x: 0, y: 12 } }), + sprite({ color: TRANSPARENT }), + text({ value: '유물', fontSize: 22, bold: true, color: { r: 1, g: 1, b: 1, a: 1 }, alignment: 4 }), + ], + })); + shop.push(entity({ + id: guid('shp', shpN++), + path: '/ui/DefaultGroup/ShopHud/Relic/Price', + modelId: 'uitext', + entryId: 'UIText', + componentNames: 'MOD.Core.UITransformComponent,MOD.Core.SpriteGUIRendererComponent,MOD.Core.TextComponent', + displayOrder: 1, + components: [ + transform({ parentW: 560, parentH: 76, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size: { x: 540, y: 30 }, pos: { x: 0, y: -22 } }), + sprite({ color: TRANSPARENT }), + text({ value: '60 골드', fontSize: 20, bold: true, color: { r: 0.98, g: 0.85, b: 0.4, a: 1 }, alignment: 4 }), + ], + })); +``` + +- [ ] **Step 3: 문법 검사** + +Run: `node --check tools/gen-slaydeck.mjs` +Expected: 오류 없음 + +- [ ] **Step 4: 커밋** + +```bash +git add tools/gen-slaydeck.mjs +git commit -m "gen-slaydeck(E5): 유물 바·상점 유물 슬롯 UI" +``` + +--- + +### Task 5: 재생성 + 검증 + +**Files:** 생성물 + +- [ ] **Step 1: 생성** + +Run: `node tools/gen-slaydeck.mjs` +Expected: `Slay deck UI and combat codeblocks generated.` + +- [ ] **Step 2: 메서드·UI·데이터 확인** + +Run: `node -e "const j=JSON.parse(require('fs').readFileSync('RootDesk/MyDesk/SlayDeckController.codeblock','utf8')); const n=j.ContentProto.Json.Methods.map(m=>m.Name); console.log(['ApplyRelics','AddRelic','RenderRelics','BuyRelic'].every(x=>n.includes(x))?'METHODS OK':'MISSING'); const sr=j.ContentProto.Json.Methods.find(m=>m.Name==='StartRun').Code; console.log(/ironHeart/.test(sr)&&/강철 심장/.test(sr)?'RELICS OK':'NO RELICS'); const u=JSON.parse(require('fs').readFileSync('ui/DefaultGroup.ui','utf8')); const has=p=>u.ContentProto.Entities.some(e=>e.path===p); console.log(has('/ui/DefaultGroup/CombatHud/Relics')&&has('/ui/DefaultGroup/ShopHud/Relic/Label')?'UI OK':'UI MISSING')"` +Expected: `METHODS OK` / `RELICS OK` / `UI OK` + +- [ ] **Step 3: 결정성** + +Run: `node tools/gen-slaydeck.mjs >/dev/null && sha1sum ui/DefaultGroup.ui RootDesk/MyDesk/SlayDeckController.codeblock > /tmp/a.sha && node tools/gen-slaydeck.mjs >/dev/null && sha1sum ui/DefaultGroup.ui RootDesk/MyDesk/SlayDeckController.codeblock > /tmp/b.sha && diff /tmp/a.sha /tmp/b.sha && echo DETERMINISTIC` +Expected: `DETERMINISTIC` + +- [ ] **Step 4: git status** + +Run: `git checkout -- Global/common.gamelogic 2>/dev/null; git status --short` +Expected: `data/relics.json`, `tools/gen-slaydeck.mjs`, `ui/DefaultGroup.ui`, `RootDesk/MyDesk/SlayDeckController.codeblock` (+docs). + +- [ ] **Step 5: 생성물 커밋** + +```bash +git add ui/DefaultGroup.ui RootDesk/MyDesk/SlayDeckController.codeblock +git commit -m "재생성(E5): 유물 시스템·UI 반영" +``` + +- [ ] **Step 6: 메이커 Play 수동 검증 (MCP)** + +reload→Play: 시작 유물(강철심장)→전투 시작 PlayerBlock 6 / energyCore 보유 시 턴 에너지 4 / vampire 보유 시 공격 HP+1 / goldIdol 승리 골드+25 / 엘리트 승리→유물 획득(바 갱신) / 상점 유물 구매(골드-60). MCP는 AddRelic/BuyRelic/PlayCard/PickNode 직접 호출 + 로그. + +--- + +## Self-Review +- **Spec coverage:** 데이터/로드/훅메서드(Task1), 4지점통합·시작·엘리트(Task2), 상점유물(Task3), UI(Task4), 검증(Task5). 스펙 전 항목 매핑. +- **Placeholder scan:** 모든 단계 실제 코드/명령. +- **Type consistency:** 메서드 `ApplyRelics/AddRelic/RenderRelics/BuyRelic` 정의·호출·바인딩 일치. 속성 `Relics/RunRelics/RelicPool/ShopRelic/ShopRelicBought` 정의(Task1·1)·사용(Task2·3) 일치. UI 경로 `/CombatHud/Relics`·`/ShopHud/Relic/{Label,Price}`가 codeblock(RenderRelics/RenderShop)·생성(Task4)에서 동일. 유물 필드 `name/desc/hook/effect/value` 데이터·luaRelicsTable·ApplyRelics 일치. 상수 `RELIC_PRICE` Task1 정의·Task3 사용. diff --git a/docs/superpowers/specs/2026-06-09-relics-design.md b/docs/superpowers/specs/2026-06-09-relics-design.md new file mode 100644 index 0000000..d0b2d9e --- /dev/null +++ b/docs/superpowers/specs/2026-06-09-relics-design.md @@ -0,0 +1,69 @@ +# 유물 (TODO E5) — 설계 + +> 작성: 2026-06-09 / 상태: 승인됨 / 근거: TODO E 분해(E5) + 기존 전투/맵/상점 구조. +> 선행: E1~E4 완료. 후속: E6(저장/다음 층). 사용자 요청: 획득 3경로(시작·엘리트·상점) 모두. + +## 문제 + +런 영속·맵·보상·상점은 됐으나 유물(패시브 빌드 요소)이 없다. 훅 기반 패시브 + 다양한 획득 경로가 필요하다. + +## 설계 + +### 데이터 `data/relics.json` +```json +{ + "relics": { + "ironHeart": { "name": "강철 심장", "desc": "전투 시작 시 방어도 +6", "hook": "combatStart", "effect": "block", "value": 6 }, + "energyCore": { "name": "에너지 코어", "desc": "턴 시작 시 에너지 +1", "hook": "turnStart", "effect": "energy", "value": 1 }, + "vampire": { "name": "흡혈 송곳니", "desc": "공격 카드 사용 시 HP +1", "hook": "cardPlayed", "effect": "healOnAttack", "value": 1 }, + "goldIdol": { "name": "황금 우상", "desc": "전투 승리 시 골드 +10", "hook": "combatReward", "effect": "gold", "value": 10 } + }, + "startingRelic": "ironHeart", + "relicPool": ["energyCore", "vampire", "goldIdol"] +} +``` +- `relicPool` = 엘리트/상점에서 무작위로 줄 후보(시작 유물 제외). 중복 허용(스택). + +### 파라미터 (생성기 상수) +- `RELIC_PRICE = 60`. + +### 상태 추가 +- `Relics`(any) — 전체 유물 정의(주입). +- `RunRelics`(any) — 보유 유물 id 목록. +- `ShopRelic`(string) — 상점 제시 유물 id. +- `ShopRelicBought`(boolean). + +### 훅 시스템 +- `ApplyRelics(hook)`: RunRelics 순회, `hook` 일치 유물의 effect 적용: + - `block`→PlayerBlock+=value, `energy`→Energy+=value, `healOnAttack`→PlayerHp+=value(상한 클램프), `gold`→Gold+=value. +- 연결 지점: + - `combatStart` → StartCombat 끝(StartPlayerTurn 호출 뒤 — 방어도 리셋 이후 적용 → RenderCombat). + - `turnStart` → StartPlayerTurn(에너지 회복 직후). + - `cardPlayed` → PlayCard의 Attack 분기(데미지 적용 후). + - `combatReward` → CheckCombatEnd 승리(기본 골드 += 후). + +### 획득 (공통 `AddRelic(id)` → RunRelics 추가·RenderRelics) +- **C 시작**: `StartRun`에서 `RunRelics={}` → `AddRelic(startingRelic)`. +- **A 엘리트**: `CheckCombatEnd` 승리 시 노드 `type=="elite"`면 `relicPool`에서 무작위 `AddRelic`(보스는 런 종료라 제외). +- **B 상점**: `ShowShop`에서 `ShopRelic = relicPool 무작위`, ShopRelicBought=false; `BuyRelic`(ShopRelicBought거나 Gold