Block components

Block components are JSON objects that are added to a custom block definition in a behavior pack to customize the block's behavior and visuals.

Block components can be applied by adding them to components within minecraft:block in the block's definition file.

Components can also be found in a components object located in objects within the permutations array. This can be used to make a component only active when the permutation's condition evaluates to true.

Tags are used to categorize blocks and allow them to work better with vanilla blocks and items. Both vanilla and custom block tags can be added. Tags are added with other components, as an empty object with the format: "tag:<tag_name>": {}

Example:

"tag:minecraft:is_pickaxe_item_destructible":{}

Permutations are used to make some block components active only under certain conditions. Permutations are defined in the permutations array within minecraft:block, and consist of two properties:

• [String] condition: A molang expression resolving to a boolean, representing when the permutation's components should be active. This is most often a block state query. For example:

"condition":"query.block_state('minecraft:cardinal_direction') == 'north'"

• [NBT Compound / JSON Object] components: The components for this permutation.

Example:

"permutations":[
{
"condition":"query.block_state('minecraft:vertical_half') == 'top'",
"components":{
"minecraft:collision_box":{
"origin":[-8,8,-8],
"size":[16,8,16]
}
}
},
{
"condition":"query.block_state('minecraft:vertical_half') == 'bottom'",
"components":{
"minecraft:collision_box":{
"origin":[-8,0,-8],
"size":[16,8,16]
}
}
}
]

This component is used to define whether a block has an associated block entity. This component can not be specified in entries in the permutations array.

Fields:

• dynamic_properties:
  • Can be true or false determines whether the block entity will store properties, if true the block gains the internal component minecraft:dynamic_properties.

Example:

"minecraft:block_entity":{
"dynamic_properties":true
}

Defines how the block should obstruct chests from opening when placed above one.

Structure:

Example:

"minecraft:chest_obstruction":{
"obstruction_rule":"always"
}

Defines the block's collision box. This component can be specified in 3 ways.

• As a single true or false value:

Example:

"minecraft:collision_box":true

• As a JSON object:

Fields:

• origin:
  • The origin of the collision box. (0,0,0) represents the bottom center of the block.
• size:
  • The size of the collision box. The total size of the collision box may not be larger than 16×24×16.

Example (Bottom half slab collision):

"minecraft:collision_box":{
"origin":[-8,0,-8],
"size":[16,8,16]
}

• As a JSON array:

The array consists of the above object, allowing for the definition of multiple collision boxes.

Example:

"minecraft:collision_box":[
{
"origin":[-8,0,-8],
"size":[16,8,16]
},
{
"origin":[-8,8,-8],
"size":[16,8,8]
}
]

Defines which blocks this block can connect to with the minecraft:connection block trait.

Fields:

• accepts_connections_from:
  • Optional. Which blocks this block can connect to. If omitted, the block accepts connections from all blocks. Allowed values are all, only_fences, and none.
• enabled_directions:
  • Optional. Enables connection in only certain directions, disabling others; available values are north, south, west, and east.

Example:

"minecraft:connection_rule":{
"accepts_connections_from":"only_fences",
"enabled_directions":["north","south","east"]
}

Gives a custom block the functionality of a crafting table.

Fields:

• crafting_tags:
  • An array of recipe tags that this block should be able to craft. There can be at most 64 tags, and each tag can be at most 64 characters.
  • The default tag for vanilla crafting recipes is crafting_table, and custom tags can be specified to allow crafting of recipes with that tag in their definition.
• table_name:
  • The name to display in the crafting table UI. Specified as a localization string, or will resort to a regular string if it can't be resolved.

Example:

"minecraft:crafting_table":{
"crafting_tags":[
"crafting_table",
"custom_crafting_table"
],
"table_name":"Custom Crafting Table"
}

Defines whether the block can be destroyed by explosions, and sets its blast resistance. This component can be defined in two ways.

• As a boolean (true or false) value:

Example:

"minecraft:destructible_by_explosion":false

• As a JSON object:

Fields:

• explosion_resistance:
  • Sets the block's resistance to explosions.
  • Note that the actual blast resistance value of the block is 1/5 of the value set here.

Example (Blast resistance 6, similar to cobblestone):

"minecraft:destructible_by_explosion":{
"explosion_resistance":30
}

Defines whether the block can be mined and sets its hardness. This component can be defined in two ways.

As a boolean (true or false) value:

A value of true makes the block destructible in 0 seconds, making it able to be instant mined. A value of false makes the block indestructible by mining.

Example:

"minecraft:destructible_by_mining":true

As a JSON object:

Structure:

Fields:

• seconds_to_destroy: The amount of time it takes to destroy the block. Note that this sets the block's hardness value, not the actual seconds to destroy!
• item_specific_speeds: Optional. Specific breaking speed values for each item, it is recommended to use tags because manually defining items can make the list unnecessarily long and remove compatibility with the enchantment Efficiency.

Example:

"minecraft:destructible_by_mining":{
"item_specific_speeds":[
{
"item":{
"tags":"q.all_tags('minecraft:is_pickaxe') && q.any_tag('minecraft:diamond_tier','minecraft:netherite_tier')"
},
"destroy_speed":30
},
{
"item":"minecraft:iron_axe",
"destroy_speed":13
}
],
"seconds_to_destroy":100
}

Configures the destruction particles created when the block is destroyed.

Fields:

• particle_count:
  • Optional. Sets the number of particles created when the block destroyed. Default is 100, maximum is 255.
• texture:
  • Optional. The texture to use for the particles. This is a texture name defined in terrain_texture.json. Defaults to the texture of the down material instance.
• tint_method:
  • Optional. The method with which the particles are tinted. Default is none.
  • Can be none, default_foliage, birch_foliage, evergreen_foliage, dry_foliage, grass, or water.

Example:

"minecraft:destruction_particles":{
"particle_count":255,
"texture":"cobblestone",
"tint_method":"none"
}

Sets the display name of the block. If omitted, the default display name is "tile.<block identifier>.name". The name given will try be resolved as a localization string. If it cannot be resolved, it will show as given.

This component is specified as a string.

Example:

"minecraft:display_name":"tile.wiki:custom_block.name"

Sets the visuals of the block when it is embedded, such as in a flowerpot. This component can not be specified in entries in the permutations array.

Fields:

• geometry:
  • A minecraft:geometry component defining the embedded geometry.
• material_instances:
  • A minecraft:material_instances component defining the embedded material.

Example:

"minecraft:embedded_visual":{
"geometry":"minecraft:geometry.full_block",
"material_instances":{
"*":{
"texture":"cobblestone"
}
}
}

Configures the fall distance required to trigger the onEntityFallOn custom component script event. The distance defaults to 1 block if omitted.

Fields:

• min_fall_distance:
  • The distance an entity must fall to trigger the event.

Example:

"minecraft:entity_fall_on":{
"min_fall_distance":2
}

Defines how flammable the block is, in this case, all blocks with this component will burn from fire and lava, unlike vanilla where some blocks do not burn from lava. This component can be defined in two ways.

• As a boolean (true or false) property:

If true, the block can catch fire from nearby blocks. The chance modifier for catching fire is automatically set to 5, and the chance modifier for the block being destroyed by fire is set to 20.

If false (or omitted) the block will only catch fire if directly ignited.

Example:

"minecraft:flammable":true

• As a JSON object:

Fields:

• catch_chance_modifier:
  • Optional. The chance that the block catches fire from a nearby block. Default is 5.
  • If greater than 0, fire on the block will burn until it is destroyed or the fire is put out. If destroy_chance_modifier is 0, the block will burn forever.
  • If 0 the block will eventually burn out (if it isn't destroyed).
• destroy_change_modifier:
  • Optional. The chance the block is destroyed while on fire. Default is 20.
  • If 0, the block will not be destroyed by fire.
• lava_flammable:
  • Optional. Can be always and never.
  • when always the block always burns like lava when never it never burns like small flowers.

Example:

"minecraft:flammable":{
"catch_chance_modifier":5,
"destroy_chance_modifier":20,
"lava_flammable":"always"
}

Indicates that this block can be placed inside a flower pot. The geometry of the block while inside a flower pot is specified by minecraft:geometry by default, but it can be changed with minecraft:embedded_visual. This component is specified as an empty object, and can not be specified in an entry to the permutations array.

Example:

"minecraft:flower_pottable":{}

Describes the block's friction. This component is specified as a decimal number between 0.0 and 9.0.

Example:

"minecraft:friction":0.4

Defines the geometry of the block. There are three vanilla models that can be used: minecraft:geometry.full_block, minecraft:geometry.cross, and minecraft:geometry.full_block_v1. You can also use your own model from a resource pack. This component must be included with minecraft:material_instances. This component can be specified in two ways.

• As a string:

The identifier of the model for the block.

Example:

"minecraft:geometry":"minecraft:geometry.full_block"

• As a JSON object:

Fields:

• bone_visibility:
  • Optional. Defines the visibility of each bone. All bones are visible by default.
  • A key-value map of bone names from the model to molang expressions that result in boolean values.
• culling:
  • Optional. An identifier of a culling definition.
• culling_layer:
  • Optional. A string to group multiple blocks when comparing them in a culling rule. Default is minecraft:culling_layer.undefined but there is also minecraft:culling_layer.leaves as vanilla.
• culling_shape:
  • Optional. An identifier of a voxel shape definition.
  • Vanilla shapes are minecraft:unit_cube, and minecraft:empty.
• identifier:
  • The identifier of the block model to use.
• uv_lock:
  • Optional. Sets whether UVs should be locked to their original rotations, regardless of the minecraft:transformation component.
  • Can be an array of bone names to lock, false (default) which locks none, or true which locks all bones.

Example:

"minecraft:geometry":{
"identifier":"geometry.some_model",
"culling":"wiki:culling.example_block",
"culling_layer":"minecraft:culling_layer.leaves",
"bone_visibility":{
"north_top":false,
"right_corner":"q.block_state('wiki:corner') == 'right'"
},
"uv_lock":["bottom"]
}

Defines the sound of the block's in the note block.

Fields:

• up:
  • The sound the block makes if it's above the note block, by default note.harp.
• down:
  • The sound the block makes if the note block is above the block, by default note.none.

Example:

"minecraft:instrument_sound":{
"up":"note.bit",
"down":"note.bell"
}

Defines the visuals of the block's item form.

Fields:

• geometry:
  • A minecraft:geometry component defining the geometry of the block item.
• material_instances:
  • A minecraft:material_instances component defining the material of the block item.

Example:

"minecraft:item_visual":{
"geometry":"minecraft:geometry.full_block",
"material_instances":{
"*":{
"texture":"cobblestone"
}
}
}

Allows a lead to be attached to the block like a fence and specifies an offset for the leash knot's location.

Fields:

• offset:
  • A Vector3 property (array of three numbers [x, y, z]) that sets the position of the leash knot. [0, 0, 0] represents the bottom center of the block.

Example:

"minecraft:leashable":{
"offset":[0,8,0]
}

Sets the number of light levels that will be dampened by the block. This component is specified as an integer between 0 and 15, where 15 blocks all light.

Example:

"minecraft:light_dampening":15

Sets the light level emitted by the block. This component is specified as an integer between 0 and 15.

Example:

"minecraft:light_emission":14

Defines how the block responds to liquids.

Structure:

Example:

"minecraft:liquid_detection":{
"detection_rules":[
{
"liquid_type":"water",
"can_contain_liquid":false,
"on_liquid_touches":"popped",
"use_liquid_clipping":true
}
]
}

Defines the block's loot table. This component is defined as a string path to the loot table. This component is completely ignored if the block is broken with an item enchanted by Silk Touch, resulting in the block dropping itself.

Example:

"minecraft:loot":"loot_tables/blocks/some_block.json"

Sets the block's color when seen on a map. This component can be defined in three ways.

• As a string:

The hex color value to use for the block's color on a map.

Example:

"minecraft:map_color":"#7A4F0C"

• As an array:

An array of three values between 0 and 255, representing the red, green, and blue color values respectively.

Example:

"minecraft:map_color":[50,205,25]

• As a JSON object:

Fields:

• color:
  • The color to use on the map.
  • This is specified as an RGB array, or an hex string, as described above.
• tint_method:
  • Optional. The method to use to tint the color based on the biome. Available values are none, default_foliage, birch_foliage, evergreen_foliage, dry_foliage, grass, and water.

Example:

"minecraft:map_color":{
"color":"#FEFEFE",
"tint_method":"grass"
}

Defines the materials and textures of the block. This component must be included with minecraft:geometry.

Structure:

Example:

"minecraft:material_instances":{
"*":{
"isotropic":true,
"render_method":"opaque",
"texture":"cobblestone"
}
}

Determines the block's behavior when being pushed or pulled by a piston. If trait minecraft:multi_block is defined, the component cannot be used in permutations, and the only available movement_type are popped, and immovable.

Fields:

• movement_type:
  • How the block will react to a piston.
  • Can be push_pull, push, popped, or immovable.
• sticky:
  • Optional. Whether or not the block affects nearby blocks when pushed or pulled, allowing behavior similar to slime or honey blocks.
  • Can be same, or none. Default is none.

Example:

"minecraft:movable":{
"movement_type":"popped"
}

Defines the conditions in which the block can survive. If the conditions are not met, the block can not be placed, and if it already exists, it will break and drop itself. If trait minecraft:multi_block is defined, the component it cannot be used in permutations.

Structure:

Example:

"minecraft:placement_filter":{
"conditions":[
{
"allowed_faces":["up","down"],
"block_filter":[
{
"tags":"q.any_tag('stone')"
}
]
}
]
}

Defines how the block is affected by precipitation. If the block has minecraft:collision_box that is not false, it will not be possible to use snow_log_no_collision.

Structure:

Example:

"minecraft:precipitation_interactions":{
"precipitation_behavior":"obstruct_rain"
}

Allows the block's model to be randomly offset, similar to short grass. The chosen offset is still subject to the block model limits. Due to current limitations, this component causes the block to be shadowed if it intersects another block.

Structure:

Example:

"minecraft:random_offset":{
"x":{
"steps":0,
"range":{
"max":5,
"min":-5
}
},
"y":{
"steps":4,
"range":{
"max":2,
"min":-1
}
},
"z":{
"steps":0,
"range":{
"max":5,
"min":-5
}
}
}

Defines how the block conducts redstone power.

Structure:

Example:

"minecraft:redstone_conductivity":{
"allows_wire_to_step_down":false,
"redstone_conductor":false
}

Allows the block to consume a redstone signal, sending the onRedstoneUpdate custom component event to scripts when the power changes.

Structure:

Example:

"minecraft:redstone_consumer":{
"min_power":0,
"propagates_power":true
}

Allows the block to produce a redstone signal. If the format version is 1.26.20+, adding it to the permutation also requires adding it to the root component.

Structure:

Example:

"minecraft:redstone_producer":{
"power":15,
"strongly_powered_face":"up",
"connected_faces":["north","south"],
"transform_relative":true
}

Allows the block to be replaced when another block is placed in its position, like short grass. This component is specified as an empty object.

Example:

"minecraft:replaceable":{}

Defines the block's selection box. This component can be defined in two ways.

• As a boolean (true or false) value:

A value of true creates the default full block selection box. A value of false makes the block not selectable by players.

Example:

"minecraft:selection_box":true

• As a JSON object:

Fields:

• origin:
  • The origin of the selection box. (0,0,0) represents the bottom center of the block.
• size:
  • The size of the selection box. The total size of the selection box may not be larger than 16×16×16.

Example (Bottom half slab):

"minecraft:selection_box":{
"origin":[-8,0,-8],
"size":[16,8,16]
}

Defines the shape of the block with regards to how it can support other blocks like torches. This component cannot be used in permutations.

Structure:

Example:

"minecraft:support":{
"shape":"fence"
}

Defines the block's tags available in format version 1.26.20+. Tags are used to categorize blocks and allow them to work better with vanilla blocks and items. Both vanilla and custom block tags can be added. This component is defined as an array.

Structure:

Example:

"minecraft:tags":["minecraft:is_pickaxe_item_destructible","example:custom_tag"]

Sets the block to tick after a certain number of ticks, which will trigger the onTick custom component event. This component is required in order to use the onTick event.

Structure:

Example:

"minecraft:tick":{
"interval_range":[20,100],
"looping":true
}

Transforms the block's geometry, collision box, and selection box. The transformations specified here are still subject to the block model limits.

Structure:

Example:

"minecraft:transformation":{
"rotation":[0,90,0]
}

Custom block components allow for custom blocks to take advantage of script API capabilities. Custom components are registered in scripts using the method StartupEvent.blockComponentRegistry.registerCustomComponent().

Custom components can be added to blocks the same way as any other component, using the namespaced identifier the component was registered with. Custom components can have arguments of any type, which will be passed to scripts as the second argument.

Examples:

"example_namespace:example_component":"foo",
"example_namespace:example_component2":4,
"example_namespace:example_component3":["hello","world"],
"example_namespace:example_component4":true,
"example_namespace:example_component5":{
"stuff":4
}

In scripts, the custom component object can have methods added to listen to any amount of the following events^[1]:

• beforeOnPlayerPlace: Called before the player places the block.
• onBlockStateChange: Called when a block has its state changed.‌^{["Beta APIs" Experiment only]}
• onBreak: Called when the block is destroyed.
• onEntity: Called when an entity sends an event to the block.
• onEntityFallOn: Called when an entity falls onto the block. This requires the minecraft:entity_fall_on component.
• onPlace: Called when the block is placed.
• onPlayerBreak: Called when the block is destroyed by a player.
• onPlayerInteract: Called when a player interacts with the block.
• onRandomTick: Called when the block is randomly ticked.
• onRedstoneUpdate: Called when the block receives a redstone update. This requires the minecraft:redstone_consumer component, and will only be called if the signal power is greater than or equal to the min_power set in the component.
• onStepOff: Called when an entity steps off the block.
• onStepOn: Called when an entity steps on to the block.
• onTick: Called when the block ticks (As specified by the minecraft:tick component).

• Block Components Documentation - Microsoft Learn
• Bedrock Wiki