Проблемы с аддон-транспортом в FiveM: причины и решения

Симптом	Наиболее вероятная причина	Решение
Команда спавна сообщает, что модель не существует	Ресурс не запущен, vehicles.meta не загружен или modelName отличается от имени .yft	Не спавнится
Транспорт невидим или появляется с задержкой	Слишком тяжёлые модель или текстуры; нет _hi.yft	Невидимый транспорт
Белые, серые или отсутствующие текстуры	txdName отличается от имени .ytd или текстуры нет в словаре	Нет текстур
Транспорт проваливается сквозь землю	Модель экспортирована без коллизии	Проваливается сквозь карту
Едет как другая машина, или правки handling ничего не дают	handlingId не совпадает или имя использовано дважды	Неправильный handling
Нет деталей тюнинга или детали от другой машины	Дублирующийся ID кита в carcols.meta	Проблемы с тюнингом
Название показывается как NULL или как код	Нет текстовой метки для gameName	Неправильное название
Игрок сидит неправильно или не может сесть	Layout не подходит к костям модели	Сиденья и посадка

Прежде всего посмотрите в консоль сервера при запуске ресурса и в клиентскую консоль (F8) при спавне транспорта. Обе называют файл, с которым у них проблема.

Если игра сообщает, что модель не существует, транспорт так и не был зарегистрирован. Проверьте по порядку:

1. Ресурс запущен. ensure mycar есть в server.cfg, и имя папки написано так же. Папка внутри папки-категории вроде [cars] допустима.
2. vehicles.meta указан и в files, и в data_file 'VEHICLE_METADATA_FILE', с правильным путём. См. справочник data_file.
3. Имена совпадают. Имя для спавна равно modelName, а файл модели должен называться stream/<modelName>.yft.
4. XML корректен. Один незакрытый тег делает весь файл нечитаемым. Откройте его в редакторе, который проверяет XML.
5. Файлы извлечены. FiveM не загружает архивы .rpf, положенные в stream, поэтому файлы .yft и .ytd нужно из них достать.

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>

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

Если транспорт спавнится (в него можно сесть, камера следует за ним), но не отрисовывается, это почти всегда проблема стриминга.

• Слишком тяжёлые файлы. Поищите в консоли сервера "uses ... MiB of physical memory". FXServer сам сообщает, что такие файлы "lead to streaming issues (such as models not loading/rendering)". Уменьшите текстуры, как описано в гайде о файлах модели транспорта и предупреждении 16 MiB.
• Нет _hi.yft. Когда первое значение lodDistances больше нуля, игра запрашивает <modelName>_hi.yft для транспорта рядом с камерой. Кладите в ресурс этот файл именно с таким именем.
• Слишком много тяжёлого транспорта в одном месте. Память суммируется по уникальным моделям, поэтому на автосходке может сломаться то, что работает с одной машиной.

• Имя словаря. txdName в vehicles.meta должно быть равно имени файла .ytd без расширения.
• Текстуры нет в словаре. Откройте .ytd и проверьте, что каждая текстура, которую используют материалы, лежит там под тем же именем.
• Общие текстуры. Если модель полагается на текстуры из vehshare или из общего словаря пака транспорта, этот словарь должен быть родителем словаря транспорта в txdRelationships.
• Ливреи. Им нужен FLAG_HAS_LIVERY и текстуры, имена которых заканчиваются на _sign_1, _sign_2 и так далее.

Коллизия транспорта хранится внутри .yft. Модели, экспортированной без коллизии, не на что опереться, поэтому она проваливается сквозь дорогу или уходит в землю по крышу. Исправлять это нужно в модели: откройте её в инструменте, в котором она сделана, добавьте коллизию и экспортируйте заново. Никакой meta-файл этого не исправит.

Если тонут только колёса или кузов скребёт по земле, коллизия есть, а проблема в подвеске: смотрите fSuspensionRaise и пределы хода в разборе handling.meta.

Как добавить bounds в Blender, описано в гайде как настроить коллизию транспорта в Sollumz.

• Имена не совпадают. handlingId в vehicles.meta должен быть равен handlingName в handling.meta.
• Файл не загружен. Для handling.meta нужны files и data_file 'HANDLING_FILE'.
• Имя использовано дважды. Если два ресурса определяют один и тот же handlingName, ваши правки могут попадать в ту запись, которую игра не использует. Давайте каждому транспорту уникальное имя.
• Не тот блок sub-handling. Для VEHICLE_TYPE_BIKE нужен CBikeHandlingData, для машины CCarHandlingData.
• Правки не применились. Перезапустите ресурс, переподключитесь и заспавните новый транспорт, прежде чем оценивать изменение.

ID китов в carcols.meta общие для всего транспорта на сервере. Когда у двух китов одинаковый id, игра переносит один из них на другой ID, и транспорт с этим китом может получить не те детали или остаться без них. Поменяйте id на номер, который не использует другой транспорт. ID сирен и света конфликтуют так же.

Также проверьте, что имя кита в списке kits файла carvariations.meta равно kitName в carcols.meta и что модель каждой детали, названной в ките, лежит в папке stream. Подробности в разборе carvariations и carcols.

Проверка конфликтов ID в carcols показывает каждый ID кита, который занят в нескольких carcols.meta на сервере.

В gameName хранится ключ текстовой метки, а не само название. Добавьте метку в клиентском скрипте и уложите ключ максимум в 11 символов:

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

layout в vehicles.meta определяет сиденья и анимации посадки и рассчитывает на определённые кости в модели: кости сидений вроде seat_dside_f и кости дверей вроде door_dside_f. Выберите layout, сделанный для такого же вида транспорта (layout мотоцикла для мотоцикла, двухдверный layout для двухдверной машины), и проверьте, что в модели есть кости, которые называет layout. Как устроены layout, описано в разборе vehiclelayouts.meta.

Если ничего из этого не помогло, соберите ресурс с нуля по гайду о добавлении аддон-транспорта в FiveM и тестируйте после каждого файла.