# 프로젝트 개발 및 개선 종합 체크리스트 (docs/agents_docs/todo.md)

이 문서는 본 3D 무작위 유닛 디펜스 게임의 기본 프레임워크 설계부터 시작하여, 여태까지 진행된 핵심 8단계 구현 사항, 디버깅 내역, AI/비주얼 개선 내역 및 향후 확장 계획을 정리한 개발 관리 문서입니다.

---

## ▣ 개발 완료 및 버그 수정 완료 내역

### [x] 1단계: 기본 맵과 3D 카메라 셋업
- [x] 프로젝트 기본 폴더 구조 생성 (`src/core`, `src/autoload`, `src/entities/monsters`, `src/entities/units`, `src/ui`, `src/utils`)
- [x] 메인 게임 씬 (`src/core/main.tscn`) 설계
- [x] 3D 지형 바닥(Ground) 및 실외 환경 조명 설정
- [x] 맵 가장자리를 회전하는 사각형 루프 경로 (`Path3D`) 배치
- [x] RTS 3D 탑다운 카메라 컨트롤러 구현 (`src/core/rts_camera.gd`)
  - WASD 키보드 입력 및 화면 가장자리(Screen Edge) 마우스 스크롤 대응
  - 마우스 휠을 활용한 고도 기반 줌인/줌아웃 (피치 60도 고정각 보정)
  - 맵 크기에 딱 들어차 여백을 최소화하도록 최대 줌 아웃 한계(`max_zoom`)를 15.0으로 튜닝
  - 줌 아웃을 최대로 당겼을 때(전체 맵이 화면에 다 보일 때) 카메라 이동을 불가능하게 막고, 초점(`_target_focus`)을 맵 중앙`(0, 0)`으로 부드럽게 정렬(lerp)시키는 기능 구현 완료

### [x] 2단계: 글로벌 게임 매니저와 스테이지 시스템
- [x] 글로벌 게임 매니저 AutoLoad 싱글톤 (`src/autoload/game_manager.gd`) 구현
  - `player_gold` (초기 300), `unit_spawn_cost` (100), `current_stage` (1), `active_monster_count` 실시간 추적
  - 몬스터 200마리 초과 시 게임 패배 및 20스테이지 생존 성공 시 게임 승리 감지
- [x] 스테이지 제어 엔진 (`src/core/stage_manager.gd`) 작성
  - 1초 간격 몬스터 스폰 타이머 관리 및 스폰 수량 통제
  - 스테이지별 몬스터 체력 및 처치 골드 스케일링 공식 구현
  - 스폰 및 스테이지 시작 대기 시간(쿨다운) 타이머를 정지/재개시키는 `toggle_spawning_pause()` 일시 정지 로직 추가
- [x] HUD UI (`src/ui/hud.gd`) 리팩토링 및 멈춤 버튼 추가
  - 런타임에 소환 버튼 옆에 `PauseSpawningButton`을 동적 생성 및 배치
  - 버튼 클릭 시 `StageManager`의 스폰 제어기와 연결되어 텍스트를 `"Pause Spawning"` ↔ `"Resume Spawning"` 으로 상호 토글 및 리셋(재시작 시) 연동 완료

### [x] 3단계: 몬스터 시스템 구현
- [x] 몬스터 캐릭터 씬 및 비주얼 구체 메쉬 생성 (`src/entities/monsters/base_monster.tscn`)
- [x] 몬스터 `PathFollow3D` 상속 스크립트 구현 (`src/entities/monsters/base_monster.gd`)
  - 경로를 자동으로 순환 비행하며 끝부분(Progress 1.0) 도달 시 0.0으로 리셋되어 무한 루프 회전
  - 피해 적용(`take_damage()`), 체력 소진 시 사망 처리 및 플레이어 골드 보상 증여 로직 구현

### [x] 4단계: RTS식 유닛 선택 및 이동 (Navigation)
- [x] 런타임 내비게이션 맵 생성을 위한 `NavigationRegion3D` 탑재 및 자동 베이킹
- [x] RTS 드래그 다중 선택 제어기 구현 (`src/core/unit_controller.gd`)
  - 화면 마우스 좌클릭 드래그 박스 2D 렌더링 및 3D 공간 투영(Unproject) 다중 유닛 수집
  - 키보드 'H' 키 입력을 통한 선택 유닛 제자리 고정대기(Hold Position) 명령 기능 구현 완료
- [x] 우클릭 지점 대한 유닛 분산 격자 정렬 이동 및 몬스터 대상 타겟 어택 명령 하달 구현

### [x] 5단계: 유닛 클래스 정의 및 전투 구현
- [x] 5종 유닛(Striker, Guardian, Ranger, Slayer, Archmage) 제원을 정의하는 커스텀 리소스 스키마 (`src/entities/units/unit_data.gd`) 작성
- [x] 유닛 뼈대 캐릭터 씬 및 선택 링 하이라이트 생성 (`src/entities/units/base_unit.tscn`)
- [x] 유닛 행동 및 전투 인공지능 스크립트 작성 (`src/entities/units/base_unit.gd`)
  - 네비게이션 에이전트(`NavigationAgent3D`)를 활용한 맵 경로 이동
  - 정지 상태 중 사거리 내의 가까운 적 자동 탐지 및 쿨타임 공격 연산 루프 구현
  - 홀드 상태(`_is_holding`)에서 추격을 전면 억제하고 오직 자신의 공격 사거리 내에 들어온 몬스터만 수비 타겟팅하도록 AI 알고리즘 보완 완료 (수동 우클릭 지시 시 홀드 상태 자동 해제)

### [x] 6단계: UI 및 소환 시스템
- [x] HUD UI 인터페이스 구축 (`src/ui/hud.tscn`)
  - 화면 상단 골드, 현재 스테이지, 몬스터 마릿수 한도(200) 라벨 배치
  - 화면 중앙 결과(승리/패배) 알림 Panel 및 재시작 Button 설정
- [x] HUD 스크립트 제어 (`src/ui/hud.gd`)
  - 유닛 소환 버튼 클릭 시 100G 차감 및 중앙 영역 무작위 분산 스폰
  - 5종 유닛 20% 동일 확률 주입 초기화 장치 마련
  - 재시작 클릭 시 씬 내 잔존 개체 정리 및 매니저 값 초기화 연동

### [x] 7단계 & 8단계: Striker 전용 씬 분리 및 스킨 연동 리팩토링
- [x] `src/entities/units/striker/` 전용 폴더 및 `striker_unit.tscn` 씬 파일 생성
- [x] `striker_unit.tscn` 내부에 `striker.fbx` 모델을 서브씬 인스턴스로 바인딩하고 스케일을 0.01로 조정하여 저장
- [x] `base_unit.gd`를 리팩토링하여 불필요한 런타임 FBX 로더 및 런타임 스케일 세팅 코드를 모두 제거하고, 씬에 구성된 노드를 인계받는 구조로 슬림화
- [x] `hud.gd`에 소환 씬 분기 기능을 도입하여, 소환 시 ID에 맞춰 Striker 유닛일 때 전용 `striker_unit.tscn`을 소환하도록 구현
- [x] 유닛이 스폰될 때 3D 모델 하위 메쉬에 `striker_0.png` 텍스처를 씌우는 오버라이드 매핑 기능을 작동시켜 모델 렌더 텍스처 출력 완료
- [x] `assets/models/units/striker/` 폴더 내부의 개별 애니메이션 FBX 파일들(`striker_idle.fbx`, `striker_walk.fbx`, `striker_run.fbx`, `striker_attack.fbx`)을 추출하여 단일 `AnimationLibrary` 리소스(`striker_animations.tres`)로 병합 완료
- [x] 신규 유닛 `Guardian` 모델(`guardian.fbx`)에 탑재된 애니메이션들을 추출하고 루프 상태를 정밀 정규화하여 단일 라이브러리 리소스인 `guardian_animations.tres`로 빌드 완료
- [x] `base_unit.gd`에서 유닛 모델명(예: `striker`, `guardian`)을 동적으로 감지하여 해당 애니메이션 라이브러리(`.tres`)를 자동 주입하고 고유 이름 프리픽스(`striker/`, `guardian/`)로 적합한 애니메이션들을 실시간 교차 분기 재생하는 범용 애니메이션 시스템 일반화 리팩토링 완료
- [x] `res://src/entities/units/guardian/` 폴더 내에 `guardian_unit.tscn` 씬을 설계 및 신설하여 가디언 모델의 스킨 및 계층 구조 연동 완료
- [x] `hud.gd` 스크립트를 수정하여 기존의 중복된 유닛 ID 버그를 해결(Striker 외형으로만 고정 스폰되던 현상 픽스)하고, Guardian 유닛 소환 시 전용 `guardian_unit.tscn`이 스폰되도록 연동 완료
- [x] 사용자가 직접 `striker_unit.tscn`에서 모델 Y축 회전 보정(180도)을 조치한 내용을 인지하고, `base_unit.gd` 스크립트 상에서 불필요해진 수동 회전 보정 코드부를 완전히 삭제하여 씬 지향적 설정을 완수
- [x] Striker 유닛의 뼈대 스켈레톤의 오른손 본(`RightHand`)에 `BoneAttachment3D` 노드를 런타임 동적 배치하고, `azure_blade.fbx` 검 무기를 텍스처 오버라이드 매핑(`azure_blade_0.png`)과 방향/크기 보정을 더해 안정적으로 쥐어주는 런타임 무기 장착 시스템 구현 완료 (스케일 150배 확대 적용 및 Z축 -0.6m 손잡이 쥠 정밀 오프셋 보정 완료)
- [x] 데이터와 UI/제어 로직의 느슨한 결합(Loose Coupling)을 위해 데이터 매니저 싱글톤 `DataManager` (`res://src/autoload/data_manager.gd`)을 신설하고 오토로드에 등록
- [x] `hud.gd`에 하드코딩되어 있던 5종 유닛 최초 세팅 데이터와 `stage_manager.gd`에 정의되어 있던 몬스터 스폰 스펙(HP 스케일링 공식 및 골드 리워드 테이블)을 모두 `DataManager` 싱글톤으로 온전히 이전 및 리팩토링 완료

---

### [x] 추가 디버깅 및 고도화 개선 내역
- [x] **구문 컴파일 오류 정비**
  - `unit_controller.gd` 내부의 존재하지 않는 `ceilf()`, `sqrtf()` 수학 함수를 Godot 4.x 내장 표준 함수인 `ceil()`, `sqrt()`로 교정 완료.
  - `base_monster.gd` 내부에서 Godot 4.x에서 폐기된 `rotates` 프로퍼티 주석 라인을 완전히 삭제하여 컴파일 실패 차단.
- [x] **몬스터 감지 및 수동 조작 마비 버그 픽스**
  - `base_monster.gd` 초기화 시 `add_to_group("monsters")`를 추가하여 유닛 자동 전투 AI가 적을 감지할 수 있도록 연계.
  - `unit_controller.gd` 내의 `_get_monster_node()` 및 `_get_unit_node()` 판정 방식을 단순 그룹 대조에서 클래스 타입 캐스팅 대조(`is BaseMonster`, `is BaseUnit`)로 강화하여 우클릭 공격 지정이 유실되지 않도록 정밀 수정.
- [x] **UI 입력 가로챔 차단 및 드래그 박스 정비**
  - 화면 전체를 덮는 `HUD` 씬의 루트 컨트롤 `mouse_filter`를 `2` (IGNORE)로 수정하여 마우스 좌/우클릭이 맵 바닥까지 안전하게 통과하도록 조치.
  - `UnitController` 마우스 필터 역시 IGNORE로 조율하고 입력 방식을 `_gui_input`에서 `_unhandled_input`으로 전면 변경하여 UI 클릭(예: 소환 버튼)과 순수 필드 클릭의 경계를 분리.
- [x] **RTS 전투 인공지능(AI) 고도화**
  - 유닛이 목적지로 이동하는 중이라도 주변에 몬스터가 포착되면 즉시 자동 추격/공격을 개시하도록 타겟팅 주기 튜닝.
  - 수동 긴급 대피(Flee) 시 즉시 복귀해 버리는 충돌을 막기 위해, 수동 이동 시 **1.5초간 어그로 인지를 임시 정지**시키는 쿨다운 장치 탑재.
- [x] **모바일(스마트폰) 스펙 축소 리스케일링**
  - 스마트폰 세로/가로 컴팩트 비율 가독성을 위해 지형 크기를 `50x50` $\rightarrow$ **`20x20`**으로 대폭 축소.
  - 몬스터 이동 경로 포인트를 맵 안쪽 **`(±8.5, ±8.5)`** 스케일로 축소.
  - 카메라 줌 조절 범위 **`5.0 ~ 18.0`** (기본 10.0), 스크롤 이탈 경계 **`(±8.0, ±8.0)`**, 유닛 탐지 반경 **`15.0m`**로 소형 맵 최적화 완료.
- [x] **원거리 유닛 3D 발사체 이펙트 시스템 탑재**
  - 원거리 유도 비행 발사체 엔티티 스크립트 작성 (`src/entities/units/projectile.gd`).
  - Ranger와 Archmage 공격 시, 즉발 대미지 대신 해당 유도 탄환을 어깨 높이에서 생성 발사하며 충돌 시점에 대미지가 연산되도록 구현.
  - 유닛 스펙 컬러에 동기화되는 빛 구슬 이펙트 머티리얼 적용. 컴파일 순환 참조 오류 우회를 위해 프리로드 동적 주입 기법 적용.
- [x] **RTS 조작 편의성 추가 (Shift 선택)**
  - `UnitController` 선택 루프 시 `Input.is_key_pressed(KEY_SHIFT)`를 확인하여, Shift 입력 상태에서는 선택을 초기화하지 않고 신규 대상을 중복 없이 `append`하는 추가/누적 선택 시스템 구현.

---

## ▣ 향후 계획 (Next Steps)

### [ ] 9단계: 사운드 피드백 및 3D 이펙트 연출 보강
- [ ] 몬스터 피격 시 간단한 3D 파티클 스파크 연출 구현
- [ ] 유닛 소환, 몬스터 타격, 사망, 스테이지 클리어 시 2D/3D 효과 오디오 플레이어 추가
- [ ] 원거리 유닛(Archmage 등)의 마법 광역 빔 또는 낙하 이펙트 추가

### [ ] 10단계: 밸런싱 및 게임 모드 세분화
- [ ] 라운드 증가에 따른 몬스터 외관 다형화 (크기 변형, 색상 변형)
- [ ] 유닛 판매(환급) 및 유닛 합성(조합) 업그레이드 시스템 기반 설계
- [ ] 웨이브 시작 수동 조절 모드 및 배속 플레이 기능 도입
