Разработка плагинов

Создание и тестирование

Откройте Creator / Workshop в главном меню либо менеджере карт/плагинов. Создайте карту, кампанию из двух уровней, плагин или урок с боссом и связанным плагином; редактируйте, сохраняйте, проверяйте и тестируйте офлайн. Рабочая область управляет локальными проектами, подписками, публикациями, поиском и задачами. Шаблон «Миссия королевства» создаёт кампанию kingdom из одного уровня с брифингом, заданиями, волнами и именным боссом. Импортируйте ZIP, файл карты или папку проекта кнопкой «Импортировать контент» или перетащив его в рабочую область; «Экспорт…» записывает ZIP или папку, а «Открыть папку» показывает файлы проекта. Оба спрашивают папку (снова предлагается последняя), уже занятое там имя становится name-2, name-3…, и ничего не пишется в содержимое, скачанное Steam. Каждый проект показан с превью, видом, версией, автором, отметкой, может ли эта игра его загрузить, и итогом последней проверки; в каждом списке есть поиск и фильтр по виду, пустой список объясняет почему, а сведения о выбранном проекте называют лицензию, версии игры, зависимости и папку. «Новый проект» перечисляет шаблоны с тем, что создаёт каждый, и показывает, куда ляжет проект, до того как что-то будет записано. Проверка предупреждает о крепостях, сундуках и расставленных боссах, до которых герои не могут дойти от замка (ошибка, если они нужны для победы), и ограничивает карту 64 крепостями, 256 сундуками и 32 расставленными боссами; двойной щелчок по проблеме на клетке карты открывает редактор в этом месте. Редактор местности и кампаний открывается в отдельном процессе, который загружает только зависимости проекта, поэтому установленное игроком содержимое в нём не появляется и не мешает; сохраняет он прямо в проект. Проверка, экспорт, пробная игра и публикация ждут, пока у проекта есть несохранённые изменения в редакторе, открытом из рабочей области: они используют сохранённые файлы. В редакторе плагинов фазы босса — это таблица (здоровье, с которого начинается каждая, её навыки), а у количества, предела и предупреждения навыка есть свои поля. Редактор плагинов вскоре после каждой правки сохраняет черновик несохранённой работы рядом с настройками и вне проекта; при повторном открытии проекта после сбоя предлагает его восстановить. В редакторе плагинов «Дублировать» копирует определение под новым ID, определение, на которое ссылается другое, нельзя удалить, пока эта ссылка есть, а «Копировать из игры…» добавляет полную копию актёра игры под его собственным ID, которая заменяет оригинал там, где он используется, не трогая файлы игры. У классов, врагов, зданий, твердынь и исследований есть форма свойств (диапазоны и рост характеристик, выпадающее золото, цены, класс, который нанимает здание, кого высылает твердыня, на что действует исследование): значения из определения-основы показаны серым, а значение вне границ игры или с неизвестным ID сразу отмечается; зависимости редактируются в таблице. Вкладка «Ресурсы» принимает перетащенные файлы, показывает видимую область каждого изображения рядом с ограничениями игры по размеру и памяти, показывает его как местность или значок, хранит строку источника и авторства, перечисляет и задаёт определения, которые его используют, переименовывает файл вместе со всеми ссылками, не удаляет используемый файл и перенаправляет поля, ссылающиеся на отсутствующий файл. Тестовая игра начинается со списка загруженного (каждый плагин в порядке загрузки с добавленными или заменёнными определениями и пропущенные плагины с причиной); рабочая область показывает тот же список и вносит пропущенное определение тестируемого плагина в список проблем, где открытие проблемы из таблицы определений ведёт к этому определению в редакторе плагинов.

Импорт папок/ZIP и редактируемые копии получают новые ID с изменением собственных ссылок пространства имён. Автор, источник и лицензия сохраняются, привязка обновления не наследуется. Оригиналы Steam доступны только для чтения. Проверяются относительные пути, лимиты, массивы и циклы триггеров. Пустая лицензия не разрешает распространение. При публикации копии проверка показывает её источник (проект, версию, автора и страницу оригинала) и условия автора оригинала, и отправить её можно только после того, как вы подтвердите, что сохраняете указание авторства и соблюдаете эти условия или, если у оригинала нет лицензии, что у вас есть разрешение автора; неуказанная лицензия всегда означает отсутствие разрешения делиться. Копия называет свой оригинал в подробностях и сообщает, когда оригинал из подписок обновился, а подсказки «Создание локальной редактируемой копии», «Экспорт…» и «Отписаться» объясняют, что делает каждая кнопка.

Публикация требует Steam: подготовьте страницу и превью, проверьте неизменяемый снимок файлов/хешей и явно отправьте. Задачи продолжаются после закрытия окна; подготовку можно отменить. После отправки или при неизвестном результате проверьте состояние либо синхронизируйте перед повтором. Привязки разделяются по аккаунту, приложению и проекту. Превью меньше 1 MiB; тесты используют имитацию Steam. Сначала опубликуйте необходимые плагины и подтвердите ID той же app при проверке карты/кампании. Мастер сохраняет тексты страницы для каждого языка и метаданные JSON, обрезает главное превью до квадрата и меняет порядок/удаляет до восьми дополнительных снимков. Опубликованные работы допускают обновление только страницы и зависимостей без повторной передачи содержимого; изображения включены в проверяемый снимок. Мастер может создать главное превью из самого проекта (местность карты с замком, твердынями и сундуками, первые уровни кампании, собственные изображения плагина, каждое с названием), показывает превью в том виде, в каком оно будет загружено, вместе с размером, рисует необязательную подпись внизу каждого снимка и сообщает, каких изображений из черновика больше нет. Три шага мастера (страница, зависимости и версии, проверка) проходятся кнопками «Назад» и «Далее» (Alt+←, Alt+→); проблема переводит к своему шагу и обводит поле, пока его не исправят, а проверка считает файлы, добавленные, изменённые и удалённые с прошлой публикации. Неудачная задача сообщает, с какой проблемой она столкнулась (права, соглашение мастерской, место, занятый Steam, таймаут, Steam не в сети, проверки, неизвестный результат, прерывание), что делать дальше, и код вроде WS-PERM-R15 без учётной записи, предмета и имён файлов. Выбор своего предмета в разделе «Мои публикации» показывает его видимость, версию, время создания и обновления, размер, связанный локальный проект и список того, что изменит обновление из этого проекта: поля страницы, файлы и обязательные предметы. При выборе предмета в обозревателе показываются его описание (или то, что Steam его не передал) и две отдельные части: что сообщает Steam (тип, обязательные предметы, разрешённые автором ветки игры, версия, записанная при публикации, время обновления, размер, оценки) и, после установки через Steam, что говорит собственный манифест предмета (проект и версия, может ли эта сборка запустить требуемые версии игры, нужные проекты, что он может изменить). То, чего Steam не передал, не додумывается. Предмет из подписок используется только после того, как Steam его установил и он прошёл проверку: манифест читается этой игрой, а каждый нужный проект установлен в допустимой версии и без циклических зависимостей (если один проект дают два предмета, берётся ваш собственный плагин, иначе самый старый предмет). Предмет, который Steam обновляет, используется в установленной версии. Вкладка «Подписки» показывает, на каком этапе каждый предмет из подписок (ждёт Steam, загружается с числом байт, ждёт проверки, доступен, не хватает нужного, или ошибка и её причина), а обозреватель показывает то же для выбранного предмета; загрузка, которую Steam не смог завершить, например из-за заполненного диска, не запрашивается снова, пока вы не нажмёте «Повторить загрузку». Перед загрузкой сохранения игра проверяет содержимое, с которым оно сделано: если использованный проект обновлён, выключен, удалён из подписок или непригоден, или включено другое содержимое, она называет каждый случай и после подтверждения загружает сохранение из сохранённой копии либо объясняет, почему загрузка невозможна (нет пригодной копии, обновление игры, другая учётная запись или приложение Steam, Steam не запущен), и как это исправить; файл сохранения и текущая игра остаются как были. «Сохранённое содержимое…» на вкладке «Подписки» показывает эти копии и зависящие от них сохранения, проверяет их и удаляет ненужные; копию, от которой зависит сохранение, можно удалить только после подтверждения с названиями сохранений, а копию запущенной игры — никогда. В подробностях предметов и проектов также указаны версия этой игры (не задана в сборке для разработки, и тогда содержимое, требующее определённой версии игры, не загружается) и её ветка Steam, а «Открыть страницу предмета» на вкладке «Подписки» показывает непригодный предмет; если Steam переключает игру на другую ветку во время игры, появляется уведомление, и ничего не перезапускается само. Метки страницы — это её тип и любые из Story, Challenge, Bosses, Classes, Enemies, Buildings, Research, Events, Languages, Art; шаг страницы показывает языки, для которых написаны страницы (для любого другого языка Steam показывается страница по умолчанию), а для уже опубликованного предмета «Взять страницу из Steam…» сравнивает страницу в Steam с черновиком по полям и берёт только отмеченные поля. Без Steam предметы из подписок не загружаются, а сохранённые копии не используются: и то и другое принадлежит учётной записи и приложению Steam (демо и полная версия — разные приложения со своими предметами, черновиками и профилями контента); сохранение, которому они нужны, сообщает об этом, а создание, проверка, тестовая игра, экспорт и импорт своих проектов работают без сети. Во время тестовой игры замеряются время тика, память и атлас спрайтов, а рабочая область добавляет их в отчёт с оценкой «нормально», «стоит последить» или «слишком тяжело» и подсказкой, что поможет; если загрузка не удалась из-за содержимого или квоты, объяснение называет ограничения Steam, а после успешной напоминает подписаться и проверить загрузку, потому что публикация этого не проверяет. Загрузка прерывается только после пяти минут без продвижения, а завершённые или отменённые задачи исчезают из списка через неделю; тестовые сеансы, которые не использует ни одна запущенная игра, удаляются при запуске новых, Enter на локальном проекте открывает его редактор, а эти окна помещаются на экран 1280 × 720 на любом языке.

Определения и зависимости

Плагины с версиями добавляют независимые классы, врагов, здания и опорные пункты на основе встроенных шаблонов, а также навыки, исследования, события, именованных боссов, ресурсы и языки. Новые ID имеют вид namespace:name; встроенный ID заменяет существующее содержимое. Основные файлы доступны только для чтения. Оформление меняет изображения персонажей или местности без изменения игровых значений. Здание игрока может нести эффект: один навык атаки, лечения, щита или состояния, который оно применяет с постоянным интервалом к врагам или героям в радиусе, начиная с заданного уровня. Пакет, у которого из возможностей только assets и languages, может содержать лишь скины и языки, а изображение или звук, которые игра не может использовать, оставляют на месте встроенные.

Общий манифест хранит ID проекта, автора, версию, совместимость, ресурсы и зависимости. Порядок загрузки детерминирован; отсутствующие, несовместимые или циклические зависимости блокируют загрузку. Старые форматы и порядок сохраняются. Профили показывают замены и применяются в следующей игре. Профили контента показывают выбранные плагины в порядке загрузки, у каждого — источник и версии: установленная, используемая запущенной игрой и выбранная на следующий раз; «Выше» и «Ниже» меняют порядок только там, где позволяют зависимости, и порядок действует при следующей загрузке в той же учётной записи и приложении Steam. До любых изменений профиль показывает, что применение включит или выключит, вместе с картами, кампаниями, плагинами и сохранениями, которым нужен выключаемый плагин; двойной щелчок по проблеме находит её плагин, карта или кампания может предложить нужные ей плагины, а предмет из подписок, которого здесь нет (например, копия вашего собственного плагина), объясняет почему.

Примеры

{"manifest_version":1,"format_version":1,"kind":"Plugin",
 "project_id":"sample:content","namespace":"sample","version":"1.0.0",
 "author":"Author","game_version":"*","entry_points":["plugin.json"],
 "assets":["preview.png"],"preview":"preview.png","languages":["en"],
 "capabilities":["dynamic_types","behavior_templates","bosses","assets"],
 "dependencies":[],"license":"","source":{}}

content-manifest.json / <map-stem>.manifest.json

{"id":"sample","name":"Example","version":"1.0.0",
 "content":{"enemies":"content/enemies.json","skills":"content/skills.json",
 "bosses":"content/bosses.json","languages":["lang/en.json"]}}

plugin.json

[{"id":"sample:slime","base":"SLIME","stats":{"hp":90}}]

[{"id":"sample:strike","template":"attack","cooldown":60,"radius":5,"power":10}]

[{"id":"sample:chief","enemy":"sample:slime","name":"Chief",
 "phases":[{"hp":1,"skills":[]},{"hp":0.5,"skills":["sample:strike"]}],"reward":100}]

{"bosses":[{"definition":"sample:chief","encounter":"bridge_chief","x":21,"y":16}],
 "victory":"defeat_boss","victory_target":"bridge_chief"}

{"project_id":"sample:content","version":">=1.0.0,<2.0.0","optional":false}

Ресурсы и ограничения

JSON	Ресурсы и ограничения
skills	attack, heal, shield, status, summon
adventurer_classes.skills	древо умений класса (пассивные умения): список {"id", "level", "effect", "requires": [ids]}, сколько угодно и по нескольку на уровень, либо прежняя таблица {"<уровень>": {"id", "effect"}}, читаемая как цепочка; id уникальны в классе, requires называет умения того же класса, без колец
adventurer_classes.active_skill, tree_skills	собственные активные умения класса, узлы того же древа: active_skill — ID первого (корень), tree_skills — до 12 ID тех, что растут из древа. Каждое — умение из skills (не summon), изучается на своём level, когда герой изучил все умения из requires (до 8 ID умений класса, пассивных или активных; у первого их нет), и каждое ждёт своё cooldown. Без active_skill класс сохраняет первое умение базового класса
buildings.effect	навык attack, heal, shield или status (не summon), применяется каждые 10–3600 тиков с уровня здания 1–3; состояния не складываются
research	stat_modifier
castle_branches	путь замка: id, playable, buildings (ID зданий, игры или самого плагина), effects и level3 (числа по именам эффектов, тем же, что у путей игры), specialities (ни одной либо две и больше {"id", "effects"}). Определение с ID встроенного пути заменяет его целиком; ID вида namespace:name добавляет путь, он идёт после путей игры и предлагается везде, где есть пути. Его тексты — языковые ключи branch_<id>, branch_<id>_desc, branch_<id>_price, branch_<id>_level3, branch_<id>_heroes и speciality_<id>_<speciality>. Королевство, чей путь больше не загружен, играет как не выбравшее пути, а сохранение помнит выбор
events	gold, enemy_wave, stat_buff
bosses	1–8 phases; optional stats of its own (hp, attack, defense); a name starting i18n: is a translation key
skins	tiles, adventurer_classes, enemies, buildings, enemy_buildings; только оформление
assets by kind	adventurer_classes, enemies: animation_sheet / sprite, sound; buildings: sprite, icon; enemy_buildings: sprite; skills: skill_effect; skins tiles: sprite (рисуется непрозрачным); скины персонажей: как у цели; остальное, а также layout вне персонажей, не используется и даёт предупреждение
plugin art and sounds	256 МиБ декодированных изображений (ширина × высота × 4) на все включённые пакеты, файл считается один раз, сверх этого остаётся встроенная графика; 64 МиБ звуков плагинов в памяти
capabilities: assets, languages only	только скины и языки; другие определения отклоняются
assets.animation_sheet	PNG: 24 columns × 5 rows
assets.sprite / icon / skill_effect	PNG; 8192 px/side, 16 million pixels
assets.sound	WAV; mono/stereo, ≤30 seconds
layout.anchor	[0–1, 0–1]
effect_frames	1–64
preview	<1 MiB
portable project	≤2048 files; ≤64 MiB total; ≤16 MiB/file
map	≤2048 tiles/side
campaign	≤127 карт уровней
spawn_enemies.action_params.count	1–32
spawn_enemies.action_params.march	castle / road
reveal.action_params.radius	1–40
post_bounty.action_params.reward	1–99999
post_bounty.action_params.deadline	0–6000 ticks
adventurer_classes.profile.explore_range	10–400
adventurer_classes.profile.retreat_hp	0.15–0.5
adventurer_classes.profile: explore / hunt / steal / flags.* / errands.*	0–3

{"id":"sample:grass","kind":"tiles","target":"GRASS",
 "assets":{"sprite":"assets/grass.png"}}

PLUGINS.md

Совместимость с версией игры

game_version задаёт требования к выпущенной версии запущенной игры. "*" принимается, в том числе для старых проектов. Конкретный диапазон принимается только тогда, когда сборка объявляет известную семантическую версию игры, которая ему соответствует; иначе проверка, загрузка и публикация отклоняются. В этом репозитории game.build_info.GAME_VERSION пока неизвестна: используйте "*", пока сборка выпуска не предоставит утверждённую версию. Поле version проекта и названия веток Steam не определяют версию игры.