Crie seu primeiro mod de vida com Lua para SM64CoopDX

Seu primeiro modo de jogo não precisa de uma estrutura enorme. Neste tutorial, você criará uma pasta, escreverá um arquivo main.lua e conectará uma função ao evento que atualiza Mario.

O resultado será um pequeno treinador de vida: ao pressionar para cima no direcional, você recuperará uma fatia da vida do jogador local sem ultrapassar o valor normal de vida completa.

O que você aprenderá

• Como o SM64CoopDX encontra um mod escrito em Lua.
• Como HOOK_MARIO_UPDATE chama sua função para cada jogador.
• Por que o parâmetro m é mais seguro do que ler gMarioStates[0] dentro deste hook.
• Como o medidor circular de vida corresponde a valores inteiros e hexadecimais.
• Como testar e depurar o mod pelo console do jogo.

Pré-requisitos

Entenda o medidor de vida

O campo MarioState.health é um número inteiro. O guia oficial de MarioState identifica 0x880 como vida completa, enquanto o exemplo oficial de HUD documenta o intervalo do medidor entre 0xFF e 0x880.

Cada fatia visível ocupa 0x100 unidades de vida. Em decimal, 0x100 equivale a 256. Lua aceita os dois formatos, portanto estas operações são equivalentes:

m.health = m.health + 256
m.health = m.health + 0x100

Construa o mod

1. Crie a pasta do mod

   Crie uma pasta chamada first-health-mod dentro da sua pasta mods.

   A referência oficial permite que a pasta de um mod contenha vários arquivos Lua, desde que um deles se chame main.lua. Este tutorial precisa apenas desse arquivo.

   Verificação: A nova pasta está dentro de um local de mods compatível com o SM64CoopDX.

2. Crie main.lua

   Dentro de first-health-mod, crie um arquivo de texto simples chamado main.lua.

   Verificação: O arquivo se chama main.lua, e não main.lua.txt.

3. Adicione o treinador de vida

   Cole este exemplo completo em main.lua:

   -- name: First Health Mod
   -- description: Press D-pad Up to restore one health slice.
   
   local HEALTH_SLICE = 0x100
   local FULL_HEALTH = 0x880
   
   local function mario_update(m)
     -- HOOK_MARIO_UPDATE runs once per player each frame.
     -- Player index 0 is the local player on each client.
     if m.playerIndex ~= 0 then return end
   
     if (m.controller.buttonPressed & U_JPAD) ~= 0 then
         m.health = math.min(m.health + HEALTH_SLICE, FULL_HEALTH)
         djui_chat_message_create("Restored one health slice")
     end
   end
   
   hook_event(HOOK_MARIO_UPDATE, mario_update)

   Treinador local completo que utiliza as APIs documentadas de MarioState, Controller, entrada e hooks.

   Fonte: Exemplo original baseado na referência Lua oficial do SM64CoopDX

   Verificação: O arquivo contém as constantes, a função de atualização e o hook mostrados abaixo.

4. Inicie o jogo e ative o mod

   Inicie o SM64CoopDX, abra a lista de mods e ative First Health Mod. Se o jogo já estava aberto quando você criou os arquivos, reinicie-o para carregar o novo mod.

   Verificação: First Health Mod aparece na lista de mods e está ativado.

5. Teste o resultado

   Entre em uma fase, perca pelo menos uma fatia de vida e pressione para cima no direcional uma vez. O medidor deve aumentar uma fatia, a menos que Mario já esteja com a vida completa.

   Verificação: Uma pressão para cima recupera vida e o chat confirma a ação.

Como o código funciona

As constantes deixam as regras legíveis

HEALTH_SLICE armazena 0x100, que equivale a 256 em decimal. FULL_HEALTH armazena o máximo documentado de 0x880. Dar nomes a esses valores esclarece a intenção e evita repetir números sem explicação.

O hook fornece MarioState

A referência oficial informa que HOOK_MARIO_UPDATE é executado uma vez por jogador e por quadro, no final da atualização desse jogador. Ele também entrega um valor MarioState à função. Esse valor é o parâmetro m de mario_update(m).

O guia de MarioState recomenda utilizar esse m em vez de gMarioStates[0] quando o hook já o fornece.

A verificação limita a mudança ao jogador local

Como o hook é executado para cada jogador, esta linha interrompe a função para jogadores remotos:

if m.playerIndex ~= 0 then return end

Isso transforma o treinador em um efeito local. Ele não tenta sincronizar nem modificar a vida de outro jogador.

buttonPressed realiza uma ação por pressão

A estrutura Controller expõe buttonPressed, e a referência de constantes expõe U_JPAD. A verificação de bits detecta para cima no direcional durante a atualização atual. Ao contrário de buttonDown, buttonPressed evita somar vida continuamente enquanto o botão permanece pressionado.

math.min respeita o máximo normal

Esta expressão soma uma fatia e escolhe o menor valor entre o resultado e a vida completa:

m.health = math.min(m.health + HEALTH_SLICE, FULL_HEALTH)

Resultado esperado

Problemas comuns

O mod não aparece

Confirme se a estrutura de pastas é exatamente esta:

mods/
└── first-health-mod/
  └── main.lua

Verifique também se o editor não salvou o arquivo como main.lua.txt.

Pressionar para cima não faz nada

Verifique se o mod está ativado e se o jogo reconhece o direcional. Faça o teste depois que Mario perder vida, pois o limite impede intencionalmente que o valor ultrapasse 0x880.

O jogo mostra um erro de Lua

A referência oficial recomenda iniciar o jogo por um console com o parâmetro --console durante o desenvolvimento de mods Lua. Os erros de Lua e a saída de print() aparecerão ali. Leia o primeiro erro, identifique o arquivo e a linha, corrija-o e depois reinicie ou recarregue o mod.

Próximo passo

Agora você tem a estrutura essencial de um modo de jogo Lua: um arquivo de entrada main.lua, um callback, um hook documentado, um campo do estado do jogador e um resultado observável.

Como próximo exercício, você pode substituir a constante do botão por outra constante documentada de Controller ou mostrar o valor atual com djui_chat_message_create(tostring(m.health)). Continue utilizando o m fornecido por HOOK_MARIO_UPDATE e mantenha a verificação do jogador local quando o comportamento for destinado apenas ao jogador atual.

Fontes oficiais

Os detalhes técnicos deste tutorial foram verificados pela última vez em 30 de setembro de 2026 com o commit 8cd6e5977d9f920d51ca71f2c61801d019ed79c6 do SM64CoopDX.