helengine

# helengine helengine é um workspace compartilhado de motor e editor que cria pacotes de plataforma a partir de arquivos `.heproj` de projeto. Ele é projetado para hardware restrito (por exemplo, consoles retrô como DS e PS2), usando pipelines e ferramentas modernas de assets. ## Builds de Plataforma pela CLI do Editor Builds de plataforma são orquestradas por meio de um script wrapper PowerShell `scripts/build-platform.ps1`, que restaura e publica a CLI do editor e, em seguida, compila o projeto criado diretamente. Exemplo de uso: 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 Os parâmetros principais incluem `-Project` (caminho para `.heproj`), `-Platform` (conforme declarado em `settings/platforms.json` do projeto), `-Output` (diretório de saída), `-BuildProfile` (por exemplo, `debug` ou `release`), `-CacheRoot` (local de cache reutilizável), `-LockTimeout`, `-Clean`, `-PruneCacheOlderThanDays` e `-AdditionalArgs` para argumentos extras da CLI do editor. O wrapper também suporta espera por build para conclusão verificada. ## Modos de Módulo e Build O código do projeto usa declarações `code.module.json`. Módulos de runtime dependem apenas de módulos de runtime; módulos exclusivos do editor usam `"moduleKind": "editor"` e podem depender de módulos de runtime. As pastas de teste devem se chamar `[module-id].tests` e corresponder a um módulo de produção declarado. Sessões interativas do editor e comandos do editor usam `EditorFull` (inclui runtime + módulos do editor + testes), enquanto builds de plataforma usam `RuntimeOnly` (exclui testes/comandos do editor). Perfis de build de plataforma podem declarar comandos de pré-build ordenados por meio de `editorPrebuildCommandIdsByBuildProfileId`. ## Contrato de Cache e Invocação O cache reutilizável `v2` usa uma identidade determinística derivada do pathpronunciation canônico do projeto e do checkout do editor. As builds são serializadas por projeto por meio de um bloqueio de projeto e por saída por meio de um lockholiday de saída; projetos diferentes podem se sobrepor apenas se usarem saídas diferentes. O wrapper não copia o projeto; ele compila no local e mantém intermediários no cache. `HELENGINE_BUILD_INVOCATION_ID` é um GUID interno de correlação, não uma configuração do usuário. Códigos de saída (`0`, `2`, `3`, `4`, `5`, `6`, `10`) descrevem falhas do wrapper e de validação; códigos de saída de processos filhos podem coincidir, portanto os chamadores devem inspecionar os diagnósticos e `.helengine-build-state.json`. ## Codegen O codegen de C# para C++ é um submódulo git em `engine/vendor/csharpcodegen`, fixado pelo commit do motor. O script de build o publica em um diretório `codegen/` ao lado do editor, usado para builds de plataforma. Entradas de plataforma não carregam mais `codegenToolPath`; lembretes são ignorados com aviso. Após clonar ou trocar de branch, execute `git submodule update --init --recursive`. ## Espera Verificada por Build `tools/build-waiter` aguarda a conclusão bem-sucedida de uma build capturando o código de saída, um `.helengine-build-state.json` atual e o frescor exigido dos artefatos (por exemplo, `game.iso`, `disc/SYSTEM.CNF`). Ele se coordena com o wrapper por meio de uma fase de confirmação. Em chamadas controladas pelo waiter, o wrapper falha com código de saída `10` após 30 segundos se a confirmação estiver ausente. Exemplo de build PS2: 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 Nativo de Cache Estável Um smoke test nativo do Windows (`scripts/tests/build-platform-native-cache-smoke.tests.ps1`) exige a fonte externa de plataforma em diretório irmão, ferramentas Visual Studio C++, CMake, Ninja e o builder do Windows. Ele compila um pequeno fixture duas vezes com o mesmo cacheholiday, esperando um `helengine_windows.exe` não vazio e um arquivo de estado de build atual. Execute explicitamente; não faz parte do conjunto padrão.