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

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건 유지.