Własne receptury Minecraft przez datapack: tutorial krok po kroku (2026)

Własne receptury craftingu na serwerze Minecraft nie wymagają ani jednego pluginu. Vanilla datapack pokrywa shaped, shapeless, smelting, blasting, smoking, ognisko, smithing i stonecutter. Ten poradnik jest pisany od admina dla admina: struktura katalogów, pack_format dla 1.21.x, pełne przykłady JSON, tagi przedmiotów jako składniki, wyłączanie waniliowych receptur i typowe problemy.

Wszystko sprawdzone na 1.21.x, stan na 2026 rok. Vanilla, Paper, Spigot, Purpur, Fabric, Forge, NeoForge: format datapacka jest taki sam, rdzeń serwera ładuje ten sam folder.

Czym jest datapack i gdzie siedzi w stosie

Datapack to katalog plików JSON i mcfunction, który ładuje sama gra. Używa tego samego języka definicji, jakim Mojang opisuje wewnętrznie waniliowe receptury, tabele lootu, advancementy i tagi. Do "9 bloków złota plus jabłko daje zaczarowane złote jabłko" nie potrzebujesz MMOItems.

Przewagi nad pluginem:

• działa na każdej implementacji serwera (Vanilla, Spigot, Paper, Purpur, Fabric, Forge, NeoForge),
• działa w singleplayerze i na Realms,
• jest powiązany z wersją Minecrafta, nie z rdzeniem serwera,
• przeładowuje się gorąco przez /reload, bez restartu,
• praktycznie nie zajmuje RAM, koszt tickowy zerowy.

Limity są. Datapack nie doda nowych ID bloków, nowych typów przedmiotów ani nie złapie dowolnych eventów. Do prawdziwego moddingu potrzebujesz loadera i resource packa. Ale do receptur datapack jest narzędziem właściwym.

Struktura datapacka dla 1.21

Każdy datapack ma jeden katalog główny i dwa obowiązkowe elementy.

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

Nazwa katalogu głównego jest twoja. Namespace pod data/ też jest twój i pojawi się później w ID receptury, np. mypack:super_apple. Nie używaj minecraft jako namespace dla własnych treści: nadpisuje waniliowe i psuje kompatybilność.

Ważna zmiana w 1.21: katalog receptur nazywa się teraz recipe (liczba pojedyncza). Do 1.20.6 włącznie ścieżka brzmiała data/<ns>/recipes/. Jeżeli portujesz stary pack, przemianuj folder, inaczej gra po cichu zignoruje wszystkie pliki JSON. To samo spotkało advancements (teraz advancement), loot_tables (teraz loot_table), tags/items (teraz tags/item). Pełna lista zmian jest na minecraft.wiki/w/Data_pack.

pack.mcmeta

Minimalny poprawny plik:

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

pack_format to liczba całkowita związana z wersją Minecrafta.

Wersja 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

Jeśli liczba nie zgadza się z wersją serwera, pojawi się ostrzeżenie "made for a different version of Minecraft". Najczęściej receptury nadal działają, ale lepiej trzymać aktualny numer. Pełną tabelę pack_format prowadzi minecraft.wiki/w/Pack_format.

Od 1.20.2 można rozszerzyć pack_format o supported_formats, żeby jeden pack oficjalnie obsługiwał kilka wersji:

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

Nazwy namespace i plików w data/ są ograniczone do [a-z0-9_.-]. Bez spacji, bez wielkich liter.

Gdzie wrzucić datapack na serwerze

W folderze świata serwerowego ścieżka jest stała:

<server>/world/datapacks/my_recipes/

Jeśli masz wiele światów, kopiujesz do każdego albo robisz symlink. Bukkit i Paper czasem nazywają główny świat world niezależnie od level-name. Sprawdź level.dat dla pewności.

Po skopiowaniu zaloguj się jako op:

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

/reload przeładowuje wszystkie datapacki bez restartu serwera. Gracze nie muszą się rozłączać. Komendy i tagi aktualizują się natychmiast. Jeżeli JSON jest błędny, serwer wypisze błąd w konsoli i pominie tę jedną recepturę; pozostałe nadal działają.

W Realms i singleplayerze pack trafia do tego samego world/datapacks/. Aternos ma wbudowaną stronę "Datapacks", wgrywasz tam zip o tej samej zawartości.

Typy receptur w 1.21

Gra zna dziewięć typów. Każdy to osobny JSON z własnym zestawem pól.

Typ	wartość type	Gdzie się crafci	Kluczowe pola
Shaped	minecraft:crafting_shaped	stół rzemieślniczy	pattern, key, result, category
Shapeless	minecraft:crafting_shapeless	stół rzemieślniczy	ingredients, result, category
Smelting	minecraft:smelting	piec	ingredient, result, experience, cookingtime
Blasting	minecraft:blasting	wielki piec	jw., cookingtime 100 default
Smoking	minecraft:smoking	wędzarnia	jw., cookingtime 100
Campfire	minecraft:campfire_cooking	ognisko	jw., cookingtime 600
Smithing transform	minecraft:smithing_transform	stół kowalski	template, base, addition, result
Smithing trim	minecraft:smithing_trim	stół kowalski	template, base, addition, pattern
Stonecutting	minecraft:stonecutting	piła kamienna	ingredient, result, count

Prefiks minecraft: jest opcjonalny (działa domyślny namespace), ale ja zawsze go piszę: lepsze jawne niż domyślne.

Pole category wpływa wyłącznie na zakładkę w księdze receptur: building, redstone, equipment, misc dla craftingu, plus food, blocks, misc dla smeltingu. Nieobowiązkowe.

Pole group łączy kilka receptur w jedno miejsce w księdze. Sześć receptur schodów drewnianych dzieli "group": "wooden_stairs" i pokazuje się jako jeden wpis.

Przykład 1: shaped, złote jabłko z 9 bloków złota

Wrzuć do 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
  }
}

Od 1.20.5 klucz wyniku to id, nie item. To część przebudowy item components: każdy recipe JSON używa nowego schematu od pack_format 41.

pattern to tablica od jednego do trzech ciągów, każdy od jednego do trzech znaków. Spacja to pusty slot. Pusty ciąg jest niedozwolony.

Ten sam wzór z pustym środkiem:

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

To kształt X: cztery bloki złota w rogach, jabłko na środku.

Przykład 2: shapeless z tagów

Często chcesz akceptować "dowolne drewno" albo "dowolną sadzonkę". Do tego są tagi przedmiotów. Stwórz 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
  }
}

Dowolne trzy kłody (mangrove, cherry, każde drzewo dodane do 1.21) zamieniają się w dwa prochy. W shapeless kolejność składników na siatce jest nieistotna.

W jednym slocie można połączyć tag i item przez tablicę:

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

Czyta się jako "diament albo szmaragd" w pierwszym slocie i dowolne deski w drugim.

Własny tag idzie do data/<ns>/tags/item/my_logs.json:

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

Prefiks # znaczy "włącz inny tag". Dobry wzorzec: zdefiniuj tag raz, odwołuj się z wielu receptur; przy nowym drewnie zmieniasz tylko plik tagu.

Przykład 3: smelting i jego warianty

Piec, wielki piec, wędzarnia i ognisko mają tę samą strukturę pól, różni je tylko type. Wrzuć 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 liczy się w tickach (20 ticków = 1 sekunda). Standard pieca to 200 (10 sekund). Wielki piec i wędzarnia gotują dwa razy szybciej, dlatego ich receptury zwykle stoją na 100. Ognisko jest wolne, 600.

experience to float. Gracz dostaje go przy odbiorze.

Aby ten sam input działał we wszystkich czterech urządzeniach, piszesz cztery osobne JSON. Sposób na oszczędność: zostaw wspólny ingredient, zmieniaj tylko type i cookingtime.

Przykład 4: smithing dla ulepszeń

Stół kowalski w 1.21 ma trzy sloty: template, base, addition. smithing_transform tworzy nowy przedmiot, smithing_trim nakłada wzór na zbroję.

Prosty przykład: nadpisanie waniliowego ulepszenia netherite_pickaxe.

{
  "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"}
}

Aby zrobić "pseudo-netheryt" z, powiedzmy, copper_block plus diamond_pickaxe, podmień template lub addition.

Wariant 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 zbiera tu sloty zbroi: każdy waniliowy hełm albo napierśnik spełnia warunek base.

Przykład 5: stonecutter

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

Stonecutter zawsze działa 1 do N: jeden blok wchodzi, N wychodzi. Brak pattern i key.

Własne nazwy i komponenty w wyniku

Od 1.20.5 waniliowy format receptur obsługuje item components bezpośrednio w result. Możesz dać graczowi z góry nazwany, zaczarowany, opisany przedmiot, bez następnego /give.

Custom kilof "Aether Drill" z okładki:

{
  "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"
    }
  }
}

Komponenty tekstowe trafiają jako serializowany ciąg JSON wewnątrz wartości. Tak działa format item component: zagnieżdżony JSON podróżuje jako string.

Uwaga: components w wyniku nie czynią składnika unikalnym. Dowolny waniliowy diamentowy kilof nadal craftuje "Aether Drill". Aby przyjmować tylko nazwany przedmiot, dorzuć components do składnika i wyłącz waniliowe receptury.

Wyłączanie waniliowych receptur

Czasem chcesz pozbyć się standardowego craftingu, żeby zastąpić go własnym. Najczystszy sposób: nadpisz waniliowy JSON kształtem, który nigdy się nie wyzwoli.

Plik wrzucasz pod tę samą ścieżkę, co wanilia. Aby wyłączyć stół zaklęć:

data/minecraft/recipe/enchanting_table.json:

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

Gracz nigdy nie ma w eq bariery, więc receptura jest martwa. Od 1.21 jest też /recipe take @a minecraft:enchanting_table. Ta komenda ściąga recepturę tylko z księgi; sam crafting w siatce nadal działa. Nadpisywanie JSON pozostaje standardową metodą.

Można też wycofać advancement, który daje recepturę: gracz wtedy jej nie odblokuje. Już odblokowani gracze ją zachowają.

Hot reload przy pracy

Standardowy workflow:

1. Zapisujesz JSON.
2. Alt-Tab w grę, /reload.
3. Jeśli błąd, widzisz w konsoli. Otwierasz log, naprawiasz JSON.
4. Powtarzasz.

Przydatne komendy:

• /datapack list available: wyłączone packi.
• /datapack list enabled: aktywne.
• /datapack disable "file/my_recipes": wyłącz.
• /recipe give @p mypack:super_apple: dodaj recepturę do księgi gracza.
• /recipe take @a *: zabierz wszystkie receptury wszystkim (do testów odblokowania).

/reload odświeża tylko zawartość datapacków. Zmiany w server.properties, bukkit.yml, pluginach lub rdzeniu wymagają prawdziwego restartu.

Częste błędy

Serwer pisze "Couldn't load data pack mypack". Trzy możliwe przyczyny:

1. pack_format nie pasuje do wersji serwera. Sprawdź tabelę powyżej.
2. JSON ma błąd składni. Przepuść przez jq lub walidator online.
3. Nazwa pliku lub folderu zawiera niedozwolone znaki.

Receptura nie pojawia się w księdze. Minecraft pokazuje tylko odblokowane receptury. Domyślne odblokowanie idzie z advancementu. Dla custom receptur advancement nie tworzy się sam; w 1.21 piszesz go ręcznie do data/<ns>/advancement/recipes/<name>.json. Skrót: po /reload wykonaj /recipe give @a *.

Crafting nie działa, choć JSON się załadował. Sprawdź:

• pattern ma maksymalnie trzy linie po trzy znaki.
• każdy klucz z key występuje w pattern, a każdy znak inny niż spacja w pattern jest zdefiniowany w key.
• crafting_shapeless ma maksymalnie dziewięć składników.
• ID przedmiotów są poprawne: minecraft:cobblestone, nie Cobblestone.

Konflikt dwóch receptur o tej samej formie. Gdy twoja shaped receptura ma dokładnie ten sam pattern co waniliowa, w księdze wygra ta załadowana później. Rozwiązanie: nadpisz waniliowy JSON.

Receptura działa w singleplayerze, nie działa na serwerze. Najprawdopodobniej datapack jest w niewłaściwym świecie. Bukkit/Paper trzymają osobne światy dla netheru i endu (world_nether, world_the_end), ale jeden katalog datapacks/ w głównym świecie. Vanilla serwer trzyma datapacki w world/datapacks/ tak samo. Multiverse-Core potrafi przemianować główny świat: sprawdź level-name= w server.properties.

Kompatybilność i żywotność

Datapack 1.21 nie wczyta się na 1.20.4 i odwrotnie. Format item components mocno zmienił się w 1.20.5. Jeśli wspierasz kilka wersji, trzymaj dwa foldery: mypack-1.20.4/ z pack_format: 26 i starym wynikiem (item zamiast id, bez components), oraz mypack-1.21/ z aktualnym schematem.

Przy każdym update Minecrafta sprawdzaj changelog Mojanga pod kątem zmian ścieżek. Zdarzają się rzadko, ale regularnie: 1.21 przemianował recipes na recipe i wywalił wszystkie stare datapacki bez migracji.

Warte zakładki:

• minecraft.wiki/w/Recipe: pełna specyfikacja.
• minecraft.wiki/w/Data_pack: przegląd struktury.
• misode.github.io/recipe: wizualny generator z autouzupełnianiem.
• minecraft.wiki/w/Pack_format: tabela wersji.

FAQ

Czy datapack doda nowy przedmiot?

Nie. Datapacki zmieniają receptury, loot, tagi, advancementy i mcfunction. Nowych typów ItemStack nie dodadzą. Do nowego przedmiotu potrzebujesz moda (Fabric, Forge, NeoForge) lub plugina Bukkit. Obejście: waniliowy przedmiot z custom_model_data plus resource pack z innym modelem. Z punktu widzenia receptury to nadal waniliowy item.

Czy potrzebuję advancementu do każdej receptury?

Do działania craftingu nie. Bez advancementu receptura nadal wyzwala się w siatce; gracz po prostu nie zobaczy jej w księdze. Aby odblokować ją automatycznie po spełnieniu warunku (np. składnik wpada do eq), napisz data/<ns>/advancement/recipes/<name>.json z triggerem inventory_changed i nagrodą recipe.

Jak wymusić nazwany składnik?

Przez components w składniku. Przykład:

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

components w składnikach pojawiły się w 1.20.5+. Wcześniej trzeba było bramkować recepturę przez predicate w advancement.

Czy datapack lagga serwer?

Sam lookup receptury nie chodzi co tick, odpala się tylko przy próbie craftu. Tick lag z datapacków prawie zawsze idzie z ciężkich pętli execute w mcfunction. Czyste receptury są darmowe.

Czy mogę odblokować receptury tylko wybranym graczom?

Przez advancement i predicate na tag. Daj graczowi /tag @s add unlocked, advancement wymaga tego tagu. Tylko otagowani gracze odblokują recepturę w księdze. Samego craftingu w siatce nie zablokujesz; każdy ze składnikami skraftuje. Faktyczny zakaz wymaga scoreboardu i /clear w pętli mcfunction, co już wychodzi poza czysty datapack.

Jak testować bez przelogowania?

/reload załatwia wszystko. Nawet przy zmianie pack.mcmeta albo dodaniu/usunięciu namespace /reload wystarczy. Reconnect potrzebny jest tylko przy zmianie resource packa (tekstury, modele), nie datapacka.

Custom receptury przez datapack to jeden z tych przypadków, gdzie wanilia wystarczy, a plugin tylko dorzuca zbędną zależność. Format JSON jest stabilny, dokumentacja kompletna, a misode.github.io zdejmuje 90 procent rutyny. Załóż world/datapacks/, wrzuć kilkanaście własnych receptur, a serwer dostanie unikalny układ craftingu bez ani jednej linijki Javy.