Debug Visualization

PhysicsDebugPlugin draws each circle and box collider, and a line for each joint, as immediate-mode gizmos. It is separate from PhysicsPlugin, so debug rendering can be enabled only in development builds.

Setup

import { PhysicsDebugPlugin, PhysicsPlugin } from '@shell/physics';

world.addPlugin(PhysicsPlugin, PhysicsDebugPlugin);

PhysicsDebugPlugin depends on GizmoPlugin, which in turn installs the Pixi renderer integration it needs. If those plugins are already registered, their normal duplicate-plugin handling applies.

The debug systems run in Schedule.Update and read the components directly:

• CircleCollider is drawn with gizmos.circle().
• BoxCollider is drawn with gizmos.rect().
• DistanceJoint and SpringJoint are drawn with gizmos.line() between their two ends, when both are there.

They also run in an edit world, so the editor’s scene view shows them where the project installs the plugin.

Toggle rendering

Use the gizmos resource to toggle all debug drawing:

world.get('gizmos').enabled = false;

See Gizmos Resource for line styling, visibility, and layer controls.

Scope

The plugin renders collider outlines at their current ECS Position. It does not visualize contact normals, penetration depth, raycasts, spatial hash cells, the limits of a joint, or the beat of a Patrol. Box outlines remain axis-aligned because box collision ignores rotation.

An entity with both collider components displays both debug outlines, although collision detection uses only its circle collider.