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.
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.
An editor project lists it in the debug field of its project definition instead: the editor’s scene view and the game playing in the editor draw it, the shipped game does not, and the editor’s View › Gizmos switches each gizmo layer it draws on: Colliders and Joints.
The debug systems run in Schedule.Update and read the components directly:
CircleCollideris drawn withgizmos.circle()on the layerphysics:colliders.BoxCollideris drawn withgizmos.rect()on the layerphysics:colliders.DistanceJointandSpringJointare drawn withgizmos.line()between their two ends, when both are there, on the layerphysics:joints.
Nothing of it is drawn on the default layer, which stays a game’s own.
They also run in an edit world, so the editor’s scene view shows them where the project installs the plugin.
Toggle rendering
Section titled “Toggle rendering”Switch off colliders or joints on their own by their layer:
world.get('gizmos').disableLayer('physics:joints'); // colliders are still drawnworld.get('gizmos').enableLayer('physics:joints');Or use the gizmos resource to toggle all gizmo drawing:
world.get('gizmos').enabled = false;See Gizmos Resource for line styling, visibility, and layer controls.
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.