SEQUA-Engine/prototypes/libgodot_host

PROTOTYPE JETABLE — pas du code produit. Ce dossier sert uniquement à valider une hypothèse technique. Il sera supprimé ou réécrit.

libgodot_host — héberger Godot par LibGodot

Rôle

Vérifier ce que supposent l'ADR 0007 et l'ADR 0008 : un programme SEQUA peut charger Godot comme bibliothèque, le démarrer et piloter sa boucle image par image avec GodotInstance::iteration().

Le programme n'utilise que l'interface C de GDExtension (gdextension_interface.gen.h, généré par la construction de Godot), sans godot-cpp :

1. charge godot.windows.template_debug.x86_64.dll (LoadLibrary, dlopen ailleurs) ;
2. appelle libgodot_create_godot_instance avec sa fonction d'initialisation GDExtension, par laquelle il reçoit l'accès à l'API de Godot ;
3. retrouve GodotInstance::start et iteration (classdb_get_method_bind, empreinte tirée de extension_api-4-7.json) et les appelle (object_method_bind_ptrcall) ;
4. boucle sur iteration() en mesurant chaque appel, jusqu'à --frames N ou la fermeture de la fenêtre ;
5. détruit l'instance, puis décharge la bibliothèque.

Le projet Godot chargé (project/) contient un cube qui tourne, une caméra et une lumière.

Construire et lancer

.\scripts\build-godot.ps1                      # Godot en bibliothèque (~6 min la première fois)
.\scripts\build.ps1 -Preset windows-msvc-prototypes -BuildDir build\windows-msvc-prototypes -Target libgodot_host -TestRegex libgodot_host
.\build\windows-msvc-prototypes\prototypes\libgodot_host\libgodot_host.exe [--frames N] [--headless]

Sans Godot construit, la cible est ignorée (message STATUS à la configuration).

Résultats (2026-11-07)

Windows 11, RTX 4090 Laptop, Vulkan 1.4.357, Godot 4.7.2-stable (fork sequa/4.7.2), template_debug.

Mesure	Fenêtre	--headless
Démarrage (création + start())	1,5 – 1,8 s	0,14 s
Débit	≈179 images/s	≈150 images/s
iteration() médiane / p95	5,6 / 6,1 ms	6,9 / 6,9 ms
Pilote de rendu	Vulkan, Forward+	factice (aucune image)
Arrêt	propre (code 0)	propre (code 0)

Lecture : ≈5,6 ms correspond à la synchronisation verticale de l'écran (≈180 Hz), pas au coût du rendu de cette scène minuscule. Le mode --headless confirme qu'aucun rendu n'a lieu.

Constats

• --path est interdit par défaut dans les modèles d'export de Godot 4.7 : il faut compiler avec disable_path_overrides=no (fait dans scripts/build-godot.ps1).
• Déchargement explicite obligatoire. Laisser Windows décharger la DLL en fin de processus provoque un accès mémoire invalide (0xC0000005) : elle passe alors après d'autres DLL dont Godot dépend encore. Détruire l'instance puis appeler FreeLibrary tout de suite donne un arrêt propre. Ne pas détruire l'instance « marche » aussi, mais Godot signale alors de nombreuses fuites.
• Une seule instance de Godot par processus, et pas de recréation après destruction (commentaire de platform/windows/libgodot_windows.cpp) : relancer Godot revient à relancer le processus de rendu.
• ERROR: Could not load global script cache : le projet n'a jamais été importé par l'éditeur. Sans effet ici.

Limites

• Windows seulement pour l'instant ; le code prévoit dlopen, mais rien n'a été essayé sous Linux.
• La scène vient d'un fichier .tscn : rien n'est encore créé depuis SEQUA (étape suivante, avec godot-cpp).
• Le temps d'iteration() inclut l'attente de la synchronisation verticale ; mesurer le coût réel demandera de la couper ou d'utiliser les compteurs GPU.

Licences

MPL 2.0 (en-têtes SPDX). Godot : MIT.