impetus 0.23.3

Physics engine — 2D/3D rigid body simulation, collision detection, constraints, and spatial queries for AGNOS
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

# Impetus

**Impetus** (Latin: *impetus* — driving force, the medieval theory of why
objects keep moving after being thrown) is a physics engine for the AGNOS
ecosystem. It provides 2D/3D rigid-body simulation with deterministic stepping,
serializable state, physics particles, and standalone spring animation.

Built on [hisab](https://github.com/MacCracken/hisab) — the AGNOS math
library — for vector/quaternion math (DVec3, DQuat), geometry, and numerical
methods. No external physics engine dependencies; the entire simulation stack
is owned in-house.

## Architecture

Impetus is a pure physics library — no ECS, no rendering, no scene loading.
It sits at the foundation layer, consumed by:

- **Kiran** — game engine (ECS integration via kiran-physics bridge)
- **Aethersafha** — desktop compositor (window spring animations, snapping physics)
- **Simulation workloads** — headless agent training environments via daimon

See [docs/architecture/overview.md](docs/architecture/overview.md) for the full module map and simulation pipeline.

## Features

- **2D and 3D** — feature-gated backends with spatial hash broadphase
- **Native f64** — full double precision via hisab's DVec3/DQuat
- **Deterministic** — fixed timestep, reproducible simulation for replay and network sync
- **Serializable** — bincode world snapshots for save/load and network state transfer
- **Physics particles** — debris, projectiles with gravity, drag, collider interaction, emitters
- **Spring animation** — standalone damped harmonic oscillator (1D/2D/3D) for UI/compositor use
- **Unit-aware** — `Quantity` type with `PhysicsUnit` enum (Newtons, meters, kg, etc.)
- **Material presets** — ice, rubber, wood, steel, bouncy with physically plausible defaults
- **Joint system** — fixed, revolute, prismatic, spring, distance constraints
- **Spatial queries** — raycast with hit point and normal
- **Collision events** — started/stopped events with contact data
- **Zero external physics deps** — broadphase, narrowphase, solver all built on hisab

## Quick Start

```rust
use impetus::{PhysicsWorld, WorldConfig, BodyDesc, BodyType,
              ColliderDesc, ColliderShape, PhysicsMaterial, Force};

let mut world = PhysicsWorld::new(WorldConfig::default());

// Add a dynamic ball
let ball = world.add_body(BodyDesc {
    body_type: BodyType::Dynamic,
    position: [0.0, 10.0, 0.0],
    ..Default::default()
});
world.add_collider(ball, ColliderDesc {
    shape: ColliderShape::Ball { radius: 0.5 },
    offset: [0.0, 0.0, 0.0],
    material: PhysicsMaterial::rubber(),
    is_sensor: false,
    mass: None,
});

// Add a static floor
let floor = world.add_body(BodyDesc {
    body_type: BodyType::Static,
    position: [0.0, 0.0, 0.0],
    ..Default::default()
});
world.add_collider(floor, ColliderDesc {
    shape: ColliderShape::Box { half_extents: [50.0, 0.5, 50.0] },
    offset: [0.0, 0.0, 0.0],
    material: PhysicsMaterial::wood(),
    is_sensor: false,
    mass: None,
});

// Apply a sideways force and step
world.apply_force(ball, Force::new(5.0, 0.0, 0.0));
world.step();
```

## Spring Animation

Standalone springs for UI — no world needed:

```rust
use impetus::Spring2d;

let mut pos = Spring2d::critically_damped([0.0, 0.0], [500.0, 300.0], 400.0);
// Each frame:
pos.step(1.0 / 60.0);
let [x, y] = pos.position();
```

## Feature Flags

| Flag | Default | Description |
|------|---------|-------------|
| `2d` | yes | 2D physics backend |
| `3d` | no | 3D physics backend (uses hisab DVec3/DQuat) |
| `serialize` | no | bincode world snapshots |
| `full` | no | all features |

## Documentation

- [Architecture overview](docs/architecture/overview.md)
- [Development roadmap](docs/development/roadmap.md)
- [Testing guide](docs/guides/testing.md)

## License

GPL-3.0 — see [LICENSE](LICENSE).