Struct PyPhysicsWorld 

pub struct PyPhysicsWorld { /* private fields */ }

A self-contained physics simulation world.

Provides Python-friendly methods using integer handles (u32) and plain array types. Internally uses a slot-based arena with generation counters so that stale handles are detected as absent bodies.

Implementations

impl PyPhysicsWorld

Extension: constraint storage and resolution on PyPhysicsWorld.

pub fn add_constraint(&mut self, c: PyConstraint) -> u32

Add a constraint to the world. Returns the constraint handle.

Note: constraint handles are auto-incremented independently of body handles.

pub fn remove_constraint(&mut self, handle: u32) -> bool

Remove a constraint by handle. Returns true if found.

pub fn constraint_count(&self) -> usize

Return the number of active constraints.

impl PyPhysicsWorld

pub fn compute_total_energy(&self) -> (f64, f64, f64)

Compute total mechanical energy: kinetic energy + gravitational potential energy.

KE = Σ ½ m v² (summed over dynamic bodies) PE = Σ m * |g| * h (height measured along gravity direction; uses Y component of gravity)

Returns (kinetic, potential, total).

pub fn apply_gravity_field<F>(&mut self, field: F)

where F: Fn([f64; 3]) -> [f64; 3],

Apply a spatially varying gravity field to all dynamic bodies for one step.

The field is specified as a closure f(position) -> [f64; 3] mapping a body’s world-space position to a gravitational acceleration vector.

This method accumulates forces based on the field and does not step the simulation; call step() afterwards.

Example

Radial gravity toward the origin:

world.apply_gravity_field(|p| {
    let r2 = p[0]*p[0] + p[1]*p[1] + p[2]*p[2] + 1e-6;
    let r = r2.sqrt();
    [-9.81 * p[0] / r, -9.81 * p[1] / r, -9.81 * p[2] / r]
});

pub fn get_contact_list(&self) -> Vec<ContactPair>

Return the list of contact pairs from the most recent simulation step.

Each entry contains the two body handles and contact geometry.

impl PyPhysicsWorld

pub fn stats(&self) -> SimStats

Return simulation statistics for the current state.

pub fn body_kinetic_energy(&self, handle: u32) -> Option<f64>

Return the kinetic energy of a single body, or None if not found.

pub fn closest_body(&self, point: [f64; 3]) -> Option<(u32, f64)>

Return the closest active body handle to point, or None if empty.

pub fn bodies_in_sphere(&self, center: [f64; 3], radius: f64) -> Vec<u32>

Return handles of all bodies within radius of center.

pub fn closest_pair(&self) -> Option<(u32, u32, f64)>

Find the pair of bodies with the smallest center-to-center distance.

Returns None if fewer than 2 bodies are present.

impl PyPhysicsWorld

pub fn new(config: PySimConfig) -> Self

Create a new physics world with the given simulation config.

pub fn add_rigid_body(&mut self, config: PyRigidBodyConfig) -> u32

Add a new rigid body described by config. Returns a u32 handle.

pub fn add_body_legacy(&mut self, desc: &PyRigidBodyDesc) -> u32

Add a rigid body using the legacy PyRigidBodyDesc interface.

pub fn add_collider(&mut self, handle: u32, desc: &PyColliderDesc)

Add a collider shape to the body with the given handle.

Does nothing if the handle is invalid.

pub fn remove_body(&mut self, handle: u32) -> bool

Remove a body by handle. Returns true if the body existed.

pub fn get_position(&self, handle: u32) -> Option<[f64; 3]>

Get the position of a body, or None if the handle is invalid.

pub fn get_velocity(&self, handle: u32) -> Option<[f64; 3]>

Get the linear velocity of a body, or None if the handle is invalid.

pub fn get_orientation(&self, handle: u32) -> Option<[f64; 4]>

Get the orientation quaternion [x, y, z, w], or None.

pub fn get_angular_velocity(&self, handle: u32) -> Option<[f64; 3]>

Get the angular velocity, or None.

pub fn is_sleeping(&self, handle: u32) -> bool

Whether the body with handle is currently sleeping.

pub fn get_tag(&self, handle: u32) -> Option<String>

Get the tag of a body, or None.

pub fn set_position(&mut self, handle: u32, pos: [f64; 3])

Set the position of a body.

pub fn set_velocity(&mut self, handle: u32, vel: [f64; 3])

Set the linear velocity of a body.

pub fn set_orientation(&mut self, handle: u32, orientation: [f64; 4])

Set the orientation (quaternion [x, y, z, w]) of a body.

pub fn set_angular_velocity(&mut self, handle: u32, omega: [f64; 3])

Set the angular velocity of a body.

pub fn apply_force( &mut self, handle: u32, force: [f64; 3], point: Option<[f64; 3]>, )

Apply a force [fx, fy, fz] to a body, optionally at a world-space point.

If point is None, the force is applied at the center of mass. Force accumulates until the next step().

pub fn apply_impulse( &mut self, handle: u32, impulse: [f64; 3], point: Option<[f64; 3]>, )

Apply an impulse [ix, iy, iz] directly to a body’s velocity.

An impulse is a instantaneous change in momentum: Δv = impulse / mass. If point is provided, an angular impulse is also applied.

pub fn apply_torque(&mut self, handle: u32, torque: [f64; 3])

Apply a torque [tx, ty, tz] to a body (accumulates until next step).

pub fn wake_body(&mut self, handle: u32)

Wake up a sleeping body.

pub fn sleep_body(&mut self, handle: u32)

Put a body to sleep.

pub fn set_gravity(&mut self, g: [f64; 3])

Set the gravity vector.

pub fn gravity(&self) -> [f64; 3]

Get the current gravity vector.

pub fn config(&self) -> &PySimConfig

Get the current simulation configuration.

pub fn body_count(&self) -> usize

Total number of allocated body slots (includes removed ones until reuse).

pub fn sleeping_count(&self) -> usize

Number of bodies currently sleeping.

pub fn time(&self) -> f64

Accumulated simulation time in seconds.

pub fn get_contacts(&self) -> Vec<PyContactResult>

Contacts from the most recent simulation step.

pub fn all_positions(&self) -> Vec<[f64; 3]>

Return all body positions as a flat Vec<[f64;3]> in handle order (skipping removed).

pub fn all_velocities(&self) -> Vec<[f64; 3]>

Return all body velocities in handle order (skipping removed).

pub fn active_handles(&self) -> Vec<u32>

Return all active (non-removed) handles.

pub fn step(&mut self, dt: f64)

Advance the simulation by dt seconds.

Uses symplectic Euler integration:

1. Accumulate gravity + applied forces.
2. Update velocity from forces.
3. Apply damping.
4. Update position from velocity.
5. Integrate orientation from angular velocity.
6. Run a simple sphere-sphere narrow-phase to detect contacts.
7. Resolve contacts with impulse-based collision response.
8. Update sleep state.
9. Clear accumulated forces.

pub fn reset(&mut self)

Reset the world: remove all bodies, clear contacts, constraints, reset time.

pub fn step_substeps(&mut self, dt: f64, substeps: u32)

Advance the simulation by dt seconds using substeps equal sub-steps.

This is useful when CCD is needed for fast-moving objects, or when a larger integration step must be subdivided for stability.

Example

world.step_substeps(1.0 / 60.0, 4); // 4 sub-steps of 1/240 s each

pub fn bodies_in_aabb(&self, aabb: [f64; 6]) -> Vec<u32>

Return the handles of all bodies whose centre-of-mass lies within aabb.

aabb is given as [xmin, ymin, zmin, xmax, ymax, zmax].

pub fn raycast( &self, origin: [f64; 3], dir: [f64; 3], max_dist: f64, ) -> Option<(u32, f64)>

Cast a ray from origin in direction dir and return the handle and hit distance of the nearest body whose sphere collider is struck.

Returns None if no body is hit within max_dist.

Direction dir need not be normalized; it is normalised internally.

pub fn contact_count(&self) -> usize

Return the total number of contacts from the most recent step.

pub fn get_body_position(&self, handle: usize) -> Option<PyVec3>

Legacy: get body position as PyVec3.

pub fn get_body_velocity(&self, handle: usize) -> Option<PyVec3>

Legacy: get body velocity as PyVec3.

pub fn set_body_velocity(&mut self, handle: usize, vel: PyVec3)

Legacy: set body velocity from PyVec3.

pub fn num_bodies(&self) -> usize

Legacy: return body count (same as body_count).

pub fn gravity_vec3(&self) -> PyVec3

Legacy: return gravity as PyVec3.

pub fn all_positions_vec3(&self) -> Vec<PyVec3>

Legacy: return all positions as VecPyVec3`.

Trait Implementations

impl Clone for PyPhysicsWorld

fn clone(&self) -> PyPhysicsWorld

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PyPhysicsWorld

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.