`simvx.core.physics.world2d`¶

Role¶

This module defines Physics2DWorld, the abstract interface every 2D physics backend (BuiltinPhysics2D now, an optional PymunkPhysics2D later) implements. It is the 2D sibling of :class:~simvx.core.physics.world.PhysicsWorld and serves the same purpose: a transport abstraction that moves rigid-body state across the Python boundary efficiently, not a definition of solver behaviour.

A SEPARATE seam (not the 3D one constrained to a plane) is deliberate (design physics_2d_design.md): the bulk contract width differs ((N,4) transforms / (N,3) velocities here vs (N,7) / (N,6) in 3D), the optional native backend differs (pymunk / Chipmunk2D vs Jolt), and rotation is a scalar radian angle rather than a quaternion. Dimension-agnostic pieces (:class:BodyMode,

class:: CombineMode, :class:ContactPhase, :class:PhysicsMaterial) are REUSED by import from the 3D modules, never duplicated.

World convention (state it loudly)¶

Y-up, identical to the 3D world. Gravity defaults to Vec2(0, -9.81): down is -Y. A Y-down game (renders +Y downward on screen) simply sets gravity=Vec2(0, 9.81); the seam itself stays neutral and never assumes a screen orientation. Rotation is a scalar angle in radians, positive counter-clockwise (standard math convention).

The load-bearing part of the contract is the bulk-array transfer: per-frame body state is exchanged as a single numpy buffer (one transfer per world per frame), in a fixed body->row order, by filling a caller-preallocated array in place. The transform row is (N, 4) = [px, py, cos(theta), sin(theta)] (cos/sin rather than the bare angle so interpolation lerps the unit vector with no +-pi wraparound, matching Transform2D and the pymunk angle convention); the velocity row is (N, 3) = [lx, ly, omega] (linear x/y plus scalar angular velocity in radians/s). See :meth:register_bodies,

meth:: read_transforms, and :meth:read_velocities.

Stage T2a status¶

This module defines the FULL ABC surface so subclasses have a complete contract. BuiltinPhysics2D implements the T2a subset (gravity, shapes, bodies, integrator, bulk readers); the collision-dependent methods (queries, events, joints, forces, character, one-way) are declared @abstractmethod here and filled by later sub-stages (T2b-T2e), with honest NotImplementedError stubs in the backend until then.

Physics2DWorld: the 2D backend transport seam (Stage T2 additive scaffolding).

Module Contents¶

Classes¶

`RaycastHit2D`	Result of a successful 2D raycast against the world (T2d).
`Contact2D`	Result of a kinematic / character shape-sweep stopping against a body (T2d).
`ContactEvent2D`	A node-agnostic 2D body-pair collision event emitted by the seam (T2d).
`OverlapEvent2D`	A node-agnostic 2D sensor-overlap event emitted by the seam (T2d).
`CharacterMoveResult2D`	Returned struct of a 2D character collide-and-slide move (T2e).
`Physics2DWorld`	Abstract 2D backend seam: one isolated simulation world.

Data¶

`BodyHandle`
`ShapeHandle`
`CharacterHandle`
`JointHandle`
`__all__`

API¶

simvx.core.physics.world2d.BodyHandle¶: None

simvx.core.physics.world2d.ShapeHandle¶: None

simvx.core.physics.world2d.CharacterHandle¶: None

simvx.core.physics.world2d.JointHandle¶: None

class simvx.core.physics.world2d.RaycastHit2D[source]¶

Result of a successful 2D raycast against the world (T2d).

Attributes: body: Handle of the body the ray hit. point: World-space contact point (Vec2). normal: World-space surface normal at the hit (Vec2, unit length). distance: Distance from the ray origin to point along the ray.

body: simvx.core.physics.world2d.BodyHandle¶: None

point: simvx.core.math.Vec2¶: None

normal: simvx.core.math.Vec2¶: None

distance: float¶: None

class simvx.core.physics.world2d.Contact2D[source]¶

Result of a kinematic / character shape-sweep stopping against a body (T2d).

2D sibling of :class:~simvx.core.physics.world.Contact: a single “other” body (like a query result); the swept body is implicit (the caller).

Attributes: body: Handle of the OTHER body that was hit. point: World-space contact point (Vec2). normal: World-space surface normal (Vec2, unit), pointing AWAY from the other body toward the moving body (the direction that separates the mover). distance: Distance the mover actually travelled before contact (TOI distance, 0..|motion|).

body: simvx.core.physics.world2d.BodyHandle¶: None

point: simvx.core.math.Vec2¶: None

normal: simvx.core.math.Vec2¶: None

distance: float¶: None

class simvx.core.physics.world2d.ContactEvent2D[source]¶

A node-agnostic 2D body-pair collision event emitted by the seam (T2d).

2D sibling of :class:~simvx.core.physics.world.ContactEvent. Keyed by body HANDLES only (the seam never names a node); orientation is fixed a -> b. Reuses :class:ContactPhase (no second phase enum).

Attributes: a: Handle of the first body of the pair (canonical order). b: Handle of the second body of the pair. phase: :class:ContactPhase (ENTER / EXIT). point: World contact point (Vec2). Meaningful on ENTER; degenerate (Vec2(0)) on EXIT. normal: Unit contact normal oriented a -> b (Vec2). Degenerate (Vec2(0)) on EXIT. impulse: Normal impulse magnitude applied to the pair this step. 0 on EXIT and 0 on an ENTER where the solver applied none. rel_velocity: Pre-solve velocity of b w.r.t. a at the contact (Vec2). Degenerate (Vec2(0)) on EXIT.

a: simvx.core.physics.world2d.BodyHandle¶: None

b: simvx.core.physics.world2d.BodyHandle¶: None

phase: simvx.core.physics.world.ContactPhase¶: None

point: simvx.core.math.Vec2¶: None

normal: simvx.core.math.Vec2¶: None

impulse: float¶: None

rel_velocity: simvx.core.math.Vec2¶: None

class simvx.core.physics.world2d.OverlapEvent2D[source]¶

A node-agnostic 2D sensor-overlap event emitted by the seam (T2d).

2D sibling of :class:~simvx.core.physics.world.OverlapEvent: a SECOND, independent edge-diffed stream. DIRECTED sensor -> other (the observing sensor decides via its mask). Reuses :class:ContactPhase.

Attributes: sensor: Handle of the detecting sensor body (the observer). other: Handle of the detected body (a normal body OR another sensor). phase: :class:ContactPhase (ENTER / EXIT).

sensor: simvx.core.physics.world2d.BodyHandle¶: None

other: simvx.core.physics.world2d.BodyHandle¶: None

phase: simvx.core.physics.world.ContactPhase¶: None

class simvx.core.physics.world2d.CharacterMoveResult2D[source]¶

Returned struct of a 2D character collide-and-slide move (T2e).

2D sibling of :class:~simvx.core.physics.world.CharacterMoveResult. Floor/wall/ceiling are computed seam-side from contact normals vs up (and the character’s slope_limit) so every backend exposes identical semantics.

Attributes: velocity: Post-slide velocity (deflected along contact normals); the caller writes this back as its new velocity (Vec2). on_floor: True if a contact this move was classified as floor. on_wall: True if a contact this move was classified as wall. on_ceiling: True if a contact this move was classified as ceiling. floor_normal: Normal of the floor contact this move (unit Vec2), or +up if there was no floor contact.

velocity: simvx.core.math.Vec2¶: None

on_floor: bool¶: None

on_wall: bool¶: None

on_ceiling: bool¶: None

floor_normal: simvx.core.math.Vec2¶: None

class simvx.core.physics.world2d.Physics2DWorld(*, gravity: simvx.core.math.Vec2)[source]¶

Bases: abc.ABC

Abstract 2D backend seam: one isolated simulation world.

A Physics2DWorld owns a set of bodies, advances them as a unit at a fixed timestep via :meth:step, and exchanges per-frame state in bulk. Concrete backends (BuiltinPhysics2D, later PymunkPhysics2D) implement every method.

Bulk-array contract (the keystone)

Call :meth:register_bodies once (or whenever membership changes) to fix the body->row order used by the bulk readers.
Each frame, after :meth:step, call :meth:read_transforms and/or

meth:

read_velocities, passing a caller-preallocated, C-contiguous float32 numpy array of the documented shape. The backend fills it in place; it must not allocate or return a new array on the hot path.

The array shapes/dtypes/contiguity are part of the contract and MUST be asserted by subclasses (see _check_transforms_out / _check_velocities_out). The transform row is (N, 4) = [px, py, cos(theta), sin(theta)] and the velocity row is (N, 3) = [lx, ly, omega] (see the module docstring for the Y-up / radians convention).

Initialization

Initialise the world.

Args: gravity: World gravity acceleration vector (Vec2), metres/s^2. Y-up: Vec2(0, -9.81) is “down”.

property gravity: simvx.core.math.Vec2[source]¶: World gravity acceleration vector (Vec2), metres/s^2 (Y-up).

capabilities() → frozenset[simvx.core.physics.capability.Capability][source]¶

Return the set of Tier-3 :class:Capability features this 2D backend honours.

2D sibling of :meth:~simvx.core.physics.world.PhysicsWorld.capabilities, sharing the same dimension-agnostic :class:Capability enum. The default is the empty set (a backend advertises nothing it cannot honour); native backends override to list only what they actually support.

abstractmethod create_circle(radius: float) → simvx.core.physics.world2d.ShapeHandle[source]¶

Create a circle collision shape and return an opaque handle.

Args: radius: Circle radius, world units (> 0).