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.

El antiguo __resource.lua manifiesto y el lua54 'yes' cambio están obsoletos para trabajos nuevos. Cfx.re afirma que el soporte de Lua 5.3 finalizó en junio de 2025 y los scripts actuales utilizan Lua 5.4.

Crea un recurso mínimo

Dentro de tu resources directorio server-data/resources, crea [local]/hello_fivem. Los corchetes agrupan recursos; el recurso en sí es el hello_fivem directorio.

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 en tiempo de ejecución se documentan en la guía oficial de referencia del manifiesto de recursos y 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.

Usa AddEventHandler para eventos que deben permanecer en un contexto. Usa RegisterNetEvent solo cuando un evento deba cruzar el límite cliente/servidor. La guía oficial Secure Your Events explica por qué cada acción en red debe validar el permiso y el estado actual del jugador en el lado del 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 compatibles se enumeran en la guía oficial referencia de comandos del servidor. Continúa con el tutorial oficial del primer script Lua antes de añadir dependencias de framework o base de datos.