Add Voltex engine design specification

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/superpowers/specs/2026-03-24-voltex-engine-design.md

@@ -0,0 +1,447 @@
+# Voltex Engine - Design Specification
+
+## Overview
+
+Voltex는 Rust로 작성되는 AAA급 3D 게임 엔진이다.
+포트폴리오, 프로덕션, 기술 연구를 모두 목표로 한다.
+
+- **언어**: Rust
+- **타겟 플랫폼**: PC (Windows, Linux, macOS) + 콘솔 + 모바일
+- **에디터**: 초기에는 코드 기반, 추후 GUI 에디터 추가
+
+---
+
+## Architecture
+
+레이어 구조로 설계한다. 하위 레이어는 상위 레이어에 의존하지 않는다.
+
+```
+┌─────────────────────────────────┐
+│         Game / App Layer        │  사용자 게임 코드
+├─────────────────────────────────┤
+│        Scripting Layer          │  추후 구현 (Lua 등)
+├─────────────────────────────────┤
+│        Engine Systems           │  물리, 오디오, AI, 네트워크
+├─────────────────────────────────┤
+│     Scene / ECS Framework       │  엔티티, 컴포넌트, 시스템
+├─────────────────────────────────┤
+│     Rendering Pipeline          │  PBR, GI, 레이트레이싱
+├─────────────────────────────────┤
+│   Graphics Abstraction (wgpu)   │  Vulkan/DX12/Metal/WebGPU
+├─────────────────────────────────┤
+│     Platform Layer (winit)      │  윈도우, 입력, OS 추상화
+└─────────────────────────────────┘
+```
+
+### 의존성 규칙
+
+- 각 레이어는 바로 아래 레이어에만 의존한다.
+- 레이어를 건너뛰는 의존은 허용하지 않는다.
+- 같은 레이어 내 모듈 간 순환 의존을 금지한다.
+
+---
+
+## 외부 라이브러리 vs 자체 구현
+
+### 외부 라이브러리 (2개만 사용)
+
+| 라이브러리 | 버전 | 역할 | 라이선스 |
+|-----------|------|------|---------|
+| winit | latest | 크로스플랫폼 윈도우 생성, 키보드/마우스/터치 입력 | Apache 2.0 |
+| wgpu | latest | Vulkan/DX12/Metal/WebGPU 그래픽스 API 추상화 | MIT / Apache 2.0 |
+
+- 라이선스 의무: 출처 표기, 변경 명시 (Apache 2.0)
+- 상업적 사용 자유, 로열티 없음, 소스 공개 의무 없음
+
+### 자체 구현
+
+| 시스템 | 설명 |
+|--------|------|
+| 수학 라이브러리 | Vec2, Vec3, Vec4, Mat3, Mat4, Quaternion, Transform, AABB, Ray, Plane |
+| 렌더링 파이프라인 | 포워드/디퍼드 렌더링, PBR, GI, 레이트레이싱, 포스트 프로세싱 |
+| ECS 프레임워크 | 엔티티, 컴포넌트 스토리지, 시스템 스케줄링, 쿼리 |
+| 씬 관리 | 씬 그래프, 부모-자식 트랜스폼 계층, 씬 직렬화/역직렬화 |
+| 에셋 시스템 | 에셋 로딩, 캐싱, 핫 리로드, 포맷 변환 |
+| 물리 엔진 | 충돌 감지 (AABB, GJK/SAT), 리지드바디 시뮬레이션, 레이캐스팅 |
+| 오디오 시스템 | 사운드 로딩/재생, 3D 공간 오디오, 믹서 |
+| AI | 내비메시 생성, A* 패스파인딩 |
+| 네트워킹 | 클라이언트-서버 아키텍처, UDP 기반 |
+| 스크립팅 | Lua 바인딩 또는 자체 스크립트 언어 (추후 결정) |
+
+---
+
+## 구현 단계
+
+### Phase 1: 기반 (Foundation)
+
+**목표**: 윈도우에 삼각형 하나를 렌더링한다.
+
+#### 1-1. 수학 라이브러리 (`voltex_math`)
+
+**타입**:
+- `Vec2`, `Vec3`, `Vec4` — 벡터 (f32 기반)
+- `Mat3`, `Mat4` — 행렬
+- `Quat` — 쿼터니언 (회전)
+- `Transform` — Position + Rotation(Quat) + Scale
+- `AABB` — Axis-Aligned Bounding Box
+- `Ray` — 원점 + 방향
+- `Plane` — 법선 + 거리
+
+**연산**:
+- 벡터: 덧셈, 뺄셈, 스칼라 곱, 내적, 외적, 정규화, 길이, lerp
+- 행렬: 곱셈, 전치, 역행렬, look_at, perspective, orthographic
+- 쿼터니언: 곱셈, slerp, from_axis_angle, from_euler, to_mat4
+- Transform: 로컬→월드 변환, 부모-자식 결합
+
+**최적화**:
+- 초기에는 순수 Rust 구현 (정확성 우선)
+- 추후 SIMD 최적화 (`std::arch` 또는 `core::simd`)
+
+**테스트**:
+- 모든 연산에 대해 단위 테스트
+- glam 라이브러리 결과와 교차 검증
+
+#### 1-2. 윈도우 + 입력 (`voltex_platform`)
+
+**윈도우**:
+- winit을 래핑하는 `Window` 구조체
+- 생성 파라미터: 제목, 크기, 풀스크린 여부, vsync
+- 리사이즈 이벤트 처리
+
+**입력**:
+- `InputState` — 현재 프레임의 입력 상태
+- 키보드: `is_key_pressed(key)`, `is_key_just_pressed(key)`, `is_key_released(key)`
+- 마우스: 위치, 델타, 버튼 상태, 스크롤
+- 이벤트 큐 방식이 아닌 폴링 방식 (게임 루프에 적합)
+
+**게임 루프**:
+- 고정 타임스텝 + 가변 렌더링
+- `fixed_update(dt)` — 물리/로직 (고정 간격, 기본 60Hz)
+- `update(dt)` — 프레임별 로직
+- `render(alpha)` — 보간 기반 렌더링
+
+```
+while running {
+    accumulator += frame_time;
+    while accumulator >= FIXED_DT {
+        fixed_update(FIXED_DT);
+        accumulator -= FIXED_DT;
+    }
+    let alpha = accumulator / FIXED_DT;
+    update(frame_time);
+    render(alpha);
+}
+```
+
+#### 1-3. 렌더러 초기화 (`voltex_renderer`)
+
+**wgpu 초기화**:
+- Instance → Adapter → Device + Queue 생성
+- Surface 설정 (윈도우와 연결)
+- 기본 렌더 패스 구성
+
+**첫 렌더링**:
+- 하드코딩된 삼각형 정점 데이터
+- 기본 버텍스/프래그먼트 셰이더 (WGSL)
+- 파이프라인 생성 및 렌더링
+
+**Phase 1 완료 기준**: 윈도우가 열리고, 색이 있는 삼각형이 보이며, ESC로 종료할 수 있다.
+
+---
+
+### Phase 2: 렌더링 기초
+
+**목표**: 3D 모델을 로딩하고 카메라로 돌려볼 수 있다.
+
+#### 2-1. 메시 시스템
+
+- `Mesh` 구조체: 정점 버퍼 (position, normal, uv, tangent) + 인덱스 버퍼
+- OBJ 파서 자체 구현 (간단한 포맷부터)
+- 추후 glTF 파서 추가
+- GPU 버퍼 업로드 및 관리
+
+#### 2-2. 카메라
+
+- `Camera` 구조체: position, rotation, fov, near, far
+- Perspective / Orthographic 프로젝션
+- FPS 스타일 카메라 컨트롤러 (마우스 + WASD)
+- View-Projection 행렬 계산 (자체 수학 라이브러리 사용)
+
+#### 2-3. 기본 라이팅
+
+- Blinn-Phong 셰이딩 모델
+- Directional Light 1개
+- Ambient + Diffuse + Specular
+
+#### 2-4. 텍스처
+
+- PNG/JPG 이미지 디코딩 (자체 구현 또는 최소한의 디코더)
+- GPU 텍스처 업로드
+- 샘플러 설정 (필터링, 래핑)
+
+**Phase 2 완료 기준**: .obj 모델을 로딩하고, 텍스처를 입히고, 카메라로 돌려볼 수 있다.
+
+---
+
+### Phase 3: ECS + 씬
+
+**목표**: 데이터 주도 아키텍처로 다수의 오브젝트를 관리한다.
+
+#### 3-1. ECS 프레임워크
+
+**엔티티**:
+- 경량 ID (u32 또는 u64)
+- 생성/삭제, 세대(generation) 관리로 dangling 참조 방지
+
+**컴포넌트 스토리지**:
+- Archetype 기반 스토리지 (같은 컴포넌트 조합을 가진 엔티티를 연속 메모리에 배치)
+- 캐시 친화적 순회
+- 동적 컴포넌트 추가/제거 시 아키타입 마이그레이션
+
+**시스템**:
+- 시스템 = 특정 컴포넌트 조합을 쿼리하여 처리하는 함수
+- 실행 순서 지정 (의존성 기반 스케줄링)
+- 추후 병렬 실행 지원
+
+**쿼리**:
+- `Query<(&Position, &mut Velocity)>` 스타일
+- 필터: With, Without, Changed
+
+#### 3-2. 씬 그래프
+
+- 부모-자식 트랜스폼 계층
+- 로컬 트랜스폼 → 월드 트랜스폼 자동 계산
+- 씬 직렬화/역직렬화 (JSON 또는 바이너리)
+
+#### 3-3. 에셋 매니저
+
+- 에셋 타입별 로더 등록
+- 핸들 기반 참조 (경로 → 핸들 → 에셋)
+- 참조 카운팅으로 메모리 관리
+- 비동기 로딩 지원
+- 핫 리로드 (파일 변경 감지 → 자동 리로드)
+
+**Phase 3 완료 기준**: ECS로 수백 개의 엔티티를 생성하고, 각각 위치/메시/머티리얼 컴포넌트를 가지며, 씬을 저장/로드할 수 있다.
+
+---
+
+### Phase 4: PBR 렌더링
+
+**목표**: 물리 기반 렌더링으로 사실적인 머티리얼을 표현한다.
+
+#### 4-1. PBR 머티리얼
+
+- Metallic-Roughness 워크플로 (glTF 표준)
+- 텍스처 맵: Albedo, Normal, Metallic, Roughness, AO, Emissive
+- Cook-Torrance BRDF (GGX 분포, Smith 기하, Fresnel-Schlick)
+
+#### 4-2. 다중 라이트
+
+- Directional Light (태양)
+- Point Light (감쇠 포함)
+- Spot Light (각도 + 감쇠)
+- 라이트 컬링 (타일/클러스터 기반)
+
+#### 4-3. 섀도우
+
+- Directional Light: Cascaded Shadow Maps (CSM)
+- Point Light: Omnidirectional Shadow Maps (큐브맵)
+- Spot Light: 단일 Shadow Map
+- PCF (Percentage Closer Filtering) 소프트 섀도우
+
+#### 4-4. IBL (Image-Based Lighting)
+
+- 환경맵 (HDR 큐브맵)
+- Diffuse Irradiance Map
+- Specular Pre-filtered Environment Map
+- BRDF LUT
+
+**Phase 4 완료 기준**: 금속, 나무, 돌 등 다양한 머티리얼이 사실적으로 보이며, 여러 종류의 광원과 그림자가 작동한다.
+
+---
+
+### Phase 5: 물리 엔진
+
+**목표**: 기본적인 물리 시뮬레이션이 동작한다.
+
+#### 5-1. 충돌 감지
+
+**Broad Phase**:
+- AABB 기반 BVH (Bounding Volume Hierarchy)
+- SAP (Sweep and Prune) 알고리즘
+
+**Narrow Phase**:
+- GJK (Gilbert-Johnson-Keerthi) 알고리즘
+- EPA (Expanding Polytope Algorithm) — 침투 깊이
+- 지원 콜라이더: Sphere, Box, Capsule, Convex Hull
+
+#### 5-2. 리지드바디 시뮬레이션
+
+- 질량, 관성 텐서, 중력
+- 속도/각속도 적분 (Semi-implicit Euler)
+- 충돌 응답: 임펄스 기반 해결
+- 마찰 (Coulomb)
+- 제약 조건 솔버 (Sequential Impulse)
+
+#### 5-3. 레이캐스팅
+
+- Ray vs AABB, Sphere, Plane, Triangle, Mesh
+- BVH 가속 구조를 이용한 빠른 레이캐스트
+
+**Phase 5 완료 기준**: 상자와 구가 떨어지고, 바닥과 충돌하고, 서로 밀어내며, 레이캐스트로 오브젝트를 선택할 수 있다.
+
+---
+
+### Phase 6: 오디오 시스템
+
+**목표**: 게임에 사운드를 추가할 수 있다.
+
+#### 6-1. 오디오 백엔드
+
+- 플랫폼별 오디오 출력 (WASAPI/CoreAudio/ALSA)
+- 또는 `cpal` crate를 최소한으로 사용 (PCM 출력만)
+- 오디오 스레드 분리
+
+#### 6-2. 사운드 재생
+
+- WAV 파서 자체 구현
+- OGG/Vorbis 디코더 (추후)
+- 재생, 일시정지, 정지, 볼륨, 루프
+
+#### 6-3. 3D 오디오
+
+- 거리 기반 감쇠
+- 패닝 (스테레오)
+- 도플러 효과 (추후)
+
+#### 6-4. 믹서
+
+- 채널/그룹 기반 믹싱 (BGM, SFX, Voice 등)
+- 볼륨 페이드 인/아웃
+
+**Phase 6 완료 기준**: 3D 공간에서 소리가 위치에 따라 다르게 들리며, BGM과 SFX를 독립적으로 제어할 수 있다.
+
+---
+
+### Phase 7: 고급 렌더링
+
+**목표**: AAA급 비주얼 퀄리티에 도달한다.
+
+#### 7-1. 디퍼드 렌더링
+
+- G-Buffer: Position, Normal, Albedo, Metallic-Roughness, Depth
+- 라이팅 패스 분리
+- 다수의 라이트를 효율적으로 처리
+
+#### 7-2. Global Illumination
+
+- Screen-Space GI (SSGI) 또는
+- Voxel-based GI (VXGI) 또는
+- Light Probe 기반 GI
+- (구현 시점에 기술 선택)
+
+#### 7-3. 레이트레이싱
+
+- wgpu의 레이트레이싱 확장 활용
+- RT Shadows, RT Reflections, RT AO
+- 하이브리드 렌더링 (래스터 + RT)
+
+#### 7-4. 포스트 프로세싱
+
+- HDR 렌더링 + 톤매핑 (ACES, Filmic 등)
+- Bloom
+- SSAO (Screen-Space Ambient Occlusion)
+- SSR (Screen-Space Reflections)
+- Motion Blur
+- Depth of Field
+- Anti-Aliasing (TAA)
+
+**Phase 7 완료 기준**: 디퍼드 렌더링으로 수백 개의 라이트를 처리하고, GI/RT/포스트 프로세싱이 적용된 씬이 AAA 수준으로 보인다.
+
+---
+
+### Phase 8: 확장
+
+**목표**: 엔진을 완전한 게임 개발 도구로 확장한다.
+
+#### 8-1. AI
+
+- 내비메시 생성 (Recast 스타일 알고리즘)
+- A* 패스파인딩
+- 스티어링 행동 (Seek, Flee, Arrive, Wander)
+
+#### 8-2. 네트워킹
+
+- UDP 소켓 기반
+- 클라이언트-서버 아키텍처
+- 상태 동기화 (스냅샷 + 보간)
+- 지연 보상
+
+#### 8-3. 스크립팅
+
+- Lua 바인딩 또는 자체 스크립트 언어
+- 핫 리로드 지원
+- 엔진 API 노출 (엔티티 생성/삭제, 컴포넌트 접근 등)
+
+#### 8-4. 에디터 (GUI)
+
+- egui 또는 자체 UI 시스템
+- 씬 뷰포트 (3D 뷰)
+- 엔티티 인스펙터
+- 에셋 브라우저
+- 실시간 프리뷰
+
+**Phase 8 완료 기준**: 에디터에서 씬을 편집하고, AI 에이전트가 내비메시를 따라 이동하며, 멀티플레이어 테스트가 가능하다.
+
+---
+
+## 프로젝트 구조
+
+```
+voltex/
+├── Cargo.toml              # 워크스페이스
+├── crates/
+│   ├── voltex_math/        # 수학 라이브러리
+│   ├── voltex_platform/    # 윈도우, 입력, 게임 루프
+│   ├── voltex_renderer/    # 렌더링 파이프라인
+│   ├── voltex_ecs/         # ECS 프레임워크
+│   ├── voltex_scene/       # 씬 관리
+│   ├── voltex_asset/       # 에셋 시스템
+│   ├── voltex_physics/     # 물리 엔진
+│   ├── voltex_audio/       # 오디오 시스템
+│   ├── voltex_ai/          # AI 시스템
+│   ├── voltex_net/         # 네트워킹
+│   ├── voltex_script/      # 스크립팅
+│   └── voltex_editor/      # 에디터 (추후)
+├── examples/               # 예제/데모
+├── assets/                 # 테스트용 에셋
+└── docs/                   # 문서
+```
+
+Cargo 워크스페이스로 관리하며, 각 crate는 독립적으로 빌드/테스트 가능하다.
+
+---
+
+## 테스트 전략
+
+- **단위 테스트**: 각 crate 내 `#[cfg(test)]` 모듈
+- **통합 테스트**: `examples/` 디렉토리의 데모 앱
+- **벤치마크**: `criterion` crate로 성능 측정 (수학, ECS 쿼리, 렌더링 등)
+- **교차 검증**: 수학 라이브러리는 glam 결과와 비교
+
+---
+
+## 성능 목표
+
+- 60 FPS 이상 (1080p, 복잡한 씬)
+- ECS: 100,000 엔티티 순회 < 1ms
+- 물리: 1,000 리지드바디 실시간 시뮬레이션
+- 렌더링: 디퍼드 파이프라인에서 1,000+ 라이트
+
+---
+
+## 라이선스
+
+- Voltex 엔진 코드: 추후 결정 (MIT, Apache 2.0, 또는 독점)
+- 외부 의존: winit (Apache 2.0), wgpu (MIT / Apache 2.0)
+- 라이선스 고지 파일을 `THIRD_PARTY_LICENSES` 에 유지한다