🎯 碰撞箱（Hitbox）#

#bs.hitbox:help

获取并检查方块或实体的碰撞箱。

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

—亚瑟·叔本华（Arthur Schopenhauer）

🔧 函数#

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

烘培实体#

#bs.hitbox:bake_entity

Bake an entity’s hitbox to improve performance when its size never changes. If the entity has passengers, they are also baked, and the base entity’s hitbox is expanded to include the full bounding box of the entire stack.

输入:

执行 as <entities>: 要烘培碰撞箱的实体。

输出:

状态：实体的碰撞箱将以烘焙状态保存，供后续使用。

警告

Only use baked hitboxes when you are sure the entity’s size will not change, for example: no growth (babies), no scaling, no new passengers, and no equipment that could affect 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.

什么是烘焙碰撞箱？

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

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 interact with or aim at the block. Coordinates range from 0 to 16 within a block space, as in block models.

输入:

执行 at <实体> 或 positioned <x> <y> <z>：要获取方块碰撞箱的位置。

输出:

命令存储 bs:out hitbox：

  • 方块碰撞箱

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

    • offset: 碰撞箱偏移 (用于花草等方块的偏移)。

      • x: x轴坐标的偏移量。

      • z: z轴坐标的偏移量。

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

Get the collision shape of a block, represented by a list of box coordinates. This shape defines the solid boundaries of the block that entities cannot pass through. Coordinates range from 0 to 16 within a block space, as in block models.

输入:

执行 at <实体> 或 positioned <x> <y> <z>：要获取方块碰撞箱的位置。

输出:

命令存储 bs:out hitbox：

  • 方块碰撞箱

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

    • offset: 碰撞箱偏移 (用于花草等方块的偏移)。

      • x: x轴坐标的偏移量。

      • z: z轴坐标的偏移量。

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

获取实体的宽度和高度。

输入:

执行 as <实体>：要获取碰撞箱的实体。

输出:

命令存储 bs:out hitbox：

  • 实体碰撞箱数据

    • width: 实体的宽度。

    • height：实体的高度。

    • width: 实体的宽度。

    • scale: 实体碰撞箱的缩放。

备注

For most entities without a custom hitbox, depth is equal to width. However, some entities like paintings and item frames return more complex dimensions.

示例：获取盔甲架的碰撞箱：

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

制作人员：Aksiome

实体是否在内部#

#bs.hitbox:is_entity_in_blocks_shape

Check if the specified entity is within the default shape of any block.

输入:

执行 as <实体>：要检查的实体。

输出:

返回值：成功或失败。

备注

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

示例：检查召唤的牛是否在方块内部：

# 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

Check if the specified entity is within the collision shape of any block.

输入:

执行 as <实体>：要检查的实体。

输出:

返回值：成功或失败。

备注

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

示例：检查召唤的牛是否在方块内部：

# 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

Check if the specified entity is within the default shape of the block at the execution position.

输入:

执行 as <实体>：要检查的实体。

执行 at <实体> 或 positioned <x> <y> <z>：要检查的位置。

输出:

返回值：成功或失败。

备注

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

示例：检查召唤的牛是否在你所在位置的栅栏内部：

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

Check if the specified entity is within the collision shape of the block at the execution position.

输入:

执行 as <实体>：要检查的实体。

执行 at <实体> 或 positioned <x> <y> <z>：要检查的位置。

输出:

返回值：成功或失败。

备注

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

示例：检查召唤的牛是否在你所在位置的栅栏内部：

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

是否在内部#

#bs.hitbox:is_in_block_shape

Check if the execution position is within the default shape of a block.

输入:

执行 at <实体> 或 positioned <x> <y> <z>：要检查的位置。

输出:

返回值：成功或失败。

示例：如果你在方块内部，说“My name is Pavel”：

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

Check if the execution position is within the collision shape of a block.

输入:

执行 at <实体> 或 positioned <x> <y> <z>：要检查的位置。

输出:

返回值：成功或失败。

示例：如果你在方块内部，说“My name is Pavel”：

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

检查执行位置是否在执行命令的实体内部。

输入:

执行 as <实体>：要检查的实体。

执行 at <实体> 或 positioned <x> <y> <z>：要检查的位置。

输出:

返回值：成功或失败。

示例：检查你是否在实体内部：

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

制作人员：Aksiome

重置实体#

#bs.hitbox:reset_entity

将实体的碰撞箱重置为默认的动态形式，移除所有先前应用的烘焙或自定义碰撞箱。

输入:

执行 as <实体>：要重置碰撞箱的实体。

输出:

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

制作人员：Aksiome

设置实体#

#bs.hitbox:set_entity

Define a custom hitbox for an entity with full control over its dimensions. This allows setting a hitbox not constrained by Minecraft’s built-in width/height system and can be used on entities that normally have no hitbox.

输入:

执行 as <实体>：要设置自定义碰撞箱尺寸的实体。

函数宏：

  • 参数

    • with：碰撞箱数据。

      • width：沿X轴的总水平尺寸。

      • height：沿Y轴的总垂直尺寸。

      • depth：沿Z轴的总尺寸。若未提供则默认与width相同。

      • centered：碰撞箱是否应在Y轴上垂直居中。默认为false，表示碰撞箱从实体脚部开始（与原版相同）。

输出:

输出状态：实体现在拥有自定义的轴对齐边界框（AABB）碰撞箱。

警告

自定义碰撞箱会带来轻微性能开销。仅在需要精确控制形状和位置时使用，避免在同一区域使用过多自定义碰撞箱。

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.

什么是自定义碰撞箱？

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

  • 可自由塑形，包括沿Z轴（深度）方向。

  • 不受Minecraft内部碰撞模型约束。

  • 适用于无原生碰撞箱的实体，如显示实体。

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

制作人员：Aksiome

🏷️ 标签#

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

方块#

#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 that are full 16×16×16 cubes.

制作人员：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

🎓 碰撞箱类型#

Bookshelf provides multiple hitbox types, each suited to different use cases. Understanding the differences helps you choose the right one.

方块#

The default shape defines the area where players can interact with or break the block:

  • 指定右键点击、挖掘等交互操作生效的区域。

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

➔ Returned by #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).

➔ Returned by #bs.hitbox:get_block_collision

实体#

即 Minecraft 原生碰撞箱，自动更新机制：

  • 随缩放、幼年体生长、装备或新乘客等实体变化实时调整。

  • 无需配置（默认行为）。

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

➔ 通过 #bs.hitbox:reset_entity 恢复

A snapshot of the entity’s hitbox at a specific moment:

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

  • 包含基础实体及所有乘客的合并边界框。烘焙实体乘客堆时，基础实体会烘焙所有乘客并将其碰撞箱扩展至覆盖整个实体堆。

  • 不再动态更新，若实体后续变化可能导致碰撞检测失效。

➔ 通过 #bs.hitbox:bake_entity 设置

完全用户定义的碰撞箱：

  • 精确设置 width、height 和可选 depth。

  • 适用于无原生碰撞箱的实体（如：显示实体）。

  • 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.

  • 存在轻微性能开销，避免同一区域过度使用。

➔ 通过 #bs.hitbox:set_entity 设置

🔌 Hitbox Providers#

A hitbox provider is a callback that returns a block’s shape for consumers such as bs.raycast or bs.move.

A provider can return one of two forms:

  1. A single flag (e.g., return 1), telling the consumer to treat the block as a full 16×16×16 cube.

  2. An array of bounding boxes, stored in bs:lambda hitbox:

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

    Each bounding box uses coordinates from 0 to 16, and may include a flag (defaults to 1 if omitted).

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.

Flags

Flags do not have inherent meaning. They are numeric labels used by providers and consumers to classify bounding boxes. You may use any of the following flags: 1, 2, 4, or 8.

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

Available Providers#

All built-in providers include 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 block types.

  • #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 block types.

  • #bs.hitbox:callback/get_block_collision

  • #bs.hitbox:callback/get_block_collision_with_fluid

Returns the block’s default shape and adds a placement-only bounding box (flag 4) to replicate vanilla block-placement behavior for blocks such as cauldrons, composters, hoppers, and scaffolding.

  • #bs.hitbox:callback/get_block_placement

  • #bs.hitbox:callback/get_block_placement_with_fluid

Custom Providers#

A common pattern for custom providers is either to directly return a custom shape or to:

  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

💬 这对你有帮助吗？

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