wsg/docs/PLAN.md

type, title, description, tags, status, generated

type	title	description	tags	status	generated
Plan	Implementation Plan for wsg_lib Engine Consolidation and Finalization	Implementation plan defining priority steps to finalize the current architecture, making the API intuitive for standard users while maintaining power for advanced users	plan implementation roadmap development wsg-lib	stable	by at human:jerome 2026-07-31T00:00:00Z

Plan d'Implémentation : Consolidation et Finalisation du Moteur wsg_lib

Ce plan définit les étapes prioritaires pour finaliser l'architecture actuelle. L'objectif est de rendre l'API intuitive pour l'utilisateur standard tout en conservant la puissance de contrôle pour l'utilisateur avancé.

Statut réel (à jour au 2026-09-18). La phase de consolidation (Phases 1 à 3 de ce plan) est terminée ; la source de vérité sur l'état actuel est README.md et le code. Depuis la révision du 2026-09-14, le rendu de la Scene est automatisé en une passe groupée (App::render_scene(frame.view()), appelée par défaut dans AppHandler::render) et simple.rs (API AppBuilder, sans winit/wgpu) déclare un quad rendu automatiquement. Les étapes suivantes ont ensuite : posé l'infrastructure 3D (bind groups uniformes frame+object partagés, caméra active, matrices monde par entité — Étapes 3+4, 2026-09-16) ; atteint le MVP 3D Phong (Étape 5, 2026-09-17 : l'exemple cube ; le 2D plat = variante unlit de standard via Renderer::set_unlit) ; rattaché le PipelineCache à la Scene et fait référencer son Material par chaque Mesh (Étape 7) ; donné à Mesh une source de vérité CPU partagée (geometry: Arc<Geometry>, Étape 8) ; activé un depth buffer sur toutes les passes (Étape 9) ; et ajouté les textures diffuses (Étape 10, 2026-09-18 : resources::Texture + bind group @2 + Material.texture).

Phase 1 : Finalisation et Nettoyage de l'Existant (Priorité Absolue)

Cette phase vise à supprimer la dette technique et à unifier les accès.

Uniformisation des Modules

• Vérifier que tous les traits (AppHandler) et structures (App, Context) sont explicitement marqués pub dans leurs fichiers sources.
• Ré-exporter l'API dans lib.rs pour permettre des imports simplifiés (ex : use wsg_lib::{App, AppHandler}).
• Nettoyer les accès internes pour que l'utilisateur n'ait pas à importer les modules système (core, pipeline) sauf besoin spécifique.

Abstraction de la Boucle (App::run)

• Déplacer la gestion de winit::event_loop et des Frame à l'intérieur de la méthode run() de App.
• Garantir que le trait AppHandler reçoit une référence à App permettant d'appeler app.renderer ou app.scene.
• Supprimer toute gestion de Frame ou EventLoop manuelle des exemples utilisateurs (simple.rs).

Correction du Builder et Initialisation

• Standardiser la création de App via un AppBuilder robuste.
• Gérer les dev-dependencies dans lib/Cargo.toml (notamment pollster avec la feature macro) pour permettre la compilation des exemples sans polluer les dépendances finales de la librairie.

Phase 2 : Structure de Rendu et Scène

Une fois la plomberie encapsulée, nous devons rendre l'assemblage des objets cohérent.

Intégration de la Scene

• Formaliser la structure Scene : un conteneur qui liste les Entities.
• Associer le PipelineCache à la Scene pour que la gestion des matériaux soit entièrement portée par la scène (actuellement le cache est porté par App, indépendant de la Scene — le rendu de la scène est, lui, déjà automatisé depuis 2026-09-16). (fait — 2026-09-17, DRAFT Étape 7 : Scene::init_gpu détient device+format+PipelineCache ; App n'a plus de champ cache)
• Implémenter la logique de rendu de la scène : App::render_scene(view) parcourt la scène, récupère les matériaux et soumet tous les draw calls en une seule passe groupée (Renderer::render_scene), appelée automatiquement chaque frame par l'implémentation par défaut de AppHandler::render (Scene auto-render — réalisé 2026-09-16). Reste à brancher : associé au PipelineCache porté par la Scene (cf. ligne précédente).

Gestion des Matériaux et Shaders

• S'assurer que chaque Mesh possède une référence vers un Material (à l'heure actuelle le lien est porté par l'entité (mesh_id, material_id) de la Scene, pas par le Mesh lui-même). (fait — 2026-09-17, DRAFT Étape 7 : Mesh.material: Option<Arc<Material>> ; Entity { mesh_id, transform }, plus de material_id)
• Implémenter le comportement par défaut : si aucun matériau n'est assigné, le moteur injecte automatiquement le standard_shader (variante unlit) (non implémenté). (fait — 2026-09-17, DRAFT Étape 7.3.5 : Scene::default_material() injecte standard ; le flat reste piloté par Renderer::set_unlit)

Phase 3 : Documentation et Interface (API "User-Friendly")

Refonte des Exemples

• simple.rs doit devenir le modèle : 15 lignes de code, pas de manipulation WGPU explicite (mis en conformité : AppBuilder, compile sans winit/wgpu).
• manual.rs doit rester disponible en tant que tutoriel pour ceux qui veulent contourner l'abstraction App.

Nettoyage du Code Interne

• Vérifier les durées de vie (lifetimes) et les Arc pour s'assurer qu'aucune fuite mémoire ou accès concurrentiel invalide ne survient lors des changements de frame.

Phase 4 : Nouvelles Fonctionnalités (Planification Future)

Une fois les phases 1 à 3 validées, nous pourrons introduire :

• Système de Lumières : Ajout de buffers d'uniformes dans le PipelineCache (planifié — ROADMAP 4.2, Éclairage avancé).
• Textures : Intégration d'un module de chargement d'images et de BindGroups (fait 2026-09-18, Étape 10, ROADMAP 4.1 : resources::Texture, bind group @2, Material.texture).
• Caméras : Gestion des matrices de projection/vue dans la Scene (fait 2026-09-16, Étape 4.3 — Scene::set_camera/camera() porte une caméra active ; render_scene écrit view/proj/cam_pos réels dans le buffer frame chaque frame, aspect calculé depuis la fenêtre).

Check-list de Vérification pour le LLM d'Assistance

• Est-ce que simple.rs compile sans importer winit ou wgpu ? (oui — modèle 15 lignes, API AppBuilder)
• Est-ce que App::run gère bien le cycle update → render → present ? (oui — la vue de frame est exposée via Frame::view(), render() dessine la scène automatiquement en une passe via App::render_scene(frame.view()), la présentation est faite par App::run)
• Les modules sont-ils bien exposés via lib.rs ?
• pollster est-il isolé de l'utilisateur final ? — résolu : depuis winit 0.30 (2026-09-16), pollster est en dependencies de la lib ; le block_on de l'init GPU est appelé une seule fois dans lib/src/app.rs (resumed()). Les exemples compilent sans le connaître (crates séparées).