World

API reference for World. Access via the 'physics' submodule.

Experimental API:

The physics submodule is a VERY experimental and new API that is highly susceptible to breaking changes in the future.

Constructor

Properties

NameDescriptionType
gravityThe gravity vector of the world.Vec2

Methods

Add Fixed Update

add_fixed_update(callback: Any) → None

Add a callback function to be executed during each physics step.

Clear Fixed Updates

clear_fixed_updates() → None

Remove all registered fixed update callbacks.

Create Distance Joint

create_distance_joint(
    body_a: Body,
    body_b: Body,
    anchor_a: Vec2,
    anchor_b: Vec2
) → DistanceJoint

Create 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

create_filter_joint(body_a: Body, body_b: Body) → FilterJoint

Create 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

create_motor_joint(body_a: Body, body_b: Body) → MotorJoint

Create 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

create_mouse_joint(
    ground_body: Body,
    pulled_body: Body,
    target: Vec2
) → MouseJoint

Create 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

create_prismatic_joint(
    body_a: Body,
    body_b: Body,
    anchor: Vec2,
    axis: Vec2
) → PrismaticJoint

Create 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

create_revolute_joint(body_a: Body, body_b: Body, anchor: Vec2) → RevoluteJoint

Create 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

create_weld_joint(body_a: Body, body_b: Body, anchor: Vec2) → WeldJoint

Create 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

create_wheel_joint(
    body_a: Body,
    body_b: Body,
    anchor: Vec2,
    axis: Vec2
) → WheelJoint

Create 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.

Fixed Callback

fixed_callback(callback: Any) → Any

A decorator to register a function as a physics update callback.

From Map Layer

from_map_layer(layer: tilemap.Layer) → 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 : The TileMap ObjectGroup layer.

Returns

StaticBody : The created static body with all shapes attached.

Get Collisions

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 Aabb

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.

Query Point

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.

Ray Cast

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).

Shape Cast

shape_cast(
    circle: Circle,
    transform: Transform,
    translation: Vec2
) → list[CastHit]

Cast a circular shape into the world.

Args

  • circle : The circular shape.
  • transform : The initial transform of the shape.
  • translation : The movement vector.

Returns

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

shape_cast(
    capsule: Capsule,
    transform: Transform,
    translation: Vec2
) → list[CastHit]

Cast a capsule shape into the world.

Args

  • capsule : The capsule shape.
  • transform : The initial transform of the shape.
  • translation : The movement vector.

Returns

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

shape_cast(
    polygon: Polygon,
    transform: Transform,
    translation: Vec2
) → list[CastHit]

Cast a polygonal shape into the world.

Args

  • polygon : The polygonal shape.
  • transform : The initial transform of the shape.
  • translation : The movement vector.

Returns

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

shape_cast(
    rect: Rect,
    transform: Transform,
    translation: Vec2
) → list[CastHit]

Cast a rectangular shape into the world.

Args

  • rect : The rectangular shape.
  • transform : The initial transform of the shape.
  • translation : The movement vector.

Returns

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