Block Components

PLEASE READ

This page will be part of a rewrite to accomodate for the removal of the Holiday Creator Feature experimental toggle. Expect this page to be rewritten or removed when this happens.

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.

Only one instance of each component can be active at once. Duplicate components will be overridden by the latest permutation.

Looking for event trigger components? Find them here!

Applying Components

Block components are used to change how your block appears and functions in the world. They are applied in the components child of minecraft:block or a permutation.

BP/blocks/lamp.jsonCopy
json
{
  "format_version": "1.20.60",
  "minecraft:block": {
    "description": {
      "identifier": "wiki:lamp",
      "menu_category": {
        "category": "items"
      }
    },
    "components": {
      "minecraft:light_dampening": 0,
      "minecraft:light_emission": 15,
      "minecraft:map_color": [210, 200, 190],
      "minecraft:geometry": "geometry.lamp",
      "minecraft:material_instances": {
        "*": {
          "texture": "lamp"
        },
        "shade": {
          "texture": "lamp_shade"
        }
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

Collision Box

The block's entity/particle collision box, measured in pixels - must be contained within the block unit (16×16×16).

  • Origin is measured from the horizontal middle and vertical bottom of your block, extending from the north-east.

  • Size is calculated from the origin point, extending from the north-east.

May also be defined as a boolean:

  • When false, entities can pass through the block.
  • When true, a unit-sized cube is set as the collision.

Default value: true

Released from experiment Holiday Creator Features for format versions 1.19.50 and higher.

minecraft:block > componentsCopy
json
"minecraft:collision_box": {
  "origin": [-8, 0, -8],
  "size": [16, 16, 16]
}
1
2
3
4
minecraft:block > componentsCopy
json
"minecraft:collision_box": false
1

Crafting Table

Turns your block into a crafting table, opening a functional crafting interface when interacted with.

Released from experiment Holiday Creator Features for format versions 1.19.50 and higher.

minecraft:block > componentsCopy
json
"minecraft:crafting_table": {
  "table_name": "Wiki Workbench", // Name shown in crafting menu, can be translated
  "crafting_tags": ["crafting_table", "wiki_workbench"] // Tags to be used within the recipe file
}
1
2
3
4

Destructible by Explosion

How resistant your block is to being destroyed by explosions.

May also be defined as a boolean:

  • When false, the block cannot be exploded.
  • When true, the block has an explosion resistance of 0.

Default value: true

minecraft:block > componentsCopy
json
"minecraft:destructible_by_explosion": {
  "explosion_resistance": 20
}
1
2
3
minecraft:block > componentsCopy
json
"minecraft:destructible_by_explosion": false // Cannot be destroyed by explosions
1

Destructible by Mining

Duration required to destroy block when being mined.

May also be defined as a boolean:

  • When false, the block cannot be mined.
  • When true, the block can be mined instantly.

Default value: true

minecraft:block > componentsCopy
json
"minecraft:destructible_by_mining": {
  "seconds_to_destroy": 0.5
}
1
2
3
minecraft:block > componentsCopy
json
"minecraft:destructible_by_mining": false // Cannot be destroyed by mining
1

Display Name

Language file key that determines text that will be displayed when you hover over the block in your inventory and hotbar.

If the string given does not have a translation, the raw string given will be displayed.

Note: Minecraft may revert to using tile.<identifier>.name in some scenarios.

Released from experiment Holiday Creator Features for format versions 1.19.60 and higher.

minecraft:block > componentsCopy
json
"minecraft:display_name": "tile.example_block.red.name"
1
RP/texts/en_US.langCopy
c
tile.example_block.red.name=Red Example Block
1

Flammable

Describes your block's flammability.

May also be defined as a boolean:

  • When false, the block will not catch on fire or be destroyed by fire.
  • When true, the example values below are used.

Default value: false

minecraft:block > componentsCopy
json
"minecraft:flammable": {
  "catch_chance_modifier": 5, // Affects chance that this block will catch flame when next to a fire
  "destroy_chance_modifier": 20 // Affects chance that this block will be destroyed by flames when on fire
}
1
2
3
4
minecraft:block > componentsCopy
json
"minecraft:flammable": false // Default - your block will not catch fire, but can be directly ignited
1

Friction

Describes your block's friction in a decimal range of 0.0 to 0.9. Less friction means a more slippery surface.

Vanilla value examples:

  • Dirt: 0.4
  • Ice: 0.02

Default value: 0.4

minecraft:block > componentsCopy
json
"minecraft:friction": 0.4
1

Geometry

The model that the block will use. Your model will not have any face culling applied when intersecting with other blocks.

Custom block model limitations:

  • Your block is limited to 30×30×30 pixels in size.

  • At least 1 pixel of your block on each axis must be contained by the base 16×16×16 block.

  • The absolute bounds of the position of your 30×30×30 block are 30 pixels in each direction from the origin. Your block can be placed in any position within these bounds, as long as it adheres to rule #2.

When active:

  • The block becomes breathable.
  • The block no longer conducts redstone power.

Released from experiment Holiday Creator Features for format versions 1.19.40 and higher.

minecraft:block > componentsCopy
json
"minecraft:geometry": "geometry.example_block" // Geometry identifier from file in 'RP/models/entity' or 'RP/models/blocks' folder
1

Bone Visibility

Hide direct child cubes of bones in your model.

Molang expressions must adhere to permutation condition limitations.

Molang expressions supported in bone_visibility for format versions 1.20.10 and higher.

minecraft:block > componentsCopy
json
"minecraft:geometry": {
  "identifier": "geometry.example_block", // Geometry identifier from file in 'RP/models/entity' or 'RP/models/blocks' folder.
  "bone_visibility": {
    "wiki_bone": false, // Hide cubes in this bone
    "conditional_bone": "q.block_state('wiki:example_state') == 3", // Molang expressions can conditionally set visibility
    "another_bone": true // true is the default so has no effect.
  }
}
1
2
3
4
5
6
7
8

Light Dampening

Sets how much the light will be dampened when passed through the block (integer 0-15) - higher value means less light passes through.

Vanilla value examples:

  • Dirt & Tinted Glass: 15
  • Iron Bars & Glass Panes: 0

Default value: 15

minecraft:block > componentsCopy
json
"minecraft:light_dampening": 7
1

Light Emission

Sets how much the light will be emitted by the block (integer 0-15).

Vanilla value examples:

  • Froglight: 15
  • Redstone Torch (lit): 7

Default value: 0

minecraft:block > componentsCopy
json
"minecraft:light_emission": 10
1

Loot

Loot to drop when destroyed (ignored by Silk Touch enchantment).

If omitted, drops the block as an item.

minecraft:block > componentsCopy
json
"minecraft:loot": "loot_tables/blocks/custom_block.json"
1

Map Color

Block's appearance on a map as a hex string or [R, G, B] (0-255) array.

If omitted, the block is ignored by maps.

minecraft:block > componentsCopy
json
"minecraft:map_color": "#ffffff"
1
minecraft:block > componentsCopy
json
"minecraft:map_color": [255, 255, 255]
1

Material Instances

Configuration of your block's rendering, including textures and lighting.

  • All instances must have the same render method.
  • Block faces will unconditionally darken if intersecting another block.

Material instances can be combined with RP/blocks.json entries to create blocks which exhibit opaque-like properties. This is primarily used to enable face culling on custom glass blocks.

Released from experiment Holiday Creator Features for format versions 1.19.40 and higher.

Render Methods

Render methods essentially control how a block appears in the world, much like entity materials. Below are the key properties of each type:

Render MethodTransparencyTranslucencyBackface CullingVanilla Examples
opaque (default)✔️Dirt, Stone, Concrete.
double_sidedN/A - Use for opaque 2D plains.
alpha_test✔️Vines, Rails, Saplings.
blend✔️✔️✔️Glass, Beacon, Honey Block.
  • Transparency - fully see-through areas.

  • Translucency - semi-transparent areas.

    • Transulcent pixel appear opaque in UI rendering.
  • Backface Culling - faces become invisible when viewed from behind.

    • Render methods without backface culling disappear at a distance (based on fog/render distance).
    • Backface culling is always enabled in UI rendering.
minecraft:block > componentsCopy
json
"minecraft:material_instances": {
  // '*' instance required - default instance for your block (also used for destruction particles)
  // Wildcards follow render controller syntax
  // Instance names 'up', 'down', 'north', 'east', 'south' and 'west' are built in
  "*": {
    "texture": "texture_name", // Shortname defined in `RP/textures/terrain_textures.json`
    "render_method": "blend", // One of the render methods in the above table
    "face_dimming": true, // Defaults to true; should faces with this material be dimmed by their direction?
    "ambient_occlusion": true // Defaults to true; should shadows be created based on surrounding blocks?
  }
}
1
2
3
4
5
6
7
8
9
10
11

Custom Instance Names

TIP

Custom material instance names can be defined on the faces of cubes within Blockbench by right-clicking ona cube and opening its Material Instances.

Custom instance names can be defined within material instances, and can be referenced by built-in instance names, or within the block model.

minecraft:block > componentsCopy
json
"minecraft:material_instances": {
  "*": {
    "texture": "texture_name",
    "render_method": "blend" // Must match other instances
  },
  // Custom instance name
  "end": {
    "texture": "texture_name_end",
    "render_method": "blend" // Must match other instances
  },
  "up": "end",
  "down": "end",
  // Instance name defined in model:
  "flower": {
    "texture": "texture_name_flower",
    "render_method": "blend" // Must match other instances
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

Placement Filter

Configure conditions for a block to be able to survive. If these conditions are not met, the block will not be placed, or if the block is already placed, it will pop off.

The block_filter may have up to 64 entries.

If omitted, the block can be placed and survive on any surface.

Released from experiment Holiday Creator Features for format versions 1.19.60 and higher.

minecraft:block > componentsCopy
json
"minecraft:placement_filter": {
  "conditions": [
    {
      "allowed_faces": ["up"], // Can include 'up', 'down', 'north', 'east', 'south', 'west', and 'side'.
      "block_filter": [
        // Test for identifier
        "minecraft:dirt",
        // Test for tags
        { "tags": "!q.any_tag('stone', 'wiki_tag')" }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13

See this page for a list of vanilla tags and relevant blocks.

Selection Box

The selectable area (hitbox) of the block, measured in pixels - must be contained within the block unit (16×16×16).

  • Origin is measured from the horizontal middle and vertical bottom of your block, extending from the north-east.
  • Size is calculated from the origin point, extending from the north-east.

May also be defined as a boolean:

  • When false, entities can pass through the block.
  • When true, a unit-sized cube is set as the collision.

Default value: true

Released from experiment Holiday Creator Features for format versions 1.19.60 and higher.

minecraft:block > componentsCopy
json
"minecraft:selection_box": {
  "origin": [-8, 0, -8],
  "size": [16, 16, 16]
}
1
2
3
4

Or..

minecraft:block > componentsCopy
json
"minecraft:selection_box": false
1

Transformation

Allows for translation (movement), scaling and rotation of blocks - both visual and functional.

Transformed models must not exceed the block geometry limits.

TIP

Lean about rotatable blocks to apply rotation based on how the block is placed, just like furnaces and mob heads!

minecraft:block > componentsCopy
json
"minecraft:transformation": {
  "translation": [-5, 8, 0],
  "rotation": [90, 180, 0],
  "scale": [0.5, 1, 0.5]
}
1
2
3
4
5

Contributors

SirLichKaioga5