Block Traits Reference

In older format versions, orienting a block required declaring a custom property in the description and using an on_player_placing event trigger with Molang queries to set that property. After the removal of legacy block events in recent format versions, block traits became the standard, stable way to handle placement orientation without needing the Script API.

Traits live inside the traits object under description in your behavior pack block JSON. When you enable a trait, it injects one or more vanilla block states under the minecraft: namespace onto your block. Even though you do not list these states in the states object yourself, they become part of the block's permutation table and can be queried in your permutations array using the q.block_state() Molang function.

Keep in mind that every state injected by a trait multiplies your block's total permutation count. A block with a 6-way facing state and a 3-way position state already uses 18 permutations before you add any custom states of your own.

The minecraft:placement_direction trait captures the direction of the player placing the block. It uses an enabled_states array to let you choose whether you want full 3D rotation or horizontal-only rotation.

You can enable minecraft:cardinal_direction for four horizontal directions (north, south, east, west), or minecraft:facing_direction for all six directions (including up and down). You can also optionally set y_rotation_offset in degrees to change how the block aligns relative to the player. For example, an offset of 180 makes the front of the block face toward the player placing it, matching how vanilla furnaces and chests behave.

While placement_direction cares about where the player is looking, the minecraft:placement_position trait cares about the exact spot on an existing block face that the player clicked to place the new block.

This trait also requires an enabled_states array, which accepts minecraft:block_face and minecraft:vertical_half. The block_face state records which side of the supporting block was clicked (useful for torches, buttons, or directional logs). The vertical_half state records whether the player clicked the upper half or lower half of a block's side, or against a floor or ceiling (useful for slabs and stairs).

Adding a trait to the description only records the state on the block when placed; it does not visually rotate your model on its own. To make the block actually turn, you must read the trait's state inside the permutations array and apply a minecraft:transformation component.

In the example below, a custom statue block uses minecraft:placement_direction with minecraft:cardinal_direction and a 180-degree offset so it always faces the player who placed it. Each permutation checks q.block_state('minecraft:cardinal_direction') and rotates the model around the Y axis accordingly. Note that the default north face of a standard Blockbench model faces north in-game with a rotation of [0, 0, 0].

{
  "format_version": "1.20.60",
  "minecraft:block": {
    "description": {
      "identifier": "wiki:stone_statue",
      "traits": {
        "minecraft:placement_direction": {
          "enabled_states": [
            "minecraft:cardinal_direction"
          ],
          "y_rotation_offset": 180.0
        }
      }
    },
    "components": {
      "minecraft:geometry": "geometry.stone_statue",
      "minecraft:material_instances": {
        "*": {
          "texture": "stone_statue",
          "render_method": "alpha_test"
        }
      },
      "minecraft:destructible_by_mining": {
        "seconds_to_destroy": 2.0
      }
    },
    "permutations": [
      {
        "condition": "q.block_state('minecraft:cardinal_direction') == 'north'",
        "components": {
          "minecraft:transformation": {
            "rotation": [0, 0, 0]
          }
        }
      },
      {
        "condition": "q.block_state('minecraft:cardinal_direction') == 'south'",
        "components": {
          "minecraft:transformation": {
            "rotation": [0, 180, 0]
          }
        }
      },
      {
        "condition": "q.block_state('minecraft:cardinal_direction') == 'west'",
        "components": {
          "minecraft:transformation": {
            "rotation": [0, 90, 0]
          }
        }
      },
      {
        "condition": "q.block_state('minecraft:cardinal_direction') == 'east'",
        "components": {
          "minecraft:transformation": {
            "rotation": [0, 270, 0]
          }
        }
      }
    ]
  }
}

A common use for minecraft:placement_position is building a custom slab that can be placed on either the bottom or the top half of a block space. By enabling minecraft:vertical_half, the game handles the placement math for you.

Instead of making two separate geometry files for the top and bottom slab, you can use a single bottom-slab geometry and shift it up by 8 pixels (0.5 blocks in translation units) using the translation field inside minecraft:transformation when the state is top. When you translate the visual geometry with minecraft:transformation, the block's default collision and selection boxes move along with it automatically.

{
  "format_version": "1.20.60",
  "minecraft:block": {
    "description": {
      "identifier": "wiki:mossy_tile_slab",
      "traits": {
        "minecraft:placement_position": {
          "enabled_states": [
            "minecraft:vertical_half"
          ]
        }
      }
    },
    "components": {
      "minecraft:geometry": "geometry.custom_bottom_slab",
      "minecraft:material_instances": {
        "*": {
          "texture": "mossy_tile",
          "render_method": "opaque"
        }
      },
      "minecraft:collision_box": {
        "origin": [-8, 0, -8],
        "size": [16, 8, 16]
      },
      "minecraft:selection_box": {
        "origin": [-8, 0, -8],
        "size": [16, 8, 16]
      }
    },
    "permutations": [
      {
        "condition": "q.block_state('minecraft:vertical_half') == 'top'",
        "components": {
          "minecraft:transformation": {
            "translation": [0.0, 0.5, 0.0]
          }
        }
      }
    ]
  }
}

Stable in format_version 1.20.20 and higher. No experimental toggles are required.

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