docs: add project status, deferred items, and CLAUDE.md
- STATUS.md: completed phases, crate structure, test counts, next steps - DEFERRED.md: simplified/postponed items per phase - CLAUDE.md: build rules, wgpu quirks, project conventions Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
27
CLAUDE.md
Normal file
27
CLAUDE.md
Normal file
@@ -0,0 +1,27 @@
|
|||||||
|
# Voltex Engine
|
||||||
|
|
||||||
|
Rust 게임 엔진 프로젝트. wgpu 28.0 + winit 0.30 기반.
|
||||||
|
|
||||||
|
## 작업 현황
|
||||||
|
- `docs/STATUS.md` — 완료된 Phase, crate 구조, 테스트 현황, 다음 작업
|
||||||
|
- `docs/DEFERRED.md` — 간소화/미뤄진 항목 목록
|
||||||
|
|
||||||
|
## 스펙
|
||||||
|
- `docs/superpowers/specs/2026-03-24-voltex-engine-design.md` — 전체 엔진 설계
|
||||||
|
|
||||||
|
## 구현 계획
|
||||||
|
- `docs/superpowers/plans/` — 각 Phase별 상세 구현 계획
|
||||||
|
|
||||||
|
## 빌드/테스트
|
||||||
|
```bash
|
||||||
|
cargo build --workspace
|
||||||
|
cargo test --workspace
|
||||||
|
```
|
||||||
|
|
||||||
|
## 규칙
|
||||||
|
- Cargo path: `export PATH="$HOME/.cargo/bin:$PATH"` (Windows bash)
|
||||||
|
- wgpu 28.0 API: `immediate_size`, `multiview_mask`, `TexelCopyTextureInfo` 등 28.0 전용 필드 사용
|
||||||
|
- WGSL vec3 alignment: Rust struct에서 vec3 뒤에 padding 필요 (16바이트 정렬)
|
||||||
|
- max_bind_groups=4 (group 0~3). 리소스를 합쳐서 4개 이내로 유지
|
||||||
|
- Dynamic UBO 패턴: per-entity uniform은 aligned staging buffer + dynamic offset 사용
|
||||||
|
- 기존 예제(triangle, model_viewer 등)는 mesh_shader.wgsl(Blinn-Phong) 사용 — PBR 변경에 영향 없음
|
||||||
48
docs/DEFERRED.md
Normal file
48
docs/DEFERRED.md
Normal file
@@ -0,0 +1,48 @@
|
|||||||
|
# 미뤄진/간소화된 구현 항목
|
||||||
|
|
||||||
|
## Phase 2
|
||||||
|
|
||||||
|
- **PNG 디코더 자체 구현** — deflate + 필터링. 현재 BMP만 지원.
|
||||||
|
- **JPG 디코더 자체 구현** — Huffman + DCT. 현재 미구현.
|
||||||
|
- **glTF 파서** — OBJ만 지원 중.
|
||||||
|
|
||||||
|
## Phase 3a
|
||||||
|
|
||||||
|
- **Archetype 기반 스토리지** → SparseSet 사용 중. 대규모 씬에서 성능 이슈 시 전환.
|
||||||
|
- **시스템 스케줄러** — 의존성 기반 실행 순서/병렬 실행 미구현. 시스템은 함수 호출.
|
||||||
|
- **쿼리 필터** — With, Without, Changed 미구현. query/query2만 존재.
|
||||||
|
- **query3+** — query2까지만 있음.
|
||||||
|
|
||||||
|
## Phase 3b
|
||||||
|
|
||||||
|
- **JSON 직렬화** → 커스텀 .vscn 텍스트 포맷 사용.
|
||||||
|
- **바이너리 씬 포맷** — 미구현.
|
||||||
|
- **임의 컴포넌트 직렬화** — Transform/Parent/Tag만 지원.
|
||||||
|
|
||||||
|
## Phase 3c
|
||||||
|
|
||||||
|
- **비동기 로딩** — 동기 insert만.
|
||||||
|
- **핫 리로드** — 파일 변경 감지 미구현.
|
||||||
|
|
||||||
|
## Phase 4a
|
||||||
|
|
||||||
|
- **Metallic/Roughness/AO 텍스처 맵** → 파라미터 값만 사용. 텍스처 샘플링 미구현.
|
||||||
|
- **Emissive 맵** — 미구현.
|
||||||
|
|
||||||
|
## Phase 4b
|
||||||
|
|
||||||
|
- **CSM (Cascaded Shadow Maps)** → 단일 캐스케이드만. 원거리 그림자 해상도 낮음.
|
||||||
|
- **Point Light Shadow (큐브맵)** — 미구현.
|
||||||
|
- **Spot Light Shadow** — 미구현.
|
||||||
|
- **라이트 컬링** — 타일/클러스터 기반 미구현.
|
||||||
|
|
||||||
|
## Phase 4c
|
||||||
|
|
||||||
|
- **HDR 큐브맵 환경맵** → 프로시저럴 sky 함수로 대체.
|
||||||
|
- **Irradiance/Prefiltered Map 컨볼루션** → 프로시저럴 근사.
|
||||||
|
- **GPU 컴퓨트 BRDF LUT** → CPU 생성 (256x256).
|
||||||
|
|
||||||
|
## 렌더링 한계
|
||||||
|
|
||||||
|
- **per-entity dynamic UBO** — 수천 개 이상은 인스턴싱 필요.
|
||||||
|
- **max_bind_groups=4** — IBL을 shadow group에 합쳐서 해결. 추가 group 필요 시 리소스 합치거나 bindless 활용.
|
||||||
95
docs/STATUS.md
Normal file
95
docs/STATUS.md
Normal file
@@ -0,0 +1,95 @@
|
|||||||
|
# Voltex Engine - 작업 현황
|
||||||
|
|
||||||
|
## 완료된 Phase
|
||||||
|
|
||||||
|
### Phase 1: Foundation (삼각형 렌더링)
|
||||||
|
- voltex_math: Vec3
|
||||||
|
- voltex_platform: VoltexWindow, InputState, GameTimer
|
||||||
|
- voltex_renderer: GpuContext, Vertex, shader, pipeline
|
||||||
|
- examples/triangle
|
||||||
|
|
||||||
|
### Phase 2: Rendering Basics
|
||||||
|
- voltex_math: Vec2, Vec4, Mat4 (transforms, look_at, perspective, orthographic)
|
||||||
|
- voltex_renderer: MeshVertex(+tangent), Mesh, depth buffer, OBJ parser, Camera, FpsController
|
||||||
|
- voltex_renderer: Blinn-Phong shader, BMP texture loader, GpuTexture
|
||||||
|
- examples/model_viewer
|
||||||
|
|
||||||
|
### Phase 3a: ECS
|
||||||
|
- voltex_ecs: Entity(id+generation), SparseSet<T>, World(type-erased storage)
|
||||||
|
- voltex_ecs: query<T>, query2<A,B>, Transform component
|
||||||
|
- examples/many_cubes (400 entities, dynamic UBO)
|
||||||
|
|
||||||
|
### Phase 3b: Scene Graph
|
||||||
|
- voltex_ecs: Parent/Children hierarchy, add_child/remove_child/despawn_recursive
|
||||||
|
- voltex_ecs: WorldTransform propagation (top-down)
|
||||||
|
- voltex_ecs: Scene serialization (.vscn text format), Tag component
|
||||||
|
- examples/hierarchy_demo (solar system)
|
||||||
|
|
||||||
|
### Phase 3c: Asset Manager
|
||||||
|
- voltex_asset: Handle<T>(generation), AssetStorage<T>(ref counting), Assets(type-erased)
|
||||||
|
- examples/asset_demo
|
||||||
|
|
||||||
|
### Phase 4a: PBR Rendering
|
||||||
|
- voltex_renderer: MaterialUniform (base_color, metallic, roughness, ao)
|
||||||
|
- voltex_renderer: Cook-Torrance BRDF shader (GGX NDF + Smith geometry + Fresnel-Schlick)
|
||||||
|
- voltex_renderer: Procedural UV sphere generator
|
||||||
|
- voltex_renderer: PBR pipeline (3→4 bind groups)
|
||||||
|
- examples/pbr_demo (7x7 metallic/roughness sphere grid)
|
||||||
|
|
||||||
|
### Phase 4b-1: Multi-Light
|
||||||
|
- voltex_renderer: LightData (Directional/Point/Spot), LightsUniform (MAX_LIGHTS=16)
|
||||||
|
- PBR shader: multi-light loop, point attenuation, spot cone falloff
|
||||||
|
- examples/multi_light_demo (orbiting colored point lights)
|
||||||
|
|
||||||
|
### Phase 4b-2: Shadow Mapping
|
||||||
|
- voltex_renderer: ShadowMap (2048x2048 depth), ShadowUniform, ShadowPassUniform
|
||||||
|
- Shadow depth-only shader + pipeline (front-face cull, depth bias)
|
||||||
|
- PBR shader: shadow map sampling + 3x3 PCF
|
||||||
|
- examples/shadow_demo (directional light shadows)
|
||||||
|
|
||||||
|
### Phase 4c: Normal Map + IBL
|
||||||
|
- MeshVertex: tangent[4] added, computed in OBJ parser + sphere generator
|
||||||
|
- voltex_renderer: BRDF LUT (CPU Monte Carlo, 256x256), IblResources
|
||||||
|
- PBR shader: TBN normal mapping, procedural sky IBL, split-sum approximation
|
||||||
|
- Texture bind group: albedo + normal map (pbr_texture_bind_group_layout)
|
||||||
|
- IBL merged into shadow bind group (group 3) due to max_bind_groups=4
|
||||||
|
- examples/ibl_demo
|
||||||
|
|
||||||
|
## Crate 구조
|
||||||
|
|
||||||
|
```
|
||||||
|
crates/
|
||||||
|
├── voltex_math — Vec2, Vec3, Vec4, Mat4
|
||||||
|
├── voltex_platform — VoltexWindow, InputState, GameTimer
|
||||||
|
├── voltex_renderer — GPU, Mesh, OBJ, Camera, Material, PBR, Shadow, IBL, Sphere
|
||||||
|
├── voltex_ecs — Entity, SparseSet, World, Transform, Hierarchy, Scene, WorldTransform
|
||||||
|
└── voltex_asset — Handle<T>, AssetStorage<T>, Assets
|
||||||
|
```
|
||||||
|
|
||||||
|
## 테스트: 105개 전부 통과
|
||||||
|
|
||||||
|
- voltex_asset: 14
|
||||||
|
- voltex_ecs: 39
|
||||||
|
- voltex_math: 29 (28 + orthographic)
|
||||||
|
- voltex_platform: 3
|
||||||
|
- voltex_renderer: 20
|
||||||
|
|
||||||
|
## Examples (8개)
|
||||||
|
|
||||||
|
- triangle — Phase 1 삼각형
|
||||||
|
- model_viewer — OBJ 큐브 + Blinn-Phong
|
||||||
|
- many_cubes — 400 ECS 엔티티 렌더링
|
||||||
|
- hierarchy_demo — 태양계 씬 그래프
|
||||||
|
- asset_demo — Handle 기반 에셋 관리
|
||||||
|
- pbr_demo — metallic/roughness 구체 그리드
|
||||||
|
- multi_light_demo — 다중 색상 라이트
|
||||||
|
- shadow_demo — Directional Light 그림자
|
||||||
|
- ibl_demo — Normal map + IBL
|
||||||
|
|
||||||
|
## 다음: Phase 5 (물리 엔진)
|
||||||
|
|
||||||
|
스펙 참조: `docs/superpowers/specs/2026-03-24-voltex-engine-design.md`
|
||||||
|
|
||||||
|
## 간소화/미뤄진 항목
|
||||||
|
|
||||||
|
상세: `docs/DEFERRED.md`
|
||||||
Reference in New Issue
Block a user