gale.physics.world module

This file contains the implementation of the class World: a physics simulation, in pixel units, wrapping a Box2D world without ever exposing Box2D itself — creates every Body/Joint, steps the simulation, and dispatches collision callbacks.

Author: Alejandro Mujica (aledrums@gmail.com)

class gale.physics.world.World(gravity=(0, 900), pixels_per_meter=30.0, fixed_timestep=0.016666666666666666)[source]

Bases: object

A physics simulation, in pixel units. Wraps a Box2D world (never exposed) and every Body/Joint created in it.

Follows the same update/fixed_update split Unity uses to decouple the game loop’s real, variable dt from the fixed timestep Box2D’s solver needs for stable results: call update(dt) once a frame, same as everything else in gale; it accumulates dt and calls fixed_update() (a real Box2D step) as many times as needed to consume it. fixed_update() is itself a public method, useful for tests (or the rare game) that want to drive the simulation one fixed step at a time directly.

Usage example:

world = World(gravity=(0, 900)) ground = world.create_static_body(200, 280, BoxShape(400, 20)) ball = world.create_dynamic_body(200, 50, CircleShape(radius=10))

# In your state: def update(self, dt: float) -> None:

self.world.update(dt)

Parameters:

  • gravity (Tuple[float, float])

  • pixels_per_meter (float)

  • fixed_timestep (float)

create_static_body(x, y, shape=None)[source]
Parameters:

  • x (float) – Initial x position, in pixels.

  • y (float) – Initial y position, in pixels.

  • shape (Any | None) – A CircleShape/BoxShape/PolygonShape to attach immediately. The default value is None, so fixtures can be added later via Body.add_circle/add_box/add_polygon.

Returns:

The new Body.

Return type:

Body

create_dynamic_body(x, y, shape=None)[source]
Parameters:

  • x (float) – Initial x position, in pixels.

  • y (float) – Initial y position, in pixels.

  • shape (Any | None) – A CircleShape/BoxShape/PolygonShape to attach immediately. The default value is None, so fixtures can be added later via Body.add_circle/add_box/add_polygon.

Returns:

The new Body.

Return type:

Body

create_kinematic_body(x, y, shape=None)[source]
Parameters:

  • x (float) – Initial x position, in pixels.

  • y (float) – Initial y position, in pixels.

  • shape (Any | None) – A CircleShape/BoxShape/PolygonShape to attach immediately. The default value is None, so fixtures can be added later via Body.add_circle/add_box/add_polygon.

Returns:

The new Body.

Return type:

Body

destroy_body(body)[source]
Parameters:

body (Body) – The Body to remove from this World.

Return type:

None

create_revolute_joint(body_a, body_b, anchor, **options)[source]
Parameters:

  • body_a (Body) – The first body.

  • body_b (Body) – The second body.

  • anchor (Tuple[float, float]) – The pivot point, in pixels, in world coordinates.

  • options (Any) – Forwarded to Box2D’s revolute joint definition (e.g. enableLimit, lowerAngle, upperAngle).

Returns:

The new RevoluteJoint.

Return type:

RevoluteJoint

create_wheel_joint(body_a, body_b, anchor, axis=(0, 1), **options)[source]
Parameters:

  • body_a (Body) – The chassis (or other body the wheel is attached to).

  • body_b (Body) – The wheel.

  • anchor (Tuple[float, float]) – The suspension’s attachment point, in pixels, in world coordinates.

  • axis (Tuple[float, float]) – The suspension’s movement axis, in body_a’s local frame. The default value is (0, 1) (straight up/down).

  • options (Any) – Forwarded to Box2D’s wheel joint definition (e.g. frequencyHz, dampingRatio, maxMotorTorque, motorSpeed, enableMotor).

Returns:

The new WheelJoint.

Return type:

WheelJoint

destroy_joint(joint)[source]
Parameters:

joint (Joint) – The Joint to remove from this World.

Return type:

None

on_collision_begin(callback)[source]
Parameters:

callback (Callable[[Body, Body], None]) – Called with (body_a, body_b) when two fixtures start touching. At least one of the two must not be a sensor for physical collision response; either or both may be sensors for overlap-only detection.

Return type:

None

on_collision_end(callback)[source]
Parameters:

callback (Callable[[Body, Body], None]) – Called with (body_a, body_b) when two fixtures that were touching stop touching.

Return type:

None

update(dt)[source]

Call once a frame with the real, variable elapsed time. Steps the simulation forward by calling fixed_update() as many times as the accumulated time covers.

Parameters:

dt (float) – Time elapsed, in seconds, since the last call.

Return type:

None

fixed_update()[source]

Advance the simulation by exactly one fixed_timestep.

Return type:

None

render_debug(surface, color=(0, 255, 0))[source]

Draw every fixture’s outline directly onto surface, with no assets — a debugging aid for building a level.

Parameters:

  • surface (Surface) – The surface to draw on.

  • color – The outline color. The default value is (0, 255, 0).

Return type:

None