Lua para FiveM: o básico, erros comuns e a skill de IA

326 instalações no skills.sh

Baixar SKILL.md Comunidade

Não quer gerenciar as skills por conta própria? Obtenha o app completo.

Lua para FiveM é uma linguagem pequena com algumas arestas afiadas, e a maioria dos recursos quebrados tropeça nessas arestas, não na API do FiveM. Arrays começam em 1, nil e false são coisas diferentes, não existe continue nem operador ternário. Se você escreve ou revisa recursos em Lua, ou deixa um assistente de IA escrevê-los, precisa dessas regras na sua frente. A skill de Lua básico empacota tudo em arquivos de regras que o assistente lê antes de escrever código.

O que a skill de Lua básico te dá

O SKILL.md é um índice. Cada tema tem o seu próprio arquivo de regras com explicações e exemplos.

  • rules/functions.md. Tamanho de funções, nomes, parâmetros, exports e guard clauses. Funções curtas que retornam cedo em vez de aninhar.
  • rules/tables.md. Índices de array começam em 1, desreferenciação, evitar table.insert em caminhos quentes, iteração com ipairs e pairs, e tamanho de array com #.
  • rules/variables.md. Nomes para constantes, locais em vez de globais, e quando um enum se lê melhor que um booleano.
  • rules/conditionals.md. Valores padrão com or, expressões booleanas e legibilidade.
  • rules/errors.md. Asserções, pré-condições, erros como valores e falhar em voz alta em vez de engolir problemas.
  • rules/reference-links.md. Documentação oficial de Lua e FiveM, incluindo docs.fivem.net.

Erros comuns com Lua para FiveM

  • Globais acidentais. Um local faltando transforma a variável em uma global compartilhada por todos os arquivos do recurso. Sintoma: valores vazando entre scripts, um contador de um arquivo mudando em outro, e acesso mais lento que com locais. Correção: declare tudo com local e trate uma atribuição sem local como bug.
  • Indexar a partir de 0. players[0] é nil e um loop for i = 0, #players começa em um slot vazio. Sintoma: a primeira entrada é pulada ou o código falha na iteração zero. Correção: comece em 1 e itere com ipairs.
  • Usar # na tabela errada. #t só está definido para uma sequência sem buracos. Ele ignora chaves de texto e, com buracos, o resultado é imprevisível. Correção: mantenha um contador separado ou itere com pairs quando as chaves não forem 1..n.
  • Confundir false com nil. if x then falha tanto com nil quanto com false. Se false é um valor válido, um padrão como x = x or true sobrescreve em silêncio. Correção: escreva if x ~= nil then quando false importa, e cuidado com a and b or c quando b pode ser false.
  • Tratar Lua como JavaScript. Não existe != (use ~=), não existe continue (use goto continue ou reestruture), não existe ternário. Montar strings grandes com .. dentro de loops cria uma string nova a cada passo. Correção: use table.concat para saídas grandes e escreva condicionais do jeito Lua.

Por que assistentes de IA erram em Lua para FiveM

Um assistente genérico escreve Lua com a memória muscular de JavaScript e Python. Ele esquece local, começa loops em 0, usa !=, inventa um continue e recorre a a and b or c como ternário sem perceber o caso de false. Também chama table.insert dentro de loops quentes do servidor porque é o que todo tutorial faz. O código costuma rodar e falhar depois, em silêncio, sob carga.

A skill de Lua básico entrega ao assistente os cinco arquivos de regras e manda ler o que combina com a tarefa. Funções ganham guard clauses e corpos curtos, tabelas usam loops a partir de 1 com ipairs, variáveis são locais por padrão e erros aparecem por meio de asserções e pré-condições em vez de serem ignorados. O resultado se lê como Lua escrito por alguém que trabalha com FiveM todo dia, e isso torna a revisão muito mais fácil.

Instale a skill de Lua básico em 30 segundos

  1. Clique em “Download SKILL.md” no topo desta página.
  2. Descompacte na pasta de skills ou rules da sua ferramenta de IA. A seção de instalação abaixo mostra o caminho exato para Claude Code, Cursor e VS Code.
  3. Peça ao assistente algo concreto, como “escreva uma função que retorne os jogadores a menos de 10 metros de uma coordenada”, e confira que toda variável é local, que o loop usa ipairs e que a função retorna cedo com entrada inválida.

Como instalar esta skill

Baixe o zip, descompacte e coloque a pasta onde a sua ferramenta carrega skills ou regras. O caminho exato depende da ferramenta:

Claude Code

Descompacte em .claude/skills/lua-basics/ dentro do projeto (a pasta precisa conter SKILL.md). Para todos os projetos, use ~/.claude/skills/lua-basics/.

Documentação de skills do Claude Code

Cursor

O Cursor carrega as regras do projeto de .cursor/rules/. Adicione ali um arquivo de regra apontando para a skill descompactada, ou cole o conteúdo do SKILL.md e dos arquivos de regras em uma regra. O formato é .mdc com frontmatter e muda entre versões, então confira a documentação da sua versão.

Documentação de regras do Cursor

VS Code / Copilot

O Copilot lê arquivos de instruções em .github/instructions/*.instructions.md. Copie o SKILL.md para lá com um glob applyTo para os seus arquivos Lua e mantenha os arquivos de regras ao lado.

Documentação de instruções do VS Code

O arquivo SKILL.md

Este é o arquivo que o seu assistente de IA lê. Ele aponta para os arquivos de regras incluídos no download.

Conteúdo da skill (inclui SKILL.md e quaisquer outros arquivos)

O conteúdo da skill está em inglês: é documentação técnica feita para agentes de IA.

Lua Basics

Idiomatic, performant Lua patterns for FiveM: functions, tables, variables, conditionals and errors.

Activation Contract

Load this skill when writing or reviewing any Lua in a FiveM resource, or when the user asks about Lua naming, structure, performance, tables or error handling.

Hard Rules

  • Naming: ALL_CAPS constants, camelCase locals, PascalCase globals, _ for unused variables.
  • Prefer local; declare locals as close to first use as possible; group file-level globals at the top of a single client/server file.
  • Do not use table.insert; append with t[#t + 1] = v or maintain your own size counter.
  • Iterate arrays with numeric for i = 1, #t; imply array indices ({ a, b }) instead of writing them out.
  • Extract repeated table dereferences into locals; use t.key for constant keys and t[var] for dynamic keys.
  • Use guard clauses and early returns; never write if x then return true else return false end.
  • Prefer positive boolean expressions; set defaults with value = value or default.
  • Use assert for pre-conditions instead of if not x then error() end; fail loudly on unexpected state; return errors as values for expected failures.
  • Limit parameters; avoid boolean parameters in APIs (use enums); pass named local functions instead of inline ones.
  • Keep functions small, single-level of abstraction, and document exports.

Decision Gates

Situation Pattern
Expected failure (not found, invalid input) return nil, err or false
Programmer error / impossible state assert / error
Flag with more than two meanings enum table, not boolean
Function reused more than once as argument local function then pass by name
Append to array t[#t + 1] = v

Execution Steps

  1. Apply naming and scope rules to every identifier.
  2. Replace nested if with guard clauses.
  3. Replace table.insert and pairs on arrays with index writes and numeric loops.
  4. Add assert pre-conditions at function entry.
  5. Re-read for size: split any function mixing high- and low-level code.

Output Contract

Return Lua that follows the naming, locality, table and error-handling rules above; annotate any deliberate deviation.

References

  • rules/functions.md — size, naming, parameters, exports, guard clauses.
  • rules/tables.md — indices, dereferencing, table.insert, iteration, size.
  • rules/variables.md — naming, enums vs booleans, declaration location.
  • rules/conditionals.md — defaults, boolean expressions, readability.
  • rules/errors.md — assert, pre-conditions, errors as values, fail loudly.
  • rules/reference-links.md — official Lua and FiveM documentation.

Upstream docs: https://www.lua.org/manual/5.4/

Perguntas frequentes

Qual versão de Lua o FiveM usa?
As builds atuais do FXServer rodam Lua 5.4 com adições próprias do FiveM. Recursos antigos escritos para 5.3 em geral ainda funcionam, mas confira a divisão inteira e outras mudanças do 5.4 antes de copiar código velho.
Preciso saber Lua para usar IA no FiveM?
Você deveria ler bem o suficiente para revisar o que o assistente escreve. A IA consegue produzir um recurso que funciona, mas também produz globais acidentais e loops com índice errado. Se você não enxerga isso, não pode confiar no resultado.
Posso usar esta skill com o ChatGPT?
Sim, com um passo manual. O SKILL.md e a pasta rules são markdown puro, então você pode colá-los na conversa como contexto. O suporte nativo a skills é para Claude Code, Cursor e VS Code.

Guias relacionados

Leituras mais longas do blog da FiveAI sobre o mesmo tema.

Mais skills