Guía de Lua

Con Lua cada servidor puede agregar sus propios sistemas sin tocar los ejecutables: premios, eventos, comandos, NPC, reglas de PvP, ventanas propias en el cliente y mucho más. IGK usa Lua 5.4 en el GameServer y en el cliente (PC, Android y navegador).

#Qué se puede hacer

• Reaccionar a lo que pasa en el juego: entrar al juego, matar un monstruo o a un jugador, subir de nivel, mover o usar ítems, abrir el baúl, cambiar de mapa, revivir y más (27 eventos).
• Cambiar o bloquear acciones: prohibir el PvP en un mapa, que matar no deje PK, cambiar el daño de un golpe, impedir recoger o tirar un ítem, dar otros puntos por nivel, hacer el drop de un monstruo.
• Leer y cambiar el personaje: nivel, puntos, estadísticas, vida, maná, SD, PK, resets, VIP, monedas, buffs, party y guild (más de 300 funciones).
• Ítems: dar ítems con todas sus opciones, tirarlos al suelo, contarlos y quitarlos, mandarlos al Gremory Case.
• Monstruos: crearlos, borrarlos, invocaciones propias.
• Base de datos segura: consultas que no frenan el juego y no se pueden inyectar, y datos guardados sin escribir SQL.
• Paquetes propios entre el servidor y el cliente, y ventanas propias en el cliente (en las tres plataformas).
• Temporizadores y horarios: cada N segundos, a una hora, un día de la semana.

#Dónde están y cómo se activan

Activar un script: en ScriptMain.lua agrega una línea al final:

require('Scripts\\MiScript')              -- un archivo: Data\Script\Scripts\MiScript.lua
requirefolder('Scripts\\MisEventos')      -- todos los .lua de una carpeta, en orden alfabético

Recargar sin reiniciar: escribe /reload lua en el juego (solo los scripts) o /reload custom (los scripts y todos los sistemas custom). Al recargar, todo lo que el script tenía en memoria se pierde: lo que deba durar, guárdalo con DataSet o en la base.

Si falta ScriptMain.lua, no hay scripts y no pasa nada.

#Seguridad y límites

• Encerrados: los scripts no pueden leer ni escribir archivos (salvo los .ini de Data\Script con ConfigSaveString), ni ejecutar programas, ni cargar librerías, ni código compilado. require solo carga archivos de Data\Script.
• Tiempo: si un evento tarda más de 3 segundos (10 al cargar), el script se corta con un error y el servidor sigue. Un while true do end ya no cuelga el GameServer.
• Memoria: todos los scripts juntos pueden usar hasta 256 MB.
• Errores: un error se escribe en rojo en la consola, en el log del GameServer ([Lua] ...) y en LOGS\LUA_LOG\<fecha>.txt, y el servidor sigue funcionando. En el panel IGK Host, la pestaña Lua de la consola muestra todos los errores con el archivo y la línea (un clic abre el archivo en esa línea) y tiene el botón Revisar todos los scripts. Al guardar un .lua desde el panel se revisa su sintaxis: si tiene un error, se marca la línea en el editor. Si falla un evento que puede bloquear algo (por ejemplo, "¿puede atacar?"), el juego hace lo normal: un script con errores nunca bloquea al juego.
• Rendimiento: los eventos frecuentes (daño, ítems, movimiento) solo se llaman si algún script se enganchó a ellos. Engancha solo los que uses.

#Cómo se escribe un script

Cada script se engancha a los eventos que le interesan con BridgeFunctionAttach('Evento', 'NombreDeTuFuncion'). Usa nombres de función únicos (por ejemplo, con el nombre del script delante), porque todos los scripts comparten el mismo espacio.

-- Data\Script\Scripts\Bienvenida.lua
BridgeFunctionAttach('OnCharacterEntry', 'Bienvenida_Entrar')

function Bienvenida_Entrar(aIndex)
    NoticeSend(aIndex, 1, "Hola " .. GetObjectName(aIndex) .. ", bienvenido!")
end

aIndex es el número del jugador (o del monstruo) en el servidor. Casi todas las funciones lo reciben primero.

Respuestas: algunos eventos esperan una respuesta:

• Veto (OnCheckUserTarget, OnCheckUserKiller, OnUserItemPick, OnUserItemDrop, OnUserItemMove): devolver 0 bloquea la acción; 1 o nada la deja pasar.
• Tomar (OnCommandManager, OnNpcTalk, OnMonsterDieGiveItem): devolver 1 significa "me encargué yo" y el juego no hace lo suyo; 0 o nada, sigue lo normal.
• Valor (OnUserDamage, OnMonsterDamage, OnUserItemUse, OnUserLevelUp, OnUserMasterLevelUp): ver cada evento.

#Eventos del servidor

effect en los golpes: 1 ignora defensa, 2 excelente, 3 crítico, 4 reflejo; se suman 64 doble, 256 triple y 128 combo.

#Funciones del servidor

En las tablas, aIndex es el jugador o el monstruo. Las funciones que cambian algo de un jugador solo actúan si está en el juego. Cuando un argumento es opcional, va el valor por defecto entre paréntesis.

La lista completa de nombres (servidor y cliente), sacada del código, está en 17_LUA_LISTA.md.

#Servidor y ayudas

#Personaje: GetObject… y SetObject…

Para cada campo de esta lista existe GetObject<Campo>(aIndex) y, si no tiene asterisco, SetObject<Campo>(aIndex, valor). Por ejemplo GetObjectStrength(aIndex) y SetObjectStrength(aIndex, 1000).

Importante: los SetObject… solo cambian el valor en el servidor. Para que el jugador lo vea, después llama a la función de envío que corresponda (LevelUpSend, UserInfoSend, UserCalcAttribute, LifeSend, MoneySend, PKLevelSend...).

Otras funciones del personaje:

#Monedas

Las monedas se guardan en la base con el procedimiento WZ_SetCoin (necesita Update31).

#Enviar al cliente

#Sesión

#Inventario e ítems

#Monstruos

#Mapas e invasiones

#Buffs

#Party y guild

#Mensajes y comandos

Comandos propios: agrega una fila en Data\Command.txt (por ejemplo con el índice 100, que está libre) con su precio, requisitos y nivel de GM, y en tu script maneja ese code (índice + 1 = 101) en OnCommandManager, devolviendo 1.

#Configuración en archivos .ini

#Temporizadores y horarios (Utils\Cron.lua y Utils\Schedule.lua)

Un temporizador cuya función falla se cancela y se avisa en el log. Al recargar los scripts, los temporizadores se pierden (se vuelven a crear en OnReadScript).

#Base de datos

Las consultas van por el DataServer, en segundo plano: el juego no se frena esperando a la base. La respuesta llega un momento después a la función que le pases.

DBQuery("SELECT TOP 10 Name, cLevel FROM Character WHERE AccountID = ?", { GetObjectAccount(aIndex) },
    function(ok, resultado)
        if not ok then LogColor(1, resultado) return end
        for _, fila in ipairs(resultado.rows) do
            NoticeSend(aIndex, 1, fila.Name .. " nivel " .. fila.cLevel)
        end
    end)

• Los ? se cambian por los valores de la lista, con las comillas puestas por el servidor: un nombre que escribió un jugador nunca puede meter SQL propio. No armes el SQL pegando textos.
• El resultado: resultado.rows[i].Columna (número o texto; nil si es NULL), resultado.count, resultado.columns, resultado.affected (filas cambiadas), resultado.truncated (había más de 100 filas o no entraban en la respuesta).
• Qué se permite: leer (SELECT) cualquier tabla; escribir (INSERT, UPDATE, DELETE, MERGE) solo en tablas cuyo nombre empieza con Lua_. Nunca: varias sentencias, comentarios, EXEC, DROP, ALTER, CREATE, SELECT ... INTO y similares.
• Escribir en las tablas del juego: solo si el dueño lo permite en DataServer\Data\DataServer.ini, sección [DataServerInfo], LuaDatabaseWrite = 1 (y se reinicia el DataServer). Úsalo con cuidado.
• Tus tablas: créalas con un script SQL propio (Update32 en adelante, ver 02_INSTALACION_SERVIDOR.md) con nombres Lua_....

Datos guardados sin SQL (necesita DataBase\SQL\Update32 - Lua scripts data.sql, tabla Lua_Data):

ámbito es un nombre corto (por ejemplo "global", "account", "character"); dueño es la cuenta, el personaje, o "" para algo global.

Forma de otros servidores (sigue funcionando): CreateAsyncQuery(nombre, sql, aIndex, 1) y, en el evento OnSQLAsyncResult(nombre, id, aIndex), QueryAsyncGetValue(nombre, columna [, fila]), QueryAsyncGetRowCount(nombre), QueryAsyncGetTable(nombre) y QueryAsyncDelete(nombre). ConnectQueryAsync() siempre devuelve 1 (la conexión es la del DataServer). Valen las mismas reglas de seguridad, pero aquí el SQL va armado a mano: no pegues textos de los jugadores.

No existen SQLQuery, SQLFetch y las demás funciones SQL que esperan la respuesta en el momento: frenarían el GameServer. Si un script las usa, el log avisa una vez que se cambie a DBQuery. Para que esos scripts no se caigan, SQLConnect, SQLDisconnect, SQLFetch, SQLGetNumber, SQLGetString, SQLGetResult, SQLGetSingle y SQLClose existen pero no hacen nada (devuelven 1, 0, 100 o ""). ExecuteQuery(sql) sí manda la consulta, por DBQuery, sin esperar la respuesta.

#Paquetes Lua entre el servidor y el cliente

Un script del servidor y uno del cliente pueden mandarse datos propios.

Hasta 4000 bytes por paquete. El servidor acepta hasta 30 paquetes Lua por segundo de cada jugador (los demás se descartan). Lo que llega del cliente puede venir modificado: comprueba siempre los valores en el servidor antes de dar algo.

#Lua en el cliente (PC, Android y navegador)

El cliente también corre scripts Lua: sirven para ventanas propias, botones, avisos en pantalla y para hablar con los scripts del servidor. Es el mismo código en PC, Android y el navegador.

#Dónde están

Se activan igual que en el servidor: require('Scripts\\MiVentana') o requirefolder('Scripts\\MisVentanas') en ScriptMain.lua. Los scripts se cargan la primera vez que aparece la pantalla de login. Para recargarlos, un script llama a ReloadClientScripts() (por ejemplo desde una tecla). Para que los jugadores los tengan, hay que repartirlos con el cliente: en PC con el resto de los archivos, en el navegador volviendo a correr WebPacker, y en Android en los datos del celular (parche o data.zip).

Los scripts del cliente son archivos de texto que el jugador puede ver y cambiar: nunca confíes en lo que manda un script del cliente; el servidor debe comprobarlo todo.

#Seguridad y límites del cliente

• Mismo encierro que en el servidor: sin archivos, sin programas, sin librerías, sin internet, sin tocar la memoria del juego.
• Cada evento puede tardar como máximo 50 milisegundos (2 segundos al cargar). Si un evento se pasa 3 veces, se apaga hasta la próxima recarga y el juego sigue.
• Memoria: hasta 64 MB.
• Los errores van al MuError.log del cliente como [Lua] ..., cada error una sola vez.
• Los eventos que nadie usa no cuestan nada: el cliente solo llama a los enganchados.

#Eventos del cliente

Los eventos de cada cuadro corren en la pantalla de login (2), de personajes (4) y en el juego (5).

#Coordenadas

Los scripts dibujan en las mismas unidades que las ventanas del juego: una pantalla virtual de al menos 640 × 480 que el juego escala a cualquier resolución y al celular. El tamaño real es GetWindowWidth() × GetWindowHeight() (por ejemplo 1092.8 × 614.4 en 1366 × 768). X va de izquierda a derecha y Y de arriba abajo. El ratón usa las mismas unidades. En el celular un toque llega como clic izquierdo y no hay teclado.

#Funciones del cliente

#Una ventana en pocas líneas

Utils\Window.lua arma ventanas que se pueden arrastrar, con título, botón de cerrar, botones y líneas de texto: Window.New{ Title, X, Y, Width, Height, Key, Lines, OnDraw } crea una, y luego win:AddButton{ Text, X, Y, Width, OnClick }, win:SetLine(n, texto [, r, g, b]), win:Show(), win:Hide(), win:Toggle() y win:IsVisible(). Mira Scripts\Example.lua: una ventana que se abre con la tecla J, muestra el nombre y el nivel del personaje, y con un botón manda el paquete "IGKPing" al servidor y muestra la respuesta "IGKPong" (el script del servidor es Scripts\Examples\PingPong.lua).

BridgeFunctionAttach('MainInterfaceProcThread', 'MiAviso_Dibujar')

function MiAviso_Dibujar()
    if GetMainScene() ~= 5 then return end
    DrawBar(10, 60, 160, 20, 0, 0, 0, 160)
    SetTextColor(255, 210, 0, 255)
    RenderText(10, 64, "Evento a las 20:00", 160, 1)
end

#Ejemplos incluidos

En Data\Script\Scripts\Examples\, apagados. Para usar uno: require('Scripts\\Examples\\Nombre') en ScriptMain.lua.

#Scripts de otros servidores

IGK usa los mismos nombres de eventos y funciones que la API Lua más usada en MU, así que muchos scripts funcionan con pocos cambios. Diferencias a revisar:

• SQLQuery / SQLFetch (síncronas) no existen: usar DBQuery o CreateAsyncQuery.
• Escribir en tablas del juego necesita LuaDatabaseWrite = 1.
• MoveUser acepta (aIndex, puerta) y también (aIndex, map, x, y); ItemGive acepta (aIndex, especial) y (aIndex, ítem, nivel, ...).
• No hay funciones para leer archivos, internet ni el ID del hardware: son bloqueos de seguridad a propósito.

#Preguntas frecuentes

P: Agregué un script y no hace nada. R: Revisa que esté en ScriptMain.lua con require('Scripts\\Nombre'), que el nombre del archivo coincida y que el evento esté bien escrito en BridgeFunctionAttach. Después /reload lua y mira la consola del GameServer: un error de Lua sale en rojo con el archivo y la línea.

P: ¿Cómo veo los errores de mis scripts? R: En la consola del GameServer y en su log (GameServer\LOGS\LOG\), en rojo con [Lua], el archivo y la línea. También puedes escribir tus propios mensajes con LogPrint o LogColor.

P: Después de mi script nadie puede usar comandos (o los NPC no hablan). R: En IGK eso ya no pasa por olvidar return 0, pero sí si tu función devuelve 1 siempre. Devuelve 1 solo cuando tu script se encargó de ese comando o NPC.

P: Mi script se cortó con "the script ran for more than 3000 ms". R: Algo en tu script tarda demasiado (un bucle que no termina o muy grande). Para tareas largas usa temporizadores (Timer.Interval) o hazlas por partes.

P: ¿Se pierden los datos de mi script al reiniciar? R: Lo que esté en variables de Lua sí. Guarda lo importante con DataSet (tabla Lua_Data) o en una tabla Lua_... tuya con DBQuery, o en un .ini con ConfigSaveString.

P: DataGet o DBQuery no responden. R: Revisa que el DataServer esté conectado, que ejecutaste Update32 - Lua scripts data.sql y mira el log del DataServer: una consulta rechazada aparece como [LuaQuery] Refused con el motivo.

P: Mi consulta dice "scripts may only change tables named Lua_...". R: Por seguridad, los scripts solo escriben en tablas Lua_.... Crea tu tabla con ese prefijo, o permite escribir en las del juego con LuaDatabaseWrite = 1 en el DataServer.ini (bajo tu responsabilidad).

P: ¿Cómo hago un comando nuevo, por ejemplo /premio? R: Agrega una fila en Data\Command.txt con un índice libre (el 100), el texto "/premio", sus precios y su nivel de GM. En tu script, en OnCommandManager, si code == 101 haz lo que quieras y devuelve 1.

P: ¿Puedo quitar el PvP de un mapa sin tocar el juego? R: Sí: con OnCheckUserTarget devolviendo 0 en ese mapa. Mira el ejemplo PvPRules.lua.

P: ¿Puedo cambiar lo que tira un monstruo? R: Sí: en OnMonsterDieGiveItem haz tu drop con ItemDropEx o MoneyDrop y devuelve 1; el drop normal no sale.

P: ¿Un script puede leer archivos o conectarse a internet? R: No. Los scripts están encerrados por seguridad: solo leen y escriben archivos .ini dentro de Data\Script.

P: ¿Los scripts funcionan en el GameServerCS (Castle Siege)? R: Sí, el GameServerCS usa la misma carpeta Data\Script. Si quieres que un script haga algo solo en uno de los dos, compara GetGameServerCode().

P: Hice una ventana en el cliente y los jugadores no la ven. R: Los scripts del cliente van con el cliente: copia Data\IGK\Scripts en el cliente que repartes (PC), vuelve a correr WebPacker para el navegador y manda un parche de datos para Android. Revisa también que el script esté activado en Data\IGK\Scripts\ScriptMain.lua.

P: ¿Dónde veo los errores de los scripts del cliente? R: En el MuError.log de la carpeta Log del juego (en Android, en la de la carpeta de datos), con [Lua], el archivo y la línea. Va cifrado: arrástralo sobre Encoder.exe y lee el MuError.txt que sale al lado.

P: Mi ventana del cliente funciona en PC pero en el celular el personaje camina cuando la toco. R: En el celular, el joystick y los botones táctiles no pasan por los clics del ratón. Pon tu ventana lejos del joystick y de los botones de skills, o usa IsMobile() para ubicarla en otro lugar en el celular.