A physics world that manages bodies, joints, and collision detection. Access via the 'physics' submodule.
Experimental API:
The physics submodule is an experimental and new API that is highly susceptible to breaking changes in the future.
A physics world that manages bodies, joints, and collision detection.
| Name | Description | Type |
|---|---|---|
gravity | The gravity vector of the world. | Vec2 |
debug_draw(color: Color = ..., filled_shapes: bool = False, shapes: bool = True, joints: bool = True, joint_extras: bool = True, bounds: bool = False, mass: bool = False, body_names: bool = False, contacts: bool = False, graph_colors: bool = False, contact_normals: bool = False, contact_impulses: bool = False, contact_features: bool = False, friction_impulses: bool = False, islands: bool = False) → Nonedebug_draw(color: Color = ..., filled_shapes: bool = False, shapes: bool = True, joints: bool = True, joint_extras: bool = True, bounds: bool = False, mass: bool = False, body_names: bool = False, contacts: bool = False, graph_colors: bool = False, contact_normals: bool = False, contact_impulses: bool = False, contact_features: bool = False, friction_impulses: bool = False, islands: bool = False) → NoneDraw physics debug geometry. If shapes are disabled, the filled_shapes option is ignored.
Args
color : The color to use for drawing. Defaults to red.filled_shapes : Whether to draw filled shapes. Defaults to False.shapes : Whether to draw collider shapes. Defaults to True.joints : Whether to draw joints. Defaults to True.joint_extras : Whether to draw extra joint info like limits. Defaults to True.bounds : Whether to draw body AABBs. Defaults to False.mass : Whether to draw mass indicators. Defaults to False.body_names : Whether to draw body names. Defaults to False.contacts : Whether to draw contact points. Defaults to False.graph_colors : Whether to use graph colors for contact points. Defaults to False.contact_normals : Whether to draw contact normals. Defaults to False.contact_impulses : Whether to draw contact impulse vectors. Defaults to False.contact_features : Whether to draw contact feature points. Defaults to False.friction_impulses : Whether to draw friction impulse vectors. Defaults to False.islands : Whether to color bodies by island. Defaults to False.from_map_layer(layer: Layer) → StaticBodyfrom_map_layer(layer: Layer) → StaticBodyCreate a single StaticBody from a TileMap ObjectGroup layer.
This method iterates through all rectangular and polygonal objects in the specified layer and adds them as colliders to a new StaticBody. Points, lines, and ellipses are discarded.
Args
layer : The TileMap ObjectGroup layer.Returns
StaticBody : The created static body with all shapes attached.
Raises
TypeError : If the layer is not an ObjectGroup.add_fixed_update(callback: Callable[[float], None]) → Noneadd_fixed_update(callback: Callable[[float], None]) → NoneAdd a callback function to be executed during each physics step.
fixed_callback(callback: Callable[[float], None]) → Callable[[float], None]fixed_callback(callback: Callable[[float], None]) → Callable[[float], None]A decorator to register a function as a physics update callback.
clear_fixed_updates() → Noneclear_fixed_updates() → NoneRemove all registered fixed update callbacks.
create_distance_joint(body_a: Body, body_b: Body, anchor_a: Vec2, anchor_b: Vec2) → DistanceJointcreate_distance_joint(body_a: Body, body_b: Body, anchor_a: Vec2, anchor_b: Vec2) → DistanceJointCreate a distance joint between two bodies.
Args
body_a : The first body.body_b : The second body.anchor_a : The anchor point on the first body in world coordinates.anchor_b : The anchor point on the second body in world coordinates.Returns
DistanceJoint : The created joint.
create_filter_joint(body_a: Body, body_b: Body) → FilterJointcreate_filter_joint(body_a: Body, body_b: Body) → FilterJointCreate a filter joint between two bodies to disable collision.
Args
body_a : The first body.body_b : The second body.Returns
FilterJoint : The created joint.
create_motor_joint(body_a: Body, body_b: Body) → MotorJointcreate_motor_joint(body_a: Body, body_b: Body) → MotorJointCreate a motor joint between two bodies.
Args
body_a : The first body.body_b : The second body.Returns
MotorJoint : The created joint.
create_mouse_joint(ground_body: Body, pulled_body: Body, target: Vec2) → MouseJointcreate_mouse_joint(ground_body: Body, pulled_body: Body, target: Vec2) → MouseJointCreate a mouse joint between a ground body and a target body.
Args
ground_body : The ground body (usually a static body).pulled_body : The body to be pulled and moved to the target.target : The initial target point in world coordinates.Returns
MouseJoint : The created joint.
create_prismatic_joint(body_a: Body, body_b: Body, anchor: Vec2, axis: Vec2) → PrismaticJointcreate_prismatic_joint(body_a: Body, body_b: Body, anchor: Vec2, axis: Vec2) → PrismaticJointCreate a prismatic joint between two bodies.
Args
body_a : The first body.body_b : The second body.anchor : The anchor point in world coordinates.axis : The axis of movement in world coordinates.Returns
PrismaticJoint : The created joint.
create_revolute_joint(body_a: Body, body_b: Body, anchor: Vec2) → RevoluteJointcreate_revolute_joint(body_a: Body, body_b: Body, anchor: Vec2) → RevoluteJointCreate a revolute joint between two bodies.
Args
body_a : The first body.body_b : The second body.anchor : The anchor point in world coordinates.Returns
RevoluteJoint : The created joint.
create_weld_joint(body_a: Body, body_b: Body, anchor: Vec2) → WeldJointcreate_weld_joint(body_a: Body, body_b: Body, anchor: Vec2) → WeldJointCreate a weld joint between two bodies.
Args
body_a : The first body.body_b : The second body.anchor : The anchor point in world coordinates.Returns
WeldJoint : The created joint.
create_wheel_joint(body_a: Body, body_b: Body, anchor: Vec2, axis: Vec2) → WheelJointcreate_wheel_joint(body_a: Body, body_b: Body, anchor: Vec2, axis: Vec2) → WheelJointCreate a wheel joint between two bodies.
Args
body_a : The first body.body_b : The second body.anchor : The anchor point in world coordinates.axis : The axis of movement in world coordinates.Returns
WheelJoint : The created joint.
get_collisions() → list[Collision]get_collisions() → list[Collision]Get all collision events that occurred during the last physics step.
Note: This only includes hit events. The list is cleared after each call.
Returns
list[Collision] : A list of collision events.
query_point(point: Vec2) → list[Body]query_point(point: Vec2) → list[Body]Find all bodies that contain the specified point.
Args
point : The point to query in world coordinates.Returns
list[Body] : A list of bodies at the point.
query_aabb(rect: Rect) → list[Body]query_aabb(rect: Rect) → list[Body]Find all bodies that overlap with the specified rectangular area.
Args
rect : The rectangular area to query.Returns
list[Body] : A list of bodies overlapping the area.
ray_cast(origin: Vec2, translation: Vec2) → list[CastHit]ray_cast(origin: Vec2, translation: Vec2) → list[CastHit]Cast a ray into the world and find all bodies that intersect it.
Args
origin : The starting point of the ray.translation : The direction and length of the ray.Returns
list[RayCastHit] : A list of hits, sorted by distance (fraction).