Body Module

class box2d.body.Body(world, body_def)[source]

Represents a rigid body in the 2D physics simulation.

Bodies can be dynamic, kinematic, or static, and can have various forces, impulses, and constraints applied to them.

__init__(world, body_def)[source]

Initialize a Body instance.

Parameters:

world – The World instance in which this body exists.
body_def – The body definition used to create this body.

add_box(width: float, height: float, radius: float = 0.0, offset: tuple = (0, 0), angle: float = 0.0, density: float = None, friction: float = None, restitution: float = None, is_sensor: bool = None, collision_filter=None, custom_color=None)[source]

Add a box shape to the body.

Parameters:

width – Full width of the box.
height – Full height of the box.
radius – The radius of the rounded corners (default: 0.0).
offset – The offset of the box from the body’s position (default: (0, 0)).
angle – The rotation angle of the box in radians (default: 0.0).
density – Mass density of the shape.
friction – Friction coefficient.
restitution – Bounciness.
is_sensor – Flag indicating whether the shape is a sensor.
collision_filter – Optional CollisionFilter instance for collision filtering.
custom_color – Optional custom debug draw color (uint32_t).

Returns:

The created box shape.

add_capsule(point1: tuple, point2: tuple, radius: float, density: float = None, friction: float = None, restitution: float = None, is_sensor: bool = None, collision_filter=None, custom_color=None)[source]

Add a capsule shape to the body.

Parameters:

point1 – First endpoint of the capsule.
point2 – Second endpoint of the capsule.
radius – Radius of the capsule.
density – Mass density of the shape.
friction – Friction coefficient.
restitution – Bounciness.
is_sensor – Flag indicating whether the shape is a sensor.
collision_filter – Optional CollisionFilter instance for collision filtering.
custom_color – Optional custom debug draw color (uint32_t).

Returns:

The created capsule shape.

add_chain(vertices: list[tuple], loop: bool = False, friction: float = None, restitution: float = None, collision_filter=None, custom_color=None)[source]

Add a chain shape to the body.

Parameters:

vertices – List of vertices defining the chain (must contain at least 4 vertices).
loop – Boolean indicating whether the chain should be closed (looped).
friction – Friction coefficient.
restitution – Bounciness.
collision_filter – Optional CollisionFilter instance for collision filtering.
custom_color – Optional custom debug draw color (uint32_t).

Returns:

The created chain shape.

add_circle(radius: float, center: tuple = (0, 0), density: float = None, friction: float = None, restitution: float = None, is_sensor: bool = None, collision_filter=None, custom_color=None)[source]

Add a circle shape to the body.

Parameters:

radius – Radius of the circle.
center – Center of the circle (default: (0, 0)).
density – Mass density of the shape.
friction – Friction coefficient.
restitution – Bounciness.
is_sensor – Flag indicating whether the shape is a sensor.
collision_filter – Optional CollisionFilter instance for collision filtering.
custom_color – Optional custom debug draw color (uint32_t).

Returns:

The created circle shape.

add_polygon(vertices: list[tuple], radius: float = 0.0, density: float = None, friction: float = None, restitution: float = None, is_sensor: bool = None, collision_filter=None, custom_color=None)[source]

Add a convex polygon shape to the body.

Parameters:

vertices – List of vertices defining the polygon.
radius – Optional radius for rounded corners (default: 0.0).
density – Mass density of the shape.
friction – Friction coefficient.
restitution – Bounciness.
is_sensor – Flag indicating whether the shape is a sensor.
collision_filter – Optional CollisionFilter instance for collision filtering.
custom_color – Optional custom debug draw color (uint32_t).

Returns:

The created polygon shape.

add_segment(point1: tuple, point2: tuple, density: float = None, friction: float = None, restitution: float = None, is_sensor: bool = None, collision_filter=None, custom_color=None)[source]

Add a line segment shape to the body.

Parameters:

point1 – Starting point of the segment.
point2 – Ending point of the segment.
density – Mass density of the shape.
friction – Friction coefficient.
restitution – Bounciness.
is_sensor – Flag indicating whether the shape is a sensor.
collision_filter – Optional CollisionFilter instance for collision filtering.
custom_color – Optional custom debug draw color (uint32_t).

Returns:

The created segment shape.

property angular_damping: Get the current angular damping value.

property angular_velocity: Get angular velocity in radians/sec.

apply_force(force, point=None, wake=True)[source]

Apply a force at a world point.

Parameters:

force – Tuple representing the force vector (Fx, Fy).
point – Tuple representing the application point (x, y). Defaults to center.
wake – Boolean indicating whether to wake the body.

apply_linear_impulse(impulse, point=None, wake=True)[source]

Apply a linear impulse at a world point.

Parameters:

impulse – Tuple representing the impulse vector (Ix, Iy).
point – Tuple representing the application point (x, y). Defaults to center.
wake – Boolean indicating whether to wake the body.

apply_torque(torque, wake=True)[source]

Apply a torque to the body.

Parameters:

torque – Float value representing the torque.
wake – Boolean indicating whether to wake the body.

property awake

Get the awake state of the body.

Returns:: True if the body is awake, False otherwise.
Return type:: bool

destroy()[source]: Destroy this body and remove it from the world.

property enabled

Get whether the body is enabled.

Returns:: True if the body is enabled, False otherwise.
Return type:: bool

property fixed_rotation: Check if the body has fixed rotation.

property gravity_scale: Get the gravity scale factor for this body.

property is_bullet: Check if the body is treated as a bullet.

is_sleep_enabled()[source]: Check if the body is allowed to sleep.

property linear_damping: Get the current linear damping value.

property linear_velocity: Get the linear velocity of the body.

property mass: Get the mass of the body in kilograms

property position: Get the world position of the body.

remove_shape(shape)[source]: Remove a shape from the body.

property rotation

Get the world rotation of the body in radians.

Returns:: The body’s rotation angle in radians.
Return type:: float

property rotational_inertia: Get the rotational inertia of the body.

property shapes: Get the shapes attached to this body.

property sleep_threshold: Get the sleep threshold value.

property transform: Transform: Get the body Transform. You can use it to convert world coordinates to body coordinates.

property type: Get the body type as a string (‘dynamic’, ‘kinematic’, or ‘static’).

class box2d.body.BodyBuilder(world)[source]

Builder for creating Box2D bodies with chained configuration methods.

Example

>>> body = world.new_body()
>>> body.dynamic()
>>> body.position(2, 3)
>>> body.box(width=2, height=1)
>>> body.circle(radius=0.5, center=(1, 0))
>>> body = body.build()

__init__(world)[source]

Initialize the BodyBuilder with the world context.

Parameters:: world – The World instance where the body will be created.

angular_damping(damping: float)[source]

Set the angular damping of the body.

Damping reduces the angular velocity over time. :param damping: Float value for angular damping

Returns:: The builder instance

angular_velocity(radians: float)[source]

Set the initial angular velocity of the body.

Parameters:: radians – The angular velocity in radians per second
Returns:: The builder instance

box(width: float, height: float, radius=0.0, offset=(0, 0), angle=0.0, density: float = 1.0, friction: float = 0.2, restitution: float = 0.0, is_sensor: bool = False, collision_filter: CollisionFilter = None)[source]

Add a box shape to the body during construction.

Parameters:

width – Full width of the box.
height – Full height of the box.
radius – The radius of the rounded corners (default: 0.0).
offset – The offset of the box from the body’s position (default: (0, 0)).
angle – The angle of the box (default: 0.0).
density – Mass density (kg/m²).
friction – Friction coefficient (0-1).
restitution – Bounciness (0-1).
is_sensor – True for sensor shape (no collision response).
collision_filter – Optional CollisionFilter instance for collision filtering.

Returns:

Self for method chaining.

build() → Body[source]

Finalize the body creation and attach configured shapes.

Creates and configures the body in the world using the specified properties. :returns: The newly created Body instance

bullet(bullet=True)[source]

Set whether the body is treated as a bullet.

Bullet bodies perform continuous collision detection, suitable for fast-moving objects. :param bullet: Boolean indicating whether to enable bullet behavior

Returns:: The builder instance

capsule(point1: tuple, point2: tuple, radius: float, density: float = 1.0, friction: float = 0.2, restitution: float = 0.0, is_sensor: bool = False, collision_filter: CollisionFilter = None)[source]

Add a vertical capsule shape (cylinder with hemispherical ends).

Parameters:

point1 – The first endpoint of the capsule.
point2 – The second endpoint of the capsule.
radius – Radius of the hemispherical ends.
density – Mass density (kg/m²).
friction – Friction coefficient (0-1).
restitution – Bounciness (0-1).
is_sensor – True for sensor shape.
collision_filter – Optional CollisionFilter instance for collision filtering.

Returns:

Self for method chaining.

chain(vertices: list[tuple], loop: bool = False, friction: float = 0.2, restitution: float = 0.0, collision_filter: CollisionFilter = None)[source]

Add a chain shape to the body during construction.

Parameters:

vertices – List of points that define the chain shape. Must contain at least 4 vertices.
loop – Boolean indicating whether the chain should be closed (looped). Default is False.
friction – Friction coefficient (0-1).
restitution – Bounciness (0-1).
collision_filter – Optional CollisionFilter instance for collision filtering.

Returns:

Self for method chaining.

circle(radius: float, center: tuple = (0, 0), density: float = 1.0, friction: float = 0.2, restitution: float = 0.0, is_sensor: bool = False, collision_filter: CollisionFilter = None)[source]

Add a circle shape to the body during construction.

Parameters:

radius – Radius of the circle.
center – Local center position (x, y).
density – Mass density (kg/m²).
friction – Friction coefficient (0-1).
restitution – Bounciness (0-1).
is_sensor – True for sensor shape.
collision_filter – Optional CollisionFilter instance for collision filtering.

Returns:

Self for method chaining.

dynamic()[source]

Set the body type to dynamic.

Dynamic bodies are affected by forces and impulses. Returns the builder instance.

enable_sleep(enable: bool)[source]

Set whether the body is allowed to sleep.

Sleeping bodies are skipped in simulations for performance optimization. :param enable: Boolean indicating whether sleeping is enabled

Returns:: The builder instance

classmethod extend(func)[source]

Decorator that adds a new method to the BodyBuilder class.

When decorating a function with @BodyBuilder.extend, the function is attached as a new method to the BodyBuilder class. This enables you to extend the builder with custom configuration methods that can be chained with the built-in methods.

Example:

>>> @BodyBuilder.extend
>>> def custom_shape(self, value):
>>>     # Custom functionality
>>>     return self

>>> builder = world.new_body().custom_shape(10)

Parameters:: func (callable) – A function to be added as a method to BodyBuilder. The function should accept ‘self’ as its first argument.
Returns:: The unchanged original function.
Return type:: callable

fixed_rotation(fixed=True)[source]

Set whether the body has fixed rotation.

Fixed rotation bodies will not rotate. Useful for objects like characters. :param fixed: Boolean indicating whether rotation should be fixed

Returns:: The builder instance

gravity_scale(scale)[source]

Set the gravity scale for the body.

Adjusts the effect of gravity on this body relative to the world gravity. :param scale: Float value representing the gravity scale factor

Returns:: The builder instance

kinematic()[source]

Set the body type to kinematic.

Kinematic bodies are moved by setting their velocity. Returns the builder instance.

linear_damping(damping: float)[source]

Set the linear damping of the body.

Damping reduces the linear velocity over time. :param damping: Float value for linear damping

Returns:: The builder instance

linear_velocity(x: float, y: float)[source]

Set the initial linear velocity of the body.

Parameters:

x – The x-component of the velocity
y – The y-component of the velocity

Returns:

The builder instance

polygon(vertices: list[tuple], radius: float = 0.0, density: float = 1.0, friction: float = 0.2, restitution: float = 0.0, is_sensor: bool = False, collision_filter: CollisionFilter = None)[source]

Add a convex polygon shape.

The given vertices are processed to compute their convex hull. An exception will be raised if the provided vertices do not form a valid convex polygon.

Parameters:

vertices – List of points that define the polygon shape.
radius – The radius of the rounded corners (default: 0.0).
density – Mass density (kg/m²).
friction – Friction coefficient (0-1).
restitution – Bounciness (0-1).
is_sensor – True for sensor shape.
collision_filter – Optional CollisionFilter instance for collision filtering.

Returns:

Self for method chaining.

Raises:

Exception – If the vertices cannot form a convex polygon.

position(x: float, y: float)[source]

Set the initial position of the body.

Parameters:

x – The x-coordinate of the body’s position
y – The y-coordinate of the body’s position

Returns:

The builder instance

rotation(rotation: float)[source]

Set the initial rotation of the body.

Parameters:: rotation – The rotation in radians
Returns:: The builder instance

segment(start: tuple, end: tuple, density: float = 0.0, friction: float = 0.2, restitution: float = 0.0, is_sensor: bool = False, collision_filter: CollisionFilter = None)[source]

Add a line segment shape with optional edge radius.

Parameters:

start – Starting point (x, y) in local coordinates.
end – Ending point (x, y) in local coordinates.
density – Typically 0 for static segments.
friction – Friction coefficient (0-1).
restitution – Bounciness (0-1).
is_sensor – True for sensor shape.
collision_filter – Optional CollisionFilter instance for collision filtering.

Returns:

Self for method chaining.

sleep_threshold(threshold: float)[source]

Set the sleep threshold for the body.

The minimum velocity below which the body will go to sleep. :param threshold: Float value representing the sleep threshold

Returns:: The builder instance

static()[source]

Set the body type to static.

Static bodies cannot move and are unaffected by forces. Returns the builder instance.