Bedrock Wiki
Beginner's Guide
Animation Controllers
Blocks
Commands
Concepts
Documentation
Entities
Items
JSON UI
Loot, Recipes & Trading
Meta
NBT
Particles
Scripting
Servers
Text & Localization
Visuals
World Generation

Custom Heads

expert
Custom Heads
Download Example
Download as ZIP Download as MCADDON

FORMAT VERSION 1.26.40

This tutorial assumes an advanced understanding of blocks and items. Check out the blocks guide, block states and block events before starting.

In this tutorial you will learn how to create your own mob head blocks.

Features:

  • Able to face any of 16 directions when placed on the ground and attach to the side faces of adjacent blocks.
  • Able to be worn on the heads of entities, hiding players on the locator bar and maps.
  • Drops as an item when the appropriate mob is exploded by a charged creeper.

Issues:

  • Custom heads cannot be used to craft firework stars.
  • When enchanted, custom heads lack an enchantment glint outside of the user interface.

By the end of this tutorial, you should have created something like this:

A charged creeper, surrounded by husk heads, waiting eagerly outside a desert villager's house

Block Model ​

Here's the JSON code for a basic 8×8×8 head model, where each face of the block should have a separate 8×8 texture defined by material instances.

Example Head Model
📝 RP/models/blocks/custom_head.geo.json
json
{
    "format_version": "1.26.40",
    "minecraft:geometry": [
        {
            "description": {
                "identifier": "geometry.custom_head",
                "texture_width": 8,
                "texture_height": 8
            },
            "item_display_transforms": {
                "gui": {
                    "fit_to_frame": false,
                    "rotation": [30, 225, 0],
                    "scale": [1, 1, 1],
                    "translation": [0, 3, 0]
                },
                "fixed": {
                    "scale": [1, 1, 1],
                    "translation": [0, 4, 0]
                },
                "ground": {
                    "scale": [0.5, 0.5, 0.5],
                    "translation": [0, 3, 0]
                },
                "firstperson_righthand": {
                    "rotation": [0, 180, 0],
                    "scale": [1, 1, 1]
                },
                "thirdperson_righthand": {
                    "rotation": [45, 225, 0],
                    "scale": [0.5, 0.5, 0.5],
                    "translation": [0, 3, 0]
                },
                "head": {
                    "scale": [1.9, 1.9, 1.9],
                    "translation": [0, 8, 0]
                }
            },
            "bones": [
                {
                    "name": "head",
                    "pivot": [0, 0, 0],
                    "cubes": [
                        {
                            "origin": [-4, 0, -4],
                            "size": [8, 8, 8],
                            "uv": {
                                "north": { "uv": [0, 0], "uv_size": [8, 8] },
                                "east": { "uv": [0, 0], "uv_size": [8, 8] },
                                "south": { "uv": [0, 0], "uv_size": [8, 8] },
                                "west": { "uv": [0, 0], "uv_size": [8, 8] },
                                "up": { "uv": [0, 0], "uv_size": [8, 8] },
                                "down": { "uv": [0, 8], "uv_size": [8, -8] }
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

Initial Block JSON ​

Note that the block description does not have the menu_category parameter as that will be defined in the item JSON instead in a later step.

📝 BP/blocks/custom_head.json
json
{
    "format_version": "1.26.40",
    "minecraft:block": {
        "description": {
            "identifier": "wiki:custom_head"
        },
        "components": {
            // Collision and selection boxes
            "minecraft:collision_box": {
                "origin": [-4, 0, -4],
                "size": [8, 8, 8]
            },
            "minecraft:selection_box": {
                "origin": [-4, 0, -4],
                "size": [8, 8, 8]
            },
            // Prevents blocks (such as fences) from connecting to the block
            "minecraft:connection_rule": {
                "accepts_connections_from": "none"
            },
            // Prevents the block from being placed on the bottom face of another block
            "minecraft:placement_filter": {
                "conditions": [{ "allowed_faces": ["up", "south", "north", "west", "east"] }]
            },
            // Prevents snow from accumulating above the block
            "minecraft:precipitation_interactions": {
                "precipitation_behavior": "none"
            },
            // Destruction
            "minecraft:destructible_by_explosion": {
                "explosion_resistance": 5
            },
            "minecraft:destructible_by_mining": {
                "seconds_to_destroy": 1
            },
            "minecraft:destruction_particles": {
                "particle_count": 48,
                "texture": "soul_sand"
            },
            // Break and drop as an item when pushed by a piston
            "minecraft:movable": {
                "movement_type": "popped"
            },
            "minecraft:liquid_detection": {
                "detection_rules": [
                    {
                        "liquid_type": "water",
                        "can_contain_liquid": true, // Allows the block to be waterlogged
                        "on_liquid_touches": "popped" // Break and drop as an item when water flows into the block
                    }
                ]
            },
            // Visuals
            "minecraft:material_instances": {
                "down": {
                    "texture": "wiki:custom_head_bottom",
                    "ambient_occlusion": 0
                },
                "up": {
                    "texture": "wiki:custom_head_top",
                    "ambient_occlusion": 0
                },
                "north": {
                    "texture": "wiki:custom_head_front",
                    "ambient_occlusion": 0
                },
                "south": {
                    "texture": "wiki:custom_head_back",
                    "ambient_occlusion": 0
                },
                "west": {
                    "texture": "wiki:custom_head_left",
                    "ambient_occlusion": 0
                },
                "east": {
                    "texture": "wiki:custom_head_right",
                    "ambient_occlusion": 0
                }
            }
        }
    }
}

Enabling the Direction States ​

Mob heads use two types of block orientation. They can be attached to the sides of adjacent blocks, or placed on the ground facing one of 16 directions.

To support this, we'll need to add two direction states to our block:

  • For 16-way rotation when placed on the ground, we will use the placement direction trait to enable the minecraft:sixteen_way_rotation state.
  • For block face attachment, we will use the placement position trait to enable the minecraft:block_face state.
📝 BP/blocks/custom_head.json
minecraft:blockdescription
json
"traits": {
    "minecraft:placement_direction": {
        "enabled_states": ["minecraft:sixteen_way_rotation"],
        "y_rotation_offset": 180
    },
    "minecraft:placement_position": {
        "enabled_states": ["minecraft:block_face"]
    }
}

Applying Block Rotation ​

Ground Rotation ​

First, we'll make use of the N-way rotation geometry feature to apply 16-way rotation when the head is placed on top of another block.

📝 BP/blocks/custom_head.json
minecraft:blockcomponents
json
"minecraft:geometry": {
    "identifier": "geometry.custom_head",
    "n_way_visual_rotation": {
        "y": "minecraft:sixteen_way_rotation"
    }
}

Wall Attachment ​

Now, use the permutations array to define the rotation for the base cardinal rotations of the block by inserting the following into your block permutations array (in the presented order):

📝 BP/blocks/custom_head.json
minecraft:block
json
"permutations": [
    // Disable N-way rotation when placed on a side face
    {
        "condition": "q.block_state('minecraft:block_face') != 'up'",
        "components": {
            "minecraft:geometry": "geometry.custom_head"
        }
    },
    // Block face attachments
    {
        "condition": "q.block_state('minecraft:block_face') == 'north'",
        "components": {
            "minecraft:transformation": {
                "rotation": [0, 0, 0],
                "translation": [0, 0.25, 0.25]
            }
        }
    },
    {
        "condition": "q.block_state('minecraft:block_face') == 'west'",
        "components": {
            "minecraft:transformation": {
                "rotation": [0, 90, 0],
                "translation": [0.25, 0.25, 0]
            }
        }
    },
    {
        "condition": "q.block_state('minecraft:block_face') == 'south'",
        "components": {
            "minecraft:transformation": {
                "rotation": [0, 180, 0],
                "translation": [0, 0.25, -0.25]
            }
        }
    },
    {
        "condition": "q.block_state('minecraft:block_face') == 'east'",
        "components": {
            "minecraft:transformation": {
                "rotation": [0, -90, 0],
                "translation": [-0.25, 0.25, 0]
            }
        }
    }
]

Final Block JSON ​

Custom Head Block JSON
📝 BP/blocks/custom_head.json
json
{
    "format_version": "1.26.40",
    "minecraft:block": {
        "description": {
            "identifier": "wiki:custom_head",
            "traits": {
                "minecraft:placement_direction": {
                    "enabled_states": ["minecraft:sixteen_way_rotation"],
                    "y_rotation_offset": 180
                },
                "minecraft:placement_position": {
                    "enabled_states": ["minecraft:block_face"]
                }
            }
        },
        "components": {
            // Collision and selection boxes
            "minecraft:collision_box": {
                "origin": [-4, 0, -4],
                "size": [8, 8, 8]
            },
            "minecraft:selection_box": {
                "origin": [-4, 0, -4],
                "size": [8, 8, 8]
            },
            // Prevents blocks (such as fences) from connecting to the block
            "minecraft:connection_rule": {
                "accepts_connections_from": "none"
            },
            // Prevents the block from being placed on the bottom face of another block
            "minecraft:placement_filter": {
                "conditions": [{ "allowed_faces": ["up", "south", "north", "west", "east"] }]
            },
            // Prevents snow from accumulating above the block
            "minecraft:precipitation_interactions": {
                "precipitation_behavior": "none"
            },
            // Destruction
            "minecraft:destructible_by_explosion": {
                "explosion_resistance": 5
            },
            "minecraft:destructible_by_mining": {
                "seconds_to_destroy": 1
            },
            "minecraft:destruction_particles": {
                "particle_count": 48,
                "texture": "soul_sand"
            },
            // Break and drop as an item when pushed by a piston
            "minecraft:movable": {
                "movement_type": "popped"
            },
            "minecraft:liquid_detection": {
                "detection_rules": [
                    {
                        "liquid_type": "water",
                        "can_contain_liquid": true, // Allows the block to be waterlogged
                        "on_liquid_touches": "popped" // Break and drop as an item when water flows into the block
                    }
                ]
            },
            // Visuals
            "minecraft:material_instances": {
                "down": {
                    "texture": "wiki:custom_head_bottom",
                    "ambient_occlusion": 0
                },
                "up": {
                    "texture": "wiki:custom_head_top",
                    "ambient_occlusion": 0
                },
                "north": {
                    "texture": "wiki:custom_head_front",
                    "ambient_occlusion": 0
                },
                "south": {
                    "texture": "wiki:custom_head_back",
                    "ambient_occlusion": 0
                },
                "west": {
                    "texture": "wiki:custom_head_left",
                    "ambient_occlusion": 0
                },
                "east": {
                    "texture": "wiki:custom_head_right",
                    "ambient_occlusion": 0
                }
            },
            "minecraft:geometry": {
                "identifier": "geometry.custom_head",
                "n_way_visual_rotation": {
                    "y": "minecraft:sixteen_way_rotation"
                }
            }
        },
        "permutations": [
            // Disable N-way rotation when placed on a side face
            {
                "condition": "q.block_state('minecraft:block_face') != 'up'",
                "components": {
                    "minecraft:geometry": "geometry.custom_head"
                }
            },
            // Block face attachments
            {
                "condition": "q.block_state('minecraft:block_face') == 'north'",
                "components": {
                    "minecraft:transformation": {
                        "rotation": [0, 0, 0],
                        "translation": [0, 0.25, 0.25]
                    }
                }
            },
            {
                "condition": "q.block_state('minecraft:block_face') == 'west'",
                "components": {
                    "minecraft:transformation": {
                        "rotation": [0, 90, 0],
                        "translation": [0.25, 0.25, 0]
                    }
                }
            },
            {
                "condition": "q.block_state('minecraft:block_face') == 'south'",
                "components": {
                    "minecraft:transformation": {
                        "rotation": [0, 180, 0],
                        "translation": [0, 0.25, -0.25]
                    }
                }
            },
            {
                "condition": "q.block_state('minecraft:block_face') == 'east'",
                "components": {
                    "minecraft:transformation": {
                        "rotation": [0, -90, 0],
                        "translation": [-0.25, 0.25, 0]
                    }
                }
            }
        ]
    }
}

Item JSON ​

In order to make our custom head wearable and enchantable, we'll need to replace its block item by adding a new item definition to our pack:

📝 BP/items/custom_head.json
json
{
    "format_version": "1.26.40",
    "minecraft:item": {
        "description": {
            "identifier": "wiki:custom_head", // Must be the same identifier as the block
            "menu_category": {
                "category": "items",
                "group": "minecraft:itemGroup.name.skull"
            }
        },
        "components": {
            "minecraft:block_placer": {
                "block": "wiki:custom_head", // Must be the same identifier as the block
                "replace_block_item": true
            },
            // Use the same localization key as the block
            "minecraft:display_name": {
                "value": "tile.wiki:custom_head.name"
            },
            // Allows the head to be enchanted with "Curse of Binding" and "Curse of Vanishing"
            "minecraft:enchantable": {
                "slot": "cosmetic_head",
                "value": 0
            },
            "minecraft:max_stack_size": 64, // Allows the item to be stacked
            "minecraft:rarity": "uncommon",
            // Allows the item to be equipped into the head slot
            "minecraft:wearable": {
                "hides_player_location": true, // Hides the player from the locator bar and maps like vanilla heads
                "slot": "slot.armor.head"
            }
        }
    }
}

Great! Now we're able to equip the block into the head slot:

Charged Creeper Drops ​

scripting

If a vanilla mob has a mob head associated with it, that head will drop as an item when the entity is exploded by a charged creeper.

You can use the following script to add drops for any custom heads.

📝 BP/scripts/headDrops.js
js
import { world, system, ItemStack } from "@minecraft/server";

// Object where keys are entity types and values are the item to drop when exploded by a charged creeper
const heads = {
    "minecraft:husk": "wiki:custom_head",
};

// Set containing the unique IDs of charged creepers that have exploded within the last tick
const explodingChargedCreepers = new Set();

world.beforeEvents.explosion.subscribe(({ source }) => {
    if (!source) return;

    const isCreeper = source.typeId === "minecraft:creeper";
    const isCharged = source.hasComponent("minecraft:is_charged");

    if (isCreeper && isCharged) {
        // Add the charged creeper's ID to the set
        explodingChargedCreepers.add(source.id);

        // Remove the ID after the next tick
        system.runTimeout(() => explodingChargedCreepers.delete(source.id), 1);
    }
});

world.afterEvents.entityDie.subscribe(
    (event) => {
        const { damagingEntity } = event.damageSource;
        if (!damagingEntity || !world.gameRules.doMobLoot) return;

        // Check whether the damaging entity is one of the charged creepers that exploded within the last tick
        const explodedByChargedCreeper = explodingChargedCreepers.has(damagingEntity.id);

        if (explodedByChargedCreeper) {
            const { dimension, location, typeId } = event.deadEntity;
            const head = heads[typeId];

            dimension.spawnItem(new ItemStack(head), location);
        }
    },
    { entityTypes: Object.keys(heads) }
);

Remember to import the scripts into your entry file and set up scripts in BP/manifest.json if you haven't already!

📝 BP/scripts/index.js
js
import "./headDrops.js";

Result ​

What you have created:

  • A block with 16 supported direction state values when placed on the ground, along with 4 side attachments
  • A block item that can be worn and enchanted
  • A custom head drop system for charged creeper explosions
Custom head blocks in a square formation, each pointing towards the middle

Contributors

Edit Custom Heads on GitHub

Text and image content on this page is licensed under the Creative Commons Attribution 4.0 International License

Code samples on this page are licensed under the MIT License