Crea tu primer mod de salud con Lua para SM64CoopDX

Tu primer modo de juego no necesita una estructura enorme. En este tutorial crearás una carpeta, escribirás un archivo main.lua y conectarás una función al evento que actualiza a Mario.

El resultado será un pequeño entrenador de salud: al pulsar arriba en la cruceta, recuperarás una porción de salud del jugador local sin superar el valor normal de salud completa.

Lo que aprenderás

• Cómo detecta SM64CoopDX un mod escrito en Lua.
• Cómo HOOK_MARIO_UPDATE llama a tu función para cada jugador.
• Por qué el parámetro m es más seguro que leer gMarioStates[0] dentro de este hook.
• Cómo se relaciona el medidor circular de salud con valores enteros y hexadecimales.
• Cómo probar y depurar el mod desde la consola del juego.

Requisitos previos

Comprende el medidor de salud

El campo MarioState.health es un número entero. La guía oficial de MarioState identifica 0x880 como la salud completa, mientras que el ejemplo oficial del HUD documenta el rango del medidor desde 0xFF hasta 0x880.

Cada porción visible ocupa 0x100 unidades de salud. En decimal, 0x100 equivale a 256. Lua acepta ambos formatos, por lo que estas operaciones son equivalentes:

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

Construye el mod

1. Crea la carpeta del mod

   Crea una carpeta llamada first-health-mod dentro de tu carpeta mods.

   La referencia oficial permite que la carpeta de un mod contenga varios archivos Lua siempre que uno se llame main.lua. Este tutorial solo necesita ese archivo.

   Verificación: La carpeta nueva está dentro de una ubicación de mods compatible con SM64CoopDX.

2. Crea main.lua

   Dentro de first-health-mod, crea un archivo de texto plano llamado main.lua.

   Verificación: El archivo se llama main.lua y no main.lua.txt.

3. Añade el entrenador de salud

   Pega este ejemplo completo en 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)

   Entrenador local completo que utiliza las API documentadas de MarioState, Controller, entrada y hooks.

   Fuente: Ejemplo original basado en la referencia Lua oficial de SM64CoopDX

   Verificación: El archivo contiene las constantes, la función de actualización y el hook mostrados abajo.

4. Inicia el juego y activa el mod

   Inicia SM64CoopDX, abre su lista de mods y activa First Health Mod. Si el juego ya estaba abierto cuando creaste los archivos, reinícialo para que cargue el mod nuevo.

   Verificación: First Health Mod aparece en la lista de mods y está activado.

5. Prueba el resultado

   Entra a un nivel, pierde al menos una porción de salud y pulsa arriba en la cruceta una vez. El medidor debe aumentar una porción, salvo que Mario ya tenga la salud completa.

   Verificación: Una pulsación hacia arriba recupera salud y el chat confirma la acción.

Cómo funciona el código

Las constantes hacen legibles las reglas

HEALTH_SLICE almacena 0x100, que equivale a 256 en decimal. FULL_HEALTH almacena el máximo documentado de 0x880. Dar nombres a estos valores aclara su intención y evita repetir números sin explicación.

El hook proporciona MarioState

La referencia oficial indica que HOOK_MARIO_UPDATE se ejecuta una vez por jugador y por fotograma al final de la actualización de ese jugador. También entrega un valor MarioState a la función. Ese valor es el parámetro m de mario_update(m).

La guía de MarioState recomienda utilizar este m en lugar de gMarioStates[0] cuando el hook ya lo proporciona.

La comprobación limita el cambio al jugador local

Como el hook se ejecuta para cada jugador, esta línea detiene la función para los jugadores remotos:

if m.playerIndex ~= 0 then return end

Esto convierte el entrenador en un efecto local. No intenta sincronizar ni modificar la salud de otro jugador.

buttonPressed realiza una acción por pulsación

La estructura Controller expone buttonPressed y la referencia de constantes expone U_JPAD. La comprobación de bits detecta arriba en la cruceta durante la actualización actual. A diferencia de buttonDown, buttonPressed evita sumar salud continuamente mientras mantienes pulsado el botón.

math.min respeta el máximo normal

Esta expresión suma una porción y elige el valor menor entre el resultado y la salud completa:

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

Resultado esperado

Problemas comunes

El mod no aparece

Comprueba que la estructura de carpetas sea exactamente esta:

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

Comprueba también que tu editor no haya guardado el archivo como main.lua.txt.

Pulsar arriba no hace nada

Asegúrate de que el mod esté activado y de que el juego reconozca la cruceta. Haz la prueba después de que Mario haya perdido salud, porque el límite impide intencionalmente superar 0x880.

El juego muestra un error de Lua

La referencia oficial recomienda iniciar el juego desde una consola con el parámetro --console mientras desarrollas mods Lua. Los errores de Lua y la salida de print() aparecerán allí. Lee el primer error, identifica el archivo y la línea, corrígelo y después reinicia o vuelve a cargar el mod.

Próximo paso

Ya tienes la estructura esencial de un modo de juego Lua: un archivo de entrada main.lua, un callback, un hook documentado, un campo del estado del jugador y un resultado observable.

Como siguiente ejercicio puedes sustituir la constante del botón por otra constante documentada de Controller, o mostrar el valor actual con djui_chat_message_create(tostring(m.health)). Continúa utilizando el m que entrega HOOK_MARIO_UPDATE y conserva la comprobación del jugador local cuando el comportamiento esté destinado únicamente al jugador actual.

Fuentes oficiales

Los detalles técnicos de este tutorial se verificaron por última vez el 30 de septiembre de 2026 con el commit 8cd6e5977d9f920d51ca71f2c61801d019ed79c6 de SM64CoopDX.