SEQUA-Engine/docs/adr/0007-adaptateur-godot-dans-le-depot.md

ADR 0007 : Adaptateur Godot dans le dépôt, Godot hébergé par LibGodot depuis un fork

• 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 §1, §3, §4.8, §5.5, §5.6, §7, §7.0.1, §7.1, §7.2, §10.2, §10.3, §13 ; ADR 0008 ; prototype prototypes/gpu_interop

Contexte

La phase 1 se joue sur Godot (§7.1). SEQUA 3D (3d/) définit I3DEngineAdapter, la négociation des capacités et la synchronisation de la scène par deltas versionnés, sans dépendre d'aucun moteur. Il faut décider où vit l'adaptateur Godot, comment obtenir et modifier le moteur, comment SEQUA l'héberge, et comment il produit les tampons du contrat (§5.6, §7.2).

Le README prévoyait des dépôts séparés pour les adaptateurs. La doc (§7) réserve le mot « backend » au calcul GPU (IComputeBackend) et parle de « moteurs 3D ».

Constats faits sur le code de Godot 4.7.2 :

• --headless n'accepte que le pilote de rendu factice (servers/display/display_server_headless.h) : aucune image n'est produite, même hors écran.
• Forward+ fournit nativement couleur, profondeur, normales (normal_roughness) et vecteurs de mouvement ; il n'a ni albedo séparé ni identifiants d'objets.
• Le VkDevice de Godot n'active pas VK_KHR_external_memory_win32 (seule l'extension _fd est demandée, sans usage), et son allocateur n'exporte pas la mémoire (VMA_EXTERNAL_MEMORY_WIN32=0). En revanche, RenderingDevice::texture_create_from_extension() permet de confier à Godot une image créée hors de lui.
• Godot prend en charge D3D12 sous Windows, mais son pilote par défaut est Vulkan.

Options envisagées

Emplacement

1. Dépôt séparé par adaptateur : isolation stricte, mais versions à synchroniser entre dépôts alors que le contrat change souvent en phase 0 et 1 (§5.6).
2. Monorepo, moteur en sous-module : le contrat et l'adaptateur changent dans le même commit, et la version du moteur est figée par le sous-module. En contrepartie, le clone de Godot est lourd.

Modifications de Godot

1. Fichiers de correctifs appliqués à la construction sur le dépôt officiel : le diff reste petit par construction, mais chaque modification oblige à régénérer un .patch, et les conflits se règlent à la main à chaque version.
2. Fork sur le Gitea du projet : modifications en commits ordinaires, diff visible par git diff 4.7.2-stable..sequa/4.7.2, passage de version par git rebase, aucune dépendance à GitHub. En contrepartie, le fork pèse environ 1 Go et il faut veiller à ce qu'il ne dérive pas.

Hébergement de Godot

1. LibGodot (Godot 4.6 et plus, core/extension/libgodot.h, library_type=shared_library, Windows, Linux et macOS) : SEQUA charge Godot comme bibliothèque et appelle GodotInstance::iteration() à chaque image. Il garde ainsi la maîtrise de la boucle.
2. Processus Godot séparé + GDExtension : plantages isolés, mais un transport de plus et un partage de textures GPU entre processus.
3. Module C++ compilé dans Godot : accès complet aux internes du rendu, mais lié à une version de Godot.

Albedo et identifiants d'objets

1. Seconde vue partageant le monde et la caméra : lumière éteinte (DEBUG_DRAW_UNSHADED) pour l'albedo, copies des objets sur un calque dédié avec un matériau qui écrit l'identifiant. Aucune modification de Godot, mais la géométrie est dessinée deux fois.
2. Sorties supplémentaires dans la pré-passe de profondeur de Forward+ : une seule passe, mais une modification du renderer à maintenir.

Décision

• Emplacement : engines/godot/adapter (code SEQUA, MPL 2.0) ; sous-modules engines/godot/vendor/godot-src (Godot) et engines/godot/vendor/godot-cpp (liaisons C++ GDExtension, MIT, tag 10.0.0-stable, API 4.7).
• Fork : godot-src pointe vers le fork du Gitea du projet (ange/godot), branche sequa/4.7.2 partant du tag 4.7.2-stable, historique complet conservé. Règles du fork :
  • un commit par modification, avec un message qui dit pourquoi ;
  • aucune logique de SEQUA dans le fork, seulement des capacités génériques du moteur (§1 : les moteurs ne contiennent aucune logique du produit) ;
  • les modifications restent sous licence MIT, celle de Godot ;
  • GitHub n'est qu'une source de lecture (upstream) pour les versions suivantes.
• Hébergement : LibGodot, dans le processus de rendu défini par l'ADR 0008.
• Pilote graphique : Vulkan sur Windows et Linux (un seul chemin de partage avec l'inférence, validé par prototypes/gpu_interop). D3D12 n'est pas retenu pour l'instant ; macOS (Metal) est reporté.
• Vrai headless : le fork ajoute un mode sans fenêtre qui garde le rendu Vulkan (vues dessinées dans des textures, aucune présentation à l'écran), pour les tests, la génération de données et les machines sans écran.
• Albedo et identifiants : option 1 (seconde vue) d'abord, pour vérifier que ça marche et mesurer le coût ; l'option 2 seulement si le budget est dépassé.
• Partage GPU avec l'inférence : le fork active les extensions de mémoire et de sémaphores externes ; SEQUA alloue lui-même la mémoire partageable sur le VkDevice de Godot et la confie à Godot par texture_create_from_extension().

Conséquences

Positives

• Le contrat (3d/) et l'adaptateur évoluent ensemble, et le test d'isolation (§7.1, phase 2) se fera en ajoutant engines/unreal/ sans toucher au Core.
• La version de Godot et chacune de nos modifications sont visibles et versionnées sur le Gitea du projet.
• SEQUA maîtrise la boucle d'image, ce qui colle à render_frame() et au pas fixe du Core.

Négatives et coûts

• Le fork doit être poussé avant SEQUA quand il change, sinon SEQUA référence un commit absent du Gitea (push.recurseSubmodules=check à la racine de SEQUA).
• Passer à une nouvelle version de Godot demande de rejouer nos commits et de les revalider.
• Godot se construit avec SCons et Python, en dehors des presets CMake : un script de construction de LibGodot reste à écrire.
• Le vrai headless est estimé à quelques centaines de lignes dans le renderer de Godot, à confirmer par un premier essai.
• La seconde vue double le coût de la géométrie tant que l'option 2 n'est pas faite.
• Godot est sous licence MIT (compatible §10.2) ; ses dépendances tierces (thirdparty/) doivent être revues avant toute distribution.

Questions ouvertes

• Formats, résolution et calques partagés avec l'inférence : fixés par le choix du premier modèle neuronal (§17).
• Image affichée quand le rendu IA est actif : le compositeur écrit dans une texture partagée que Godot affiche en dernière passe (voir engines/godot/adapter/README.md).
• Interactions dans la fenêtre du moteur (peindre une ambiance sur la scène, §8) : à prévoir tôt, leur chemin vers Studio et le Core reste à définir.