# 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.