CGRLabs/horizon-native-mod

Horizon ネイティブモッド (.hnmod)

ネイティブモッドは、ステージングツールによってパッチ適用済みの Horizon クライアントにコンパイルされる Rust ミキシンバンドルです。これらはサンドボックス化されていないコードであり、完全なユーザー権限で実行されます — あらゆる UI コピーでその旨を明確に伝え、バンドルを強力なものとして扱ってください。ゲームができることはすべて実行できます。

以下は、すべての動作を決定づける 2 つの構造的事実です。

1. ピン留め。 バンドルは、ビルドされた Horizon の正確なコミット（horizon_revision、40 桁の 16 進数）と horizon-mixins のコミットを指定します。あるいは、hooks: N（NATIVE_HOOKS_API レベル）を宣言し、ランチャーはフック API が少なくとも N である 任意の Horizon 上でビルドします — フックポイントは追加されるだけで削除されることはないため、これはナイトリーでも有効です。フックポイントを推奨します。
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               # 注入ポイントごとに 1 ファイル（ヘルパー）
  tools/package.py              # 決定論的 .hnmod をビルド
  tools/horizon.py              # パッチ済みクライアントをステージング + ビルド（gyro から借用）

バンドルごとに 1 つの .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 のフィールド、3 種類の注入（HEAD、RETURN、OVERWRITE）、バインディング構文、$value、[[module]] ランタイムクレート。注入を作成する前に読んでください。
• references/pipeline.md — compatibility.json のフィールドごとの説明、ピン戦略（コミット vs フック）、ステージングの内部、決定論的パッケージングのルール、ランチャーの「GitHub から追加」フロー。パッケージングやピンの選択の前に読んでください。
• references/example-gyro.md — 完全で動作する出荷済みモッド（6 つのフックポイントにわたるカメラロール + 入力キャプチャ）の注釈付きウォークスルー。複雑なものを設計する前に読んで、その構造をコピーしてください。

譲れない条件

• hooks の番号を決して推測しないでください — ピン留めされたコミットに対して検証してください（--check-hooks がこれを行います）。
• ヘルパーファイルは小さく、単一目的に保ち、ロジックは runtime.rs に置いて単体テスト可能にしてください。
• ネイティブモッドはデフォルトではレビューされません：レジストリ/ランチャーに未サンドボックスコード警告が表示され、README にも同様の警告を記載する必要があります。
• Mojang のアセットやコードを同梱しないでください。Horizon と一貫性のある MIT ライセンスとしてください。
• オプション → モッド行は runtime.rs の VERSION を表示します。これをマニフェストのバージョンと等しくしないとチェックに失敗します。