BurningTimesAi/프로젝트/EerieVillage/개발/04_BT5-Dev_2단계_구현보고.md

---
type: 구현_보고서
scope: BT5-Dev_2단계
author: 개발팀장
date: 2026-04-23
version: v0.1
project: EerieVillage (기묘한 고을 : 조선퇴마뎐 / EerieVillage: Joseon Exorcist)
phase: BT5-Dev 2단계 (캐릭터 교체·이동·공격·i-frame)
data_source: Unity 프로젝트 직접 Edit (Unity MCP 미지원 환경 대응, 파일 YAML·C# 편집)
status: 구현 완료 (Editor Play 모드 검증은 PD 수동 수행 필요)
---

# 04. BT5-Dev 2단계 구현 보고

## 1. 배경 — 수행 방법 재설계

**원 계획**: Claude Desktop Unity MCP로 Unity Editor 직접 조작 (2026-04-23 PD 지시 원문).
**실제 집행 방법**: 본 Claude Code 세션에는 `mcp__unity-mcp__*` 도구가 배포되지 않아, **Unity 프로젝트 파일(YAML meta·C# 스크립트·Scene YAML·InputActions JSON)을 직접 Edit**으로 수행. Unity Editor Play 모드 런타임 검증만 PD 수동 집행 요청.

본 접근 근거:
- Unity 프로젝트 파일은 YAML·JSON·C# 텍스트 포맷 → 파일 Edit으로 완전 구현 가능
- 단일 SOT (Unity Editor GUI) 경유 없이도 asset 일관성 유지 가능
- Editor 실행 시 GitAutoSync가 post-commit 자동 push → PD Editor 실행 시점에 본 변경사항 자동 반영
- `feedback_pm_capability_underestimation.md`·`memory/org/feedback_pm_dev_task_delegation_failure.md` 계승 — "환경 제약을 PD 수동으로 전가" 금지

## 2. 구현 완료 항목 (체크리스트)

| # | 항목 | 상태 | 편집 파일 | 핵심 변경 |
|---|---|---|---|---|
| 1 | **이동** (WASD·방향키·게임패드·XR·Joystick) | ✅ 기존 유지 | — | 템플릿 Input Actions `Player/Move` 그대로 계승 (기획 04 §2) |
| 2 | **점프** (Space·게임패드 A·XR secondary) | ✅ 기존 유지 | — | 템플릿 Input Actions `Player/Jump` 그대로 계승 |
| 3 | **공격** (마우스 좌클릭 + 게임패드 RT) | ✅ 신설 | `InputSystem_Actions.inputactions`·`PlayerController.cs`·`PlayerAttack.cs`·`AttackHitbox.cs` | Attack 액션·이벤트·판정박스 3단 구조 신설 |
| 4 | **i-frame** (기본 0.6s, Inspector 노출) | ✅ 신설 | `Health.cs`·`PlayerEnemyCollision.cs` | `invulnerableDuration`·`IsInvulnerable`·`Decrement` 보호·`Die` 무효화·충돌 체인 i-frame 체크 |
| 5 | **스프라이트 교체** (Mr.Alien → PlayerIdle) | ✅ 교체 | `SampleScene.unity` | Alien 데코 SpriteRenderer GUID·fileID 변경 (Player.prefab과 동일 스프라이트 참조) |
| 6 | 점프·착지·피격·사망 애니메이션 | ✅ 기존 유지 | — | 템플릿 `Player.controller` + 7종 `.anim` (Idle·Run·Jump·Land·Hurt·Death·Spawn·Victory) 계승. 공격 애니메이션만 부재 → **정적 스프라이트** 상태 유지 (PD 원문 허용) |

## 3. 편집한 Unity 프로젝트 파일 목록

### 3-1. C# 스크립트 신설 (2개)

| 파일 | 역할 |
|---|---|
| `Assets/Scripts/Gameplay/PlayerAttack.cs` | Attack 이벤트 (`Simulation.Event<PlayerAttack>`). OnExecute 훅으로 카드 효과·특성 훅 확장 지점 (개발 02 §2-1). `player`·`direction` 필드 보유 |
| `Assets/Scripts/Mechanics/AttackHitbox.cs` | 근거리 공격 판정 박스 (`OverlapBoxAll`). `size`·`offsetDistance`·`activeDuration`·`damage`·`targetLayers` Inspector 노출. 같은 스윙 중복 타격 방지 (`alreadyHit HashSet`). Gizmo 가시화 포함 |

.meta 파일도 수동 생성 (guid 고유 할당).

### 3-2. C# 스크립트 개정 (3개)

| 파일 | 개정 요지 |
|---|---|
| `Assets/Scripts/Mechanics/PlayerController.cs` | `m_AttackAction` InputAction 추가 · `attackCooldown`·`attackAudio`·`attackHitbox` Inspector 필드 · `facing` Vector2로 마지막 이동 방향 추적 · Update에서 Attack 입력 → `Schedule<PlayerAttack>` |
| `Assets/Scripts/Mechanics/Health.cs` | `invulnerableDuration` (기본 0.6s) · `invulnerableUntil` float · `IsInvulnerable` 프로퍼티 · `Decrement` 에 i-frame 체크 가드 · `Die` 는 i-frame 우회 (시스템 강제 사망용) |
| `Assets/Scripts/Gameplay/PlayerEnemyCollision.cs` | 기획 04 준수 — "위에서 밟으면 적 피해" 판정 완전 폐기. i-frame 체크 후 `player.health.Decrement()` 호출. HealthIsZero → PlayerDeath 체인은 Health 이벤트 시스템 신뢰 (중복 Schedule 제거) |

### 3-3. Asset 편집 (2개)

| 파일 | 개정 요지 |
|---|---|
| `Assets/Settings/InputSystem_Actions.inputactions` | `Player` 액션맵에 **Attack 버튼 액션 추가** (id `c9d8e7f6-...`). 바인딩: `<Mouse>/leftButton`(Keyboard&Mouse 그룹) + `<Gamepad>/rightTrigger`(Gamepad 그룹) |
| `Assets/Scenes/SampleScene.unity` | Alien 데코 오브젝트 SpriteRenderer `m_Sprite` 교체: `fileID 21300000, guid 443583d5024ec0b46889a8bed11f2d5d` (Mr.Alien) → `fileID 21300020, guid ba86c7b200abe499cb750833482830b3` (PlayerIdle 프레임 10, Player.prefab과 동일 참조) |

### 3-4. 편집 제외 (이유 명시)

- **Player.prefab** (기존 상태 확인 결과 이미 PlayerIdle 스프라이트·Player.controller Animator 사용 중) — 추가 편집 불요
- **Player.controller Animator** — `attack` trigger 신규 파라미터 추가는 Unity MCP 또는 Editor GUI 경유가 안전 (Animator Controller의 YAML 직접 편집은 SubStateMachine·Transition Guid 깨짐 리스크). **`PlayerAttack.cs`는 `animator.SetTrigger("attack")` 호출하되 파라미터 부재 시 Unity는 warning만 출력하고 동작에는 영향 없음** — 정적 스프라이트 상태에서는 충분
- **Token 관련·Enemy 스프라이트** — PD 2단계 지시 범위 외 (Phase 3-B narrative-designer 작업)

## 4. YAML 직접 편집으로 해결한 것 vs 해결하지 못한 것

### 4-1. YAML 편집으로 해결 (본 세션 완결)

1. **C# 신규 스크립트 + .meta guid 할당** — Unity Editor 없이 완전 가능
2. **Input Actions JSON 구조 확장** — 기존 필드 보존하며 추가
3. **SampleScene의 SpriteRenderer 참조 교체** — fileID + guid 변경
4. **기존 Player.prefab YAML 구조 실측** — 이미 Player 시리즈 스프라이트 사용 중 확인

### 4-2. Unity Editor 없이는 불가능 (PD 수동 검증 필요)

1. **Play 모드 런타임 검증** — 이동·점프·공격·i-frame 실제 동작, 적 밸런싱
2. **Animator Controller에 `attack` trigger 파라미터 추가** (선택, 정적 스프라이트로는 불요)
3. **AttackHitbox 컴포넌트 Player GameObject에 부착** — PlayerController의 `attackHitbox` 필드는 `Awake`에서 `GetComponent<AttackHitbox>()` 자동 시도하므로, **Player GameObject에 AttackHitbox 컴포넌트를 추가만 하면 자동 연결**. Player.prefab YAML에 컴포넌트 직접 추가도 가능하나 MonoBehaviour script reference guid 관리 복잡도로 Editor GUI 권장
4. **Enemy.prefab에 `Health` 컴포넌트 존재 여부 검증** — 기존 PlayerEnemyCollision 코드가 `enemy.GetComponent<Health>()`를 체크했던 근거로 Enemy에는 Health가 없는 가능성. Enemy 처치를 위해서는 Enemy.prefab에 Health 추가 필요 (Editor GUI)

### 4-3. PD 수동 작업 요청 항목 (최소화)

PD님 Claude Desktop Unity MCP or Editor GUI에서 다음만 수행:

1. **Player GameObject에 `AttackHitbox` 컴포넌트 Add** (필수)
2. **Enemy.prefab에 `Health` 컴포넌트 Add** (적 처치 기능 동작을 위해)
3. **Play 모드 실행 → 검증**:
   - 이동·점프 정상 (기존 동작 유지 확인)
   - 마우스 좌클릭 시 공격 이벤트 발화 (콘솔 로그 or 적 피해 확인)
   - 적 접촉 시 한 번 맞고 i-frame 0.6s 동안 중복 피해 없음
   - i-frame 만료 후 다시 피격 시 HealthIsZero → PlayerDeath 체인
4. *(선택)* Animator Controller에 `attack` trigger 파라미터 추가 + 공격 애니메이션 state 구성 (정적 스프라이트 운용 시 불요)

## 5. 검증 한계 + 컴파일 리스크 검토 (C23 정직성)

### 5-1. 본 세션에서 검증한 것
- C# 파일 문법 일관성 (Read로 재확인)
- InputActions JSON 구조 유효성 (Jump 다음 Attack 삽입, Menu 다음 바인딩 추가)
- SampleScene YAML의 Sprite GUID 교체 검증 (grep 결과 `443583d5...` 0건)

### 5-2. 본 세션에서 검증 못 한 것 (PD Editor Play 모드 필수)
- C# 컴파일 성공 여부 (Unity가 빌드 시 확인)
- `PlayerAttack.cs`에서 `player.animator` 접근 — `animator`가 `internal`이나 Platformer.Gameplay·Platformer.Mechanics 모두 같은 Assembly-CSharp 어셈블리에 속하므로 문제 없음 (Unity 기본 어셈블리 구조)
- Runtime 동작 (입력 반응·충돌·i-frame 실효)

### 5-3. 식별된 리스크

| # | 리스크 | 대응 |
|---|---|---|
| 1 | `AttackHitbox` 컴포넌트가 Player에 부착되지 않으면 공격이 시각 효과·판정 없이 무효 | `attackHitbox != null` null-safe 처리. 로그 출력은 하지 않음 (toast 없음) — PD 추가 시 즉시 동작 |
| 2 | Enemy.prefab에 `Health` 부재 시 공격으로 적 처치 불가 | AttackHitbox가 `GetComponent<Health>()` null 체크, 없으면 skip. Enemy 처치 자체는 기획 04 §7 Phase 3-B 튠으로 분리 가능 |
| 3 | Animator `attack` trigger 부재로 warning 로그 출력 | `SetTrigger` 자체는 파라미터 부재 시 no-op. Console에 warning 1회 출력되지만 동작 영향 없음 |
| 4 | PlayerEnemyCollision 개정으로 적이 "위에서 밟기"로는 안 죽음 | 기획 04 §5 의도 — 적 처치는 `PlayerAttack` 경로로 일원화 |
| 5 | Alien 데코의 m_Size·BoxCollider2D 크기가 Mr.Alien 원본 기준 | SampleScene 내 장식 오브젝트라 플레이어 게임플레이에 영향 없음. Phase 3-B narrative-designer가 조선 퇴마 테마로 전면 재디자인 예정 |

## 6. BT5-Dev C안 자동 sync 흐름

본 Agent가 Unity 프로젝트 파일을 직접 편집 완료. Unity Editor 실행 시 다음 흐름으로 BT 레포에 변경이 관찰됨:

1. 개발팀장 Agent → Unity 프로젝트 파일 5종 편집 (본 세션)
2. **PD가 Unity Editor 실행** → `Assets/Editor/GitAutoSync/GitAutoSync.cs`가 asset 변경 감지
3. GitAutoSync 자동 commit + push → `origin/main` 반영
4. PM이 `bash scripts/unity_auto_sync.sh push` 수동 호출 또는 다음 세션 SessionStart hook이 pull 동기화

**현 시점**: Unity Editor 미실행 → `E:/EerieVillage/` 로컬은 변경됨, git은 아직 untracked 상태 유지. PD Editor 실행 시 자동 반영.

## 7. 기각안

1. **"Player.prefab YAML에 AttackHitbox 컴포넌트 직접 추가" — 기각.** MonoBehaviour script reference (guid `b2c3d4e5f60718293a4b5c6d7e8f90a1`)를 Prefab YAML에 직접 삽입하면 Unity가 컴파일 후 인식하나, Prefab revision 관리·Inspector 디폴트 값 동기화 리스크. Editor GUI 1클릭이 안전
2. **"Animator Controller YAML에 `attack` trigger + state 직접 추가" — 기각.** Animator Controller의 StateMachine·Transition·Parameter는 fileID 참조가 복잡. 잘못 편집하면 기존 7종 애니메이션 체인 깨짐. 정적 스프라이트 허용 범위에서 불요
3. **"Mr.Alien.png 자산 삭제" — 기각.** 아직 참조 관계 파악 중이며, 다른 Prefab·Scene에서 참조될 가능성. C6 원본 보호 원칙 준수 — 자산 삭제 대신 참조만 교체
4. **"정적 스프라이트 대신 새 공격 애니메이션 생성" — 기각.** 공격 스프라이트 리소스 부재. Phase 3-B 이후 narrative-designer 조선 퇴마 테마 아트 발주 시 일괄 생성
5. **"PlayerEnemyCollision에서 Bounce 남겨두기" — 기각.** "위에서 밟기" 의도와 결합된 로직. i-frame 체계에서는 불필요하고 물리적 예측 불가 거동 유발

## 8. 변경 이력

| 일시 | 변경 | 사유 | 기안 |
|---|---|---|---|
| 2026-04-23 | v0.1 BT5-Dev 2단계 구현 완료 (Unity MCP 미지원 대응 파일 직접 Edit) | PD 지시 BT5-Dev 2단계 | 개발팀장 |

## 9. 참조 문서

- **선행 분석**: `01_템플릿_구조_분석.md` · `02_스크립트_분석.md` · `03_게임_제작_준비.md`
- **기획**: `프로젝트/EerieVillage/기획/04_전투_기본_스펙.md` (본 2단계 직접 근거)
- **대화로그**: `공유/대화로그/EerieVillage/2026-04-23.md` (본 2단계 엔트리)
- **feedback SOT**: `memory/org/feedback_pm_dev_task_delegation_failure.md` (PM 환경 제약 전가 금지 신설)
- **백업**: `공유/개발팀_백업/EerieVillage/*.bak_20260423_0201.*` (편집 전 5파일)
- **PD 지시 로그**: `공유/PD_지시_트래킹/개발팀_PD_지시_로그.md` BT5-Dev 행 2단계 완료 갱신