NerdNavis_AiDev
/
BurningTimesAi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
BurningTimesAi/프로젝트/EerieVillage/개발/04_BT5-Dev_2단계_구현보고.md

12 KiB
Raw Blame History

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단계 완료 갱신