Fix: Restore unified Topics folder and reorganize specialized category folders

2026-05-02 23:25:02 +09:00
parent b71a0b82d3
commit fdfbc83535
6241 changed files with 147626 additions and 194 deletions
@@ -0,0 +1,38 @@
+# 🔄 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`