Configuración de VS Code para FiveM: servidor de lenguaje Lua, nativos, sin advertencias falsas

Abres un script perfectamente correcto en VS Code y se ve así:

Undefined global `PlayerPedId`.

Cada nativo, exports, ESX y QBCore obtiene un subrayado amarillo, y los errores reales se ahogan en el ruido. Esta guía configura VS Code para que entienda Lua de FiveM, y solo te advierte sobre cosas que son realmente incorrectas.

#Instala un servidor de lenguaje Lua

En el panel de Extensiones, instala una extensión Lua language server. La ampliamente utilizada es la extensión "Lua" de sumneko, que se construye sobre Lua Language Server (LuaLS). Te proporciona completado, ir a definición, renombrar y diagnósticos.

Abre tu carpeta de recursos como el espacio de trabajo (no un archivo único), para que el servidor pueda ver cada script y la configuración que estás a punto de agregar.

#Agrega definiciones de nativos de FiveM

LuaLS simple no tiene idea de qué toma GetEntityCoords. La comunidad mantiene tipificaciones para FiveM / CfxLua: un conjunto de archivos de anotación que describen los nativos, los globales de Cfx.re y la sintaxis Lua extra que FiveM permite. Busca en el panel de Extensiones "CfxLua" o "FiveM natives", o busca un complemento "FiveM" en el administrador de complementos de LuaLS, y elige el que se mantiene activamente.

Con ellos instalados obtienes firmas cuando escribes:

local ped = PlayerPedId()
local coords = GetEntityCoords(ped)

Pasa el cursor sobre un nativo y los parámetros y tipos de retorno aparecen. La mayoría de las tipificaciones también incluyen anotaciones de exports, lib si agregas las definiciones de ox_lib, y la tabla cache.

Consejo: los nombres de extensión y la configuración cambian con el tiempo. Si una configuración a continuación no existe en tu versión, verifica el README propio de la extensión, que siempre es más actual que un tutorial.

#Configuración del espacio de trabajo

Crea .vscode/settings.json en la raíz de tu carpeta de recursos. Esto mantiene la configuración con el proyecto, así que todos los que lo abran obtienen el mismo comportamiento:

{
  "Lua.runtime.version": "Lua 5.4",
  "Lua.runtime.nonstandardSymbol": [
    "/**/", "`", "+=", "-=", "*=", "/=", "<<=", ">>=", "&=", "|=", "^="
  ],
  "Lua.diagnostics.globals": [
    "ESX", "QBCore", "Config", "Locales", "PlayerData",
    "lib", "cache", "exports"
  ],
  "Lua.workspace.checkThirdParty": false,
  "Lua.workspace.ignoreDir": [".vscode", "node_modules", "dist"]
}

Lo que hace cada parte:

• Lua.runtime.version coincide con lua54 'yes' en tu fxmanifest.lua.
• nonstandardSymbol le dice al analizador que la asignación compuesta de FiveM (x += 1) y los hashes de acento grave son válidos. Sin ella, el código perfectamente bueno se señala como un error de sintaxis.
• Lua.diagnostics.globals enumera nombres que el script define en algún lugar que el servidor no puede rastrear. Agrega los tuyos: ESX, QBCore, una tabla Config de config.lua. Si una extensión de tipificaciones ya declara lib y exports, puedes soltarlos de la lista.

Solo agrega globales reales. Si silencias todo, pierdes la advertencia que detecta una variable mal escrita, que es una de las mejores cosas que hace el editor.

#Arregla las advertencias que son reales

Algunas advertencias son el editor haciendo su trabajo:

local players = ESX.GetPlayers()
for i = 1, #player do   -- 'player' is not defined: should be 'players'
end

Convierte Lua.diagnostics.globals en una lista corta y deliberada y cada Undefined global restante es un error tipográfico o una local faltante. Esa también es la forma más rápida de encontrar globales accidentales, que la guía de resmon enumera como fuente de rendimiento y errores.

Para casos puntuales, un comentario en línea es mejor que una configuración global:

---@diagnostic disable-next-line: undefined-global
local x = SomeOtherResourceGlobal

#Anota tu propio código

LuaLS lee comentarios ---@. Algunas líneas hacen que tus propias funciones sean autodocumentadas y den a los llamadores completado automático:

---@param plate string
---@param coords vector3
---@return boolean
local function isPlateNear(plate, coords)
    -- ...
end

Si construyes una biblioteca que otros scripts llaman a través de exports, poner estas anotaciones en las funciones exportadas da la mejor rentabilidad.

#Formatea al guardar

Instala StyLua (la extensión para el formateador StyLua) o usa el formateador propio del servidor de lenguaje. Para StyLua, agrega un stylua.toml junto a tus recursos:

column_width = 120
indent_type = "Spaces"
indent_width = 4
quote_style = "AutoPreferSingle"

Luego en la configuración de VS Code:

{
  "[lua]": {
    "editor.defaultFormatter": "JohnnyMorganz.stylua",
    "editor.formatOnSave": true
  }
}

Verifica el ID del formateador en el panel de Extensiones si no se dispara. StyLua puede no gustar la sintaxis solo de FiveM como hashes de acento grave, así que ejecuta en una copia primero si tus scripts las usan mucho.

#Busca los nativos

El editor te dice la firma; la referencia oficial de nativos te dice qué hace realmente el nativo, con notas de otros desarrolladores. Las páginas de nativos están en docs.fivem.net/natives, y el cuadro de búsqueda encuentra un nativo por nombre o descripción. Dos hábitos ayudan:

• Busca por lo que quieres, no el nombre exacto: "get closest vehicle", "ped bone".
• Lee primero el nativo Cfx.re, luego el texto de referencia de GTA V, ya que algunos nativos se comportan diferente en la compilación de FiveM.

Para detalles cliente/servidor, ver eventos del cliente y el servidor y Wait y hilos.

#Lista de verificación