# 05. PlayerTestGirl 아틀라스 적용 구현 보고

**작성일**: 2026-04-24
**집행**: 개발팀장 Agent (단일 PM 세션)
**PD 지시**: "캐릭터 리소스 교체 최종 집행" (2026-04-23~24)
**선행 맥락**: `04_BT5-Dev_2단계_구현보고.md` v0.2 (Player·Enemy Component Add 재위임) + PD `PlayerTestGirl.png` 수동 배치 (2026-04-22 23:47)

---

## 1. 결정 — B안 채택 근거

### 1.1 선택지
1. **A안**: 기존 Player.png 시리즈(Idle·Run 등 9종) 그대로 유지, 이미지 교체 없음
2. **B안 (채택)**: 기존 PlayerIdle.anim·PlayerRun.anim 의 m_PPtrCurves 만 PlayerTestGirl 상단 4프레임으로 교체 + PlayerAttack.anim 신설
3. **C안 (기각)**: PlayerIdle·PlayerRun.anim 통합 후 State Machine 재편 — 회귀 리스크 과다

### 1.2 B안 선택 근거
- 기존 Player.controller State Machine 보존 → Idle/Run/Jump/Land/Hurt/Death 전환 로직 미변경
- m_PPtrCurves 단순 교체로 회귀 범위 최소
- Attack 은 독립 State (Trigger 기반 AnyState→Attack) 신설로 기존 경로 간섭 없음
- C11(코드 구조 직관성): 다음 개발자가 읽었을 때 "Idle/Run 애니메이션이 PlayerTestGirl 로 교체됨 + Attack 추가" 로 명료

### 1.3 기각안 (P24 필수)
- **A안 기각**: PD 지시 본문 "해당 이미지로 아틀라스 구성 + 애니메이션 교체" — 명시적 교체 요구
- **C안 기각**: State Machine 재편은 범위 과다, Play 모드 검증 없이 commit 시 회귀 위험 과다

---

## 2. 집행 내역

### 2.1 Sprite Slice (재생성)
| 항목 | 값 |
|------|----|
| 파일 | `Assets/Character/Sprites/PlayerTestGirl.png.meta` |
| guid | `44ad58ba82191ca4d818108ab01d3baa` (기존 자동 import 결과 유지) |
| spriteMode | 2 (Multiple) |
| 해상도 | 1536×1024 |
| Grid | 4열 × 2행 = 8 sprite |
| 셀 크기 | 384 × 512 |
| sprite 명명 | `PlayerTestGirl_0` ~ `PlayerTestGirl_7` |
| pivot | (0.5, 0.5) center, pivot field (0, 0) → alignment 0 + rect 내부 계산 |
| pixelsPerUnit | 100 |
| textureType | Sprite (8) |
| spriteMeshType | 1 (Tight) |

**내용 매핑**:
- sprite 0~3 (1행, y=512): walk 애니메이션 프레임 1~4 (검 든 채 걷기)
- sprite 4~7 (2행, y=0): attack 애니메이션 프레임 1~4 (검 올리기→찌르기→검기→마무리)

**이전 meta 이슈 (재생성 사유)**:
- 기존 meta (Apr 23 00:36 Unity auto-import 생성) 는 9 sprite 로 auto-slice 되어 있었고 rect 좌표가 임의적 (예: x:96 y:580 width:223 height:305)
- 4x2 일괄 grid 가 아닌 내용 기반 auto-detection 결과
- PD 요구 대로 균일 grid 로 재생성 필요 → guid·internalID 는 유지 (prefab·anim 참조 안정)

### 2.2 AnimationClip 교체 (방식: 기존 파일 전면 재작성)

| 파일 | 기존 | 신규 |
|------|------|------|
| `PlayerIdle.anim` | PlayerIdle.png 38프레임 loop (3.17s) | PlayerTestGirl sprite 0~3 4프레임 loop (0.4s, 10fps) |
| `PlayerRun.anim` | PlayerRun.png 29프레임 loop (0.60s) | PlayerTestGirl sprite 0~3 4프레임 loop (0.25s, 16fps) |
| `PlayerAttack.anim` | **신규** | PlayerTestGirl sprite 4~7 4프레임 **non-loop** (0.48s, 12fps) |

**PlayerAttack.anim guid**: `c8d7e5a1f9b24e63a7f5d2c8e1b9a4f7` (기존 42개 guid 와 충돌 없음, grep 검증 완료)

**SampleRate 차등 근거**:
- Idle 10fps: 대기 모션 느긋
- Run 16fps: 이동 모션 빠름 (기존 27fps에서 감속, 4프레임 특성상 조정)
- Attack 12fps: 중간 속도, PlayerController.attackCooldown 0.5s 내 완결 (0.48s)

### 2.3 Player.controller 수정
1. **신규 파라미터**: `attack` Trigger (m_Type: 9) — 총 7개 파라미터 (기존 6개 + attack)
2. **신규 State**: `Player-Attack` (fileID 1102700000000000001)
   - m_Motion: PlayerAttack.anim (guid c8d7e5a1f9b24e63a7f5d2c8e1b9a4f7)
   - position: (624, -420, 0)
3. **신규 AnyState Transition**: fileID 1101700000000000001
   - 조건: attack Trigger → Player-Attack
   - m_HasExitTime: 0 (즉시 전환)
   - m_TransitionDuration: 0
4. **신규 Exit Transition**: fileID 1101700000000000002
   - Player-Attack → Player-Idle (기본 복귀)
   - m_ExitTime: 1 (애니메이션 끝난 후)
   - 조건: 없음 (unconditional)

### 2.4 Player.prefab
- SpriteRenderer `m_Sprite`: PlayerIdle (fileID 21300020) → PlayerTestGirl_0 (fileID 7882920275377484039, guid 44ad58ba82191ca4d818108ab01d3baa)
- 런타임에는 Animator Controller 가 덮어쓰므로 미학 기본값만 교체

### 2.5 EditMode 테스트 신규 2건
1. **`Player_Prefab_SpriteRenderer_References_PlayerTestGirl`**: Player.prefab YAML Regex 파싱으로 m_Sprite guid 가 `44ad58ba82191ca4d818108ab01d3baa` 와 일치 검증
2. **`Player_Controller_Has_Attack_Parameter_And_State`**: Player.controller YAML Regex 파싱으로 `attack` Trigger(m_Type:9) + Player-Attack State 존재 검증

**기존 8개 + 신규 2개 = 총 10개 EditMode 테스트**.

---

## 3. C6-1 백업 (5종)
백업 timestamp: **`20260424_0003`**.

| 원본 | 백업 |
|------|------|
| `Assets/Character/Sprites/PlayerTestGirl.png.meta` | `PlayerTestGirl.png.meta.bak_20260424_0003.meta` |
| `Assets/Character/Animations/PlayerIdle.anim` | `PlayerIdle.anim.bak_20260424_0003.anim` |
| `Assets/Character/Animations/PlayerRun.anim` | `PlayerRun.anim.bak_20260424_0003.anim` |
| `Assets/Character/Animations/Player.controller` | `Player.controller.bak_20260424_0003.controller` |
| `Assets/Prefabs/Player.prefab` | `Player.prefab.bak_20260424_0003.prefab` |

롤백 절차: 백업 파일명에서 `.bak_20260424_0003` 제거하여 덮어쓰기.

---

## 4. PD 수동 작업 — 최소화 (Play 검증 1회)

### 4.1 이상적 시나리오
1. Unity Editor 재실행
2. Asset import 자동 트리거 (meta·anim·controller YAML 변경 감지)
3. Play 버튼 → 캐릭터 walk/attack 애니메이션 확인

### 4.2 예상 시나리오 (안전 측)
1. Unity Editor 재실행
2. Asset import 확인 (Console에 import 오류 없는지)
3. `Window > General > Test Runner` → EditMode → **10 tests all green** 확인
4. Play 버튼 → walk 4프레임·attack 4프레임 표시 확인
5. 문제 발견 시 즉시 보고 → 개발팀 세션 재호출

### 4.3 런타임 검증 한계 (C23 진실)
- PM 세션에서 Unity Play 모드 실행 **불가**
- EditMode 테스트로 **YAML 구조 정합성**까지만 검증
- 시각적 애니메이션 재생·Trigger 발동·공격 판정은 PD Play 검증 필수

---

## 5. 이전 오류 재발 방지 체크리스트 (PM 요청)

| 체크 항목 | 이전 실패 | 금차 이행 |
|----------|----------|----------|
| **리소스 실물 Read(이미지) 시각 확인 선행** | 파일명 매칭만으로 판단 | PlayerTestGirl.png Read 후 보라머리·파란옷·검 든 캐릭터 **직접 확인** → 4x2 8 sprite 구성 현장 확인 |
| **전수 ls (head·tail 자르기 금지)** | `head -20` 으로 파일 스캔 | `ls -la "Assets/Character/Sprites/"` 전수 — PlayerTestGirl.png.meta 존재 (Apr 23 00:36) 발견 |
| **기존 meta Read 후 guid·구조 재사용** | 신규 meta 작성 시 기존 자동 import 결과 무시 | 기존 meta Read → guid `44ad58ba82191ca4d818108ab01d3baa` + internalID 8개 재활용 |
| **guid 충돌 검증** | 충돌 가능성 방치 | `grep -hoE "guid: [a-f0-9]{32}"` 로 42개 기존 guid 수집 + 신규 후보 `c8d7e5a1f9b24e63a7f5d2c8e1b9a4f7` grep 0건 확인 |
| **C6-1 백업 5종** | 3종 이하 | meta·Idle.anim·Run.anim·controller·prefab 5종 백업 |

---

## 6. 향후 후속 작업 제안

### 6.1 PD Play 검증 결과에 따른 분기
- **정상 동작**: 본 05 보고서 확정 + BT5-Dev 3단계 완결 아카이브
- **import 오류**: 개발팀 재위임 + Unity Console 로그 PD 전달
- **애니메이션 재생 이상**: m_PPtrCurves fileID·guid 재검증 (fileID 부호 포함 전달 확인)

### 6.2 기획팀 선행 작업 재합류 (기획팀 Agent 영역)
- PlayerTestGirl 애니메이션 4프레임으로 충분한지 기획팀 재미 판단 (P30)
- 8프레임·16프레임 확장 시 아틀라스 재발주 여부

### 6.3 다른 Player 애니메이션 (Jump·Land·Hurt·Death·Spawn·Victory)
- PlayerTestGirl 아틀라스에 대응 프레임 부재 → 현 시점 **기존 Player*.png 유지**
- 기획팀 캐릭터 교체 완전성 요구 시 추가 아틀라스 발주 (본 05 범위 외)

---

## 7. 참조
- 기획: `기획/04_전투_기본_스펙.md` (공격 마우스 좌, i-frame 0.6s)
- 선행: `개발/04_BT5-Dev_2단계_구현보고.md` v0.2
- feedback: `memory/org/feedback_pm_image_verification_skip.md` (본 작업 부산 신설)
- feedback: `memory/org/feedback_pm_dev_task_delegation_failure.md` (3회차 append)