Block Events & Triggers
experimental
FORMAT & MIN ENGINE VERSION 1.20.30
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.30
.
EXPERIMENTAL
Block events require the Holiday Creator Features
experiment to be enabled.
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.
{
"format_version": "1.20.30",
"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"
}
}
}
}
}
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.
"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"
}
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Random Responses
Randomly run event responses.
"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"
}
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Event Responses
add_mob_effect
damage
decrement_stack
die
play_effect
play_sound
remove_mob_effect
run_command
set_block
set_block_at_pos
set_block_state
spawn_loot
swing
teleport
transform_item
trigger
add_mob_effect
Adds a mob effect to a target when triggered.
"wiki:effect_event": {
"add_mob_effect": {
"effect": "poison",
"target": "other",
"duration": 8,
"amplifier": 3
}
}
2
3
4
5
6
7
8
damage
Inflicts a specified damage unto a target in context.
"wiki:damage_event": {
"damage": {
"type": "magic",
"target": "other",
"amount": 4
}
}
2
3
4
5
6
7
decrement_stack
Removes one item from the player's selected stack.
"wiki:remove_one": {
"decrement_stack": {
"ignore_game_mode": true // Optional - Should this affect creative mode players (default is false)
}
}
2
3
4
5
die
Kills the specified target, making the block disappear with no loot or effects if self
is the target.
"wiki:destroy": {
"die": {
"target": "self"
}
}
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.
"wiki:particle_effect": {
"play_effect": {
"effect": "???",
"target": "self"
}
}
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.
"wiki:play_sound": {
"play_sound": {
"sound": "beacon.power",
"target": "self"
}
}
2
3
4
5
6
remove_mob_effect
Removes a target's mob effect when triggered.
"wiki:remove_effect_event": {
"remove_mob_effect": {
"effect": "poison",
"target": "other"
}
}
2
3
4
5
6
run_command
Runs a command onto a target in context.
Use an array to run multiple commands.
"wiki:execute_event": {
"run_command": {
"target": "self", // Optional - 'self' is default (targets block)
"command": "summon pig"
}
}
2
3
4
5
6
Or...
"wiki:execute_event": {
"run_command": {
"target": "self", // Optional - 'self' is default (targets block)
"command": [
"summon pig",
"say Everybody welcome the pig!"
]
}
}
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.
"wiki:place_block": {
"set_block": {
"block_type": "minecraft:grass"
}
}
2
3
4
5
Or...
"wiki:place_block": {
"set_block": {
"block_type": {
"name": "minecraft:trapdoor",
"states": {
"direction": 2,
"open_bit": true
}
}
}
}
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.
"wiki:generate_stone_above": {
"set_block_at_pos": {
"block_type": "minecraft:stone",
"block_offset": [0, 1, 0]
}
}
2
3
4
5
6
Or...
"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]
}
}
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).
"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'"
}
}
2
3
4
5
6
7
spawn_loot
Summons a loot table.
"wiki:drop_loot": {
"spawn_loot": {
"table": "loot_tables/blocks/my_loot_table.json"
}
}
2
3
4
5
swing
Causes the involved actor to swing.
"wiki:swing_arm": {
"swing": {}
}
2
3
teleport
Teleport a target randomly around a destination point.
"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
}
}
2
3
4
5
6
7
8
9
transform_item
Replace the target's selected item.
"wiki:replace": {
"transform_item": {
"transform": "iron_sword"
}
}
2
3
4
5
trigger
Trigger an event on a specified target.
"wiki:trigger_crack": {
"trigger": {
"event": "wiki:crack",
"target": "self"
}
}
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.
minecraft:on_fall_on
minecraft:on_interact
minecraft:on_placed
minecraft:on_player_destroyed
minecraft:on_player_placing
minecraft:on_step_off
minecraft:on_step_on
minecraft:queued_ticking
minecraft:random_ticking
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: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
}
2
3
4
5
6
On Interact
Runs an event when the player interacts with / uses the block.
"minecraft:on_interact": {
"event": "wiki:example_event",
"target": "self", // Optional - 'self' is default (targets block)
"condition": "q.block_state('wiki:boolean_state_example')" // Optional
}
2
3
4
5
On Placed
Runs an event when the block is placed.
"minecraft:on_placed": {
"event": "wiki:example_event",
"target": "self", // Optional - 'self' is default (targets block)
"condition": "q.block_state('wiki:boolean_state_example')" // Optional
}
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:on_player_destroyed": {
"event": "wiki:example_event",
"target": "self", // Optional - 'self' is default (targets block)
"condition": "q.block_state('wiki:boolean_state_example')" // Optional
}
2
3
4
5
On Player Placing
Runs an event as the player places the block.
"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
}
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:on_step_off": {
"event": "wiki:example_event",
"target": "self", // Optional - 'self' is default (targets block)
"condition": "q.block_state('wiki:boolean_state_example')" // Optional
}
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:on_step_on": {
"event": "wiki:example_event",
"target": "self", // Optional - 'self' is default (targets block)
"condition": "q.block_state('wiki:boolean_state_example')" // Optional
}
2
3
4
5
Queued Ticking
Triggers between X and Y amount of ticks inside interval_range
.
"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
}
}
2
3
4
5
6
7
8
9
Random Ticking
Triggers event on every random tick, allowing for behavior like random crop growth.
"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
}
}
2
3
4
5
6
7