docs: sync recent Combat Progression and Stat Injection mechanics to Wiki

2026-04-22 13:45:53 +09:00
parent 7835487b0a
commit f18790f898
16 changed files with 456 additions and 46 deletions
@@ -0,0 +1,25 @@
+# [LOG] All Repositories Update (Full Sync)
+
+- **작업 일시**: 2026-04-22
+- **작업 내용**: 4개 주요 프로젝트 거점(`2nd`, `skybound`, `Legal`, `Agent`)에 대한 원격 저장소 동기화(`git pull`).
+- **이유/목적**: 로컬 작업 환경을 최신 상태로 유지하여 개발 및 문서화 작업 시 발생할 수 있는 충돌을 방지하고 코드 정합성을 확보하기 위함.
+- **기대값**: 
+    1. 모든 로컬 브랜치가 최신 원격 브랜치(`main`)와 동기화됨.
+    2. 동기화 과정에서 에러 및 수동 충돌 해결 작업 0건 유지.
+- **처리 과정**: 
+    1. `2nd` (Wiki): `git pull lm_sync main` 진행 -> 최신 상태 확인.
+    2. `skybound`: `git pull origin main` 진행 -> 최신 상태 확인.
+    3. `Legal`: `git pull origin main` 진행 -> 최신 상태 확인.
+    4. `Agent`: `git pull origin main` 진행 -> 최신 상태 확인.
+- **사용 지식**: 
+    1. Git Remote Operations (`git pull`)
+    2. Local Git Mapping Protocol (신규 수립 지침)
+- **결과**: 
+    *   4개 프로젝트 모두 성공적으로 `Already up to date` 또는 최신 커밋 반영 완료.
+    *   작업 경로 및 리모트 명칭(lm_sync vs origin) 혼선 없이 처리됨.
+- **연결 지식 (Relevant Knowledge)**: 
+    *   [[E:\Wiki\2nd\10_Wiki\Topics\03_DevOps_Environment]] (데브옵스 및 환경 구성)
+    *   [[E:\Wiki\2nd\10_Wiki\Topics\Automation]] (작업 자동화)
+
+---
+**작성자**: AI 개발부장 코다리 🫡
@@ -0,0 +1,66 @@
+# 작업 로그: Combat Level Design — Time-Based Difficulty Scaling 구현
+
+## 📋 작업 내용 (What)
+"전투 타임라인 & 난이도 프로토콜" 설계안을 기반으로 Skybound 프로젝트의
+StageDirectorSystem, SpawnerSystem, EngineProtocol을 업그레이드하고,
+신규 CombatTimeline 설정 파일을 추가함.
+
+## 🎯 왜 했는지 (Why)
+기존 스테이지 시스템의 문제점:
+- StageDirectorSystem: 하드코딩된 `if frame >= X` 체이닝, 새 phase 추가 불가
+- SpawnerSystem: 완전 무작위 스폰 → 스파이크 없음, 긴장감 없음
+- 난이도 곡선 부재: 적 HP 단순 배율만 존재, 밀도/타이밍 변화 없음
+- Death Trap 발생 가능: EVO 준비 없이 Spike 구간 진입
+
+## 💡 기대값 (Expected Value)
+- 시간(초) 기반 스크립티드 웨이브 등장 (STANDARD 15분 / BLITZ 8분)
+- 페이즈별 difficultyMult / spawnIntervalMult 자동 동기화
+- Spike 30초 전 자동 EXP 젬 밀도 2배 부스트 (Death Trap Avoidance)
+- 스웜 구간에서 최대 6유닛씩 3프레임 간격 분산 스폰 (성능 보장)
+- 보스 처치 후 영구 성장 보상 발행 (UX Continuity)
+- TypeScript 에러 0개
+
+## 🔧 처리 과정 (How)
+
+### 1. CombatTimeline.ts (신규 생성)
+- StageMode: STANDARD(15분) / BLITZ(8분)
+- DifficultyPhase: name, startSec, diffMult, spawnIntervalMult, maxEnemyCount, bgmCue
+- WaveTrigger: triggerSec, enemyType, density, isSpike, eventEffect, comms, shake
+- STANDARD_TIMELINE: 5개 페이즈, 15개 WaveTrigger (Spike 4회)
+- BLITZ_TIMELINE: 5개 페이즈, 10개 WaveTrigger (Spike 6회)
+- 유틸 함수: getActivePhase(), collectDueTriggers(), getTimeline()
+
+### 2. StageDirectorSystem.ts (전면 재작성 v2.0)
+- tickTimeline(): 매 프레임 currentSec = frame/60로 getActivePhase() 및 collectDueTriggers() 호출
+- 페이즈 자동 전환: activePhase.name !== phase일 때 STAGE_TRANSITION 인텐트 발행
+- difficultyMult / tensionLevel: activePhase.diffMult + densityFactor로 자동 동기화
+- EXP 밀도 부스트: 다음 Spike까지 30초 이내 시 EXP_DENSITY_BOOST 인텐트 발행
+- processTriggers(): WaveTrigger → 이벤트(COMMS, SCREEN_SHAKE) + SCRIPTED_SPAWN 인텐트
+- UX Continuity: 보스 처치 시 PERMANENT_REWARD 인텐트 발행
+
+### 3. SpawnerSystem.ts (전면 재작성 v2.0)
+- notifyScriptedSpawn(): Director로부터 스폰 요청 수신 (메서드 호출 방식)
+- flushSpawnQueue(): 큐 소비 + MAX_ENEMIES_HARD_CAP(=30) 보호막
+- activateSwarmBurst(): SWARM_BURST 모드 활성화
+- tickSwarmBurst(): MAX_SWARM_BATCH(=6), SWARM_SPAWN_GAP(=3프레임) 분산 스태거링
+- 절차적 스폰: difficultyMult 기반 간격 계산, 타임라인 간격 채우기 보조 역할
+- dispose(): 큐 + 버스트 상태 초기화
+
+### 4. EngineProtocol.ts (확장)
+- SCRIPTED_SPAWN, SPAWN_MODE, EXP_DENSITY_BOOST, PERMANENT_REWARD 인텐트 타입 추가
+
+## 🧠 사용한 지식 (Knowledge Used)
+- Time-Based Difficulty Scaling 패턴
+- Object Pool + Staggered Spawn 패턴 (성능 최적화)
+- "Death Trap Avoidance" 게임 디자인 원칙
+- "UX Continuity" 실패 보상 설계
+- TypeScript discriminated union (EngineIntentType)
+- Observer → Direct Method Call 결정 (EventBus 미도입 상태에서의 최적 통신 방식)
+
+## ✅ 결과 (Result)
+TypeScript 에러 0개 — `npx tsc --noEmit` 클린 통과
+
+## 🔗 연결 지식 (Relevant Knowledge)
+- E:\Wiki\2nd\10_Wiki\Topics\Game-Design (Difficulty Curve, Spike Design, Time-Based Scaling)
+- E:\Wiki\2nd\10_Wiki\Topics\Software-Architecture (Intent Protocol, Event-Driven)
+- E:\Wiki\2nd\10_Wiki\Topics\Performance-Optimization (Staggered Spawn, Object Pooling)
@@ -0,0 +1,98 @@
+# [RAW LOG] 2026-04-22 — Crafting System Full Activation
+
+## 작업 개요
+- 날짜: 2026-04-22
+- 세션: Skybound Crafting Economy Full Integration (Option B)
+- Git: `facb2ba` → `9e0110d`
+
+---
+
+## 1. 감사 결과 (진단)
+
+| 항목 | 이전 상태 |
+|------|----------|
+| `mergeEquipment()` | ✅ HangarOverlay에서만 연결됨 |
+| `cosmicCast()` | ❌ 호출처 없음 |
+| `astralForge()` | ❌ 호출처 없음 |
+| `disassemble()` | ❌ 호출처 없음 |
+| `mergeTechPart()` | ❌ 호출처 없음 |
+| `techParts`, `materials` 상태 | ❌ 선언만 있고 실제 데이터 입출력 없음 |
+
+---
+
+## 2. 구현 내역
+
+### A. `useGameStore.ts` — 크래프팅 액션 전면 활성화
+- `addMaterials(mats)`: TechMats/Core 획득 시 상태 누적
+- `addTechPart(part)`: 드롭된 TechPart 인벤토리 추가
+- `disassembleItems(ids)`: 선택 아이템 일괄 분해 → 재료 획득 + 슬롯 해제
+- `cosmicCastAction()`: 재료(Eternal×50, Destruction×50, Tech×2000) 소모 → SS급 장비 생성
+- `astralForgeAction(targetId, sacrificeId)`: LEGEND/SS 대상 + S급 희생 → forgeLevel +1
+- `mergeTechPartAction(targetId, fodderIds)`: 동일 티어/스킬 TechPart 합성 → plusLevel +1
+
+### B. `HangarOverlay.tsx` — 5탭 크래프팅 UI 전면 재작성
+| 탭 | 기능 |
+|----|------|
+| 🔩 EQUIP | 기존 장착 슬롯 + 인벤토리 |
+| ⬆ MERGE | 장비 합성(3개) + TechPart 합성(2개) |
+| 🔧 DISASSEMBLE | 선택 아이템 분해 + 재료 미리보기 |
+| ✦ COSMIC CAST | SS급 제작 재료 요구량 체크 + 실행 |
+| ⚒ FORGE | TARGET/SACRIFICE 슬롯 선택 → forgeLevel +1 |
+
+- 재료 패널(TechMats, Eternal, Destruction, Relic)을 좌측 패널에 항상 표시
+- Feedback Toast: 성공/실패 3초 표시
+
+### C. `HangarOverlay.css` — 새 스타일 추가
+- `.craft-tabs`, `.craft-tab-btn` — 5탭 네비게이션
+- `.materials-panel`, `.mat-grid` — 재료 표시
+- `.disassemble-preview` — 분해 미리보기 패널
+- `.cosmic-recipe`, `.cosmic-result-preview` — 코스믹 캐스트
+- `.forge-slots`, `.forge-slot-box` — 포지 슬롯 UI
+- `.craft-feedback` — 피드백 토스트 애니메이션
+- `.tech-list`, `.tech-row` — TechPart 목록
+
+### D. `CombatSystem.ts` — 재료 드롭 연결
+- 일반 적: 3% 확률 TechMats 10~30 획득
+- 엘리트 적: 10% 확률 TechMats 50~100 획득 + 파란 텍스트 알림
+- 엘리트 적: 5% 확률 TechPart 드롭 → 보라색 텍스트 알림
+
+### E. `LootGenerator.ts` — `rollTechPart()` 신규 추가
+- 6종 스킬 풀: fire_rate / speed_boost / magnet_range / damage_up / shield / missile
+- 스테이지 연동 티어: Stage 1-2→EXCELLENT, 3-4→EPIC, 5+→LEGEND
+
+---
+
+## 3. 경제 흐름 (완성된 파이프라인)
+
+```
+적 처치 (일반 3% / 엘리트 10%)
+    ↓
+addMaterials({ techMats })
+    ↓
+HangarOverlay [DISASSEMBLE 탭] → 불필요 장비 분해 → Eternal/Destruction Core 획득
+    ↓
+HangarOverlay [COSMIC CAST 탭] → 코스믹 캐스트 → SS급 장비 생성
+    ↓
+HangarOverlay [FORGE 탭] → SS/LEGEND 장비 forgeLevel +1~5
+
+엘리트 처치 (5%)
+    ↓
+addTechPart()
+    ↓
+HangarOverlay [MERGE 탭] → TechPart 합성 → plusLevel +1
+```
+
+---
+
+## 4. TypeScript & Git
+- `npx tsc --noEmit`: **에러 0개 ✅**
+- Commit: `feat_crafting_full_ui_economy` (`9e0110d`)
+- Push: `main` ✅
+
+---
+
+## 5. 다음 과제 (Next Steps)
+1. **보스 처치 시 Eternal/Destruction Core 보장 드롭** 추가
+2. **코스믹 캐스트 결과 다양화** — Twin Lance 외 랜덤 SS급 풀 확장
+3. **TechPart 효과 실제 반영** — 인게임 스탯에 plusLevel 반영 로직
+4. **UI 시각 검증** — `http://localhost:5174/` 5탭 동작 확인
@@ -0,0 +1,27 @@
+# [LOG] Git Operation Mapping Protocol & Work Log System Setup
+
+- **작업 일시**: 2026-04-22
+- **작업 내용**: 구역별 Git 명령어 맵핑(Wiki, Skybound, Legal, Agent) 및 작업 자동 기록 시스템(Work Log) 수립.
+- **이유/목적**: 대표님의 명령 한마디로 복잡한 Git 작업을 정확한 경로와 저장소에 수행하고, 모든 AI 작업 과정을 체계적으로 문서화하여 누락 없는 히스토리 관리를 하기 위함.
+- **기대값**: 
+    1. Git 작업 시 경로 혼선 및 저장소 오류 0건 달성.
+    2. 모든 작업의 의도, 지식, 결과가 md 파일로 축적되어 추후 지식 베이스 강화에 기여.
+- **처리 과정**: 
+    1. 각 프로젝트별(`2nd`, `skybound`, `Legal`, `Agent`) 현재 Git 설정 확인.
+    2. 대표님 지시 URL과 로컬 설정 대조 및 필요 시 `set-url`로 업데이트.
+    3. 각 폴더에 `GIT_PROTOCOL.md`를 생성하여 명문화.
+    4. `E:\Wiki\2nd\00_Raw` 경로에 작업 일지 작성 시스템 가동.
+- **사용 지식**: 
+    *   Git Remote Management (`git remote set-url`)
+    *   Organizational Process Assets (OPA) 구축 방법론
+    *   Markdown 기반 기술 문서 표준화
+- **결과**: 
+    *   4개 주요 거점의 Git 맵핑 완료 및 승인 대기.
+    *   첫 번째 작업 로그(`2026-04-22_Git_Protocol_Setup.md`) 생성 완료.
+- **연결 지식 (Relevant Knowledge)**: 
+    *   [[E:\Wiki\2nd\10_Wiki\Topics\04_Governance_Reliability]] (거버넌스 및 신뢰성)
+    *   [[E:\Wiki\2nd\10_Wiki\Topics\Automation]] (자동화)
+    *   [[E:\Wiki\2nd\10_Wiki\Topics\Skybound]] (프로젝트 연계)
+
+---
+**작성자**: AI 개발부장 코다리 🫡
@@ -0,0 +1,70 @@
+# 작업 로그: 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)