Jumpfall Modding Lua Tutorial

1. Idea general

Jumpfall usa Lua para scripts de mapas. Esto sirve para hacer eventos simples sin instalar cargadores externos ni tocar la carpeta raiz del juego.

El runtime usa MoonSharp embebido en Unity. No hace falta instalar Lua en Windows, macOS o Linux.

El modding Lua recomendado vive dentro del mapa y se empaqueta con el archivo .jsm.

2. Carpetas importantes

Carpeta	Uso
`Documents\jumpfall\levels\assetslocal\lua`	Scripts Lua locales mientras creas un mapa.
`Documents\jumpfall\levels\assetslocal\sound`	Sonidos locales que los scripts o la banda sonora pueden usar.
`Documents\jumpfall\levels\assetslocal\backgroundimg`	Fondos PNG locales usados por el Level Editor.
`Documents\jumpfall\levels\workshop\{workshopid}\assetlocal\lua`	Scripts Lua instalados desde Workshop dentro de un mapa publicado.

El archivo de entrada por defecto es main.lua. Si el mapa no tiene ese archivo, no pasa nada: el mapa carga sin Lua.

Si un mapa compilado no debe usar Lua, su configuracion puede dejar lua.enabled en false.

3. Primer script

Crea este archivo:

Documents\jumpfall\levels\assetslocal\lua\main.lua

Ejemplo basico:

function on_level_start()
  jf.log("Lua cargado en " .. jf.map_name)
end

function on_update(dt)
  local pos = jf.player.position()

  if pos.y < -20 then
    jf.player.damage(999)
  end
end

function on_trigger_enter(trigger_id, x, y)
  jf.log("Trigger tocado: " .. trigger_id)

  if trigger_id == "finish_level" then
    jf.level.finish()
  end
end

Guarda el mapa, entra en playtest con F5 y mira la consola de Unity o la dev console del juego.

4. API disponible

Eventos

Funcion	Cuando se llama
`on_level_start()`	Un frame despues de cargar el mapa, para que el jugador ya exista.
`on_update(dt)`	Cada frame mientras el mapa esta activo.
`on_trigger_enter(trigger_id, x, y)`	Cuando el jugador entra en un trigger runtime. En un trigger `lua_event`, el primer valor es el nombre configurado del evento.
`on_trigger_enter_ex(event_name, raw_trigger_id, x, y)`	Version extendida: entrega el nombre de evento y tambien el id real del trigger.
`on_lua_event(event_name, x, y)`	Solo se llama cuando el jugador toca un trigger `lua_event`.

Trigger lua_event

Un trigger lua_event no cambia de mapa ni termina el nivel. Solo avisa al script Lua con el nombre configurado.

En el Level Editor se coloca desde el modo triggers (F6). Para configurarlo, activa edicion de objetos con F4, selecciona el trigger y presiona E.

function on_lua_event(event_name, x, y)
  if event_name == "open_door" then
    jf.log("Abrir puerta desde Lua")
  end
end

Funciones generales

Funcion	Uso
`jf.log(texto)`	Escribe un mensaje en consola.
`jf.time()`	Devuelve el tiempo de Unity.
`jf.dt()`	Devuelve el ultimo delta time registrado.

Variables simples

jf.vars.set("coins", 0)
jf.vars.add("coins", 1)
local coins = jf.vars.get("coins")

Solo se guardan valores simples: nil, booleanos, numeros y texto.

Jugador

Funcion	Detalle
`jf.player.position()`	Devuelve una tabla con `x` e `y`.
`jf.player.set_velocity(x, y)`	Cambia la velocidad del Rigidbody2D con limite interno.
`jf.player.add_force(x, y)`	Aplica un impulso limitado.
`jf.player.damage(amount)`	Hace dano al jugador.
`jf.player.heal(amount)`	Cura al jugador.
`jf.player.set_gravity(value)`	Cambia la gravedad del jugador entre 0 y 12.
`jf.player.set_move_speed(value)`	Cambia la velocidad base entre 0 y 30.
`jf.player.set_jump_force(value)`	Cambia la fuerza de salto entre 0 y 60.

Nivel

Funcion	Detalle
`jf.level.finish()`	En playtest muestra el mensaje de final. En runtime vuelve a `Menugame`.
`jf.level.change("mapa")`	Carga un `.jfue` por nombre usando el cargador de mapas compilados.

Audio

function on_level_start()
  jf.audio.play("campana.ogg", 0.8)
end

Los sonidos deben estar en assetlocal\sound y ser .wav u .ogg.

5. Como entra Lua en un .jsm

Cuando compilas un mapa para Workshop, el paquete .jsm debe tener esta forma:

mi_mapa.jfue
manifest.json
assetlocal/backgroundimg/background.png
assetlocal/sound/campana.ogg
assetlocal/lua/main.lua

El juego instala ese paquete en:

Documents\jumpfall\levels\workshop\{workshopid}

Al cargar el .jfue, Jumpfall busca el script en la carpeta assetlocal\lua de ese mapa.

6. Seguridad y limites

Lua corre en sandbox duro de MoonSharp.
No se exponen io, os, debug, package ni require.
Los scripts no reciben rutas reales del sistema.
Cada archivo .lua tiene limite de 512 KB.
Los errores runtime se cuentan; despues de varios errores, el script se desactiva.
Las funciones que mueven al jugador tienen limites internos para evitar valores absurdos.

Lua es el camino recomendado para mods de mapas. El parametro -dev_insecure solo debe usarse para pruebas avanzadas con cargadores externos, porque reduce las protecciones del juego.

Evita loops infinitos como while true do end. Aunque el sandbox bloquea acceso peligroso, un loop infinito puede congelar el juego.

7. Probar y depurar

Coloca main.lua en Documents\jumpfall\levels\assetslocal\lua.
Abre el Level Editor.
Presiona F5 para probar.
Usa jf.log("mensaje") para confirmar que el script carga.
Compila con F8 cuando quieras crear el .jfue y el .jsm.

Para abrir la dev console del juego en build, activa el parametro de lanzamiento dev_console y usa F11.

Comandos utiles de consola: luapath muestra la carpeta local de Lua y luascripts lista los scripts encontrados.