wsg/docs/ROADMAP.md

---
type: Roadmap
title: WSG Engine Development Roadmap
description: Development roadmap for the WSG engine from prototype to full-featured 3D rendering engine
tags: [roadmap, development, planning, wsg-lib, 3d-rendering]
status: stable
generated: { by: human:jerome, at: 2026-07-31T00:00:00Z }
---

# Roadmap WSG — Prototype → Moteur Complet

> Basé sur l'architecture existante (ARCHI_APP, ARCHI_ARENES, ARCHI_CPU_GPU, ARCHI_RENDU).
> Objectif : prototype fonctionnel d'abord, enrichissement progressif ensuite.

---

## Phase 1️⃣ — Prototype MVP : Un Mesh 3D éclairé à l'écran

**Objectif** : Afficher un cube (ou autre mesh) 3D avec un éclairage Phong basique.

### 1.1 Dépendances & Mathématiques
- [ ] Ajouter `glam = "0.33"` en dépendance (`lib/Cargo.toml`)
- [ ] Ajouter `slotmap = "1.0"` en dépendance
- [ ] Créer module `math/` (ou `transform.rs`) :
  - [ ] Struct `Transform { translation: Vec3, rotation: Quat, scale: Vec3 }`
  - [ ] Méthode `to_matrix() -> Mat4` pour calculer la matrice locale
  - [ ] Struct `Camera { position: Vec3, target: Vec3, up: Vec3 }` : resources/camera.rs
  - [ ] Fonctions `view_matrix()` et `projection_matrix(fov, aspect, near, far)`

### 1.2 Geometry & Mesh
- [ ] Créer struct `Geometry` (math/geometry.rs) : 
  - [ ] `positions: Vec<[f32; 3]>` (obligatoire)
  - [ ] `indices: Option<Vec<u16>>` (optionnel)
  - [ ] `normals: Option<Vec<[f32; 3]>>` (pour Phong)
- [ ] Refactorer `Mesh` pour contenir :
  - [ ] `geometry: Arc<Geometry>`
  - [ ] `vertex_buffer: wgpu::Buffer`
  - [ ] `index_buffer: Option<wgpu::Buffer>`
  - [ ] `transform: Transform` (état CPU)
- [ ] Ajouter un mesh de test (cube unitaire) en exemple

### 1.3 Shader Phong Minimal
- [ ] Créer `standard_shader.wgsl` :
  - [ ] Vertex shader : projection * view * world * position
  - [ ] Fragment shader : éclairage hémisphérique + diffuse avec une lumière directionnelle
  - [ ] Uniforms : `view_matrix`, `proj_matrix`, `world_matrix`, `light_dir`, `light_color`
- [ ] Mettre à jour `Material` pour supporter les uniforms du shader Phong

### 1.4 Scene avec Arènes (slotmap)
- [ ] Implémenter `Scene` avec arènes générationalles :
  - [ ] `SlotMap<MeshId, Mesh>`
  - [ ] `SlotMap<MaterialId, Material>` (préparation future)
- [ ] Méthodes : `add_mesh()`, `get_mesh()`, `iter_meshes()`
- [ ] Les entités stockent des `MeshId` (handles typés), pas des références

### 1.5 Rendu du Prototype
- [ ] Uniform buffer pour la frame : `view_matrix`, `proj_matrix`, `light_dir`
- [ ] Uniform buffer par mesh : `world_matrix` (calculée sur CPU pour le MVP)
- [ ] `Renderer::render()` itère sur les meshes de la Scene et dessine chacun
- [ ] Exemple fonctionnel : un cube éclairé tourne à l'écran

---

## Phase 2️⃣ — Système de Ressources complet

**Objectif** : Étoffer la Scene avec tous les types de ressources.

### 2.1 Arènes complètes
- [ ] `SlotMap<MaterialId, Material>`
- [ ] `SlotMap<TextureId, Texture>` (struct de base)
- [ ] `SlotMap<LightId, Light>` (struct de base)
- [ ] `SlotMap<EntityId, Entity>` pour les entités de la scène

### 2.2 Entités & Hiérarchie
- [ ] Struct `Entity { mesh_id: Option<MeshId>, material_id: Option<MaterialId>, transform: Transform }`
- [ ] `Scene::add_entity()` → retourne `EntityId`
- [ ] `Scene::iter_entities()` → pour le render loop

### 2.3 Camera dans la Scene
- [ ] Intégrer `Camera` comme ressource de la Scene
- [ ] Permettre plusieurs caméras (actuelle/inactive)
- [ ] Exposer API : `scene.set_active_camera(camera_id)`

---

## Phase 3️⃣ — GPU-Driven Rendering

**Objectif** : Déléguer les calculs de transformation et culling au GPU (suivre ARCHI_CPU_GPU.md).

### 3.1 Compute Shader
- [ ] Buffer `TransformBuffer` (CPU → GPU) : positions/rotations/échelles brutes
- [ ] Buffer `MatrixBuffer` (GPU calculé) : World Matrices finales
- [ ] Compute shader : calcul des World Matrices pour tous les meshes

### 3.2 Frustum Culling GPU
- [ ] Ajouter `BBox` dans `Geometry` (center + extents)
- [ ] Buffer `BoundingBoxBuffer` (CPU → GPU, statique)
- [ ] Compute shader : culling basé sur la frustum de caméra
- [ ] Buffer `IndirectDrawBuffer` rempli par le GPU

### 3.3 Rendu Indirect
- [ ] `draw_indexed_indirect()` au lieu de draw calls individuels
- [ ] Un seul command draw pour tous les objets visibles

---

## Phase 4️⃣ — Fonctionnalités Avancées

**Objectif** : Qualité visuelle et performances.

### 4.1 Textures
- [ ] Struct `Texture` avec chargement d'image
- [ ] Ajouter `uvs: Option<Vec<[f32; 2]>>` dans `Geometry`
- [ ] BindGroup pour les textures dans le shader
- [ ] `Material` supporte une texture diffuse

### 4.2 Éclairage avancé
- [ ] Support multi-lumières (directionnelles, ponctuelles)
- [ ] Lumières hémisphériques
- [ ] Shadows (optionnel)

### 4.3 Optimisations
- [ ] Batching par Material (réduction des state changes GPU)
- [ ] Level of Detail (LOD)
- [ ] HDR + Tone Mapping (optionnel)

---

## Phase 5️⃣ — Documentation & Polish

- [ ] Exemple complet : mesh texturé, éclairé, avec caméra orbitale
- [ ] Documentation API (`docs/ARCHI_SCENE.md`)
- [ ] Tests unitaires : `Geometry`, `Scene`, `Transform`
- [ ] README mis à jour avec les nouvelles fonctionnalités

---

## Notes de Décision

| Décision | Raison |
|----------|--------|
| **Normals dès Phase 1** | Nécessaires pour le shader Phong ; sans elles, pas d'éclairage |
| **UVs en Phase 4** | Inutiles avant les textures ; on garde `Geometry` simple au départ |
| **BBox en Phase 3** | Utile uniquement pour le frustum culling GPU |
| **World Matrix CPU → MVP, GPU → Phase 3** | Le MVP est plus simple avec un uniform par mesh ; la migration GPU-driven est progressive |
| **slotmap dès Phase 1** | Architecture décidée (`ARCHI_ARENES.md`) ; mieux de l'adopter tôt que de refactorer |