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

# 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 원문 허용) |
| **7** | **AttackHitbox 컴포넌트 Player.prefab Add** (재위임) | ✅ **신설 v0.2** | `Assets/Prefabs/Player.prefab` | MonoBehaviour 블록 직접 YAML 추가 (`fileID 7700000000000000001`, guid `b2c3d4e5...`). 기본값: size 1.2×0.9, offsetDistance 0.7, activeDuration 0.12s, damage 1, targetLayers ALL |
| **8** | **Health 컴포넌트 Enemy.prefab Add** (재위임) | ✅ **신설 v0.2** | `Assets/Prefabs/Enemy.prefab` | MonoBehaviour 블록 직접 YAML 추가 (`fileID 7700000000000000002`, guid `ffad43bb...`). `maxHP: 1` (일반 적 첫 세팅, 코어 룰 7 정합) |
| **9** | **EditMode 테스트 스위트** (재위임) | ✅ **신설 v0.2** | `Assets/Tests/Editor/{PlayerAttackTests.cs,EerieVillage.Tests.Editor.asmdef}` | 8종 테스트 (Player 컴포넌트 3종·AttackHitbox 필드 2종·Enemy 컴포넌트 3종). Play 모드 불요 — AssetDatabase.LoadAssetAtPath + GetComponent 기반 prefab 직렬화 검증 |

## 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 수동 작업 요청 항목 (재위임 후 1건으로 축소)

**v0.1 원안** 4건(AttackHitbox Add·Health Add·Play 검증·Animator trigger) 중 컴포넌트 Add 2건 + 대체 검증 1건은 **재위임 후 AI 에이전트가 직접 수행**. 남은 PD 수동 작업은 Play 모드 GUI QA 성격 1건:

1. **Play 모드 실행 → 검증** (Unity Editor GUI 필수):
   - 이동·점프 정상 (기존 동작 유지 확인)
   - 마우스 좌클릭 시 공격 이벤트 발화 + 적 피해 (Enemy Health.maxHP 1 → 1타 처치 → EnemyDeath 체인)
   - 적 접촉 시 한 번 맞고 i-frame 0.6s 동안 중복 피해 없음
   - i-frame 만료 후 재피격 시 HealthIsZero → PlayerDeath 체인

본 1건은 Play 모드 런타임 자산 참조·프레임 타이밍·물리 시뮬레이션을 요구하므로 **AI 대체 불가**(C29-3 인간 검증 예외). 1분 미만 소요.

### 4-4. 재위임 전 기각 처리됐던 2건 — AI 에이전트 직접 수행으로 전환 (v0.2)

**v0.1 §4-2·§7-1·§7-2**에서 "MonoBehaviour guid 관리 복잡도" 사유로 Editor GUI에 위임했던 항목을 **PD 2026-04-23 재지시로 번복 직접 수행**:

1. **Player.prefab YAML에 AttackHitbox MonoBehaviour 블록 직접 추가** — 고유 `fileID 7700000000000000001` (기존 fileID 9종과 충돌 없음 grep 검증), script reference `guid b2c3d4e5f60718293a4b5c6d7e8f90a1` (AttackHitbox.cs.meta에서 확보). `m_Component` 리스트 확장. Inspector 기본값 5종 직렬화 (size·offsetDistance·activeDuration·damage·targetLayers)
2. **Enemy.prefab YAML에 Health MonoBehaviour 블록 직접 추가** — 고유 `fileID 7700000000000000002`, script reference `guid ffad43bb006db4856a9c527b89b48db9` (Health.cs.meta). `maxHP: 1` 직렬화

**근거**: (1) Unity fileID는 uint64 — `7700000000000000001` 은 기존 fileID와 완전 격리. (2) .meta guid는 파일에서 이미 확보(컴파일 후 생성 불필요). (3) `m_Component` 리스트 확장 + `--- !u!114 &<fileID> MonoBehaviour` 블록 append는 Unity 표준 YAML 구조. (4) Prefab 수정은 Scene의 모든 PrefabInstance에 자동 전파(Player 1체·Enemy 8체 — Scene YAML 직접 편집 불요, 근본 해결).

**대체 검증**: `Assets/Tests/Editor/PlayerAttackTests.cs` 8종 EditMode 테스트 — AssetDatabase 경유 prefab 컴포넌트 검증. Unity Editor에서 `Window > General > Test Runner > EditMode > Run All`로 실행. Play 모드 진입 없이 prefab 직렬화 상태 실측.

## 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 컴포넌트 직접 추가" — 기각~~ — **v0.2에서 번복 수행** (PD 2026-04-23 재위임). MonoBehaviour script reference guid는 .meta 파일에서 이미 확보(컴파일 후 생성 불필요). Inspector 기본값은 YAML에 직렬화. fileID 충돌 없음 실측 검증. 리스크는 C23 정직성 — 실제로는 YAML 직접 편집이 표준 경로(다수 2D/3D CI·자동화 사례). **기존 기각 사유 "MonoBehaviour guid 관리 복잡도"는 AI Agent Unity 파일 편집 능력 과소평가 — `feedback_pm_dev_task_delegation_failure.md` 2회차 실증**
2. **"Animator Controller YAML에 `attack` trigger + state 직접 추가" — 기각 유지.** Animator Controller의 StateMachine·Transition·Parameter는 fileID 참조가 복잡. 잘못 편집하면 기존 7종 애니메이션 체인 깨짐. 정적 스프라이트 허용 범위(PD 원문)에서 불요. `SetTrigger("attack")`은 미존재 파라미터여도 no-op (Unity API 보장). 아트 리소스 생성 후 Phase 3-B에서 일괄 처리
3. **"Mr.Alien.png 자산 삭제" — 기각 유지.** 아직 참조 관계 파악 중이며, 다른 Prefab·Scene에서 참조될 가능성. C6 원본 보호 원칙 준수 — 자산 삭제 대신 참조만 교체
4. **"정적 스프라이트 대신 새 공격 애니메이션 생성" — 기각 유지.** 공격 스프라이트 리소스 부재. Phase 3-B 이후 narrative-designer 조선 퇴마 테마 아트 발주 시 일괄 생성
5. **"PlayerEnemyCollision에서 Bounce 남겨두기" — 기각 유지.** "위에서 밟기" 의도와 결합된 로직. i-frame 체계에서는 불필요하고 물리적 예측 불가 거동 유발
6. **"EditMode 테스트 대신 PlayMode 테스트로 통합 검증" — 기각 (v0.2 신설).** PlayMode 테스트는 실제 Play 모드 진입이 필요하며 Animator·Physics·InputSystem 런타임 의존성 발생. Prefab 컴포넌트 구성 자체는 AssetDatabase로 Play 없이 검증 가능 → EditMode 선택이 회귀 방지에 더 강력(이전 상태로 rollback 돼도 Editor가 즉시 검출)
7. **"Scene YAML 직접 편집으로 Player/Enemy GameObject에 컴포넌트 추가" — 기각 (v0.2 신설).** 실측 결과 Scene의 Player·Enemy는 모두 PrefabInstance로 배치됨 (Player.prefab/Enemy.prefab guid 참조). Prefab을 수정하면 모든 Scene 인스턴스에 자동 전파 — Scene YAML 직접 편집은 불필요한 우회(C2 proxy 개선). Prefab 편집이 근본 해결

## 8. 변경 이력

| 일시 | 변경 | 사유 | 기안 |
|---|---|---|---|
| 2026-04-23 | v0.1 BT5-Dev 2단계 구현 완료 (Unity MCP 미지원 대응 파일 직접 Edit) | PD 지시 BT5-Dev 2단계 | 개발팀장 |
| 2026-04-23 | v0.2 재위임 집행 — Player.prefab AttackHitbox Add + Enemy.prefab Health Add + EditMode 테스트 8종 신설 + 기각안 1번 번복 | PD 재지시 2026-04-23 "컴포넌트 Add 2건 AI 직접 수행". AI Agent Unity 파일 편집 능력 과소평가 자진 정정 | 개발팀장 |

## 9. 참조 문서

- **선행 분석**: `01_템플릿_구조_분석.md` · `02_스크립트_분석.md` · `03_게임_제작_준비.md`
- **기획**: `프로젝트/EerieVillage/기획/04_전투_기본_스펙.md` (본 2단계 직접 근거)
- **대화로그**: `공유/대화로그/EerieVillage/2026-04-23.md` (본 2단계 + v0.2 재위임 엔트리)
- **feedback SOT**: `memory/org/feedback_pm_dev_task_delegation_failure.md` (2회차 — AI Agent Unity 파일 편집 능력 과소평가 append)
- **백업**: `Assets/Prefabs/{Player,Enemy}.prefab.bak_20260423_2334.prefab` (v0.2 집행 전) · `공유/개발팀_백업/EerieVillage/*.bak_20260423_0201.*` (v0.1 집행 전)
- **PD 지시 로그**: `공유/PD_지시_트래킹/개발팀_PD_지시_로그.md` BT5-Dev 행 2단계 v0.2 반영
- **EditMode 테스트**: `Assets/Tests/Editor/PlayerAttackTests.cs` (8종) + `EerieVillage.Tests.Editor.asmdef`