Companion Dogs: базовый план создания аддона породы
Руководство Companion Dogs описывает отдельный Workshop add-on, который регистрирует одну породу либо несколько вариантов с общим телом. Оно рассчитано на читателя, знакомого с Lua и уже имеющего ригованную анимированную модель. Здесь — последовательность интеграции и контрольные точки; полноценный проект, полный код, создание/риггинг модели и публикация не входят в материал.
В примере mod.info указаны pzversion=42.19.0 и versionMin=42.18.0; они не устанавливают универсальный минимум для всех аддонов. Версия базового мода, API и поля могут отличаться. API_VERSION, совместимость, регистрацию и код здесь не запускали и в игре не проверяли. Примеры функций могут ссылаться на нераскрытые вспомогательные функции; воспринимайте их как иллюстрации интерфейса API, а не как копируемый самодостаточный код.
Что делает аддон, а что остаётся базовому моду
Базовый Companion Dogs предоставляет машину состояний, анимации/скелет, маршрутизацию, бой, охоту, пастуший режим, окно, меню, приручение, размножение, щенков, sandbox-настройки и сетевую синхронизацию. Аддон задаёт отличия своего животного: параметры, модель/текстуру/портрет, места появления, имя, описание и при необходимости значок настроения.
Сначала решите, создаёте ли вы породу собаки или новый вид животного. Порода пользуется общими функциями собаки, но имеет собственные параметры; вид может не иметь некоторых доступных породе занятий, а его регистрация требует дополнительных полей и функций. Этот план сосредоточен на породном add-on.
Подготовьте мод и зависимость
В примере руководства аддон оформлен отдельной структурой с каталогом версии игры, media и common. Файл mod.info задаёт ID, имя, описание, версии и зависимость. В руководстве дана строка require=CompanionDogs; она нужна, чтобы базовый Lua загрузился раньше файлов аддона. Поле versionMin относится к версии игры и не задаёт минимальную версию Companion Dogs. Укажите требуемую версию базового мода словами в описании аддона и проверяйте её во время загрузки.
Авторский пример version guard для Lua-файла (версию API нужно выставить по реально используемым вызовам):
local CD = CompanionDogs
if not (CD and CD.registerBreed and (CD.API_VERSION or 0) >= 3) then return end
Поместите guard в каждый Lua-файл и проверяйте именно API, который этому файлу нужен. Не создавайте глобальную заглушку вида CompanionDogs = CompanionDogs or {}: источник предупреждает, что она маскирует отсутствие базового мода. Отдельный файл, работающий с моделью, может требовать дополнительные функции и проверять их отдельно.
Модель и файлы
- Модель животного — собственный skinned .glb в media/models_X/Skinned/. Руководство требует полный комплект из 21 клипа Rac_*; отсутствующие клипы не наследуются и могут приводить к зависшей анимации.
- Источник называет ограничение менее 60 костей и identity у верхнего узла модели. Это требования руководства к описанной реализации; отдельно их не проверяли.
- Два дополнительных цикла хромоты Rac_WalkLimpFront и Rac_WalkLimpBack нужны только при limpAnim = true. Не включайте это поле без обоих клипов.
- Для тестирования прочих систем источник предлагает временно использовать базовую модель через CD.applyDogModel. Тогда животное внешне похоже на Caramelo; такая подмена не создаёт новый арт-ассет.
- Кроме модели нужны текстура тела и портрет для окна/питомника. Полный художественный конвейер в руководстве не рассматривается.
Минимальный файл регистрации находится в shared Lua и вызывает CD.registerBreed({...}). В примере руководства присутствуют key, engineBreed, typePrefix, nameKey, litter, xpMult, combatPower, lethalityCurve, canKill, canKnockdown, combatStressMult, panicThreshold, bagMult, sentinelMult, barkNoiseMult, alertModeLocked, loyaltyDecayMult, geneRange и spawns. Не копируйте числовые значения примера как универсальные настройки — это демонстрационная конфигурация Pug.
| Поле | Назначение по документации | Важное ограничение |
|---|---|---|
| key | Уникальный идентификатор породы | Сохраняется в мире; после релиза менять нельзя |
| typePrefix | Префикс мужского, женского и щенячьего animal type | Типы формируются как <prefix>male, <prefix>female, <prefix>pup; модель связана с этой системой |
| nameKey | Ключ перевода отображаемого имени | Должен присутствовать в локализациях |
| xpMult | Скорость развития scent, combat, obedience, hunt и herding | 1.0 — обычная скорость в описании API |
| combatPower и lethalityCurve | Сила укуса и масштабирование урона по Combat | Сочетаются с другими параметрами боя; значения требуют игрового теста |
| geneRange | Диапазоны strength, aggressiveness, resistance и stress | Четыре пары low/high внутри 0–1 |
| engineBreed | Внутреннее имя породы для движка и текстуры | Должно быть уникальным, если породы требуют отдельные текстуры |
| spawns | Описание шагов появления | Стабильный суффикс каждого шага хранится в сохранении |
В руководстве есть много необязательных полей — например canKill, canKnockdown, panicThreshold, bagMult, puppySize, sentinelMult, huntFetchLevel, diet и голоса. Некоторые поля относятся только к дополнительным способностям. Используйте таблицу полного API из установленной версии; не добавляйте поле, пока не знаете, как конкретная версия его читает.
Определения животного и скрипт модели
Зарегистрируйте стадии и три типа животного — щенка, самку и самца — в shared/Definitions/animal, привяжите породу и текстуру, стадии и геном. Для породы собаки руководство использует геном dog и помощники CD.applyDogModel и CD.applyDogBehaviour; имена species-neutral доступны в более новых версиях API. Animation set должен оставаться raccoon. Не задавайте mate: встроенное размножение движка обходит ограничения мода.
Определения частей для разделки обязательны для всех трёх типов: руководство использует CD.defineDogParts(typePrefix, engineBreed). Без них разделка может вызвать ошибку. Для собственного тела объявите модель и animationsMesh в media/scripts/ и включите keepMeshAnimations = true; иначе встроенные клипы модели не будут использоваться. Размещение и совместимость API проверьте по документации установленной версии.
Появление породы
Шаги появления можно указать в spawns породы либо зарегистрировать через CD.registerStraySpawns. Источник приводит поля шага id, class, chance, suffix и breed; необязательные gate и indoor задают дополнительное условие/процент вероятности появления внутри здания. Функция chance может читать sandbox-множитель в момент броска. Для своего типа здания предлагается CD.registerBuildingClass.
Не повторяйте занятые spawn suffix: это ключ сохранённого результата «здание уже проверено». Каждый суффикс должен быть уникальным между модами и оставаться неизменным. Руководство рекомендует учитывать CD.dogSpawnMultiplier() либо CD.strayChancePerHouse(), чтобы пользовательские настройки появления продолжали влиять на add-on. Правила классов зданий и конкретные имена действующих суффиксов проверьте в текущем руководстве/версии.
Переводы и совместимость сохранений
Поставляйте IG_UI.json в media/lua/shared/Translate/<LANG>/. В источнике указаны ключи имени породы IGUI_PD_Breed_<key>, описания IGUI_PD_BreedDesc_<key>, имени в интерфейсе игры IGUI_Breed_<engineBreed> и подписи каждого animal type. Все ключи нужны в каждом языке, который вы включили в пакет. Руководство отдельно предупреждает про знак процента в форматируемых строках и BOM в JSON.
Три значения автор описывает как записываемые в сохранение: key породы, typePrefix типов животного и suffix каждого шага появления. После выпуска не переименовывайте их: смена key может оставить уже приручённых животных без связанной породы; смена суффикса повторит броски появления в старых мирах. Удаление add-on из мира с живыми животными этого вида может привести к потере животных, поэтому предупредите пользователей на странице мода.
Проверка перед тестированием
- Убедитесь, что каждый Lua-файл имеет guard с нужным API и mod.info зависит от CompanionDogs.
- Проверьте уникальность key, engineBreed и spawn suffix, обязательные поля регистрации и переводы.
- При тесте откройте журнал: руководство говорит, что отклонённая регистрация может вернуть nil без остановки загрузки, но оставляет именованную запись.
- Проверьте появление животного, модель/анимации, щенка и разделку, если они входят в задачу.
- Протестируйте в сетевой игре: источник указывает, что запись mod data на клиенте может перезаписаться сервером; серверную логику размещайте на сервере или в серверных hooks.
- Перед выпуском проверьте API установленного базового мода, версии и стабильность идентификаторов.