Debug Draw Module

class box2d.debug_draw.Color(hex_color: int)

Bases: object

property as_float

Return the RGBA color as a tuple of floats scaled 0 to 1.

changed(r: int = None, g: int = None, b: int = None, a: int = None)

Return a new Color instance with the specified components changed.

Parameters:

• r – New red component (0-255). If None, retains current value.

• g – New green component (0-255). If None, retains current value.

• b – New blue component (0-255). If None, retains current value.

• a – New alpha component (0-255). If None, retains current value.

Returns:

A new instance of Color with updated color components.

property hex: int

class box2d.debug_draw.DebugDraw

Bases: object

Abstract base class for custom debug rendering of Box2D simulations.

Subclass this and override methods to implement debug visualization of: - Shape outlines and solids - Joints, AABBs, contact points - Physics metrics like mass centers and impulses

Set boolean flags (draw_shapes, draw_aabbs etc.) to control which elements are rendered. Uses Box2D’s b2DebugDraw callbacks internally.

Example

class MyDebugDraw(DebugDraw):

def _draw_polygon(self, vertices, color):

# Implement polygon drawing with your graphics API

property draw_aabbs

draw_capsule(p1: Vec2, p2: Vec2, radius: float, color: Color)

Callback for drawing capsule outlines (line segment with radius).

Parameters:

• p1 – First endpoint of the capsule’s centerline

• p2 – Second endpoint of the capsule’s centerline

• radius – Radius of the capsule (extends beyond endpoints)

• color – Outline color

Note

Used for character controllers or rounded collision shapes

draw_circle(center: Vec2, radius: float, color: Color)

Callback for drawing circle outlines.

Parameters:

• center – World position of circle center

• radius – Radius in meters

• color – RGB color of the outline

property draw_contact_impulses

property draw_contact_normals

property draw_contacts

property draw_friction_impulses

property draw_joint_extras

property draw_joints

property draw_mass

draw_point(p: Vec2, size: float, color: Color)

Visualize contact points (draw_contacts) or mass centers (draw_mass).

Parameters:

• position – World coordinates of the point

• size – Diameter to render the point (screen pixels or meters)

• color – RGB color of the point

Note

Used for contact points when draw_contacts flag is True

draw_polygon(vertices: list[Vec2], color: Color)

Draw wireframe polygon outlines (AABBs and shape outlines when draw_aabbs/shapes enabled).

Parameters:

• vertices – Polygon vertex coordinates in Counter-Clockwise order

• color – RGB color with alpha

draw_segment(p1: Vec2, p2: Vec2, color: Color)

Draw line segments for joints/contact normals (requires draw_joints or draw_contact_normals).

Parameters:

• p1 – Starting point in world coordinates

• p2 – Ending point in world coordinates

• color – Color of the line segment

property draw_shapes

draw_solid_capsule(p1: Vec2, p2: Vec2, radius: float, color: Color)

Draw filled capsule shapes (triggered by draw_shapes for capsule fixtures).

Parameters:

• p1 – First endpoint of the capsule’s axis

• p2 – Second endpoint of the capsule’s axis

• radius – Radial thickness of the capsule

• color – Fill color with transparency

Note

Rendered as two half-circles connected by a rectangle

draw_solid_circle(transform: Transform, radius: float, color: Color)

Draw filled circles with orientation marker (used for circular fixtures when draw_shapes enabled).

Parameters:

• transform – Center position and rotation (rotation affects orientation line)

• radius – Circle radius in world units

• color – Fill color with alpha channel

draw_solid_polygon(transform: Transform, vertices: list[Vec2], radius: float, color: Color)

Draw filled convex polygons with optional rounded corners (triggered by draw_shapes flag).

Parameters:

• transform – Position and rotation of the polygon

• vertices – Polygon vertices in CCW order

• radius – Radius for rounded corners (0 for sharp edges)

• color – Fill color with transparency

draw_string(p: Vec2, s: str, color: Color)

Render debug text for impulse values (draw_contact_impulses/draw_friction_impulses).

Parameters:

• p – World position where text should be anchored

• s – Text string to display

• color – Color of the text

Note

Coordinate system depends on your renderer’s text handling

draw_transform(transform: Transform)

Visualize coordinate frames for joint anchors (requires draw_joint_extras flag).

Parameters:

• transform – Contains position and rotation matrix

• color – Base color for the axes (often overridden)

box2d.debug_draw.draw_circle(center, radius, color, context)

box2d.debug_draw.draw_point(p, size, color, context)

box2d.debug_draw.draw_polygon(vertices, count, color, context)

box2d.debug_draw.draw_segment(p1, p2, color, context)

box2d.debug_draw.draw_solid_capsule(p1, p2, radius, color, context)

box2d.debug_draw.draw_solid_circle(transform, radius, color, context)

box2d.debug_draw.draw_solid_polygon(transform, vertices, count, radius, color, context)

box2d.debug_draw.draw_string(p, s, color, context)

box2d.debug_draw.draw_transform(transform, context)