Cómo instalar un script en FiveM (ESX, QBCore y Standalone)

Instalar un script en FiveM parece trivial: descargas, copias la carpeta y listo. Y a veces es así. Pero cuando el recurso no arranca, la consola escupe errores en rojo o el script funciona a medias, la causa casi siempre está en uno de cuatro sitios: la estructura de carpetas, el ensure del server.cfg, el fxmanifest.lua o una dependencia que falta. En este tutorial repasamos el proceso completo de instalación, las diferencias entre frameworks y los errores típicos con su solución, para que instalar cualquier recurso te lleve dos minutos y no dos horas.

La carpeta resources y cómo organizarla

Todo recurso de FiveM vive dentro de la carpeta resources de tu servidor (en instalaciones con txAdmin, dentro de tu carpeta de datos, por ejemplo server-data/resources). Cada script es una carpeta con su propio fxmanifest.lua en la raíz:

resources/
├── [standalone]/
│   ├── ox_lib/
│   └── oxmysql/
├── [qb]/
│   ├── qb-core/
│   └── qb-inventory/
└── mi_script/
    ├── fxmanifest.lua
    ├── client/
    ├── server/
    └── config.lua

Dos reglas de oro al copiar un script nuevo:

• Cuidado con la carpeta doble. Al descomprimir un zip es habitual acabar con mi_script/mi_script/fxmanifest.lua. FiveM busca el manifest en la raíz de la carpeta del recurso: si está un nivel más adentro, el recurso ni aparece.
• Nada de espacios ni caracteres raros en el nombre. mi script v2 (final) es una receta para errores. Usa nombres simples: mi_script.

Las carpetas entre corchetes como [standalone] o [qb] son solo categorías organizativas: FiveM las recorre buscando recursos dentro, pero no son recursos en sí.

Añadir el script al server.cfg con ensure

Copiar la carpeta no basta: el servidor solo arranca los recursos que le indiques con ensure en el server.cfg:

ensure oxmysql
ensure ox_lib
ensure qb-core
ensure mi_script

El nombre que va después de ensure es el nombre de la carpeta, no el del archivo zip ni el nombre comercial del script. Y el orden importa: las dependencias se arrancan antes que quien las usa. Si mi_script necesita ox_lib, la línea de ox_lib debe ir antes. También puedes arrancar una categoría completa con ensure [qb], útil cuando tienes muchos recursos agrupados.

Un truco para no reiniciar el servidor con cada prueba: desde la consola (o desde txAdmin) puedes ejecutar ensure mi_script en caliente para arrancar o reiniciar solo ese recurso. Si aún no tienes el servidor montado, primero pasa por nuestra guía para crear un servidor FiveM paso a paso.

Entender el fxmanifest.lua

El fxmanifest.lua es la ficha técnica del recurso: le dice a FXServer qué archivos cargar y dónde ejecutarlos. Uno moderno tiene esta pinta:

fx_version 'cerulean'
game 'gta5'
lua54 'yes'

author 'Cube Resources'
description 'Ejemplo de manifest moderno'
version '1.0.0'

shared_scripts {
    '@ox_lib/init.lua',
    'config.lua',
}

client_scripts {
    'client/*.lua',
}

server_scripts {
    '@oxmysql/lib/MySQL.lua',
    'server/*.lua',
}

dependencies {
    'ox_lib',
    'oxmysql',
}

Lo esencial de cada bloque:

• fx_version 'cerulean' es la versión actual del manifest. Si ves __resource.lua en lugar de fxmanifest.lua, estás ante un recurso antiquísimo: funcionará a duras penas, pero es una señal de alarma sobre su calidad.
• shared_scripts se ejecutan en cliente y servidor (típico para configs), client_scripts solo en el cliente y server_scripts solo en el servidor. Un native de cliente en un script de servidor produce el clásico “attempt to call a nil value”.
• El prefijo @ importa un archivo de otro recurso: @ox_lib/init.lua carga la librería de ox_lib dentro de este script. Por eso ox_lib debe estar instalado y arrancado antes.
• dependencies declara qué recursos deben existir y estar iniciados; si falta alguno, el servidor se niega a arrancar el recurso y te lo dice en consola.

Como instalador rara vez tendrás que editar el manifest, pero saber leerlo te dice de un vistazo qué necesita el script para funcionar.

Dependencias y orden de arranque

La mayoría de scripts modernos dependen de dos o tres recursos base: oxmysql para base de datos, ox_lib para interfaz y utilidades, y a veces un inventario concreto como ox_inventory. La documentación del script siempre las lista; instálalas primero y colócalas antes en el server.cfg.

Un orden de arranque sano se ve así: primero base de datos (oxmysql), después librerías (ox_lib), después el core del framework (qb-core, es_extended o qbx_core), después inventario y módulos del framework, y al final los scripts de terceros. Si tu inventario es una pieza que aún estás decidiendo, en la guía del mejor inventario para FiveM comparamos las opciones más usadas.

Diferencias al instalar en ESX, QBCore y standalone

El proceso mecánico es idéntico en todos los casos; lo que cambia es la integración:

• ESX Legacy: los scripts suelen traer un config.lua donde se ajustan trabajos, precios y permisos, y en ocasiones un archivo .sql que debes importar en tu base de datos antes del primer arranque. Verifica que el script pide ESX Legacy y no versiones antiguas (1.2 o anteriores), cuyos eventos ya no existen.
• QBCore: similar, con la particularidad de que muchos recursos esperan nombres concretos de otros recursos qb (por ejemplo qb-target o qb-menu). Si has renombrado carpetas del core, tocará ajustar configs.
• Qbox: compatible con gran parte del ecosistema QBCore a través de sus bridges, pero revisa siempre que el script declare soporte para qbx_core.
• Standalone: la instalación más limpia, sin framework de por medio. Como mucho, dependencias de ox_lib. Ideal para HUDs, loading screens o utilidades.

Muchos scripts de calidad son multiframework: detectan el framework al arrancar o lo seleccionas en el config. Si dudas de qué base te conviene a largo plazo, nuestra comparativa QBCore vs ESX vs Qbox te lo aclara.

Scripts con escrow: qué cambia

Los scripts de pago suelen llegar protegidos con el Asset Escrow de FiveM: parte de los archivos van cifrados y solo se ejecutan en servidores cuya clave de licencia pertenece a la cuenta del Keymaster que compró el asset. En la práctica, instalar un script con escrow es igual que uno abierto, con dos matices:

• Debes haberlo comprado con la misma cuenta de Cfx.re que genera la licencia de tu servidor.
• Solo podrás editar los archivos que el autor dejó fuera del cifrado (normalmente config.lua y carpetas marcadas como editables).

Si la consola muestra errores de autorización al arrancar un recurso cifrado, el problema casi siempre es la cuenta o la clave, no el script. Explicamos el sistema a fondo, con sus ventajas y limitaciones, en nuestro artículo sobre el escrow de FiveM.

Errores típicos y cómo leer la consola

La consola del servidor (o la pestaña Live Console de txAdmin) te dice exactamente qué falla; solo hay que leerla con calma. Los tres errores estrella:

• El recurso no arranca y ni aparece: casi siempre es la carpeta doble tras descomprimir, un nombre con espacios o un fxmanifest.lua ausente. El mensaje típico es Couldn't find resource mi_script.
• Error de fx_version: mensajes como resource is not compatible o quejas sobre el manifest indican un recurso viejo o un manifest corrupto. Comprueba que existe fx_version 'cerulean' (o al menos una versión válida) y game 'gta5'.
• Dependencia faltante: Could not start dependency ox_lib for resource mi_script significa exactamente eso: instala la dependencia o corrige el orden de los ensure.

Ante cualquier error de script en rojo, la primera línea del mensaje señala archivo y línea exacta (@mi_script/server/main.lua:42). Con eso ya sabes si el fallo está en tu config (lo normal) o en el código del recurso.

Instalar bien un script es la mitad del trabajo; la otra mitad es instalar scripts que merezcan la pena. En nuestro catálogo todos los recursos llegan con documentación de instalación, descarga instantánea tras el pago verificado por Tebex, actualizaciones gratis de por vida y soporte 24/7 por Discord y tickets, con versiones para QBCore, ESX, Qbox y standalone.