All parameters are required unless explicitly marked 🔹Optional.

---

IRuleList

This is the main object of any .json rule files.

Rule files are processed in the order in which they are loaded. Files with a higher priority will have their rules matched first.

{
  "priority": int,
  "rules": IRule[]
}

• priority: int

  • 🔹Optional - if omitted, defaults to 0.
  • Files with a higher priority will have their rules matched first. This value can be positive or negative.

• rules: IRule[]

  • This array contains objects which define match and replace behavior.

---

IRule

The IRule defines match and replace behavior.

Each IRule entry is matched in the same order it is defined the file.

{
  "debug": boolean,
  "fallthrough": boolean,
  "match": IRuleMatch,
  "replaceStrategy": enum,
  "dropStrategy": enum,
  "dropCount": IRandomFortuneInt,
  "drops": IRuleDrop[]
}

• debug: boolean

  • 🔹Optional - if omitted, defaults to false.
  • Prints a large amount of debug data to the log file. Be careful how many rules you enable this flag on, as it will rapidly bloat your log file. Useful for testing, see: DEBUG.md

• fallthrough: boolean

  • 🔹Optional - if omitted, defaults to false.
  • Continues matching rules after this rule if this rule is matched.

• match: IRuleMatch

  • 🔹Optional - if omitted, all blocks will be matched.
  • This object defines the conditions used to match this rule.

• replaceStrategy: enum

  • 🔹Optional - if omitted, defaults to REPLACE_ALL.
  • REPLACE_ITEMS: All items defined in the IRuleMatch will be removed.
  • REPLACE_ITEMS_IF_SELECTED: All items defined in the IRuleMatch will be removed if and only if drops are selected from this rule.
  • REPLACE_ALL: All block drops will be replaced by drops from this rule.
  • REPLACE_ALL_IF_SELECTED: All block drops will be replaced by drops from this rule if and only if drops are selected from this rule.
  • ADD: Any selected drops from this rule will be added to the block's existing drops. If this rule is matched and no drops are selected, the block will drop nothing.

• dropStrategy: enum

  • 🔹Optional - if omitted, defaults to REPEAT.
  • REPEAT: When picking drops from the weighted picker, any IRuleDrop that is selected may be selected more than once.
  • UNIQUE: When picking drops from the weighted picker, any IRuleDrop that is selected will be removed from the picker, ensuring that it will only be selected once. If the picker is depleted before the defined dropCount is reached, drop picking will stop.

• dropCount: IRandomFortuneInt

  • 🔹Optional - if omitted, defaults to 1.
  • This object defines how many times the weighted picker will be queried for drops.
  • Note: dropCount does not apply to forced drops.

• drops: IRuleDrop[]

  • 🔹Optional - if omitted, no drops will be processed.
  • This array defines the potential drops for this rule.

---

IRuleMatch

The IRuleMatch is responsible for matching a rule using defined conditions.

When a block is broken, the first IRule to successfully satisfy the requirements of the IRuleMatch is selected.

{
  "blocks": IRuleMatchBlocks,
  "drops": IRuleMatchDrops,
  "harvester": IRuleMatchHarvester,
  "biomes": IRuleMatchBiome,
  "dimensions": IRuleMatchDimension,
  "verticalRange": IRangeInt
  "spawnDistance": IRuleMatchSpawnDistance
}

• blocks: IRuleMatchBlocks

  • 🔹Optional - if omitted, this condition will pass.
  • This object defines conditions to match blockstates.

• drops: IRuleMatchDrops

  • 🔹Optional - if omitted, this condition will pass.
  • This object defines items to be matched against the items dropped.

• harvester: IRuleMatchHarvester

  • 🔹Optional - if omitted, any harvester will be matched.
  • This object defines conditions specific to the entity that broke the block.

• biomes: IRuleMatchBiome

  • 🔹Optional - if omitted, all biomes will match.
  • This object defines biome conditions.

• dimensions: IRuleMatchDimension

  • 🔹Optional - if omitted, all dimensions will match.
  • This object defines dimension conditions.

• verticalRange: IRangeInt

  • 🔹Optional - if omitted, defaults to full height range.
  • This object defines the vertical range condition.

• spawnDistance: IRuleMatchSpawnDistance

  • 🔹Optional - if omitted, all distances will match.
  • This object defines the range from world spawn condition.

---

IRuleMatchBlocks

This object defines conditions to match the broken blockstate.

{
  "type": enum,
  "blocks": String[]
}

• type: enum

  • 🔹Optional - if omitted, defaults to WHITELIST.
  • WHITELIST: If the broken block is in the list, then this match condition passes.
  • BLACKLIST: If the broken block is not in the list, then this match condition passes.

• blocks: String[]

  • 🔹Optional - if omitted, all blocks will be matched.
  • This string array defines blocks to be matched against the block broken.
  • Syntax: domain:path:meta, meta may be a wildcard *. Multiple meta values can be specified using domain:path:meta,meta,meta.
  • Example: minecraft:stone:0
  • Note: These block strings are matched against blockStates and OreDict values are not valid.

---

IRuleMatchDrops

This object defines conditions to match the items dropped by the broken block.

{
  "type": enum,
  "drops": String[]
}

• type: enum

  • 🔹Optional - if omitted, defaults to WHITELIST.
  • WHITELIST: If any item dropped by the block is in the list, then this match condition passes.
  • BLACKLIST: If no item dropped by the block is in the list, then this match condition passes.

• drops: String[]

  • 🔹Optional - if omitted, this condition passes.
  • This string array defines items to be matched against the items dropped.
  • Syntax: domain:path:meta, meta may be a wildcard *. Multiple meta values can be specified using domain:path:meta,meta,meta. OreDict values are accepted.
  • Example: minecraft:stone:0

---

IRuleMatchHarvester

This object defines conditions specific to the entity that broke the block.

{
  "type": enum,
  "heldItemMainHand": IRuleMatchHarvesterHeldItem,
  "heldItemOffHand": IRuleMatchHarvesterHeldItem,
  "gamestages": IRuleMatchHarvesterGameStage,
  "playerName": IRuleMatchHarvesterPlayerName
}

• type: enum

  • 🔹Optional - if omitted, defaults to ANY.
  • PLAYER: The block must be broken by a player (fake or real) to match.
  • NON_PLAYER: The block must not be broken by a player to match.
  • ANY: The matcher does not care what broke the block.
    If a player broke the block and heldItemMainHand, gamestages, or playerName is provided, they will be checked.
  • EXPLOSION: The matcher will only match blocks broken by explosions.
    NOTE: some dropped items will be destroyed as per the normal explosion mechanics.
  • REAL_PLAYER: The harvester must be a real player.
  • FAKE_PLAYER: The harvester must be a fake player.

• heldItemMainHand: IRuleMatchHarvesterHeldItem

  • 🔹Optional - if omitted, this condition will pass.
  • This object defines conditions for matching held items.

• gamestages: IRuleMatchHarvesterGameStage

  • 🔹Optional - if omitted, this condition will pass.
  • This object defines conditions for matching gamestages.

• playerName: IRuleMatchHarvesterPlayerName

  • 🔹Optional - if omitted, this condition will pass.
  • This object defines conditions for matching player names.

---

IRuleMatchHarvesterHeldItem

This object defines conditions for matching held items.

{
  "type": enum,
  "items": String[],
  "harvestLevel": String
}

• type: enum

  • 🔹Optional - if omitted, defaults to WHITELIST.
  • WHITELIST: Passes if the held item is in the list.
  • BLACKLIST: Passes if the held item is not in the list.

• items: String[]

  • 🔹Optional - if omitted, all held items will be matched.
  • Syntax: domain:path:meta, meta can be a wildcard *. It is advised to use the meta wildcard * when matching tools.
  • Note: To match an empty hand, use "EMTPY"; ie. "items": ["EMPTY"]

• harvestLevel: String

  • 🔹Optional - if omitted, harvest level is ignored.
  • Syntax: toolClass;min;max; ie. shovel;0;1 for wood and stone shovels.
  • To set only a min or max value, set the value you want ignored to -1; ie. pickaxe;2;-1 for iron pickaxes and above.
  • Note that the min and max level values are inclusive and that the harvest level matching respects the type enum.

---

IRuleMatchHarvesterGameStage

This object defines conditions for matching gamestages.

{
  "type": enum,
  "require": enum,
  "stages": String[]
}

• type: enum

  • 🔹Optional - if omitted, defaults to WHITELIST.
  • WHITELIST: Does not invert the result of this check.
  • BLACKLIST: Inverts the result of this check.

• require: enum

  • 🔹Optional - if omitted, defaults to ANY.
  • ANY: The player must have any of the listed gamestages to match.
  • ALL: The player must have all of the listed gamestages to match.

• stages: String[]

  • This string array lists the gamestages required to match.

---

IRuleMatchHarvesterPlayerName

This object defines conditions for matching player names.

{
  "type": enum,
  "names": String[]
}

• type: enum

  • 🔹Optional - if omitted, defaults to WHITELIST.
  • WHITELIST: Passes if the player name is in the list.
  • BLACKLIST: Passes if the player name is not in the list.

• playerName: String[]

  • 🔹Optional - if omitted, this condition will pass.
  • This array defines player names to match.

---

IRuleMatchBiome

This object defines conditions for matching biomes.

{
  "type": enum,
  "ids": String[]
}

• type: enum

  • 🔹Optional - if omitted, defaults to WHITELIST.
  • WHITELIST: If the block is broken in a biome in the list, the match passes.
  • BLACKLIST: If the block is broken in a biome not in the list, the match passes.

• ids: String[]

  • This string array contains the biome ids required to match.
  • Syntax: domain:path
  • Example: minecraft:birch_forest_hills

---

IRuleMatchDimension

This object defines conditions for matching dimensions.

{
  "type": enum,
  "ids": int[]
}

• type: enum

  • 🔹Optional - if omitted, defaults to WHITELIST.
  • WHITELIST: If the block is broken in a dimension in the list, the match passes.
  • BLACKLIST: If the block is broken in a dimension not in the list, the match passes.

• ids: int[]

  • This array contains the integer id's of the dimensions required to match.

---

IRuleMatchSpawnDistance

This object defines conditions for matching dimensions.

{
  "type": enum,
  "min": int,
  "max": int
}

• type: enum

  • 🔹Optional - if omitted, defaults to WHITELIST.
  • WHITELIST: If the block is broken is within the provided range, the match passes.
  • BLACKLIST: If the block is broken in outside the provided range, the match passes.

• min: int

  • 🔹Optional - if omitted, defaults to 0.
  • Defines the minimum distance bound.
  • Valid range for this value is [0,2147483647]

• max: int

  • 🔹Optional - if omitted, defaults to 2147483647.
  • Defines the maximum distance bound.
  • Valid range for this value is [0,2147483647]

---

IRangeInt

This object defines a range between a min and max integer value.

{
  "min": int,
  "max": int
}

• min: int

  • 🔹Optional - if omitted, defaults to the minimum value of the enclosing context.
  • This integer defines the minimum value of this range (inclusive).

• max: int

  • 🔹Optional - if omitted, defaults to the maximum value of the enclosing context.
  • This integer defines the maximum value of this range (inclusive).

---

IRandomFortuneInt

This object defines a range used to select a fortune modified random number.

{
  "fixed": int,
  "min": int,
  "max": int,
  "fortuneModifier": int
}

Calculation: random(max - min) + min + fortuneModifier * fortuneLevel

• fixed: int

  • 🔹Optional - if omitted, defaults to using min and max.
  • The fixed value that will always be used. If a value > 0 is supplied, it will be used in the calculation instead of a randomly selected value.

• min: int

  • 🔹Optional - if omitted, defaults to context.
  • The minimum value that will be randomly selected (inclusive).

• max: int

  • 🔹Optional - if omitted, defaults to context.
  • The maximum value that will be randomly selected (inclusive).

• fortuneModifier

  • 🔹Optional - if omitted, defaults to 0.
  • This value will be added to the result of the random value for each level of fortune passed into the BlockEvent.HarvestDropsEvent.

---

IRuleDrop

This object defines conditions used to select and weight a drop as well as the dropped item itself.

If the drop is a valid candidate it will be placed into the weighted picker using the fortune modified weight described in the IRuleDropSelector.

{
  "force": boolean,
  "selector": IRuleDropSelector,
  "item": IRuleDropItem,
  "matchQuantity": IRuleDropMatchQuantity,
  "xp": IRandomFortuneInt,
  "xpReplaceStrategy": enum,
  "replaceBlock": IBlockState
}

• force: boolean

  • 🔹Optional - if omitted, defaults to false.
  • If true, the selector is ignored and this drop definition will always be processed.
  • Note: a forced drop does not count toward the dropCount value.

• selector: IRuleDropSelector

  • 🔹Optional - if omitted, no selection conditions will apply to the drop's candidacy and the weight will default to 1.
  • This object defines conditions for the drop's candidacy as well as its chance to drop.

• item: IRuleDropItem

  • 🔹Optional - if omitted, no item will be dropped if this IRuleDrop is selected from the weighted picker.
  • This object defines the item to drop.

• matchQuantity: IRuleDropMatchQuantity

  • 🔹Optional - if omitted, drop quantity selection will occur as normal.
  • This defines parameters for matching the quantity of existing drops.

• xp: IRandomFortuneInt

  • 🔹Optional - if omitted, defaults to 0.
  • This object defines how much XP to drop when the block is broken and this drop is selected.
  • This amount will either be added to or completely replace any XP that the block normally drops, see the enum below.

• xpReplaceStrategy: enum

  • 🔹Optional - if omitted, defaults to ADD.
  • ADD: Add the specified xp to any xp dropped.
  • REPLACE: Replace any xp dropped with the specified xp.

• replaceBlock: IBlockState

  • 🔹Optional - if omitted, defaults to no block replacement.
  • This defines a blockstate to replace the broken block with.

---

IRuleDropSelector

This object acts as a predicate to identify drop candidates.

If a rule is matched, the IRuleDropSelector is queried to determine a drop's candidacy for the weighted picker. If selected, it also supplies the fortune modified weight to use when adding the drop to the weighted picker.

{
  "weight": IRuleDropSelectorWeight,
  "silktouch": enum,
  "fortuneLevelRequired": int
}

• weight: IRuleDropSelectorWeight

  • 🔹Optional - if omitted, defaults to 1.
  • This object defines the fortune modified weight to use when adding this drop to the weighted picker.

• silktouch: enum

  • 🔹Optional - if omitted, defaults to ANY.
  • REQUIRED: Silk touch is required on the tool the player is using.
  • EXCLUDED: Silk touch must not be on the tool the player is using.
  • ANY: Silk touch is overlooked.

• fortuneLevelRequired: int

  • 🔹Optional - if omitted, defaults to 0.
  • The minimum fortune level required for this drop to be a candidate.

---

IRuleDropSelectorWeight

This object defines the fortune modified weight to use when adding a drop to the weighted picker

{
  "value": int,
  "fortuneModifier": int
}

Calculation: value + fortuneModifier * fortuneLevel

• value: int

  • 🔹Optional - if omitted, defaults to 1.
  • This is the weight used when adding this drop to the weighted picker.

• fortuneModifier: int

  • 🔹Optional - if omitted, defaults to 0.
  • This value will be added to weight value for each level of fortune passed into the BlockEvent.HarvestDropsEvent.

---

IRuleDropItem

{
  "items": String[]
  "quantity": IRandomFortuneInt
}

This defines the item for the IRuleDrop.

• drop: String

  • 🔹Optional - if omitted, defaults to ONE
  • ONE: One item will be randomly selected from the item list to drop.
  • ALL: All items in the item list will drop.

• items: String[]

  • This array contains a list of items, of which one will be randomly selected for the drop. Each item in the list has an equal chance of being selected for the drop.
  • Syntax: domain:path:meta#nbt * quantity, meta may be a wildcard *, see experimental feature below.
  • If the quantity below is omitted or resolves to 1 and an explicit quantity is provided as shown in the item syntax above, the item's explicit quantity will be used.
  • NBT: the best way to generate a string with the proper NBT encoding is to hold the dropped item and use the /dropt hand command
  • 🔸Experimental: OreDict entries in this array, like ore:logWood, are permitted and will be expanded to the best of the system's ability. This feature is experimental and may not produce the desired results.
  • 🔸Experimental: If a wildcard value * is supplied for the meta, the system will attempt to expand that item into all of its valid subtypes. This feature is experimental and may not produce the desired results.

• quantity: IRandomFortuneInt

  • 🔹Optional - if omitted, defaults to 1
  • This uses a random, fortune modified range to determine how many of this item will be dropped if selected.
  • If this is omitted or resolves to 1, the item's explicit quantity will be used if provided.

---

IRuleDropMatchQuantity

This object defines parameters for setting the quantity of a drop to the quantity of an existing drop.

{
  "drops": String[]
}

• drops: String[]
  • 🔹Optional - if omitted, defaults to an empty string array.
  • The quantity of the parent drop will be set to the quantity of the first item in this list to match one of the unmodified dropped items.

---

IBlockState

This object defines a blockstate.

{
  "block": String,
  "properties": Map
}

• block: String
  • 🔹Optional - if omitted, defaults to null.
  • The resource location of the block (domain):(path), ie. minecraft:stone.
• properties: Map
  • 🔹Optional - if omitted, defaults to an empty map.
  • This object contains string values mapped to string keys that represent block properties.
  • For example the properties for a minecraft:log might look like this: {"axis": "y", "variant": "spruce"}.