Настройка MegaBlock Survivors

MegaBlock Survivors использует пакеты Nightbreak. Для игры необходимо установить FreeMinecraftModels: враги и оружие напрямую используют его классы моделей, хотя дескриптор объявляет зависимость мягкой.

Требования

• Java 21
• Сервер, совместимый с вашей сборкой MegaBlock Survivors. Дескриптор объявляет API 1.21.4, но текущий исходный код компилируется со Spigot 26.2; сам дескриптор не определяет список поддерживаемых версий.
• FreeMinecraftModels и необходимые для игры пакеты моделей/контента
• WorldEdit для схематиков башен, стен и деревьев, которые вставляет генерация мира. Плагин напрямую вызывает API WorldEdit, но дескриптор не объявляет его зависимостью
• Рабочая встроенная поддержка minecraft:dialog для экранов выбора и наград

Необязательная интеграция: LibsDisguises для дополнительных визуальных эффектов.

Что создаёт MegaBlock Survivors

При запуске MegaBlock Survivors инициализирует или использует следующие пути внутри plugins/MegaBlockSurvivors/:

plugins/MegaBlockSurvivors/config.yml
plugins/MegaBlockSurvivors/translations.yml
plugins/MegaBlockSurvivors/content_packages/
plugins/MegaBlockSurvivors/content_markers/
plugins/MegaBlockSurvivors/imports/
plugins/MegaBlockSurvivors/schematics/
plugins/MegaBlockSurvivors/worlds/
plugins/MegaBlockSurvivors/npcs/
plugins/MegaBlockSurvivors/leaderboard.yml
plugins/MegaBlockSurvivors/meta_progression.yml
plugins/MegaBlockSurvivors/stats-dump.log
plugins/MegaBlockSurvivors/version.txt
plugins/MegaBlockSurvivors/nightbreak-changelogs.yml

nightbreak-changelogs.yml хранит общее состояние прочтения заметок о выпусках, которое использует /mbschangelog (см. Команды).

Плагин также загружает созданный оператором мир лобби mbs_spawn, если его папка существует на диске, а сам мир ещё не загружен. Установите лобби до запуска плагина. Если лобби недоступно:

• Голограмма таблицы рекордов в точке (4.5, 67, -14.5) мира mbs_spawn не создаётся; в журнал записывается информационное сообщение.
• Телепортация в лобби при входе ничего не делает. Если лобби загружено, плагин пытается отправить игрока в (0.5, 65, 0.5) с yaw 180, когда у него нет записи о матче или название текущего мира начинается с megablocksurvivors_. Наличие активного матча само по себе не отменяет это условие.
• При завершении матча вместо лобби используется позиция игрока до матча.

Конфигурация

config.yml содержит:

Ключ	Тип	По умолчанию	Описание
setupDone	boolean	false	Отслеживает, завершено ли руководство по первоначальной настройке
preGenerateWorldCache	boolean	false	Предварительно генерирует игровые миры survivor во время запуска. Оставьте false, чтобы загрузка сервера оставалась лёгкой; миры всё равно генерируются по требованию, когда они нужны матчу
nightbreak.autoDownloadPluginUpdates	boolean	false	Добавляется встроенной библиотекой MagmaCore после запуска. При true доступное обновление плагина автоматически загружается через несколько минут после запуска. Для автоматической загрузки плагина нужны действительный токен аккаунта Nightbreak и активное членство поддерживающего
nightbreak.applyPluginUpdatesWithoutRestart	string	never	Добавляется MagmaCore. never ждёт следующего перезапуска, when-empty применяет загруженное обновление, как только на сервере не останется игроков, а immediately — сразу же. Применение обновления перезагружает MegaBlock Survivors и завершает активные матчи. /mbs applypluginupdate применяет ожидающее обновление вручную

О том, как общие настройки обновлений работают во всех плагинах Nightbreak, см. Автоматические обновления.

Переводы

Многие игровые сообщения, диалоги, полосы боссов и строки голограмм используют translations.yml. Часть сообщений пакетов контента, описаний общих команд и текста рейтинга остаётся жёстко заданной на английском. Поддерживаются следующие возможности перевода:

• Простые цветовые коды с префиксом & и hex-экранирование &#RRGGBB.
• Теги градиентов MagmaCore вида <gradient:#FF0000:#00FF00>text</gradient>.
• Токены {placeholder}, которые плагин подставляет во время выполнения.
• Отсутствующие ключи отображаются как видимый маркер [translations: key.name], чтобы незаданные записи было легко заметить в игре.

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

Постоянные данные игрока

Файл	Назначение
leaderboard.yml	Записи таблицы рекордов по корзинам (6 секций: 2 режима × 3 сложности), не более 100 записей на корзину.
meta_progression.yml	Баланс Soul Echo и уровни треков улучшений по каждому игроку. Ключом служит UUID игрока.
stats-dump.log	Журнал сводок матчей в формате JSON-lines, дописываемый при завершении матча. /mbs dump очищает общий файл до поиска текущего или последнего забега вызывающего игрока. Даже если сводки нет, прежний журнал уже удалён.

Папки контента

Папка	Назначение
imports/	Место для скачанных или вручную помещённых архивов контента. Обрабатывается импортёром MagmaCore при запуске и по /mbs reload.
schematics/	Схемы структур, используемые генерацией мира. Файлы называются Level<1-3>_<Name>.schem — Tower, Wall / Wall1 / Wall2 и Tree1..Tree5 (Мир 1 и Мир 3 поставляются с 4 вариантами деревьев, Мир 2 — с 5). Арена финального босса схем не использует.
worlds/	Папки миров, устанавливаемые пакетами контента.
content_packages/	YAML-определения по каждому пакету (см. ниже).
content_markers/	Маркерные файлы, используемые для определения того, установлен ли пакет.

Предупреждение о первой настройке

Когда setupDone имеет значение false, плагин при входе показывает предупреждение о первой настройке игрокам с разрешением megablocksurvivors.*. Уведомление настроено (через NightbreakFirstTimeSetupSpec) только с командой настройки, поэтому оно направляет игроков к /mbs setup (браузер контента), а не к шагу инициализации/загрузки. /mbs initialize в этой сборке не зарегистрирована; /mbs downloadall зарегистрирована, но скачивает только jar плагина, поскольку пакеты контента отключены (см. страницу Команды) — используйте вместо неё /mbs setup.

Открытие браузера контента не устанавливает setupDone. Меню, записывающее этот флаг, доступно только через незарегистрированный обработчик initialize. Завершив и проверив настройку, задайте setupDone: true в config.yml и перезагрузите плагин, чтобы отключить напоминание.

Рекомендуемый порядок первой настройки

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

1. Установите MegaBlock Survivors и запустите сервер один раз. Файлы переводов и конфигурации создаются при первом запуске.
2. Привяжите свой аккаунт Nightbreak с помощью /nightbreaklogin <token>.
3. Выполните /mbs setup, откройте браузер контента Nightbreak и установите необходимые пакеты. Убедитесь, что FreeMinecraftModels загрузил их модели: статус установки пакета проверяет только отслеживаемые пути.
4. После ручного импорта или изменения конфигурации пакетов выполните /mbs reload. Это перезапускает MegaBlock Survivors и завершает активные матчи. Если при этом импортируются модели и FreeMinecraftModels включён, контент FMM также перезагружается. Для файлов, изменённых или скопированных непосредственно в папки FMM, используйте собственную команду перезагрузки FMM.

/nightbreaklogin <token> предоставляется общим потоком аккаунтов Nightbreak/MagmaCore, а не файлом plugin.yml плагина MegaBlock Survivors.

Пакеты контента

Пакеты контента настраиваются через YAML-файлы в папке content_packages/. Каждый пакет может определять:

Поле	Тип	Описание
isEnabled	boolean	Сохраняемые метаданные; текущая проверка установки опирается на наличие ресурсов и не использует поле как переключатель игрового контента
name	string	Отображаемое имя пакета
description	string list	Строки описания
downloadLink	string	URL для ручного скачивания
version	integer	Номер версии пакета
nightbreakSlug	string	Слаг контента Nightbreak для автоматических загрузок
schematicFiles	string list	Файлы схем, включённые в пакет
worldFolders	string list	Включённые папки миров
worldContainerFolders	string list	Включённые папки контейнеров миров
modelFolders	string list	Папки моделей для FreeMinecraftModels
markerFileName	string	Маркерный файл для определения, установлен ли пакет
category	enum	FREE, PREMIUM или RESOURCES
toggleable	boolean	По умолчанию false. Текущий обработчик удаления всегда выводит инструкции по ручному удалению; этот флаг не даёт рабочего переключателя отключения

Пакет считается установленным, если отслеживается хотя бы один ресурс и все отслеживаемые ресурсы присутствуют. Проверяются пути, а не содержимое файлов или готовность моделей; папка модели в каталоге отключённых моделей FreeMinecraftModels тоже считается присутствующей. Неполный набор ресурсов даёт статус частичной установки. Нажатие на установленный актуальный пакет выводит инструкции по ручному удалению; изменение одного isEnabled не отключает импортированные игровые ресурсы.

Настройка NPC

NPC настраиваются через YAML-файлы в npcs/. Зарегистрированные NPC создаются заново при повторной загрузке их чанка. Если мир был недоступен при инициализации, загрузите его и перезагрузите MegaBlock Survivors для регистрации NPC. Правый клик запускает настроенную interactionCommand от имени игрока и с его разрешениями.

С плагином поставляются два NPC, которые автоматически появляются в mbs_spawn, когда этот мир загружен:

NPC	Локация по умолчанию	Маскировка	Команда взаимодействия
Match Starter	mbs_spawn, 0, 67, -15	VILLAGER	mbs start
Meta Progression	mbs_spawn, -9, 66, -13	PIGLIN	mbs meta

Любого из них можно отключить, переместить или перенастроить, изменив соответствующий YAML в npcs/ и перезагрузив плагин. С LibsDisguises используется сущность жителя с настроенной маскировкой. Без него плагин пробует указанный тип сущности Bukkit и возвращается к жителю, если тип не является живой сущностью, которую можно создать.

Поля YAML для NPC

Поле	Тип	Описание
isEnabled	boolean	Появляется ли NPC
name	string	Внутреннее имя
location	string	Формат world,x,y,z или world,x,y,z,yaw,pitch
disguise	string	Тип сущности LibsDisguises (опционально)
interactionCommand	string	Команда, выполняемая при правом клике игрока по NPC
nameTag	string	Видимое пользовательское имя сущности NPC (допустимы цветовые коды)

Уведомления об обновлении версии

Если текущая версия новее сохранённой в version.txt, плагин уведомляет консоль и операторов онлайн. Первый запуск без сохранённой версии, неизменная версия и понижение версии не вызывают это уведомление об обновлении.