17 KiB

Raw Blame History

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 편집으로 해결 (본 세션 완결)

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

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

Play 모드 런타임 검증 — 이동·점프·공격·i-frame 실제 동작, 적 밸런싱
Animator Controller에 attack trigger 파라미터 추가 (선택, 정적 스프라이트로는 불요)
AttackHitbox 컴포넌트 Player GameObject에 부착 — PlayerController의 attackHitbox 필드는 Awake에서 GetComponent<AttackHitbox>() 자동 시도하므로, Player GameObject에 AttackHitbox 컴포넌트를 추가만 하면 자동 연결. Player.prefab YAML에 컴포넌트 직접 추가도 가능하나 MonoBehaviour script reference guid 관리 복잡도로 Editor GUI 권장
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건:

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 재지시로 번복 직접 수행:

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)
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 레포에 변경이 관찰됨:

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

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

7. 기각안

~~"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회차 실증
"Animator Controller YAML에 attack trigger + state 직접 추가" — 기각 유지. Animator Controller의 StateMachine·Transition·Parameter는 fileID 참조가 복잡. 잘못 편집하면 기존 7종 애니메이션 체인 깨짐. 정적 스프라이트 허용 범위(PD 원문)에서 불요. SetTrigger("attack")은 미존재 파라미터여도 no-op (Unity API 보장). 아트 리소스 생성 후 Phase 3-B에서 일괄 처리
"Mr.Alien.png 자산 삭제" — 기각 유지. 아직 참조 관계 파악 중이며, 다른 Prefab·Scene에서 참조될 가능성. C6 원본 보호 원칙 준수 — 자산 삭제 대신 참조만 교체
"정적 스프라이트 대신 새 공격 애니메이션 생성" — 기각 유지. 공격 스프라이트 리소스 부재. Phase 3-B 이후 narrative-designer 조선 퇴마 테마 아트 발주 시 일괄 생성
"PlayerEnemyCollision에서 Bounce 남겨두기" — 기각 유지. "위에서 밟기" 의도와 결합된 로직. i-frame 체계에서는 불필요하고 물리적 예측 불가 거동 유발
"EditMode 테스트 대신 PlayMode 테스트로 통합 검증" — 기각 (v0.2 신설). PlayMode 테스트는 실제 Play 모드 진입이 필요하며 Animator·Physics·InputSystem 런타임 의존성 발생. Prefab 컴포넌트 구성 자체는 AssetDatabase로 Play 없이 검증 가능 → EditMode 선택이 회귀 방지에 더 강력(이전 상태로 rollback 돼도 Editor가 즉시 검출)
"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

17 KiB Raw Blame History Unescape Escape