SEQUA-Engine/docs/adr/0009-processus-de-rendu-lance-par-le-core.md

ADR 0009 : Processus de rendu lancé par le Core, protocole Core ↔ rendu, adaptateurs en bibliothèques chargées

• Statut : Acceptée
• Date : 2026-11-07
• Décideur : Ange-Marie MAURIN - A2M Systèmes
• Références : docs/SEQUA_Engine_resume_complet_v2.md §4.8, §5.3, §5.6, §5.7, §7.0, §7.0.1, §7.1, §9, §10.2, §14 ; ADR 0005, ADR 0006, ADR 0007, ADR 0008 ; spécification docs/specs/protocole-core-rendu-0.1.md

Contexte

L'ADR 0008 sépare le rendu du Core dans un processus à part, où l'adaptateur, le moteur et plus tard l'inférence sont des bibliothèques chargées. Elle laisse ouvertes cinq questions : qui lance et supervise ce processus, le transport Core ↔ rendu, la frontière binaire des bibliothèques, le rythme entre la simulation et l'affichage, et le nom de l'exécutable. L'étape 4 (la simulation du Core affichée dans Godot) oblige à les trancher.

Le Core doit rester utilisable sans Studio (tests, rejeux en lot, génération de données, machines sans écran : ADR 0006, §5.3). Le monde simulé actuel est le micro-mode 2D de démonstration (SIMULÉ).

Options envisagées

Qui lance le processus de rendu

1. Studio host, qui supervise déjà le Core (ADR 0006) : le code de lancement existe, mais sans Studio il n'y a plus de rendu, ce qui contredit le mode sans interface.
2. Le Core : le rendu existe dans tous les modes, Studio compris. Le Core ne connaît toujours aucun moteur : il lance un exécutable et lui désigne une bibliothèque d'adaptateur, puis ne lui parle que par le protocole.

Transport

1. WebSocket et JSON provisoire, comme le protocole Studio - Core 0.2 (ADR 0005) : déjà en place des deux côtés, facile à observer ; coût à mesurer à 60 messages par seconde.
2. Canal local plus léger (tube nommé, mémoire partagée) : plus rapide, mais un transport de plus à écrire pour chaque plateforme.

Frontière binaire

1. Interface C++ exportée directement : suppose le même compilateur et la même bibliothèque standard, sans vérification.
2. Point d'entrée C versionné qui renvoie un I3DEngineAdapter : même hypothèse de compilateur (tout est construit ensemble dans le monorepo), mais la version de l'interface est vérifiée au chargement, et le symbole à chercher est unique.

Décision

• Le Core lance et supervise le processus de rendu, sequa-render. Deux façons de le démarrer : option --render <adaptateur> au lancement du Core (mode sans interface), et commandes render/start et render/stop du protocole Studio - Core. Si le rendu plante, le Core le relance et lui renvoie la scène complète (SceneState::snapshot() côté rendu, scène complète du projecteur côté Core), puis reprend les deltas : la simulation et la session continuent (ADR 0008).
• Aucun rendu orphelin (VRAM) : le rendu tient un bail sur sa connexion au Core (arrêt si elle disparaît, délai de grâce), et le système le lie au Core (job object sous Windows, PR_SET_PDEATHSIG sous Linux).
• Transport : WebSocket et JSON provisoire, sur le serveur existant du Core, avec un client sequa-render distinct de Studio. Critère de vitesse : p95 du délai entre la fin d'un tick et l'application de son delta dans le rendu inférieur à 4 ms (un quart d'image à 60 images par seconde), mesuré sur le poste. Au-delà, on passe à un canal local plus léger.
• Adaptateurs en bibliothèques chargées : chaque adaptateur est une bibliothèque partagée qui exporte sequa_create_engine_adapter et sequa_destroy_engine_adapter (C), avec un numéro de version d'interface vérifié au chargement. sequa-render charge la bibliothèque, crée l'adaptateur, puis décharge l'adaptateur avant le moteur, ce qui règle aussi l'ordre de déchargement de godot-cpp constaté à l'étape 3.
• Projection du monde dans le Core : un module du Core (sequa::core_render, SIMULÉ) traduit l'état du monde en deltas SEQUA 3D (joueur : capsule, sol : plan, pièces : sphères). Le Core reste la seule source de vérité et ne dépend que du contrat SEQUA 3D (§7.0.1).
• Rythme : un delta par tick simulé (60 Hz), numéroté par le tick et par la version du monde. Le rendu applique tous les deltas reçus avant chaque image et affiche le dernier état, sans interpolation pour l'instant (mouvement saccadé sur un écran au-dessus de 60 Hz).
• Deuxième adaptateur, de débogage (engines/debug/adapter) : dessine la scène en 2D vue de côté, sans GPU, et l'écrit en images ou en vidéo à faible cadence (ffmpeg en outil externe facultatif). Il sert au mode sans interface tant que Godot n'a pas de vrai headless (ADR 0007), à comparer deux rejeux image par image, et de premier test d'isolation léger (§7.1).

Conséquences

Positives

• Le rendu existe avec et sans Studio, par le même chemin.
• Changer de moteur revient à désigner une autre bibliothèque d'adaptateur ; l'adaptateur de débogage le prouve dès l'étape 4.
• Le transport et la logique du protocole sont déjà connus et testés (ADR 0005).

Négatives et coûts

• Le Core devient superviseur de processus : le code de lancement de Studio host (studio/host/supervisor) et son client WebSocket (studio/host/client) doivent passer dans une bibliothèque commune, utilisée par le host, le Core et sequa-render.
• Un deuxième protocole à faire évoluer avec le premier (deux numéros de version).
• Tant que Godot n'a pas de vrai headless, --render godot ouvre une fenêtre même sans Studio ; le mode sans interface utilise l'adaptateur de débogage.
• Le JSON coûte plus que nécessaire ; le format définitif du schéma (§17) le remplacera.

Questions ouvertes

• Seuil de vitesse, absence d'interpolation et vrai headless reporté : retenus par défaut, confirmés avec l'acceptation de cette ADR le 2026-11-07.
• Fausse sortie générative (une vidéo lente rendue avec retard, pour éprouver le rejet des images périmées, §5.7) : étape 4 bis.
• Interpolation entre deux ticks côté rendu : quand le délai et la saccade auront été mesurés.
• Mesures renvoyées par le rendu (temps, VRAM) jusqu'à Studio : le protocole 0.2 n'a pas de message spontané du Core ; à prévoir avec la version suivante.
• Entrées du joueur captées par la fenêtre du moteur (ADR 0008) : chemin vers session/input à définir.