Introdução ao Scripting Lua para FiveM

Os recursos do FiveM podem usar o CfxLua, um runtime Lua 5.4 modificado, para scripts de cliente e servidor. Um recurso atual começa com fxmanifest.lua, lista os arquivos que cada contexto carrega e mantém as decisões finais, como permissões, dinheiro e inventário no servidor.

A configuração e os exemplos de código aqui são voltados ao FiveM para GTA V Legacy. O Enhanced tem regras diferentes de runtime e de compatibilidade; verifique as alterações de Legacy para Enhanced do Cfx.re antes de aplicá-las a um servidor Enhanced.

O antigo __resource.lua manifesto e o lua54 'yes' switch estão obsoletos para novos trabalhos. A Cfx.re afirma que o suporte a Lua 5.3 terminou em junho de 2025 e os scripts atuais usam Lua 5.4.

Crie um recurso mínimo

Dentro do seu diretório de recursos resources server-data, crie [local]/hello_fivem. Os colchetes agrupam recursos; o recurso em si é o hello_fivem diretório.

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)

O manifesto e o comportamento do tempo de execução são documentados no e a referência do manifesto de recursos e guia CfxLua.

Entenda os contextos do cliente e do servidor

Um script de cliente é executado separadamente para cada jogador conectado e pode chamar nativos voltados para o jogo, como PlayerPedId e GetEntityCoords. Um script de servidor coordena o estado compartilhado, a persistência e a autorização. Valores fornecidos por um cliente são entradas, não prova.

Use AddEventHandler para eventos que devem permanecer em um contexto. Use RegisterNetEvent apenas quando um evento precisar cruzar a fronteira cliente/servidor. O guia oficial Secure Your Events explica por que cada ação de rede deve validar a permissão e o estado atuais do jogador no lado do servidor.

Evite bloquear o agendador

Scripts CfxLua são agendados cooperativamente. Um loop que nunca cede pode congelar seu contexto de script. Quando um loop precisa esperar, use Wait com um atraso apropriado para a tarefa, e não consulte um banco de dados ou endpoint HTTP a cada frame. Prefira eventos e mudanças de estado em vez de polling permanente.

Use exports para um limite claro de recursos

Um export expõe uma função nomeada para outro recurso. Defina-a explicitamente e documente seus argumentos e valor de retorno:

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

Outro recurso Lua pode chamá-lo como exports.hello_fivem:formatPlayerLabel(id, name). Não use um export para contornar verificações de permissão ou propriedade.

Execute e teste o recurso

1. Faça backup do recurso que você está substituindo, se houver.
2. No console do servidor, execute refresh e então ensure hello_fivem.
3. Verifique o console do servidor para a mensagem de início.
4. Conecte-se ao servidor de desenvolvimento, abra o F8 e execute mycoords.
5. Adicione ensure hello_fivem ao server.cfg após quaisquer dependências e, em seguida, reinicie o servidor para confirmar a inicialização normal.

Os comandos de recurso suportados estão listados na referência de comandos de servidor. Continue com o tutorial do primeiro script Lua antes de adicionar dependências de framework ou banco de dados.