Introducción a la programación en Lua para FiveM

Los recursos de FiveM pueden usar CfxLua, un tiempo de ejecución modificado de Lua 5.4, para scripts de cliente y servidor. Un recurso actual comienza con fxmanifest.lua, enumera los archivos que carga cada contexto y mantiene las decisiones de autoridad, como permisos, dinero e inventario, en el servidor.

Los ejemplos de configuración y código aquí están dirigidos a FiveM para GTA V Legacy. Enhanced tiene diferentes reglas de tiempo de ejecución y compatibilidad; consulta los cambios de Legacy a Enhanced de Cfx.re antes de aplicarlos a un servidor Enhanced.

Crea un recurso mínimo

Dentro del directorio resources de tu carpeta server-data, crea [local]/hello_fivem. Los corchetes agrupan recursos; el recurso propiamente dicho es el directorio hello_fivem.

fxmanifest.lua:

fx_version 'cerulean'
game 'gta5'

author 'Your name'
description 'Small CfxLua learning resource'
version '1.0.0'

client_script 'client.lua'
server_script 'server.lua'

client.lua:

RegisterCommand('mycoords', function()
    local coords = GetEntityCoords(PlayerPedId())
    print(('x=%.2f y=%.2f z=%.2f'):format(coords.x, coords.y, coords.z))
end, false)

server.lua:

AddEventHandler('onResourceStart', function(resourceName)
    if resourceName ~= GetCurrentResourceName() then
        return
    end

    print(('[%s] started'):format(resourceName))
end)

El manifiesto y el comportamiento del entorno de ejecución están documentados en la referencia oficial del manifiesto de recursos y la guía de CfxLua.

Comprender los contextos del cliente y del servidor

Un script de cliente se ejecuta por separado para cada jugador conectado y puede llamar a funciones nativas del juego como PlayerPedId y GetEntityCoords. Un script de servidor coordina el estado compartido, la persistencia y la autorización. Los valores proporcionados por un cliente son entradas, no pruebas.

Utiliza AddEventHandler para eventos que deban permanecer en un solo contexto. Utiliza RegisterNetEvent únicamente cuando un evento deba cruzar el límite entre cliente y servidor. La guía oficial Secure Your Events explica por qué toda acción de red debe validar los permisos y el estado actuales del jugador en el servidor.

Evita bloquear el planificador

Los scripts de CfxLua se programan de forma cooperativa. Un bucle que nunca cede puede congelar su contexto de script. Cuando un bucle deba esperar, usa Wait con un retraso apropiado para la tarea, y no consultes una base de datos o un punto final HTTP en cada fotograma. Prefiere los eventos y los cambios de estado en lugar del sondeo permanente.

Usa exportaciones para un límite de recursos claro

Una exportación expone una función con nombre a otro recurso. Defínela explícitamente y documenta sus argumentos y valor de retorno:

exports('formatPlayerLabel', function(serverId, playerName)
    return ('[%d] %s'):format(serverId, playerName)
end)

Otro recurso Lua puede llamarla como exports.hello_fivem:formatPlayerLabel(id, name). No uses una exportación para eludir las comprobaciones de permisos o propiedad.

Ejecuta y prueba el recurso

1. Haz una copia de seguridad del recurso que estás reemplazando, si lo hay.
2. En la consola del servidor, ejecuta refresh y luego ensure hello_fivem.
3. Comprueba la consola del servidor para ver el mensaje de inicio.
4. Conéctate al servidor de desarrollo, abre F8 y ejecuta mycoords.
5. Añade ensure hello_fivem a server.cfg después de cualquier dependencia, luego reinicia el servidor para confirmar el inicio normal.

Los comandos de recursos admitidos se enumeran en la referencia oficial de comandos del servidor. Continúa con el tutorial oficial del primer script Lua antes de añadir dependencias de frameworks o bases de datos.