2nd/00_Raw/2026-04-22_LevelUp_Evolution_System.md

작업 로그: In-Game Level-Up & Evolution System (Phase 1~4) 전체 구현

📋 작업 내용 (What)

Skybound 프로젝트의 인게임 레벨업 및 진화 시스템을 4개 핵심 파일에 걸쳐 완전 구현.

🎯 왜 했는지 (Why)

기존 ProgressionSystem.ts에 EXP 수집, 레벨업, 진화 구조가 골격만 있었고:

• 게임 Pause 연동이 없어 카드 선택 중에도 전투가 진행됨
• 스킬 선택 후 엔진 내부 상태에 (engine as any).state 해킹으로 불완전 반영
• EVO 스탯 적용 로직 없음, 패시브 스킬 확장 불가
• 카드 풀 생성이 UI에서 무작위 생성되어 엔진 로직과 분리됨

💡 기대값 (Expected Value)

• 레벨업 시 게임 완전 Pause + 3지선다 카드 표시 → 선택 후 재개
• 스킬이 엔진 내부 state에 정확히 반영됨 (단방향 플로우)
• 진화 조건 달성 시 EVO 이펙트 + 스탯 즉시 반영
• TypeScript 타입 에러 0개

🔧 처리 과정 (How)

1. ProgressionSystem.ts (전면 재작성)

• handleLevelUp(): ctx.setPaused(true) 호출 후 generateSkillCards() 결과를 LEVEL_UP 이벤트에 포함
• generateSkillCards(): MAX_SKILL_SLOTS 가드, 소유 스킬 2x 가중치 Fisher-Yates 셔플
• applySkillSelection(ctx, skillId): 외부 콜백 포트 — UI에서 호출 → 엔진 state.skills 직접 업데이트 → setPaused(false)
• processEvolution(): EVOLUTION_RECIPES 레지스트리 기반 스캔으로 EVO 트리거
• syncPassives(): magnetRadius, speedBoost, fireRateBoost 패시브 스탯 매 프레임 동기화

2. useGameEngine.ts

• skillUpdaterRef 추가: React UI → 엔진 단방향 주입 포트
• ctx 선언 전 클로저 TDZ 방지를 위해 let ctx 패턴 사용
• applySkill() 메서드 훅 반환에 추가

3. GameSceneRenderer.tsx (전면 재작성)

• engineRef 패턴으로 hoisting 에러 제거
• handleEngineEvent에서 e.cards 수신 → levelUpCards state 저장
• handleSkillSelect: addSkill(store) + engine.applySkill(engine) 순서 보장
• LevelUpModal에 preGeneratedCards prop 전달

4. LevelUpModal.tsx (전면 재작성)

• preGeneratedCards prop 우선 사용 (엔진 결정론적 생성)
• 레벨 업그레이드 표시 (Lv.N → Lv.N+1)
• 빈 풀 처리 (Skip 옵션)

5. 타입 시스템 업데이트

• EffectiveStats: magnetRadius: number 추가
• GameEvent.LEVEL_UP: cards: string[] 추가
• createDefaultState: magnetRadius: 180 초기화
• calculateEffectiveStats: magnetRadius: 180 반환

6. AudioManager.ts

• playLevelUp(): C5→E5→G5→C6 상승 아르페지오 절차형 사운드
• playEvoSuccess(): 베이스 충격파 + 5음 하모닉 버스트 + 시머 레이어
• playSFX() 라우팅: 'level-up', 'evo-success' → 전용 메서드

🧠 사용한 지식 (Knowledge Used)

• JavaScript TDZ (Temporal Dead Zone): let ctx + closure 패턴
• Fisher-Yates 셔플 알고리즘 (결정론적 랜덤)
• Game Engine State-Driven Architecture (Pause Gate Pattern)
• React useRef 패턴 (closure staleness 방지)
• Web Audio API: OscillatorNode, BiquadFilterNode, GainNode 절차형 합성
• TypeScript 인터페이스 확장 원칙

✅ 결과 (Result)

TypeScript 타입 에러 0개 — npx tsc --noEmit 클린 통과

🔗 연결 지식 (Relevant Knowledge)

• E:\Wiki\2nd\10_Wiki\Topics\Game-Design (State Machine, Loop Design)
• E:\Wiki\2nd\10_Wiki\Topics\TypeScript-Patterns (Closure, TDZ, Ref Pattern)
• E:\Wiki\2nd\10_Wiki\Topics\Audio-Engineering (Procedural Sound Design)
• E:\Wiki\2nd\10_Wiki\Topics\Software-Architecture (Unidirectional Data Flow)