Как добавить аддон-транспорт на сервер FiveM

У аддон-транспорта своё имя модели, и он загружается рядом со стоковым транспортом GTA V, а не заменяет его. В FiveM он лежит в ресурсе сервера: сервер отправляет файлы каждому подключившемуся игроку, поэтому вручную никто ничего не ставит.

	Аддон	Замена (replace)
Имя модели	Новое (например, mycar)	Уже существующее (например, sultan)
Стоковый транспорт	Остаётся в игре	Подменяется у всех игроков
Meta-файлы	Нужна своя запись в vehicles.meta	Можно использовать стоковую запись
Типичное применение	Серверные машины, автосалоны, рабочий транспорт	Визуальная подмена машин из трафика

1. Создайте папку ресурса внутри папки resources сервера.
2. Положите файлы .yft и .ytd в подпапку stream.
3. Положите файлы .meta в подпапку data.
4. Напишите fxmanifest.lua, где каждый meta-файл указан в files и в строке data_file.
5. Добавьте ensure <имя папки> в server.cfg и перезапустите сервер.
6. Заспавните транспорт по имени модели.

У каждого meta-файла есть ещё и отдельный гайд, ссылки на них стоят в таблице в следующем разделе.

Аддон-транспорт состоит из двух групп файлов. Бинарные файлы модели лежат в stream/, а XML meta-файлы сообщают игре, что это за модель и как она себя ведёт. Игра требует только модель, её текстуры и запись в vehicles.meta. Остальные meta-файлы добавляют handling, цвета, тюнинг и сиденья.

Файл	Папка	Что делает	Обязателен?
mycar.yft, mycar_hi.yft	stream	3D-модель. См. файлы модели транспорта.	Да
mycar.ytd	stream	Словарь текстур.	Да
vehicles.meta	data	Регистрирует модель: имя, тип, layout, флаги. См. разбор vehicles.meta.	Да
handling.meta	data	Физика: масса, мощность, сцепление, подвеска. См. разбор handling.meta.	Только если у транспорта свой handlingId
carvariations.meta	data	Сочетания цветов, мод-кит, настройки света и сирен.	Рекомендуется
carcols.meta	data	Свои киты тюнинга, сирены и настройки света. См. carvariations и carcols.	Только для своих деталей тюнинга или сирен
vehiclelayouts.meta	data	Свои сиденья, точки входа и анимации. См. разбор vehiclelayouts.meta.	Только для своей посадки или анимаций

Паки транспорта для FiveM уже приходят готовым ресурсом с этими папками. Мод для одиночной игры обычно приходит архивом dlc.rpf. Внутри те же файлы, но их нужно извлечь и разложить по структуре, показанной ниже.

Инструмент	Для чего нужен
CodeWalker	Просмотр архивов игры и моделей, экспорт стоковых файлов .meta, из которых можно скопировать запись.
Blender с аддоном Sollumz	Импорт, редактирование и экспорт моделей транспорта (.yft) и словарей текстур (.ytd).
Любой текстовый редактор	Редактирование файлов .meta и fxmanifest.lua: это обычный текст.

Быстрее всего писать meta-файлы для нового транспорта так: скопировать записи самого похожего стокового транспорта и поменять имена.

Как создать или изменить саму модель, описано в гайде как сделать транспорт для FiveM в Blender с Sollumz. Как превратить dlc.rpf из одиночной игры в ресурс, читайте в гайде как конвертировать мод машины из одиночной игры в аддон FiveM, а два инструмента сравниваются в гайде CodeWalker или Sollumz.

Ресурс с транспортом это одна папка внутри папки resources сервера, а в ней fxmanifest.lua, папка stream и папка для meta-файлов. Имя папки и есть имя ресурса. Папка для meta-файлов может называться как угодно, и чаще всего её называют data.

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

Файлы в stream/ подхватываются по имени файла, поэтому в манифесте их не перечисляют. С meta-файлами так не выйдет. Каждый нужно объявить в манифесте.

В манифесте каждый meta-файл объявляется дважды: один раз в files, чтобы сервер отправил его игрокам, и один раз в строке data_file, чтобы игра загрузила его как данные нужного вида. И то и другое описано в справочнике 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' и game 'gta5' обязательны в начале любого манифеста FiveM.
• Если meta-файл есть в data_file, но его нет в files, до игрока он не доходит, и транспорта для этого игрока не существует.
• Строка типа должна соответствовать файлу: HANDLING_FILE для handling.meta, VEHICLE_METADATA_FILE для vehicles.meta и так далее. Полный список есть в справочнике data_file для транспорта.

Добавьте в server.cfg одну строку с именем папки ресурса и перезапустите сервер. ensure запускает ресурс или перезапускает его, если он уже работает.

ensure mycar

На работающем сервере вместо полного перезапуска можно ввести в консоли сервера refresh, а затем ensure mycar. Если уже подключённый игрок не видит транспорт, попросите его переподключиться.

Имя для спавна берётся из modelName в vehicles.meta, оно же имя файла .yft. Используйте его в любом админ-меню или в команде спавна транспорта. Если на сервере ещё нет команды спавна, этот клиентский скрипт добавляет /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)

Название транспорта, которое показывает игра, берётся из gameName. Это ключ текстовой метки, поэтому без метки HUD показывает сам ключ. Зарегистрируйте метку из клиентского скрипта:

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

Если аддон-транспорт не загружается, чаще всего в двух файлах не совпадает какое-то имя. Каждая пара в строках ниже должна совпадать точно:

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>

Если транспорт спавнится, но что-то не так (нет текстур, не та физика, нет деталей тюнинга), пройдитесь по гайду по устранению проблем с транспортом.

Нет. В ресурсе с транспортом нет скриптов, зависящих от ESX, QBCore или QBox, поэтому шаги выше одинаковы на любом фреймворке. Фреймворк нужен только тогда, когда транспорт должен продаваться в автосалоне или храниться в гараже. Об этом рассказано в гайде о добавлении своего транспорта в ESX, QBCore или QBox.

Рабочий пример такой структуры есть в Coil S-Cooter: папка stream с моделью, текстурами и словарями анимаций и папка data с handling, vehicles, carvariations, vehiclelayouts и clip set, и всё это загружается строками data_file без скрипта.