Cómo añadir un vehículo add-on a un servidor FiveM

Un vehículo add-on es un vehículo con su propio nombre de modelo que se carga junto a los vehículos originales de GTA V en lugar de reemplazar a uno de ellos. En FiveM vive en un resource del servidor: el servidor envía los archivos a cada jugador que entra, así que nadie instala nada a mano.

	Add-on	Reemplazo
Nombre de modelo	Nuevo (por ejemplo mycar)	Uno existente (por ejemplo sultan)
Vehículo original	Sigue en el juego	Se sustituye para todos los jugadores
Archivos meta	Necesita su propia entrada en vehicles.meta	Puede reutilizar la entrada original
Uso típico	Coches del servidor, tiendas, vehículos de trabajo	Cambios visuales de coches del tráfico

1. Crea una carpeta para el resource dentro de la carpeta resources del servidor.
2. Pon los archivos .yft y .ytd en una subcarpeta stream.
3. Pon los archivos .meta en una subcarpeta data.
4. Escribe un fxmanifest.lua que declare cada meta en files y en una línea data_file.
5. Añade ensure <folder name> a server.cfg y reinicia el servidor.
6. Haz spawn del vehículo con su nombre de modelo.

Cada archivo meta tiene además su propia guía, enlazada en la tabla de la sección siguiente.

Un vehículo add-on son dos grupos de archivos: los archivos binarios del modelo, que van en stream/, y los archivos meta en XML, que le dicen al juego qué es el modelo y cómo se comporta. El juego solo exige el modelo, sus texturas y una entrada en vehicles.meta. Los demás metas añaden handling, colores, tuning y asientos.

Archivo	Carpeta	Qué hace	¿Necesario?
mycar.yft, mycar_hi.yft	stream	El modelo 3D. Consulta archivos de modelo del vehículo.	Sí
mycar.ytd	stream	El diccionario de texturas.	Sí
vehicles.meta	data	Registra el modelo: nombre, tipo, layout, flags. Consulta vehicles.meta explicado.	Sí
handling.meta	data	Física: masa, potencia, agarre, suspensión. Consulta handling.meta explicado.	Solo si el vehículo tiene su propio handlingId
carvariations.meta	data	Combinaciones de color, mod kit, ajustes de luces y sirenas.	Recomendado
carcols.meta	data	Kits de tuning, sirenas y configuraciones de luces personalizados. Consulta carvariations y carcols.	Solo para piezas de tuning o sirenas personalizadas
vehiclelayouts.meta	data	Asientos, puntos de entrada y animaciones personalizados. Consulta vehiclelayouts.meta explicado.	Solo para asientos o animaciones personalizados

Los packs de vehículos hechos para FiveM ya vienen como un resource con estas carpetas. Un vehículo descargado como mod de un jugador suele venir como un archivo dlc.rpf. Dentro están los mismos archivos, pero hay que extraerlos y ordenarlos en la estructura de abajo.

Herramienta	Para qué se usa
CodeWalker	Explorar los archivos del juego, ver modelos y exportar archivos .meta originales de los que copiar una entrada.
Blender con el add-on Sollumz	Importar, editar y exportar modelos de vehículos (.yft) y diccionarios de texturas (.ytd).
Cualquier editor de texto	Editar los archivos .meta y fxmanifest.lua, que son texto plano.

La forma más rápida de escribir los metas de un vehículo nuevo es copiar las entradas del vehículo original que más se le parezca y cambiar los nombres.

Para crear o cambiar el modelo en sí, mira cómo hacer un vehículo FiveM en Blender con Sollumz. Convertir un dlc.rpf de un jugador en un resource está en cómo convertir un coche de un jugador en add-on FiveM, y las dos herramientas se comparan en CodeWalker vs Sollumz.

Un resource de vehículo es una carpeta dentro de la carpeta resources del servidor con un fxmanifest.lua, una carpeta stream y una carpeta para los metas. El nombre de la carpeta es el nombre del resource. La carpeta de los metas puede llamarse como quieras, y casi todo el mundo la llama data.

resources/
  mycar/
    fxmanifest.lua
    data/
      handling.meta
      vehicles.meta
      carcols.meta
      carvariations.meta
    stream/
      mycar.yft
      mycar_hi.yft
      mycar.ytd

Los archivos de stream/ se detectan por su nombre de archivo, así que no se declaran en el manifest. Los archivos meta no tienen ese atajo. Hay que declarar cada uno en el manifest.

El manifest declara cada archivo meta dos veces: una en files, para que el servidor lo envíe a los jugadores, y otra en una línea data_file, para que el juego lo cargue como el tipo de dato correcto. Ambas están documentadas en la referencia del resource manifest de FiveM.

fx_version 'cerulean'
game 'gta5'

files {
  'data/handling.meta',
  'data/vehicles.meta',
  'data/carcols.meta',
  'data/carvariations.meta',
}

data_file 'HANDLING_FILE'          'data/handling.meta'
data_file 'VEHICLE_METADATA_FILE'  'data/vehicles.meta'
data_file 'CARCOLS_FILE'           'data/carcols.meta'
data_file 'VEHICLE_VARIATION_FILE' 'data/carvariations.meta'

• fx_version 'cerulean' y game 'gta5' son obligatorios al principio de todo manifest de FiveM.
• Un meta que está en data_file pero falta en files nunca llega al jugador, así que el vehículo no existirá para él.
• La cadena del tipo debe corresponder al archivo: HANDLING_FILE para handling.meta, VEHICLE_METADATA_FILE para vehicles.meta, y así con los demás. La lista completa está en la referencia de data_file para vehículos.

Añade a server.cfg una línea con el nombre de la carpeta del resource y reinicia el servidor. ensure inicia el resource, o lo reinicia si ya está en marcha.

ensure mycar

Con el servidor en marcha puedes escribir refresh y después ensure mycar en la consola del servidor en lugar de reiniciarlo entero. Si un jugador que ya estaba conectado no ve el vehículo, pídele que se reconecte.

El nombre de spawn es el modelName de vehicles.meta, que también es el nombre del archivo .yft. Úsalo con cualquier menú de administración o comando de spawn de vehículos. Si el servidor todavía no tiene un comando de spawn, este script de cliente añade /car mycar:

RegisterCommand('car', function(_, args)
  local model = GetHashKey(args[1] or 'mycar')
  if not IsModelInCdimage(model) then return print('model not found') end
  RequestModel(model)
  while not HasModelLoaded(model) do Wait(0) end
  local ped = PlayerPedId()
  local veh = CreateVehicle(model, GetEntityCoords(ped), GetEntityHeading(ped), true, false)
  SetPedIntoVehicle(ped, veh, -1)
  SetModelAsNoLongerNeeded(model)
end)

El nombre que el juego muestra para el vehículo sale de gameName. Es una etiqueta de texto, así que sin etiqueta el HUD muestra la clave tal cual. Registra una desde un script de cliente:

-- client script: readable name for <gameName>MYCAR</gameName>
AddTextEntry('MYCAR', 'My Car GT')

La mayoría de los vehículos add-on que no cargan tienen un nombre que no coincide entre dos archivos. En cada línea de abajo, los dos nombres tienen que ser idénticos:

stream/mycar.yft                 <modelName>mycar</modelName>
stream/mycar.ytd                 <txdName>mycar</txdName>
handling.meta <handlingName>     <handlingId>MYCAR</handlingId>
carvariations.meta <modelName>   <modelName>mycar</modelName>
vehiclelayouts.meta <Name>       <layout>LAYOUT_STANDARD</layout>
carcols.meta <kitName>           carvariations.meta <kits><Item>

Si el vehículo hace spawn pero algo falla (sin texturas, física equivocada, sin piezas de tuning), repasa la guía de solución de problemas de vehículos.

No. Un resource de vehículo no tiene ningún script que dependa de ESX, QBCore o QBox, así que los pasos de arriba son los mismos en todos los frameworks. El framework solo entra en juego cuando el vehículo se va a vender en un concesionario o guardar en un garaje, y eso está en añadir un vehículo personalizado a ESX, QBCore o QBox.

El Coil S-Cooter es un ejemplo funcional de esta estructura: una carpeta stream con el modelo, las texturas y los diccionarios de animación, y una carpeta data con handling, vehicles, carvariations, vehiclelayouts y clip sets, todo cargado con líneas data_file y sin ningún script.