🎯 碰撞箱（Hitbox）#

#bs.hitbox:help

Work with the hitboxes of blocks and entities.

“能者达人所不达，智者达人所未见。”

—亚瑟·叔本华（Arthur Schopenhauer）

🔧 函数#

你可以在下方找到此模块中的所有可用函数。

Bake entity#

#bs.hitbox:bake_entity

将实体的碰撞箱固化，以便在实体尺寸不变时提升性能。如果实体带有乘客，也会一并固化，并扩大基础实体的碰撞箱以覆盖整个实体堆的边界框。

输入:

Execution as <entities>: entities whose hitbox should be baked

输出:

State: the entity’s hitbox is saved as a baked hitbox for later use

警告

Only use baked hitboxes when you are sure the entity’s size will not change, such as when it cannot grow, scale, gain passengers, or equip items that affect its size.

如果碰撞箱在固化后发生变化，可能导致碰撞检测或逻辑出错。

What is a bounding box?

A bounding box is a simple rectangular box that surrounds an object, or part of it, to help the game figure out where it is and what it touches. For example, a set of stairs in Minecraft uses two bounding boxes: one for the lower step and one for the upper step.

What is a baked hitbox?

固化会捕捉实体碰撞箱在特定时刻的状态，此后不再更新。若实体运载乘客，固化结果将生成一个同时包容基础实体与所有乘客的边界框。

See Hitbox types for full details on block and entity hitboxes.

贡献者：Aksiome

Get block#

#bs.hitbox:get_block_shape

Get the default shape of a block, represented by a list of box coordinates. This shape defines the area where the player can target or interact with the block. Coordinates range from 0 to 16 within a block space, as in block models.

输入:

Execution at <entity> or positioned <x> <y> <z>: position from which to get the block hitbox

输出:

命令存储 bs:out hitbox：

  • block hitbox

    • shape: list of cube coordinates ([[min_x, min_y, min_z, max_x, max_y, max_z]])

    • offset: hitbox offset (used by flowers, for example)

      • x: number describing the X coordinate offset

      • z: number describing the Z coordinate offset

Example: get the shape of an open fence gate (can be targeted, even though you can walk through it)

setblock 0 0 0 minecraft:oak_fence_gate[open=true]
execute positioned 0 0 0 run function #bs.hitbox:get_block_shape
data get storage bs:out hitbox
#bs.hitbox:get_block_collision

获取方块的 collision 形状，以方框坐标列表表示。该形状定义实体无法穿过的方块实体边界。坐标范围为方块空间内的 0 到 16，与方块模型相同。

输入:

Execution at <entity> or positioned <x> <y> <z>: position from which to get the block hitbox

输出:

命令存储 bs:out hitbox：

  • block hitbox

    • shape: list of cube coordinates ([[min_x, min_y, min_z, max_x, max_y, max_z]])

    • offset: hitbox offset (used by flowers, for example)

      • x: number describing the X coordinate offset

      • z: number describing the Z coordinate offset

Example: get the collision of an open fence gate (no collision, entities can pass through)

setblock 0 0 0 minecraft:oak_fence_gate[open=true]
execute positioned 0 0 0 run function #bs.hitbox:get_block_collision
data get storage bs:out hitbox

贡献者：Aksiome

Get entity#

#bs.hitbox:get_entity

获取实体的宽度和高度。

输入:

Execution as <entities>: entity to get the hitbox from

输出:

命令存储 bs:out hitbox：

  • entity hitbox

    • width: width of the entity (X axis)

    • height: height of the entity (Y axis)

    • depth: depth of the entity (Z axis)

    • scale: scaling of the hitbox

备注

对于大多数没有自定义碰撞箱的实体，depth 等于 width。但画、物品展示框等实体的尺寸更为复杂。

Example: get the hitbox of an armor stand

execute summon minecraft:armor_stand run function #bs.hitbox:get_entity
data get storage bs:out hitbox

贡献者：Aksiome

Is entity inside#

#bs.hitbox:is_entity_in_blocks_shape

检查指定实体是否位于任意方块的 default 形状内。

输入:

Execution as <entity>: entity to check

输出:

Return: success or failure

备注

由于实体的包围盒可能跨越多个方块，此函数将检查实体可能接触的所有方块。

Example: check if a summoned cow is inside a block

# Move to the edge of a block, then run
execute summon minecraft:cow if function #bs.hitbox:is_entity_in_blocks_shape run say I'm in the fence
# Since the cow is bigger than the player, you should get a success
#bs.hitbox:is_entity_in_blocks_collision

检查指定实体是否在方块的 collision 碰撞箱内。

输入:

Execution as <entity>: entity to check

输出:

Return: success or failure

备注

由于实体的包围盒可能跨越多个方块，此函数将检查实体可能接触的所有方块。

Example: check if a summoned cow is inside a block

# Move to the edge of a block, then run
execute summon minecraft:cow if function #bs.hitbox:is_entity_in_blocks_collision run say I'm in the fence
# Since the cow is bigger than the player, you should get a success
#bs.hitbox:is_entity_in_block_shape

检查指定实体是否位于执行位置所在方块的 default 形状内。

输入:

Execution as <entity>: entity to check

Execution at <entity> or positioned <x> <y> <z>: position to check

输出:

Return: success or failure

备注

此函数检查实体的边界框是否与执行位置所在的方块相交。它不考虑实体可能接触的其他方块。

Example: check if a summoned cow is inside the fence at your position

setblock ~ ~ ~ minecraft:oak_fence
# Move to the edge of the fence, then run
execute summon minecraft:cow if function #bs.hitbox:is_entity_in_block_shape run say I'm in the fence
# Since the cow is bigger than the player, you should see the message
#bs.hitbox:is_entity_in_block_collision

检查指定实体是否在执行位置所在方块的 collision 碰撞箱内。

输入:

Execution as <entity>: entity to check

Execution at <entity> or positioned <x> <y> <z>: position to check

输出:

Return: success or failure

备注

此函数检查实体的边界框是否与执行位置所在的方块相交。它不考虑实体可能接触的其他方块。

Example: check if a summoned cow is inside the fence at your position

setblock ~ ~ ~ minecraft:oak_fence
# Move to the edge of the fence, then run
execute summon minecraft:cow if function #bs.hitbox:is_entity_in_block_collision run say I'm in the fence
# Since the cow is bigger than the player, you should see the message

贡献者：Aksiome

Is inside#

#bs.hitbox:is_in_block_shape

检查执行位置是否位于方块的 default 形状内。

输入:

Execution at <entity> or positioned <x> <y> <z>: position to check

输出:

Return: success or failure

Example: say “My name is Pavel” if you are inside a block

execute if function #bs.hitbox:is_in_block_shape run say My name is Pavel
#bs.hitbox:is_in_block_collision

检查执行位置是否在方块的 collision 碰撞箱内。

输入:

Execution at <entity> or positioned <x> <y> <z>: position to check

输出:

Return: success or failure

Example: say “My name is Pavel” if you are inside a block

execute if function #bs.hitbox:is_in_block_collision run say My name is Pavel
#bs.hitbox:is_in_entity

Check if the execution position is within the entity executing the command.

输入:

Execution as <entities>: entity to check

Execution at <entity> or positioned <x> <y> <z>: position to check

输出:

Return: success or failure

Example: check if you are inside an entity

execute summon minecraft:cow if function #bs.hitbox:is_in_entity run say Oh no...

贡献者：Aksiome

Reset entity#

#bs.hitbox:reset_entity

Reset an entity’s hitbox to its dynamic form, removing any previously applied baked or custom hitbox.

输入:

Execution as <entities>: entities whose hitbox should be reset

输出:

State: the entity’s hitbox is now dynamic again and will automatically update with scaling, growth, or other changes

贡献者：Aksiome

Set entity#

#bs.hitbox:set_entity {with:{}}

为实体定义自定义碰撞箱，完全控制其尺寸。这样可以设置不受 Minecraft 内置宽度/高度系统限制的碰撞箱，也适用于通常没有碰撞箱的实体。

输入:

Execution as <entities>: entities whose hitbox should be set to custom dimensions

函数宏：

  • arguments

    • with:

      • width: total horizontal size along the X axis

      • height: total vertical size along the Y axis

      • depth: total size along the Z axis. Defaults to the same value as width if not provided

      • centered: whether the hitbox should be vertically centered on the Y axis. Defaults to false, meaning the hitbox starts at the entity’s feet (like in vanilla)

输出:

State: the entity now has a custom axis-aligned bounding box (AABB) hitbox

警告

Custom hitboxes come with a slight performance cost. Use them when you need precise control over shape and position, but avoid using too many of them in the same area.

What is a bounding box?

A bounding box is a simple rectangular box that surrounds an object, or part of it, to help the game figure out where it is and what it touches. For example, a set of stairs in Minecraft uses two bounding boxes: one for the lower step and one for the upper step.

What is a custom hitbox?

自定义碰撞箱允许你覆盖 Minecraft 的默认碰撞箱系统，使用宽度、高度和深度定义自己的形状。与动态或固化碰撞箱不同，自定义碰撞箱具有以下特点：

  • Can have independent width, height, and depth

  • Are not tied to Minecraft’s internal collision model

  • Work on entities without a native hitbox, such as display entities

See Hitbox types for full details on block and entity hitboxes.

贡献者：Aksiome

🏷️ 标签#

You can find below all tags available in this module.

方块#

Physical#

#bs.hitbox:can_pass_through

Blocks without a collision box

#bs.hitbox:has_shape_offset

Blocks with a physical random offset

#bs.hitbox:has_visual_offset

Blocks with a purely visual random offset

#bs.hitbox:intangible

Blocks that cannot be physically interacted with, such as air variants, light blocks, and structure void

#bs.hitbox:is_full_cube

Blocks whose default and collision shapes are both full 16×16×16 cubes

For shape-specific checks, use:

  • #bs.hitbox:is_full_cube_shape

  • #bs.hitbox:is_full_cube_collision

Fluid#

#bs.hitbox:is_fluid

Blocks whose fluid occupies the block space, such as water and lava

#bs.hitbox:is_water

Blocks that represent water itself, such as water and bubble columns

#bs.hitbox:is_waterloggable

Blocks that can contain water through a waterlogged block state

#bs.hitbox:is_waterlogged

Blocks that contain water by default without having a waterlogged block state, such as kelp and seagrass

贡献者：Aksiome

实体#

#bs.hitbox:intangible

Entities that don’t act as physical obstacles, such as projectiles, markers, and displays

#bs.hitbox:is_shaped

Entities with different width and depth, such as paintings and item frames

#bs.hitbox:is_sized

Entities with equal width and depth

贡献者：Aksiome

🎓 Hitbox types#

Bookshelf 提供两种方块碰撞箱和三种实体碰撞箱类型，分别适用于不同场景。了解其差异有助于选择合适类型。

方块#

default 定义玩家可交互或破坏方块的区域：

  • Specifies the zone where right-clicks, mining, or other interactions register

  • Can differ from the collision shape, for example, fence gates keep the same default shape whether open or closed

➔ 通过 #bs.hitbox:get_block_shape 返回

collision 定义方块阻挡实体通过的物理边界。决定实体移动至该方块时的阻挡位置：

  • Matches the block’s solid parts and prevents entities from moving through

  • Can change dynamically depending on block state (e.g., a fence gate’s collision shape differs when open vs closed)

➔ 通过 #bs.hitbox:get_block_collision 返回

实体#

The native Minecraft hitbox, which updates automatically:

  • Adjusts in real time with entity changes like scaling, baby growth, equipment, or new passengers

  • No setup required, this is the default

  • Use when the entity’s shape is expected to change

➔ 通过 #bs.hitbox:reset_entity 恢复

实体碰撞箱在特定时刻的快照：

  • Improves performance when the entity’s size will never change

  • Includes the base entity and all passengers in one combined box. When baking a pile of passengers, the base entity bakes all passengers and sets its hitbox to encompass the entire stack

  • Does not update dynamically, collisions may break if the entity changes later

➔ 通过 #bs.hitbox:bake_entity 设置

完全用户定义的碰撞箱：

  • Set exact width, height, and optional depth

  • Works on entities with no native hitbox (e.g. display entities)

  • Independent from Minecraft’s internal hitbox system

  • Only applies to the base entity. When used with modules that process entity stacks, only the base entity’s hitbox is considered, passengers are ignored

  • Slight performance cost, avoid using too many of them in the same area

➔ 通过 #bs.hitbox:set_entity 设置

🔌 Hitbox providers#

碰撞箱提供者是一种回调函数，用来向 bs.raycast、bs.move 等模块提供方块形状。

提供者可以返回两种形式之一：

  1. 单个标志（例如 return 1），让调用方将该方块视为完整的 16×16×16 立方体。

  2. 一个边界框数组，存储在 bs:lambda hitbox 中：

    {shape:[[min_x, min_y, min_z, max_x, max_y, max_z, flag], ...]}

    每个边界框的坐标范围为 0 到 16，也可以包含一个标志（省略时默认为 1）。

What is a bounding box?

A bounding box is a simple rectangular box that surrounds an object, or part of it, to help the game figure out where it is and what it touches. For example, a set of stairs in Minecraft uses two bounding boxes: one for the lower step and one for the upper step.

标志

标志本身没有固定含义，只是提供者和调用方用于分类边界框的数字标签。可以使用以下任一标志：1、2、4 或 8。

For example, the Bookshelf built-in providers use 1 for solid and 2 for fluids.

Available providers#

All built-in providers have a fluid variant, where 1 represents the solid part and 2 represents the fluid part.

These providers return the block’s default shape as defined in Blocks.

  • #bs.hitbox:callback/get_block_shape

  • #bs.hitbox:callback/get_block_shape_with_fluid

These providers return the block’s collision shape as defined in Blocks.

  • #bs.hitbox:callback/get_block_collision

  • #bs.hitbox:callback/get_block_collision_with_fluid

返回方块的默认形状，并添加一个仅用于放置的边界框（标志4），以复制原版方块放置行为，例如炼药锅、堆肥桶、漏斗和脚手架。

  • #bs.hitbox:callback/get_block_placement

  • #bs.hitbox:callback/get_block_placement_with_fluid

Custom providers#

自定义提供者的常见模式是直接返回自定义形状，或者：

  1. Copy a built-in shape

  2. Modify it

  3. Return it

Example: defining a custom shape with a custom flag

# Custom shape for <my_custom_block>. You can add multiple bounding boxes, each with its own flag, if your block has a complex shape
execute if block ~ ~ ~ <my_custom_block> run return run data modify storage bs:lambda hitbox set value {shape:[[2,2,2,14,14,14,<flag>]]}

# If the block is a full cube, return 1
execute if block ~ ~ ~ #bs.hitbox:is_full_cube run return 1
# Get the shape (step 1)
function #bs.hitbox:get_block_shape
# Copy and return the shape (step 3)
data modify storage bs:lambda hitbox set from storage bs:out hitbox

💬 这对你有帮助吗？

欢迎在下方留下你的问题和反馈！