Cómo añadir scripts y recursos en FiveM sin errores

Añadir resources en FiveM parece trivial hasta que el servidor no arranca, la consola muestra Couldn't load resource o un script nuevo tumba al framework completo. La mayor parte de los errores no viene del resource en sí — viene de una estructura de carpetas incorrecta, un fxmanifest inválido, mal orden en el server.cfg o conflicto con otro script.

Esta guía está orientada a quien opera un servidor FiveM propio (Windows o Linux), ya tiene framework instalado (ESX o QBCore) y quiere añadir scripts de la comunidad o pagos sin romper nada. Tiempo estimado: 10 a 15 minutos por resource bien probado.

Requisitos previos

Si tu servidor está en una VPS Linux, conecta vía SSH antes. En Windows, conecta vía RDP y abre una terminal PowerShell en la carpeta del servidor.

Entendiendo la estructura de un resource

Antes de añadir cualquier cosa, conviene conocer qué espera FXServer. Un resource FiveM válido es una carpeta dentro de resources/ (o en subcarpetas con prefijo [categoria]) que contiene al menos un fxmanifest.lua en el directorio raíz. Sin ese archivo, FXServer ignora el resource — no importa cuántos .lua o .js haya dentro.

La estructura típica:

resources/
└── [scripts]/
    └── mi-resource/
        ├── fxmanifest.lua
        ├── client.lua
        ├── server.lua
        ├── config.lua
        └── html/
            ├── index.html
            ├── style.css
            └── script.js

Las carpetas con corchetes ([scripts], [esx], [qb]) son solo organización visual — FXServer hace un escaneo recursivo. Puedes anidar hasta 2-3 niveles sin problema. Evita más que eso para no dificultar el mantenimiento.

El fxmanifest.lua mínimo

Todo resource debe declarar la versión de la API y el juego objetivo. El archivo mínimo viable:

fx_version 'cerulean'
game 'gta5'

author 'Nombre del autor'
description 'Descripción breve'
version '1.0.0'

client_scripts {
  'client.lua'
}

server_scripts {
  'server.lua'
}

shared_scripts {
  'config.lua'
}

fx_version 'cerulean' es el valor actual recomendado (soporta features modernas de FiveM). Versiones antiguas como adamant o bodacious siguen funcionando pero pierden capacidades.

Añadiendo un resource paso a paso

scp -r mi-resource/ usuario@ip-del-servidor:/path/to/server-data/resources/[scripts]/

ls /path/to/server-data/resources/[scripts]/mi-resource/

ensure mi-resource

# Frameworks primero
ensure qb-core

# Bibliotecas y dependencias
ensure ox_lib
ensure oxmysql

# Scripts de gameplay
ensure qb-multicharacter
ensure qb-spawn
ensure mi-resource

refresh
ensure mi-resource

Started resource mi-resource

Verificando que todo funciona

En la consola del servidor, ejecuta resources para ver la lista completa de resources activos. El nombre de tu resource debe aparecer con estado started. Si aparece como stopped, fue reconocido pero no se está ejecutando — verifica el ensure en el server.cfg.

Para probar funcionalmente, conéctate al servidor con tu client FiveM. Los scripts client-side reaccionan generalmente a comandos (/comando), ítems del inventario o eventos automáticos. Abre la consola F8 del client (~ o F8) — los errores Lua o JavaScript del lado client aparecen ahí con stack trace.

Resolución de problemas comunes

”Couldn’t load resource X”

Casi siempre es un fxmanifest.lua ausente o inválido. Verifica:

• El archivo se llama exactamente fxmanifest.lua (minúsculas, con .lua)
• Tiene fx_version 'cerulean' y game 'gta5' declarados
• Sintaxis Lua válida (comas y comillas balanceadas)

Si el archivo está correcto, confirma que el nombre de la carpeta coincide exactamente con el ensure del server.cfg. En Linux, MiResource y miresource son carpetas distintas — case-sensitive.

”Error loading script” con error Lua

La consola muestra la línea exacta del error. Causas frecuentes:

• Variable del framework usada antes de que el framework cargue (orden incorrecto en el server.cfg)
• Dependencia ausente (exports['ox_lib'] invocado sin ox_lib corriendo)
• Sintaxis Lua rota por edición manual

Para aislar: comenta el resource en el server.cfg, reinicia y agrega uno por uno hasta reproducir el error.

El servidor crashea al iniciar

Comenta todos los ensure excepto los core (mapmanager, chat, spawnmanager, sessionmanager, framework). Reinicia. Si sube sin crash, añade resources uno a uno hasta identificar al culpable. Ese proceso lleva tiempo pero es el único confiable cuando el error ocurre muy temprano en el boot.

Conflicto entre dos scripts en el mismo evento

Dos resources que registran un handler para el mismo evento (AddEventHandler('playerSpawned', ...)) pueden competir por el orden de ejecución. FiveM no garantiza orden entre handlers del mismo evento en resources distintos. Solución: define explícitamente la dependencia en el fxmanifest.lua del resource que tiene que ejecutarse después:

dependencies {
  'otro-resource'
}

Eso garantiza que otro-resource se cargue primero.

Próximos pasos

Con la estructura limpia y los resources corriendo estables, vale la pena profundizar en:

• Optimización de scripts: identificar resources que consumen mucha CPU usando resmon en el client (Shift+~). Resources por encima de 1.0ms client-side merecen revisión.
• Backup automatizado de resources: versionar la carpeta resources/ en un Git privado evita perder trabajo cuando rompes algo probando.
• Whitelist de scripts: en servidores roleplay, mantener una lista curada de resources aprobados reduce la superficie de bugs y exploits.
• Base de datos separada por categoría: los scripts pesados (jobs, inventario) pueden usar databases aisladas para reducir contención.

Si estás ejecutando FiveM en producción con 32+ slots y quieres infraestructura que aguante latencia baja para Brasil y Latinoamérica, los servidores de juegos de Hostini entregan latencia por debajo de 30ms para todo el Sudeste brasileño con protección DDoS incluida en el precio.