AI/잡다한개발노트Antigravity, Codex 2026-02-15 Plan/Task MD (작업노하우 공유)

게임씬_구현명세서.md

0.02MB

task.md

0.02MB

게임씬 구현 플랜 (보강본)

1. 목적

• GameScene을 Mock 중심 임시 상태에서 실제 전투 루프로 전환한다.
• 씬 흐름을 Init -> Title -> WorldMap -> Game -> WorldMap로 고정한다.
• 전투 결과(승/패, 별, 기록)가 저장과 월드맵 반영까지 일관되게 연결되도록 한다.

2. 범위

• 포함:
  • 전투 상태머신
  • 웨이브/스폰/경로
  • 타워/병영 블로킹/영웅 기본 루프
  • 전투 경제(골드)
  • 결과 처리/저장/월드맵 복귀
  • HUD/일시정지/결과 UI 최소 기능
• 제외(후속):
  • 라이브옵스 운영툴(원격 밸런스 패치, A/B)
  • 고급 연출(시네마틱, 특수 카메라 워크)

3. 현재 코드 기준 진단

항목	현재 상태	연결 코드
씬 정의	3개 (Title, WorldMap, Game)	KingdomDef.SCENES
게임 진입	월드맵 스테이지 선택 후 전환	WorldMapScene.SelectedStageId
전투 로직	FSM + 최소 루프 스캐폴딩 적용 (본 전투 시스템은 진행중)	GameStateController, WaveManager
HUD	최소 슬롯 적용 (Lives/Gold/Wave/NextWave/Hero/Spell/Result)	GameView
스테이지 데이터	StageConfig SO — 웨이브/적 미포함	StageData 구조체
저장	글로벌 SaveManager 싱글톤 경유로 단일화	SaveManager, WorldMapScene
복귀 경로	WorldMapScene으로 통일 (Mock은 DEV_MOCK 분리)	GameMockController, GameView

4. 목표 아키텍처

4.1 상태 흐름 다이어그램

┌─────────────────────────────────────────────────────┐
│  GameScene FSM                                      │
│                                                     │
│  ┌─────────┐   ┌────────────┐   ┌───────────┐      │
│  │ Prepare  │──>│ WaveRunning │──>│ WaveBreak │──┐  │
│  └─────────┘   └─────┬──────┘   └─────┬─────┘  │  │
│                      │                 │         │  │
│                      │    ┌────────────┘         │  │
│                      │    │  (다음 웨이브 있으면)   │  │
│                      │    v                      │  │
│                      │  ┌────────────┐           │  │
│                      │  │ WaveRunning│───────────┘  │
│                      │  └─────┬──────┘              │
│                      │        │ (마지막 웨이브 종료)  │
│                      v        v                     │
│                   ┌──────┐                          │
│                   │Result│                          │
│                   └──┬───┘                          │
│         ┌────────────┼────────────┐                 │
│         v            v            v                 │
│     [승리→월드맵] [패배→Retry]  [패배→Exit]         │
│                                                     │
│  ※ Pause: 모든 전투 상태에서 오버레이 진입/복귀 가능  │
└─────────────────────────────────────────────────────┘

4.2 매니저 배치

• 글로벌(DontDestroyOnLoad)
  • SaveManager
  • AudioManager
  • MetaEconomyManager
• 로컬(GameScene 전용)
  • GameStateController — FSM 상태 전이 총괄
  • WaveManager — 웨이브 진행/조기 호출/종료 판정
  • SpawnManager — 적 유닛 생성 및 경로 주입
  • PathManager — 적 이동 경로 캐시(웨이포인트)
  • TowerManager — 건설/업그레이드/판매/분기
  • HeroController — 이동/공격/스킬
  • InGameEconomyManager — 골드 수급/지출
  • GameView — HUD 표시 (기존 BaseView 확장, InGameUIBinder 역할 겸임)

5. 핵심 설계 원칙 (NotebookLM 반영)

• KR 스타일 핵심인 고정 건설 포인트 + 병영 블로킹을 초기에 포함한다.
• 단순 화력 경쟁 대신 조기 웨이브 호출(Early Call)의 리스크/리워드를 구현한다.
• 밸런싱은 감각이 아니라 계측 기반으로 진행한다(KPI 선구축).
• 초기화 순서를 강제한다:
  • 글로벌 매니저 초기화 완료
  • 스테이지 데이터 로드
  • 경로 캐시
  • 웨이브/스폰 시작

6. 전투 수학 (피해 공식)

6.1 피해 유형

유형	적용 방어	설명
물리(Physical)	ArmorPhysical(%)	아처/병영/포병 기본 출력
마법(Magic)	ArmorMagic(%)	마법사 기본 출력, 물리 방어 무시
고정(True)	없음	독/저주 등, 모든 방어 무시

6.2 물리 피해 공식

실제피해 = 기본피해 × (1 - ArmorPhysical / 100)

• 포병 특수: 적 방어력을 절반 무시 → 실제피해 = 기본피해 × (1 - ArmorPhysical / 200)

6.3 즉사(Insta-kill)

• 확률 기반: 공격 히트 시 확률 판정 (예: 스나이퍼 샷 최대 60%)
• 쿨타임 기반: 일정 쿨다운 후 확정 발동 (예: 죽음의 광선)
• 보스 면역: 보스/엘리트는 즉사 + 강제이동(CC) 면역

6.4 별 등급 기준

등급	조건
★★★	생명력 손실 ≤ 기준값A (거의 무손실)
★★	생명력 손실 ≤ 기준값B
★	생명력 > 0으로 클리어
패배	생명력 = 0

기준값은 WaveConfig.StarThresholds[]로 스테이지별 개별 설정

7. 타워 건설 UI 인터랙션

7.1 빈 건설 포인트 터치

터치 → 원형 링 메뉴 열림 (4종 타워 아이콘 + 비용 표시)
     ├─ 타워 선택 → 골드 차감 → 건설
     ├─ 골드 부족 → 아이콘 비활성(그레이아웃) + 비용 빨간색
     └─ 외부 터치/취소 → 메뉴 닫힘

7.2 기존 타워 터치

터치 → 타워 정보 + 액션 메뉴
     ├─ [업그레이드] 다음 레벨 비용 표시 (Lv1→2→3)
     ├─ [판매] 회수 골드 표시
     ├─ [분기 선택] Lv3→Lv4 시 2개 분기 아이콘 표시 (택 1, 비가역)
     └─ [랠리 포인트] (병영 전용) 집결 위치 드래그 지정

7.3 Lv4 이후 터치

터치 → 특수 능력 구매 메뉴
     ├─ 능력 A (비용/효과 표시)
     ├─ 능력 B (비용/효과 표시)
     └─ [판매]

7.4 GameView 프리팹 최소 슬롯 (NotebookLM 기준)

기준: NotebookLM 킹덤러쉬 노트북 질의 결과 (전투 HUD 최소셋)

A. Top HUD (필수)

• txtLives : 생명력 표시
• txtGold : 골드 표시
• txtWaveInfo : WAVE n / total
• btnNextWave : 조기 웨이브 호출 버튼
• btnPause : 일시정지 토글

B. Hero / Spell (필수)

• imgHeroPortrait : 영웅 상태 슬롯
• btnSpellReinforce : 증원군 스킬
• btnSpellRain : 불의비 스킬
• imgSpellReinforceCooldown : 증원군 쿨다운 오버레이
• imgSpellRainCooldown : 불의비 쿨다운 오버레이

C. Result / Debug (개발 단계)

• resultRoot, txtResultTitle, txtResultMessage
• btnRetry, btnExit
• btnVictory, btnDefeat (개발 디버그 전용)

D. 이벤트 인터페이스

• Bind(GameStateController) : 상태/웨이브 바인딩
• UpdateResourceInfo(lives, gold) : 자원 HUD 갱신
• SetNextWaveInteractable(bool) : 조기호출 활성/비활성
• SetSpellCooldown(spellId, normalized01) : 스킬 쿨다운 반영
• ShowResult(...), HideResult(), SetPauseVisual(...)

8. 단계별 구현 계획

8.1 1단계: 전투 프레임 구축

• 작업:
  • GameStateController 추가 (enum FSM)
  • 상태 전이 규칙 확정 (§4.1 다이어그램 기반)
  • Pause 진입/복귀 — Time.timeScale = 0 + 오버레이 UI
• 산출물: 상태 전이 로그(디버그), FSM 유닛테스트
• 완료 조건: Prepare→WaveRunning→WaveBreak→Result 전이 끊김 없음

8.2 2단계: 맵/경로/웨이브 골격

• 작업:
  • PathManager — 웨이포인트 기반 적 이동 경로 캐시
  • WaveConfig/EnemyConfig SO 도입
  • SpawnManager 적 생성 + 경로 주입
  • WaveManager 웨이브 종료 판정 (생존 적 0 + 스폰 완료)
• 산출물: 최소 1개 스테이지 웨이브 실행
• 완료 조건: 적이 경로를 따라 이동, 웨이브 시작/종료 정확 판정

8.3 3단계: 타워/경제/블로킹

• 작업:
  • TowerManager 건설/업그레이드/판매/분기
  • 원형 링 메뉴 UI (§7 인터랙션 기반)
  • InGameEconomyManager 골드 수급/소모
  • 병영 블로킹 루프 (적 상태: Moving→Blocked→Attacking→Dead)
  • 조기 호출 보상 (남은시간 × 보상계수 + 스펠 쿨다운 단축)
• 산출물: 4계열 기본 타워 동작, 조기 호출 버튼
• 완료 조건: 경제 루프(처치→골드→강화) 안정 순환

8.4 4단계: 영웅/결과/복귀

• 작업:
  • HeroController 이동/공격/스킬 최소 구현
  • 승/패 결과 계산 (§6.4 별 등급 기준 적용)
  • 저장 반영 + WorldMapReturnAnimator 연계
  • 복귀 경로를 WorldMapScene으로 통일
• 산출물: 승리/패배 UI, 저장 리포트 로그
• 완료 조건: 승/패 후 월드맵 복귀 정상, 앱 재시작 후 기록 유지

8.5 5단계: Mock 격리/회귀 안정화

• 작업:
  • GameMockController를 DEV_MOCK 분기로 제한
  • 기본 실행 경로에서 Mock 완전 분리
  • 핵심 회귀 테스트 수행
• 완료 조건: 기본 빌드 Mock 비활성, 주요 루프 회귀 통과

9. 데이터 스키마(초안)

StageConfig와 WaveConfig의 관계: 기존 StageConfig SO는 월드맵 표시용(위치/이름/해금)이고, WaveConfig는 전투 실행용(웨이브/골드/적). StageConfig.StageId를 키로 1:1 매핑하되, SO는 분리 유지한다. StageConfig에 WaveConfig 참조 필드를 추가하여 연결한다.

9.1 WaveConfig (SO)

• StageId — StageConfig.StageId와 1:1 매핑
• InitialGold
• InitialLives
• StarThresholds[] — 3별/2별 판정 기준 (남은 생명력)
• Wave[]
  • WaveIndex
  • SpawnEntries[]
    • EnemyId
    • Count
    • SpawnInterval
    • PathId
    • SpawnDelay
  • BonusGoldOnEarlyCall
  • IsBossWave

9.2 TowerConfig (SO)

• TowerId
• TowerType (Archer/Barracks/Mage/Artillery)
• DamageType (Physical/Magic/True)
• BuildCost
• SellRate (회수 비율, 예: 0.6)
• CanTargetAir
• Levels[]:
  • Damage, FireRate, Range, UpgradeCost
• BarracksData (병영 전용, TowerType == Barracks일 때만 사용):
  • SoldierCount — 소환 병사 수 (기본 3)
  • SoldierHP, SoldierArmor, SoldierDamage
  • RespawnCooldown — 병사 재소환 대기 시간
  • RallyRange — 집결 위치 지정 가능 반경
• BranchOptions[] (Lv4 분기):
  • BranchId, BranchName, BranchCost
  • Abilities[] (특수 능력, 개별 비용)

9.3 EnemyConfig (SO)

• EnemyId
• HP
• ArmorPhysical (% 감소)
• ArmorMagic (% 감소)
• MoveSpeed
• GoldBounty
• DamageToBase (탈출 시 생명력 차감)
• IsFlying
• IsBoss
• IsInstaKillImmune
• SpawnOnDeath[] (하수인 소환 시)

9.4 HeroConfig (SO)

• HeroId
• HeroName
• HP, Armor, MoveSpeed
• AttackDamage, AttackRange, AttackSpeed
• Skills[]:
  • SkillId, SkillType (Passive/Active/Ultimate)
  • Cooldown, Duration, DamageOrEffect

9.5 SpellConfig (SO)

• SpellId (증원군/불의비)
• Cooldown
• EarlyCallCooldownReduction
• Duration, DamageOrEffect

10. KPI/텔레메트리(초기 필수)

• WaveClearTime
• LifeLostPerWave
• GoldIncomePerWave / GoldSpendPerWave
• UnspentGoldAtWaveStart
• TowerBuildRateByType / TowerSellRateByType
• EnemyLeakCountByType
• EnemyDeathHeatmap (경로 구간별)
• EarlyCallUsageRate
• HeroSkillUsageRate

10.1 튜닝 기준(초기)

• 한 웨이브 종료 후 평균 신규 건설 0~1회 또는 업그레이드 1회 가능한 경제값
• 특정 타워 타입 사용률이 과도하게 치우치면 수치 조정 트리거
• UnspentGoldAtWaveStart가 지속적으로 높으면 난이도/가격 재조정

11. 위험 요소와 대응

위험	대응
초기화 순서 꼬임 → Null/경로 누락	부트스트랩 완료 전 GameScene 진입 금지 가드
병영 블로킹 → 전투 상태 충돌	적 상태를 Moving/Blocked/Attacking/Dead로 분리
Mock 경로 잔존 → 실제 루프 왜곡	DEV_MOCK 컴파일 심볼로 강제 분리
피해 공식 누적 오차 → 밸런스 붕괴	고정소수점 또는 int 기반 HP/데미지 사용
타워 UI 터치 영역 겹침	타워/건설포인트에 우선순위 레이어 + 상호배타 처리
UserSaveData 인스턴스 중복 → 데이터 덮어쓰기	글로벌 SaveManager 싱글톤으로 단일 인스턴스 보장
Time.timeScale 변경 → Coroutine/DOTween 오동작	timeScale 비의존 타이머 분리, 속도 변경 시 회귀 테스트

12. 체크리스트

• 월드맵 → 게임 진입 시 스테이지 데이터 일치
• 웨이브 시작/종료와 HUD 동기화
• 타워 건설/업그레이드/판매 정상
• 병영 블로킹 정상
• 조기 웨이브 호출 보상 정상
• 영웅 이동/스킬 최소 기능 정상
• 승/패 결과 저장 반영 정상 (§6.4 별 등급)
• 게임 → 월드맵 복귀 루프 정상
• 앱 재실행 후 기록 유지
• 기본 빌드 Mock 비활성 확인
• 피해 공식 검증 (물리/마법/고정/포병 관통)
• 속도 조절(x1/x2) 시 Coroutine/애니메이션/물리 정상 동작
• 복귀 경로 통일 확인 (Mock/GameView 모두 WorldMapScene)

13. 우선순위

1. 상태머신 + 웨이브/스폰/경로
2. 타워/경제 + 병영 블로킹
3. 결과 처리 + 저장 + 월드맵 복귀
4. 영웅 최소 기능
5. KPI 계측 + 튜닝
6. Mock 제거 + 회귀 안정화

14. 참고 메모

• 본 문서는 NotebookLM 킹덤러쉬 노트북을 기반으로 보강했다.
• 반영 포인트:
  • KR 스타일 핵심 전투 루프(병영 블로킹, 조기 호출)
  • 전투 씬 매니저 분리 원칙
  • 초기 단계 KPI 기반 밸런싱 접근
  • 피해 유형 3종(물리/마법/고정) + 포병 관통 공식
  • 별 등급 산정 기준 (라이프 기반)
  • 타워 건설 UI 인터랙션 흐름 (링 메뉴 → 분기 → 능력 구매)

15. 누락 위험 체크리스트 (High Risk)

• 병영/영웅이 적을 실제로 멈추게 하는 Melee Lock 규칙이 구현됨
• 적 상태(Moving/Blocked/Attacking/Dead) 전이가 프레임 단위로 충돌 없이 동작함
• 초기화 순서가 고정됨(맵/경로 로드 전 스폰 시작 금지)
• 비행 적 타겟팅 제약(CanTargetAir)이 타워별로 정확히 적용됨
• 방어력/저항/고정피해 계산식이 공통 함수로 단일화됨
• 보스 면역(즉사/강제이동 면역) 플래그가 실제 전투 판정에 반영됨
• 웨이브 미리보기 UI가 실 유닛 스폰 없이 데이터만으로 동작함
• 조기 웨이브 호출이 경제 보상과 스킬 쿨다운 감소를 함께 처리함
• Pause 상태에서도 입력 허용 범위(배치/업글/이동)가 명확히 분리됨
• 사운드 동시 재생 시 우선순위/채널 제한으로 클러터링을 제어함

16. Definition Of Done (전투씬)

16.1 기능

• 웨이브 데이터 기준으로 적 수량/타이밍이 정확히 스폰됨
• 적이 경로를 이탈하지 않고 목표 지점까지 이동함
• 타워가 유효 타겟만 공격하고(지상/공중 제약) 우선순위가 적용됨
• 병영 블로킹 및 영웅 교전이 정상 동작함
• 승/패 판정 및 결과 UI가 기획 조건대로 동작함

16.2 성능

• 적/투사체/이펙트 오브젝트 풀링 적용
• 목표 기기에서 전투 피크 시 목표 FPS 유지
• 불필요한 GC 스파이크(웨이브 시작/종료 구간) 없음

16.3 안정성

• Null 참조 없이 타겟 소실 시 재탐색
• 씬 전환 반복(월드맵↔게임) 30회 이상에서 누수/크래시 없음
• 저장 실패/로드 실패 시 안전 폴백 동작

16.4 밸런스

• 초반 3웨이브 체감 난이도가 급격히 튀지 않음
• 특정 타워 한 종류만으로 강제되지 않음(사용률 편중 감시)
• 조기 호출 사용이 명확한 보상과 리스크를 가짐

16.5 회귀

• WorldMapScene -> GameScene -> WorldMapScene 루프 회귀 통과
• 기존 저장 데이터와 신규 스키마 호환 확인
• DEV_MOCK 비활성 빌드에서 Mock 경로 호출 0건

17. 코드 반영 대상 (초안)

• Assets/Scripts/Kingdom/App/GameScene.cs
  • GameMockController 자동 생성 제거, GameStateController 초기화 진입점으로 변경
• Assets/Scripts/Kingdom/App/WorldMapScene.cs
  • 진입 파라미터(SelectedStageId, 난이도) 전달 검증 강화
• Assets/Scripts/Kingdom/App/GameMockController.cs
  • DEV_MOCK 분기 격리 및 기본 빌드 경로 차단
• Assets/Scripts/Kingdom/UI/GameView.cs
  • HUD/링 메뉴/결과 UI 이벤트 바인딩 확장
• Assets/Scripts/Kingdom/WorldMap/WorldMapReturnAnimator.cs
  • 전투 결과 데이터 소비 지점 점검
• 신규(예정):
  • Assets/Scripts/Kingdom/Game/GameStateController.cs
  • Assets/Scripts/Kingdom/Game/WaveManager.cs
  • Assets/Scripts/Kingdom/Game/SpawnManager.cs
  • Assets/Scripts/Kingdom/Game/PathManager.cs
  • Assets/Scripts/Kingdom/Game/InGameEconomyManager.cs
  • Assets/Scripts/Kingdom/Game/TowerManager.cs
  • Assets/Scripts/Kingdom/Game/HeroController.cs

18. 작업 순서(실행 단위)

1. GameScene에서 Mock 자동생성 제거 + FSM 뼈대 연결
2. 웨이브/스폰/경로 최소 루프 구현
3. 타워 건설/업글/판매 + 골드 루프 연결
4. 병영 블로킹 + 영웅 최소 동작 추가
5. 결과 저장 + 월드맵 복귀 루프 고정
6. KPI 로그 삽입 후 수치 1차 튜닝

19. StageInfoPopup ±¸Ƕ ¹ݿµ (2026-02-15) -> 코덱스가 자주 한글 날려먹는다 해결법 찾는중...

• ³놮ºόM(ŷ´ý·¯½¬) ±⁘ Ö¼Ҡ±¸¼º ¹ݿµ: ½ºŗÀ́ö¸?°/±ǀ峭À̵µ/Ö°?·Ϡ+ ³­À̵µ ¼±Ń + Start/´ݱ⠈帧.
• Assets/Resources/UI/StageInfoPopup.prefab ½űԠ»ý¼º.
• »ý¼º Àڵ¿ȭ µµ±¸ ß°¡: Assets/Scripts/Kingdom/Editor/StageInfoPopupPrefabBuilder.cs (Tools/Kingdom/Build StageInfoPopup Prefab).
• WorldMapScene¿¡¼­ Resources/UI/StageInfoPopup ·ε堰淎¿͠¿¬°ᵇ¾˾÷ ǥÁؠǃ·ο츦 ¿켱 »翫.
• StageInfoPopup ½ð¢/û°¢ ¿¬µ¿: ¿ùµ帊 ½ºǁ¶󀌆®(ico_stage_bg/ico_text_bg) Àû¿묠UI Ŭ¸¯/¿­¸² SFX(WorldMap_Click) ¿¬°ᬠŬ¸¯ Áߺ¹ ¹恶 °£°ݠÀû¿뮍
• ¾Ɔ® ƄÀ̇Á¶󀎺 StageInfoPopup Àü¿렸®¼ҽº °淎(UI/Sprites/WorldMap/StageInfoPopup/*) ¿켱 ¼Á¶, ±⁸ ¿ùµ帊 °ø¿렽ºǁ¶󀌆®´ fallback À¯Áö. ³ª³빙³ª³ª ǁ·҇ÁƮ ¹®¼­ ß°¡.
• StageInfoPopup ¾Ɔ® Àû¿렀ý· 2/3 ¼öǠ: Àü¿렰淎 À̹́ö ¹脡 Ȅ PrefabBuilder À罇ǠÀ¸·Πǁ¸®ƕ ½ºǁ¶󀌆® ¼Á¶ °»½Ů
• À̹́ö »ý¼º ´냼 °淎: OpenAI Image API ´뽅 ·΄àComfyUI º긮Áö(Assets/Scripts/Kingdom/Editor/stageinfopopup_comfy_bridge.py)·ΠStageInfoPopup ¾Ɔ® 4Á¾ »ý¼º ¹נǁ¸®ƕ ¹ݿµ.

---

게임씬 구현 — Task 체크리스트

근거 문서: 게임씬_구현명세서.md
작성일: 2026-02-14

---

0단계: 사전 정리 (선행 필수)

• UserSaveData → 글로벌 SaveManager 싱글톤으로 전환
• 복귀 경로 통일: GameMockController, GameView 모두 WorldMapScene으로 변경
• Assets/Scripts/Kingdom/Game/ 폴더 생성

---

1단계: 게임뷰/HUD 선행 정리 (UI Contract First)

명세서 §7, §8.1 · 완료 조건: GameView가 전투 상태/웨이브/결과 표시 계약을 먼저 제공

코드 작업

• GameView UI 계약 확정
  • 상태 텍스트(Prepare/WaveRunning/WaveBreak/Result/Pause)
  • 웨이브 텍스트(WAVE n / total)
  • Pause 토글 버튼 동작
  • 결과 영역(승리/패배/Retry/Exit) 기본 슬롯 확보
  • 최소 HUD 슬롯(Lives/Gold/NextWave/Hero/Spell) 추가
• GameView 이벤트 진입점 표준화
  • Bind(GameStateController) 유지
  • ShowResult(...), SetPauseVisual(...) 등 명시 API 정의
  • UpdateResourceInfo(...), SetNextWaveInteractable(...), SetSpellCooldown(...) 추가
• GameView 프리팹 바인딩 누락 방어(Null-safe) 정리

검증

• GameScene 진입 즉시 HUD 기본 정보 표시
• 상태 전이 시 HUD 표시 즉시 동기화
• Pause 토글 시 시각 상태와 실제 상태一致

---

2단계: 전투 프레임 구축 (FSM)

명세서 §8.1 · 완료 조건: Prepare→WaveRunning→WaveBreak→Result 전이 끊김 없음

코드 작업

• GameStateController.cs 신규 — enum FSM (Prepare/WaveRunning/WaveBreak/Result/Pause)
• 상태 전이 규칙 구현 (§4.1 다이어그램 기반)
• Pause 진입/복귀 — Time.timeScale = 0 + 오버레이 UI
• GameScene.cs 수정 — Mock 자동생성 제거, GameStateController 초기화 진입점으로 변경

검증

• 상태 전이 로그(디버그) 출력 확인
• FSM 유닛테스트 작성 및 통과

---

3단계: 맵/경로/웨이브 골격

명세서 §8.2 · 완료 조건: 적이 경로를 따라 이동, 웨이브 시작/종료 정확 판정

데이터

• WaveConfig SO 정의 (§9.1)
• EnemyConfig SO 정의 (§9.3)
• StageConfig에 WaveConfig 참조 필드 추가

코드 작업

• PathManager.cs 신규 — 웨이포인트 기반 경로 캐시
• SpawnManager.cs 신규 — 적 생성 + 경로 주입
• WaveManager.cs 신규 — 웨이브 종료 판정 (생존 적 0 + 스폰 완료)
• 적 기본 이동 로직 (경로 따라 이동 → 탈출 시 생명력 차감)

검증

• 최소 1개 스테이지 웨이브 실행
• 초기화 순서 고정 확인 (맵/경로 로드 전 스폰 시작 금지) [High Risk]

---

4단계: 타워/경제/블로킹

명세서 §8.3 · 완료 조건: 경제 루프(처치→골드→강화) 안정 순환

데이터

• TowerConfig SO 정의 (§9.2) — BarracksData 포함
• 피해 공식 공통 함수 단일화 (물리/마법/고정/포병 관통) [High Risk]

코드 작업

• TowerManager.cs 신규 — 건설/업그레이드/판매/분기
• InGameEconomyManager.cs 신규 — 골드 수급/소모
• 원형 링 메뉴 UI 구현 (§7.1~7.3)
• 병영 블로킹 루프 — 적 상태: Moving→Blocked→Attacking→Dead [High Risk]
• 랠리 포인트 (병영 전용) 드래그 지정
• 조기 호출 보상 (남은시간 × 보상계수 + 스펠 쿨다운 단축) [High Risk]
• 비행 적 타겟팅 제약 (CanTargetAir) 적용 [High Risk]

검증

• 4계열 기본 타워 동작 확인
• 조기 호출 버튼 동작 확인
• 타워 UI 터치 영역 겹침 없음 (우선순위 레이어)
• 피해 공식 검증 (물리/마법/고정/포병 관통)

---

5단계: 영웅/결과/복귀

명세서 §8.4 · 완료 조건: 승/패 후 월드맵 복귀 정상, 앱 재시작 후 기록 유지

데이터

• HeroConfig SO 정의 (§9.4)
• SpellConfig SO 정의 (§9.5)

코드 작업

• HeroController.cs 신규 — 이동/공격/스킬 최소 구현
• 승/패 결과 계산 (§6.4 별 등급 기준)
• 결과 UI 표시 (승리 → 별/보상, 패배 → Retry/Exit)
• 저장 반영 (SaveManager 경유)
• WorldMapReturnAnimator 연계 — 전투 결과 데이터 소비 지점 점검
• 보스 면역(즉사/강제이동 면역) 플래그 전투 판정 반영 [High Risk]

검증

• 월드맵 → 게임 진입 시 스테이지 데이터 일치
• 승/패 결과 저장 반영 정상 (§6.4 별 등급)
• 게임 → 월드맵 복귀 루프 정상
• 앱 재실행 후 기록 유지

---

6단계: Mock 격리 / 회귀 안정화

명세서 §8.5 · 완료 조건: 기본 빌드 Mock 비활성, 주요 루프 회귀 통과

코드 작업

• GameMockController를 DEV_MOCK 컴파일 심볼 분기로 격리
• 기본 실행 경로에서 Mock 완전 분리

검증 (DoD §16)

• WorldMapScene → GameScene → WorldMapScene 루프 회귀 30회+
• DEV_MOCK 비활성 빌드에서 Mock 경로 호출 0건
• 기존 저장 데이터와 신규 스키마 호환 확인
• 씬 전환 반복 시 메모리 누수/크래시 없음
• 저장 실패/로드 실패 시 안전 폴백 동작

---

7단계: KPI / 밸런스 튜닝

명세서 §10 · 완료 조건: 텔레메트리 로그 삽입 + 수치 1차 튜닝

코드 작업

• KPI 로그 삽입 (§10 전체 항목)
  • WaveClearTime, LifeLostPerWave, GoldIncomePerWave
  • TowerBuildRateByType, EnemyLeakCountByType
  • EarlyCallUsageRate, HeroSkillUsageRate
• 속도 조절(x1/x2) 구현 — timeScale 비의존 타이머 분리 [위험 §11]

검증

• 초반 3웨이브 체감 난이도 안정
• 특정 타워 타입 사용률 편중 없음
• 조기 호출 사용이 명확한 보상과 리스크를 가짐
• 속도 조절 시 Coroutine/애니메이션/물리 정상 동작
• 적/투사체/이펙트 오브젝트 풀링 적용 (성능)
• 전투 피크 시 목표 FPS 유지

---

코드 반영 대상 요약 (§17)

구분	파일	변경
수정	GameScene.cs	Mock 제거, FSM 진입점
수정	WorldMapScene.cs	진입 파라미터 검증 강화
수정	GameMockController.cs	DEV_MOCK 격리
수정	GameView.cs	HUD/링메뉴/결과 UI 확장
수정	WorldMapReturnAnimator.cs	결과 데이터 소비 점검
신규	Game/GameStateController.cs	FSM 총괄
신규	Game/WaveManager.cs	웨이브 진행/판정
신규	Game/SpawnManager.cs	적 생성/경로 주입
신규	Game/PathManager.cs	경로 캐시
신규	Game/InGameEconomyManager.cs	골드 경제
신규	Game/TowerManager.cs	타워 CRUD
신규	Game/HeroController.cs	영웅 최소 기능

---

진행 로그

• 2026-02-14:
  • SaveManager 추가 및 KingdomAppManager 초기화 경유 연결 완료
  • WorldMapScene, GameMockController의 저장 접근을 SaveManager.Instance.SaveData로 전환
  • GameMockController 복귀 경로를 WorldMapScene으로 통일
  • GameMockController를 DEV_MOCK 컴파일 심볼 영역으로 격리
  • GameStateController(FSM) 신규 추가 및 GameScene 연결
  • GameView에 FSM 바인딩/상태 표시/일시정지 토글 연결
  • WaveConfig, EnemyConfig SO 정의 추가 및 StageData에 WaveConfig 참조 필드 연결
  • PathManager, SpawnManager, WaveManager, EnemyRuntime 최소 전투 루프 스캐폴딩 추가
  • dotnet build 점검 시 Unity 생성 Assembly-CSharp.csproj에 신규 파일 미반영 상태 확인 (Unity 에디터 재생성 후 재검증 필요)
  • 작업 순서를 UI Contract First로 재정렬: GameView/HUD를 전투 매니저보다 선행 구현하도록 단계 재배치
  • GameView UI 계약 보강:
    • 상태/웨이브 표시, Pause 토글, Result 슬롯(승리/패배/Retry/Exit) 추가
    • ShowResult(...), HideResult(), SetPauseVisual(...) API 추가
    • 프리팹 바인딩 누락 시 런타임 기본 Result 슬롯 생성으로 Null-safe 강화
  • GameView 레거시 프리팹 레이아웃 자동 교정 추가:
    • 중앙 중첩 버튼/텍스트를 HUD 위치(좌상단 정보, 우상단 Pause, 우하단 디버그 버튼)로 재배치
    • HUDRoot 기준 재부모화로 GameScene 진입 시 검은 화면 중앙 겹침 현상 완화
  • GameViewLayoutFixTool 추가 (Kingdom/GameView/Fix Layout And Bindings):
    • Assets/Resources/UI/GameView.prefab 구조/직렬화 참조 자동 보정용
    • 현 세션에서 메뉴 실행 실패(에디터 컴파일/컨텍스트 이슈 추정), 에디터 리컴파일 후 재실행 필요
  • GameViewScenePreview 추가 (Tools/Preview/GameView/*):
    • Canvas (Environment) 상위 오브젝트 자동 생성 후 GameView 프리팹 배치
    • WorldMapView 프리뷰 방식과 동일한 편집 모드 단독 미리보기 지원
  • NotebookLM 기반 GameView 최소 슬롯 반영:
    • Top HUD: txtLives, txtGold, txtWaveInfo, btnNextWave, btnPause
    • Hero/Spell: imgHeroPortrait, btnSpellReinforce, btnSpellRain, 쿨다운 오버레이 2종
    • 인터페이스: UpdateResourceInfo, SetNextWaveInteractable, SetSpellCooldown 추가
  • GameView.cs.meta 누락/Guid 불일치 복구:
    • 기존 프리팹 참조 Guid(35dfde0a8ebb4c04c95f39fcd76eb8bd)로 정합성 복원
  • Kingdom/GameView/Fix Layout And Bindings 메뉴 실행 성공:
    • Assets/Resources/UI/GameView.prefab 레이아웃/직렬화 참조 자동 보정 완료
  • 중앙 겹침 원인 제거:
    • GameView 루트 레거시 직속 노드(btn*/txt*) 정리 로직 추가
    • 프리팹 보정 툴도 동일 정리 로직 반영 후 메뉴 재실행 완료
  • 스크린샷 기준 1단계 검증 진행:
    • GameScene 진입 시 HUD 기본 정보 표시 확인(웨이브/상태/생명력/골드/버튼 노출)
    • 영웅 포트레이트 기본 슬롯 시각 강도 완화(흰 사각형 알파 낮춤)

• 2026-02-14 (fix): WaveManager 참조 자동 재바인딩 + GameScene의 StageConfig.WaveConfig 주입 + 런타임 fallback WaveConfig 추가(참조 누락 시 경고/실패 완화).
• 2026-02-14 (verify): Unity Play에서 WaveManager missing-reference 경고 재현 여부 점검(콘솔 클리어 후 재확인).
• 2026-02-14 (fix): CameraBackgroundColorFixer obsolete API 교체 (FindObjectsOfType -> FindObjectsByType).
• 2026-02-14 (fix): WorldMapManager 스테이지 노드 생성 보완 + 월드맵 진입 fallback 정리 + WaveConfig 누락 시 FSM 안전화 + wave out-of-range 시 Result 전환.
• 2026-02-14 (fix): WorldMapManager 노드 생성 경로에 UIStageNode fallback 생성 추가(nodePrefab/nodeRoot 누락 시 경고 완화) + StageInfoPopup 리소스 누락 시 기본 fallback 추가.
• 2026-02-15 (feature): StageInfoPopup 프리팹 제작 완료 (Assets/Resources/UI/StageInfoPopup.prefab). 난이도 선택(Casual/Normal/Veteran), Start/Back/Close 버튼, 텍스트 영역 배치 완료.
• 2026-02-15 (enhance): StageInfoPopup 이미지/사운드 연동 완료. Panel=ico_stage_bg, Button=ico_text_bg, SFX=WorldMap_Click(open/click), 클릭 중복 재생 방지(0.08s).
• 2026-02-15 (asset-prep): 나노바나나용 프롬프트 문서 추가 (문서/이미지프롬프트/StageInfoPopup_이미지프롬프트_나노바나나.md). 코드/에셋 경로를 StageInfoPopup 기준으로 정리하고 fallback 정책 명시.
• 2026-02-15 (asset-apply): Step 2/3 적용 완료. StageInfoPopup 경로에 임시 이미지 4종 배치(StageInfoPopup_Panel/Button/Button_Start/Button_Close) 및 Tools/Kingdom/Build StageInfoPopup Prefab 메뉴로 프리팹 재생성 확인.
• 2026-02-15 (blocker): StageInfoPopup 신규 이미지 생성 시도 중 OpenAI Image API billing_hard_limit_reached로 중단. 과금 한도 확인 필요.
• 2026-02-15 (image-gen): OpenAI 한도 이슈 우회를 위해 ComfyUI 브릿지 적용. stageinfopopup_comfy_bridge.py로 이미지 4종 생성 후 PrefabBuilder 반영.
• 2026-02-15 (ui-tune): StageInfoPopup 레이아웃 1차 조정(패널/텍스트/버튼 간격, 닫기 버튼 크기/위치/패딩) 및 PrefabBuilder 업데이트.
• 2026-02-15 (ui-tune-2): StageInfoPopup 레이아웃 2차 조정(닫기 버튼 인셋/크기/외곽 여백, 중앙 텍스트 y축, 하단 Back/Start 정렬 간격).
• 2026-02-15 (ui-tune-3): StageInfoPopup 닫기 버튼 추가 미세조정(프레임 안착 강화: 위치/크기 재조정) 및 프리팹 재생성.
• 2026-02-15 (audio-fix): WorldMap_Click.mp3 교체(ComfyUI one-shot 클릭 효과음). 이전 버전은 WorldMap_Click_backup_prev.mp3로 백업.
• 2026-02-15 (audio-route-fix): WorldMap_Click mp3/wav 중복 참조 경로 정리. UI 클릭 전용 WorldMap_Click_UI.mp3 추가 후 WorldMapView/StageInfoPopup/Editor 할당 경로를 동일 파일로 통일.
• 2026-02-15 (noise-fix): StageConfig에 WaveConfig가 없을 때 발생하던 fallback 로그를 1회 정보 로그로 완화(WaveManager). 이후 StageConfig-WaveConfig 마이그레이션 진행.
• 2026-02-15 (game-visibility-fix): GameScene 월드가 검게만 보이던 문제 수정. 카메라를 2D 전투 기준(orthographic, z=-10)으로 강제 정렬하고, 런타임 배경(GameWorldRuntime/RuntimeBackground) fallback 생성 추가. SpawnManager에서 적 생성 시 기본 SpriteRenderer를 부여해 맵/적 가시성을 확보.
• 2026-02-15 (enemy-visual-fix): 흰 박스 적 fallback 개선. EnemyConfig에 Sprite/Tint/VisualScale 필드 추가, SpawnManager에서 EnemyConfig.Sprite 우선 사용 + Resources/UI/Sprites/Enemies/{EnemyId} 규칙 로드 + 미지정 시 EnemyId 해시 기반 색상 fallback 적용.
• 2026-02-15 (pause-resume-fix): Pause 후 Resume 불가 이슈 수정. GameView의 Pause 버튼을 쿨다운 바인딩에서 분리(즉시 토글), Pause 상태에서 버튼 라벨 Resume 표시. 공통 UIButtonExtensions 쿨다운을 unscaled time으로 변경해 timeScale=0에서도 interactable 복구되도록 보강.
• 2026-02-15 (battlefield-prefab-flow): GameScene이 Resources/Prefabs/Game/GameBattlefield 프리팹을 우선 로드하고, 없으면 GameBattlefield 런타임 fallback을 생성하도록 전환. PathManager.SetDefaultPathPoints(...), SpawnManager.SetEnemyRoot(...)를 추가해 전투 월드의 경로/적 루트 연결을 코드에서 고정. 에디터 메뉴 Kingdom/Game/Build GameBattlefield Prefab 추가.
• 2026-02-15 (battlefield-prefab-guard): GameBattlefield 프리팹의 Missing Script 참조 감지 가드 추가. 프리팹에 null component 또는 GameBattlefield 컴포넌트 누락 시 인스턴스화를 스킵하고 런타임 fallback 월드로 안전 전환.
• 2026-02-15 (battlefield-script-stability): GameBattlefield를 PathManager.cs 내부 선언에서 GameBattlefield.cs 단독 파일로 분리해 Unity 스크립트 매핑 안정화. 프리팹 빌더에서 기존 GameBattlefield.prefab 삭제 후 재생성하도록 변경.
• 2026-02-15 (verify): 몬스터가 지정 경로(웨이포인트)를 따라 이동하는 동작 확인 완료.