CGRLabs/horizon-native-mod

Mods Nativos de Horizon (.hnmod)

Los mods nativos son paquetes de mixins en Rust compilados en un cliente Horizon parcheado mediante la herramienta de staging. Son código no sandboxeado que se ejecuta con todos los privilegios del usuario — indícalo claramente en cualquier copia de la UI, y trata el paquete como poderoso: puede hacer cualquier cosa que el juego pueda.

Dos hechos estructurales lo determinan todo:

1. Fijación. Un paquete nombra la confirmación exacta de Horizon contra la que fue construido (horizon_revision, 40 hex) más la confirmación de horizon-mixins. Alternativamente declara hooks: N (un nivel de NATIVE_HOOKS_API) y entonces el lanzador lo construye en cualquier Horizon cuyo API de hooks sea al menos N — los puntos de hook solo se agregan, nunca se eliminan, por lo que esto sobrevive a las versiones nocturnas. Prefiere puntos de hook.
2. Plataforma. El staging requiere Linux (WSL2 funciona), Rust 1.95.0, Python 3.12+, Git. Las pruebas unitarias de tiempo de ejecución del código de la biblioteca del paquete se ejecutan en cualquier lugar, incluido Windows.

Anatomía del paquete

<repo>/
  compatibility.json            # fijaciones + nivel de hooks (ver referencias/pipeline.md)
  mixins/<id>/
    horizon-mixin.toml          # bloque de mod + inyecciones (ver referencias/mixin-bundle-format.md)
    runtime.rs                  # #![used como crate de biblioteca inyectada en el cliente]
    <x>_helper.rs               # un archivo por punto de inyección (helpers)
  tools/package.py              # construye el .hnmod determinista
  tools/horizon.py              # stage + construye el cliente parcheado (tomar prestado de gyro)

Un paquete por .hnmod; la carpeta dentro de mixins/ debe llamarse exactamente como el id del mod; solo se envían archivos .rs y .toml.

El pipeline (comandos verificados de principio a fin)

cargo test                                        # pruebas unitarias estilo flight-maths, ejecutable en cualquier lugar
python3 tools/horizon.py stage                    # exportar código fuente fijado de Horizon, planificar/aplicar mixins (~3 min)
cargo check  --locked --offline                   # en el árbol staged
cargo test   --locked --offline
cargo build  --profile fast --locked --offline    # cliente parcheado (~6 min la primera vez)
python3 tools/package.py --check-hooks            # target/<id>-<version>.hnmod + verifica la declaración de hooks

--check-hooks obtiene native_hooks.rs en la confirmación fijada y afirma que el nivel de hooks declarado realmente existe — nunca permitas que el número sea una suposición.

Dónde vive el conocimiento

• references/mixin-bundle-format.md — campos de horizon-mixin.toml, los tres tipos de inyección (HEAD, RETURN, OVERWRITE), sintaxis de enlace, $value, el [[module]] runtime crate. Léelo antes de escribir cualquier inyección.
• references/pipeline.md — compatibility.json campo por campo, estrategia de fijación (commit vs hooks), internos del staging, reglas de empaquetado determinista, flujo "Añadir desde GitHub" del lanzador. Léelo antes de empaquetar o elegir fijaciones.
• references/example-gyro.md — recorrido anotado de un mod completo, funcional y enviado (rollo de cámara + captura de entrada en 6 puntos de hook). Léelo antes de diseñar algo no trivial; copia su estructura.

No negociables

• Nunca adivines el número de hooks — verifícalo contra la confirmación fijada (--check-hooks hace esto).
• Mantén los archivos helper pequeños y de un solo propósito; pon la lógica en runtime.rs donde pueda ser probada unitariamente.
• Los mods nativos no se revisan por defecto: el registro/lanzador muestra una advertencia de código no sandboxeado, y tu README también debe hacerlo.
• No envíes activos o código de Mojang; licencia de estilo MIT consistente con la de Horizon.
• La fila Opciones → Mods imprime VERSION de runtime.rs; mantenlo igual a la versión del manifiesto o la verificación falla.