Настройка MegaBlock Survivors

Процесс настройки MegaBlock Survivors построен на управляемых Nightbreak пакетах контента с опциональной поддержкой моделей через FreeMinecraftModels.

Требования

Java 21
Сервер, совместимый с Paper/Spigot, на линии API 1.21.4

Опциональные интеграции:

FreeMinecraftModels — пользовательские модели мобов и оружия (мягкая зависимость)
LibsDisguises — мягкая зависимость для дополнительной визуальной поддержки

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

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

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

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

Голограмма таблицы рекордов (закреплённая в (4.5, 67, -14.5) в mbs_spawn) не появляется, а в лог пишется предупреждение.
Телепорт при входе (SpawnLobbyListener) отправляет входящих игроков в (0.5, 65, 0.5) в mbs_spawn с углом yaw 180 — обходится, если у игрока есть активный матч.
Разбор после матча возвращает игрока в mbs_spawn, если он существует.

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

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

Ключ	Тип	По умолчанию	Описание
`setupDone`	boolean	`false`	Отслеживает, завершено ли руководство по первоначальной настройке

Переводы

Все строки, видимые пользователю (сообщения в чате, заголовки диалогов, боссбары, текст голограмм, описания команд), загружаются из translations.yml. Операторы сервера могут локализовать или переоформить каждую строку, не трогая jar. Поддерживаемые возможности:

Простые цветовые коды с префиксом & и 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`	Append-only JSON-журнал каждого завершённого матча, записываемый при разборе матча.

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

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

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

Пакеты контента настраиваются через 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	Можно ли включать/выключать пакет

Настройка NPC

NPC (квестодатели и торговцы в лобби) настраиваются через YAML-файлы в npcs/. NPC возрождаются при загрузке чанков, чтобы пережить циклы выгрузки/загрузки чанков лобби. Правый клик по 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 для отрисовки; без него NPC всё равно появляется как базовая сущность в настроенной локации.

Поля YAML для NPC

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

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

Когда плагин обнаруживает изменение версии (сравнивая с version.txt), он уведомляет консоль и всех онлайн-операторов.

Требования​

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

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

Переводы​

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

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

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

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

Настройка NPC​

Поля YAML для NPC​

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