Antigravity 2026-02-14 (월드맵씬, 게임씬,기타 모듈화, 시스템작업)

작업하며 노트 끄적끄적내용. 그 그뒤부터 내용은 본격적으로 문서화 하였습니다. 나눠서 하자니 분류도 애매하고 .. 개발은 Antigravity를 메인으로 사용하고 IDE에 Codex, kilo를 추가로 설치하여 작업하고있습니다.

IDE 작업 예시

 

---

1. 아이콘 제작 프롬프트

### A. Back (`Icon_Back`)#### 이미지 사이즈- `512x512` (기본)- 고해상도 필요 시 `1024x1024`#### Positive Prompt```textUI button icon for "Back", red curved arrow pointing left, wooden button frame with metal rim,game interface asset, game UI icon, isolated on white background, chunky vector style, wood and stone texture,Kingdom Rush art style, 2D vector art, flat cartoon style, thick bold outlines, vibrant saturated colors,hand-drawn game asset, Flash game aesthetic, cel-shaded, high contrast, 1:1 composition, 512x512```#### Negative Prompt```texttext, realistic, 3D render, complex details, thin lines, watermark

---

2. 피드백 후 정리 보완작업

피드백 내용과 대응 요청(볼드는 수정요청내역)

1.중앙 세로 이음선 제거

배경 중앙에 seam(경계선)처럼 보이는 라인이 있어 품질이 떨어져 보입니다. 배경 스프라이트/타일 정렬부터 수정하는 게 1순위입니다.(Scene에서 생긴 그리드이기 떄문에 작업안해도됨)

2.스테이지 선택 노드 가독성 강화

현재 STAGE SELECT가 배경과 비슷한 톤이라 눈에 덜 띕니다.

선택 링(펄스), 외곽 글로우, 노드 그림자 추가 추천.
(ComfyUI가 아닌 직접 GPT를 이용해서 생성 할 수 있을 떄만 대응)

3.상단 타이틀 대비 개선

WORLD MAP 텍스트가 배경 위에서 약합니다.

반투명 배너 또는 텍스트 외곽선/드롭섀도우를 넣어 가독성 확보하세요.
(메이플 폰트 링크 후 연동)

4.하단 버튼 의미 분리

두 버튼의 기능이 직관적으로 안 보입니다.

아이콘 크기 키우고, 짧은 라벨(예: HERO, UPGRADE) 또는 툴팁을 붙이세요.

5.버튼 배치 균형

하단 버튼이 맵 오브젝트 위에 떠 있는 느낌입니다.

공통 하단 바(패널) 위에 정렬하면 UI 체계가 안정됩니다.

6.상태 정보 추가

스테이지에 클리어/잠금/신규 상태를 표시하세요(별, 자물쇠, 느낌표).

월드맵의 진행감이 크게 좋아집니다.

7. 클릭 피드백 강화

버튼/노드에 hover/press 스케일(예: 1.0→0.93→1.0), 클릭 SFX를 강하게 주면 조작감이 좋아집니다.

8.안전영역 대응

버튼 위젯으로 추가하고. 컨텐츠사이즈필터랑 레이아웃 그룹 추가.

하단 버튼 규격화 가능하도록 모듈화(이미지와 텍스트 수정하도록)

하단 버튼 공통 모듈화

**
SafeArea 작업**

---

2026-02-14 개발일지 (feat. 

월드맵에서 전투로 — UI 시스템 완성과 게임씬 설계

월드맵 UI를 프로덕션 수준으로 끌어올리고, 게임씬 전투 루프의 설계 문서를 확정한 하루.
"버튼 하나하나에 시스템이 있고, 전환 하나하나에 설계가 있다."

---

🎯 오늘의 목표

1. 월드맵 UI 완성도 향상 — 스테이지 노드, 액션 버튼, 사이드 보더를 프리팹 기반으로 안정화
2. 씬 전환 Fade 효과 — 모든 씬 전환에 FadeOut/FadeIn 적용
3. 게임씬 구현 플랜 — NotebookLM 킹덤러쉬 분석 데이터를 기반으로 전투 루프 설계 문서 작성

---

📦 커밋 요약

시간	커밋	내용
16:09	a9a937e	월드맵 UI 워크플로우, 에셋, 문서 일괄 적용
17:19	501258b	UIActionButtonItem 프리팹 추가 + 하단바 레이아웃 개선
20:34	faf18d5	UIStageNode 고도화 + 사이드보더 실행 플랜 추가
21:11	347805d	사이드보더 구조 툴 + SafeArea 바인딩
21:28	0a4937d	사이드보더 아트 에셋 생성 + 프리팹 바인딩
22:14	51d8495	UIStageNode 시각 상태 규칙 정리

---

🏗️ 1. UIStageNode 시스템 고도화

문제

스테이지 버튼이 단순 Button + Text로만 되어 있어, 잠금 상태/클리어 등급/선택 하이라이트를 표현할 수 없었음.

해결: 데이터 바인딩 기반 ViewModel

StageNodeViewModel
  ├── StageId, StageName
  ├── IsUnlocked, IsBoss
  ├── ClearStars (0~3)
  └── IsSelected

      ↓ 바인딩

UIStageNode (MonoBehaviour)
  ├── 잠금 오버레이 (IsUnlocked = false → 어둡게 + 자물쇠 아이콘)
  ├── 별 표시 (ClearStars → 별 아이콘 1~3개)
  ├── 보스 마커 (IsBoss → 해골 아이콘 표시)
  └── 선택 하이라이트 (IsSelected → 테두리 발광)

시각 상태 규칙

상태	배경	아이콘	인터랙션
잠금	어둡게	자물쇠	터치 불가
해금(미클리어)	기본	스테이지 번호	터치 가능
클리어	기본	별 1~3개	터치 가능
선택됨	하이라이트	유지	선택 연출 재생

핵심: IStageUnlockPolicy 인터페이스로 해금 조건을 분리하여, 선형/분기/조건부 해금을 유연하게 교체할 수 있도록 설계.

---

🖼️ 2. 사이드 보더 시스템

배경

월드맵 배경 이미지가 16:9 기준으로 제작되었지만, 4:3이나 19.5:9 같은 다른 비율에서 빈 공간이 노출됨.

해결 구조

WorldMapView
├── Background (Stretch)
├── LeftBorder  ← SafeArea 바깥 영역을 채움
├── RightBorder ← SafeArea 바깥 영역을 채움
└── Content (SafeArea 내부)

• Editor 스크립트로 사이드보더 구조를 자동 생성 (WorldMapSideBorderStructureTool)
• AI 생성 에셋을 좌/우 보더에 바인딩
• SafeArea 기준으로 위치/크기 자동 조절

---

🔀 3. 씬 전환 Fade 효과

변경 내용

AppManagerBase.ChangeScene()에 useFade 파라미터 추가:

public void ChangeScene(TSceneEnum sceneID, bool useFade = true)

• 기본값 true: 모든 씬 전환에 FadeOut → 로드 → FadeIn 적용
• useFade: false: 초기 진입(InitScene → TitleScene)처럼 자연스러운 전환에 사용
• 중복 호출 방지: _isChangingScene 플래그로 연타 방어
• FadeIn 조건부 실행: _needsFadeIn 플래그로 FadeOut 없이 FadeIn만 되는 버그 차단

---

📐 4. 게임씬 전투 루프 설계

오늘의 가장 큰 작업은 게임씬 구현 플랜을 NotebookLM 킹덤러쉬 분석 데이터를 기반으로 확정한 것.

NotebookLM에서 추출한 핵심 설계 포인트

요소	킹덤러쉬 원칙	구현 반영
건설 방식	자유 배치가 아닌 고정 슬롯	StrategicPoint 배치 시스템
병영 블로킹	유닛이 적을 물리적으로 저지	적 상태 FSM (Moving/Blocked)
조기 호출	리스크 감수 → 골드/쿨타임 보상	WaveManager.EarlyCall()
피해 공식	물리(% 감소), 마법(물리방어 무시), 고정(모든 방어 무시)	DamageType enum 3종
포병 관통	적 방어력 절반 무시	별도 공식 분기
경제 밸런스	항상 부족하게, 선택과 집중 강제	KPI 기반 튜닝
별 등급	남은 생명력 기준 (스테이지별 개별 설정)	StarThresholds[]

5단계 구현 로드맵

1단계: 전투 프레임 (FSM)
  └── Prepare → WaveRunning → WaveBreak → Result

2단계: 맵/경로/웨이브
  └── PathManager + WaveConfig/EnemyConfig SO

3단계: 타워/경제/블로킹
  └── TowerManager + InGameEconomyManager + 병영 루프

4단계: 영웅/결과/복귀
  └── HeroController + 저장 + WorldMapReturnAnimator

5단계: Mock 격리/회귀
  └── DEV_MOCK 분기 + 회귀 테스트

---

💡 핵심 교훈

1. NotebookLM을 설계 도구로 쓰기

킹덤러쉬 분석 자료를 NotebookLM에 축적해두니, "포병의 방어력 관통 공식이 뭐야?" 같은 구체적인 질의에 정확한 답변을 받을 수 있었다. 게임 디자인 레퍼런스를 체계적으로 관리하면, 구현 단계에서 "감으로 만드는" 실수를 줄일 수 있다.

2. KPI를 코드보다 먼저 설계하기

보통 밸런싱은 게임이 어느 정도 완성된 후에 하지만, 이번에는 계측 지표(KPI)를 구현 플랜 단계에서 먼저 정의했다:

• WaveClearTime, GoldIncomePerWave, EnemyLeakCountByType…

이 지표들이 먼저 정의되면, 코드를 짤 때 자연스럽게 로깅 포인트를 넣게 되고, "이 값이 어디서 튀는지" 추적이 가능해진다.

3. Disposable Tool 패턴의 위력

사이드보더 구조 생성, UIStageNode 검증, 에셋 바인딩 — 이 모든 작업을 일회성 에디터 스크립트로 처리하고 즉시 삭제했다. MCP로 개별 오브젝트를 하나씩 조작하는 것보다 Editor Script API를 활용한 일괄 처리가 훨씬 안정적이고 재현 가능하다.

---

📋 Disposable Tools (생성 → 사용 → 삭제)

Assets/Scripts/Kingdom/Editor/
├── WorldMapSideBorderStructureTool.cs    ← 사이드보더 구조 자동 생성
├── WorldMapStageNodeAutoLayoutTool.cs    ← 스테이지 노드 배치 도구
└── WorldMapStageNodeValidationTool.cs    ← 스테이지 노드 프리팹 검증

---

🔄 오늘의 작업 흐름

1. 월드맵 UI 개선 (오전~오후)
   ├── UIActionButtonItem 프리팹 + 레이아웃
   ├── UIStageNode ViewModel 바인딩 + 시각 규칙
   └── 사이드보더 구조/에셋/바인딩

2. 씬 전환 Fade (오후)
   ├── AppManagerBase.ChangeScene() 확장
   ├── _needsFadeIn 플래그 추가
   └── InitScene → TitleScene fade 제외

3. 게임씬 설계 (저녁)
   ├── NotebookLM 질의 4건 (HUD/타워/경제/피해공식/UI인터랙션)
   ├── 기존 플랜 → 보강본 작성 (1차)
   ├── 사용자 편집 (구조 재정리, KPI/위험요소 추가)
   └── 2차 보강 (피해 공식, UI 흐름, 스키마 추가)

---

📊 수치 요약

항목	수량
커밋	6건
신규/수정 스크립트	~12개
프리팹 생성/수정	4개 (UIStageNode, UIActionButtonItem, WorldMapView, SideBorder)
문서 작성/보강	5개 (사이드보더 플랜, 버튼 프리팹 플랜, 게임씬 플랜 등)
NotebookLM 질의	4건
컴파일 에러	0 (최종 검증 완료)
---

3. 플랜 보완하기!!

제미나이 프로 모델로 플랜을 만들후 제미나이 -> 클루드 -> 코덱스 -> 제미나이 계속 이렇게 플랜을 보강하면 (토큰 광탈) 플랜이 매우 단단해진다. 이후 Task세팅하고 코덱스나 클루드로 코드작업하면 한번에 엄청 길게 작업하면서도 매우 안정적으로 진행이 가능하다.

4. 스테이지 버튼도 모듈화

5. 작업이 너무 오래걸린다... 이제부터 코덱스 스파크 모델로 코드구현을 해보자! 생각보단? 빠르지 않은거 같은데 변경 내역을 자세히 못봐서 그런거 같기도하다.

6. 다음은 코덱스 <-> 오퍼스4.6 으로 게임씬 구현 플랜 내용이다. 해당 내용을 가지고 이후에 클루드 코드의 코딩을 진행 그러면 정말 한참을 짠다

게임씬_구현명세서.md

0.02MB

task.md

0.01MB

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

1. 목적

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

2. 범위

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

3. 현재 코드 기준 진단

항목	현재 상태	연결 코드
씬 정의	3개 (Title, WorldMap, Game)	KingdomDef.SCENES
게임 진입	월드맵 스테이지 선택 후 전환	WorldMapScene.SelectedStageId
전투 로직	Mock 시뮬레이션만 존재	GameMockController
HUD	디버그 버튼(Victory/Defeat/Pause) + 웨이브 텍스트	GameView
스테이지 데이터	StageConfig SO — 웨이브/적 미포함	StageData 구조체
저장	매번 new UserSaveData()로 생성 — 글로벌 싱글톤 아님	WorldMapScene:25, GameMockController:95
복귀 경로	충돌: Mock은 TitleScene, GameView는 WorldMapScene	GameMockController:103 vs GameView:58,65

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 (비용/효과 표시)
     └─ [판매]

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차 튜닝

---

task.md

0.01MB

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

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

---

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

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

---

1단계: 전투 프레임 구축 (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 유닛테스트 작성 및 통과

---

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

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

데이터

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

코드 작업

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

검증

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

---

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

명세서 §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 터치 영역 겹침 없음 (우선순위 레이어)
• 피해 공식 검증 (물리/마법/고정/포병 관통)

---

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

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

데이터

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

코드 작업

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

검증

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

---

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

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

코드 작업

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

검증 (DoD §16)

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

---

6단계: 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 에디터 재생성 후 재검증 필요)