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#-to-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`와 현재 빌드 상태 파일을 기대합니다. 명시적으로 실행하세요. 기본 스위트에는 포함되지 않습니다.