CGRLabs/horizon-native-mod

Mods Nativos do Horizon (.hnmod)

Mods nativos são bundles de mixin Rust compilados em um cliente Horizon patched pela ferramenta de preparação. Eles são código não isolado executando com privilégios completos do usuário — diga isso claramente em qualquer texto de interface e trate o bundle como poderoso: ele pode fazer qualquer coisa que o jogo pode.

Dois fatos estruturais orientam tudo:

1. Fixação (Pinning). Um bundle nomeia o commit exato do Horizon contra o qual foi compilado (horizon_revision, 40 hexadecimais) mais o commit do horizon-mixins. Alternativamente, declara hooks: N (um nível NATIVE_HOOKS_API) e então o launcher o compila em qualquer Horizon cuja API de hooks seja pelo menos N — pontos de hook são apenas adicionados, nunca removidos, então isso sobrevive a Nightlies. Prefira pontos de hook.
2. Plataforma. A preparação requer Linux (WSL2 funciona), Rust 1.95.0, Python 3.12+, Git. Testes unitários de tempo de execução do código da biblioteca do bundle rodam em qualquer lugar, incluindo Windows.

Anatomia do bundle

<repo>/
  compatibility.json            # fixações + nível de hooks (veja referências/pipeline.md)
  mixins/<id>/
    horizon-mixin.toml          # bloco do mod + injeções (veja referências/formato-bundle-mixin.md)
    runtime.rs                  # #[ usado como uma crate de biblioteca injetada no cliente
    <x>_helper.rs               # um arquivo por ponto de injeção (helpers)
  tools/package.py              # compila o .hnmod determinístico
  tools/horizon.py              # preparam + compila o cliente patched (emprestado do gyro)

Um bundle por .hnmod; a pasta dentro de mixins/ deve ser nomeada exatamente com o id do mod; apenas arquivos .rs e .toml são enviados.

O pipeline (comandos verificados de ponta a ponta)

cargo test                                        # testes unitários estilo flight-maths, rodam em qualquer lugar
python3 tools/horizon.py stage                    # exporta código-fonte fixado do Horizon, planeja/aplica mixins (~3 min)
cargo check  --locked --offline                   # na árvore preparada
cargo test   --locked --offline
cargo build  --profile fast --locked --offline    # cliente patched (~6 min na primeira vez)
python3 tools/package.py --check-hooks            # target/<id>-<version>.hnmod + verifica a reivindicação de hooks

--check-hooks baixa native_hooks.rs no commit fixado e afirma que o nível hooks declarado realmente existe — nunca deixe o número ser um palpite.

Onde o conhecimento reside

• referências/formato-bundle-mixin.md — campos do horizon-mixin.toml, os três tipos de injeção (HEAD, RETURN, OVERWRITE), sintaxe de vinculação, $value, o [[module]] crate de tempo de execução. Leia antes de escrever qualquer injeção.
• referências/pipeline.md — compatibility.json campo por campo, estratégia de fixação (commit vs hooks), detalhes internos da preparação, regras de empacotamento determinístico, fluxo "Adicionar do GitHub" do launcher. Leia antes de empacotar ou escolher fixações.
• referências/exemplo-gyro.md — passo a passo anotado de um mod completo, funcional e enviado (rolagem de câmera + captura de entrada em 6 pontos de hook). Leia antes de projetar algo não trivial; copie sua estrutura.

Inegociáveis

• Nunca adivinhe o número hooks — verifique contra o commit fixado (--check-hooks faz isso).
• Mantenha arquivos auxiliares pequenos e de propósito único; coloque a lógica em runtime.rs onde possa ser testada unitariamente.
• Mods nativos não são revisados por padrão: o registro/launcher mostra um aviso de código não isolado, e seu README também deve mostrar.
• Não envie ativos ou código da Mojang; licenciamento estilo MIT consistente com o do Horizon.
• A linha Opções → Mods imprime VERSION de runtime.rs; mantenha-o igual à versão do manifesto ou a verificação falha.