Examples

Each recipe below is a complete JSON file. Save block recipes as config/betterharvestlevel/blocks.json, tool recipes as config/betterharvestlevel/tools.json, and the tier and equivalence recipes under the filenames shown.

Block requirements

Raise coal ore to iron

{
  "configVersion": 1,
  "overrides": [
    {
      "target": "minecraft:coal_ore",
      "type": "block",
      "requiredTier": "iron"
    }
  ]
}

minecraft:coal_ore now requires an iron-tier or stronger tool to produce drops. Its vanilla tool category still applies, so the player must use a pickaxe.

Lower obsidian to stone

{
  "configVersion": 1,
  "overrides": [
    {
      "target": "minecraft:obsidian",
      "type": "block",
      "requiredTier": "stone"
    }
  ]
}

minecraft:obsidian now produces drops with a stone-tier or stronger tool. Its vanilla tool category still applies, so the player must use a pickaxe.

Harvest cobblestone by hand

{
  "configVersion": 1,
  "overrides": [
    {
      "target": "minecraft:cobblestone",
      "type": "block",
      "requiredTier": "hand"
    }
  ]
}

minecraft:cobblestone now produces drops when broken with an empty hand. Setting requiredTier to hand explicitly makes the block hand-harvestable, so its normal vanilla tool category does not block hand harvesting.

Apply diamond to a block tag

{
  "configVersion": 1,
  "overrides": [
    {
      "target": "#minecraft:needs_iron_tool",
      "type": "tag",
      "requiredTier": "diamond"
    }
  ]
}

Every block in #minecraft:needs_iron_tool now requires a diamond-tier or stronger tool to produce drops. Each block’s vanilla tool category still applies unless another rule explicitly makes that block hand-harvestable.

Apply netherite to a mod namespace

{
  "configVersion": 1,
  "overrides": [
    {
      "target": "examplemod:*",
      "type": "mod",
      "requiredTier": "netherite"
    }
  ]
}

For this illustrative examplemod namespace, every matching block now requires a netherite-tier tool to produce drops. Each block’s vanilla tool category still applies unless another rule explicitly makes that block hand-harvestable.

Match modded ores with a regular expression

{
  "configVersion": 1,
  "overrides": [
    {
      "target": "examplemod:.*_ore",
      "type": "regex",
      "requiredTier": "iron"
    }
  ]
}

For this illustrative examplemod namespace, every block ID ending in _ore now requires an iron-tier or stronger tool to produce drops. Each block’s vanilla tool category still applies unless another rule explicitly makes that block hand-harvestable.

Tool tiers

Assign diamond to one item

{
  "configVersion": 1,
  "overrides": [
    {
      "target": "examplemod:drill",
      "type": "item",
      "tier": "diamond"
    }
  ]
}

The illustrative examplemod:drill resolves as a diamond-tier tool. It can satisfy diamond-tier and lower requirements when it also matches the block’s vanilla tool category.

Assign iron to an item tag

{
  "configVersion": 1,
  "overrides": [
    {
      "target": "#c:tools/drill",
      "type": "tag",
      "tier": "iron"
    }
  ]
}

Every item in #c:tools/drill resolves as an iron-tier tool. Those items can satisfy iron-tier and lower requirements when they also match the block’s vanilla tool category.

Custom tier and equivalence

Add the steel tier

Use this complete tiers.json to keep the generated tiers and add the same steel tier used on the Configuration page. The illustrative examplemod:steel_pickaxe ID is Jade’s fallback icon when no matching vanilla tool icon exists and should be replaced with a real item ID.

{
  "configVersion": 1,
  "tiers": [
    {
      "name": "wood",
      "level": 0,
      "displayName": "Wooden",
      "color": "#8B6914",
      "builtIn": true,
      "iconItem": "minecraft:wooden_pickaxe"
    },
    {
      "name": "gold",
      "level": 0,
      "displayName": "Golden",
      "color": "#FFAA00",
      "builtIn": true,
      "iconItem": "minecraft:golden_pickaxe"
    },
    {
      "name": "stone",
      "level": 1,
      "displayName": "Stone",
      "color": "#888888",
      "builtIn": true,
      "iconItem": "minecraft:stone_pickaxe"
    },
    {
      "name": "copper",
      "level": 2,
      "displayName": "Copper",
      "color": "#E77C56",
      "builtIn": true,
      "iconItem": "minecraft:copper_ingot"
    },
    {
      "name": "iron",
      "level": 3,
      "displayName": "Iron",
      "color": "#C8C8C8",
      "builtIn": true,
      "iconItem": "minecraft:iron_pickaxe"
    },
    {
      "name": "diamond",
      "level": 4,
      "displayName": "Diamond",
      "color": "#55FFFF",
      "builtIn": true,
      "iconItem": "minecraft:diamond_pickaxe"
    },
    {
      "name": "netherite",
      "level": 5,
      "displayName": "Netherite",
      "color": "#4D3B3B",
      "builtIn": true,
      "iconItem": "minecraft:netherite_pickaxe"
    },
    {
      "name": "steel",
      "level": 4,
      "displayName": "Steel",
      "color": "#9AA4AD",
      "builtIn": false,
      "iconItem": "examplemod:steel_pickaxe"
    }
  ]
}

Better Harvest Levels registers steel at level 4. Rules can now use steel as a required block tier or assigned tool tier, and commands display it as Steel.

Make steel and diamond equivalent

After adding steel to tiers.json, save this as equivalences.json:

{
  "configVersion": 1,
  "groups": [
    {
      "name": "diamond-grade",
      "tiers": ["steel", "diamond"]
    }
  ]
}

A steel-tier tool now satisfies a diamond requirement, and a diamond-tier tool satisfies a steel requirement. Numeric tier ordering continues to apply outside the diamond-grade group.

Layered modpack layout

Split broad defaults and progression adjustments into files whose names show their load order:

config/betterharvestlevel/
├── blocks.json
├── blocks_10_ores.json
├── blocks_20_progression.json
├── tools.json
└── tools_10_modded.json

Better Harvest Levels loads each file family in alphabetical filename order. blocks_20_progression.json loads after blocks_10_ores.json, so a matching entry in the progression file wins over an earlier matching entry in the ores file. The same rule applies within each file: a later matching entry in its overrides array wins.