A guide to using BoxCast in Unity

August 21, 2023

We recently developed an incredible Responsive Smokes asset for Unity. The smoke dynamically grows in your scene. If there is something in the way, then the smoke will get blocked and go a different way.

One method that I looked into for this process was BoxCast().

I ended up using SphereCast() for this specific scenario. But, I wrote this article to help out any beginner game developers who want to learn about BoxCast(). So, what is BoxCast and how does it work?

When you use BoxCast(), you can imagine that you create a Box at the start position. Then, you drag that box through space to the end position. If it hits anything, it tells you.

That’s just the tip of the iceberg. By the end of this article, you will understand what BoxCast does. You will have some code examples showcasing how to use BoxCast in your project. You will have a useful script to draw a BoxCast using the debug tools. And, you will have some resources to continue learning!

Let’s get started.

Key Takeaways

To sweep a box through your scene and get collision data for that box, use BoxCast.
You need to provide the box dimensions and the length of the sweep.
If BoxCast hits something, it returns true.
If you want more information about the hit, use the RaycastHit out parameter.

This is a series on Unity Physics. We recommend reading the series in order.

Usage

In 2D games, use Physics2D.BoxCast().
In 3D games, use Physics.BoxCast().

I put together a basic example of using each method.

In both examples, you create a BoxCast starting at the origin, then sweep that box 1 unit along the x axis.

Physics2D.BoxCast(Vector2.zero, Vector2.one, 0f, Vector2.right, 1f);

Physics.BoxCast(Vector3.zero, Vector3.one, Vector3.right, Quaternion.identity, 1f);

Learn more about these methods with Unity’s documentation.

Physics2D.BoxCast(): https://docs.unity3d.com/ScriptReference/Physics2D.BoxCast.html
Physics.BoxCast(): https://docs.unity3d.com/ScriptReference/Physics.BoxCast.html

What does BoxCast do?

BoxCast creates a 2D or 3D box. Then, it sweeps that box through space. As the box moves through space, Unity looks for collisions. If the box hits anything, the method returns true.

Caution: If a collider is already inside of the box when BoxCast starts, BoxCast ignores it. Consider using Physics.OverlapBox() instead.

What parameters does BoxCast offer?

There are six main options when using BoxCast. You get all these options in both the 2D and 3D variants.

The start position
The box size
The box orientation
The direction of the sweep
The distance of the sweep
The list of layers you want to include

Code Example

Imagine that you have a 2D character defined by a box collider. The player provides the input to move this character one unit to the right.

Before you move the character, you want to check: Is there something in the way? Here’s how:


using UnityEngine;
public class CharacterMovement : MonoBehaviour
{
  public BoxCollider2D characterCollider;
  void Update()
  {
    bool doMoveRight = Input.GetKeyDown(KeyCode.D);
    if (doMoveRight)
    {
      if (
        Physics2D.BoxCast(
          characterCollider.bounds.center,
          characterCollider.size,
          0f,
          Vector2.right,
          1f
        )
      )
      {
        Debug.Log("The BoxCast hit something! Don't move.");
      }
      else
      {
        transform.Translate(Vector3.right);
      }
    }
  }
}

Visualize a BoxCast

Copy and paste this component into a new script in your project.
Add the component onto the object you want to visualize the BoxCast for
Set the object scale and max distance

using UnityEngine;

[ExecuteAlways]
public class VisualizeBoxCast : MonoBehaviour
{
  public float maxDistance = 1f;
  void Update()
  {
    if (
      Physics.BoxCast(
        transform.position,
        transform.lossyScale * 0.5f,
        transform.forward,
        Quaternion.identity,
        maxDistance
        )
      )
      {
        Debug.Log("The BoxCast hit something!");
      }
    }
    
    private void OnDrawGizmos()
    {
      DrawBoxCast(
        transform.position,
        transform.position + maxDistance * transform.forward,
        transform.lossyScale,
        transform.rotation
      );
    }
    
    void DrawBoxCast(Vector3 start, Vector3 end, Vector3 size, Quaternion rotation){
      Gizmos.color = Color.green;
      
      // Cache the Gizmos matrix.
      Matrix4x4 currentMatrix = Gizmos.matrix;
      
      // Draw Cubes
      Gizmos.matrix = Matrix4x4.TRS(start, rotation, size);
      Gizmos.DrawWireCube(Vector3.zero, Vector3.one);
      Gizmos.matrix = Matrix4x4.TRS(end, rotation, size);
      Gizmos.DrawWireCube(Vector3.zero, Vector3.one);
      
      // Draw Connecting Lines
      Vector3 x = Vector3.right * size.x * 0.5f;
      Vector3 y = Vector3.up * size.y * 0.5f;
      Vector3 z = Vector3.forward * size.z * 0.5f;
      Gizmos.matrix = Matrix4x4.TRS(start, rotation, Vector3.one);
      Gizmos.DrawRay(Vector3.zero - x - y - z, Vector3.forward * maxDistance);
      Gizmos.DrawRay(Vector3.zero - x + y - z, Vector3.forward * maxDistance);
      Gizmos.DrawRay(Vector3.zero + x - y - z, Vector3.forward * maxDistance);
      Gizmos.DrawRay(Vector3.zero + x + y - z, Vector3.forward * maxDistance);
      
      // Reset the Gizmos matrix.
      Gizmos.matrix = currentMatrix;
    }
}

Build your game more quickly

The best way to build your game? Use our assets. Don’t make the mistake of trying to build everything from scratch. AAA studios are able to make amazing games because they have a huge team working on their projects. You don’t have the budget for a huge team, but you do have the budget for our free assets. And, if you start earning money from you game, you can level up your project and invest in our premium assets for Unity.