Jérôme Bousquié
66 lines
2.9 KiB
Markdown
66 lines
2.9 KiB
Markdown
# 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.
|