CGRLabs/horizon-native-mod

Mods Natifs Horizon (.hnmod)

Les mods natifs sont des bundles de mixins Rust compilés dans un client Horizon patché par l'outil de staging. Ce sont des codes non sandboxés s'exécutant avec tous les privilèges de l'utilisateur — dites-le clairement dans toute copie d'interface utilisateur, et traitez le bundle comme puissant : il peut faire tout ce que le jeu peut faire.

Deux faits structurels régissent tout :

1. Pinning. Un bundle nomme le commit exact d'Horizon contre lequel il a été compilé (horizon_revision, 40 hex) ainsi que le commit de horizon-mixins. Alternativement, il déclare hooks: N (un niveau NATIVE_HOOKS_API) et le lanceur le construit sur tout Horizon dont l'API de hooks est au moins N — les points de hook sont uniquement ajoutés, jamais supprimés, c'est donc ce qui survive aux Nightlies. Préférez les points de hook.
2. Plateforme. Le staging nécessite Linux (WSL2 fonctionne), Rust 1.95.0, Python 3.12+, Git. Les tests unitaires d'exécution du code de la bibliothèque du bundle peuvent être effectués partout, y compris sous Windows.

Anatomie du bundle

<repo>/
  compatibility.json            # pins + niveau de hooks (voir references/pipeline.md)
  mixins/<id>/
    horizon-mixin.toml          # bloc de mod + injections (voir references/mixin-bundle-format.md)
    runtime.rs                  # #[ utilisé comme crate de bibliothèque injectée dans le client
    <x>_helper.rs               # un fichier par point d'injection (helpers)
  tools/package.py              # construit le .hnmod déterministe
  tools/horizon.py              # staging + construction du client patché (emprunter à gyro)

Un bundle par .hnmod ; le dossier sous mixins/ doit être nommé exactement l'identifiant du mod ; seuls les fichiers .rs et .toml sont expédiés.

Le pipeline (commandes vérifiées de bout en bout)

cargo test                                        # tests unitaires de type flight-maths, exécutables partout
python3 tools/horizon.py stage                    # exporter le code source Horizon épinglé, planifier/appliquer les mixins (~3 min)
cargo check  --locked --offline                   # dans l'arbre stagé
cargo test   --locked --offline
cargo build  --profile fast --locked --offline    # client patché (~6 min la première fois)
python3 tools/package.py --check-hooks            # target/<id>-<version>.hnmod + vérifie la déclaration de hooks

--check-hooks récupère native_hooks.rs au commit épinglé et affirme que le niveau de hooks déclaré existe vraiment — ne laissez jamais le nombre être une supposition.

Où se trouve la connaissance

• references/mixin-bundle-format.md — champs de horizon-mixin.toml, les trois types d'injection (HEAD, RETURN, OVERWRITE), la syntaxe de liaison, $value, le [[module]] de la crate d'exécution. Lisez-le avant d'écrire une injection.
• references/pipeline.md — champ par champ de compatibility.json, stratégie de pinning (commit vs hooks), internes du staging, règles de packaging déterministes, flux « Ajouter depuis GitHub » du lanceur. Lisez-le avant de packager ou de choisir des pins.
• references/example-gyro.md — walkthrough annoté d'un mod complet, fonctionnel et livré (roulis de caméra + capture d'entrée sur 6 points de hook). Lisez-le avant de concevoir quoi que ce soit de non trivial ; copiez sa structure.

Non-négociables

• Ne devinez jamais le numéro de hooks — vérifiez-le contre le commit épinglé (--check-hooks le fait).
• Gardez les fichiers helpers petits et à but unique ; mettez la logique dans runtime.rs où elle peut être testée unitairement.
• Les mods natifs ne sont pas revus par défaut : le registre/le lanceur affiche un avertissement de code non sandboxé, et votre README doit aussi le faire.
• N'expédiez pas d'actifs ou de code Mojang ; licence de type MIT cohérente avec celle d'Horizon.
• La ligne Options → Mods affiche VERSION depuis runtime.rs ; maintenez-la égale à la version du manifeste ou la vérification échoue.