Миграция Profession Framework на Build 42

Статические определения черт и профессий, runtime API, совместимость с B41 и порядок проверки.

Порт и руководство по миграции созданы Skizzo; прежняя версия Build 41 по-прежнему указывает Fenris_Wolf. Build 42 загружает пакет 42/ и оставляет корневой пакет B41. Мод может поставлять отдельные каталоги версий для поддержки обеих сборок.

Для B42 сначала регистрируют статические определения, до загрузки игровых скриптов. Profession Framework затем добавляет только поведение уже существующим определениям. Он не восстанавливает удалённые TraitFactory, ProfessionFactory или переопределения интерфейса создания персонажа.

Структура мода-потребителя

Структура пакета: 42/; mod.info; media/registries.lua; media/scripts/MyDefinitions.txt; media/lua/shared/MyBehavior.lua; media/lua/shared/Translate/EN/UI.json.

В 42/mod.info указывается идентификатор мода-фреймворка, не Steam Workshop ID.

name=My Build 42 Add-on id=MyAddon require=ProfessionFramework versionMin=42.20

1. Зарегистрируйте идентификаторы

42/media/registries.lua загружается до статических скриптов. Используйте канонические идентификаторы namespace:path; система ресурсов игры приводит их к нижнему регистру.

MyAddonRegistries = MyAddonRegistries or {} MyAddonRegistries.Survivalist = CharacterTrait.register("MyAddon:survivalist") MyAddonRegistries.Scout = CharacterProfession.register("MyAddon:scout")

2. Объявите статические определения

Данные экрана выбора задаются статическим скриптом, а не таблицей Lua. Минимальный пример определения черты и профессии:

module MyAddon { character_trait_definition MyAddon:survivalist { CharacterTrait = MyAddon:survivalist, UIName = UI_trait_MyAddon_Survivalist, UIDescription = UI_trait_MyAddon_SurvivalistDesc, Cost = 2, XPBoosts = Sneak=1, } character_profession_definition MyAddon:scout { CharacterProfession = MyAddon:scout, UIName = UI_prof_MyAddon_Scout, UIDescription = UI_profdesc_MyAddon_Scout, Cost = 0, IconPathName = profession_parkranger2, GrantedTraits = base:outdoorsman, XPBoosts = PlantScavenging=1;Trapping=1, } }

В статических определениях B42 используются GrantedTraits, GrantedRecipes, XPBoosts, MutuallyExclusiveTraits, стоимость очков, подписи, описания, иконки и доступность в мультиплеере. Переводы добавляют в media/lua/shared/Translate/EN/UI.json.

{ "UI_trait_MyAddon_Survivalist": "Survivalist", "UI_trait_MyAddon_SurvivalistDesc": "At home in the wilderness.", "UI_prof_MyAddon_Scout": "Scout", "UI_profdesc_MyAddon_Scout": "A practiced outdoor guide." }

3. Подключите поведение во время игры

Подключайте B42 API из shared Lua только после появления статических ID. Новый код должен явно вызывать attachTraitBehavior и attachProfessionBehavior.

require "ProfessionFramework/B42" ProfessionFramework.attachTraitBehavior("MyAddon:survivalist", { inventory = { ["Base.Hammer"] = 1 }, OnNewGame = function(player, square, traitId) -- Server / single-player only. `square` can be nil on a dedicated server. end, OnGameStart = function(traitId, player) -- Client presentation behavior only; do not grant items here. end, }) ProfessionFramework.attachProfessionBehavior("MyAddon:scout", { square = { ["Base.Hammer"] = 1 }, spawns = { ["Muldraugh, KY"] = { { position = "center" }, }, }, })

Начальные предметы в инвентаре и на земле выдаются авторитетно на сервере или в одиночной игре во время OnNewGame. AlwaysUseStartingKits по умолчанию true; задайте false до создания персонажа, чтобы применялся параметр песочницы StarterKit.

inventory кладёт экземпляры предмета в инвентарь, square — на стартовую клетку. Эти поля не экипируют оружие и не надевают одежду. Для предмета в руке или надетой одежды добавьте явное поведение OnNewGame и проверьте нужный режим. Декларативного auto-equip нет.

Не переносите поле clothing из Build 41 в таблицу поведения Build 42: оно не поддерживается. Поскольку поля проверяются как одна регистрация, неподдерживаемое поле может помешать подключить и корректный стартовый набор профессии.

Фреймворк проверяет ID поведения, количества предметов, структуру spawn и дублирующие подключения. addTrait и addProfession остаются предупреждающими алиасами совместимости только для поведения; они отклоняют статические поля B41 и не создают и не изменяют выбираемые определения.

Изменения B41 → B42

Шаблон B41	Замена B42.20
TraitFactory / ProfessionFactory	media/registries.lua и скрипты character_*_definition
Переопределения BaseGameCharacterDetails	Статические определения; без UI-переопределения фреймворка
Lua-поля name, description, cost, icon, xp, traits, recipes, exclude	UIName, UIDescription, Cost, IconPathName, XPBoosts, GrantedTraits, GrantedRecipes, MutuallyExclusiveTraits в статических скриптах
RemoveDefaultTraits / RemoveDefaultProfessions	Не поддерживаются; Build 42 сохраняет регистрацию vanilla-определений
clothing, experimental restricted / required	Не поддерживаются этим фреймворком; при необходимости нужна отдельная UI-система B42
removeInMP	Для новой черты используйте статическое DisabledInMultiplayer
requiresSleepEnabled	Общей точки расширения B42 нет; не полагайтесь на UI-патч B41

OnNewGame работает на сервере/в одиночной игре. OnGameStart выполняется на клиенте, в том числе для каждого локального игрока split-screen. Нельзя делать клиентский код авторитетным для инвентаря, черт, рецептов или опыта.

spawns добавляются из OnSpawnRegionsLoaded. В B42 таблицы используют path профессии (например scout), а не полный namespace. Одинаковые пути двух модов конфликтуют; фреймворк записывает конфликт в лог и не перезаписывает существующую таблицу.

Наследуемые черты профессий

Пакет сохраняет статические bridge-алиасы скрытых черт профессий B41 (Brave2, SpeedDemon2 и другие). При первом появлении персонажа сервер B42 преобразует поддерживаемый алиас в соответствующую черту base: и применяет её XP и рецепты. Это поддерживает старые данные зависимых модов без прежнего динамического factory.

Для новых определений B42 напрямую указывайте базовую черту:

GrantedTraits = base:brave,

Не используйте bridge-алиасы в новом контенте. У Lucky2 и Unlucky2 нет аналога в Build 42.20; ранее закомментированная Hypercondriac2 также не предоставляется. Поддерживаемые соответствия доступны через ProfessionFramework.LegacyTraitAliases и ProfessionFramework.LegacyTraitTargets.

Проверка и пробный запуск

Руководство предлагает запускать validator для установленной игры Build 42.20: .\tools\validate-b42.ps1 -GameDir 'C:\steam\steamapps\common\ProjectZomboid'. Он проверяет метаданные пакета, соответствие реестра и скриптов, legacy bridge, запрещённые API B41, fixture и (с GameDir) ссылки на vanilla traits/UI keys.

Проверка Lua-синтаксиса в репозитории выполняется командой: npx --yes luaparse --quiet --file .\42\media\lua\shared\ProfessionFramework\B42.lua. Игровой smoke test не проводился.

Описанный автором игровой smoke test: включить фреймворк и fixture, создать одиночного персонажа с чертой/профессией fixture, проверить статические подписи, очки и однократную выдачу предмета; затем повторить на выделенном сервере, чтобы проверить выдачу предметов на землю, когда аргумент square события OnNewGame равен nil.

Выбор руководства по версии

README проекта предупреждает: для Build 42.20+ используйте API статических определений и runtime-поведения из migration guide и consumer example. Старые примеры README относятся к legacy API Build 41; не применяйте их как инструкции для B42.