Horizon 네이티브 모드 빌더

Horizon 네이티브 모드 (.hnmod)

네이티브 모드는 스테이징 도구가 패치된 Horizon 클라이언트로 컴파일한 Rust 믹신 번들입니다. 이는 완전한 사용자 권한으로 실행되는 샌드박스 없는 코드입니다. UI 카피에 이를 명확히 명시하고, 번들을 강력한 도구로 취급하세요. 게임이 할 수 있는 모든 작업을 수행할 수 있습니다.

모든 것을 결정하는 두 가지 구조적 사실:

1. Pinning. 번들은 빌드된 정확한 Horizon 커밋(horizon_revision, 40자리 16진수)과 horizon-mixins 커밋을 명시합니다. 또는 hooks: N(NATIVE_HOOKS_API 수준)을 선언하면 런처가 후크 API가 최소 N 이상인 모든 Horizon에서 빌드합니다. 후크 포인트는 추가만 되고 제거되지 않으므로, 이 방식이 Nightly에서도 유효합니다. 후크 포인트를 선호하세요.
2. 플랫폼. 스테이징은 Linux(WSL2 작동), Rust 1.95.0, Python 3.12+, Git이 필요합니다. 번들 라이브러리 코드의 런타임 단위 테스트는 Windows를 포함한 모든 곳에서 실행 가능합니다.

번들 구조

<repo>/
  compatibility.json            # 핀 + 후크 수준 (참고: references/pipeline.md)
  mixins/<id>/
    horizon-mixin.toml          # 모드 블록 + 인젝션 (참고: references/mixin-bundle-format.md)
    runtime.rs                  # 클라이언트에 주입되는 라이브러리 크레이트로 사용되는  #[used]
    <x>_helper.rs               # 인젝션 포인트당 하나의 파일 (헬퍼)
  tools/package.py              # 결정적 .hnmod 빌드
  tools/horizon.py              # 패치된 클라이언트 스테이징 + 빌드 (gyro에서 참조)

번들당 하나의 .hnmod; mixins/ 아래 폴더는 모드 ID와 정확히 일치해야 함; .rs와 .toml 파일만 배포됨.

파이프라인 (종단간 검증된 명령)

cargo test                                        # flight-maths 스타일 단위 테스트, 어디서나 실행 가능
python3 tools/horizon.py stage                    # 핀된 Horizon 소스 내보내기, 믹신 계획/적용 (~3분)
cargo check  --locked --offline                   # 스테이징된 트리에서
cargo test   --locked --offline
cargo build  --profile fast --locked --offline    # 패치된 클라이언트 (~6분 첫 빌드)
python3 tools/package.py --check-hooks            # target/<id>-<version>.hnmod + 후크 주장 검증

--check-hooks는 핀된 커밋에서 native_hooks.rs를 가져와 선언된 hooks 수준이 실제로 존재하는지 확인합니다. 숫자를 추측하지 마세요.

지식 소스

• references/mixin-bundle-format.md — horizon-mixin.toml 필드, 세 가지 인젝션 종류(HEAD, RETURN, OVERWRITE), 바인딩 문법, $value, [[module]] 런타임 크레이트. 인젝션 작성 전 반드시 읽으세요.
• references/pipeline.md — compatibility.json 필드별 설명, 핀 전략(커밋 vs 후크), 스테이징 내부, 결정적 패키징 규칙, 런처 "Add from GitHub" 흐름. 패키징 또는 핀 선택 전 반드시 읽으세요.
• references/example-gyro.md — 완전하고 작동하며 출시된 모드(카메라 롤 + 6개 후크 포인트에서 입력 캡처)에 대한 주석 처리된 워크스루. 복잡한 작업을 설계하기 전에 읽고 그 구조를 복사하세요.

불가침 원칙

• hooks 번호를 추측하지 마세요. 핀된 커밋에 대해 검증하세요(--check-hooks가 수행).
• 헬퍼 파일을 작고 단일 목적으로 유지하고, 로직은 runtime.rs에 넣어 단위 테스트 가능하게 하세요.
• 네이티브 모드는 기본적으로 검토되지 않습니다. 레지스트리/런처는 샌드박스 없는 코드 경고를 표시하며, README에도 포함해야 합니다.
• Mojang 자산이나 코드를 배포하지 마세요. Horizon과 일관된 MIT 스타일 라이선스를 사용하세요.
• 설정 → 모드 행에 runtime.rs의 VERSION이 출력됩니다. 매니페스트 버전과 동일하게 유지하지 않으면 검사가 실패합니다.