physics

physics

The physics module provides types and step functions for common Newtonian mechanics systems: projectiles, spring-mass oscillators, n-body gravitational systems, and AABB collision detection.

Import

from std::physics::types use { Particle, OscillatorState, ProjectileState }
from std::physics::mechanics use { projectile_step, spring_mass_step, n_body_step }
from std::physics::simulation use { simulate_projectile, simulate_oscillator, simulate_n_body }
from std::physics::collision use { aabb, aabb_overlaps, find_collisions_sweep }

Types

Particle

State for an n-body gravitational particle:

Field	Type	Description
position	[number, number, number]	Position vector [x, y, z]
velocity	[number, number, number]	Velocity vector [vx, vy, vz]
mass	number	Particle mass

OscillatorState

State for a 1D spring-mass oscillator:

Field	Type	Description
x	number	Displacement from equilibrium
v	number	Velocity

ProjectileState

State for a 2D ballistic projectile:

Field	Type	Description
x	number	Horizontal position
y	number	Vertical position
vx	number	Horizontal velocity
vy	number	Vertical velocity
t	number	Elapsed time

Mechanics Step Functions

These functions advance a system by one time step dt:

• projectile_step(state, dt, g?) — Advance a projectile (no drag). Default gravity: 9.81 m/s^2.
• spring_mass_step(state, k, m, dt, damping?) — Advance a spring-mass oscillator.
• n_body_step(particles, dt, G?) — Advance an n-body gravitational system by one step. Uses pairwise acceleration with softening.

Simulation Wrappers

Convenience functions that iterate step functions over time:

• simulate_projectile(initial_state, t_end, dt, g?) — Run projectile until t_end or y < 0. Returns array of states.
• simulate_oscillator(initial_state, k, m, t_end, dt, damping?) — Run oscillator for a fixed duration.
• simulate_n_body(particles, steps, dt, G?) — Run n-body system for a number of steps.

Example: Projectile

from std::physics::simulation use { simulate_projectile }

let trajectory = simulate_projectile(
    { x: 0.0, y: 0.0, vx: 10.0, vy: 20.0, t: 0.0 },
    5.0,   // t_end
    0.01   // dt
)
for state in trajectory {
    print(f"t={state.t:fixed(2)} x={state.x:fixed(2)} y={state.y:fixed(2)}")
}

Collision Detection (std::physics::collision)

AABB (Axis-Aligned Bounding Box) collision detection primitives:

Constructors

• aabb(min_x, min_y, max_x, max_y) — Create from min/max corners.
• aabb_centered(cx, cy, hw, hh) — Create centered at (cx, cy) with half-extents.
• aabb_from_pos(x, y, w, h) — Create from position and size.

Overlap Tests

• aabb_overlaps(a, b) -> bool — Test if two AABBs overlap.
• aabb_contains(a, b) -> bool — Test if a fully contains b.
• aabb_contains_point(box, px, py) -> bool — Test if point is inside AABB.
• aabb_overlap_area(a, b) -> number — Compute overlap area (0 if none).

Geometry

• aabb_union(a, b) — Smallest enclosing AABB.
• aabb_intersection(a, b) — Intersection AABB or None.
• aabb_expand(box, margin) — Expand by margin on all sides.
• aabb_center(box) — Center point { x, y }.
• aabb_size(box) — Dimensions { width, height }.
• aabb_separation(a, b) — Minimum separation vector or None.

Broad-Phase

• find_collisions_brute(boxes) -> Array<{i, j}> — Brute force O(n^2) pair detection.
• find_collisions_sweep(boxes) -> Array<{i, j}> — Sort-and-sweep broad-phase (more efficient for sparse scenes).

Response

• elastic_response(body_a, body_b) — Elastic collision response. Bodies are { aabb, vx, vy, mass }. Returns post-collision velocities.

See Also

• Simulation — generic simulation framework