Every rule is defined by a JSON object with specific fields. If a field is omitted, that specific condition is ignored (i.e., it matches everything).

Input & Output

Output Customization

You can further control the properties of the placed block using these fields.

Item Replacements Properties

When using the item_replacements array, each rule object accepts the following properties to surgically swap items inside NBT lists:

Multi-Block Structures

Use the additional_blocks field to place or remove secondary blocks at specific offsets relative to the main block.

Additional Block Object properties:

• output / outputs: The block ID(s) to place at the offset.
• remove: Boolean. If true, explicitly sets the offset block to Air.
• x_offset, y_offset, z_offset: Integers representing the coordinate offset relative to the original block (Default 0).
• output_nbt: A JSON string representing NBT data to apply to this offset block.
• output_state_properties: A Map to force specific properties on this offset block.
• randomize_properties: A List of properties to randomize for this offset block.

World Conditions

Note: Large radius checks can have a hit on worldgen performance.

Coordinates

Coordinate fields accept simple numbers or relative text.

Coordinate Syntax:

• "64": Absolute coordinate.
• "spawn": The world spawn coordinate.
• "spawn+100": 100 blocks positive from spawn.
• "spawn-50": 50 blocks negative from spawn.

Advanced Logic

State Filters

Use the state_properties field to only replace blocks that match specific states (properties).

"state_properties": {
  "half": "upper",
  "lit": "true"
}

• The key is the property name (e.g., facing, age, layers).
• The value is the required state as a string.

Neighbor Filters

Use the neighbors field to only replace blocks if their neighbors match specific block conditions.

"neighbors": {
  "up": "minecraft:air",
  "sides": ["#minecraft:logs", "minecraft:stone"],
  "down": "#minecraft:dirt"
}

• Keys (Directions & Direction Keywords):
  • Specific Directions: up (or top), down (or bottom), north, south, east, west.
  • any: Matches if at least one of the 6 neighboring blocks satisfies the condition.
  • all: Matches only if all 6 neighboring blocks satisfy the condition.
  • sides or horizontal: Matches if at least one horizontal neighbor (north, south, east, west) satisfies the condition.
  • all_sides or all_horizontal: Matches only if all 4 horizontal neighbors satisfy the condition.
• Values (Block Matching):
  • Single Block ID: "minecraft:air"
  • Block List / Array: ["minecraft:air", "minecraft:cave_air"] (matches if neighbor is any block in the list)
  • Block Tags: Prefix with # (e.g., "#minecraft:logs", "#c:stones")
  • Wildcards & Patterns: Supports wildcard namespaces (e.g., "modid:*" or regex pattern matching).

State Retention

When keep_states is set to true (default), the mod attempts to be smart about how it places the new block by copying the block state (properties) from the original block.

How it works:

The mod looks for properties that exist on both the original block and the replacement block.

• If both blocks share a property definition (e.g., facing, waterlogged, power, lit), the value is copied over.
• If a property exists on the original but not the replacement (or vice versa), it is simply ignored.

Examples:

• Perfect Match (Stair -> Stair): You replace oak_stairs with stone_stairs. Both blocks have facing, half, shape, and waterlogged. The new stairs will face the exact same way and connect exactly like the old ones.
• Partial Match (Chest -> Furnace): You replace a chest with a furnace. Both blocks have the facing property. The furnace will face the same direction as the chest. However, the chest's type property (left/right/single) is ignored because furnaces don't have it.
• No Match (Log -> Furnace): You replace an oak_log with a furnace. Logs use the axis property (x, y, z) for rotation. Furnaces use the facing property (north, south, east, west). Since these properties are different, the furnace will spawn with its default rotation.