docs(motion): P12 설계·계획 — 전투 모션 (공격/피격/독뎀)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/superpowers/specs/2026-06-12-combat-motion-design.md

@@ -0,0 +1,36 @@
+# P12 — 전투 모션 설계
+
+날짜: 2026-06-12 (사용자 승인 완료)
+브랜치: `feature/p12-combat-motion`
+
+## 범위
+
+플레이어·몬스터의 공격/피격 모션 (독 틱 피해 포함). 순수 클라이언트 연출 — 전투 수치·시뮬 비대상.
+
+## 모션 매핑
+
+| 상황 | 대상 | 모션 |
+|---|---|---|
+| 카드 공격(단일·AoE) 사용 | 플레이어 | 아바타 공격 스윙 (`AvatarBodyActionSelectorComponent.ActionState`, pcall 가드 — 실패 시 전방 런지 폴백) → 0.4s 후 복귀 |
+| 적 공격 행동 | 몬스터 | 플레이어 방향 런지 (x −0.35 → 0.18s 복귀) — 몹 다수가 공격 클립 미보유 → StS식 채택 |
+| 몬스터 피격 (카드·AoE·물약·**독 틱**·체인메일 반사) | 몬스터 | `hit` 클립 재생(`SpriteRendererComponent.SpriteRUID` ← `StateAnimationComponent.ActionSheet["hit"]`, BuildMonsters에서 pcall 캐시) → 0.5s 후 stand 복귀. 클립 없으면 좌우 흔들림 폴백 |
+| 플레이어 피격 (적 공격) | 플레이어 | 넉백 틱 (x −0.15 → 0.15s 복귀) |
+
+## 훅 지점
+
+- `PlayCard` Attack 분기 → `PlayerAttackMotion()`
+- `EnemyActStep` Attack 인텐트 → `MonsterLunge(idx)` + 피해 후 `PlayerHitMotion()`; 독 틱 → `MonsterHitMotion(idx)`
+- `DealDamageToTarget` 피해 적용 후 → `MonsterHitMotion(slot)` (물약 화염병 포함 자동)
+- `PlayAoeFx` 대상 루프 → `MonsterHitMotion(i)`
+- `DealDamageToPlayer` 브론즈 체인메일 반사 → `MonsterHitMotion(attackerSlot)`
+- 사망 연출은 기존(KillMonster SetVisible) 유지. 모션 중 사망 시 isvalid·alive 가드로 복귀 타이머 무해화
+
+## 구현 메모
+
+- `BuildMonsters`에서 `m.hitClip`/`m.standClip` pcall 캐시 (SyncDictionary 인덱싱 실패 대비)
+- 모든 위치 복귀는 캡처한 원위치 기준 (이중 발동 시 어긋남 방지를 위해 모션 중 재발동은 위치 캡처 생략 — `m.motionBusy` 플래그)
+- 아바타 enum `MapleAvatarBodyActionState` 멤버는 메이커 프로브로 확정 후 베이크 (후보: swingO1·stabO1)
+
+## 검증
+
+메이커 플레이테스트: 카드 공격 시 아바타 스윙(또는 폴백) 로그·몬스터 hit 클립 전환 로그, 적 턴 런지·플레이어 넉백, 독 틱 모션. 빌드·런타임 0에러, 기존 테스트 40건 유지.