Block Components Reference

Every custom block file in your behavior pack contains a root object called "minecraft:block". Inside this object, the "components" block holds the default rules for that block. If you do not specify a particular component, the game falls back to hardcoded defaults: the block renders as a standard full cube, mines almost instantly, emits no light, and drops itself when broken.

Components can sit in two places: the main "components" list, which applies to the block at all times, and inside "permutations", which conditionally override or add components based on block states using Molang queries. When a permutation becomes active, its components merge with the base list, replacing any matching keys while leaving unrelated base components intact.

{
  "format_version": "1.20.80",
  "minecraft:block": {
    "description": {
      "identifier": "wiki:polished_basalt_brick",
      "menu_category": {
        "category": "construction"
      }
    },
    "components": {
      "minecraft:destructible_by_mining": {
        "seconds_to_destroy": 2.5
      },
      "minecraft:destructible_by_explosion": {
        "explosion_resistance": 6.0
      },
      "minecraft:map_color": "#3a3a40"
    }
  }
}

Physical components control how entities and the environment interact with your block. In older format versions, properties like block hardness and blast resistance had different names, so you may still see legacy tutorials referencing "minecraft:destroy_time" or "minecraft:explosion_resistance". In modern packs, these have been replaced by "minecraft:destructible_by_mining" and "minecraft:destructible_by_explosion", both of which accept either a boolean (to make a block unbreakable like bedrock) or an object containing numerical values.

Light handling is split into two distinct mechanics: emission and dampening. Emission determines how much light the block casts into surrounding spaces, while dampening controls how much sky or block light is blocked when passing through the block itself. Both take integer values from 0 to 15. A standard opaque stone block dampens 15 levels of light and emits 0, whereas a custom glass block might dampen 0 and emit 0.

In modern Bedrock add-ons, you do not have to declare custom block visuals inside "RP/blocks.json" if you use "minecraft:geometry" and "minecraft:material_instances" in the behavior pack. In Fact, attempting to combine behavior pack visual components with legacy "RP/blocks.json" texture definitions for the same block can cause rendering conflicts. When using "minecraft:geometry", you reference either a custom model identifier from your resource pack's "models/blocks" folder or the built-in "minecraft:geometry.full_block" identifier.

Once a block uses custom geometry, you usually need to adjust its physical bounds to match the model. The game separates bounds into two components: "minecraft:collision_box" (what stops players and entities from walking through) and "minecraft:selection_box" (the wireframe outline that appears when aiming at the block). Both components accept a boolean to disable them entirely, or an object with "origin" and "size" arrays measured in pixels on a 16x16x16 grid.

{
  "format_version": "1.20.80",
  "minecraft:block": {
    "description": {
      "identifier": "wiki:garden_lantern"
    },
    "components": {
      "minecraft:geometry": "geometry.garden_lantern",
      "minecraft:material_instances": {
        "*": {
          "texture": "garden_lantern_tex",
          "render_method": "alpha_test"
        }
      },
      "minecraft:collision_box": {
        "origin": [-4.0, 0.0, -4.0],
        "size": [8.0, 12.0, 8.0]
      },
      "minecraft:selection_box": {
        "origin": [-4.0, 0.0, -4.0],
        "size": [8.0, 12.0, 8.0]
      },
      "minecraft:light_emission": 14,
      "minecraft:light_dampening": 0
    }
  }
}

The "minecraft:transformation" component lets you rotate, scale, and translate your block's geometry and hitboxes without making separate model files for every direction. It accepts "translation", "rotation", and "scale" arrays with X, Y, and Z values. Because block models must stay aligned to the grid, rotation values are strictly limited to 90-degree increments (such as 0, 90, 180, -90). Trying to rotate a block by 45 degrees through this component will fail validation.

Transformations are almost always paired with placement traits or block states inside permutations. For example, if you enable the "minecraft:placement_direction" trait in the block's description, the game automatically tracks which way the player was looking when placing the block. You can then check that state in your permutations and apply a "minecraft:transformation" component to rotate the model to face the player.

Earlier experimental versions of Bedrock allowed JSON event responses like "minecraft:on_interact" or "minecraft:on_player_placing" to run slash commands or trigger block events directly inside the JSON file. Those JSON event triggers were removed from modern format versions. To add interactive behavior, ticking logic, or step effects today, you use the "minecraft:custom_components" component alongside the Scripting API.

Inside your block JSON, "minecraft:custom_components" takes a simple array of namespace-prefixed string identifiers. On the JavaScript or TypeScript side, you listen for the world initialization event and register the matching custom component name using the block component registry. This ties standard lifecycle events—such as a player interacting with the block, breaking it, stepping on it, or a scheduled tick firing—directly to your script functions.

{
  "format_version": "1.21.10",
  "minecraft:block": {
    "description": {
      "identifier": "wiki:interactive_pedestal"
    },
    "components": {
      "minecraft:destructible_by_mining": {
        "seconds_to_destroy": 1.5
      },
      "minecraft:custom_components": [
        "wiki:pedestal_interaction"
      ]
    }
  }
}

Applies to Bedrock Edition 1.20.80 and 1.21+. All components listed on this page are stable and do not require any experimental toggles when using a matching format_version.

Read out of the game itself, so the ids match the version you are building for.