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 autorizadas, como permisos, dinero e inventario, en el servidor.

Crea un recurso mínimo

Dentro del directorio resources de server-data, crea [local]/hello_fivem. Los corchetes agrupan recursos; el directorio del recurso es 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 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. Reinicia el servidor para confirmar que el recurso está incluido en el orden de 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.