gahusb/maplecontest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1847e2d9b2fa60f1d998d5895b6e6d7a85019f0f
maplecontest/docs/superpowers/plans/2026-06-08-card-combat-integration.md
gahusb 724cd5a04d docs(B): 카드 전투 통합 설계·구현 계획 문서 추가 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-09 00:04:33 +09:00

18 KiB
Raw Blame History

카드 전투 통합 (TODO B) 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: 카드 사용이 실제 적 HP·플레이어 Block·적 의도·승패에 반영되는 단일 전투 루프를 완성한다.

Architecture: 모든 변경은 tools/gen-slaydeck.mjs 단일 생성기에서 만든다. 적/플레이어 전투 상태는 SlayDeckController codeblock 내부 속성으로 보유(필드 Monster.codeblock과 분리). UI는 CombatHud 그룹으로 DeckHud와 별도 생성. 수치(플레이어 80 / 적 45 / 의도 10·6·방8)는 임시 placeholder.

Tech Stack: Node.js ESM 생성기(gen-slaydeck.mjs), MSW Lua codeblock, MSW UI JSON. 검증은 node --check + 재생성 + sha1 결정성 + 메이커 Play.

File Structure

  • Modify: tools/gen-slaydeck.mjs — 유일한 변경 대상.
    • upsertUi(): CombatHud 그룹(적/플레이어 패널·결과 텍스트) 생성 추가, 정리 필터 확장.
    • writeCodeblocks(): SlayDeckController 속성·메서드 추가/수정.
  • 생성물(자동, 직접 편집 금지): ui/DefaultGroup.ui, RootDesk/MyDesk/SlayDeckController.codeblock, Global/common.gamelogic.

검증 한계: MSW codeblock Lua는 단위 테스트 러너가 없다. 자동 검증은 생성기 문법·재생성·결정성·JSON 유효성까지, 실제 동작은 메이커 Play(사용자)로 확인.

Task 1: 카드 데이터 수치화 (Cards 테이블 + UI 카드 배열)

Files:

  • Modify: tools/gen-slaydeck.mjs (upsertUi 내 cards 배열, writeCodeblocks 내 StartCombat의 self.Cards)

  • Step 1: upsertUi의 카드 배열은 표시용 그대로 두되, codeblock Cards에 수치 필드 추가

writeCodeblocks()의 StartCombat 메서드 코드에서 self.Cards 정의를 아래로 교체:

self.Cards = {
	Strike = { name = "타격", cost = 1, desc = "피해 6", kind = "Attack", damage = 6 },
	Defend = { name = "방어", cost = 1, desc = "방어도 5", kind = "Skill", block = 5 },
	Bash = { name = "강타", cost = 2, desc = "피해 10", kind = "Attack", damage = 10 },
}
  • Step 2: 문법 검사

Run: node --check tools/gen-slaydeck.mjs Expected: 오류 없음 (출력 없음, exit 0)

  • Step 3: 커밋
git add tools/gen-slaydeck.mjs
git commit -m "gen-slaydeck(B): 카드 데이터에 damage/block 수치 필드 추가"

Task 2: 전투 상태 속성 + StartCombat 초기화

Files:

  • Modify: tools/gen-slaydeck.mjs (writeCodeblocks 속성 배열, StartCombat 메서드)

  • Step 1: codeblock 속성 추가

codeblock('SlayDeckController', ...)의 properties 배열 끝에 추가:

    prop('number', 'PlayerHp', '0'),
    prop('number', 'PlayerMaxHp', '80'),
    prop('number', 'PlayerBlock', '0'),
    prop('number', 'EnemyHp', '0'),
    prop('number', 'EnemyMaxHp', '45'),
    prop('number', 'EnemyBlock', '0'),
    prop('number', 'EnemyIntentIndex', '1'),
    prop('boolean', 'CombatOver', 'false'),
    prop('any', 'EnemyIntents'),
    prop('any', 'EnemyName'),
  • Step 2: StartCombat에 전투 상태 초기화 추가

StartCombat 코드의 맨 위(self.MaxEnergy = 3 직후)에 삽입:

self.PlayerMaxHp = 80
self.PlayerHp = self.PlayerMaxHp
self.PlayerBlock = 0
self.EnemyName = "슬라임"
self.EnemyMaxHp = 45
self.EnemyHp = self.EnemyMaxHp
self.EnemyBlock = 0
self.EnemyIntents = {
	{ kind = "Attack", value = 10 },
	{ kind = "Attack", value = 6 },
	{ kind = "Defend", value = 8 },
}
self.EnemyIntentIndex = 1
self.CombatOver = false

그리고 StartCombat 끝(self:StartPlayerTurn() 직전)에 self:RenderCombat() 추가.

  • Step 3: 문법 검사

Run: node --check tools/gen-slaydeck.mjs Expected: 오류 없음

  • Step 4: 커밋
git add tools/gen-slaydeck.mjs
git commit -m "gen-slaydeck(B): 플레이어/적 전투 상태 속성·초기화 추가"

Task 3: 전투 헬퍼 메서드 (데미지/적턴/승패/렌더)

Files:

  • Modify: tools/gen-slaydeck.mjs (writeCodeblocks methods 배열에 신규 메서드 추가)

SetText는 엔티티 nil 가드가 있어, 참조하는 UI가 Task 5에서 생성되기 전이어도 안전(no-op).

  • Step 1: 신규 메서드들을 methods 배열에 추가 (Toast 메서드 정의 뒤)
    method('DealDamageToEnemy', `local dmg = amount
if self.EnemyBlock > 0 then
	local absorbed = math.min(self.EnemyBlock, dmg)
	self.EnemyBlock = self.EnemyBlock - absorbed
	dmg = dmg - absorbed
end
self.EnemyHp = self.EnemyHp - dmg
if self.EnemyHp < 0 then
	self.EnemyHp = 0
end`, [{ Type: 'number', DefaultValue: null, SyncDirection: 0, Attributes: [], Name: 'amount' }]),
    method('DealDamageToPlayer', `local dmg = amount
if self.PlayerBlock > 0 then
	local absorbed = math.min(self.PlayerBlock, dmg)
	self.PlayerBlock = self.PlayerBlock - absorbed
	dmg = dmg - absorbed
end
self.PlayerHp = self.PlayerHp - dmg
if self.PlayerHp < 0 then
	self.PlayerHp = 0
end`, [{ Type: 'number', DefaultValue: null, SyncDirection: 0, Attributes: [], Name: 'amount' }]),
    method('EnemyTurn', `self.EnemyBlock = 0
local intent = self.EnemyIntents[self.EnemyIntentIndex]
if intent ~= nil then
	if intent.kind == "Attack" then
		self:DealDamageToPlayer(intent.value)
	elseif intent.kind == "Defend" then
		self.EnemyBlock = self.EnemyBlock + intent.value
	end
end
self.EnemyIntentIndex = self.EnemyIntentIndex + 1
if self.EnemyIntentIndex > #self.EnemyIntents then
	self.EnemyIntentIndex = 1
end
self:RenderCombat()`),
    method('CheckCombatEnd', `if self.EnemyHp <= 0 then
	self.CombatOver = true
	self:ShowResult("승리!")
	-- TODO(E): 전투 보상 훅 — 카드 보상/골드/유물 선택 진입점
elseif self.PlayerHp <= 0 then
	self.CombatOver = true
	self:ShowResult("패배...")
end`),
    method('ShowResult', `self:SetText("/ui/DefaultGroup/CombatHud/Result", text)
local entity = _EntityService:GetEntityByPath("/ui/DefaultGroup/CombatHud/Result")
if entity ~= nil then
	entity.Enable = true
end`, [{ Type: 'string', DefaultValue: null, SyncDirection: 0, Attributes: [], Name: 'text' }]),
    method('RenderCombat', `self:SetText("/ui/DefaultGroup/CombatHud/EnemyName", self.EnemyName)
self:SetText("/ui/DefaultGroup/CombatHud/EnemyHp", "HP " .. tostring(self.EnemyHp) .. "/" .. tostring(self.EnemyMaxHp))
self:SetText("/ui/DefaultGroup/CombatHud/EnemyBlock", "방어 " .. tostring(self.EnemyBlock))
local intent = self.EnemyIntents[self.EnemyIntentIndex]
local intentText = ""
if intent ~= nil then
	if intent.kind == "Attack" then
		intentText = "의도: 공격 " .. tostring(intent.value)
	elseif intent.kind == "Defend" then
		intentText = "의도: 방어 " .. tostring(intent.value)
	end
end
self:SetText("/ui/DefaultGroup/CombatHud/EnemyIntent", intentText)
self:SetText("/ui/DefaultGroup/CombatHud/PlayerHp", "HP " .. tostring(self.PlayerHp) .. "/" .. tostring(self.PlayerMaxHp))
self:SetText("/ui/DefaultGroup/CombatHud/PlayerBlock", "방어 " .. tostring(self.PlayerBlock))`),
  • Step 2: 문법 검사

Run: node --check tools/gen-slaydeck.mjs Expected: 오류 없음

  • Step 3: 커밋
git add tools/gen-slaydeck.mjs
git commit -m "gen-slaydeck(B): 데미지/적턴/승패/전투렌더 헬퍼 메서드 추가"

Task 4: 턴 흐름 배선 (PlayCard 효과·EndPlayerTurn·StartPlayerTurn)

Files:

  • Modify: tools/gen-slaydeck.mjs (StartPlayerTurn, EndPlayerTurn, PlayCard 메서드 코드)

  • Step 1: StartPlayerTurn 교체

self.Turn = self.Turn + 1
self.Energy = self.MaxEnergy
self.PlayerBlock = 0
self:DrawCards(5)
self:RenderHand(true)
self:RenderCombat()
  • Step 2: EndPlayerTurn 교체
if self.CombatOver == true then
	return
end
for i = 1, #self.Hand do
	table.insert(self.DiscardPile, self.Hand[i])
end
self.Hand = {}
self:RenderHand(false)
self:RenderPiles()
self:EnemyTurn()
self:CheckCombatEnd()
if self.CombatOver == true then
	return
end
_TimerService:SetTimerOnce(function() self:StartPlayerTurn() end, 0.45)
  • Step 3: PlayCard 효과 분기 교체

PlayCard 코드를 아래로 교체(에너지 차감 후 Toast 대신 효과 적용):

if self.CombatOver == true then
	return
end
if self.Hand == nil then
	return
end
local cardId = self.Hand[slot]
if cardId == nil then
	return
end
local c = self.Cards[cardId]
if c == nil then
	return
end
if self.Energy < c.cost then
	self:Toast("에너지가 부족합니다")
	return
end
self.Energy = self.Energy - c.cost
if c.kind == "Attack" then
	if c.damage ~= nil then
		self:DealDamageToEnemy(c.damage)
	end
elseif c.kind == "Skill" then
	if c.block ~= nil then
		self.PlayerBlock = self.PlayerBlock + c.block
	end
end
table.remove(self.Hand, slot)
table.insert(self.DiscardPile, cardId)
self:RenderHand(false)
self:RenderPiles()
self:RenderCombat()
self:CheckCombatEnd()
  • Step 4: 문법 검사

Run: node --check tools/gen-slaydeck.mjs Expected: 오류 없음

  • Step 5: 커밋
git add tools/gen-slaydeck.mjs
git commit -m "gen-slaydeck(B): PlayCard 효과 분기·적턴·승패 턴흐름 배선"

Task 5: CombatHud UI 엔티티 생성

Files:

  • Modify: tools/gen-slaydeck.mjs (upsertUi: 정리 필터 확장 + CombatHud 그룹 생성)

  • Step 1: 정리 필터 확장

upsertUi() 시작부의 필터를 CombatHud도 제거하도록 교체:

  ui.ContentProto.Entities = E.filter((e) => !e.path.startsWith('/ui/DefaultGroup/DeckHud') && !e.path.startsWith('/ui/DefaultGroup/CombatHud'));
  • Step 2: DeckHud hud push 직후, CombatHud 엔티티 생성 블록 추가

ui.ContentProto.Entities.push(...hud); 직전에 아래 블록 삽입(헬퍼 entity/transform/sprite/text/guid 재사용):

  const PANEL_BG = { r: 0.08, g: 0.09, b: 0.11, a: 0.78 };
  const combat = [];
  combat.push(entity({
    id: guid('cmb', 0),
    path: '/ui/DefaultGroup/CombatHud',
    modelId: 'uiempty',
    entryId: 'UIEmpty',
    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: 1920, y: 1080 }, pos: { x: 0, y: 0 }, align: ALIGN_CENTER }),
      sprite({ color: TRANSPARENT }),
    ],
  }));
  // 적 패널 배경
  combat.push(entity({
    id: guid('cmb', 1),
    path: '/ui/DefaultGroup/CombatHud/EnemyBg',
    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: 380, y: 170 }, pos: { x: 0, y: 300 }, align: ALIGN_CENTER }),
      sprite({ color: PANEL_BG, type: 1 }),
    ],
  }));
  const enemyTexts = [
    ['EnemyName', { x: 0, y: 58 }, { x: 360, y: 44 }, '슬라임', 28, true, GOLD, 1],
    ['EnemyHp', { x: 0, y: 16 }, { x: 360, y: 40 }, 'HP 45/45', 24, true, { r: 1, g: 1, b: 1, a: 1 }, 2],
    ['EnemyBlock', { x: 0, y: -20 }, { x: 360, y: 36 }, '방어 0', 20, false, { r: 0.6, g: 0.8, b: 1, a: 1 }, 3],
    ['EnemyIntent', { x: 0, y: -56 }, { x: 360, y: 38 }, '의도: 공격 10', 22, true, { r: 1, g: 0.72, b: 0.5, a: 1 }, 4],
  ];
  let cmbN = 2;
  for (const [suffix, pos, size, value, fontSize, bold, color] of enemyTexts) {
    combat.push(entity({
      id: guid('cmb', cmbN++),
      path: `/ui/DefaultGroup/CombatHud/${suffix}`,
      modelId: 'uitext',
      entryId: 'UIText',
      componentNames: 'MOD.Core.UITransformComponent,MOD.Core.SpriteGUIRendererComponent,MOD.Core.TextComponent',
      displayOrder: enemyTexts.findIndex(([s]) => s === suffix) + 1,
      components: [
        transform({ parentW: 1920, parentH: 1080, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size, pos }),
        sprite({ color: TRANSPARENT }),
        text({ value, fontSize, bold, color }),
      ],
    }));
  }
  // 플레이어 패널 배경 + 텍스트
  combat.push(entity({
    id: guid('cmb', cmbN++),
    path: '/ui/DefaultGroup/CombatHud/PlayerBg',
    modelId: 'uisprite',
    entryId: 'UISprite',
    componentNames: 'MOD.Core.UITransformComponent,MOD.Core.SpriteGUIRendererComponent',
    displayOrder: 5,
    components: [
      transform({ parentW: 1920, parentH: 1080, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size: { x: 300, y: 110 }, pos: { x: -760, y: -260 }, align: ALIGN_CENTER }),
      sprite({ color: PANEL_BG, type: 1 }),
    ],
  }));
  const playerTexts = [
    ['PlayerHp', { x: -760, y: -238 }, { x: 280, y: 44 }, 'HP 80/80', 26, true, { r: 1, g: 1, b: 1, a: 1 }],
    ['PlayerBlock', { x: -760, y: -284 }, { x: 280, y: 38 }, '방어 0', 22, false, { r: 0.6, g: 0.8, b: 1, a: 1 }],
  ];
  for (const [suffix, pos, size, value, fontSize, bold, color] of playerTexts) {
    combat.push(entity({
      id: guid('cmb', cmbN++),
      path: `/ui/DefaultGroup/CombatHud/${suffix}`,
      modelId: 'uitext',
      entryId: 'UIText',
      componentNames: 'MOD.Core.UITransformComponent,MOD.Core.SpriteGUIRendererComponent,MOD.Core.TextComponent',
      displayOrder: 6 + playerTexts.findIndex(([s]) => s === suffix),
      components: [
        transform({ parentW: 1920, parentH: 1080, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size, pos }),
        sprite({ color: TRANSPARENT }),
        text({ value, fontSize, bold, color }),
      ],
    }));
  }
  // 결과 텍스트 (기본 숨김)
  const result = entity({
    id: guid('cmb', cmbN++),
    path: '/ui/DefaultGroup/CombatHud/Result',
    modelId: 'uitext',
    entryId: 'UIText',
    componentNames: 'MOD.Core.UITransformComponent,MOD.Core.SpriteGUIRendererComponent,MOD.Core.TextComponent',
    displayOrder: 8,
    components: [
      transform({ parentW: 1920, parentH: 1080, anchor: { x: 0.5, y: 0.5 }, pivot: { x: 0.5, y: 0.5 }, size: { x: 700, y: 140 }, pos: { x: 0, y: 120 } }),
      sprite({ color: TRANSPARENT }),
      text({ value: '', fontSize: 64, bold: true, color: GOLD, alignment: 4 }),
    ],
  });
  result.jsonString.enable = false;
  combat.push(result);
  ui.ContentProto.Entities.push(...combat);

guid 프리픽스 'cmb'를 위해 guid()의 ns 매핑에 분기 추가:

  const ns = prefix === 'hud' ? 0xd0 : prefix === 'dck' ? 0xca : prefix === 'cmb' ? 0xcb : 0xfe;
  • Step 3: 문법 검사

Run: node --check tools/gen-slaydeck.mjs Expected: 오류 없음

  • Step 4: 커밋
git add tools/gen-slaydeck.mjs
git commit -m "gen-slaydeck(B): CombatHud(적/플레이어 패널·결과) UI 엔티티 생성"

Task 6: 재생성 + 검증

Files: 생성물 3종 (생성기 실행 결과)

  • Step 1: 생성기 실행

Run: node tools/gen-slaydeck.mjs Expected: Slay deck UI and combat codeblocks generated.

  • Step 2: 생성물 JSON 유효성 확인

Run: node -e "JSON.parse(require('fs').readFileSync('ui/DefaultGroup.ui','utf8')); JSON.parse(require('fs').readFileSync('RootDesk/MyDesk/SlayDeckController.codeblock','utf8')); console.log('JSON OK')" Expected: JSON OK

  • Step 3: 결정성 확인 (2회 실행 동일)

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: CombatHud 엔티티·전투 메서드 생성 확인

Run: grep -c "CombatHud" ui/DefaultGroup.ui; grep -c "DealDamageToEnemy\|EnemyTurn\|RenderCombat" RootDesk/MyDesk/SlayDeckController.codeblock Expected: 두 값 모두 > 0

  • Step 5: 의도한 파일만 변경됐는지 확인

Run: git status --short Expected: ui/DefaultGroup.ui, RootDesk/MyDesk/SlayDeckController.codeblock (그리고 필요 시 Global/common.gamelogic)만 변경.

  • Step 6: 생성물 커밋
git add ui/DefaultGroup.ui RootDesk/MyDesk/SlayDeckController.codeblock Global/common.gamelogic
git commit -m "재생성(B): 카드 전투 통합 — 적/플레이어 전투 상태·CombatHud 반영"
  • Step 7: 메이커 Play 수동 검증 (사용자)

메이커에서 로컬 워크스페이스 reload 후 Play:

  • 타격 카드 클릭 → 적 HP 감소(적 Block 있으면 먼저 차감).
  • 방어 카드 클릭 → 플레이어 방어 수치 증가.
  • 턴 종료 → 적이 표시된 의도대로 공격(플레이어 Block이 피해 흡수) 또는 방어, 다음 의도 갱신.
  • 적 HP 0 → "승리!" 표시·입력 잠금 / 플레이어 HP 0 → "패배..." 표시·입력 잠금.

Self-Review

  • Spec coverage: 전투 상태(Task 2), 카드 수치화(Task 1), 효과 분기(Task 4), 적 의도·적 턴(Task 3·4), 승패(Task 3·4), UI 노출(Task 5) — 스펙 5개 절 모두 태스크로 매핑됨. 검증은 Task 6.
  • Placeholder scan: 모든 코드 단계에 실제 코드 포함. "TODO(E)"는 의도된 미래 훅 주석(스펙 명시)으로 placeholder 아님.
  • Type consistency: UI 경로(/ui/DefaultGroup/CombatHud/EnemyHp 등)가 codeblock RenderCombat/ShowResult와 Task 5 생성 경로에서 동일. 메서드명(DealDamageToEnemy/DealDamageToPlayer/EnemyTurn/CheckCombatEnd/ShowResult/RenderCombat)이 호출부(Task 4)와 정의부(Task 3)에서 일치. 카드 필드(damage/block/kind)가 Cards 정의(Task 1)와 PlayCard 사용(Task 4)에서 일치.
Reference in New Issue View Git Blame Copy Permalink