Debugging Physics Stability and Collision Issues

In this lesson, you will learn how to use visual debugging tools to see what the physics engine is "thinking," allowing you to identify and fix common instabilities like tunneling, jitter, and overlapping colliders.

Visualizing the Invisible

When a physics object behaves strangely—like vibrating against a wall or passing through a floor—it is often because your colliders are not aligned with your visual meshes. To investigate, enable the Gizmos in your Scene view by clicking the "Gizmos" button. Ensure the Colliders option is checked. Now, you can physically see the green wireframe boundaries of your colliders. If a collider is slightly floating above the ground or overlapping another, you will see it immediately.

Tackling Common Issues

• Tunneling: If a fast-moving object passes through walls, it is likely "tunneling." This happens when an object moves so far in a single FixedUpdate step that it clears the collider entirely between frames. To debug this, select your Rigidbody and change the Collision Detection mode from Discrete to Continuous. This forces Unity to perform a more expensive "sweep" test to catch collisions mid-motion.
• Jitter: If an object is shaking, check for overlapping colliders or conflicting forces. Use the Physics Debugger (found under Window > Analysis > Physics Debugger). This window color-codes your colliders based on their properties, making it easy to spot "trigger" vs "collision" misconfigurations.
• Overlapping Colliders: If two objects are stuck, the Physics Debugger will show them in red if they are currently in a collision state. If they are overlapping at the start of the scene, Unity may apply extreme forces to resolve the penetration, causing the object to "pop" or fly away.

Practical Troubleshooting

If you suspect an object is stuck because of a complex mesh, temporarily replace its Mesh Collider with a Box Collider to test for stability. If the jitter stops, you know the issue is the complexity of your original collider geometry.

// Example: Switching to Continuous detection for a projectile
void Start() {
    Rigidbody rb = GetComponent<Rigidbody>();
    rb.collisionDetectionMode = CollisionDetectionMode.Continuous;
}

Key Takeaway: Use the Scene view Gizmos and the Physics Debugger window to visually verify that your collider boundaries match your game's collision logic, and use Continuous collision detection to prevent fast-moving objects from passing through barriers.