Датапаки Minecraft: установка, порядок загрузки и отладка

Датапак - это папка с JSON-файлами и скриптами .mcfunction, которую игра загружает так, будто она часть самой игры. Он может менять рецепты, добычу, достижения, генерацию мира и игровые правила, работает целиком на сервере, так что никому ничего устанавливать не нужно, и одинаково работает и на ванили, и на Paper. Положите его в world/datapacks/, выполните /datapack list, и если его там нет, то в девяноста случаях из ста внутри архива лишняя папка. Остальная часть статьи - про оставшиеся десять.

Что датапак умеет и чего не умеет#

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

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

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

У последней строки есть оговорка. Поскольку датапак работает на стороне сервера, его эффекты доходят до всех игроков, в том числе до игроков Bedrock, приходящих через Geyser. Всё, что зависит от парного пакета ресурсов ради внешнего вида, будет выглядеть для них неправильно, а часто и для игроков Java тоже, если вы не раздаёте и пакет ресурсов. Если вы вообще сравниваете датапаки с плагинами, то в статье Paper, Fabric или ваниль разобрано, какое серверное ПО что позволяет.

Где датапаки лежат на сервере#

Путь один: world/datapacks/, где world - то, что указано в level-name в server.properties. Каждый пак - это либо папка, либо .zip, и оба варианта ведут себя одинаково.

world/  level.dat  datapacks/    house-rules/      pack.mcmeta      data/    vt-multiplayer-sleep.zip

Здесь удивляют две вещи.

Во-первых, на Paper и Spigot незер и энд лежат в отдельных каталогах - world_nether и world_the_end, - но датапаки всё равно загружаются только из папки основного мира. Пак в world_nether/datapacks/ не делает ничего. Паки загружаются один раз на весь сервер и действуют во всех измерениях.

Во-вторых, в zip файл pack.mcmeta должен лежать на верхнем уровне архива. Если выбрать папку в проводнике Windows и сжать её, в архиве окажется одна папка, внутри которой лежит pack.mcmeta, и сервер её проигнорирует. Выделите содержимое - pack.mcmeta и data - и сожмите его. Та же ловушка встречается в обратную сторону, когда файловый менеджер панели распаковывает архивы на месте: распакуйте правильно собранный zip пака, и в datapacks/ окажутся россыпью файлы, а не папка пака. Загрузите zip и оставьте его сжатым либо распакуйте в отдельную папку. Данные для подключения при любом из способов есть в статье SFTP и файловый менеджер.

pack.mcmeta, pack_format и переименование в 1.21#

Каждому паку нужен ровно один pack.mcmeta в корне:

{  "pack": {    "pack_format": 48,    "description": "House rules"  }}

pack_format - это номер версии самого формата датапаков, и он меняется всякий раз, когда игра меняет форму файлов. Значения, которые стоит запомнить:

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

{  "pack": {    "pack_format": 48,    "supported_formats": { "min_inclusive": 41, "max_inclusive": 57 },    "description": "House rules"  }}

Неверный pack_format не всегда фатален - на деле важно, лежат ли файлы внутри в той структуре, которую ожидает эта версия, - но сервер помечает пак как несовместимый, и это первое, что нужно проверить, когда пак загружается и ничего не делает.

Изменение структуры, которое ломает больше всего старых паков, пришло в 1.21: каталоги внутри data/<namespace>/ из множественного числа стали единственным.

Сам tags/ сохранил имя, а папка внутри него - нет. Пак, написанный для 1.20 и положенный на сервер 1.21, обычно загружается без ошибок и тихо ничего не делает, потому что сервер ищет в function/ и находит пустой реестр. Если заведомо хороший пак не даёт эффекта и не пишет ничего в лог, прежде всего проверьте названия папок.

Пространства имён - вторая половина пути. data/minecraft/... переопределяет собственные файлы игры - именно так пак делает так, чтобы с гравия всегда выпадал кремень: он поставляет собственный data/minecraft/loot_table/blocks/gravel.json. data/yourname/... определяет новое. Пространства имён и имена файлов должны быть в нижнем регистре и содержать только буквы, цифры, подчёркивание, точку и дефис.

Включение, порядок и перезагрузка#

Паки, найденные в папке при загрузке мира, при первой загрузке включаются автоматически; после этого список включённых и их порядок хранятся в level.dat. Управляйте им из консоли:

$ datapack list$ datapack list available$ datapack enable "file/house-rules" last$ datapack disable "file/vt-multiplayer-sleep.zip"

Имя - это file/ плюс имя папки или zip в точности так, как оно записано на диске, и из-за косой черты его нужно брать в кавычки. У enable есть необязательная позиция: first, last, before <other> или after <other>.

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

Чтобы применить изменение без перезапуска, выполните reload, но следите, какая именно перезагрузка вам достанется. На Paper и Spigot обычный /reload - это перезагрузка плагинов Bukkit, известный способ сломать работающий сервер. Ванильная команда пишется с пространством имён:

$ minecraft:reload

Она пересобирает рецепты, таблицы добычи, достижения, теги и функции и заново запускает всё из тега #minecraft:load. Она не перегенерирует ландшафт и не отменяет ничего из того, что функция уже сделала.

Ещё один полезный параметр находится в server.properties:

initial-enabled-packs=vanillainitial-disabled-packs=

Они определяют, с какими паками стартует совершенно новый мир, и именно так на выделенном сервере включают экспериментальные пакеты функций самой игры, ведь экрана создания мира, где можно поставить галочку, там нет. Названия этих пакетов функций меняются в каждом релизе, так что берите их из примечаний к релизу. Всё остальное в этом файле разобрано в статье server.properties простыми словами.

Vanilla Tweaks и другие готовые паки#

Vanilla Tweaks - набор, с которого начинает большинство серверов. Вы выбираете на сайте версию игры, отмечаете нужные паки и скачиваете один zip. Внешний zip - это контейнер: распакуйте его, и получите по одному zip на каждый пак, и именно эти внутренние zip кладутся в datapacks/. Загрузка внешнего zip - вторая по частоте причина того, что установка Vanilla Tweaks ничего не делает.

Те, что оправдывают своё место на мультиплеерном сервере:

• Graves, который складывает инвентарь игрока в могилу, откуда его можно забрать, вместо того чтобы разбрасывать. Проверьте его, прежде чем полагаться: он плохо взаимодействует с keepInventory и с любым плагином, который тоже занимается смертью.
• More mob heads, double shulker shells и fast leaf decay - небольшие улучшения, с которыми никто не спорит.
• Паки против грифинга для криперов и эндерменов, которые поддерживают порядок в мире без плагина защиты.
• Coordinates HUD, который выводит координаты в боковую панель таблицы счёта для игроков, не видящих F3.
• Armour statues - редактор стоек для брони, самый востребованный строительный инструмент.

Часть старых любимцев теперь избыточна. Сон в мультиплеере - это игровое правило: playersSleepingPercentage по умолчанию равно 100, а если поставить 30, то ночь могут пропустить трети игроков. Проверьте, не делает ли игра это уже сама, прежде чем добавлять пак, который делает то же самое.

Vanilla Tweaks публикует и пакеты ресурсов с такими же названиями, и они клиентские. Если нужно, чтобы они были у каждого игрока, это resource-pack и resource-pack-sha1 в server.properties, а это уже другая задача - см. MOTD, иконка и пакеты ресурсов. Большой каталог датапаков есть и на Modrinth. Установщика в один клик для всего этого нет: каждый пак - это файл, который вы загружаете.

Пишем и отлаживаем свои#

Самый маленький полезный пак состоит из четырёх файлов. Функция загрузки для настройки, функция тика, защищённая таймером, чтобы не делать настоящую работу двадцать раз в секунду, и два тега, которые их запускают.

scoreboard objectives add hr.timer dummytellraw @a {"text":"House rules loaded","color":"gray"}

scoreboard players add #t hr.timer 1execute if score #t hr.timer matches 20.. run function houserules:second

scoreboard players set #t hr.timer 0execute as @a[nbt={OnGround:1b}] at @s run particle happy_villager ~ ~ ~

{  "values": ["houserules:tick"]}

Парный data/minecraft/tags/function/load.json, указывающий на houserules:load, завершает набор. Выполните /minecraft:reload и следите за консолью.

Когда что-то не работает, пройдите этот список по порядку:

1. Показывает ли /datapack list пак как включённый? Если его нет в списке совсем, дело в структуре zip или в не той папке мира.
2. Пишет ли консоль ошибку при перезагрузке? Ошибки разбора называют файл, а обычно ещё строку и символ.
3. Запустите функцию вручную: /function houserules:load. Если вручную работает, а автоматически нет, неверен файл тега - не та папка, не то пространство имён или опечатка в пути к функции.
4. Проверьте расширение файла. Windows по умолчанию скрывает известные расширения, так что файл, который вы считаете tick.mcfunction, часто оказывается tick.mcfunction.txt.
5. Проверьте JSON на висячие запятые. Парсер игры строгий, и висячая запятая убивает весь файл.

Если логика должна реагировать на происходящее, стандартный приём - достижение с триггером, функция-награда и отзыв достижения в конце этой функции, чтобы оно могло сработать снова. Это неуклюже по сравнению со слушателем плагина, но покрывает большую часть того, что нужно людям: игрок убил моба, создал предмет, вошёл в биом или что-то подобрал. Синтаксис селекторов и execute, из которого строятся такие функции, есть в статье шпаргалка по командам сервера Minecraft.

Два ограничения, которые нужно знать. function-permission-level в server.properties по умолчанию равен 2, так что функции не могут выполнять команды, требующие уровня 3 или 4, такие как /ban или /op. И maxCommandChainLength - игровое правило со значением по умолчанию 65536 - ограничивает, сколько команд может выполнить одна цепочка, прежде чем игра её остановит; это страховка, которая не даёт зациклившейся рекурсивной функции утащить за собой сервер.

Во что обходится плохой датапак и как это увидеть#

Всё, что делает датапак, происходит в основном потоке сервера, внутри тика. Функция в #minecraft:tick выполняется двадцать раз в секунду вечно, и если она начинается с execute as @e, то обходит каждую загруженную сущность в каждом загруженном чанке двадцать раз в секунду, изменилось что-нибудь или нет.

Способы исправить те же, что и в любой проблеме бюджета тика:

• Используйте счётчик на таблице счёта, чтобы дорогая часть выполнялась раз в секунду или раз в пять, а не каждый тик.
• Предпочитайте @a вместо @e, а когда нужны сущности, сужайте селектор: type=, distance=, tag=, limit=. Один только фильтр type= нередко сокращает работу на два порядка.
• Ставьте execute if перед всем дорогим, а не делайте работу и не выбрасывайте результат.
• Будьте очень осторожны с fill, clone и forceload. Пак, принудительно загружающий чанки, заставляет их тикать вечно, а это постоянные затраты ради временной возможности.

Чтобы измерить, собственный профилировщик ванили здесь лучше spark, потому что он относит время к отдельным функциям по именам:

$ minecraft:debug start$ minecraft:debug stop

Он записывает отчёт в папку debug сервера с разбивкой по секциям, на что ушло время тика, в том числе на функции. spark скажет, что менеджер функций дорогой; ванильный отчёт скажет, какая именно функция. Для всего остального - плагины, сущности, загрузка чанков, сборка мусора - используйте spark, как описано в статье диагностика лагов Minecraft через spark.

Удаление пака и обновление версии#

Отключение пака, который добавлял только рецепты, достижения, таблицы добычи или функции, безопасно. Игроки сохраняют предметы, которые у них уже есть, рецепты исчезают из книги, и ничего в мире не портится.

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

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

При обновлении версии нужно пройтись по каждому паку. Проверьте, что для целевой версии есть сборка, обновите pack_format и переименуйте каталоги, если пересекаете 1.21. Делайте это на копии мира, а не на живом. Более широкая последовательность описана в статье обновление версий Minecraft, а честный совет прежний: делайте бэкап до включения пака, а не после того, как он что-то сломал. В игровые тарифы RE:NODE входят два слота бэкапов, по требованию или по расписанию, а восстановление - одна кнопка, так что оправданий проверять пак на единственной копии мира нет.

FAQ#

Нужно ли игрокам что-то устанавливать для датапака?

Нет. Датапаки работают на стороне сервера и загружаются до того, как кто-либо подключится. Единственное исключение - внешний вид: если пак опирается на собственные текстуры или модели, они берутся из пакета ресурсов, а это отдельный клиентский файл.

Почему мой пак не появляется в /datapack list?

Почти всегда виноват архив. pack.mcmeta должен лежать на верхнем уровне zip, а не внутри папки-обёртки. Затем проверьте, что вы положили пак в папку основного мира, а не в world_nether, и что level-name в server.properties указывает туда, куда вы думаете.

Работают ли датапаки на Paper?

Полностью. Paper загружает их точно так же, как ваниль. Единственная ловушка, характерная для Paper, - /reload, который перезагружает плагины, а не датапаки; используйте /minecraft:reload.

Может ли датапак заменить плагин?

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

Будут ли мои датапаки работать после обновления Minecraft?

Иногда. Минорные обновления обычно лишь повышают pack_format. Переименование каталогов из множественного числа в единственное в 1.21 сломало большинство старых паков начисто, а новые реестры, управляемые данными, появляются регулярно. Проверяйте каждый пак на копии мира, прежде чем обновлять живой сервер.

Сколько датапаков - это слишком много?

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