Кастомные рецепты Minecraft через datapack: пошаговый туториал (2026)

Свои крафты на сервере не требуют ни одного плагина. Ванильная система datapack закрывает shaped, shapeless, плавку, доменную печь, коптильню, костёр, кузнечный стол и каменотёс. Туториал админ-админу: структура папок, pack_format под 1.21.x, рабочие JSON, теги в качестве ингредиентов, отключение ванильных рецептов и типичные грабли.

Все примеры проверены на 1.21.x по состоянию на 2026 год. Vanilla, Paper, Spigot, Purpur, Fabric, Forge, NeoForge: формат datapack везде один и тот же. Серверное ядро просто читает одну и ту же папку.

Что такое datapack и зачем он на сервере

Datapack, это папка из JSON и mcfunction файлов, которую игра подхватывает сама. Тот же язык, на котором Mojang описывает ванильные рецепты, лут-таблицы, ачивки и теги. Чтобы 9 золотых блоков плюс яблоко превращались в зачарованное золотое яблоко, MMOItems не нужен.

Плюсы по сравнению с плагинами:

• работает на любом ядре (Vanilla, Spigot, Paper, Purpur, Fabric, Forge, NeoForge),
• работает в одиночке и на Realms,
• зависит от версии Minecraft, не от ядра,
• грузится горячо через /reload, без рестарта,
• не ест RAM, не тратит тик-бюджет.

Ограничения есть. Datapack не делает новых ID блоков, не добавляет своих типов предметов и не ловит произвольные события. Для настоящих модов нужен loader плюс ресурспак. Для рецептов datapack, это родной инструмент.

Структура datapack под 1.21

У каждого datapack корневая папка и два обязательных элемента.

my_recipes/
  pack.mcmeta
  data/
    mypack/
      recipe/
        super_apple.json
        aether_drill.json
        crushed_gold.json

Имя корня произвольное. Namespace под data/ ваш, он попадёт в ID рецепта mypack:super_apple. Не используйте minecraft как namespace для своих файлов: это перетирает ваниль и убивает совместимость.

Важная правка в 1.21: папка рецептов называется recipe в единственном числе. До 1.20.6 включительно путь был data/<ns>/recipes/. Если переносите старый пак, переименуйте папку первым делом, иначе игра тихо пропустит весь её контент. Похожая история с advancements (стало advancement), loot_tables (стало loot_table), tags/items (стало tags/item). Полная карта переименований лежит на minecraft.wiki/w/Data_pack.

pack.mcmeta

Минимальный валидный файл:

{
  "pack": {
    "pack_format": 48,
    "description": "My custom recipes"
  }
}

pack_format, это целое число, привязанное к версии Minecraft.

Версия Minecraft	datapack pack_format
1.20.5 / 1.20.6	41
1.21 / 1.21.1	48
1.21.2 / 1.21.3	57
1.21.4	61
1.21.5	71
1.21.6 / 1.21.7 / 1.21.8	80

Если число не совпадает с версией сервера, появляется предупреждение "made for a different version of Minecraft". Чаще всего рецепты всё равно работают, но значение лучше держать актуальным. Полная таблица версий: minecraft.wiki/w/Pack_format.

С 1.20.2 поддерживается supported_formats, чтобы пак официально покрывал диапазон версий:

{
  "pack": {
    "pack_format": 48,
    "supported_formats": {"min_inclusive": 48, "max_inclusive": 80},
    "description": "My recipes (1.21+)"
  }
}

Имена namespace и файлов под data/ ограничены символами [a-z0-9_.-]. Никаких пробелов и заглавных букв.

Куда класть datapack на сервере

В мирах сервера путь жёсткий:

<server>/world/datapacks/my_recipes/

Если миров несколько, копируйте в каждый или поставьте symlink. Bukkit и Paper иногда называют главный мир world независимо от level-name в server.properties, поэтому перепроверьте по level.dat.

После копирования заходим оператором:

/datapack list
/datapack enable "file/my_recipes"
/reload

/reload перечитывает все datapack без перезапуска сервера. Игроков не выкидывает. Команды и теги цепляются мгновенно. При ошибке в JSON сервер пишет конкретную строку в консоль и пропускает только этот рецепт; остальные продолжают работать.

На Realms и в одиночке пак кладётся в тот же world/datapacks/. У Aternos есть отдельная вкладка "Datapacks", туда грузится Zip с такой же структурой.

Типы рецептов в 1.21

Игра знает девять типов. Каждый, это отдельный JSON со своим набором полей.

Тип	значение type	Где крафтится	Ключевые поля
Shaped	minecraft:crafting_shaped	верстак	pattern, key, result, category
Shapeless	minecraft:crafting_shapeless	верстак	ingredients, result, category
Smelting	minecraft:smelting	печь	ingredient, result, experience, cookingtime
Blasting	minecraft:blasting	доменная печь	то же, cookingtime 100 по умолчанию
Smoking	minecraft:smoking	коптильня	то же, cookingtime 100
Campfire	minecraft:campfire_cooking	костёр	то же, cookingtime 600
Smithing transform	minecraft:smithing_transform	кузнечный стол	template, base, addition, result
Smithing trim	minecraft:smithing_trim	кузнечный стол	template, base, addition, pattern
Stonecutting	minecraft:stonecutting	каменотёс	ingredient, result, count

Префикс minecraft: опционален (это namespace по умолчанию), но я всегда дописываю его явно: явное лучше неявного.

Поле category влияет только на вкладку в книге рецептов: building, redstone, equipment, misc для крафтов, плюс food, blocks, misc для плавки. Поле необязательное.

Поле group склеивает несколько рецептов в один слот книги. Шесть рецептов деревянных лестниц делят "group": "wooden_stairs" и показываются единым пунктом.

Пример 1: shaped рецепт, золотое яблоко из 9 золотых блоков

В файл data/mypack/recipe/super_apple.json:

{
  "type": "minecraft:crafting_shaped",
  "category": "misc",
  "group": "golden_apple",
  "pattern": [
    "GGG",
    "GAG",
    "GGG"
  ],
  "key": {
    "G": {"item": "minecraft:gold_block"},
    "A": {"item": "minecraft:apple"}
  },
  "result": {
    "id": "minecraft:enchanted_golden_apple",
    "count": 1
  }
}

С 1.20.5 ключ результата называется id, не item. Это часть рефактора Item Components: каждый рецептный JSON использует новую схему начиная с pack_format 41.

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

Тот же рецепт с пустым центром:

"pattern": [
  "G G",
  " A ",
  "G G"
]

Это X-форма: четыре золотых блока по углам, яблоко в середине.

Пример 2: shapeless с тегами

Часто вы хотите принимать "любое бревно" или "любой саженец". Для этого есть item-теги. Кладём data/mypack/recipe/wood_dust.json:

{
  "type": "minecraft:crafting_shapeless",
  "category": "misc",
  "ingredients": [
    {"tag": "minecraft:logs"},
    {"tag": "minecraft:logs"},
    {"tag": "minecraft:logs"}
  ],
  "result": {
    "id": "minecraft:gunpowder",
    "count": 2
  }
}

Любые три бревна (mangrove, cherry, любая древесина 1.21) дают два пороха. У shapeless порядок в гриде неважен.

В одном слоте можно совместить tag и item массивом:

{"ingredients": [
  [{"item": "minecraft:diamond"}, {"item": "minecraft:emerald"}],
  {"tag": "minecraft:planks"}
]}

Читается как "алмаз или изумруд" в первом слоте плюс любые доски во втором.

Свои теги кладутся в data/<ns>/tags/item/my_logs.json:

{
  "values": [
    "minecraft:oak_log",
    "minecraft:spruce_log",
    "#minecraft:cherry_logs"
  ]
}

# означает "включить другой тег". Чистый паттерн: определите тег один раз и ссылайтесь на него из разных рецептов; при появлении нового дерева правится только файл тега.

Пример 3: плавка и варианты

Печь, доменная печь, коптильня и костёр делят набор полей, отличается только type. Кладём data/mypack/recipe/smelt_cobble_to_clay.json:

{
  "type": "minecraft:smelting",
  "category": "misc",
  "group": "clay_smelting",
  "ingredient": {"item": "minecraft:cobblestone"},
  "result": {"id": "minecraft:clay_ball"},
  "experience": 0.1,
  "cookingtime": 200
}

cookingtime считается в тиках (20 тиков = 1 секунда). По умолчанию у печи 200 (10 секунд). Доменная печь и коптильня вдвое быстрее, у них рецепты обычно стоят на 100. Костёр медленный, 600.

experience, это float. Игрок получает его при заборе предмета.

Чтобы тот же ингредиент работал во всех четырёх устройствах, пишутся четыре файла. Экономия: блок ingredient остаётся, меняются только type и cookingtime.

Пример 4: smithing для апгрейдов

Кузнечный стол в 1.21 имеет три слота: template, base, addition. smithing_transform создаёт новый предмет, smithing_trim накладывает на броню узор.

Простой пример: ванильный апгрейд до netherite_pickaxe как datapack-override.

{
  "type": "minecraft:smithing_transform",
  "template": {"item": "minecraft:netherite_upgrade_smithing_template"},
  "base": {"item": "minecraft:diamond_pickaxe"},
  "addition": {"item": "minecraft:netherite_ingot"},
  "result": {"id": "minecraft:netherite_pickaxe"}
}

Для условного "псевдо-незерита" из copper_block плюс diamond_pickaxe меняем template или addition.

Trim-вариант:

{
  "type": "minecraft:smithing_trim",
  "template": {"item": "minecraft:silence_armor_trim_smithing_template"},
  "base": {"tag": "minecraft:trimmable_armor"},
  "addition": {"tag": "minecraft:trim_materials"},
  "pattern": "minecraft:silence"
}

tag здесь объединяет слоты брони: любой ванильный шлем или нагрудник проходит проверку.

Пример 5: каменотёс

{
  "type": "minecraft:stonecutting",
  "ingredient": {"item": "minecraft:cobblestone"},
  "result": {"id": "minecraft:gravel"},
  "count": 4
}

Каменотёс всегда работает 1 к N: один блок на вход, N на выход. Ни pattern, ни key тут нет.

Свои имена и components в результате

С 1.20.5 ванильный формат рецептов поддерживает Item Components прямо в result. То есть игрок получает уже именованный, зачарованный предмет с описанием, без последующего /give.

Кастомная кирка "Aether Drill" с обложки:

{
  "type": "minecraft:crafting_shaped",
  "category": "equipment",
  "pattern": [
    "DDD",
    " S ",
    " S "
  ],
  "key": {
    "D": {"item": "minecraft:diamond"},
    "S": {"item": "minecraft:stick"}
  },
  "result": {
    "id": "minecraft:diamond_pickaxe",
    "count": 1,
    "components": {
      "minecraft:custom_name": "{\"text\":\"Aether Drill\",\"color\":\"aqua\",\"italic\":false}",
      "minecraft:lore": [
        "{\"text\":\"Forged in the void\",\"color\":\"gray\",\"italic\":true}"
      ],
      "minecraft:enchantments": {
        "levels": {
          "minecraft:efficiency": 5,
          "minecraft:unbreaking": 3
        }
      },
      "minecraft:rarity": "epic"
    }
  }
}

Текстовые компоненты приходят сериализованной JSON-строкой внутри значения. Это особенность формата компонентов: вложенный JSON хранится как строка.

Внимание: components в результате не делают ингредиент уникальным. Обычная алмазная кирка тоже скрафтит "Aether Drill". Если нужно, чтобы засчитывался только именованный вход, прописывайте components на ингредиенте плюс отключайте ванильный рецепт.

Отключение ванильных рецептов

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

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

data/minecraft/recipe/enchanting_table.json:

{
  "type": "minecraft:crafting_shaped",
  "pattern": [
    "###",
    "###",
    "###"
  ],
  "key": {
    "#": {"item": "minecraft:barrier"}
  },
  "result": {
    "id": "minecraft:air"
  }
}

Игроки не получают barrier-блоки в выживании, рецепт мёртв. С 1.21 есть ещё /recipe take @a minecraft:enchanting_table. Эта команда убирает рецепт только из книги; крафт в гриде продолжает работать. JSON-override остаётся базовым способом.

Альтернативно убирается соответствующее advancement, тогда рецепт не разблокируется автоматически. Но у уже разблокировавших игроков он остаётся.

Hot reload во время разработки

Стандартный цикл:

1. Сохранить JSON.
2. Alt-Tab в игру, /reload.
3. При ошибке всё в консоли. Открываем лог, чиним JSON.
4. Повторяем.

Полезные команды:

• /datapack list available: выключенные паки.
• /datapack list enabled: активные паки.
• /datapack disable "file/my_recipes": выключить.
• /recipe give @p mypack:super_apple: добавить рецепт в книгу игроку.
• /recipe take @a *: убрать все рецепты у всех (удобно для теста разблокировок).

/reload обновляет только содержимое datapack. server.properties, bukkit.yml, плагины и ядро требуют настоящего рестарта.

Reference: сравнение типов рецептов

Тип	Обязательные поля	Опциональные	Особенности
crafting_shaped	type, pattern, key, result	category, group	до 3x3, пробелы как пустые слоты
crafting_shapeless	type, ingredients, result	category, group	до 9 ингредиентов, любой порядок
smelting	type, ingredient, result	experience, cookingtime, category, group	по умолчанию 200 тиков
blasting	type, ingredient, result	experience, cookingtime	по умолчанию 100 тиков
smoking	type, ingredient, result	experience, cookingtime	по умолчанию 100 тиков, только пища
campfire_cooking	type, ingredient, result	experience, cookingtime	по умолчанию 600 тиков
smithing_transform	type, template, base, addition, result	нет	новый предмет на выходе
smithing_trim	type, template, base, addition, pattern	нет	накладывает узор, не меняет тип
stonecutting	type, ingredient, result	count, group	1 к N, без рисунка

Частые ошибки

Сервер пишет "Couldn't load data pack mypack". Три причины:

1. pack_format не совпадает с версией сервера. Сверьте по таблице выше.
2. JSON сломан синтаксически. Прогоните через jq или онлайн-валидатор.
3. В имени файла или папки запрещённые символы.

Рецепт не виден в книге. Игра показывает только разблокированные рецепты. Разблокировка завязана на advancement. Для кастомных рецептов автоматического advancement нет; в 1.21 пишите его сами в data/<ns>/advancement/recipes/<name>.json. Быстрый способ: после /reload один раз /recipe give @a *.

Крафт не срабатывает, хотя JSON загрузился. Проверьте:

• pattern максимум три строки по три символа.
• каждый ключ key встречается в pattern, и каждый непробельный символ из pattern определён в key.
• crafting_shapeless имеет максимум девять ингредиентов.
• ID предметов написаны корректно: minecraft:cobblestone, не Cobblestone.

Два рецепта с одинаковой формой. Если ваш shaped рецепт совпадает по pattern с ванильным, в книге побеждает тот, что загружен последним. Решение: отключить ванильный JSON-overrideом.

Рецепт работает в одиночке, но не на сервере. Чаще всего пак лежит не в той папке мира. У Bukkit и Paper отдельные миры для Нижнего и Энда (world_nether, world_the_end), но папка datapacks/ только в главном. Vanilla server тоже хранит datapack под world/datapacks/. Multiverse-Core может переименовать главный мир: смотрите level-name= в server.properties.

Совместимость и срок жизни

1.21-datapack не загрузится на 1.20.4 и наоборот. Формат Item Components сильно изменился в 1.20.5. Если поддерживаете несколько версий, держите две папки: mypack-1.20.4/ с pack_format: 26 и старым result (item вместо id, без components), и mypack-1.21/ с актуальной схемой.

При каждом апгрейде Minecraft проверяйте changelog Mojang на переименования путей. Происходит редко, но регулярно: 1.21 переименовала recipes в recipe и сломала все старые паки без миграции.

Закладки:

• minecraft.wiki/w/Recipe: полная спецификация.
• minecraft.wiki/w/Data_pack: обзор структуры.
• misode.github.io/recipe: визуальный генератор с автодополнением.
• minecraft.wiki/w/Pack_format: соответствие версий.

FAQ

Можно ли через datapack добавить новый предмет?

Нет. Datapack меняет рецепты, лут, теги, advancement и mcfunction. Новые типы ItemStack добавить нельзя. Для этого нужен мод (Fabric, Forge, NeoForge) или плагин Bukkit. Обходной путь: ванильный предмет с custom_model_data плюс ресурспак с альтернативной моделью. С точки зрения рецепта это всё равно ванильный предмет.

Нужно ли advancement на каждый рецепт?

Для работы нет. Без advancement рецепт всё равно срабатывает в гриде; игрок просто не видит его в книге. Если нужно автоматически разблокировать (например, при попадании ингредиента в инвентарь), пишется data/<ns>/advancement/recipes/<name>.json с триггером inventory_changed и наградой recipe.

Как требовать именованный ингредиент?

Через components на ингредиенте. Пример:

{"item": "minecraft:diamond", "components": {"minecraft:custom_name": "{\"text\":\"Magic Diamond\"}"}}

components на ингредиентах работает с 1.20.5+. До этого приходилось решать через advancement-предикат.

Лагает ли datapack сервер?

Сам recipe lookup не крутится в каждый тик, он срабатывает только при попытке крафта. Тик-лаги от datapack почти всегда идут от тяжёлых execute-циклов в mcfunction. Чистые рецепты бесплатны.

Можно ли разблокировать рецепты только конкретным игрокам?

Через advancement плюс tag-предикат. Игрокам ставится /tag @s add unlocked, advancement требует этот тег. Только помеченные видят рецепт в книге. Сам крафт в гриде заблокировать нельзя; кто собрал ингредиенты, тот скрафтит. Жёсткий запрет делается через scoreboard плюс /clear в mcfunction-цикле, что выходит за рамки чистого datapack-дизайна.

Как тестировать без релогина?

Хватит /reload. Даже если меняется pack.mcmeta, добавляется или убирается namespace. Реконнект нужен только при изменении ресурспака (текстуры, модели), не для datapack.

Кастомные рецепты через datapack, это случай, когда ваниль закрывает задачу полностью и плагин был бы лишней зависимостью. Формат JSON стабилен, документация полная, misode.github.io снимает 90 процентов рутины. Создаёте world/datapacks/, кидаете десяток своих рецептов, и сервер получает уникальный крафт-лэйаут без единой строки Java.