Registry API tutorial

1. How the API works

Every registration is a single JSON object with a type field. WEI reads type and decides which of its four entry types to store it as. You can also send a batch of registrations in a single call — see the Multiple registrations section.

Recommended: call the API from script

Prefer system.sendScriptEvent(id, message) from your own behavior-pack script over the /scriptevent chat command. Calling the API from script lets you build the payload as a real JavaScript object, generate it dynamically (loops, data-driven addons, etc.) and let JSON.stringify() handle the escaping for you — none of which you get typing a command by hand.

import { system } from "@minecraft/server";

function register(payload) {
  system.sendScriptEvent("wei:api_register", JSON.stringify(payload));
}

register({
  "type": "loot",
  "id": "myaddon:ruins_chest",
  "results": ["minecraft:emerald", "myaddon:ancient_relic"],
  "blocks": ["minecraft:chest"]
});

2. Identifiers & ingredient formats

Item, block and entity IDs are normalized automatically. Anywhere the API accepts an ingredient, you can also point to an entire tag instead of a single item.

Ingredient with a display count

Inside a craft entry, an ingredient slot can be an object with item and an optional count, so the tooltip shows how many are needed in that slot.

{ "item": "minecraft:iron_ingot", "count": 4 }

Empty visual slot

Use the literal string $invisible to make that position render as invisible (invisible, not an empty slot).

"ingredients": ["minecraft:stick", "$invisible", "minecraft:stick"]

3. Craft entries

Use type: "craft" to document a custom recipe. Pick a recipe_type that matches how the recipe is actually built in-game: grid, combination, input or pot.

register({
  "type": "craft",
  "result": "myaddon:ruby_block",
  "recipe_type": "grid",
  "recipe_tag": "myaddon:gem_bench",
  "icon": "textures/items/ruby_block",
  "dimensions": [3, 3],
  "ingredients": [
    "myaddon:ruby", "myaddon:ruby", "myaddon:ruby",
    "myaddon:ruby", "myaddon:ruby", "myaddon:ruby",
    "myaddon:ruby", "myaddon:ruby", "myaddon:ruby"
  ]
});

register({
  "type": "craft",
  "result": "myaddon:reinforced_stick",
  "recipe_type": "grid",
  "recipe_tag": "minecraft:crafting",
  "icon": "textures/items/reinforced_stick",
  "dimensions": [3, 3],
  "pattern": [
    " I ",
    " S ",
    " I "
  ],
  "key": {
    "I": "minecraft:iron_nugget",
    "S": { "item": "minecraft:stick", "count": 1 }
  }
});

register({
  "type": "craft",
  "result": "myaddon:healing_potion",
  "recipe_type": "combination",
  "recipe_tag": "myaddon:alchemy_table",
  "icon": "textures/items/healing_potion",
  "ingredients": [
    "myaddon:crushed_herb",
    "minecraft:glass_bottle",
    { "item": "minecraft:sugar", "count": 2 }
  ]
});

register({
  "type": "craft",
  "result": "myaddon:iron_plate",
  "recipe_type": "input",
  "recipe_tag": "myaddon:compactor",
  "icon": "textures/items/iron_plate",
  "ingredients": ["minecraft:iron_ingot"]
});

register({
  "type": "craft",
  "result": "myaddon:herbal_stew",
  "recipe_type": "pot",
  "recipe_tag": "myaddon:cooking_pot",
  "icon": "textures/items/herbal_stew",
  "dimensions": [3, 3],
  "pattern": [
    "H H",
    " W ",
    "H H"
  ],
  "key": {
    "H": "minecraft:sweet_berries",
    "W": "minecraft:water_bucket"
  },
  "container": "minecraft:bowl"
});

4. Loot entries

Use type: "loot" whenever an item can drop from something — a custom block, a custom entity, or both.

register({
  "type": "loot",
  "id": "myaddon:ruins_chest",
  "results": [
    "minecraft:emerald",
    "minecraft:gold_ingot",
    "myaddon:ancient_relic"
  ],
  "blocks": ["myaddon:ruined_chest"]
});

register({
  "type": "loot",
  "id": "myaddon:swamp_lurker_drops",
  "results": ["myaddon:slime_gland", "minecraft:rotten_flesh"],
  "entities": ["myaddon:swamp_lurker"]
});

5. Trade entries

Use type: "trade" for a custom trading table (merchant, altar, exchange block — anything that swaps items). gives is the heart of it: it maps each item in results to what the player must pay for it.

Shape of a want entry

Each entry inside a gives[result] array is an object { "item": "...", "quantity": N }. quantity can be a fixed integer, or a range object with min/max.

{ "item": "minecraft:emerald", "quantity": 3 }
{ "item": "minecraft:iron_ingot", "quantity": { "min": 2, "max": 5 } }

register({
  "type": "trade",
  "id": "myaddon:forest_merchant",
  "results": ["myaddon:enchanted_bow"],
  "gives": {
    "myaddon:enchanted_bow": [
      { "item": "minecraft:emerald", "quantity": 12 }
    ]
  },
  "entities": ["myaddon:forest_merchant"]
});

An offer that requires two items at once

To describe a single offer that consumes two items together (not two separate alternative offers), wrap the pair of want objects in its own array inside gives[result].

register({
  "type": "trade",
  "id": "myaddon:blacksmith",
  "results": ["myaddon:steel_pickaxe"],
  "gives": {
    "myaddon:steel_pickaxe": [
      [
        { "item": "minecraft:iron_ingot", "quantity": 10 },
        { "item": "minecraft:stick", "quantity": 2 }
      ]
    ]
  },
  "entities": ["myaddon:blacksmith"]
});

Here the pickaxe has one single offer that costs 10 iron ingots and 2 sticks together.

6. Station tags

Use type: "station_tag" to tell WEI which blocks act as a given crafting station. Any craft entry whose recipe_tag matches this tag will list all of these blocks as valid places to craft it.

register({
  "type": "station_tag",
  "tag": "myaddon:gem_bench",
  "blocks": ["myaddon:gem_bench", "myaddon:gem_bench_upgraded"]
});

7. Registering several entries at once

If your addon needs to register many recipes, drops or trades on startup, you don't have to call sendScriptEvent once per entry. Wrap a list of normal registration objects in a top-level multi array and send it as a single event.

register({
  "multi": [
    {
      "type": "craft",
      "result": "myaddon:ruby",
      "recipe_type": "input",
      "recipe_tag": "myaddon:gem_bench",
      "icon": "textures/items/ruby",
      "ingredients": ["myaddon:raw_ruby"]
    },
    {
      "type": "loot",
      "id": "myaddon:ruins_chest",
      "results": ["myaddon:raw_ruby"],
      "blocks": ["myaddon:ruined_chest"]
    },
    {
      "type": "station_tag",
      "tag": "myaddon:gem_bench",
      "blocks": ["myaddon:gem_bench"]
    }
  ]
});

Each entry inside multi follows exactly the same rules described in the sections above — it's simply a convenient way to send a batch of them together instead of firing one Script Event per entry.

8. Limits & debugging

Common validation mistakes

9. Full scenarios

Two complete, self-contained scenarios combining several entry types for the same content pack.

register({
  "multi": [
    {
      "type": "loot",
      "id": "myaddon:crystal_vein",
      "results": ["myaddon:raw_sapphire"],
      "blocks": ["myaddon:sapphire_ore"]
    },
    {
      "type": "craft",
      "result": "myaddon:sapphire",
      "recipe_type": "input",
      "recipe_tag": "myaddon:gem_furnace",
      "icon": "textures/items/sapphire",
      "ingredients": ["myaddon:raw_sapphire"]
    },
    {
      "type": "station_tag",
      "tag": "myaddon:gem_furnace",
      "blocks": ["myaddon:gem_furnace", "myaddon:gem_furnace_deluxe"]
    }
  ]
});

register({
  "type": "trade",
  "id": "myaddon:caravan_trader",
  "results": ["minecraft:saddle", "myaddon:travel_cloak"],
  "gives": {
    "minecraft:saddle": [
      { "item": "minecraft:emerald", "quantity": { "min": 6, "max": 9 } }
    ],
    "myaddon:travel_cloak": [
      [
        { "item": "minecraft:leather", "quantity": 5 },
        { "item": "minecraft:string", "quantity": 3 }
      ]
    ]
  },
  "entities": ["myaddon:caravan_trader"]
});

10. Quick reference