mojang/minecraft-creator-tools/create-block

Create or change a block

A block needs a behavior pack definition, a texture registered in terrain_texture.json, an entry in the resource pack's blocks.json, and often a loot table. For a new block, the Minecraft Creator Tools MCP tool createMinecraftContent writes these from one definition; your job is to translate the request, then check and finish what it produces. For a block that already exists, skip to "Changing an existing block".

1. Understand the request

Work out, or choose sensible defaults for:

• Name and a short lowercase ID (glow_mushroom_block).
• Shape: full cube (default), slab, stairs, fence, wall, cross (plant-like), or custom.
• Behavior: light level (0-15), how long it takes to mine, explosion resistance, flammable, falls like sand, faces the player when placed.
• What it drops when mined: itself (default), other items, or nothing.
• Whether it generates naturally (ores, plants) and where.
• Look: color or pixel-art texture, and sound set (stone, wood, gravel, grass, sand, glass, metal, cloth, snow, coral).

Only ask when an answer would change the design a lot; otherwise pick defaults and say what you chose. Blocks that _do_ something custom when clicked or stepped on need the Script API, which these skills don't cover yet; create the block and tell the user that part 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 blocks in blockTypes, and world generation in features:

{
  "schemaVersion": "1.0.0",
  "namespace": "gems",
  "itemTypes": [{ "id": "ruby", "displayName": "Ruby", "color": "#D01C3A" }],
  "blockTypes": [
    {
      "id": "ruby_ore",
      "displayName": "Ruby Ore",
      "traits": ["solid"],
      "destroyTime": 3,
      "mapColor": "#8C3A4A",
      "sounds": "stone",
      "drops": [{ "item": "gems:ruby" }]
    }
  ],
  "features": [
    {
      "id": "ruby_ore_feature",
      "spread": {
        "places": [
          {
            "type": "ore",
            "id": "gems:ruby_ore",
            "replacesBlocks": ["minecraft:stone", "minecraft:deepslate"],
            "count": 4
          }
        ],
        "count": 3,
        "heightPlacement": { "type": "range", "min": -32, "max": 16 },
        "biomes": ["overworld"]
      }
    }
  ]
}

Useful traits: solid, transparent, leaves, log, slab, stairs, fence, wall, door, trapdoor, container, workstation, light_source, gravity, button, lever, pressure_plate, redstone_signal. Use states and permutations for blocks that change (growth stages, on/off); those take native Minecraft JSON. references/placement-and-worldgen.md covers blocks that face the player and world generation. spread only works for ores; plants, trees, and other placements need raw feature JSON.

4. Check what was generated

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

• Unknown fields are silently dropped, even in `features`. A feature with the wrong shape is counted in the summary but produces no files. Confirm features/ and feature_rules/ files exist for each feature. Fix blocks by editing the generated file; running the tool again won't update a file that already exists.
• Only ore world generation is complete. Other spread placement types, scatter, count ranges, and heights of exactly 0 aren't handled; see references/placement-and-worldgen.md.
• Scatter features use an older layout that validation flags with a JSONF warning about a missing distribution field. references/placement-and-worldgen.md shows the current layout.
• Custom drops aren't wired up. A loot table is written to loot_tables/blocks/<id>.json, but the block doesn't point to it, so it drops itself. Add to the block's components:

``json "minecraft:loot": "loot_tables/blocks/ruby_ore.json" ``

• 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].
• Sounds live in resource_packs/<pack>/blocks.json, not the behavior file. That's expected.

5. Give it a readable name

Creator Tools doesn't create localization, so the block shows as tile.<namespace>:<id>.name. Run the debug-addon skill's names script with the display names the user asked for. <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 "gems:ruby_ore=Ruby Ore"

6. Texture

Without a texture, the block gets a placeholder generated from mapColor. For a specific look, pass texture.all (or per-face up/down/side) with pixelArt in the definition, or use the design-model skill's pixel-art step to draw a 16x16 resource_packs/<pack>/textures/blocks/<id>.png. Keep the file path and the key in terrain_texture.json unchanged so the block keeps finding its texture.

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 blocks created, the defaults you picked, and how to try it: find it in the creative inventory (Construction tab by default) or use /give @s <namespace>:<id>, then place and mine it. World generation only happens in newly generated chunks, so they need a new world or unexplored area to see ores. To look at it without Minecraft, they can run npx -y @minecraft/creator-tools@latest view -i <project-folder>.

Changing an existing block

1. Find the block's file (behavior_packs/<pack>/blocks/*.json, matched by identifier) and edit its components directly. Running createMinecraftContent again won't change a file that already exists.
2. Common changes: minecraft:light_emission, minecraft:destructible_by_mining (seconds_to_destroy), minecraft:destructible_by_explosion, minecraft:friction, minecraft:loot, minecraft:map_color, and menu_category in the description. Sounds are in the resource pack's blocks.json.
3. 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.