Scripting em Lua: Primeiros Passos

Lua: A Linguagem que Move o FiveM

Toda a lógica de gameplay personalizada nos servidores FiveM é escrita em Lua — uma linguagem de script leve, rápida e especialmente popular em jogos. Também é usada no Roblox, World of Warcraft addons e diversos game engines.

Se você quer criar scripts únicos, corrigir bugs, ou personalizar sistemas, Lua é a habilidade mais valiosa que você pode desenvolver como dono ou dev de servidor.

Configurando o Ambiente de Desenvolvimento

Ferramentas Necessárias

Visual Studio Code — Editor de código gratuito e poderoso
Extensão Lua (sumneko) — Autocomplete, linting e IntelliSense para Lua
Extensão FiveM Natives — Autocomplete específico para funções nativas do FiveM
Servidor FiveM local — Para testar seus scripts sem afetar o servidor de produção

Documentação Essencial

Mantenha estas páginas sempre abertas durante o desenvolvimento:

docs.fivem.net — Documentação oficial com todas as native functions
Lua 5.3 Reference — Manual oficial da linguagem Lua

Anatomia de um Resource FiveM

Todo resource (script) FiveM tem esta estrutura mínima de pastas:

meu-resource/
├── fxmanifest.lua     (manifesto obrigatório)
├── client/
│   └── main.lua       (código do lado do cliente)
└── server/
    └── main.lua       (código do lado do servidor)

O Manifesto (fxmanifest.lua)

O arquivo fxmanifest.lua é obrigatório e informa ao FiveM quais arquivos carregar. Ele define a versão do framework (atualmente adamant), o jogo alvo (gta5) e lista os scripts client e server.

Conceitos Fundamentais

Variáveis e Tipos

Lua é uma linguagem dinamicamente tipada — você não precisa declarar o tipo da variável:

local nome = "Carlos" — string
local idade = 25 — number
local ativo = true — boolean
local inventario = {} — table (array/objeto)

Funções

Funções em Lua são declaradas com a palavra-chave function. No FiveM, a maioria das suas funções serão callbacks de eventos ou threads:

Client vs. Server: Quando Usar Cada Um

Client-side	Server-side
Interface do usuário (HUDs, menus)	Banco de dados (MySQL/oxmysql)
Animações e efeitos visuais	Lógica de negócio (economia, itens)
Spawnar props/objetos locais	Validações de segurança
Eventos do jogador local	Events que afetam múltiplos jogadores

🔒 Regra de Ouro: Nunca confie no cliente. Toda lógica crítica — dinheiro, itens, status, permissões — deve sempre ser validada no servidor. O client pode ser manipulado por cheaters.

Seu Primeiro Script: Comando /hello

No arquivo client/main.lua, use a função RegisterCommand para criar um comando. Ela recebe três parâmetros:

Nome do comando (string) — ex: "hello"
Callback function — a lógica que executa quando o comando é digitado
Restricted (boolean) — se true, só admins podem usar

Dentro da callback, use GetPlayerName(PlayerId()) para obter o nome do jogador e TriggerEvent("chat:addMessage", ...) para exibir mensagens no chat do jogo.

Próximos Passos na Jornada Dev

Domine os exports do framework (ESX/QB-Core) — eles expõem funções prontas
Aprenda a usar oxmysql para interagir com o banco de dados
Estude NUI (Next User Interface) para criar HUDs com HTML/CSS/JS
Explore os state bags para sincronização de dados entre client/server
Participe de comunidades dev no Discord — a colaboração acelera o aprendizado

Qual script você gostaria de aprender a criar? Pede nos comentários! 💻