Lua para FiveM: lo básico, errores comunes y la skill de IA

¿No quieres gestionar las skills tú mismo? Consigue la app completa.

Lua para FiveM es un lenguaje pequeño con unas pocas aristas afiladas, y la mayoría de los recursos rotos tropiezan con esas aristas y no con la API de FiveM. Los arrays empiezan en 1, nil y false son cosas distintas, no hay continue ni operador ternario. Si escribes o revisas recursos en Lua, o dejas que un asistente de IA los escriba por ti, necesitas estas reglas delante. La skill de Lua básico las empaqueta en archivos de reglas que el asistente lee antes de escribir código.

Qué te da la skill de Lua básico

El SKILL.md es un índice. Cada tema tiene su propio archivo de reglas con explicaciones y ejemplos.

rules/functions.md. Tamaño de funciones, nombres, parámetros, exports y guard clauses. Funciones cortas que retornan pronto en vez de anidar.
rules/tables.md. Los índices de array empiezan en 1, desreferenciar, evitar table.insert en rutas calientes, iterar con ipairs y pairs, y el tamaño de array con #.
rules/variables.md. Nombres para constantes, locales antes que globales, y cuándo un enum se lee mejor que un booleano.
rules/conditionals.md. Valores por defecto con or, expresiones booleanas y legibilidad.
rules/errors.md. Aserciones, precondiciones, errores como valores y fallar ruidosamente en vez de tragarse los problemas.
rules/reference-links.md. Documentación oficial de Lua y FiveM, incluida docs.fivem.net.

Errores comunes con Lua para FiveM

Globales accidentales. Un local que falta convierte la variable en una global compartida por todos los archivos del recurso. Síntoma: valores que se filtran entre scripts, un contador de un archivo que cambia en otro, y accesos más lentos que con locales. Solución: declara todo con local y trata una asignación sin local como un bug.
Indexar desde 0. players[0] es nil y un bucle for i = 0, #players arranca en un hueco vacío. Síntoma: se salta la primera entrada o el código falla en la iteración cero. Solución: empieza en 1 e itera con ipairs.
Usar # en la tabla equivocada. #t solo está definido para una secuencia sin huecos. Ignora las claves de texto y con huecos el resultado es impredecible. Solución: lleva un contador aparte o itera con pairs cuando las claves no son 1..n.
Confundir false con nil. if x then falla tanto con nil como con false. Si false es un valor válido, un valor por defecto como x = x or true lo pisa en silencio. Solución: escribe if x ~= nil then cuando false importa, y cuidado con a and b or c cuando b puede ser false.
Tratar Lua como JavaScript. No hay != (usa ~=), no hay continue (usa goto continue o reestructura), no hay ternario. Construir cadenas grandes con .. dentro de bucles crea una cadena nueva en cada paso. Solución: usa table.concat para salidas grandes y escribe los condicionales a la manera de Lua.

Por qué los asistentes de IA fallan con Lua para FiveM

Un asistente genérico escribe Lua con la memoria muscular de JavaScript y Python. Omite local, arranca bucles en 0, usa !=, se inventa un continue y recurre a a and b or c como ternario sin ver el caso de false. También llama a table.insert dentro de bucles calientes del servidor porque eso hace cada tutorial. El código suele correr y fallar más tarde, en silencio, bajo carga.

La skill de Lua básico le da al asistente los cinco archivos de reglas y le indica que lea el que encaja con la tarea. Las funciones llevan guard clauses y cuerpos cortos, las tablas usan bucles desde 1 con ipairs, las variables son locales por defecto y los errores salen a la luz con aserciones y precondiciones en vez de ignorarse. El resultado se lee como Lua escrito por alguien que trabaja en FiveM a diario, y eso hace que revisarlo sea mucho más fácil.

Instala la skill de Lua básico en 30 segundos

Haz clic en “Download SKILL.md” en la parte superior de esta página.
Descomprímelo en la carpeta de skills o rules de tu herramienta de IA. La sección de instalación de abajo muestra la ruta exacta para Claude Code, Cursor y VS Code.
Pídele al asistente algo concreto, como “escribe una función que devuelva los jugadores a menos de 10 metros de una coordenada”, y comprueba que cada variable es local, que el bucle usa ipairs y que la función retorna pronto con entradas inválidas.

Cómo instalar esta skill

Descarga el zip, descomprímelo y coloca la carpeta donde tu herramienta carga skills o reglas. La ruta exacta depende de la herramienta:

Claude Code

Descomprime en .claude/skills/lua-basics/ dentro del proyecto (la carpeta debe contener SKILL.md). Para todos los proyectos, usa ~/.claude/skills/lua-basics/.

Documentación de skills de Claude Code

Cursor

Cursor carga las reglas del proyecto desde .cursor/rules/. Añade ahí un archivo de regla que apunte a la skill descomprimida, o pega el contenido de SKILL.md y los archivos de reglas en una regla. El formato es .mdc con frontmatter y cambia entre versiones, así que revisa la documentación de tu versión.

Documentación de reglas de Cursor

VS Code / Copilot

Copilot lee archivos de instrucciones desde .github/instructions/*.instructions.md. Copia SKILL.md ahí con un glob applyTo para tus archivos Lua y deja los archivos de reglas al lado.

Documentación de instrucciones de VS Code

El archivo SKILL.md

Este es el archivo que lee tu asistente de IA. Enlaza a los archivos de reglas incluidos en la descarga.

Contenido de la skill (incluye SKILL.md y cualquier otro archivo)

El contenido de la skill está en inglés: es documentación técnica pensada 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

Apply naming and scope rules to every identifier.
Replace nested if with guard clauses.
Replace table.insert and pairs on arrays with index writes and numeric loops.
Add assert pre-conditions at function entry.
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/

Preguntas frecuentes

¿Qué versión de Lua usa FiveM?

Las builds actuales de FXServer corren Lua 5.4 con añadidos propios de FiveM. Los recursos antiguos escritos para 5.3 suelen seguir funcionando, pero revisa la división entera y otros cambios de 5.4 antes de copiar código viejo.

¿Necesito saber Lua para usar IA en FiveM?

Deberías leerlo lo bastante bien como para revisar lo que escribe el asistente. La IA puede producir un recurso que funciona, pero también produce globales accidentales y bucles con índice desfasado. Si no los detectas, no puedes confiar en el resultado.

¿Puedo usar esta skill con ChatGPT?

Sí, con un paso manual. El SKILL.md y su carpeta rules son markdown plano, así que puedes pegarlos en la conversación como contexto. El soporte nativo de skills es para Claude Code, Cursor y VS Code.

Lecturas más largas del blog de FiveAI sobre el mismo tema.