re-org en App

2026-07-07 16:42:37 +02:00
parent cfd8b421a2
commit 82ea16d118
28 changed files with 518 additions and 67 deletions
@@ -0,0 +1,65 @@
+# ARCHI_APP.md : Architecture et Responsabilités
+
+Ce document définit l'architecture modulaire du moteur `wsg_lib`. L'objectif est de séparer la plomberie système de la logique métier tout en facilitant l'usage via une façade unifiée.
+
+## 1. Organisation des répertoires (`lib/src/`)
+
+L'organisation respecte les conventions Rust pour une bibliothèque modulaire :
+
+* `core/` : Plomberie système (Context, Renderer, Frame).
+* `pipeline/` : Gestion des états GPU et compilation des shaders.
+* `resources/` : Dépôt de données (Mesh, Material, Vertex, Texture).
+* `scene/` : Logique métier et hiérarchie (Entités, Transformations).
+* `shaders/` : Shaders intégrés (accessibles via `include_str!`).
+* `utils/` : Transverses (Configuration, Erreurs).
+
+## 2. Répartition des responsabilités
+
+| Module | Responsabilité |
+| :--- | :--- |
+| **App** | Façade orchestratrice (Point d'entrée unique). |
+| **Renderer** | Exécution des commandes WGPU. |
+| **PipelineCache** | Traduction des données de `resources/` vers les pipelines GPU. |
+| **Scene** | Stockage et gestion des entités et de leurs relations. |
+| **AppHandler** | Trait implémenté par l'utilisateur pour la boucle de jeu. |
+
+## 3. Workflow de l'utilisateur ("La Recette")
+
+### Phase de Déclaration (Initialisation)
+L'utilisateur configure sa scène avant le démarrage de la boucle.
+```rust
+let mut app = App::builder()
+    .with_runtime(my_runtime)
+    .build()
+    .await;
+
+let mat_id = app.resources.create_material("name", shader_id);
+let mesh_id = app.resources.load_mesh("path");
+app.scene.add_entity("id", mesh_id, mat_id);
+```
+
+### Phase d'Exécution (Render Loop)
+
+L'utilisateur implémente `AppHandler` pour manipuler ses objets.
+
+```rust
+impl AppHandler for MyGame {
+    fn render(&mut self, app: &mut App) {
+        // La scène est rendue automatiquement, l'utilisateur modifie l'état
+        app.scene.get("id").transform.rotation += 0.01;
+    }
+}
+app.run(MyGame::new());
+```
+
+### 4. Points d'attention pour l'utilisateur avancé
+
+- **Accès Bas-Niveau** : App expose ses composants internes (`renderer`, `context`, `cache`). Un utilisateur avancé peut ignorer la Scene pour faire des appels manuels.
+- **Injection Async** : Le runtime est injecté à la création via le Builder.
+- **Identifiants** : La gestion des ressources repose sur des identifiants (`Handle<T>` ou `String`), garantissant la sécurité mémoire et évitant les problèmes de durée de vie (*borrow checker*).
+
+### 5. Pourquoi cette architecture ?
+
+- **Performance** : La centralisation dans App permet d'optimiser le tri des entités et le *batching* par matériau.
+- **Maintenance** : Chaque dossier est indépendant. Ajouter une nouvelle fonctionnalité (ex: Lumières) consiste à créer un nouveau module dans `resources/` ou `scene/` sans impacter le cœur du rendu.
+- **Ergonomie** : L'utilisateur n'est plus confronté à la gestion des pipelines et des buffers, mais uniquement à la gestion de sa scène et de ses entités.