docs: update boss system technical reports and knowledge hub

2026-04-22 19:28:15 +09:00
parent f18790f898
commit 009ec6aa8f
25 changed files with 630 additions and 556 deletions
@@ -0,0 +1,39 @@
+# ⚙️ Engine Logic Optimization & Modernization
+
+**Category:** Architecture / Physics
+**Status:** Completed (v12.1)
+**Related:** [[01_Core_Engine/Game-Engine-Loop-and-System-Orchestration|Engine Loop]], [[03_Boss_Systems/Boss_Encounter_and_Timeline_Design|Boss Encounter Design]]
+
+---
+
+## 1. Tactical Logical Modernization
+Skybound의 초기 '무작위성' 중심 로직을 '의도된 연출' 중심으로 전환한 핵심 최적화 내역입니다.
+
+### 🛡️ Reactive Stat Sync (실시간 스탯 동기화)
+- **메커니즘**: `useGameStore.subscribe`를 통해 장비 교체나 영구 업그레이드 발생 시, 엔진의 `effectiveStats`를 런타임에 즉시 재계산.
+- **효과**: "인벤토리에서 공격력을 올렸는데 왜 바로 강해지지 않는가?"라는 모순을 해결.
+
+### 🛰️ Priority-Based Spawning (우선순위 기반 스폰)
+- **Logic**: 하드캡(`MAX_ENEMIES_HARD_CAP`) 도달 시, `ELITE` 이상의 등급은 일반 적(`NORMAL`)을 **강제 퇴거(Despawn)**시키고 자리를 확보함.
+- **효과**: 물량에 밀려 보스가 등장하지 못하는 치명적인 결함 방지.
+
+---
+
+## 2. Combat Physics & HP Revamp
+
+### 📏 100-Base HP System
+- **구형**: 하트 5칸 기반의 단순 생명력 시스템 (회복 및 성장 가시성 낮음).
+- **신규**: 100 기준의 체력 시스템으로 통합하여 퍼센트 단위 회복 및 영구 HP 업그레이드 반영이 가능하도록 구조화.
+
+### 💥 Mutual Knockback (물리 충돌)
+- 단순히 겹칠 때 대미지를 입는 방식에서 벗어나, 충돌 벡터(`vx`, `vy`)를 기반으로 서로 밀려나는 물리 작용 구현.
+- **타격감**: 기체 간 충돌 시의 '묵직함' 확보.
+
+---
+
+## 3. Engagement Compression
+- **Blitz Mode**: 보스 출현 시간을 **60초**로 단축하여 파밍 효율 극대화.
+- **Standard Mode**: 보스 조우 타임라인을 **2분**으로 압축하여 검증 및 플레이 텐션 강화.
+
+---
+**Last Updated:** 2026-04-22 🫡
@@ -0,0 +1,38 @@
+# 🔍 Skybound 엔진 구조 정밀 감사 보고서 (V12.1)
+
+> **카테고리**: [[Skybound]], [[Software Reliability]], [[Governance & Reliability]]
+> **상태**: ✅ 감사 완료 (Audited)
+> **최종 업데이트**: 2026-04-22
+
+---
+
+## 📌 개요 (Overview)
+엔진 안정성에 대한 의구심(코드 잘림, 상태 단절 등)이 제기됨에 따라, 전체 시스템 파이프라인(ECS-like Update, Zustand Sync, Progression Flow)을 전수 조사하여 아키텍처적 건전성을 검증함.
+
+## 📊 감사 요약 (Audit Summary)
+
+| 이슈 항목 | 실제 상태 | 심각도 | 판정 결과 |
+| :--- | :--- | :--- | :--- |
+| **#1 Engine Execution Gap** | **정상** — `ctx` 객체 완전 구성됨 | 🟢 Low | 단순 파일 읽기 초과로 인한 오판 |
+| **#2 State-Physics Disconnect** | **정상** — `setExp/setLevel` 액션 완결 | 🟢 Low | 15프레임 Dirty Checking 동기화 확인 |
+| **#3 Gimmick Manager 빈 껍데기** | **부분 유효** — 구현 완료, 타입 불일치 1건 | 🟡 Med | `spawnParticle` 인자 불일치 수정 완료 |
+| **#4 Collision-to-EXP 미연결** | **정상** — Combat → Progression 연결됨 | 🟢 Low | Gem 수집부터 카드 생성까지 연결 확인 |
+
+## 🛠️ 정밀 분석 (Detailed Analysis)
+
+### 1. 엔진 컨텍스트 (`ctx`) 및 루프 구조
+- **Context Integrity**: `useGameEngine.ts` 내에서 플레이어, 상태, 입력, 엔티티 매니저 및 각종 스폰 함수가 `ctx` 객체에 완전히 맵핑되어 각 시스템에 전달되고 있음.
+- **Loop Flow**: `StageDirector` → `System Logic` → `Combat/Progression` → `Renderer` 순의 고전적 ECS 파이프라인이 매 프레임(60FPS) 정상 작동함.
+
+### 2. 상태 관리 브릿지 (Store Sync)
+- **Zustand Interface**: 엔진 내부 상태(`state.currentExp` 등)와 외부 UI 스토어(`useGameStore`) 간의 데이터 동기화는 `useGameEngine.ts`에서 15프레임마다 수행되는 브릿지 로직을 통해 효율적으로 관리됨 (불필요한 React Re-render 방지).
+
+### 3. 실제 수정 사항 (Bug Fix)
+- **GravityGimmick.ts**: `ctx.spawnParticle` 호출 시 엔진 시그니처와 불일치하는 5번째 인자(`'DIR'`)가 전달되는 문제를 식별하여 제거함. 이는 시스템 오류를 유발하지는 않으나 타입 정결성을 위해 조치됨.
+
+## 📋 최종 결론
+Skybound 엔진은 **구조적으로 건강하며, 모든 핵심 파이프라인이 완전히 구현된 상태**임. 향후 확장을 위한 아키텍처적 기반(Intent Protocol, Signal Pattern)이 견고하게 구축되어 있음을 확인함.
+
+---
+**승인인**: AI 개발부장 코다리 🫡
+**관련 문서**: [[02_Architecture_Principles]], [[Visual_Feedback_Signal_Pattern]]