🔦 射线追踪（Raycast）#

#bs.raycast:help

检测射线与方块或实体的碰撞。

“现实只有在诗歌之光的照耀下才会展现自己。”

—乔治·布拉克（Georges Braque）

备注

This module implements a DDA algorithm, also known as voxel traversal.

Instead of checking points at fixed intervals (which can miss thin shapes), the ray steps from one block boundary to the next. This ensures:

  1. Perfect Precision: Every single block along the path is checked.

  2. Performance: No redundant checks within the same block.

  3. Flexibility: Works seamlessly with the bs.hitbox module to support complex shapes.

🔧 函数#

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

Run#

#bs.raycast:run {with:{}}

Cast a ray from the execution position and check if it hits something. Lambda scores and storage are only available during callback execution (on_*).

输入:

执行 at <实体> 或 positioned <x> <y> <z> rotated <rot>: 射线的起点和方向。

函数宏

  • 参数

    • with: 射线输入数据。

      • blocks: Whether the ray stops on blocks (default: true).
        Can be a hitbox provider (e.g. function #bs.hitbox:callback/get_block_collision).

      • entities: Whether the ray stops on entities (default: false).
        Can be a selector tag (typically assigned via /tag), which is preferred for performance.

      • ignored_blocks: 要忽略的方块（默认：#bs.hitbox:intangible）。

      • ignored_entities: Entity type to ignore (default: #bs.hitbox:intangible).
        Does not apply to entities with custom hitboxes.

      • max_distance: 射线最大前进距离（默认：16.0）。

      • on_targeted_block: Command to run at the block hit by the ray (aligned).

      • on_targeted_entity: Command to run as and at the entity hit by the ray.

      • on_hit_point: Command to run at the exact point where the ray makes contact.
        May run multiple times per block when multiple shapes are intersected.

      • piercing: Number of blocks or entities the ray can pass through (default: 0).

        • blocks: Number of blocks to track independently from entities (default: 0).

        • entities: Number of entities to track independently from blocks (default: 0).

Lambda 函数:

Score $raycast.distance bs.lambda: The distance from origin (scaled ×1000).

Score $raycast.hit_face bs.lambda: The face of the bounding box that was hit: 5 is east, 4 is west, 3 is south, 2 is north, 1 is top, and 0 is bottom.

Score $raycast.hit_flag bs.lambda: The flag of the intersected bounding box, -1 for entities.

Score $raycast.piercing bs.lambda: The remaining number of blocks or entities the ray can pass through.

Score $raycast.pierce_distance bs.lambda: The distance from previous hit point (scaled ×1000).

命令存储 bs:lambda raycast：

  • Ray lambda data (deprecated will be removed in v4.0)

    • distance: 射线的起点到碰撞点的距离。

    • hit_point: 射线碰撞点的坐标。

    • hit_normal: 射线碰撞面的法线坐标。

    • targeted_block: 射线碰撞到的方块坐标。

    • targeted_entity: 射线碰撞到的实体的UUID数组。

输出:

返回值：射线是否与碰撞箱相撞（1或0）。

命令存储 bs:out raycast：

  • Ray output data (deprecated will be removed in v4.0)

    • distance: 射线的起点到碰撞点的距离。

    • hit_point: 射线碰撞点的坐标。

    • hit_normal: 射线碰撞面的法线。

    • targeted_block: 射线碰撞到的方块坐标。

    • targeted_entity: 射线碰撞到的实体的UUID数组。

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.

Callback Order

Callbacks on_targeted_block and on_targeted_entity are always run before on_hit_point to guarantee block/entity information is available before processing hit-point data.

Custom Hitboxes

Bookshelf supports multiple hitbox types for precise control. Blocks can use custom hitbox providers. Entities support three types: dynamic, baked, and custom.

示例：从你的视线发射射线并检测是否有碰撞：

# Once (returns 0 if no collision occurred)
execute anchored eyes positioned ^ ^ ^ run function #bs.raycast:run {with:{}}

# If a collision occurred, see the collision point
data get storage bs:out raycast.hit_point

Example: Piercing multi-layer block and fluid handling:

execute anchored eyes positioned ^ ^ ^ run function #bs.raycast:run {with:{blocks:"function #bs.hitbox:callback/get_block_shape_with_fluid",ignored_blocks:"#air",piercing:1,on_hit_point:"particle minecraft:flame ~ ~ ~ 0 0 0 0 1 force"}}

  1. Callback on_targeted_block runs once with a $raycast.hit_flag bs.lambda score of 1 (solid), 2 (liquid), or 3 (both). Each unique flag is a power of 2 The hit_flag is the bitwise OR of all intersected shape flags (“both” being solid and liquid, 1 OR 2 = 3).

  2. Callback on_hit_point may run multiple times with a $raycast.hit_flag bs.lambda score of 1 (solid) or 2 (liquid) depending on the hit shape.

  3. Piercing decremented only once per block.

制作人员：Aksiome

💬 这对你有帮助吗？

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