hitbox: additional entities

content.hitbox describes additional entities that provide collision for the model. This data is separate from the visual displays in passengers.

The hitbox format

The field is an array of creation command strings. Each string already begins with summon and includes coordinates, entities, and tags. This differs from passengers, which contains SNBT fragments without an outer command.

The illustrative fragment below targets Minecraft 1.21.4: a unit-sized hitbox at the scene origin after substitution with tag=my_model. It follows the current export format.

{
  "hitbox": [
    "summon block_display ~-0.5 ~-1 ~-0.5 {Passengers:[{id:\"minecraft:shulker\",DeathLootTable:\"minecraft:empty\",NoGravity:1b,Silent:1b,NoAI:1b,Invulnerable:1b,AttachFace:0b,active_effects:[{id:\"minecraft:invisibility\",amplifier:0,duration:-1,show_particles:0b}],attributes:[{id:\"minecraft:scale\",base:1}]}],Tags:[\"my_model\",\"my_model_hitbox\",\"my_model_hitbox_0\"]}"
  ]
}

In a full export, the field appears when there are hitboxes to export. If there are none, it may be absent; do not require an empty array.

Reading the example

Command element	Purpose
summon block_display	Creates the entity carrying the hitbox
~-0.5 ~-1 ~-0.5	Relative position calculated by the exporter for this example
Passengers with minecraft:shulker	Entity providing collision
active_effects	Makes the shulker invisible
NoGravity, NoAI, Silent, Invulnerable	Configure helper entity behavior
DeathLootTable	Prevents the hitbox from dropping items
minecraft:scale	Collision scale in versions that support it
my_model_hitbox_0	Identifies this hitbox, including in animation commands

The coordinates already account for the export offset and hitbox size. Do not replace them with visual display coordinates: these are different entities with different data. ~ makes the coordinates relative to the command’s execution position.

Effect and attribute NBT depends on the selected Minecraft version. In particular, hitbox scaling is supported by exports targeting Minecraft 1.20.5 and later. Older targets use unit size without a scale attribute. Do not reuse the example’s syntax for another version without considering content.version.

Purpose and boundaries

A hitbox provides physical collision. Clickable interaction areas, seats, and the editor’s interaction commands do not become hitbox entries. The current exporter does not include their creation logic or handlers in server JSON.

An animated hitbox may have position and scale commands in datapack.anim_keyframes. The hitbox field itself contains initial creation commands. It does not start animations or provide a universal mechanism for removing an instance.

See anim_keyframes and sound_keyframes for event data and Export support and limitations for other limitations.