# 🔄 In-Game Progression & Evolution (인게임 성장 및 진화 시스템)

> **카테고리**: Skybound, Game Design, Software Architecture
> **상태**: 🔵 구현 완료 (Implemented)
> **최종 업데이트**: 2026-04-22

---

## 📌 개요 (Overview)
Skybound의 인게임 성장은 EXP 수집을 통한 레벨업, 3지선다 스킬 선택, 그리고 특정 조건 만족 시 발생하는 '진화(Evolution)'로 구성된다. 이 시스템은 게임 엔진의 상태 기계(State Machine)와 React UI 간의 단방향 데이터 흐름을 기반으로 동작한다.

## 🛠️ 핵심 메커니즘 (Core Mechanisms)

### 1. 레벨업 프로세스 (Level-Up Pipeline)
- **EXP 수집**: 적 처치 시 드롭되는 젬을 수집하여 `exp` 게이지가 차오르면 트리거됨.
- **Pause Gate Pattern**: 레벨업 발생 시 엔진은 즉시 `setPaused(true)`를 호출하여 인게임을 멈추고, `LEVEL_UP` 이벤트를 UI로 발송한다.
- **결정론적 카드 생성**: 카드 풀은 UI가 아닌 `ProgressionSystem` 엔진 로직 내에서 생성되어 전달되므로, 엔진의 상태와 UI가 항상 동기화된다.
- **Resume**: 플레이어가 카드를 선택하면 `applySkillSelection`을 통해 엔진 state가 업데이트되고 다시 `setPaused(false)`로 재개된다.

### 2. 진화 시스템 (Evolution / EVO)
- **발동 조건**: 주 무기(Primary Skill)가 최대 레벨에 도달하고, 특정 보조 무기(Support Skill)를 보유하고 있을 때 다음 레벨업 시 발생.
- **NOVA_GUARDIAN**: `aoe_nova` (Lv.3 MAX) + `energy_shield` (Lv.1+) 조합의 진화형.
- **EVO 효과**: 단순히 데미지가 증가하는 것이 아니라, 쿨다운 대폭 감소, 반경 확장, 시각적 강화(황금색), 그리고 발동 시 짧은 무적(Shield Burst) 등의 유틸리티 성능이 추가된다.

### 3. 패시브 동기화 (Passive Sync)
- 패시브 스킬(Fire Rate, Speed, Magnet)은 `syncPassives()`를 통해 매 프레임 플레이어의 `EffectiveStats`에 주입되어 즉각적인 성능 변화를 체감하게 한다.

## 💡 주요 설계 패턴 (Design Patterns)

### 1. TDZ (Temporal Dead Zone) 회피 패턴
- `useGameEngine` 내에서 `ctx` 선언 전 클로저 참조 문제를 해결하기 위해 `let ctx` 선언 후 나중에 할당하는 패턴을 사용하여 초기화 안정성을 확보함.

### 2. 단방향 데이터 흐름 (Unidirectional Data Flow)
- UI는 엔진의 상태를 직접 수정하지 않고, `applySkill` 콜백을 통해서만 의사결정을 엔진에 주입한다.

---
**승인인**: AI 개발부장 코다리 🫡
**관련 코드**: `ProgressionSystem.ts`, `evolutions.ts`, `GameSceneRenderer.tsx`, `useGameEngine.ts`