CGRLabs/horizon-native-mod

Horizon Native Mods (.hnmod)

Native Mods sind Rust-Mixin-Bündel, die in einen gepatchten Horizon-Client kompiliert werden – und zwar durch das Staging-Tool. Es handelt sich um nicht-sandboxierten Code, der mit vollen Benutzerrechten läuft – sage dies in jeder UI-Kopie deutlich und behandle das Bündel als mächtig: Es kann alles tun, was das Spiel kann.

Zwei strukturelle Fakten bestimmen alles:

1. Pinning. Ein Bündel benennt den genauen Horizon-Commit, gegen den es gebaut wurde (horizon_revision, 40 Hex-Zeichen) sowie den horizon-mixins-Commit. Alternativ deklariert es hooks: N (eine NATIVE_HOOKS_API-Stufe), und dann baut der Launcher es auf jedem Horizon, dessen Hook-API mindestens N ist – Hook-Punkte werden nur hinzugefügt, nie entfernt, daher überlebt dies Nightlies. Bevorzuge Hook-Punkte.
2. Plattform. Staging erfordert Linux (WSL2 funktioniert), Rust 1.95.0, Python 3.12+, Git. Runtime-Komponententests des Bündels laufen überall, auch unter Windows.

Bündel-Anatomie

<repo>/
  compatibility.json            # Pins + Hooks-Level (siehe references/pipeline.md)
  mixins/<id>/
    horizon-mixin.toml          # Mod-Block + Injektionen (siehe references/mixin-bundle-format.md)
    runtime.rs                  # #[wird als Bibliotheks-Crate in den Client injiziert
    <x>_helper.rs               # eine Datei pro Injektionspunkt (Helfer)
  tools/package.py              # Baut das deterministische .hnmod
  tools/horizon.py              # Staged + baut den gepatchten Client (ausleihen von gyro)

Ein Bündel pro .hnmod; der Ordner unter mixins/ muss exakt nach der Mod-ID benannt sein; nur .rs- und .toml-Dateien werden ausgeliefert.

Die Pipeline (Befehle Ende-zu-Ende verifiziert)

cargo test                                        # Flight-Maths-artige Komponententests, laufen überall
python3 tools/horizon.py stage                    # Exportiert gepinnten Horizon-Quellcode, plant/wendet Mixins an (~3 Min)
cargo check --locked --offline                    # Im gestagten Baum
cargo test --locked --offline
cargo build --profile fast --locked --offline     # Gepatchter Client (~6 Min beim ersten Mal)
python3 tools/package.py --check-hooks            # target/<id>-<version>.hnmod + verifiziert Hooks-Anspruch

--check-hooks lädt native_hooks.rs beim gepinnten Commit und stellt sicher, dass das deklarierte hooks-Level tatsächlich existiert – lass die Nummer nie eine Schätzung sein.

Wo das Wissen lebt

• references/mixin-bundle-format.md – horizon-mixin.toml-Felder, die drei Injektionsarten (HEAD, RETURN, OVERWRITE), Bindungssyntax, $value, das [[module]]-Laufzeit-Crate. Lies dies, bevor du irgendeine Injektion schreibst.
• references/pipeline.md – compatibility.json Feld für Feld, Pin-Strategie (Commit vs. Hooks), Staging-Interna, deterministische Paketierungsregeln, Launcher-Flow "Aus GitHub hinzufügen". Lies dies vor dem Paketieren oder der Wahl von Pins.
• references/example-gyro.md – Kommentierter Durchlauf einer vollständigen, funktionierenden, ausgelieferten Mod (Kamera-Roll + Eingabe-Erfassung über 6 Hook-Punkte). Lies es, bevor du etwas Nicht-Triviales entwirfst; kopiere seine Struktur.

Unverhandelbar

• Errate niemals die hooks-Nummer – verifiziere sie gegen den gepinnten Commit (--check-hooks tut dies).
• Halte Helfer-Dateien winzig und auf einen Zweck beschränkt; platziere Logik in runtime.rs, wo sie einem Komponententest unterzogen werden kann.
• Native Mods werden standardmäßig nicht überprüft: Das Registry/Launcher zeigt eine Warnung vor nicht-sandboxiertem Code an, und deine README muss dies ebenfalls tun.
• Versende keine Mojang-Assets oder -Code; MIT-ähnliche Lizenzierung, konsistent mit Horizon.
• Die Optionen → Mods-Zeile gibt VERSION aus runtime.rs aus; halte sie gleich der Manifest-Version, sonst schlägt die Prüfung fehl.