mojang/minecraft-creator-tools/create-item

Create or change an item

An item needs a behavior pack definition, an icon texture registered in item_texture.json, and usually a recipe. For a new item, the Minecraft Creator Tools MCP tool createMinecraftContent writes all of these from one definition; your job is to translate the request, then check and finish what it produces. For an item that already exists, skip to "Changing an existing item".

1. Understand the request

Work out, or choose sensible defaults for:

• Name and a short lowercase ID (magic_hammer).
• What it is: weapon, tool (and which blocks it mines), food, armor (which slot), throwable, bow, or a plain material.
• Numbers that matter to the user: damage, durability, mining tier, nutrition, stack size.
• How players get it: a crafting recipe, a mob drop (see create-mob), or creative inventory only.
• Icon look (colors, or pixel art if they describe it).

Only ask when an answer would change the design a lot; otherwise pick defaults and say what you chose.

If the item should _do_ something custom when used (right-click to teleport, heal nearby players, place a structure), that needs the Script API, which these skills don't cover yet. Create the item itself, and tell the user the custom behavior needs scripting.

2. Pick the project folder and namespace

• Existing project: reuse its namespace from existing identifier values.
• New project: an empty folder and a short lowercase namespace (letters, digits, underscores). Never minecraft.

3. Generate with createMinecraftContent

Pass outputPath as the project folder itself. Put items in itemTypes and recipes in recipes:

{
  "schemaVersion": "1.0.0",
  "namespace": "fungi",
  "itemTypes": [
    {
      "id": "magic_hammer",
      "displayName": "Magic Hammer",
      "traits": ["pickaxe"],
      "tool": { "durability": 500 },
      "weapon": { "damage": 7 },
      "glint": true,
      "color": "#8A5CFF"
    },
    {
      "id": "deluxe_stew",
      "displayName": "Deluxe Stew",
      "traits": ["food"],
      "maxStackSize": 1,
      "food": { "nutrition": 8, "saturation": 1.2 }
    },
    {
      "id": "vine_bow",
      "displayName": "Vine Bow",
      "traits": ["bow"],
      "projectile": { "projectile": "minecraft:arrow", "chargeable": true }
    }
  ],
  "recipes": [
    {
      "id": "magic_hammer",
      "type": "shaped",
      "pattern": ["III", " S ", " S "],
      "key": { "I": "minecraft:iron_ingot", "S": "minecraft:stick" },
      "result": "fungi:magic_hammer"
    }
  ]
}

Pick traits by what the item does: sword, pickaxe, axe, shovel, hoe, bow, crossbow, food, armor_helmet, armor_chestplate, armor_leggings, armor_boots, throwable, placeable. Numbers go in their sub-objects (weapon.damage, tool.durability, armor.defense, food.nutrition), not at the top level. Bows, crossbows, and throwables only work with a projectile entry (chargeable: true for bows and crossbows).

4. Check what was generated

Open behavior_packs/<pack>/items/<id>.json and compare it with the request. Known gaps as of Creator Tools 0.17:

• Unknown fields are silently dropped. A top-level "damage": 7 is ignored, and the trait default is used instead. Fix the component in the generated file directly; running the tool again won't update a file that already exists.
• Tool tiers aren't applied. tool.miningLevel is accepted but ignored, and the generated minecraft:digger uses a low speed. Raise the speed to fit the tier the user expects (roughly: wood 2, stone 4, iron 6, diamond 8, netherite 9), and tag the item with its tool type and tier using "minecraft:tags": { "tags": ["minecraft:is_pickaxe", "minecraft:iron_tier"] }. Ask the user to confirm in game that blocks needing that tier (such as diamond ore for iron) drop their items.
• Food status effects don't work. The generator writes effects inside minecraft:food, but current item formats don't support effects there, and it sets saturation_modifier to "custom" instead of a number. Remove effects, set saturation_modifier to a number (0.6 is typical), and tell the user that effects on eating need the Script API, which these skills don't cover yet.
• Bows and crossbows need `projectile`. The trait alone doesn't make the item shoot. If an item was already generated without it, generate the same definition with projectile into an empty scratch folder and copy its minecraft:shooter and related components into the real item file.
• Armor is invisible when worn. The item gets minecraft:wearable, but nothing draws it on the player. Add an attachable and an armor texture as described in references/armor.md. Validation doesn't catch this.
• Adding to an existing project rewrites both manifests. The behavior pack's dependency on its resource pack gets a new UUID that points at nothing, and header.name is reset. Check git diff (or compare with a copy you made first) and restore the original manifest values. The debug-addon validation script reports a broken dependency as [PACKDEP].
• A recipe that uses one of your own blocks can show an UNLINK "item type not found" warning. That's fine; blocks can be crafting ingredients, and the debug-addon summary script files it under likely noise.

5. Give it a readable name

Creator Tools doesn't create localization, so the item shows a raw key in game. Run the debug-addon skill's names script with the display names the user asked for; it adds a minecraft:display_name component to each item that lacks one. <debug-addon-skill-folder> is the debug-addon skill's folder, next to this skill's folder; if it's missing, install the debug-addon skill too.

node "<debug-addon-skill-folder>/scripts/add-missing-names.mjs" <project-folder> --name "fungi:magic_hammer=Magic Hammer"

6. Icon

The icon is a generated placeholder based on the traits and color. For a specific look, either pass icon with pixelArt in the definition, or use the design-model skill's pixel-art step to draw resource_packs/<pack>/textures/items/<id>.png (16x16). Keep the file path and the key in item_texture.json unchanged so the item keeps finding its icon.

7. Validate

Follow the debug-addon skill: run its validation script, add pack icons (new projects don't have them), and fix errors until none remain.

8. Tell the user

Summarize the items and recipes created, the numbers and defaults you picked, and how to get it in game: find it in the creative inventory, craft it, or use /give @s <namespace>:<id>. To look at it without Minecraft, they can run npx -y @minecraft/creator-tools@latest view -i <project-folder>.

Changing an existing item

1. Find the item's file (behavior_packs/<pack>/items/*.json, matched by identifier) and edit its components directly. Running createMinecraftContent again won't change a file that already exists.
2. Common changes: minecraft:damage, minecraft:durability (max_durability), minecraft:max_stack_size, minecraft:food (nutrition, saturation_modifier), minecraft:digger (destroy_speeds), minecraft:glint, and menu_category in the description.
3. Recipes live in behavior_packs/<pack>/recipes/; change the pattern, key, or result there.
4. Validate with the debug-addon skill, and tell the user what changed.

If the MCP tools aren't available

This skill needs the Minecraft Creator Tools MCP server (npx -y @minecraft/creator-tools@latest mcp). If its tools are missing, tell the user and suggest adding that server. As a fallback, npx -y @minecraft/creator-tools@latest add --help lists template-based commands; these need the user to have accepted the Minecraft EULA themselves (npx -y @minecraft/creator-tools@latest eula). Never accept it on their behalf.