Search Unity

Debug view mode for physics collision geometry

June 9, 2016 in Technology | 3 min. read
image2016-4-27 16-16-8
image2016-4-27 16-16-8
Topics covered

Is this article helpful for you?

Thank you for your feedback!

We want to help you quickly inspect the collision geometry in your scene to decide whether collisions should or shouldn’t happen. This is usually an issue when the Render mesh and Collider mesh get out of sync. So we’re making a debug view mode for physics collision geometry, which will allow you to quickly see through Collision Layers to find out where the issues are.

  • 5.4 Update: A new Editor build is available, based on 5.4 beta 23. This is the bleeding edge untested beta, so remember to backup your projects before opening them.

The tool also enables the user to quickly select GameObjects that own the collision geometry, for further inspection or changes. It can also highlight simulating Rigidbodies for debugging physics performance issues.

Please give this Editor build a try, explore your scenes and let us know what you find useful and what needs improving. The build is based on Unity 5.3.4p4, so it should be stable for most users. We don’t know yet when it will be a part of an official Unity release, but once ready, we think we have a good chance of backporting it to older Unity versions as well.

image2016-4-27 16-16-8
image2016-4-27 16-16-0
Scene View overlay

The view mode can be considered light version of the PhysX Visual Debugger (PVD) with added advantage of being able to select GameObjects and Assets directly inside Unity. Ease-of-use was our primary motivation for making the view mode. PVD can be tricky to work with because it is a separate application with different UI/UX conventions. Some versions of PVD also has performance issues with large terrains, which prohibits responsive navigation.

Here are some ideas for what we want to add to the tool in the future:

  • Selecting individual Collider components.
  • User defined colors per Layer.
  • Show contact points
  • Show raycasts/overlap tests/sweeps
  • Show more information, like Layer, when hover over a Collider.
  • Improve curvature information by doing light-from-viewpoint shading, like in Maya.
  • Timeline recording and scrubbing.
  • Network support.
  • Expose more render control to user scripts.
  • Show which Colliders a selected Rigidbody collides with.
  • Show which Trigger/Collide messages will be be sent or received from a selected Collider.


  • The following API can only be used in the Editor, not in Standalone players.
  • The class name is expected to change from "PhysicsVisualizationSettings" to "Physics.DebugVisualization".
public class PhysicsVisualizationSettings
  public static void Reset ();

  // properties
  public static bool showCollisionGeometry;
  public static bool enableMouseSelect;
  public static bool useSceneCam;
  public static float viewDistance;
  public static int terrainTilesMax;
  public static bool forceOverdraw;
  public static bool showStaticColliders;
  public static bool showTriggers;
  public static bool showRigidbodies;
  public static Color staticColor;
  public static Color rigidbodyColor;
  public static Color kinematicColor;
  public static float baseAlpha; // (1 - transparency)
  public static bool devOptions;
  public static int dirtyCount;

  public static bool GetShowCollisionLayer (int layer);
  public static void SetShowCollisionLayer (int layer, bool show);

  public static void UpdateMouseHighlight (Vector2 pos);
  public static void ClearMouseHighlight ();
  public static bool HasMouseHighlight ();


  • Cloth, Joints and WheelColliders are not supported yet.
  • Toggling Enable on a TerrainCollider many times causes random selection raycast failures.
  • When using multiple Scene Views, only the last Scene View can effectively do picking.
  • Tree Colliders don't highlight individual trees when hovering over terrains.
  • Drag-rectangle-to-select is not supported.
June 9, 2016 in Technology | 3 min. read

Is this article helpful for you?

Thank you for your feedback!

Topics covered