VSCode a punto para FiveM

Hasta ahora hemos hablado de recursos, fxmanifest y Lua. Pero escribir ese código en el Bloc de notas es sufrir: ni colores, ni autocompletado, ni avisos de errores. Un buen editor te ahorra horas y te enseña mientras escribes. En FiveM el estándar de facto es Visual Studio Code (VSCode): gratis, ligero, multiplataforma y con el mejor soporte de Lua que vas a encontrar. En este capítulo lo dejamos afinado para FiveM de principio a fin.

Instalar VSCode

Descárgalo de code.visualstudio.com, instálalo con las opciones por defecto y ábrelo. El truco clave para trabajar cómodo: abre la CARPETA de tu recurso (o la carpeta resources/ entera), no archivos sueltos. En VSCode se hace con «Archivo → Abrir carpeta». Al abrir una carpeta, el editor entiende el proyecto como un todo y las extensiones pueden analizar todos tus scripts juntos.

Las extensiones que importan

VSCode viene vacío a propósito; tú le añades superpoderes con extensiones desde la pestaña de Extensiones (Ctrl+Shift+X). Estas son las que de verdad mueven la aguja para FiveM:

• Lua (de sumneko / LuaLS): la más importante. Es el Language Server de Lua: autocompletado, diagnóstico de errores en tiempo real, ir a definición y documentación al pasar el ratón (hover). Sin ella vas a ciegas.
• Una extensión de natives de FiveM (busca «FiveM» o «cfx natives»): añade autocompletado y descripción de las natives de Citizen/Cfx (CreateThread, GetEntityCoords, TriggerEvent…), que son miles.
• vscode-fivem (o similar): resalta el fxmanifest.lua y aporta snippets y comodidades específicas de FiveM.
• GitLens: potencia el Git que ya trae VSCode (ver quién cambió cada línea, historial, comparar versiones). El control de versiones va integrado de serie.
• EditorConfig: respeta un estilo de indentación y fin de línea común para todo el equipo, sin discusiones.
• Prettier (opcional): formatea el JavaScript/HTML/CSS de tus interfaces NUI. Para Lua no hace falta; de eso ya se encarga LuaLS.

El .luarc.json: que deje de marcar errores falsos

Nada más instalar LuaLS te vas a encontrar con subrayados rojos por todas partes: «Undefined global Citizen», «Undefined global exports», «Undefined global ESX»… No es un error tuyo. LuaLS no sabe que estás en FiveM y desconoce las variables globales que el motor te inyecta. La solución es crear un archivo .luarc.json en la raíz del recurso para declararle esas globals y dónde están las librerías de tu framework.

{
  "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
  "runtime.version": "Lua 5.4",
  "diagnostics.globals": [
    "Citizen",
    "exports",
    "GetCurrentResourceName",
    "source",
    "vector2",
    "vector3",
    "vector4",
    "quat",
    "ESX",
    "QBCore",
    "TriggerEvent",
    "TriggerServerEvent",
    "TriggerClientEvent",
    "RegisterNetEvent",
    "AddEventHandler"
  ],
  "workspace.library": [
    "C:/FXServer/server-data/resources/[core]/es_extended"
  ],
  "workspace.checkThirdParty": false
}

• diagnostics.globals: lista de nombres que LuaLS debe tratar como globals válidas (las que inyecta FiveM y tu framework). Así dejan de salir avisos de «undefined».
• workspace.library: rutas a código externo que quieres que LuaLS lea para autocompletar. Apuntando a es_extended (ESX) o a qb-core (QBCore) tendrás sugerencias de sus funciones.
• runtime.version: FiveM usa Lua 5.4; decláralo para que el análisis cuadre.

Snippets: escribe menos, repite menos

Hay bloques que tecleas mil veces: registrar un evento, un comando, un hilo. Los snippets te dejan escribir un atajo (por ejemplo rnet) y que VSCode complete la plantilla entera con tabuladores para saltar entre los huecos. Para crear los tuyos: «Archivo → Preferencias → Configurar fragmentos de código», elige Lua y añade tu plantilla. Aquí tienes tres muy útiles:

-- rnet -> registrar y manejar un evento de red
RegisterNetEvent('mi_recurso:miEvento')
AddEventHandler('mi_recurso:miEvento', function(arg)
  -- tu lógica aquí
end)

-- rcmd -> registrar un comando de chat
RegisterCommand('micomando', function(source, args, raw)
  -- tu lógica aquí
end, false)

-- thread -> bucle en un hilo propio
CreateThread(function()
  while true do
    Wait(1000)
    -- tu lógica aquí
  end
end)

Git: versiona tu servidor desde el primer día

Versionar con Git no es solo «para equipos grandes». Es tu red de seguridad: si un cambio rompe el servidor, vuelves al estado anterior en segundos; si quieres probar algo arriesgado, lo haces en una rama; y guardas el historial de qué cambió y por qué. VSCode trae Git integrado (pestaña de control de código fuente). Lo único crítico es no subir nunca secretos ni basura. Para eso está el .gitignore en la raíz del repositorio:

# Secretos y configuración sensible — NUNCA al repositorio
secrets.cfg
.env
*.key

# Caché y datos generados por el servidor
cache/
logs/
*.log

# Dependencias de NUI (se reinstalan con npm install)
node_modules/

# Basura del sistema y del editor
.DS_Store
Thumbs.db

El flujo de trabajo del día a día

Con el editor a punto, tu ciclo de iteración es rápido y siempre el mismo: editas el código en VSCode, lo recargas en el servidor y lees la consola para ver qué pasó. No necesitas reiniciar todo el servidor por cada cambio: basta con reiniciar el recurso afectado.

• Editas y guardas el archivo en VSCode (Ctrl+S).
• En la consola del servidor (o txAdmin), ejecutas restart mi_recurso. Si has añadido archivos nuevos al manifiesto, haz antes ensure mi_recurso o refresh.
• Lees la consola: ahí salen tus print(), los errores de Lua y el stack trace si algo peta. La consola es tu mejor amiga.
• Repites. Cambio pequeño, recarga, observa. Así aíslas qué línea causa cada efecto.

Para depurar, los print() estratégicos siguen siendo la herramienta más honesta: imprime el valor de una variable justo antes de la línea sospechosa y comprueba si vale lo que crees. Un print('[DEBUG] dinero =', dinero) bien colocado resuelve la mayoría de los misterios.