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.

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.

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.

2.9 KiB Raw Blame History