Справочник data_file в fxmanifest для транспорта

По документации FiveM, data_file добавляет "a data file of a specified type to the game extra content system", то есть файл данных указанного типа в систему дополнительного контента игры. На практике это тот же механизм, который игра использует для собственных DLC-паков: каждый тип обрабатывает свой загрузчик, умеющий читать такие файлы.

В строке два строковых значения: тип и путь внутри ресурса.

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'

Файл должен быть и в files. files заставляет сервер отправить файл игрокам, а data_file заставляет игру его прочитать. Одно без другого ничего не даёт.

Типы, важные для транспорта, взяты из справочника FiveM по файлам данных.

Тип data_file	Файл	Корневой элемент	Назначение
HANDLING_FILE	handling.meta	CHandlingDataMgr	Физические профили. Гайд
VEHICLE_METADATA_FILE	vehicles.meta	CVehicleModelInfo__InitDataList	Регистрирует модели транспорта. Гайд
CARCOLS_FILE	carcols.meta	CVehicleModelInfoVarGlobal	Мод-киты, сирены, свет. Гайд
VEHICLE_VARIATION_FILE	carvariations.meta	CVehicleModelInfoVariation	Цвета, киты и настройки света для каждой модели.
VEHICLE_LAYOUTS_FILE	vehiclelayouts.meta	CVehicleMetadataMgr	Сиденья, точки входа, анимации. Гайд
CLIP_SETS_FILE	clip_sets.xml	fwClipSetManager	Clip set для своих анимаций.
EXPLOSION_INFO_FILE	explosion.meta	CExplosionInfoManager	Свои настройки взрывов.
VFXVEHICLEINFO_FILE	vfxvehicleinfo.meta		Наборы визуальных эффектов транспорта.
PTFXASSETINFO_FILE	ptfxassetinfo.meta		Информация об ассетах эффектов частиц.
AUDIO_GAMEDATA, AUDIO_SOUNDDATA, AUDIO_WAVEPACK	.dat151.rel, .dat54.rel, папка с файлами .awc		Свои звуки двигателя.
VEHICLE_SHOP_DLC_FILE	shop_vehicle.meta		Данные магазина транспорта из DLC-паков.
CONTENT_UNLOCKING_META_FILE			Указан в справочнике без описания. Для аддон-транспорта не нужен.

Тип нужно писать точно и заглавными буквами.

Частично. FiveM всегда загружает записи HANDLING_FILE и VEHICLE_LAYOUTS_FILE раньше всех остальных типов, в каком бы порядке вы их ни написали. Все остальные типы сохраняют порядок манифеста. Так устроен код клиента FiveM: перед загрузкой он сортирует список именно так.

Причина на стороне игры: при чтении vehicles.meta игра сразу же ищет по имени запись handling и layout транспорта. Если они ещё не загружены, транспорт регистрируется без них.

Остальные типы пишите в порядке зависимостей: сначала то, на что ссылаются.

fx_version 'cerulean'
game 'gta5'

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

-- 1. things vehicles.meta points at
data_file 'HANDLING_FILE'          'data/handling.meta'
data_file 'CLIP_SETS_FILE'         'data/clip_sets.xml'
data_file 'VEHICLE_LAYOUTS_FILE'   'data/vehiclelayouts.meta'
-- 2. the vehicle itself
data_file 'VEHICLE_METADATA_FILE'  'data/vehicles.meta'
-- 3. kits, then the variations that reference them
data_file 'CARCOLS_FILE'           'data/carcols.meta'
data_file 'VEHICLE_VARIATION_FILE' 'data/carvariations.meta'

• CLIP_SETS_FILE ближе к началу, потому что layout ссылаются на clip set по имени.
• Затем VEHICLE_METADATA_FILE.
• CARCOLS_FILE перед VEHICLE_VARIATION_FILE, потому что carvariations.meta ссылается на киты, которые определяет carcols.meta.

Да. И files, и data_file принимают glob-шаблоны в пути. * совпадает в пределах одной папки, а ** на любой глубине. Пак транспорта, где у каждого транспорта своя подпапка, можно объявить один раз:

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'

После этого новый транспорт в data/ подхватывается без правки манифеста.

Файлы в папке с именем stream регистрируются автоматически по имени и расширению, поэтому моделям, текстурам и словарям анимаций запись в манифесте не нужна. Подпапки внутри stream допустимы. Две вещи FiveM там не принимает: файлы без расширения и архивы .rpf, которые сначала нужно распаковать.

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

У платных ресурсов, которые поставляются через Cfx.re Asset Escrow, скрипты и файлы моделей защищены, а в записи манифеста escrow_ignore перечислены файлы, которые система escrow не трогает. Какие файлы остаются открытыми, решает автор, поэтому смотрите страницу продукта. Чаще всего владелец сервера хочет редактировать такие meta-файлы:

• handling.meta, чтобы изменить скорость, сцепление и торможение.
• carvariations.meta, чтобы изменить сочетания цветов.
• vehicles.meta, чтобы изменить флаги, класс или ключ отображаемого названия.

В транспорте Nilo3D, например в Coil S-Cooter, meta-файлы handling и vehicles остаются открытыми. Как устанавливаются ресурсы под escrow, описано в гайде об установке ресурса FiveM из Cfx.re Escrow.

Если ресурс с escrow не запускается с ошибкой "You lack the required entitlement", смотрите гайд как исправить ошибку entitlement.

Ошибка	Результат	Решение
Meta-файл есть в data_file, но его нет в files	Файл не доходит до игрока.	Добавьте тот же путь в files.
Неверный путь или имя папки	Ничего не загружается.	Пути задаются относительно папки ресурса и пишутся через прямую косую черту.
Неверный тип для файла	Файл попадает не к тому загрузчику, и его данные не применяются.	Используйте тип из таблицы выше.
Meta-файлы лежат в stream/	Они не загружаются как файлы данных.	Держите meta-файлы вне stream и объявляйте их.
Нет fx_version или game	Ресурс загружается некорректно.	Начинайте манифест с fx_version 'cerulean' и game 'gta5'.

Весь процесс, от папок до спавна, описан в гайде о добавлении аддон-транспорта в FiveM.