diff --git a/공유/PD_지시_트래킹/개발팀_PD_지시_로그.md b/공유/PD_지시_트래킹/개발팀_PD_지시_로그.md index a0abd77..f94c1d1 100644 --- 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 호출 → 산출물 수령 시 종합 보고 | --- diff --git a/공유/대화로그/EerieVillage/2026-04-23.md b/공유/대화로그/EerieVillage/2026-04-23.md index 8097330..aa33ed5 100644 --- 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` + HeapQueue + 이벤트 풀링): Unity 표준 UnityEvent 미사용. `Event.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` 이벤트 체인 (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-②). diff --git a/공유/대화로그/조직운영/2026-04-23.md b/공유/대화로그/조직운영/2026-04-23.md index df59d05..743159b 100644 --- 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` 생성 diff --git a/프로젝트/EerieVillage/개발/01_템플릿_구조_분석.md b/프로젝트/EerieVillage/개발/01_템플릿_구조_분석.md new file mode 100644 index 0000000..d5391d2 --- /dev/null +++ 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()` 기반 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 활용 검토) diff --git a/프로젝트/EerieVillage/개발/02_스크립트_분석.md b/프로젝트/EerieVillage/개발/02_스크립트_분석.md new file mode 100644 index 0000000..b0fd818 --- /dev/null +++ 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` 제네릭 (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() // tick=현재+0, 즉시 실행 +Schedule(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 invoke + eventPools[ev.GetType()].Push(ev); // 풀 반환 +} +``` + +**강점**: +- 이벤트 타입별 풀링으로 GC 압박 최소화 (C11 자원 효율성 ✓) +- `Event.OnExecute` 정적 Action으로 **외부 시스템 훅** 가능 → **EerieVillage 카드 효과가 이벤트에 부착되는 구조 가능** +- 시간 지연 이벤트 (`Schedule(delay)`) 네이티브 지원 + +**EerieVillage 활용 예상**: +- `Schedule` 이벤트 신규 → 카드 효과(관통·AoE·연사)가 `PlayerAttack.OnExecute` 훅 +- `Schedule` → 3픽 UI 띄우기 +- `Schedule` → 파츠 교체 확인 다이얼로그 + +### 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(); player.Bounce(2); } +else { Schedule(); } +``` + +- **마리오 식 "위에서 밟으면 적 피해"** 구조 +- EerieVillage는 "**공격 키로 적 피해**" 구조이므로 **이 판정 교체 필요** (개발 03 §3-1 P0) + +### 2-4. Model 직렬화 참조 (PlatformerModel) + +```csharp +// GameController.cs +public PlatformerModel model = Simulation.GetModel(); +// Simulation.InstanceRegister.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` 이벤트 체인 | +| `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.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.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 (사망 시 상태 보존 매트릭스) diff --git a/프로젝트/EerieVillage/개발/03_게임_제작_준비.md b/프로젝트/EerieVillage/개발/03_게임_제작_준비.md new file mode 100644 index 0000000..aea0986 --- /dev/null +++ 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`·`Schedule` 이벤트 신규 + +### 2-2. 사망 분기·리셋 로직 위치 + +**결정안**: `PlayerDeath.cs` 리팩터 + `ResetRunState` 이벤트 체인 신설 + +``` +피격 (i-frame 체크) → Health.Decrement() → HealthIsZero + → Schedule + → Die 애니메이션 재생 (1.5초) + → Schedule(1.5f) + → RunState.Clear() // 레벨=1, 카드덱 비우기 + → MetaState 유지 (아이템·특성) + → Schedule + → Unload CombatScene + Load VillageScene +``` + +- **리셋 범위** (기획 02 §4 매트릭스): + - `RunState.level`·`RunState.exp`·`RunState.cardDeck` → 초기화 + - `MetaState.equippedItems`·`MetaState.traits` → 유지 +- **저장**: MetaState 변동 시 즉시 JSON Save + +### 2-3. 레벨업·스킬 카드 시스템 진입점 + +**결정안**: `LevelUpFlow.cs` 싱글턴 + `Schedule` 이벤트 + +``` +적 처치 → (적 보상) → RunState.exp 증가 + → RunState.CheckLevelUp() → 레벨업 조건 만족 + → Schedule + → 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 + → 플레이어 접근 → Schedule + → 기존 파츠 비교 → 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` 이벤트 정의 | 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.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`