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-14). Ce plan couvre la phase de consolidation passée ; la source de vérité sur l'état actuel est README.md et le code. Plusieurs cases [X] ci-dessous ont été re-corrigées car elles ne reflétaient plus la réalité : notamment le rendu de la Scene n'est pas automatisé (items Phase 2 et Check-list concernés). Depuis, simple.rs a été mis en conformité (API AppBuilder, ~15 lignes, compilation sans importer winit/wgpu).

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 le rendu des matériaux soit automatique (actuellement le cache est porté par App, indépendant de la Scene ; le rendu n'est pas automatisé).
• Implémenter la logique app.render(scene) : cette méthode doit parcourir la scène, récupérer les matériaux, gérer les pipelines via le cache, et soumettre les draw calls (non implémenté — cf. README, étape 1 du Roadmap : scene auto-rendering).

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).
• Implémenter le comportement par défaut : si aucun matériau n'est assigné, le moteur injecte automatiquement le basic_shader (non implémenté).

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.
• Textures : Intégration d'un module de chargement d'images et de BindGroups.
• Caméras : Gestion des matrices de projection/vue dans la Scene.

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 ? (boucle + présentation OK, mais render() ne peut pas encore dessiner — vue de frame non exposée)
• Les modules sont-ils bien exposés via lib.rs ?
• pollster est-il uniquement en dev-dependencies ?

Ce plan garantit que les fondations sont saines. Une fois la Scene rendue automatiquement par app.render(), l'ajout de toute nouvelle fonctionnalité (lumières, textures) deviendra une simple question d'ajout de données dans la structure de scène, sans modification de la boucle de rendu.