Block Events & Triggers

experimental

FORMAT & MIN ENGINE VERSION 1.20.60

Using the latest format version when creating custom blocks provides access to fresh features and improvements. The wiki aims to share up-to-date information about custom blocks, and currently targets format version 1.20.60.

EXPERIMENTAL

Block events require the Holiday Creator Features experiment to be enabled.

WARNING

Block events are deprecated, and will be removed in a future update. It is not recommended to use them unless absolutely necessary, as you will need to convert all functionality from them to scripts once they are removed.

Defining Events

Block events allow you to manipulate the game world when certain conditions are met, and are defined in the events child of minecraft:block. Within the event, event responses are listed to configure what you want to happen when the event is triggered.

Event triggers run events when appropriate, carrying out all of their event responses.

BP/blocks/loot_dropper.jsonCopy
json
{
  "format_version": "1.20.60",
  "minecraft:block": {
    "description": {
      "identifier": "wiki:loot_dropper"
    },
    "components": {
      "minecraft:on_step_on": {
        "event": "wiki:drop_loot"
      }
    },
    "events": {
      "wiki:drop_loot": {
        "spawn_loot": {
          "table": "loot_tables/blocks/my_loot_table.json"
        }
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

This example spawns loot when an entity steps onto the block.

Sequenced Responses

Sequences allow you to run the same response multiple times, or to only trigger certain aspects of your event when conditions are met.

All event responses should be contained within the sequence.

minecraft:block > eventsCopy
json
"wiki:my_sequence": {
  "sequence": [
    {
      "set_block_state": {
        "wiki:my_state": true
      }
    },
    {
      "condition": "q.block_state('wiki:my_state')", // Optional
      "trigger": {
        "event": "wiki:my_entity_event",
        "target": "other"
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Random Responses

Randomly run event responses.

minecraft:block > eventsCopy
json
"wiki:random_action": {
  "randomize": [
    {
      "weight": 1, // 1/4 chance
      "set_block_state": {
        "wiki:my_state": true
      }
    },
    {
      "weight": 3, // 3/4 chance
      "trigger": {
        "event": "wiki:my_entity_event",
        "target": "other"
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Event Responses

add_mob_effect

Adds a mob effect to a target when triggered.

minecraft:block > eventsCopy
json
"wiki:effect_event": {
  "add_mob_effect": {
    "effect": "poison",
    "target": "other",
    "duration": 8,
    "amplifier": 3
  }
}
1
2
3
4
5
6
7
8

damage

Inflicts a specified damage unto a target in context.

minecraft:block > eventsCopy
json
"wiki:damage_event": {
  "damage": {
    "type": "magic",
    "target": "other",
    "amount": 4
  }
}
1
2
3
4
5
6
7

decrement_stack

Removes one item from the player's selected stack.

minecraft:block > eventsCopy
json
"wiki:remove_one": {
  "decrement_stack": {
    "ignore_game_mode": true // Optional - Should this affect creative mode players (default is false)
  }
}
1
2
3
4
5

die

Kills the specified target, making the block disappear with no loot or effects if self is the target.

minecraft:block > eventsCopy
json
"wiki:destroy": {
  "die": {
    "target": "self"
  }
}
1
2
3
4
5

play_effect

Play a particle effect at a specified contextual target's position.

Supported effect values are unknown. Using the playsound command with the run_command event response can be used as an alternative.

minecraft:block > eventsCopy
json
"wiki:particle_effect": {
  "play_effect": {
    "effect": "???",
    "target": "self"
  }
}
1
2
3
4
5
6

play_sound

Plays a sound from a specified contextual target.

Supports most vanilla individual sound event IDs from RP/sounds.json, however custom entries will not function.

minecraft:block > eventsCopy
json
"wiki:play_sound": {
  "play_sound": {
    "sound": "beacon.power",
    "target": "self"
  }
}
1
2
3
4
5
6

remove_mob_effect

Removes a target's mob effect when triggered.

minecraft:block > eventsCopy
json
"wiki:remove_effect_event": {
  "remove_mob_effect": {
    "effect": "poison",
    "target": "other"
  }
}
1
2
3
4
5
6

run_command

Runs a command onto a target in context.

Use an array to run multiple commands.

minecraft:block > eventsCopy
json
"wiki:execute_event": {
  "run_command": {
    "target": "self", // Optional - 'self' is default (targets block)
    "command": "summon pig"
  }
}
1
2
3
4
5
6

Or...

minecraft:block > eventsCopy
json
"wiki:execute_event": {
  "run_command": {
    "target": "self", // Optional - 'self' is default (targets block)
    "command": [
      "summon pig",
      "say Everybody welcome the pig!"
    ]
  }
}
1
2
3
4
5
6
7
8
9

set_block

Removes the current block and replaces it with the defined block in the same position.

minecraft:block > eventsCopy
json
"wiki:place_block": {
  "set_block": {
      "block_type": "minecraft:grass"
  }
}
1
2
3
4
5

Or...

minecraft:block > eventsCopy
json
"wiki:place_block": {
  "set_block": {
      "block_type": {
          "name": "minecraft:trapdoor",
          "states": {
              "direction": 2,
              "open_bit": true
          }
      }
  }
}
1
2
3
4
5
6
7
8
9
10
11

set_block_at_pos

Sets a block at a specified position relative to the block.

minecraft:block > eventsCopy
json
"wiki:generate_stone_above": {
  "set_block_at_pos": {
    "block_type": "minecraft:stone",
    "block_offset": [0, 1, 0]
  }
}
1
2
3
4
5
6

Or...

minecraft:block > eventsCopy
json
"wiki:generate_upper_door_above": {
  "set_block_at_pos": {
      "block_type": {
          "name": "minecraft:wooden_door",
          "states": {
              "upper_block_bit": true
          }
      },
      "block_offset": [0, 1, 0]
  }
}
1
2
3
4
5
6
7
8
9
10
11

set_block_state

Set block state value(s) (Can be set to the returned value of a Molang expression string).

WARNING

String values are evaluated as Molang. This means, to set a string state, you must wrap the value in 's (example below).

minecraft:block > eventsCopy
json
"wiki:change_state": {
  "set_block_state": {
    "wiki:boolean_state_example": false,
    "wiki:integer_state_example": "q.block_state('wiki:integer_state_example') + 1",
    "wiki:string_state_example": "'red'"
  }
}
1
2
3
4
5
6
7

spawn_loot

Summons a loot table.

minecraft:block > eventsCopy
json
"wiki:drop_loot": {
  "spawn_loot": {
    "table": "loot_tables/blocks/my_loot_table.json"
  }
}
1
2
3
4
5

swing

Causes the involved actor to swing.

minecraft:block > eventsCopy
json
"wiki:swing_arm": {
  "swing": {}
}
1
2
3

teleport

Teleport a target randomly around a destination point.

minecraft:block > eventsCopy
json
"wiki:go_away": {
  "teleport": {
    "target": "other", // Teleporting entity
    "avoid_water": true, // Avoid teleporting into water
    "land_on_block": true, // Place target on block
    "destination": [0, 0, 0], // Origin destination
    "max_range": [5, 6, 7] // Maximum offsets from the origin destination
  }
}
1
2
3
4
5
6
7
8
9

transform_item

Replace the target's selected item.

minecraft:block > eventsCopy
json
"wiki:replace": {
  "transform_item": {
    "transform": "iron_sword"
  }
}
1
2
3
4
5

trigger

Trigger an event on a specified target.

minecraft:block > eventsCopy
json
"wiki:trigger_crack": {
  "trigger": {
    "event": "wiki:crack",
    "target": "self"
  }
}
1
2
3
4
5
6

Event Triggers

Event triggers are defined as components in your block, so can be added, changed or removed with permutations.

On Fall On

Runs an event when an entity fell on the block.

Note: Requires the minecraft:collision_box component to be 4 or higher on the Y-axis.

minecraft:block > componentsCopy
json
"minecraft:on_fall_on": {
  "event": "wiki:example_event",
  "target": "self", // Optional - 'self' is default (targets block)
  "condition": "q.block_state('wiki:boolean_state_example')", // Optional
  "min_fall_distance": 5
}
1
2
3
4
5
6

On Interact

Runs an event when the player interacts with / uses the block.

minecraft:block > componentsCopy
json
"minecraft:on_interact": {
  "event": "wiki:example_event",
  "target": "self", // Optional - 'self' is default (targets block)
  "condition": "q.block_state('wiki:boolean_state_example')" // Optional
}
1
2
3
4
5

On Placed

Runs an event when the block is placed.

minecraft:block > componentsCopy
json
"minecraft:on_placed": {
  "event": "wiki:example_event",
  "target": "self", // Optional - 'self' is default (targets block)
  "condition": "q.block_state('wiki:boolean_state_example')" // Optional
}
1
2
3
4
5

On Player Destroyed

Runs an event when the player destroys the block from mining. This event doesn't trigger if the player is in creative mode.

minecraft:block > componentsCopy
json
"minecraft:on_player_destroyed": {
  "event": "wiki:example_event",
  "target": "self", // Optional - 'self' is default (targets block)
  "condition": "q.block_state('wiki:boolean_state_example')" // Optional
}
1
2
3
4
5

On Player Placing

Runs an event as the player places the block.

minecraft:block > componentsCopy
json
"minecraft:on_player_placing": {
  "event": "wiki:example_event",
  "target": "self", // Optional - 'self' is default (targets block)
  "condition": "q.block_state('wiki:boolean_state_example')" // Optional
}
1
2
3
4
5

On Step Off

Runs an event when an entity steps off the block.

Note: Requires the minecraft:collision_box component to be 4 or higher on the Y-axis.

minecraft:block > componentsCopy
json
"minecraft:on_step_off": {
  "event": "wiki:example_event",
  "target": "self", // Optional - 'self' is default (targets block)
  "condition": "q.block_state('wiki:boolean_state_example')" // Optional
}
1
2
3
4
5

On Step On

Runs an event when an entity stepped onto the block.

Note: Requires the minecraft:collision_box component to be 4 or higher on the Y-axis.

minecraft:block > componentsCopy
json
"minecraft:on_step_on": {
  "event": "wiki:example_event",
  "target": "self", // Optional - 'self' is default (targets block)
  "condition": "q.block_state('wiki:boolean_state_example')" // Optional
}
1
2
3
4
5

Queued Ticking

Triggers between X and Y amount of ticks inside interval_range.

minecraft:block > componentsCopy
json
"minecraft:queued_ticking": {
  "looping": true,
  "interval_range": [20, 20], // Two values (in ticks) which will be randomly decided between to determine delay duration.
  "on_tick": {
    "event": "wiki:example_event",
    "target": "self", // Optional - 'self' is default (targets block)
    "condition": "q.block_state('wiki:boolean_state_example')" // Optional
  }
}
1
2
3
4
5
6
7
8
9

Random Ticking

Triggers event on every random tick, allowing for behavior like random crop growth.

minecraft:block > componentsCopy
json
"minecraft:random_ticking": {
  "on_tick": {
    "event": "wiki:example_event",
    "target": "self", // Optional - 'self' is default (targets block)
    "condition": "q.block_state('wiki:boolean_state_example')" // Optional
  }
}
1
2
3
4
5
6
7

Contributors

SirLichMedicalJewel105