Horizon 原生模组 (.hnmod)
原生模组是由暂存工具编译成打补丁的 Horizon 客户端的 Rust 混入捆绑包。它们是未沙盒化的代码，拥有完全的用户权限 —— 在任何 UI 副本中明确说明，并将捆绑包视为强大：它可以做游戏能做的任何事情。
两个结构事实驱动一切：
- 引脚。 捆绑包命名了其编译时所针对的精确 Horizon 提交（
horizon_revision，40 位十六进制）以及horizon-mixins提交。或者它声明hooks: N（一个NATIVE_HOOKS_API级别），然后启动器在任何钩子 API 至少为 N 的 Horizon 上构建它 —— 钩子点只增不减，所以这能跨越 Nightly 版本生存。优先使用钩子点。 - 平台。 暂存需要 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 源码，计划/应用混入（约 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；保持它与清单版本一致，否则检查失败。