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_effectdamagedecrement_stackdieplay_effectplay_soundremove_mob_effectrun_commandset_blockset_block_at_posset_block_statespawn_lootswingteleporttransform_itemtrigger
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_onminecraft:on_interactminecraft:on_placedminecraft:on_player_destroyedminecraft:on_player_placingminecraft:on_step_offminecraft:on_step_onminecraft:queued_tickingminecraft: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
Contributors
