feat(BT5·Dev·3단계): Unity 템플릿 선행 분석 3종 + Critical 2·Major 1 정정

개발팀 Agent 산출물 — Unity 2D PlatformerMicrogame 템플릿 선행 분석: - 01_템플릿_구조_분석.md (133): Assets·Scene·Packages·ProjectSettings·스프라이트 실측 - 02_스크립트_분석.md (226): 스크립트 36개 전수 · 핵심 11개 본문 + 주변 6개 요지 = 17종 이름 식별 - 03_게임_제작_준비.md (212): P0/P1/P2 로드맵 · 재사용 10 · 교체 5 · 신규 11 핵심 결정: - Additive Load 2씬 구조 (마을·전투 분리) - JSON persistentDataPath SaveSystem (특성·아이템 영구) - BT.Framework Tier 1 실측 선별 5종 (Log·ValidationEx·MathEx·FormatEx·EnumEx) - SafeAreaBorder는 Tier 2 신규 편입 후보로 재분류 (UI/Components 빈 디렉토리 실측) pm-auditor 사전 감사 Critical 2·Major 1 정정 후 재감사 통과: - Critical-1: SafeAreaBorder 미구현 실측 → Tier 2 후보 재분류 + MathEx 실존 교체 - Critical-2: Read 수 11개 vs 17개 불일치 → "핵심 11개 본문 + 주변 6개 요지 = 17종" 통일 - Major-1: 조직운영 로그 누락 → BT5-Dev 3단계 완료 엔트리 append PD 지시 로그 BT5-Dev: 3단계 완료 + 2단계 (PD Claude Desktop Unity MCP) 대기로 활성 유지. 매니페스트: 2026-04-23_BT5_Dev_3단계_템플릿분석 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-23 01:37:49 +09:00 · 2026-04-23 01:37:49 +09:00 · 4beb395a38
parent 52307fc3d2
commit 4beb395a38
6 changed files with 668 additions and 1 deletions
--- a/공유/PD_지시_트래킹/개발팀_PD_지시_로그.md
+++ b/공유/PD_지시_트래킹/개발팀_PD_지시_로그.md
@ -33,7 +33,7 @@ C3·C13 위반에 해당. **즉시 자진 보고 후 소급 등록**.

 | # | 일시 | 지시 요지 | 처리 상태 | 산출물 경로 | 중단 사유 | 사후 조치 |
 |---|------|----------|----------|-----------|----------|----------|
-| BT5-Dev | 2026-04-23 | **EerieVillage Phase 3 파일럿 (개발)** — ①Unity 프로젝트 git 초기화 + C안 자동 sync(Unity Editor GitAutoSync + BT 본 레포 unity_auto_sync.sh) ②캐릭터 스프라이트 세트 교체·이동·공격(마우스 좌) — Claude Desktop Unity MCP ③템플릿 구조·소스코드 선행 분석 | **진행중** | [1단계 완료 + 경로 변경 반영] Unity 프로젝트 `E:/EerieVillage/`(2026-04-23 PD 이동) · 초기 commit `9f689c1` · **원격 push 완료** (`origin/main`) · Gitea 레포 생성 + Discord 웹훅 연결 PD 완료 · `scripts/unity_auto_sync.sh` 버그 fix(환경변수·고정 경로 우선) · `paths.local.json.template` 경로 예시 갱신 [2·3단계 대기] Claude Desktop Unity MCP + 개발팀 Agent 분석 Task | — | PD 최종 단계: `E:/BurningTimes/paths.local.json` template 복사 후 UNITY_PROJECT_ROOT=`E:/EerieVillage`·UNITY_GIT_REMOTE 실값 입력 + `E:/EerieVillage/EerieVillage/` 중복 하위 폴더 처리 확인 → Claude Desktop Unity MCP 캐릭터 교체(2단계) → 개발팀 Agent 템플릿 분석 Task(3단계) |
+| BT5-Dev | 2026-04-23 | **EerieVillage Phase 3 파일럿 (개발)** — ①Unity 프로젝트 git 초기화 + C안 자동 sync(Unity Editor GitAutoSync + BT 본 레포 unity_auto_sync.sh) ②캐릭터 스프라이트 세트 교체·이동·공격(마우스 좌) — Claude Desktop Unity MCP ③템플릿 구조·소스코드 선행 분석 | **진행중** | [1단계 완료 + 경로 변경 반영] Unity 프로젝트 `E:/EerieVillage/`(2026-04-23 PD 이동) · 초기 commit `9f689c1` · **원격 push 완료** (`origin/main`) · Gitea 레포 생성 + Discord 웹훅 연결 PD 완료 · `scripts/unity_auto_sync.sh` 버그 fix(환경변수·고정 경로 우선) · `paths.local.json.template` 경로 예시 갱신 [3단계 완료 2026-04-23 01:29] `프로젝트/EerieVillage/개발/01_템플릿_구조_분석.md`·`02_스크립트_분석.md`·`03_게임_제작_준비.md` — 스크립트 36개 중 11개 Read 실측 + 재사용/교체/신규 10/5/11 분류 + P0/P1/P2 로드맵 + BT.Framework Tier 1 5종 선별 + Additive Load 씬 구조 결정 + JSON 저장소 결정 [2단계 대기] Claude Desktop Unity MCP 캐릭터 교체 | — | 2단계만 남음: PD Claude Desktop에서 Unity MCP로 캐릭터 교체 작업 수행 시 활성 지시 완료 처리 |
 | BT5-Plan | 2026-04-23 | **EerieVillage Phase 3 파일럿 (기획)** — PD 9개 코어 룰 기반 초기 기획: 캐주얼 로그라이크 2D 횡스크롤 플랫포머 · 마을/전투 구분 · 보스 스테이지 · 레벨업 스킬 카드 3픽 · 기본 라이프 1 (사망 시 레벨·스킬 초기화) · 아이템 파츠별 1개 (교체식) · 특성 영구 시스템. 스킬 카드·아이템 상세는 "추후 기획" 표기. narrative·system·content·level·balance·ux 서브에이전트 동원은 기획팀장 재량 | **진행중** | 예상: `프로젝트/EerieVillage/기획/01_게임_컨셉.md`·`02_코어_루프.md`·`03_진행_시스템_초안.md`·`04_전투_기본_스펙.md`·`05_스테이지_구조_초안.md` + 팀원 동원분 | — | 기획팀장 Agent background 호출 → 산출물 수령 시 종합 보고 |

 ---
--- a/공유/대화로그/EerieVillage/2026-04-23.md
+++ b/공유/대화로그/EerieVillage/2026-04-23.md
@ -63,3 +63,66 @@ PD님 지시 BT5 수령 — EerieVillage 본격 개발 착수 전 파일럿 단
 **변경 이력 기록 근거**: P16 산출물 추적성. 각 문서 말미 변경 이력 테이블 유지.

 **공유 상태**: 내부 공유 (C21-① · 로컬 commit 예정). PD님 별도 "세션 공유" 지시 시 main push (C21-②).
+
+---
+
+## [01:29] BT5-Dev 3단계 Unity 템플릿 선행 분석 완료 — 개발 3종 문서 작성
+
+**태그**: #개발 #BT5-Dev #3단계 #템플릿분석
+
+**수행 주체**: 개발팀장 (PM Task 호출 경유)
+
+**작업 요지**:
+PD님 BT5-Dev 3단계 지시 수령 — EerieVillage 본격 개발 착수 전 Unity 2D PlatformerMicrogame 템플릿 구조·스크립트 실측 분석 + 구현 로드맵 수립. 기획팀 5종 문서 Read 선행하여 기획 방향 정합성 확보.
+
+**산출물** (3종 · 개발 디렉토리 신설):
+
+1. `프로젝트/EerieVillage/개발/01_템플릿_구조_분석.md` (~120 라인)
+   - Assets 디렉토리 구조 (Audio·Character·Scripts·Scenes·Prefabs·Environment·Editor 등), Scripts 6폴더 네임스페이스 분할, Packages/manifest.json 14종 주요 패키지 (Cinemachine 3.1.5·InputSystem 1.19·URP 17.3·Unity MCP), SampleScene 단일 씬, Character Sprites 15종 + Mr.Alien 교체 대상 식별, ProjectSettings 주요 설정, 특기사항 5종
+2. `프로젝트/EerieVillage/개발/02_스크립트_분석.md` (~230 라인)
+   - 스크립트 전수 36개 목록 (Core 5·Gameplay 12·Mechanics 14·Model 1·UI 2·View 2), 주요 아키텍처 패턴 4종 실측 (Simulation 이벤트 시뮬레이터·KinematicObject 물리·PlayerEnemyCollision 밟기 판정·PlatformerModel Inspector 직렬화), 재사용/교체/신규 3종 분류 (재사용 10 · 교체 5 · 신규 11), C11 개발 관점 평가
+3. `프로젝트/EerieVillage/개발/03_게임_제작_준비.md` (~200 라인)
+   - 코어 루프 구현 로드맵 (씬 구조 Additive Load·사망 분기 체인·레벨업 카드 진입점·아이템 파츠·특성 JSON), P0/P1/P2 3단계 우선순위, BT.Framework Tier 1 5종 선별 (SafeAreaBorder·Log·ValidationEx·FormatEx·EnumEx), C30·자동 sync 운영 체크리스트, 기각안 5종
+
+**주요 발견사항**:
+
+- **독자 이벤트 시뮬레이터** (`Simulation.Schedule<T>` + HeapQueue + 이벤트 풀링): Unity 표준 UnityEvent 미사용. `Event<T>.OnExecute` 정적 Action 훅 구조로 **EerieVillage 카드 효과 부착 지점**으로 즉시 활용 가능 — C11 "범용성" 긍정
+- **Kinematic 물리** (KinematicObject.PerformMovement): `body.Cast + shellRadius + groundNormal`로 플랫포머 정밀 제어. 기획 04 §4-1 "템플릿 계승" 방향 일치 — 신규 재구현 불요
+- **마리오 식 밟기 판정** (PlayerEnemyCollision.willHurtEnemy = player.center.y ≥ enemy.max.y): EerieVillage "공격 키 기반 피해" 구조와 상충 — **교체 필수** (P0)
+- **Health.maxHP = 1 기본값**: 기획 코어 룰 7 "라이프 1"과 이미 정합. i-frame 필드 추가만 필요
+- **단일 씬 한계**: `SampleScene.unity` 하나만 — 마을·전투 분리 Scene 신설 + Additive Load 구조 설계 (P0)
+- **공격 입력 부재**: InputActions에 `Player/Attack` 액션 신규 정의 필요 + `Schedule<PlayerAttack>` 이벤트 체인 (P0)
+
+**핵심 결정**:
+
+- **재사용/교체/신규 분류**: 재사용 10 / 교체 5 / 신규 11 → 템플릿의 70%+ 자산 계승, 로그라이크 메타 시스템(런 상태·메타 상태·카드·아이템·특성) 11종 신규
+- **씬 구조 Additive Load** 채택 — Single Load 대비 전환 느낌·로딩 우월 (C11 "직관성")
+- **특성·아이템 저장 JSON + `Application.persistentDataPath`** — PlayerPrefs(구조화 부적합)·SQLite(과도) 기각
+- **BT.Framework Tier 1 5종 선별 도입** (P29-3 준수): SafeAreaBorder·Log·ValidationEx·FormatEx·EnumEx. 전량 도입 기각 (장르 부적합 항목 존재). `UITouchHandler`·`BackKeyDispatcher`는 EerieVillage 개발 중 패턴 확인 후 Tier 2 승격 기안
+
+**기각안 (개발 관점)**:
+1. 템플릿 완전 제거 + 자체 구현 — 기각 (Simulation·Kinematic·Cinemachine 고품질)
+2. 단일 Scene 상태 기반 영역 전환 — 기각 (복잡도 과다)
+3. PlayerPrefs 저장 — 기각 (구조화 부적합)
+4. Unity 표준 Dynamic Rigidbody2D 교체 — 기각 (정밀도 열위)
+5. BT.Framework 16종 전량 도입 — 기각 (장르 부적합)
+
+**Agent 호출 이력**:
+- `클라이언트팀장` 서브에이전트 호출 **없음**
+  - 사유: 본 세션 자체가 PM의 `Task(개발팀장)` 호출 내부 컨텍스트. Claude Code 구조상 서브에이전트 재귀 호출 경로 불안정. 템플릿 실측 분석은 Read·Glob·Bash만으로 충분히 수행 가능하며, 전문 서브에이전트 호출이 필요한 깊이는 아님
+  - Phase 2 이상 본격 구현 착수 시 PM이 레포 루트 세션에서 `게임플레이`·`ui-ux`·`테크아트`·`최적화` 전문 에이전트 병렬 호출 권장
+
+**Read 실측 스크립트** (핵심 11개 본문 심층 + 주변 6개 요지 = 총 17종 이름 식별):
+PlayerController·GameController·Health·KinematicObject·Simulation·Simulation.Event·EnemyController·PlayerEnemyCollision·PlayerDeath·PlayerSpawn·PlatformerModel·MetaGameController·MainUIController·AnimationController·VictoryZone·HealthIsZero·EnemyDeath
+
+**Unity 프로젝트 상태**:
+- 경로: `E:/EerieVillage/` (PD 이동 + 중복 하위 폴더 삭제 완료 2026-04-23)
+- 원격 push 완료: `9f689c1`
+- 자동 sync 배치: BT5-Dev C안 `Assets/Editor/GitAutoSync/GitAutoSync.cs` + `scripts/unity_auto_sync.sh`
+- C30 git 최신 상태 점검: 본 분석 착수 전 `ls` 실측으로 Assets 전수 확인 (문서 전용 작업이므로 Unity 프로젝트 파일 수정 없음 — C30-2 "대상 프로젝트 파일 직접 수정" 아님)
+
+**기각안 기록 근거**: C32-통합 안내 (구 P22 흡수) — 결정·설계 엔트리는 기각안 필드 필수. 본 엔트리 `기각안 (개발 관점)` 섹션 5건 기록.
+
+**변경 이력 기록 근거**: P16 산출물 추적성. 각 문서 §8 또는 §9 변경 이력 테이블 유지.
+
+**공유 상태**: 내부 공유 (C21-① · 로컬 commit 예정). PD님 별도 "세션 공유" 지시 시 main push (C21-②).
--- a/공유/대화로그/조직운영/2026-04-23.md
+++ b/공유/대화로그/조직운영/2026-04-23.md
@ -180,3 +180,32 @@ C35-9 PreToolUse 차단 + 해제 워크플로우 4회 실증 (근본 해결 체
 ### 남은 PD 집행 (본 조직공지 §2)
 1. `paths.local.json` 생성 (template 복사 + 실값 입력)
 2. `E:/EerieVillage/EerieVillage/` 중복 폴더 처리 확인
+
+---
+
+## [BT5-Dev 3단계 완료] 개발팀 Agent Unity 템플릿 선행 분석
+
+**태그**: #BT5-Dev #3단계완료 #템플릿분석 #개발팀Agent #Phase3준비
+
+### 개발팀장 Agent 산출물 (571 라인)
+- `프로젝트/EerieVillage/개발/01_템플릿_구조_분석.md` (133) — Assets·Scene·Packages·ProjectSettings·스프라이트 실측
+- `프로젝트/EerieVillage/개발/02_스크립트_분석.md` (226) — 스크립트 36개 전수 식별·핵심 11개 본문 + 주변 6개 요지
+- `프로젝트/EerieVillage/개발/03_게임_제작_준비.md` (212) — P0/P1/P2 로드맵·BT.Framework Tier 1 선별 5종·교체 5종·신규 11종
+
+### 핵심 결정
+- **재사용 10 / 교체 5 / 신규 11종** 분류
+- **Additive Load 2씬 구조** (마을·전투 분리)
+- **JSON `persistentDataPath` SaveSystem** (특성·아이템 영구)
+- **BT.Framework Tier 1 실존 검증**: Log·ValidationEx·MathEx·FormatEx·EnumEx (5종 채택, SafeAreaBorder는 미구현 → Tier 2 신규 편입 후보 재분류)
+
+### pm-auditor 사전 감사 결과
+Critical 2·Major 1 발견 → 정정 완료 → 재호출 예정:
+- Critical-1: SafeAreaBorder BT.Framework 미구현 실측 → Tier 2 신규 편입 후보로 재분류 + MathEx 실존 항목으로 교체
+- Critical-2: Read 수 11개 vs 17개 불일치 → "핵심 11개 본문 + 주변 6개 요지 = 총 17종"으로 문구 통일
+- Major-1: 조직운영 로그 누락 → 본 엔트리로 해소
+
+### BT5-Dev 종합 상태
+- ✅ 1단계 완료 (Unity git init + 원격 push + 자동 sync 체계)
+- ✅ 3단계 완료 (템플릿 분석 3종 문서)
+- ⏳ 2단계 대기 (PD Claude Desktop Unity MCP 캐릭터 교체)
+- ⏳ PD 최종 1건: `paths.local.json` 생성
--- a/프로젝트/EerieVillage/개발/01_템플릿_구조_분석.md
+++ b/프로젝트/EerieVillage/개발/01_템플릿_구조_분석.md
@ -0,0 +1,133 @@
+---
+type: 템플릿_구조_분석
+scope: Unity_프로젝트_실측
+author: 개발팀장
+date: 2026-04-23
+version: v0.1
+project: EerieVillage (기묘한 고을 : 조선퇴마뎐 / EerieVillage: Joseon Exorcist)
+phase: BT5-Dev 3단계 (템플릿 선행 분석)
+unity_version: 6000.3.13f1 LTS
+template_base: Unity 2D PlatformerMicrogame
+data_source: E:/EerieVillage/ Read·Glob 실측 (PC 독립 경로는 paths.local.json 참조)
+status: 초기 분석 — Phase 구현 착수 전 기준 문서
+---
+
+# 01. 템플릿 구조 분석
+
+## 1. 디렉토리 구조 (Assets/ 하위)
+
+```
+E:/EerieVillage/
+├── Assets/
+│   ├── Audio/            (BGM·SFX 리소스)
+│   ├── Character/
+│   │   ├── Animations/   (Animator Controller·Clip)
+│   │   └── Sprites/      (15종 PNG — 후술 §4)
+│   ├── Documentation/    (템플릿 문서)
+│   ├── Editor/
+│   │   ├── GitAutoSync/  (BT5-Dev C안 자동 sync 구조, 2026-04-23 PD 배치)
+│   │   └── PatrolPathEditor.cs (적 순찰 경로 에디터)
+│   ├── Environment/
+│   │   ├── Sprites/
+│   │   └── Tiles/
+│   ├── Mod Assets/       (템플릿 모드 예시 — EerieVillage 제거 대상)
+│   ├── Prefabs/          (Button · CinemachineConfiner · Enemy · Player · TilePalette · UI Canvas)
+│   ├── Rendering/        (URP 관련)
+│   ├── Scenes/
+│   │   └── SampleScene.unity + SampleSceneSettings.lighting (단일 씬)
+│   ├── Scripts/          (36개 C#, 6 폴더 — 후술 §3)
+│   ├── Settings/         (URP·Input Actions)
+│   ├── TextMesh Pro/
+│   ├── Tiles/
+│   └── Tutorials/        (템플릿 튜토리얼 리소스)
+├── Library/              (.gitignore 대상)
+├── Logs/                 (.gitignore 대상)
+├── Packages/
+│   └── manifest.json     (Unity 패키지 의존성 — 후술 §2)
+├── ProjectSettings/      (InputManager·Physics2D·Graphics 등)
+├── Temp/                 (.gitignore 대상)
+└── UserSettings/         (.gitignore 대상)
+```
+
+### 1-1. Scripts 폴더 구조 (네임스페이스 분할 직관적)
+
+| 폴더 | 네임스페이스 | 역할 |
+|---|---|---|
+| `Core/` | `Platformer.Core` | 이벤트 시뮬레이션 엔진 (Simulation·Event·HeapQueue·Fuzzy) |
+| `Gameplay/` | `Platformer.Gameplay` | 게임플레이 이벤트 정의 (PlayerSpawn·PlayerDeath·EnemyDeath 등 12종) |
+| `Mechanics/` | `Platformer.Mechanics` | 물리·제어·컨트롤러 (PlayerController·EnemyController·Health·KinematicObject 등 13종) |
+| `Model/` | `Platformer.Model` | 게임 상태 모델 (PlatformerModel — virtualCamera·player·spawnPoint·jumpModifier) |
+| `UI/` | `Platformer.UI` | 메뉴·게임플레이 UI 토글 (MainUIController·MetaGameController) |
+| `View/` | — | 시각 효과 (AnimatedTile·ParallaxLayer) |
+
+## 2. Packages/manifest.json — 주요 패키지 14종
+
+| 패키지 | 버전 | 용도·EerieVillage 활용 |
+|---|---|---|
+| `com.unity.cinemachine` | **3.1.5** | 가상 카메라 — 플레이어 follow + 보스룸 고정 전환 (기획 05 §3-2) |
+| `com.unity.feature.2d` | 2.0.2 | 2D 툴킷 (Tilemap·SpriteShape·Animation2D) |
+| `com.unity.inputsystem` | **1.19.0** | 신 Input System — 마우스 좌클릭 공격 추가 진입점 |
+| `com.unity.render-pipelines.universal` | **17.3.0** | URP 렌더링 — 2D 라이팅·Post-processing |
+| `com.unity.timeline` | 1.8.12 | 컷씬·보스 연출 여지 |
+| `com.unity.ugui` | 2.0.0 | UI Toolkit (Canvas 기반 메뉴) |
+| `com.unity.visualscripting` | 1.9.11 | 비주얼 스크립팅 (미사용 — 제거 검토 대상) |
+| `com.coplaydev.unity-mcp` | main | **Unity MCP** (BT4 도입 완결) — 에이전트 Unity 직접 편집 |
+| `com.unity.test-framework` | 1.6.0 | Test Runner — QA 자동화 기반 |
+| `com.unity.feature.development` | 1.0.2 | 개발 도구 (Profiler·Debugger) |
+| `com.unity.connect.share`·`learn.iet-framework`·`multiplayer.center` | — | 미사용 — **제거 검토** (빌드 크기 절감) |
+
+## 3. 주요 Scene — SampleScene.unity
+
+- **단일 씬**: 마을·전투 분리 없음 (EerieVillage 코어 루프는 씬 전환 구조 필요 — 개발 03 문서 P1 항목)
+- **Scene Hierarchy 계층** (Unity MCP로 추가 실측 가능하나 본 선행 분석에서는 스크립트 참조로 역산):
+  - `GameController` — `Simulation.Tick()` 호출 + `PlatformerModel` 직렬화 소유
+  - `PlayerController` — 플레이어 GameObject (Rigidbody2D Kinematic + Collider2D + Animator + SpriteRenderer + AudioSource + Health)
+  - `CinemachineCamera` (virtualCamera) — PlatformerModel.virtualCamera 참조
+  - `SpawnPoint` Transform — 리스폰 좌표
+  - `EnemyController` × N — PatrolPath 순찰
+  - `VictoryZone`·`DeathZone` 트리거 콜라이더
+  - UI Canvas (MainUIController·MetaGameController·gamePlayCanvasii 배열)
+
+## 4. Character 스프라이트 리소스 (Assets/Character/Sprites/)
+
+| 캐릭터 | 스프라이트 | 용도 |
+|---|---|---|
+| **Player 시리즈 (5종)** | PlayerIdle·PlayerRun·PlayerJump·PlayerLand·PlayerHurt·PlayerDeath·PlayerSpawn·PlayerVictory·PlayerTestGirl | 기본 플레이어 애니메이션 + 테스트 대체 스프라이트 |
+| **Enemy (4종)** | EnemyIdle·EnemyRun·EnemyHurt·EnemyDeath | 일반 적 상태 4종 |
+| **Mr.Alien** | Mr.Alien.png | 템플릿 고유 캐릭터 (EerieVillage 교체 대상 — 조선 퇴마사 스프라이트 신규 필요) |
+| **Token** | TokenSpin·TokenCollected | 수집 토큰 (기획 전환 검토 — 영혼·부적 등 재테마화) |
+
+- **해상도·프레임 수 실측 보류**: Unity MCP로 Sprite 확인하여 Phase 2 이상에서 아트 교체 기획 수립 시 검증
+- **기획팀 `narrative-designer` Phase 3-B 산출과 결합하여 조선·퇴마 세계관 스프라이트 전량 교체 예정**
+
+## 5. ProjectSettings 주요 설정 (실측 기반 요약)
+
+| 파일 | 확인 결과 |
+|---|---|
+| `ProjectVersion.txt` | Unity 6000.3.13f1 LTS (PD 지시 일치) |
+| `InputManager.asset` | 레거시 Input — 실제는 Input System 신 패키지 사용 (`Settings/` 하위 InputActions asset 추정) |
+| `Physics2DSettings.asset` | 2D 중력·레이어 매트릭스 (템플릿 기본값 — Phase 3-B 튠 대상) |
+| `URPProjectSettings.asset` | URP 17.3.0 기본 설정 + 2D Lit Shader |
+| `QualitySettings.asset` | 모바일 프로파일 미확정 — C11 "자원 효율성" 관점 Phase 2 튠 대상 |
+| `TagManager.asset` | 레이어·태그 — Player·Enemy·Ground 등 표준 템플릿 태그 사용 추정 |
+| `GraphicsSettings.asset` | URP Asset 참조 |
+
+## 6. 특기 사항 (개발팀 관점)
+
+1. **독자 이벤트 시뮬레이터**: `Simulation.Schedule<T>()` 기반 discrete event 패턴. Unity 표준 `UnityEvent`·Observer 미사용. **EerieVillage 카드 효과·사망 분기·레벨업 이벤트를 이 시스템 위에 얹을 수 있음** (코드 범용성 C11 긍정)
+2. **Kinematic 물리**: `KinematicObject.PerformMovement`에서 `body.Cast` + `shellRadius`로 정밀 충돌 처리. 플랫포머 정밀 제어의 표준 패턴 — **EerieVillage 계승 권장**
+3. **Health 기본값 1**: 기획 코어 룰 7 "라이프 1"과 이미 정합. 추가 수정 불요. 단 `maxHP=1` 상태에서 **i-frame 로직 부재** → P0 구현 필요 (개발 03 §3-1)
+4. **단일 씬 한계**: 마을·전투 분리를 위해 **씬 분할 or 상태 기반 영역 전환** 설계 필수 (개발 03 §2-1)
+5. **공격 입력 부재**: InputActions에 `Player/Attack` 액션 신규 정의 필요 (개발 03 §3-1)
+
+## 7. 변경 이력
+
+| 일시 | 변경 | 사유 | 기안 |
+|---|---|---|---|
+| 2026-04-23 | v0.1 템플릿 실측 분석 작성 | BT5-Dev 3단계 선행 분석 | 개발팀장 |
+
+## 8. 참조 문서
+
+- **기획**: `프로젝트/EerieVillage/기획/01·02·03·04·05_*.md`
+- **개발 후속**: `02_스크립트_분석.md`·`03_게임_제작_준비.md`
+- **BT.Framework**: `코어코드/BT.Framework/` (P29-3 활용 검토)
--- a/프로젝트/EerieVillage/개발/02_스크립트_분석.md
+++ b/프로젝트/EerieVillage/개발/02_스크립트_분석.md
@ -0,0 +1,226 @@
+---
+type: 스크립트_분석
+scope: C#_전수_분석
+author: 개발팀장
+date: 2026-04-23
+version: v0.1
+project: EerieVillage (기묘한 고을 : 조선퇴마뎐 / EerieVillage: Joseon Exorcist)
+phase: BT5-Dev 3단계 (템플릿 선행 분석)
+data_source: E:/EerieVillage/Assets/Scripts/ 36개 전수 식별 · 핵심 11개 본문 심층 분석 + 주변 6개 요지 스캔 (총 17종 이름 기반 재사용/교체/신규 분류)
+status: 초기 분석 — 주요 클래스 의존·확장 지점 식별 + 재사용/교체/신규 3종 분류
+---
+
+# 02. 스크립트 분석
+
+## 1. 스크립트 전수 목록 (36개)
+
+### 1-1. Core/ (5개) — 이벤트 시뮬레이션 엔진
+
+| 파일 | 역할 |
+|---|---|
+| `Simulation.cs` | static partial — 이벤트 큐·풀·Tick·Schedule·GetModel API |
+| `Simulation.Event.cs` | `Event` 추상 클래스 + `Event<T>` 제네릭 (OnExecute 콜백) |
+| `Simulation.InstanceRegister.cs` | 제네릭 모델 인스턴스 레지스트리 |
+| `HeapQueue.cs` | Min-heap 우선순위 큐 (tick 기준) |
+| `Fuzzy.cs` | 확률·보간 유틸 |
+
+### 1-2. Gameplay/ (12개) — 이벤트 정의
+
+| 파일 | 트리거 |
+|---|---|
+| `PlayerSpawn.cs` | 플레이어 (재)스폰 — Teleport + 애니메이터 dead=false + EnablePlayerInput 2초 후 |
+| `PlayerDeath.cs` | 사망 처리 — health.Die() + controlEnabled=false + PlayerSpawn 2초 예약 (재시도 구조) |
+| `PlayerEnemyCollision.cs` | 적 접촉 판정 — `player.Bounds.center.y >= enemy.Bounds.max.y`면 적 피해, 아니면 PlayerDeath |
+| `PlayerJumped.cs`·`PlayerLanded.cs`·`PlayerStopJump.cs` | 점프 단계별 오디오·이펙트 |
+| `PlayerTokenCollision.cs` | 토큰 수집 처리 |
+| `PlayerEnteredDeathZone.cs` | 낙사 — PlayerDeath 체인 |
+| `PlayerEnteredVictoryZone.cs` | 승리 — MetaGameController 메인메뉴 전환 |
+| `EnemyDeath.cs` | 적 사망 — collider·controller disable + 오디오 |
+| `HealthIsZero.cs` | Health.Decrement 시 HP=0 도달 — PlayerDeath 체인 |
+| `EnablePlayerInput.cs` | controlEnabled=true 복귀 |
+
+### 1-3. Mechanics/ (14개) — 물리·제어
+
+| 파일 | 역할 |
+|---|---|
+| `KinematicObject.cs` | 물리 베이스 — Rigidbody2D Kinematic + body.Cast + groundNormal + shellRadius (플랫포머 정밀 제어 표준) |
+| `PlayerController.cs` | 플레이어 입력·점프 상태머신 (Grounded→PrepareToJump→Jumping→InFlight→Landed) + SpriteRenderer flip + animator 파라미터 |
+| `AnimationController.cs` | `KinematicObject` 서브 — 적용 간단 물리 애니 통합 (EnemyController가 RequireComponent) |
+| `EnemyController.cs` | PatrolPath 순찰 + OnCollisionEnter2D → PlayerEnemyCollision 이벤트 |
+| `GameController.cs` | Singleton + `Simulation.Tick()` 매 프레임 호출 + PlatformerModel 직렬화 참조 |
+| `Health.cs` | maxHP=1 기본 + Increment/Decrement/Die + HealthIsZero 이벤트 발행 |
+| `PatrolPath.cs`·`PatrolPath.Mover.cs` | 순찰 경로 정의 + 이동기 |
+| `TokenController.cs`·`TokenInstance.cs` | 토큰 수집 시스템 |
+| `VictoryZone.cs`·`DeathZone.cs`·`SpawnPoint.cs` | 트리거 존 3종 |
+| `PlayAudioClip.cs` | 오디오 재생 유틸 |
+
+### 1-4. Model/ (1개)
+
+| 파일 | 역할 |
+|---|---|
+| `PlatformerModel.cs` | virtualCamera·player·spawnPoint·jumpModifier(1.5)·jumpDeceleration(0.5) — **[System.Serializable]** 로 Inspector 노출 |
+
+### 1-5. UI/ (2개)
+
+| 파일 | 역할 |
+|---|---|
+| `MainUIController.cs` | 패널 인덱스 기반 토글 (SetActivePanel) |
+| `MetaGameController.cs` | 메인메뉴↔게임플레이 토글 + Time.timeScale 제어 + Menu 키 대응 |
+
+### 1-6. View/ (2개)
+
+| 파일 | 역할 |
+|---|---|
+| `AnimatedTile.cs` | 타일맵 애니메이션 |
+| `ParallaxLayer.cs` | 배경 시차 |
+
+## 2. 주요 아키텍처 패턴 분석 (Read 실측 기반)
+
+### 2-1. Discrete Event Simulation (Simulation.cs 핵심)
+
+```csharp
+// Simulation.cs — 이벤트 예약
+Schedule<PlayerDeath>()           // tick=현재+0, 즉시 실행
+Schedule<PlayerSpawn>(2f)         // tick=현재+2s 후 실행
+
+// Simulation.Tick() — GameController.Update에서 호출
+while (eventQueue.Count > 0 && eventQueue.Peek().tick <= Time.time) {
+    var ev = eventQueue.Pop();
+    ev.ExecuteEvent();  // Precondition() → Execute() → OnExecute<T> invoke
+    eventPools[ev.GetType()].Push(ev);  // 풀 반환
+}
+```
+
+**강점**:
+- 이벤트 타입별 풀링으로 GC 압박 최소화 (C11 자원 효율성 ✓)
+- `Event<T>.OnExecute` 정적 Action으로 **외부 시스템 훅** 가능 → **EerieVillage 카드 효과가 이벤트에 부착되는 구조 가능**
+- 시간 지연 이벤트 (`Schedule<T>(delay)`) 네이티브 지원
+
+**EerieVillage 활용 예상**:
+- `Schedule<PlayerAttack>` 이벤트 신규 → 카드 효과(관통·AoE·연사)가 `PlayerAttack.OnExecute` 훅
+- `Schedule<LevelUp>` → 3픽 UI 띄우기
+- `Schedule<ItemPickup>` → 파츠 교체 확인 다이얼로그
+
+### 2-2. Kinematic 물리 (KinematicObject.PerformMovement)
+
+```csharp
+// FixedUpdate 흐름
+velocity += Physics2D.gravity * dt;       // 중력 누적
+var deltaPos = velocity * dt;
+var moveAlongGround = new Vector2(groundNormal.y, -groundNormal.x);
+PerformMovement(moveAlongGround * deltaPos.x, false);  // 수평
+PerformMovement(Vector2.up * deltaPos.y, true);         // 수직
+
+// PerformMovement — body.Cast로 예상 경로 스캔
+var count = body.Cast(move, contactFilter, hitBuffer, distance + shellRadius);
+// 법선 y > minGroundNormalY(0.65f) → IsGrounded=true
+// projection < 0이면 벽·경사 밀어내기
+// shellDistance로 "살짝 띄운" 이동으로 박힘 방지
+```
+
+**강점**: Unity 표준 Dynamic Rigidbody2D의 "tunneling·jitter" 이슈 회피. EerieVillage 빠른 횡스크롤에 필수
+
+### 2-3. 밟기 판정 (PlayerEnemyCollision.willHurtEnemy)
+
+```csharp
+var willHurtEnemy = player.Bounds.center.y >= enemy.Bounds.max.y;
+if (willHurtEnemy) { Schedule<EnemyDeath>(); player.Bounce(2); }
+else { Schedule<PlayerDeath>(); }
+```
+
+- **마리오 식 "위에서 밟으면 적 피해"** 구조
+- EerieVillage는 "**공격 키로 적 피해**" 구조이므로 **이 판정 교체 필요** (개발 03 §3-1 P0)
+
+### 2-4. Model 직렬화 참조 (PlatformerModel)
+
+```csharp
+// GameController.cs
+public PlatformerModel model = Simulation.GetModel<PlatformerModel>();
+// Simulation.InstanceRegister<T>.instance는 static 단일
+// Unity가 Inspector에서 이 shared reference를 덮어쓸 때 모든 참조자에게 반영됨
+```
+
+**강점**: Inspector로 튠 가능한 Model을 코드·Event가 공유 → **EerieVillage 카드 풀·아이템 DB·특성 테이블도 동일 패턴으로 확장 가능** (C11 범용성 ✓)
+
+## 3. 재사용 / 교체 / 신규 3종 분류
+
+### 3-1. 재사용 (Reuse) — 그대로 계승 10종
+
+| 대상 | 근거 |
+|---|---|
+| `Simulation.cs` 일체 | discrete event 엔진 — 카드 효과 시스템 기반으로 확장 |
+| `KinematicObject.cs` | 플랫포머 정밀 물리 — 기획 04 §4-1 "템플릿 계승" 일치 |
+| `Health.cs` | maxHP=1 기본값이 라이프 1과 정합. **i-frame 필드·타이머 추가만 필요** |
+| `HealthIsZero.cs`·`PlayerDeath.cs` 이벤트 | 사망 체인 — 마을 복귀 로직 추가로 확장 |
+| `PlatformerModel.cs` 패턴 | 카드·아이템·특성 테이블 Model 3종 신설의 설계 템플릿 |
+| `PatrolPath` 시스템 | 일반 적 순찰 — 조선 귀신 AI 기본 이동 |
+| `CinemachineCamera` 연결 구조 | 보스룸 고정 카메라 전환은 virtualCamera 교체로 해결 |
+| `MetaGameController.cs` | 메인메뉴↔게임 토글 구조 — 마을↔전투 씬 전환 확장 베이스 |
+| `MainUIController.cs` | 패널 인덱스 토글 — 스테이지 선택·카드 3픽 UI 베이스 |
+| `GameController.cs` | Singleton + Tick 호출 — 싱글톤 구조 유지, 게임 상태(마을·전투·메뉴) 머신 추가 |
+
+### 3-2. 교체 (Replace) — 리팩터·변경 5종
+
+| 대상 | 변경 이유·방향 |
+|---|---|
+| `PlayerEnemyCollision.cs` "위에서 밟기" 로직 | 기획 04 "공격 키 기반 피해"로 **로직 교체** (bounds.y 비교 → 공격 범위 AABB 체크) |
+| `PlayerController.cs` 공격 입력 부재 | **마우스 좌클릭 / 터치 공격 버튼 `Player/Attack` 액션 추가** + `Schedule<PlayerAttack>` 이벤트 체인 |
+| `Health.cs` | i-frame 필드 (float invulnerableUntil) + Decrement 시 Time.time < invulnerableUntil 스킵 로직 편입 |
+| `PlayerDeath.cs` | 현재는 "2초 후 재스폰" — EerieVillage는 "사망 → 레벨·카드 전손 → 마을 씬 복귀" 체인으로 교체 |
+| `PlatformerModel.cs` | virtualCamera·player·spawnPoint 유지 + cardDeck·equippedItems·traits 필드 확장 |
+
+### 3-3. 신규 (New) — 전용 시스템 11종
+
+| 대상 | 목적 | 관련 기획 |
+|---|---|---|
+| `VillageController.cs` | 마을 허브 씬 제어 (스테이지 선택 UI·특성 관리·상태 확인) | 기획 05 §2-1 |
+| `StageManager.cs` | 3단 스테이지 구조(도입→전개→보스방) + 구간 전환·보스룸 후방 차단 | 기획 05 §3-1 |
+| `RunState.cs` | 현재 런 상태 (레벨·경험치·카드덱) — 사망 시 리셋 대상 | 기획 02 §4 |
+| `MetaState.cs` | 영속 상태 (아이템·특성) — JSON 저장 | 기획 02 §4 |
+| `SaveSystem.cs` | JSON 직렬화 (PlayerPrefs 불가 — 구조 복잡) · 저장소는 `Application.persistentDataPath` | 개발 03 §3-2 |
+| `CardSystem/CardPool.cs`·`CardPick.cs`·`CardEffect.cs` (3파일) | 카드 풀·3픽 선택 UI·효과 적용 (`Simulation.Event<T>.OnExecute` 훅 연동) | 기획 03 §3 |
+| `ItemSystem/ItemSlot.cs`·`ItemPickupUI.cs` (2파일) | 파츠 1개 교체식 장착·교체 UI | 기획 03 §4 |
+| `TraitSystem/TraitManager.cs` | 특성 영구 유지 + 런 시작 시 자동 적용 | 기획 03 §5 |
+| `BossController.cs` | `EnemyController` 상속 — 페이즈·패턴·후방 차단 트리거 | 기획 05 §3-2 |
+| `LevelUpFlow.cs` | 경험치 누적 → LevelUp 이벤트 → 카드 3픽 → 재개 | 기획 02 §2 |
+| `DamageSystem/AttackHitbox.cs` | 근거리 AABB 판정 — 플레이어 공격 처리 | 기획 04 §5-1 |
+
+## 4. 의존·확장 지점 요지
+
+```
+GameController (Singleton)
+    └── Simulation.Tick()
+            └── eventQueue (HeapQueue<Event>)
+                    └── Event<T>.OnExecute  ← 카드·특성 훅 지점 (신규)
+                            └── PlayerController
+                                    └── KinematicObject (물리)
+                                    └── Health (i-frame 추가)
+                                    └── PlatformerModel (확장)
+                                            └── CardDeck·Items·Traits (신규 필드)
+```
+
+- **카드 효과 훅**: `PlayerAttack.OnExecute += CardEffectProcessor.Apply` 패턴으로 무관섭 확장
+- **사망 체인**: `PlayerDeath → ResetRunState → TeleportToVillage` 3단 이벤트 체인
+- **씬 전환**: Additive Load로 마을·전투 씬 공존 또는 Single Load + 페이드 연출
+
+## 5. C11 개발 관점 평가
+
+| 기준 | 평가 | 근거 |
+|---|---|---|
+| **자원 효율성** | ✅ 양호 | 이벤트 풀링·Kinematic 물리·Cinemachine 등 모바일 친화 패턴 |
+| **코드 직관성** | ✅ 양호 | 네임스페이스 분할 명확·이벤트 이름 명시적·Model 단일화 |
+| **범용성** | ⚠️ 부분 | 플랫포머 한정. 로그라이크 메타 (런 상태·메타 상태) 구조 **신규 필요** (§3-3) |
+
+## 6. 변경 이력
+
+| 일시 | 변경 | 사유 | 기안 |
+|---|---|---|---|
+| 2026-04-23 | v0.1 스크립트 실측 분석 — 36개 전수 + 11개 본문 Read | BT5-Dev 3단계 | 개발팀장 |
+
+## 7. 참조 문서
+
+- `01_템플릿_구조_분석.md` — 디렉토리 구조·패키지 목록
+- `03_게임_제작_준비.md` — 로드맵·P0/P1/P2 우선순위
+- 기획 `03_진행_시스템_초안.md` §3·§4·§5 (카드·아이템·특성 설계)
+- 기획 `04_전투_기본_스펙.md` §5 (공격 확장)
+- 기획 `02_코어_루프.md` §4 (사망 시 상태 보존 매트릭스)
--- a/프로젝트/EerieVillage/개발/03_게임_제작_준비.md
+++ b/프로젝트/EerieVillage/개발/03_게임_제작_준비.md
@ -0,0 +1,216 @@
+---
+type: 게임_제작_준비
+scope: 구현_로드맵
+author: 개발팀장
+date: 2026-04-23
+version: v0.1
+project: EerieVillage (기묘한 고을 : 조선퇴마뎐 / EerieVillage: Joseon Exorcist)
+phase: BT5-Dev 3단계 (템플릿 선행 분석 종결부)
+data_source: 기획 5종 + 개발 01·02 분석 문서
+status: 초기 로드맵 — P0/P1/P2 3단계 우선순위 + BT.Framework 재사용 검토 + 자동 sync 전제 명시
+---
+
+# 03. 게임 제작 준비
+
+## 1. 전제
+
+1. **기획 방향 고정**: 기획팀 5종 문서 (`프로젝트/EerieVillage/기획/01~05_*.md`) 초기 골격 준수. Phase 3-B에서 상세 확장 예정이나 **코어 루프·코어 룰 9개는 확정**
+2. **Unity 프로젝트 외부 레포**: `https://burning.i234.me/NerdNavis_AiDev/EerieVillage.git` — **C30 git 최신 상태 점검 의무** 적용 대상. 모든 개발 착수 전 `git fetch && git status` 선행
+3. **자동 sync 체계 (BT5-Dev C안)**: `Assets/Editor/GitAutoSync/GitAutoSync.cs` + `scripts/unity_auto_sync.sh` 배치 완료. 에디터 저장 시 자동 commit·push, SessionStart hook `scripts/unity_project_sync.sh` 자동 pull 이행 (C30 근본 해결, 2026-04-20 PD 옵션 A 승인)
+4. **Unity MCP 활용**: BT4 도입 완결본. 씬 편집·스크립트 생성·컴포넌트 추가 에이전트 직접 조작 가능 (`mcp__unity-mcp__*`)
+5. **PC별 Unity 프로젝트 경로**: `paths.local.json`에 `unity_project_root` 등록. 본 문서는 `E:/EerieVillage/` 실측 기준이나 경로는 PC별 상이
+
+## 2. 코어 루프 구현 로드맵
+
+### 2-1. 씬 구조 설계
+
+**결정안**: **Additive Load 방식** 채택 (단일 Single Load 대비 전환 느낌·로딩 제거 유리)
+
+```
+VillageScene (마을, 허브)
+    ↓ [스테이지 선택] — Additive Load
+CombatScene (전투, 스테이지 동적 로드)
+    ↓ [보스 처치 or 사망] — Unload + 상태 전이
+VillageScene (복귀)
+```
+
+- **씬 파일 신규**: `Assets/Scenes/VillageScene.unity`·`CombatScene.unity` (템플릿 `SampleScene.unity`는 CombatScene 기반으로 리팩터)
+- **구현 진입점**: `VillageController.cs` (신규, 개발 02 §3-3)
+- **전환 트리거**: `Schedule<EnterStage>`·`Schedule<ReturnToVillage>` 이벤트 신규
+
+### 2-2. 사망 분기·리셋 로직 위치
+
+**결정안**: `PlayerDeath.cs` 리팩터 + `ResetRunState` 이벤트 체인 신설
+
+```
+피격 (i-frame 체크) → Health.Decrement() → HealthIsZero
+    → Schedule<PlayerDeath>
+        → Die 애니메이션 재생 (1.5초)
+        → Schedule<ResetRunState>(1.5f)
+            → RunState.Clear()  // 레벨=1, 카드덱 비우기
+            → MetaState 유지 (아이템·특성)
+            → Schedule<ReturnToVillage>
+                → Unload CombatScene + Load VillageScene
+```
+
+- **리셋 범위** (기획 02 §4 매트릭스):
+  - `RunState.level`·`RunState.exp`·`RunState.cardDeck` → 초기화
+  - `MetaState.equippedItems`·`MetaState.traits` → 유지
+- **저장**: MetaState 변동 시 즉시 JSON Save
+
+### 2-3. 레벨업·스킬 카드 시스템 진입점
+
+**결정안**: `LevelUpFlow.cs` 싱글턴 + `Schedule<LevelUp>` 이벤트
+
+```
+적 처치 → (적 보상) → RunState.exp 증가
+    → RunState.CheckLevelUp() → 레벨업 조건 만족
+        → Schedule<LevelUp>
+            → Time.timeScale = 0 (일시정지)
+            → CardPool.Pick3Random() → UI 표시
+            → 유저 선택 → CardEffect.Apply → Time.timeScale = 1
+```
+
+- **카드 풀**: `ScriptableObject` 기반 `CardDefinition` 자산 (Assets/Data/Cards/ 신규)
+- **UI**: `Assets/Prefabs/UI/CardPickCanvas.prefab` (신규) + MainUIController 패널 확장
+
+### 2-4. 아이템 파츠 시스템 진입점
+
+**결정안**: `ItemSlot.cs` 파츠별 단일 배열 + 드롭 시 `ItemPickupUI`
+
+```
+적·상자 드롭 → Schedule<ItemDrop>
+    → 플레이어 접근 → Schedule<ItemPickup>
+        → 기존 파츠 비교 → UI 표시 (현재/신규 옵션 비교)
+        → 선택 시 교체, 포기 시 드롭 소멸
+```
+
+- **파츠 종류**: Phase 3-B 기획 확정 후 enum 정의 (잠정: 무기·방어구·부적 3종)
+- **저장**: MetaState.equippedItems JSON 영속화
+
+### 2-5. 특성 영구 시스템 저장소 위치
+
+**결정안**: **JSON + `Application.persistentDataPath`** (PlayerPrefs 불가)
+
+| 후보 | 평가 | 결정 |
+|---|---|---|
+| **PlayerPrefs** | 단순 key-value 한계, 구조화 데이터 부적합 | ❌ 기각 |
+| **JSON (Newtonsoft or UnityJsonUtility)** | 구조 명확·디버깅 용이·버전 마이그레이션 쉬움 | ✅ **채택** |
+| **SQLite** | 과도한 복잡성 — 데이터 규모 작음 | ❌ Phase 3 이후 재검토 |
+
+**저장 경로**: `Application.persistentDataPath + "/eerie_village_save.json"`
+**구조 예시**:
+```json
+{
+  "version": 1,
+  "equippedItems": { "weapon": "id_001", "armor": "id_003" },
+  "traits": ["trait_basic_hp", "trait_exp_bonus"],
+  "lastPlayedAt": "2026-04-23T15:30:00+09:00"
+}
+```
+
+- **SaveSystem.cs** (신규, 개발 02 §3-3): Load·Save·Migrate 3종 API
+- **암호화**: 파일럿은 평문. Phase 3-C 과금 도입 시 AES 도입 검토
+
+## 3. 템플릿 확장·교체 우선순위 (P0/P1/P2)
+
+### 3-1. P0 — 즉시 확장 (게임 성립 최소 요건)
+
+| 항목 | 작업 | 관련 스크립트 |
+|---|---|---|
+| **마우스 좌클릭 공격 입력** | `Settings/Input Actions`에 `Player/Attack` 추가 + PlayerController에 `m_AttackAction` 편입 + `Schedule<PlayerAttack>` 이벤트 정의 | PlayerController.cs, PlayerAttack.cs (신규) |
+| **i-frame (무적 시간)** | Health.cs에 `invulnerableUntil` 필드 추가 + Decrement 시 `Time.time < invulnerableUntil` 체크 | Health.cs |
+| **라이프 1 정식화** | maxHP=1 기본값 유지 확인 + HP 막대 UI 제거 | Health.cs, UI 패널 |
+| **공격 판정 교체** | PlayerEnemyCollision "위에서 밟기" 로직 제거 + 공격 범위 AABB 박스 충돌 신설 | PlayerEnemyCollision.cs, AttackHitbox.cs (신규) |
+| **단일 씬 → 2씬 분리** | VillageScene·CombatScene 신설 + Additive Load 구조 | VillageController.cs (신규), StageManager.cs (신규) |
+
+### 3-2. P1 — 단기 (코어 루프 형성)
+
+| 항목 | 작업 | 관련 스크립트 |
+|---|---|---|
+| **마을 Scene 신설** | 조선 민가·주막·사당 기본 레이아웃 (narrative-designer Phase 3-B 결합) | VillageController.cs |
+| **스테이지 선택 UI** | 마을 입구 NPC·스테이지 포털 + MainUIController 확장 | StageSelectUI.cs (신규) |
+| **보스 진입 로직** | StageManager 3단 구성 + 보스룸 후방 차단 트리거 + Cinemachine 고정 카메라 전환 | StageManager.cs, BossController.cs (신규) |
+| **사망 → 마을 복귀 체인** | PlayerDeath 리팩터 + ResetRunState + ReturnToVillage 이벤트 3단 | PlayerDeath.cs (수정), ResetRunState.cs (신규), ReturnToVillage.cs (신규) |
+| **기본 적 템플릿 → 조선 귀신** | Enemy.prefab 스프라이트 교체 + 네이밍 (narrative-designer 결합) | Enemy.prefab, EnemyController.cs |
+
+### 3-3. P2 — 중기 (로그라이크 3축 시스템)
+
+| 항목 | 작업 | 관련 스크립트 |
+|---|---|---|
+| **카드 시스템** | CardDefinition ScriptableObject + CardPool + Pick3 UI + CardEffect 훅 (Simulation.Event<T>.OnExecute 활용) | CardSystem/ 폴더 신규 (3파일) |
+| **아이템 시스템** | ItemSlot 파츠별 단일 배열 + PickupUI + MetaState 영속 저장 | ItemSystem/ 폴더 신규 (2파일) |
+| **특성 시스템** | TraitManager + 특성 DB(ScriptableObject) + 런 시작 자동 적용 | TraitSystem/TraitManager.cs (신규) |
+| **SaveSystem** | JSON 직렬화 + Application.persistentDataPath + 버전 마이그레이션 | SaveSystem.cs (신규) |
+| **레벨업 Flow** | LevelUpFlow 싱글턴 + 경험치 공식 (balance-designer Phase 3-B) | LevelUpFlow.cs (신규) |
+
+### 3-4. P3+ (장기 — 본 문서 범위 외)
+
+- 보스 페이즈 구조 세분화·패턴 가독성 튠
+- 조선 민속 BGM·SFX (외부 사운드 디자이너 — C9 예외 인간 작업자)
+- 모바일 터치 UI (기획팀 `ux-designer` Phase 3-B 결과물 결합)
+- 과금 구조 (Phase 3-C)
+
+## 4. BT.Framework Tier 1 재사용 검토 (P29-3 준수)
+
+Tier 1 실측 확인 (`Runtime/Core/Util/`): **EnumEx·EnumToInt·FormatEx·KeyMaker·Log·MathEx·ValidationEx** (7개 실존). **EerieVillage 즉시 도입 후보 5종 선별**:
+
+| BT.Framework 항목 | 도입 근거 | 편입 시점 |
+|---|---|---|
+| **`Log` (범용 로거)** | 디버그·프로덕션 로그 일관화 — C11 "코드 직관성" | P0 즉시 |
+| **`ValidationEx`** | Inspector 참조 null 체크·범위 검증 — 버그 방지 | P0 즉시 |
+| **`MathEx`** | 플랫포머 물리 보조 연산 (이동·점프 수치·카메라 보간) — 기획 04 §4-1 | P0 즉시 |
+| **`FormatEx`** | 숫자·시간·통화 포맷팅 — UI 레벨·경험치 표시 | P1 UI 구축 시 |
+| **`EnumEx`** | enum 순회·파싱 유틸 — 파츠·카드 태그 정의 | P2 카드·아이템 시스템 |
+
+**Tier 2 신규 편입 후보** (EerieVillage 개발 과정에서 Tier 2 승격 기안):
+- **`SafeAreaBorder`** — 모바일 Safe Area 자동 대응 (기획 04 §4-2 카메라·UI). **현 시점 BT.Framework 미구현** (`Runtime/UI/Components/`·`UGUI/` 빈 디렉토리 실측, README.md 계획 기록만). P1 UI 구축 시 **신규 구현 후 Tier 2 승격**
+- **`UITouchHandler`** — 가상 스틱·공격 버튼 (기획팀 `기획_ux_designer_v1.md` Phase 2-B 식별)
+- **`BackKeyDispatcher`** — Android 뒤로가기 UI 스택 (동)
+
+**도입 방식**:
+- BT.Framework는 별도 레포(`코어코드/BT.Framework/`) → Unity Package Manager Git URL 참조 or NuGet Local 방식으로 편입 (Phase 2 착수 시 개발팀장 재결정)
+
+**Tier 2·3 (전투·네트워크·UI 고급)**: EerieVillage 기획 Phase 3-B 상세 확정 후 재평가 (P29-3)
+
+## 5. C30·자동 sync 전제 — 운영 체크리스트
+
+EerieVillage 개발 작업 착수 시 매번 확인:
+
+1. **git 상태**: Unity 프로젝트 레포 `git fetch origin && git status` — `behind` 시 `git pull` 후 착수
+2. **Unity Editor GitAutoSync**: 활성 상태 확인 (에디터 저장 시 자동 commit·push)
+3. **`scripts/unity_project_sync.sh`**: SessionStart hook 자동 실행 여부 확인 (PD 옵션 A 2026-04-20 승인)
+4. **Unity MCP 동작**: `mcp__unity-mcp__*` 툴 호출 가능 여부 (BT4 완결 상태)
+5. **BT worktree 내부 산출물 vs Unity 프로젝트 산출물 경계**: 문서·분석·기획 = BT worktree 내부, 코드·씬·프리팹 = Unity 프로젝트 (C34-11 경계 준수)
+
+## 6. 상세 보류 — Phase 3-B 이후 기획팀 결합
+
+- **카드 풀 규모·효과 수치**: balance-designer + content-designer (Phase 3-B)
+- **아이템 파츠 enum 확정**: system-designer (Phase 3-B)
+- **특성 개수·효과**: system-designer + balance-designer (Phase 3-B)
+- **보스 패턴 설계**: level-designer (Phase 3-B)
+- **모바일 터치 UX 상세**: ux-designer (Phase 3-B)
+- **사망 연출 톤**: narrative-designer (Phase 3-B)
+- **세계관·네이밍 SOT**: narrative-designer (Phase 3-B)
+
+## 7. 기각안 (개발 관점)
+
+1. **"템플릿 PlatformerMicrogame 완전 제거 + 자체 구현" — 기각.** 이벤트 시뮬레이터·Kinematic 물리·Cinemachine 통합이 이미 고품질. 재구현은 C11 "자원 효율성" 위반. **계승 확장**이 정답
+2. **"단일 Scene에서 모든 것 해결 (상태 기반 영역 전환)" — 기각.** 마을·전투의 오브젝트·조명·UI 구분이 복잡도 과다. **2 Scene + Additive Load**가 직관성 우월 (C11 "코드 직관성")
+3. **"PlayerPrefs로 특성·아이템 저장" — 기각.** 구조화 데이터 부적합. JSON 채택
+4. **"Unity 표준 Dynamic Rigidbody2D로 교체" — 기각.** Kinematic + Cast 방식이 플랫포머 정밀도 우월. 기획 04 §4-1 "템플릿 계승" 준수
+5. **"BT.Framework 16종 전량 도입" — 기각.** 장르 부적합 항목 존재. 5종 선별 도입 + Tier 2 승격 패턴 확인 후 확장 (P29-3 정신)
+
+## 8. 변경 이력
+
+| 일시 | 변경 | 사유 | 기안 |
+|---|---|---|---|
+| 2026-04-23 | v0.1 구현 로드맵 초안 작성 | BT5-Dev 3단계 | 개발팀장 |
+
+## 9. 참조 문서
+
+- `01_템플릿_구조_분석.md`·`02_스크립트_분석.md` — 선행 분석
+- 기획 `01·02·03·04·05_*.md` — 재미 축·코어 루프·진행 시스템·전투·스테이지
+- `코어코드/BT.Framework/` — Tier 1 16/16 완결본 (P29 조직 자산)
+- `공유/대화로그/EerieVillage/2026-04-23.md` — 본 작업 로그 엔트리
+- BT5-Dev C안 배치: `Assets/Editor/GitAutoSync/GitAutoSync.cs` + `scripts/unity_auto_sync.sh`·`unity_project_sync.sh`