maplecontest/docs/superpowers/specs/2026-06-12-potions-relics-design.md

P7 — 물약 시스템·유물 강화 설계

날짜: 2026-06-12 브랜치: feature/p7-potions-relics 선행: P6 (버프/디버프·Power — 물약·유물 효과가 힘/약화/취약을 참조)

범위

1. 물약 시스템 (StS 풀세트) — 전투 보상 확률 드랍 + 상점 구매 + 전투 중 사용 + 버리기, 슬롯 기본 3칸
2. 유물 19종 — 기존 4종 유지 + 신규 15종 (StS 효과 그대로, 메이플 장비 외형·이름)
3. 유물 아이콘 행 + 마우스오버 툴팁 — 텍스트 나열 → 장비 아이콘, hover 시 효과 설명 창
4. 물약 슬롯 5칸 유물(장인의 벨트) ★ 대표 필수

비범위: 밸런스 시뮬의 물약/유물 재현(시뮬은 카드·적 규칙만 동기화 — 기존과 동일), 맵/휴식 화면 유물 표시.

물약 (data/potions.json 신설)

id	이름	효과	StS 원본
redPotion	빨간 포션	HP 20 회복	Health 계열
firebomb	화염병	타겟 적에게 피해 20	Fire Potion
warriorElixir	전사의 물약	힘 +2 (전투 동안)	Strength Potion
guardPotion	수호의 물약	방어도 +12	Block Potion
manaElixir	마나 엘릭서	에너지 +2	Energy Potion
cursedVial	저주의 병	타겟 적에게 약화 3	Weakness Potion

• 슬롯: 기본 3칸, 장인의 벨트 보유 시 5칸. UI는 항상 5칸 그리고 벨트 없으면 4·5번째 칸 잠금 표시.
• 획득: 전투 승리 시 40% 확률(dropChance)로 랜덤 1개. 슬롯 가득이면 토스트 안내 후 미지급. 상점에서 랜덤 1종 20골드 판매(ShopPotion, 유물 패턴 동일).
• 사용: 물약 슬롯 클릭 → 미니 메뉴(사용/버리기/닫기). 사용은 전투 중에만 (전투 외 클릭 시 사용 버튼 무시 + 토스트), 버리기는 언제나 가능.
• 타겟형 물약(화염병·저주의 병)은 현재 TargetIndex 적에게 적용.
• 스키마: { potions: { id: { name, desc, effect, value, icon } }, dropChance: 0.4, baseSlots: 3, beltSlots: 5, shopPrice: 20 }
• effect 종류: heal damage strength block energy weak
• 상태: RunPotions (id 배열), PotionSlots (3|5). StartRun에서 초기화.

유물 19종 (data/relics.json 확장)

기존 4종(강철 심장·에너지 코어·흡혈 송곳니·황금 우상) 유지. 신규 15종 — StS 효과 그대로, 메이플 장비 이름:

id	장비명	효과	StS 원본	구현 지점
potionBelt	장인의 벨트	물약 슬롯 3→5 ★	Potion Belt	AddRelic
burningBlood	자쿰의 투구	전투 승리 시 HP 6 회복	Burning Blood	combatEnd
vajra	미스릴 액스	전투 시작 시 힘 +1	Vajra	combatStart
anchor	메이플 실드	첫 턴 방어도 +10	Anchor	combatStart(block)
bagOfPrep	모험가의 배낭	첫 턴 드로우 +2	Bag of Preparation	combatStart
bloodVial	피의 목걸이	전투 시작 시 HP 2 회복	Blood Vial	combatStart
bronzeScales	브론즈 체인메일	적 공격에 피격 시 공격자에게 3 반사	Bronze Scales	onPlayerDamaged
strawberry	건강의 반지	획득 시 최대 HP +7	Strawberry	AddRelic
penNib	황금 깃펜	10번째 공격 카드 피해 2배	Pen Nib	CalcPlayerAttack
boot	브론즈 부츠	5 미만 공격 피해를 5로	The Boot	CalcPlayerAttack
akabeko	황소 투구	전투 첫 공격 카드 피해 +8	Akabeko	CalcPlayerAttack
centennialPuzzle	백년의 부적	전투 중 처음 HP를 잃으면 드로우 3	Centennial Puzzle	onPlayerDamaged
meatOnBone	고기 망치	전투 종료 시 HP 50% 이하면 12 회복	Meat on the Bone	combatEnd
selfFormingClay	점토 갑옷	피해를 받으면 다음 턴 방어도 +3	Self-Forming Clay	onPlayerDamaged + StartPlayerTurn
championBelt	챔피언 벨트	카드로 취약 부여 시 약화 1 추가	Champion Belt	PlayCard 디버프 적용부

규칙 세부:

• penNib 카운터는 전투 내 공격 카드 사용 횟수 기준(StS는 런 전체 누적이나 단순화). 10·20·30…번째 2배.
• boot 은 최종 계산값이 1~4일 때 5로 보정 (0은 그대로).
• akabeko 는 전투당 1회, 첫 공격 카드의 기본 피해에 +8 (힘 적용 전 base에 합산).
• bronzeScales 반사는 공격한 적이 생존 중일 때 3 피해 (그 적의 block 무시하지 않음 — DealDamage 재사용, 취약 배수는 미적용하도록 직접 hp 차감).
• 적용 순서(CalcPlayerAttack): base + akabeko → penNib 2배 → 힘 → 약화 → boot 보정. 취약은 기존대로 명중 시.
• 유물 상태 props: FightAttackCount(펜닙·아카베코 겸용), FirstHpLossDone(퍼즐), ClayBlockNext(점토).
• 획득 경로(기존 유지 + 개선): 정예 승리·상점 + 보스 클리어 시 1개 추가. 풀에서 미보유 유물만 추첨(PickNewRelic), 전부 보유 시 골드 +25 대체.
• relicPool에 신규 15종 전부 + 기존 3종(에너지 코어·흡혈 송곳니·황금 우상) 포함. 시작 유물은 ironHeart 유지.
• 스키마 확장: 각 유물에 icon(RUID) 추가. 신규 hook 값: combatEnd, onPlayerDamaged, passive(AddRelic 시 1회).

UI

유물 아이콘 행 (CombatHud TopBar)

• 기존 TopBar/Relics 텍스트 제거 → TopBar/RelicSlot1..10 (UISprite 40×40, x -240부터 48px 간격).
• RenderRelics: 보유 유물 순서대로 아이콘 표시, 10개 초과분은 10번째 칸을 +N 텍스트로 대체.
• 각 슬롯에 UITouchReceiveComponent + UITouchEnterEvent/ExitEvent → 툴팁 표시/숨김.

물약 슬롯 (CombatHud TopBar 우측)

• TopBar/PotionSlot1..5 (UISprite 40×40, x 270부터 44px 간격, AllDeckButton(x 510) 앞에서 종료).
• 빈 칸은 어두운 배경, 잠금 칸(벨트 미보유 4·5번)은 자물쇠 느낌의 더 어두운 색.
• 클릭(ButtonClickEvent 대신 UITouchDownEvent) → PotionMenu 팝업: 물약명·설명 + [사용] [버리기] [닫기].
• hover 툴팁 동일 적용.

툴팁 (TooltipBox)

• /ui/DefaultGroup/CombatHud/TooltipBox — bg(260×72) + Name + Desc 텍스트, displayOrder 최상위, 기본 비활성.
• Enter 시 대상 슬롯 인덱스에 따라 x 위치 조정해 표시, Exit 시 숨김. 공용 메서드 ShowTooltip(name, desc, x, y) / HideTooltip().

상점 (ShopHud)

• 기존 ShopHud/Relic 아래 ShopHud/Potion 추가 — 라벨·가격(20골드)·구매 처리 BuyPotion (ShopRelic 패턴 복제, 슬롯 가득 시 구매 거부 토스트).

데이터 흐름

StartRun: RunPotions = {}, PotionSlots = baseSlots, 유물 초기화(기존) → RenderRelics·RenderPotions. CheckCombatEnd(승리): combatEnd 유물 → 물약 드랍 판정 → 기존 보상 흐름. DealDamageToPlayer: HP 실손실 시 onPlayerDamaged 유물 발동 (공격자 slot 인자 추가).

검증

1. node tools/deck/gen-slaydeck.mjs 성공, node --test 통과 (기존 21건 — 시뮬 변경 없음)
2. 메이커 빌드 콘솔 0 에러 + 플레이테스트: 유물 아이콘·툴팁 hover·물약 사용/버리기·벨트 5칸 확인

결정 사항

• 물약 아이콘·유물 아이콘 RUID는 공식 maplestory 리소스에서 메이커 미리보기로 선별 (계정 리소스 금지)
• 물약 6종으로 시작 (StS 핵심 6역할), 추가는 데이터만으로 확장 가능
• penNib 전투 내 카운터·bronzeScales 단순 반사 등 경량화는 표에 명시한 대로