NerdNavis_AiDev
/
BurningTimesAi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
BurningTimesAi/프로젝트/EerieVillage/개발/03_게임_제작_준비.md

12 KiB
Raw Blame History

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" 구조 예시:

{
  "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.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