---
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`