Horizon 原生模組 (.hnmod)
原生模組是由暫存工具編譯到修補後的 Horizon 用戶端中的 Rust mixin 套件。它們是未經沙盒處理、擁有完整使用者權限的程式碼——請在任何使用者介面文案中明確說明，並將套件視為強大的工具：它可以執行遊戲能做的任何事情。
兩個結構性事實驅動一切：
- 固定 (Pinning)。 套件指定它所針對的具體 Horizon 提交版本 (
horizon_revision，40 位十六進位) 加上horizon-mixins的提交版本。或者，它宣告hooks: N（一個NATIVE_HOOKS_API等級），然後啟動器可以在任何鉤子 API 至少為 N 的 Horizon 版本上建置它——鉤子點只會新增，不會移除，因此這能與夜版相容。優先使用鉤子點。 - 平台。 暫存需要 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 # 作為注入到用戶端中的庫 crate
<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 原始碼，規劃/套用 mixin（約 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]]執行時期 crate。在撰寫任何注入之前請先閱讀。references/pipeline.md—compatibility.json各欄位詳述、固定策略（提交 vs 鉤子）、暫存內部機制、確定性打包規則、啟動器「從 GitHub 新增」流程。在打包或選擇固定點之前請先閱讀。references/example-gyro.md— 一個完整、可運作、已出貨的模組（6 個鉤子點的鏡頭旋轉 + 輸入捕捉）的註釋式逐步解說。在設計任何非平凡功能之前請先閱讀；複製其結構。
不可妥協的原則
- 永遠不要猜測
hooks數字——請根據固定的提交版本驗證（--check-hooks會執行此操作）。 - 保持輔助檔案小巧且單一用途；將邏輯放在
runtime.rs中以便進行單元測試。 - 原生模組預設不會被審查：註冊表/啟動器會顯示未經沙盒處理的程式碼警告，你的 README 也必須包含此警告。
- 不得包含 Mojang 的資產或程式碼；採用與 Horizon 一致的 MIT 風格授權。
- 設定 → 模組行會顯示
runtime.rs中的VERSION；請保持它與清單版本一致，否則檢查會失敗。