physics.World

physics.World(gravity: Vec2 = Vec2(0.000000, 0.000000))

Create a new physics world with the specified gravity.

Args

• gravity (Vec2, optional) — The gravity vector for the world. Defaults to (0, 0).

gravity: Vec2

The gravity vector of the world.

create_distance_joint(self, body_a: physics.Body, body_b: physics.Body, anchor_a: Vec2, anchor_b: Vec2) -> physics.DistanceJoint

Create a distance joint between two bodies.

Args

• body_a (Body) — The first body.
• body_b (Body) — The second body.
• anchor_a (Vec2) — The anchor point on the first body in world coordinates.
• anchor_b (Vec2) — The anchor point on the second body in world coordinates.

Returns

• DistanceJoint — The created joint.

create_filter_joint(self, body_a: physics.Body, body_b: physics.Body) -> physics.FilterJoint

Create a filter joint between two bodies to disable collision.

Args

• body_a (Body) — The first body.
• body_b (Body) — The second body.

Returns

• FilterJoint — The created joint.

create_motor_joint(self, body_a: physics.Body, body_b: physics.Body) -> physics.MotorJoint

Create a motor joint between two bodies.

Args

• body_a (Body) — The first body.
• body_b (Body) — The second body.

Returns

• MotorJoint — The created joint.

create_mouse_joint(self, ground_body: physics.Body, pulled_body: physics.Body, target: Vec2) -> physics.MouseJoint

Create a mouse joint between a ground body and a target body.

Args

• ground_body (Body) — The ground body (usually a static body).
• pulled_body (Body) — The body to be pulled and moved to the target.
• target (Vec2) — The initial target point in world coordinates.

Returns

• MouseJoint — The created joint.

create_prismatic_joint(self, body_a: physics.Body, body_b: physics.Body, anchor: Vec2, axis: Vec2) -> physics.PrismaticJoint

Create a prismatic joint between two bodies.

Args

• body_a (Body) — The first body.
• body_b (Body) — The second body.
• anchor (Vec2) — The anchor point in world coordinates.
• axis (Vec2) — The axis of movement in world coordinates.

Returns

• PrismaticJoint — The created joint.

create_revolute_joint(self, body_a: physics.Body, body_b: physics.Body, anchor: Vec2) -> physics.RevoluteJoint

Create a revolute joint between two bodies.

Args

• body_a (Body) — The first body.
• body_b (Body) — The second body.
• anchor (Vec2) — The anchor point in world coordinates.

Returns

• RevoluteJoint — The created joint.

create_weld_joint(self, body_a: physics.Body, body_b: physics.Body, anchor: Vec2) -> physics.WeldJoint

Create a weld joint between two bodies.

Args

• body_a (Body) — The first body.
• body_b (Body) — The second body.
• anchor (Vec2) — The anchor point in world coordinates.

Returns

• WeldJoint — The created joint.

create_wheel_joint(self, body_a: physics.Body, body_b: physics.Body, anchor: Vec2, axis: Vec2) -> physics.WheelJoint

Create a wheel joint between two bodies.

Args

• body_a (Body) — The first body.
• body_b (Body) — The second body.
• anchor (Vec2) — The anchor point in world coordinates.
• axis (Vec2) — The axis of movement in world coordinates.

Returns

• WheelJoint — The created joint.

debug_draw(self, color: Color = Color(255, 0, 0, 255), 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) -> None

Draw physics debug geometry. If shapes are disabled, the filled_shapes option is ignored.

Args

• color (Color, optional) — The color to use for drawing. Defaults to red.
• filled_shapes (bool, optional) — Whether to draw filled shapes. Defaults to False.
• shapes (bool, optional) — Whether to draw collider shapes. Defaults to True.
• joints (bool, optional) — Whether to draw joints. Defaults to True.
• joint_extras (bool, optional) — Whether to draw extra joint info like limits. Defaults to True.
• bounds (bool, optional) — Whether to draw body AABBs. Defaults to False.
• mass (bool, optional) — Whether to draw mass indicators. Defaults to False.
• body_names (bool, optional) — Whether to draw body names. Defaults to False.
• contacts (bool, optional) — Whether to draw contact points. Defaults to False.
• graph_colors (bool, optional) — Whether to use graph colors for contact points. Defaults to False.
• contact_normals (bool, optional) — Whether to draw contact normals. Defaults to False.
• contact_impulses (bool, optional) — Whether to draw contact impulse vectors. Defaults to False.
• contact_features (bool, optional) — Whether to draw contact feature points. Defaults to False.
• friction_impulses (bool, optional) — Whether to draw friction impulse vectors. Defaults to False.
• islands (bool, optional) — Whether to color bodies by island. Defaults to False.

from_map_layer(self, layer: tilemap.Layer) -> physics.StaticBody

Create 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 (Layer) — The TileMap ObjectGroup layer.

Returns

• StaticBody — The created static body with all shapes attached.

Raises

• TypeError — If the layer is not an ObjectGroup.

get_collisions(self) -> list[physics.Collision]

Get all collision events that occurred during the last physics step.

Note

This only includes hit events. Reads do not consume events; read after each step and before destroying participating colliders.

Returns

list[Collision]: A list of collision events.

get_contact_events(self) -> list[physics.ContactEvent]

Return contact begin/end snapshots from the latest World.step(). Reads do not consume events. Read after EACH fixed step, before stepping this world again. The returned list owns its records and may be retained across subsequent steps. Colliders must opt in with enable_events=True. End-event colliders may already be destroyed: their IDs remain readable, but body access requires is_valid. Begin records precede end records; no chronological ordering is promised.

get_sensor_events(self) -> list[physics.SensorEvent]

Return sensor enter/exit snapshots from the latest World.step(). Reads do not consume events. Read after EACH fixed step. Returned records may be retained. Enable events on BOTH the sensor and visitor colliders. Destroyed colliders remain identifiable by ID; check is_valid before accessing their bodies. Begin records precede end records; no chronological ordering is promised.

query_aabb(self, rect: Rect) -> list[physics.Body]

Find all bodies that overlap with the specified rectangular area.

Args

• rect (Rect) — The rectangular area to query.

Returns

list[Body]: A list of bodies overlapping the area.

query_point(self, point: Vec2) -> list[physics.Body]

Find all bodies that contain the specified point.

Args

• point (Vec2) — The point to query in world coordinates.

Returns

list[Body]: A list of bodies at the point.

ray_cast(self, origin: Vec2, translation: Vec2) -> list[physics.CastHit]

Cast a ray into the world and find all bodies that intersect it.

Args

• origin (Vec2) — The starting point of the ray.
• translation (Vec2) — The direction and length of the ray.

Returns

list[RayCastHit]: A list of hits, sorted by distance (fraction).

shape_cast(self, circle: Circle, transform: Transform, translation: Vec2) -> list[physics.CastHit]

shape_cast(self, capsule: Capsule, transform: Transform, translation: Vec2) -> list[physics.CastHit]

shape_cast(self, polygon: Polygon, transform: Transform, translation: Vec2) -> list[physics.CastHit]

shape_cast(self, rect: Rect, transform: Transform, translation: Vec2) -> list[physics.CastHit]

Overloaded function.

1. shape_cast(self, circle: Circle, transform: Transform, translation: Vec2) -> list[physics.CastHit]

Cast a circular shape into the world.

Args

• circle (Circle) — The circular shape.
• transform (Transform) — The initial transform of the shape.
• translation (Vec2) — The movement vector.

Returns

list[ShapeCastHit]: A list of hits, sorted by distance.

2. shape_cast(self, capsule: Capsule, transform: Transform, translation: Vec2) -> list[physics.CastHit]

Cast a capsule shape into the world.

Args

• capsule (Capsule) — The capsule shape.
• transform (Transform) — The initial transform of the shape.
• translation (Vec2) — The movement vector.

Returns

list[ShapeCastHit]: A list of hits, sorted by distance.

3. shape_cast(self, polygon: Polygon, transform: Transform, translation: Vec2) -> list[physics.CastHit]

Cast a polygonal shape into the world.

Args

• polygon (Polygon) — The polygonal shape.
• transform (Transform) — The initial transform of the shape.
• translation (Vec2) — The movement vector.

Returns

list[ShapeCastHit]: A list of hits, sorted by distance.

4. shape_cast(self, rect: Rect, transform: Transform, translation: Vec2) -> list[physics.CastHit]

Cast a rectangular shape into the world.

Args

• rect (Rect) — The rectangular shape.
• transform (Transform) — The initial transform of the shape.
• translation (Vec2) — The movement vector.

Returns

list[ShapeCastHit]: A list of hits, sorted by distance.

step(self, delta: float) -> None

Advance this world by a positive, finite delta in seconds. Run gameplay updates before this call and read collision events afterward. Use the deltas yielded by physics.fixed_steps() for fixed-rate simulation. No world is automatically stepped by window.is_open().