# 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 추상화
└─────────────────────────────────┘
```

### 의존성 규칙

- 각 레이어는 바로 아래 레이어에만 의존한다.
- 레이어를 건너뛰는 의존은 허용하지 않는다.
- 같은 레이어 내 모듈 간 순환 의존을 금지한다.
- **예외**: `voltex_math`는 기반 유틸리티로서 모든 레이어에서 직접 의존 가능하다.

---

## 외부 라이브러리 vs 자체 구현

### 외부 라이브러리 (Rust crate 의존: 2개만 사용)

| 라이브러리 | 버전 | 역할 | 라이선스 |
|-----------|------|------|---------|
| winit | 0.30.x | 크로스플랫폼 윈도우 생성, 키보드/마우스/터치 입력 | Apache 2.0 |
| wgpu | 28.x | Vulkan/DX12/Metal/WebGPU 그래픽스 API 추상화 | MIT / Apache 2.0 |

- 라이선스 의무: 출처 표기, 변경 명시 (Apache 2.0)
- 상업적 사용 자유, 로열티 없음, 소스 공개 의무 없음
- 개발 전용 의존(테스트, 벤치마크 등: criterion, glam 등)은 런타임에 포함되지 않으므로 이 제한에서 제외
- OS/시스템 API (Win32, CoreAudio, ALSA 등)와 C 라이브러리 (liblua)는 FFI를 통해 직접 호출하며, Rust crate 의존에 포함하지 않는다

### 자체 구현

| 시스템 | 설명 |
|--------|------|
| 수학 라이브러리 | Vec2, Vec3, Vec4, Mat3, Mat4, Quaternion, Transform, AABB, Ray, Plane |
| 렌더링 파이프라인 | 포워드/디퍼드 렌더링, PBR, GI, 레이트레이싱, 포스트 프로세싱 |
| ECS 프레임워크 | 엔티티, 컴포넌트 스토리지, 시스템 스케줄링, 쿼리 |
| 씬 관리 | 씬 그래프, 부모-자식 트랜스폼 계층, 씬 직렬화/역직렬화 |
| 에셋 시스템 | 에셋 로딩, 캐싱, 핫 리로드, 포맷 변환 |
| 물리 엔진 | 충돌 감지 (AABB, GJK/SAT), 리지드바디 시뮬레이션, 레이캐스팅 |
| 오디오 시스템 | 사운드 로딩/재생, 3D 공간 오디오, 믹서 |
| AI | 내비메시 생성, A* 패스파인딩 |
| 네트워킹 | 클라이언트-서버 아키텍처, UDP 기반 |
| 스크립팅 | Lua 바인딩 (자체 FFI 래퍼로 Lua C API 호출) |

---

## 구현 단계

### 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 디코더 자체 구현 (deflate + 필터링)
- JPG 디코더 자체 구현 (Huffman + DCT, baseline JPEG만 지원)
- 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. 오디오 백엔드

- 플랫폼별 오디오 출력 자체 구현
  - Windows: WASAPI
  - macOS: CoreAudio
  - Linux: ALSA / PulseAudio
- 오디오 스레드 분리

#### 6-2. 사운드 재생

- WAV 파서 자체 구현
- OGG/Vorbis 디코더 자체 구현 (추후)
- 재생, 일시정지, 정지, 볼륨, 루프

#### 6-3. 3D 오디오

- 거리 기반 감쇠
- 패닝 (스테레오)
- 도플러 효과 (추후)

#### 6-4. 믹서

- 채널/그룹 기반 믹싱 (BGM, SFX, Voice 등)
- 볼륨 페이드 인/아웃

**Phase 6 완료 기준**: 3D 공간에서 소리가 위치에 따라 다르게 들리며, BGM과 SFX를 독립적으로 제어할 수 있다.

---

### Phase 7: 고급 렌더링 (Stretch Goal)

**목표**: AAA급 비주얼 퀄리티에 도달한다.

#### 7-1. 디퍼드 렌더링

- G-Buffer: Position, Normal, Albedo, Metallic-Roughness, Depth
- 라이팅 패스 분리
- 다수의 라이트를 효율적으로 처리

#### 7-2. Global Illumination

단계적으로 구현한다:
1. **Light Probes** (먼저) — 베이크 기반, 구현 난이도 낮음, 정적 씬에 효과적
2. **SSGI** (다음) — 스크린 스페이스 기반, 동적 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 수준으로 보인다.

> **Core Deliverable 경계**: Phase 1~6이 핵심 산출물이다. Phase 7~8은 핵심이 완성된 후 진행하는 확장 목표이며, 구현 계획은 Phase 6 완료 시점에 재평가한다.

---

### Phase 8: 확장 (Stretch Goal)

**목표**: 엔진을 완전한 게임 개발 도구로 확장한다.

#### 8-1. AI

- 내비메시 생성 (Recast 스타일 알고리즘)
- A* 패스파인딩
- 스티어링 행동 (Seek, Flee, Arrive, Wander)

#### 8-2. 네트워킹

- UDP 소켓 기반
- 클라이언트-서버 아키텍처
- 상태 동기화 (스냅샷 + 보간)
- 지연 보상

#### 8-3. 스크립팅

- Lua 바인딩 (자체 FFI 래퍼로 Lua C API 호출)
- 핫 리로드 지원
- 엔진 API 노출 (엔티티 생성/삭제, 컴포넌트 접근 등)

#### 8-4. 에디터 (GUI)

- 자체 Immediate Mode UI 시스템 (voltex_renderer 위에 구축)
- 씬 뷰포트 (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 이중 라이선스 (Rust 생태계 관례)
- 외부 의존: winit (Apache 2.0), wgpu (MIT / Apache 2.0)
- 라이선스 고지 파일을 `THIRD_PARTY_LICENSES` 에 유지한다