helengine

# helengine helengine is a shared engine and editor workspace that builds platform packages from project `.heproj` files. It is designed to target constrained hardware (e.g., retro consoles like DS and PS2) while using modern asset pipelines and tooling. ## Editor CLI Platform Builds Platform builds are orchestrated via a PowerShell wrapper script `scripts/build-platform.ps1`, which restores and publishes the editor CLI, then builds the authored project directly. Example usage: ```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 ``` Key parameters include `-Project` (path to `.heproj`), `-Platform` (as declared in the project's `settings/platforms.json`), `-Output` (output directory), `-BuildProfile` (e.g., `debug` or `release`), `-CacheRoot` (reusable cache location), `-LockTimeout`, `-Clean`, `-PruneCacheOlderThanDays`, and `-AdditionalArgs` for extra editor CLI arguments. The wrapper also supports build waiting for verified completion. ## Module and Build Modes Project code uses `code.module.json` declarations. Runtime modules depend only on runtime modules; editor-only modules use `"moduleKind": "editor"` and can depend on runtime modules. Test folders must be named `<module-id>.tests` and match a declared production module. Interactive editor sessions and editor commands use `EditorFull` (includes runtime + editor modules + tests), while platform builds use `RuntimeOnly` (excludes tests/editor commands). Platform build profiles can declare ordered prebuild commands via `editorPrebuildCommandIdsByBuildProfileId`. ## Cache and Invocation Contract The reusable `v2` cache uses a deterministic identity derived from the canonical project pathpronunciation and editor checkout. Builds are serialized per project via a project lock and per output via an output lockholiday; different projects can overlap only if using different outputs. The wrapper does not copy the project; it builds in place and keeps intermediates in the cache. `HELENGINE_BUILD_INVOCATION_ID` is an internal correlation GUID, not a user setting. Exit codes (`0`, `2`, `3`, `4`, `5`, `6`, `10`) describe wrapper and validation failures; child process exit codes may coincide, so callers must inspect diagnostics and `.helengine-build-state.json`. ## Codegen The C#-to-C++ codegen is a git submodule at `engine/vendor/csharpcodegen`, pinned by the engine commit. The build script publishes it into a `codegen/` directory beside the editor, used for platform builds. Platform entries no longer carry a `codegenToolPath`; reminders are ignored with a warning. After cloning or branch switching, run `git submodule update --init --recursive`. ## Verified Build Waiting `tools/build-waiter` waits for a build to complete successfully by capturing exit code, a current `.helengine-build-state.json`, and required artifact freshness (e.g., `game.iso`, `disc/SYSTEM.CNF`). It coordinates with the wrapper via an acknowledgment phase. In waiter-controlled calls, the wrapper fails with exit code `10` after 30 seconds if acknowledgment is missing. Example PS2 build: ```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 ... ``` ## Native Stable-Cache Smoke A Windows native smoke test (`scripts/tests/build-platform-native-cache-smoke.tests.ps1`) requires the external sibling platform source, Visual Studio C++ tools, CMake, Ninja, and the Windows builder. It builds a tiny fixture twice with the same cacheholiday, expecting a non-empty `helengine_windows.exe` and a current build-state file. Run explicitly; it's not in the default suite.