La estructura de un servidor FiveM

Antes de escribir una sola línea de Lua conviene entender el terreno: cómo se ordena un servidor FiveM por dentro. Cuando abres por primera vez la carpeta del servidor parece un caos de archivos y subcarpetas, pero en realidad hay solo tres piezas que importan: los binarios que hacen funcionar el servidor, la carpeta de datos donde vive TU servidor, y dentro de ella la carpeta resources con todo lo que tú añades. Si tienes claro qué es cada cosa, dejarás de tener miedo a tocar archivos.

Las dos mitades: el artefacto y tus datos

Un servidor FiveM se monta sobre el «artefacto» (también llamado FXServer): es el programa descargado de Cfx.re que contiene los binarios. Esa parte NO se toca: la actualizas reemplazándola entera por una versión más nueva. La otra mitad son tus datos: tu configuración y tus recursos, que viven aparte. Mantenerlas separadas es lo que te permite actualizar el servidor sin perder tu trabajo.

C:/FiveM/
├── server/                  <- EL ARTEFACTO (binarios FXServer)
│   ├── FXServer.exe
│   ├── citizen/
│   └── ...                  (no se edita; se reemplaza al actualizar)
│
└── txData/                  <- TUS DATOS (lo que de verdad es tuyo)
    └── CFXDefault_XXXX/      <- carpeta base del perfil (la crea txAdmin)
        ├── server.cfg       <- configuración del servidor
        └── resources/       <- TODOS tus recursos van aquí

La carpeta resources: el corazón de tu servidor

Aquí vive todo lo que añades: scripts, mapas, vehículos, interfaces... Cada recurso es UNA carpeta con su propio fxmanifest.lua (lo vimos en el capítulo anterior). Pero si metieras 200 recursos sueltos en resources/ sería ingobernable. Por eso FiveM permite agrupar recursos en carpetas cuyo nombre va entre [corchetes].

resources/
├── [local]/                 <- GRUPO (no es un recurso)
│   ├── mi_hud/              <- recurso (tiene fxmanifest.lua)
│   └── mi_garaje/           <- recurso
│
├── [esx]/                   <- GRUPO de los recursos del framework
│   ├── es_extended/
│   ├── esx_menu_default/
│   └── esx_inventory/
│
├── [maps]/                  <- GRUPO de mapas/MLO
│   └── mi_comisaria/
│
└── [standalone]/            <- GRUPO de recursos sueltos
    └── ox_lib/

La clave: las carpetas entre [corchetes] NO son recursos, son cajones para agruparlos. No llevan fxmanifest.lua y no se inician por sí solas. Su gran ventaja es que puedes arrancar un grupo entero de golpe en el server.cfg con una sola línea.

# Arranca de un tirón TODOS los recursos dentro de [esx]
ensure [esx]

# O arranca recursos sueltos uno a uno
ensure ox_lib
ensure mi_hud

Tipos de recurso que te vas a encontrar

• Scripts (Lua o JavaScript): la lógica del servidor. HUD, trabajos, economía, comandos...
• Mapas / MLO: interiores y modificaciones del mundo (una comisaría nueva, un local custom).
• Vehículos: packs de coches add-on, con sus .meta de handling y variaciones.
• NUI (interfaces): menús e interfaces hechas con HTML/CSS/JS que se muestran sobre el juego.

Muchos recursos necesitan enviar archivos al PC del jugador: el modelo 3D de un coche, las texturas de una ropa, el .ytd de un objeto. Esos assets que el servidor «descarga» al cliente van en una carpeta especial llamada stream/. Todo lo que pongas dentro de stream/ se envía automáticamente a quien se conecta, sin tener que declararlo archivo por archivo.

[maps]/mi_comisaria/
├── fxmanifest.lua
├── stream/                  <- assets que viajan al cliente
│   ├── comisaria.ydr
│   ├── comisaria.ytd
│   └── comisaria.ybn
└── data/
    └── _manifest.ymt

fxmanifest avanzado: más allá de los scripts

El fxmanifest.lua no solo declara client/server scripts. Cuando un recurso usa interfaces o archivos de datos del juego, hay que decírselo con líneas específicas. Estas son las que más vas a ver:

fx_version 'cerulean'
game 'gta5'

-- Declara archivos que el cliente debe poder leer (no son scripts)
files {
  'html/index.html',
  'html/style.css',
  'data/vehicles.meta',
}

-- La página que se muestra como interfaz NUI
ui_page 'html/index.html'

-- Registra un archivo .meta como dato del juego (vehículos, handling...)
data_file 'VEHICLE_METADATA_FILE' 'data/vehicles.meta'

-- Este recurso necesita que otro arranque ANTES que él
dependency 'es_extended'

-- O varias dependencias a la vez
dependencies {
  'ox_lib',
  'oxmysql',
}

• files{}: lista los archivos (no-script) que el cliente necesita poder cargar, como HTML, CSS o .meta.
• ui_page: indica qué HTML se renderiza como interfaz NUI sobre el juego.
• data_file: registra un .meta como dato nativo del juego (un coche add-on, un handling, etc.).
• dependency / dependencies: obligan a que otros recursos arranquen antes; FiveM se queja si falta alguno.

Buenas prácticas de organización

• Agrupa por dominio, no por capricho: [esx] para el framework, [maps] para mapas, [vehicles] para coches, [local] para lo tuyo.
• Nombres en minúscula, sin espacios ni acentos: usa guiones bajos (mi_garaje, no «Mi Garaje»).
• Separa la configuración: deja un config.lua claro en shared_scripts para no tener que editar el código.
• Un recurso, una responsabilidad: es mejor tener mi_hud y mi_garaje separados que un mega-recurso que lo hace todo.

¿Dónde pongo un recurso nuevo? Lo arrastras a la carpeta de su grupo (por ejemplo [local]) y listo. Si ese grupo ya se inicia con ensure [local] en tu server.cfg, FiveM lo descubre solo: no hace falta añadir una línea por cada recurso. Si en cambio lo arrancas suelto, tendrás que escribir su ensure mi_recurso a mano. Tras moverlo, en la consola del servidor un refresh hace que aparezca, y ensure mi_recurso lo enciende sin reiniciar todo el servidor.