helengine

# helengine helengine 是一个共享引擎和编辑器工作区，可从项目 `.heproj` 文件构建平台包。它旨在面向受限硬件（例如 DS 和 PS2 等复古主机），同时使用现代资产管线和工具链。 ## 编辑器 CLI 平台构建 平台构建通过 PowerShell 包装脚本 `scripts/build-platform.ps1` 进行编排，该脚本会还原并发布编辑器 CLI，然后直接构建所创作的项目。示例用法： ```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 ``` 关键参数包括 `-Project`（`.heproj` 的路径）、`-Platform`（如项目 `settings/platforms.json` 中所声明）、`-Output`（输出目录）、`-BuildProfile`（例如 `debug` 或 `release`）、`-CacheRoot`（可复用缓存位置）、`-LockTimeout`、`-Clean`、`-PruneCacheOlderThanDays`，以及用于额外编辑器 CLI 参数的 `-AdditionalArgs`。该包装器还支持等待构建以验证其完成。 ## 模块与构建模式 项目代码使用 `code.module.json` 声明。运行时模块仅依赖运行时模块；仅编辑器模块使用 `"moduleKind": "editor"`，并且可以依赖运行时模块。测试文件夹必须命名为 `<module-id>.tests`，并与已声明的生产模块匹配。交互式编辑器会话和编辑器命令使用 `EditorFull`（包括运行时 + 编辑器模块 + 测试），而平台构建使用 `RuntimeOnly`（排除测试/编辑器命令）。平台构建配置文件可以通过 `editorPrebuildCommandIdsByBuildProfileId` 声明有序的预构建命令。 ## 缓存与调用契约 可复用的 `v2` 缓存使用由规范项目路径和编辑器检出派生的确定性标识。构建按项目通过项目锁串行化，并按输出通过输出锁串行化；不同项目只有在使用不同输出时才能重叠。包装器不会复制项目；它就地构建，并将中间产物保留在缓存中。`HELENGINE_BUILD_INVOCATION_ID` 是内部分关联 GUID，不是用户设置。退出码（`0`、`2`、`3`、`4`、`5`、`6`、`10`）描述包装器和验证失败；子进程退出码可能与之重合，因此调用方必须检查诊断信息和 `.helengine-build-state.json`。 ## 代码生成 C# 到 C++ 的代码生成是位于 `engine/vendor/csharpcodegen` 的 git 子模块，由引擎提交固定。构建脚本会将其发布到编辑器旁边的 `codegen/` 目录中，用于平台构建。平台条目不再携带 `codegenToolPath`；相关提醒会被忽略并给出警告。克隆或切换分支后，请运行 `git submodule update --init --recursive`。 ## 已验证的构建等待 `tools/build-waiter` 通过捕获退出码、当前的 `.helengine-build-state.json` 以及所需产物的新鲜度（例如 `game.iso`、`disc/SYSTEM.CNF`）来等待构建成功完成。它通过确认阶段与包装器协调。在由等待器控制的调用中，如果缺少确认，包装器会在 30 秒后以退出码 `10` 失败。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 ... ``` ## 原生稳定缓存冒烟测试 Windows 原生冒烟测试（`scripts/tests/build-platform-native-cache-smoke.tests.ps1`）需要外部同级平台源代码、Visual Studio C++ 工具、CMake、Ninja 和 Windows 构建器。它使用相同的缓存将一个小型夹具构建两次，期望得到非空的 `helengine_windows.exe` 和当前的构建状态文件。需显式运行；它不在默认测试套件中。