🔦 Raycast

#bs.raycast:help

Cast rays and detect collisions with blocks or entities.

Note

Unlike traditional raycasts, this module uses a voxel traversal algorithm which provides much greater precision. Additionally, thanks to the bs.hitbox module, it supports all different hitbox types, including both blocks and entities.

“Reality only reveals itself when it is illuminated by a ray of poetry.”

—Georges Braque

---

🔧 Functions

You can find below all functions available in this module.

---

Run the Raycast

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

Cast a ray from the execution position and check if it hits something.

Inputs:

Execution at <entity> or positioned <x> <y> <z> rotated <rot>: Origin of the ray.

Function macro:

• Arguments
  • with: Ray input data.
    • blocks: Whether the ray should stop on blocks (default: true).
    • entities: Whether the ray should stop on entities (default: false). Can also be a required entity tag.
    • piercing: Number of blocks or entities the ray can pass through (default: 0).
    • max_distance: Maximum ray travel distance (default: 16.0).
    • hitbox_shape: Hitbox type: interaction or collision (default: interaction).
    • ignored_blocks: Blocks to ignore (default: #bs.hitbox:intangible).
    • ignored_entities: Entities to ignore (default: #bs.hitbox:intangible).
    • on_hit_point: Command to run at the exact point where the ray makes contact.
    • on_targeted_block: Command to run at the block hit by the ray.
    • on_targeted_entity: Command to run as and at the entity hit by the ray.

Lambdas:

Score $raycast.piercing bs.lambda: The remaining number of blocks or entities the ray can pass through before stopping. This score can be dynamically updated inside callbacks (on_*) to modify ray behavior.

Storage bs:lambda raycast:

• Ray lambda data, accessible only in callbacks (on_*)
  • distance: The distance from the ray’s origin to the impact point.
  • hit_point: The coordinates of the impact point.
  • hit_normal: The normal of the surface the ray hits.
  • targeted_block: The coordinates of the block that was hit.
  • targeted_entity: The UUID array of the entity that was hit.

Outputs:

Return: Whether the ray collides with a hitbox or not (1 or 0).

Storage bs:out raycast:

• Ray output data
  • distance: The distance from the ray’s origin to the impact point.
  • hit_point: The coordinates of the impact point.
  • hit_normal: The normal of the surface the ray hit.
  • targeted_block: The coordinates of the block that was hit.
  • targeted_entity: The UUID array of the entity that was hit.

Collision / Interaction Shape

• Collision Shape: Defines the physical boundaries of a block that entities cannot pass through. It determines where an entity will stop when moving towards the block.

• Interaction Shape: Defines the area where the player can interact with or break the block. This includes actions such as right-clicking to open a GUI (e.g., chests, furnaces) or mining the block. Some blocks have an interaction shape but no collision, such as crops or scaffolding.

Example: Cast a ray from your eyes and detect any collisions:

# 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

Credits: Aksiome

---

💬 Did it help you?

Feel free to leave your questions and feedback below!