helengine

# helengine helengine est un espace de travail partagé de moteur et d'éditeur qui génère des paquets de plateforme à partir de fichiers de projet `.heproj`. Il est conçu pour cibler du matériel limité (par exemple, des consoles rétro comme la DS et la PS2) tout en utilisant des pipelines d'assets et des outils modernes. ## Builds de plateforme via la CLI de l'éditeur Les builds de plateforme sont orchestrés via un script wrapper PowerShell `scripts/build-platform.ps1`, qui restaure et publie la CLI de l'éditeur, puis compile directement le projet rédigé. Exemple d'utilisation : ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File C:\dev\helworks\helengine\scripts\build-platform.ps1 ` -Project C:\dev\helprojs\city\project.heproj ` -Platform ds ` -Output C:\dev\helprojs\city\ds-build ` -BuildProfile release ` -CacheRoot D:\helengine-cache ``` Les paramètres clés incluent `-Project` (chemin vers le `.heproj`), `-Platform` (tel que déclaré dans le `settings/platforms.json` du projet), `-Output` (répertoire de sortie), `-BuildProfile` (par exemple `debug` ou `release`), `-CacheRoot` (emplacement de cache réutilisable), `-LockTimeout`, `-Clean`, `-PruneCacheOlderThanDays`, et `-AdditionalArgs` pour des arguments supplémentaires de la CLI de l'éditeur. Le wrapper prend également en charge l'attente de build pour une complétion vérifiée. ## Modes de module et de build Le code du projet utilise des déclarations `code.module.json`. Les modules d'exécution dépendent uniquement de modules d'exécution ; les modules réservés à l'éditeur utilisent `"moduleKind": "editor"` et peuvent dépendre de modules d'exécution. Les dossiers de test doivent être nommés `<module-id>.tests` et correspondre à un module de production déclaré. Les sessions interactives de l'éditeur et les commandes de l'éditeur utilisent `EditorFull` (inclut les modules d'exécution + éditeur + tests), tandis que les builds de plateforme utilisent `RuntimeOnly` (exclut les tests/commandes de l'éditeur). Les profils de build de plateforme peuvent déclarer des commandes de prébuild ordonnées via `editorPrebuildCommandIdsByBuildProfileId`. ## Contrat de cache et d'invocation Le cache réutilisable `v2` utilise une identité déterministe dérivée du chemin canonique du projet et du checkout de l'éditeur. Les builds sont sérialisés par projet via un verrou de projet et par sortie via un verrou de sortie ; différents projets peuvent se chevaucher uniquement s'ils utilisent des sorties différentes. Le wrapper ne copie pas le projet ; il compile sur place et conserve les intermédiaires dans le cache. `HELENGINE_BUILD_INVOCATION_ID` est un GUID de corrélation interne, et non un paramètre utilisateur. Les codes de sortie (`0`, `2`, `3`, `4`, `5`, `6`, `10`) décrivent les échecs du wrapper et de validation ; les codes de sortie des processus enfants peuvent coïncider, donc les appelants doivent inspecter les diagnostics et `.helengine-build-state.json`. ## Génération de code La génération de code C# vers C++ est un sous-module git situé à `engine/vendor/csharpcodegen`, épinglé par le commit du moteur. Le script de build le publie dans un répertoire `codegen/` à côté de l'éditeur, utilisé pour les builds de plateforme. Les entrées de plateforme ne portent plus de `codegenToolPath` ; les rappels sont ignorés avec un avertissement. Après un clone ou un changement de branche, exécutez `git submodule update --init --recursive`. ## Attente de build vérifiée `tools/build-waiter` attend qu'un build se termine avec succès en capturant le code de sortie, un `.helengine-build-state.json` courant, et la fraîcheur requise des artefacts (par exemple, `game.iso`, `disc/SYSTEM.CNF`). Il se coordonne avec le wrapper via une phase d'accusé de réception. Dans les appels contrôlés par le waiter, le wrapper échoue avec le code de sortie `10` après 30 secondes si l'accusé de réception est manquant. Exemple de build PS2 : ```powershell dotnet run --project ...\helengine.buildwaiter.csproj -- ` --output ...\output\ps2 ` --require game.iso ` --require disc/SYSTEM.CNF ` --require disc/HELENGIN.ELF ` -- powershell ... -File ...\build-platform.ps1 -Project ... -Platform ps2 -Output ... ``` ## Smoke test natif de cache stable Un smoke test natif Windows (`scripts/tests/build-platform-native-cache-smoke.tests.ps1`) nécessite la source de plateforme externe sœur, les outils C++ de Visual Studio, CMake, Ninja, et le builder Windows. Il compile deux fois un petit fixture avec le même cache, en attendant un `helengine_windows.exe` non vide et un fichier d'état de build courant. À exécuter explicitement ; il ne fait pas partie de la suite par défaut.