Addon-машины в FiveM: vehicles.meta и размер

Addon-машина в FiveM - это ресурс с моделью и текстурами машины в папке stream и четырьмя-пятью meta-файлами - vehicles.meta, carvariations.meta, carcols.meta, handling.meta, иногда vehiclelayouts.meta, - зарегистрированными строками data_file в fxmanifest.lua. У неё собственное имя для спавна, и она стоит рядом с машинами базовой игры. Replace-машина проще: вы стримите файл с тем же именем, что у модели из базовой игры, и оригинал исчезает везде, включая трафик. Addon - правильный вариант по умолчанию. Что идёт не так: имена, которые не совпадают между файлами, две машины, претендующие на один ID modkit, и паки настолько большие, что каждый новый игрок ждёт входа десять минут. В этом руководстве - структура ресурса, каждый meta-файл, поля, которые должны совпадать, размеры, интеграция с фреймворком и ошибки, которые вы увидите.

Addon или replace#

Replace работает потому, что FiveM стримит по имени файла: ресурс, поставляющий adder.yft, adder_hi.yft и adder.ytd, подменяет собственный Adder игры у каждого игрока. Это ровно то, что нужно, если, скажем, вы заменяете базовые полицейские машины единым автопарком, - каждая полицейская машина NPC тоже меняется. И ровно то, что не нужно для машины из автосалона, потому что Adder в трафике и в каждом скрипте, который его спавнит, становится вашей кастомной моделью.

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

Структура ресурса#

Одна addon-машина:

resources/[vehicles]/rmodgtr/  fxmanifest.lua  data/    vehicles.meta    carvariations.meta    carcols.meta    handling.meta  stream/    rmodgtr.yft    rmodgtr_hi.yft    rmodgtr.ytd

fx_version 'cerulean'game 'gta5'files {    'data/**/*.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_file 'VEHICLE_LAYOUTS_FILE'     'data/**/vehiclelayouts.meta'

Блок files делает meta-файлы доступными клиентам; строки data_file сообщают игре, что представляет собой каждый из них. Шаблон ** позволяет одному манифесту охватить пак, где у каждой машины своя подпапка внутри data/, - так устроено большинство сборных паков. Строка data_file, указывающая на несуществующий файл, безвредна, поэтому паки часто включают строку для layouts независимо от того, использует ли её какая-нибудь машина.

Стриминговые файлы: .yft - модель, _hi.yft - высокодетализированная версия для близкого расстояния, .ytd - текстуры. Некоторые машины добавляют +hi.ytd для текстур вблизи и отдельные файлы .ytd для деталей modkit. Любой файл в stream регистрируется автоматически - общие правила для стримингового контента описаны в статье о MLO и стриминговых ассетах в FiveM.

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

vehicles.meta: имена, которые должны совпадать#

vehicles.meta определяет машину. Большинство проблем возникает из-за горстки полей, которые должны в точности совпадать с другими файлами:

<Item>  <modelName>rmodgtr</modelName>  <txdName>rmodgtr</txdName>  <handlingId>RMODGTR</handlingId>  <gameName>RMODGTR</gameName>  <vehicleMakeName>NISSAN</vehicleMakeName>  <type>VEHICLE_TYPE_CAR</type>  <vehicleClass>VC_SPORT</vehicleClass>  <layout>LAYOUT_STANDARD</layout></Item>

type и vehicleClass определяют, как игра с машиной обращается: VEHICLE_TYPE_BIKE - для мотоцикла, VC_EMERGENCY помещает её в класс экстренных служб и так далее. layout определяет положение сидений и анимации посадки; кастомные layouts берутся из vehiclelayouts.meta.

Имя для спавна - это modelName. Отображаемое имя в гаражах и на HUD машины берётся из текстовой метки в gameName, и addon-машина, чья метка нигде не определена, показывается как NULL или как сырая метка. Определите её на клиенте:

CreateThread(function()    AddTextEntry("RMODGTR", "GT-R R35")end)

handling.meta, carcols.meta и автопарки экстренных служб#

handling.meta определяет, как машина едет. Её handlingName должно совпадать с handlingId из vehicles.meta, а имена handling глобальны: две машины с одинаковым именем handling делят одну запись, и та, что загрузилась последней, побеждает для обеих. Вот так седан и начинает разгоняться как гиперкар.

<Item type="CHandlingData">  <handlingName>RMODGTR</handlingName>  <fMass value="1750.000000" />  <fInitialDragCoeff value="8.500000" />  <fInitialDriveForce value="0.340000" />  <fInitialDriveMaxFlatVel value="168.000000" />  <fBrakeForce value="1.100000" />  <fTractionCurveMax value="2.650000" /></Item>

Авторы настраивают handling для удовольствия в одиночной игре, а на ролевом сервере это обычно значит «слишком быстро». Настроить весь автопарк на согласованные значения - нормальная практика, и поля выше - масса, сила тяги, максимальная скорость, тормоза, сцепление - хорошая отправная точка. Меняйте по одному значению за раз и тестируйте.

carcols.meta содержит modkit машины: список тюнинг-деталей и ID набора, на который ссылается carvariations.meta.

<Kits>  <Item>    <kitName>4517_rmodgtr_modkit</kitName>    <id value="4517" />    <kitType>MKT_SPECIAL</kitType>  </Item></Kits>

<kits>  <Item>4517_rmodgtr_modkit</Item></kits>

Простой способ проверки: найдите <id value= во всех carcols.meta и отсортируйте результаты. Дубликаты - это машины, которые нужно исправить. Измените ID в carcols.meta и держите имя набора в carvariations.meta в соответствии с новым kitName.

Размер: цена, которую платит каждый игрок#

Каждый новый игрок скачивает каждую стриминговую машину, прежде чем сможет играть, а клиент держит в памяти текстуры машин вокруг себя. Addon-машины очень сильно различаются по размеру: хорошо сделанная машина весит несколько мегабайт, а машина, выдранная с 4K-текстурами на каждой поверхности, может весить тридцать и больше. FXServer при запуске предупреждает о любом ассете больше 16 MiB физической памяти:

Asset rmodgtr.ytd uses 24.0 MiB of physical memory. Oversized assets can and WILLlead to streaming issues (such as models not loading/rendering).

На сервере с тремя сотнями машин нескольких раздутых на оживлённой парковке достаточно, чтобы у всех, кто там стоит, перестали загружаться текстуры.

Как держать автопарк под контролем:

1. Отсортируйте папки `stream` по размеру. Двадцать самых больших файлов обычно и составляют большую часть общего объёма.
2. Уменьшите раздутые текстуры. Если открыть .ytd и уменьшить большие текстуры до 2048 или 1024, размер машины обычно падает вдвое без видимой разницы на парковке.
3. Сократите автопарк. Большинство серверов несут машины, которыми никто не владеет. Ваша база данных знает, какие модели реально есть у игроков; остальные - это стоимость загрузки впустую.
4. Разделите по назначению. [vehicles-emergency], [vehicles-dealer], [vehicles-donor] - отдельные ресурсы проще измерять и удалять, чем один «карпак» на 4 GB.

Само число ресурсов для машин - не проблема производительности: у них нет скриптов, и основному потоку сервера они ничего не стоят. Цена - загрузка и память клиента. Как измерять скриптовую сторону, описано в статье о производительности сервера FiveM.

Машины экстренных служб, ливреи и extras

Автопарки полиции, EMS и пожарных - самая частая причина, по которой ролевой сервер вообще добавляет машины, и они приносят ещё три вещи, которыми нужно управлять.

Ливреи. Большинство паков экстренных служб поставляют несколько ливрей на машину - департаменты, звания, версии без опознавательных знаков, - либо как вариации текстур внутри модели, либо как записи ливрей в meta. Скрипт или гараж выбирает одну через native SetVehicleLivery. Если меню ливрей показывает неверное число вариантов, модель и meta расходятся во мнении, сколько их.

Extras. Световые балки, кенгурятники, оборудование и перегородки часто смоделированы как extras - пронумерованные детали, которые включаются и выключаются через SetVehicleExtra. Гаражи департаментов обычно задают фиксированную комбинацию для каждой машины, чтобы автопарк выглядел единообразно. Отсутствующие в игре extras - это вопрос к модели, а не к скрипту.

Сирены. Световые схемы хранятся в carcols.meta как настройки сирен и, как и modkit, идентифицируются номером. Два пака, использующие одинаковый ID настройки сирены, конфликтуют, и одна машина мигает по схеме другой. Объединяя паки экстренных служб от разных авторов, проверяйте ID сирен так же, как ID modkit.

С паками экстренных служб выбор между replace и addon становится интересным. Замена базовых полицейских машин означает, что полиция NPC и вызванные подразделения тоже ездят на вашем автопарке, чего некоторые серверы хотят ради единообразия. Большинство ролевых серверов предпочитают addon, чтобы у полиции-игроков были свои машины, а фоновая полиция оставалась на базовых, и затем отключают вызов фоновой полиции собственными скриптами.

Как сообщить фреймворку о машине#

Стриминг делает машину доступной для спавна по имени. Автосалонам, гаражам и админ-меню нужно знать, что она существует.

• QBCore хранит список машин в общем Lua-файле в qb-core (в свежих версиях это shared/vehicles.lua), по одной записи на модель с названием, маркой, ценой, категорией и магазином. Машину, которой там нет, нельзя купить, и её может не получиться поставить в гараж.
• Автосалоны ESX традиционно читают таблицу vehicles в базе данных с моделью, названием, ценой и категорией. Добавляйте строки через SQL или phpMyAdmin.
• Qbox хранит общий список машин в собственном ядре; точное расположение проверяйте в актуальном репозитории, потому что между релизами оно менялось.

Машины во владении хранятся для каждого игрока в базе данных (owned_vehicles в ESX, player_vehicles в QBCore) с именем модели или хэшем. Удаление машины с сервера оставляет эти строки, и гаражи потом ломаются, когда игрок пытается достать модель, которой больше нет. Выводя машину из оборота, решите, что получат владельцы, - возврат денег, модель на замену, - и обновите строки, а не оставляйте битые записи. Как безопасно работать с этими таблицами, описано в статье о базах данных FiveM и oxmysql, а backup перед любым массовым изменением - не опция, а обязательный шаг.

Если у вас работает sv_entityLockdown, машины должны создаваться на сервере. Современные гаражи уже так делают; старый автосалон, который спавнит машину для предпросмотра на клиенте, перестанет работать. Серверный шаблон есть в статье OneSync и слоты игроков.

Сборка игры, источники и лицензирование#

Некоторые addon-машины используют детали базовых машин из свежих обновлений GTA Online. Они работают только на сервере, который требует как минимум эту сборку игры через sv_enforceGameBuild. Машина, из-за которой клиенты вылетают при спавне или которая появляется без колёс, - это часто несовпадение сборки; автор должен указать нужную сборку.

Важно и то, откуда берутся машины. Многие бесплатные «addon-паки» - это модели, выдранные из других гоночных игр, то есть чужая интеллектуальная собственность. Правила Cfx.re запрещают продавать доступ к контенту, на который у вас нет прав, а платные ресурсы распространяются через систему escrow Cfx.re, привязанную к аккаунту покупателя, - статья об escrow и лицензировании ассетов FiveM объясняет, как это работает и почему слитые паки угрожают вашему лицензионному ключу. Донатные машины - особая ловушка; прочитайте статью о монетизации игрового сервера в рамках правил, прежде чем ставить машину за оплату.

Установка машины без простоя#

Добавление машины не требует полного перезапуска сервера:

1. Загрузите папку ресурса. На RE:NODE перетащите zip в файловый менеджер, и он распакуется на месте, а большой пак загрузите по SFTP.
2. Добавьте ensure rmodgtr в server.cfg, чтобы ресурс пережил следующий рестарт.
3. В консоли выполните refresh, затем ensure rmodgtr.
4. Игроки, которые уже онлайн, получат новые файлы; некоторые изменения meta полностью вступают в силу только после переподключения.
5. Заспавните машину один раз админской командой и проверьте текстуры, управляемость, тюнинг и отображаемое имя, прежде чем объявлять о ней.

Сначала сделайте backup, если пак затрагивает meta-файлы существующих машин, и тестируйте объединённые паки на копии сервера, а не на живом: сломанный carcols.meta может уронить каждого клиента, который заезжает в тюнинг-мастерскую.

Устранение неполадок#

«Model does not exist» или ничего не спавнится. Имя для спавна не совпадает с modelName, ресурс не запущен или строки data_file не указывают на meta-файлы. IsModelInCdimage(GetHashKey("rmodgtr")) на клиенте скажет, знает ли игра эту модель.

Машина появляется без текстур. txdName не совпадает с именем файла .ytd, или .ytd раздут и не стримится.

Едет как стоковая машина. handlingId и handlingName не совпадают, или файл handling не зарегистрирован. Или другая машина использует то же имя handling.

Тюнинг-меню показывает не те детали или вылетает. Дублирующиеся ID modkit у двух машин.

Имя показывается как NULL. Нет AddTextEntry для метки gameName.

Клиенты вылетают, когда появляется машина. Сломанная модель, раздутый ассет или сборка игры ниже, чем нужна машине.

FAQ#

Чем addon-машины отличаются от replace в FiveM?

Addon-машина - это новая модель с собственным именем для спавна и meta-файлами, рядом с базовой игрой. Replace-машина подменяет одноимённую базовую модель, так что каждый экземпляр этой машины, включая трафик, становится кастомным.

Нужны ли addon-машине все meta-файлы?

Нужен vehicles.meta и обычно carvariations.meta, carcols.meta и handling.meta. vehiclelayouts.meta - только если у машины кастомный layout. Каждый должен быть указан в files и зарегистрирован строкой data_file.

Сколько addon-машин может быть на сервере FiveM?

Фиксированного числа нет. Практический предел - общий размер загрузки и память клиента, а не CPU сервера. Сотни машин работают, если каждая разумного размера; несколько десятков раздутых сами по себе могут привести к пропаже текстур.

Почему у двух моих машин тюнинг-детали друг друга?

У них общий ID modkit в carcols.meta. Дайте одной уникальный ID и обновите имя её набора в carvariations.meta.

Можно ли добавлять машины без перезапуска сервера?

Да. Загрузите ресурс, выполните refresh и ensure в консоли и добавьте строку ensure в server.cfg. Некоторым игрокам может понадобиться переподключиться, чтобы всё загрузилось правильно.