903 lines
33 KiB
Markdown
903 lines
33 KiB
Markdown
# Rapier Physics Engine - Complete Codebase Guide
|
||
|
||
## What is Rapier?
|
||
|
||
Rapier is a high-performance 2D and 3D physics engine written in Rust by Dimforge. It's designed for games, animation, and robotics applications, offering deterministic simulations, snapshot/restore capabilities, and cross-platform support (including WASM).
|
||
|
||
**License:** Apache 2.0 (free and open-source)
|
||
**Repository:** https://github.com/dimforge/rapier
|
||
**Documentation:** https://rapier.rs/docs/
|
||
**Crate:** https://crates.io/crates/rapier3d
|
||
|
||
## Key Features
|
||
|
||
- **Dual-dimensional support**: Both 2D (`rapier2d`) and 3D (`rapier3d`) with f32 and f64 precision variants
|
||
- **Deterministic simulation**: Identical results across different machines (IEEE 754-2008 compliant)
|
||
- **Snapshot & restore**: Complete physics state serialization
|
||
- **Cross-platform**: Desktop, mobile, web (WASM), consoles
|
||
- **Performance-focused**: SIMD optimizations, optional multi-threading, sleeping system
|
||
- **Flexible**: Can be used for full physics or just collision detection
|
||
|
||
## Repository Architecture
|
||
|
||
The repository uses an unusual structure to share code between 2D/3D versions:
|
||
|
||
```
|
||
rapier/
|
||
├── src/ # Shared source code (2D/3D agnostic)
|
||
├── crates/ # Concrete 2D/3D crate definitions
|
||
│ ├── rapier2d/ # 2D f32
|
||
│ ├── rapier3d/ # 3D f32
|
||
│ ├── rapier2d-f64/ # 2D f64
|
||
│ ├── rapier3d-f64/ # 3D f64
|
||
│ ├── rapier_testbed2d/ # 2D visual debugger
|
||
│ ├── rapier_testbed3d/ # 3D visual debugger
|
||
│ └── rapier3d-urdf/ # Robot model loader
|
||
├── examples2d/ # 2D demos
|
||
├── examples3d/ # 3D demos
|
||
├── benchmarks2d/ # 2D performance tests
|
||
├── benchmarks3d/ # 3D performance tests
|
||
└── src_testbed/ # Testbed source
|
||
```
|
||
|
||
## Core Modules Deep Dive
|
||
|
||
### 1. `src/dynamics/` - Physics Simulation
|
||
|
||
Handles movement, forces, and constraints.
|
||
|
||
#### RigidBody System
|
||
|
||
**`RigidBody`** (`rigid_body.rs`) - The fundamental physics object
|
||
- **Three body types:**
|
||
- `Dynamic`: Fully simulated - responds to forces, gravity, collisions
|
||
- `Fixed`: Never moves - infinite mass (walls, floors, terrain)
|
||
- `Kinematic`: User-controlled movement - pushes but isn't pushed (platforms, doors)
|
||
|
||
**Key properties:**
|
||
- Position/rotation: `translation()`, `rotation()`, `position()`
|
||
- Velocity: `linvel()`, `angvel()`, `set_linvel()`, `set_angvel()`
|
||
- Mass: `mass()`, `center_of_mass()`, computed from attached colliders
|
||
- Forces: `add_force()`, `add_torque()`, `add_force_at_point()` (continuous, cleared each step)
|
||
- Impulses: `apply_impulse()`, `apply_torque_impulse()`, `apply_impulse_at_point()` (instant)
|
||
- Damping: `linear_damping()`, `angular_damping()` (air resistance, drag)
|
||
- Sleeping: `sleep()`, `wake_up()`, `is_sleeping()` (performance optimization)
|
||
- CCD: `enable_ccd()`, prevents fast objects tunneling through walls
|
||
- Locking: `lock_rotations()`, `lock_translations()`, `set_locked_axes()` (constrain movement)
|
||
- Gravity: `gravity_scale()`, `set_gravity_scale()` (0.0 = zero-g, 1.0 = normal, 2.0 = heavy)
|
||
- Energy: `kinetic_energy()`, `gravitational_potential_energy()`
|
||
- Prediction: `predict_position_using_velocity()`, `predict_position_using_velocity_and_forces()`
|
||
|
||
**`RigidBodySet`** (`rigid_body_set.rs`) - Collection of all bodies
|
||
- Handle-based storage (generational indices prevent use-after-free)
|
||
- Methods: `insert()`, `remove()`, `get()`, `get_mut()`, `iter()`, `contains()`
|
||
- `propagate_modified_body_positions_to_colliders()` for manual position sync
|
||
|
||
**`RigidBodyBuilder`** - Builder pattern for creating bodies
|
||
- Type constructors: `dynamic()`, `fixed()`, `kinematic_velocity_based()`, `kinematic_position_based()`
|
||
- Configuration: `translation()`, `rotation()`, `linvel()`, `angvel()`
|
||
- Settings: `gravity_scale()`, `can_sleep()`, `ccd_enabled()`, `linear_damping()`, `angular_damping()`
|
||
- Constraints: `locked_axes()`, `lock_rotations()`, `lock_translations()`, `enabled_rotations()`
|
||
- Advanced: `dominance_group()`, `additional_mass()`, `enable_gyroscopic_forces()`
|
||
|
||
#### Joint System
|
||
|
||
**Joint Types** (all in `src/dynamics/joint/`):
|
||
|
||
1. **`FixedJoint`**: Welds two bodies rigidly together
|
||
2. **`RevoluteJoint`**: Hinge - rotation around one axis (doors, wheels)
|
||
3. **`PrismaticJoint`**: Slider - translation along one axis (pistons, elevators)
|
||
4. **`SphericalJoint`**: Ball-and-socket - free rotation, fixed position (shoulders, gimbals)
|
||
5. **`RopeJoint`**: Maximum distance constraint (ropes, cables, tethers)
|
||
6. **`SpringJoint`**: Elastic connection with stiffness/damping (suspension, soft constraints)
|
||
|
||
**Joint Features:**
|
||
- **Motors**: Powered actuation with `set_motor_velocity()`, `set_motor_position()`
|
||
- Velocity control: constant speed rotation/sliding
|
||
- Position control: spring-like movement toward target
|
||
- Max force limits: `set_motor_max_force()`
|
||
- Motor models: `AccelerationBased` (mass-independent) vs `ForceBased` (mass-dependent)
|
||
- **Limits**: Restrict range with `set_limits([min, max])`
|
||
- **Anchors**: Connection points in each body's local space
|
||
|
||
**`ImpulseJointSet`** - Collection of all joints
|
||
- Methods: `insert()`, `remove()`, `get()`, `get_mut()`, `iter()`
|
||
- Queries: `joints_between()`, `attached_joints()`, `attached_enabled_joints()`
|
||
|
||
#### Integration & Solving
|
||
|
||
**`IntegrationParameters`** - Controls simulation behavior
|
||
- `dt`: Timestep (1/60 for 60 FPS, 1/120 for 120 FPS)
|
||
- `num_solver_iterations`: Accuracy vs speed (4 = default, 8-12 = high quality, 1-2 = fast)
|
||
- `length_unit`: Scale factor if not using meters (100.0 for pixel-based 2D)
|
||
- `contact_natural_frequency`, `contact_damping_ratio`: Contact compliance
|
||
- `joint_natural_frequency`, `joint_damping_ratio`: Joint compliance
|
||
- Advanced: warmstarting, prediction distance, stabilization iterations
|
||
|
||
**`IslandManager`** - Sleeping/waking optimization
|
||
- Groups connected bodies into "islands" for parallel solving
|
||
- Automatically sleeps bodies at rest (huge performance gain)
|
||
- Wakes bodies when disturbed by collisions/joints
|
||
- Sleep thresholds configurable via `RigidBodyActivation`
|
||
|
||
**`CCDSolver`** - Prevents tunneling
|
||
- Detects fast-moving bodies that might pass through geometry
|
||
- Predicts time-of-impact and clamps motion
|
||
- Enable per-body with `ccd_enabled(true)`
|
||
- Soft-CCD: cheaper predictive variant with `set_soft_ccd_prediction()`
|
||
|
||
### 2. `src/geometry/` - Collision Detection
|
||
|
||
#### Collider System
|
||
|
||
**`Collider`** - Collision shape ("hitbox") attached to bodies
|
||
- **Shapes**: Ball, Cuboid, Capsule, Cylinder, Cone, Triangle, Segment, HeightField, TriMesh, Compound, ConvexHull
|
||
- **Material properties:**
|
||
- Friction: 0.0 = ice, 0.5 = wood, 1.0 = rubber
|
||
- Restitution: 0.0 = clay (no bounce), 1.0 = perfect elastic, >1.0 = super bouncy
|
||
- Combine rules: Average, Min, Max, Multiply (how to combine when two colliders touch)
|
||
- **Mass:** Set via `density()` (kg/m³) or `mass()` (kg directly)
|
||
- **Sensors:** `set_sensor(true)` for trigger zones (detect overlaps without physical collision)
|
||
- **Position:** `position()`, `translation()`, `rotation()`, `position_wrt_parent()`
|
||
- **Groups:** `collision_groups()`, `solver_groups()` for layer-based filtering
|
||
- **Events:** `active_events()`, `contact_force_event_threshold()` for collision notifications
|
||
- **Shape queries:** `compute_aabb()`, `compute_swept_aabb()`, `volume()`, `mass_properties()`
|
||
- **Enabled:** `set_enabled()` to temporarily disable without removal
|
||
|
||
**`ColliderSet`** - Collection of all colliders
|
||
- Methods: `insert()`, `insert_with_parent()`, `remove()`, `set_parent()`
|
||
- Access: `get()`, `get_mut()`, `iter()`, `iter_enabled()`
|
||
- Invalid handle: `ColliderSet::invalid_handle()`
|
||
|
||
**`ColliderBuilder`** - Creates colliders with builder pattern
|
||
- **Primitive shapes:**
|
||
- `ball(radius)` - Sphere/circle
|
||
- `cuboid(hx, hy, hz)` - Box (half-extents)
|
||
- `capsule_y(half_height, radius)` - Pill shape (best for characters!)
|
||
- `cylinder(half_height, radius)`, `cone(half_height, radius)` (3D only)
|
||
- **Complex shapes:**
|
||
- `trimesh(vertices, indices)` - Triangle mesh (slow but accurate)
|
||
- `heightfield(heights, scale)` - Terrain from height grid
|
||
- `convex_hull(points)` - Smallest convex shape containing points
|
||
- `convex_decomposition(vertices, indices)` - Breaks concave mesh into convex pieces
|
||
- `segment(a, b)`, `triangle(a, b, c)` - Simple primitives
|
||
- **Configuration:**
|
||
- Material: `friction()`, `restitution()`, `density()`, `mass()`
|
||
- Filtering: `collision_groups()`, `sensor()`
|
||
- Events: `active_events()`, `contact_force_event_threshold()`
|
||
- Position: `translation()`, `rotation()`, `position()`
|
||
- Advanced: `active_hooks()`, `active_collision_types()`, `contact_skin()`
|
||
|
||
#### Collision Detection Pipeline
|
||
|
||
**`BroadPhaseBvh`** - First pass: quickly find nearby pairs
|
||
- Uses hierarchical BVH tree for spatial indexing
|
||
- Filters out distant objects before expensive narrow-phase
|
||
- Incrementally updated as objects move
|
||
- Optimization strategies: `SubtreeOptimizer` (default) vs `None`
|
||
|
||
**`NarrowPhase`** - Second pass: compute exact contacts
|
||
- Calculates precise contact points, normals, penetration depths
|
||
- Builds contact manifolds (groups of contacts sharing properties)
|
||
- Managed automatically by PhysicsPipeline
|
||
- Access via `contact_graph()` for querying contact pairs
|
||
|
||
**`ContactPair`** - Detailed collision information
|
||
- Methods: `total_impulse()`, `total_impulse_magnitude()`, `max_impulse()`, `find_deepest_contact()`
|
||
- Contains multiple `ContactManifold` structures
|
||
- Each manifold has contact points with normals, distances, solver data
|
||
|
||
#### Collision Filtering
|
||
|
||
**`InteractionGroups`** - Layer-based collision control
|
||
- Two components: `memberships` (what groups I'm in) and `filter` (what groups I collide with)
|
||
- 32 groups available: `Group::GROUP_1` through `Group::GROUP_32`
|
||
- Bidirectional check: A and B collide only if A's memberships overlap B's filter AND vice versa
|
||
- Example: Player bullets (group 1) only hit enemies (group 2)
|
||
|
||
**`ActiveCollisionTypes`** - Filter by body type
|
||
- Controls which body type pairs can collide
|
||
- Defaults: Dynamic↔Dynamic ✓, Dynamic↔Fixed ✓, Dynamic↔Kinematic ✓, Fixed↔Fixed ✗
|
||
- Rarely changed - defaults are correct for most games
|
||
|
||
**`QueryFilter`** - Filter spatial queries
|
||
- Flags: `EXCLUDE_FIXED`, `EXCLUDE_DYNAMIC`, `EXCLUDE_SENSORS`, `ONLY_DYNAMIC`, etc.
|
||
- Groups: Filter by collision groups
|
||
- Exclusions: `exclude_collider`, `exclude_rigid_body`
|
||
- Custom: `predicate` closure for arbitrary filtering
|
||
|
||
### 3. `src/pipeline/` - Simulation Orchestration
|
||
|
||
**`PhysicsPipeline`** - The main simulation loop
|
||
- **`step()`**: Advances physics by one timestep
|
||
1. Handles user changes (moved bodies, added/removed colliders)
|
||
2. Runs collision detection (broad-phase → narrow-phase)
|
||
3. Builds islands and solves constraints (contacts + joints)
|
||
4. Integrates velocities to update positions
|
||
5. Runs CCD if needed
|
||
6. Generates events
|
||
- Reuse same instance for performance (caches data between frames)
|
||
|
||
**`CollisionPipeline`** - Collision detection without dynamics
|
||
- Use when you only need collision detection, not physics simulation
|
||
- Lighter weight than PhysicsPipeline
|
||
|
||
**`QueryPipeline`** - Spatial queries (created from BroadPhase)
|
||
- **Raycasting:**
|
||
- `cast_ray()` - First hit along ray
|
||
- `cast_ray_and_get_normal()` - Hit with surface normal
|
||
- `intersect_ray()` - ALL hits along ray
|
||
- **Shape casting:**
|
||
- `cast_shape()` - Sweep shape through space (thick raycast)
|
||
- `cast_shape_nonlinear()` - Non-linear motion sweep
|
||
- **Point queries:**
|
||
- `project_point()` - Find closest point on any collider
|
||
- `intersect_point()` - Find all colliders containing point
|
||
- **AABB queries:**
|
||
- `intersect_aabb_conservative()` - Find colliders in bounding box
|
||
- Filtering via `QueryFilter`
|
||
|
||
**`EventHandler`** trait - Receive physics events
|
||
- `handle_collision_event()` - When colliders start/stop touching
|
||
- `handle_contact_force_event()` - When contact forces exceed threshold
|
||
- Built-in: `ChannelEventCollector` sends events to mpsc channels
|
||
- Enable per-collider with `ActiveEvents` flags
|
||
|
||
**`PhysicsHooks`** trait - Custom collision behavior
|
||
- `filter_contact_pair()` - Decide if two colliders should collide
|
||
- `filter_intersection_pair()` - Filter sensor intersections
|
||
- `modify_solver_contacts()` - Modify contact properties before solving
|
||
- Enable per-collider with `ActiveHooks` flags
|
||
- Advanced feature - most users should use `InteractionGroups` instead
|
||
|
||
**`CollisionEvent`** - Collision state changes
|
||
- `Started(h1, h2, flags)` - Colliders began touching
|
||
- `Stopped(h1, h2, flags)` - Colliders stopped touching
|
||
- Methods: `started()`, `stopped()`, `collider1()`, `collider2()`, `sensor()`
|
||
|
||
### 4. `src/control/` - High-Level Controllers
|
||
|
||
**`KinematicCharacterController`** - Player/NPC movement
|
||
- Handles walking, slopes, stairs, wall sliding, ground snapping
|
||
- NOT physics-based - you control movement directly
|
||
- Features:
|
||
- `slide`: Slide along walls instead of stopping
|
||
- `autostep`: Automatically climb stairs/small obstacles
|
||
- `max_slope_climb_angle`: Max climbable slope (radians)
|
||
- `min_slope_slide_angle`: When to slide down slopes
|
||
- `snap_to_ground`: Keep grounded on uneven terrain
|
||
- Returns `EffectiveCharacterMovement` with `translation` and `grounded` status
|
||
|
||
**`DynamicRayCastVehicleController`** - Arcade vehicle physics
|
||
- Raycast-based suspension (simpler than constraint-based)
|
||
- Add wheels with suspension, steering, engine force
|
||
- Automatically handles wheel contacts and forces
|
||
|
||
### 5. `src/data/` - Core Data Structures
|
||
|
||
**`Arena<T>`** - Handle-based storage
|
||
- Generational indices: (index, generation) pair
|
||
- Prevents use-after-free: old handles become invalid when slots reused
|
||
- Used for: `RigidBodySet`, `ColliderSet`, `ImpulseJointSet`
|
||
- Methods: `insert()`, `remove()`, `get()`, `get_mut()`, `iter()`
|
||
- Advanced: `get_unknown_gen()` bypasses generation check (unsafe)
|
||
|
||
**`Graph<N, E>`** - Generic graph structure
|
||
- Nodes and edges with associated data
|
||
- Used for: interaction graph (bodies/colliders), joint graph
|
||
- Enables: "find all joints attached to this body"
|
||
|
||
**`ModifiedObjects`** - Change tracking
|
||
- Flags objects that changed since last frame
|
||
- Enables incremental updates (only process changed objects)
|
||
- Critical for performance
|
||
|
||
### 6. `src/counters/` - Profiling
|
||
|
||
**`Counters`** - Performance measurements
|
||
- Tracks time in: collision detection, solver, CCD, island construction
|
||
- Subdivided: broad-phase time, narrow-phase time, velocity resolution, etc.
|
||
- Access via `physics_pipeline.counters`
|
||
|
||
## Complete API Reference
|
||
|
||
### Body Types
|
||
|
||
```rust
|
||
RigidBodyType::Dynamic // Fully simulated
|
||
RigidBodyType::Fixed // Never moves
|
||
RigidBodyType::KinematicVelocityBased // Velocity control
|
||
RigidBodyType::KinematicPositionBased // Position control
|
||
```
|
||
|
||
### Joint Types
|
||
|
||
```rust
|
||
FixedJoint::new() // Weld
|
||
RevoluteJoint::new(axis) // Hinge
|
||
PrismaticJoint::new(axis) // Slider
|
||
SphericalJoint::new() // Ball-and-socket (3D only)
|
||
RopeJoint::new(max_dist) // Distance limit
|
||
SpringJoint::new(rest, stiff, damp) // Elastic
|
||
```
|
||
|
||
### Collision Shapes
|
||
|
||
```rust
|
||
// Primitives (fast)
|
||
ColliderBuilder::ball(radius)
|
||
ColliderBuilder::cuboid(hx, hy, hz) // Half-extents
|
||
ColliderBuilder::capsule_y(half_h, r) // Best for characters!
|
||
ColliderBuilder::cylinder(half_h, r) // 3D only
|
||
ColliderBuilder::cone(half_h, r) // 3D only
|
||
|
||
// Complex (slower)
|
||
ColliderBuilder::trimesh(verts, indices) // Arbitrary mesh
|
||
ColliderBuilder::heightfield(heights, scale) // Terrain
|
||
ColliderBuilder::convex_hull(points) // Convex wrap
|
||
ColliderBuilder::convex_decomposition(v, i) // Auto-split concave
|
||
```
|
||
|
||
### Events & Hooks
|
||
|
||
```rust
|
||
// Event flags
|
||
ActiveEvents::COLLISION_EVENTS // Start/stop touching
|
||
ActiveEvents::CONTACT_FORCE_EVENTS // Force threshold exceeded
|
||
|
||
// Hook flags
|
||
ActiveHooks::FILTER_CONTACT_PAIRS // Custom collision filtering
|
||
ActiveHooks::FILTER_INTERSECTION_PAIR // Custom sensor filtering
|
||
ActiveHooks::MODIFY_SOLVER_CONTACTS // Modify contact properties
|
||
```
|
||
|
||
### Filtering
|
||
|
||
```rust
|
||
// Collision groups (layer system)
|
||
let groups = InteractionGroups::new(
|
||
Group::GROUP_1, // I'm in group 1
|
||
Group::GROUP_2 | Group::GROUP_3 // I collide with 2 and 3
|
||
);
|
||
|
||
// Query filters
|
||
QueryFilter::default()
|
||
QueryFilter::only_dynamic() // Ignore static geometry
|
||
QueryFilter::exclude_sensors() // Only solid shapes
|
||
```
|
||
|
||
### Locked Axes
|
||
|
||
```rust
|
||
LockedAxes::ROTATION_LOCKED // Can't rotate at all
|
||
LockedAxes::TRANSLATION_LOCKED // Can't translate at all
|
||
LockedAxes::TRANSLATION_LOCKED_Z // Lock one axis (2D in 3D)
|
||
LockedAxes::ROTATION_LOCKED_X | LockedAxes::ROTATION_LOCKED_Y // Combine
|
||
```
|
||
|
||
## Advanced Concepts
|
||
|
||
### Sleeping System
|
||
|
||
Bodies automatically sleep when at rest (velocities below threshold for 2 seconds). Sleeping bodies:
|
||
- Skipped in collision detection and simulation
|
||
- Auto-wake when hit or joint-connected to moving body
|
||
- Configured via `RigidBodyActivation`:
|
||
- `normalized_linear_threshold`: Linear velocity threshold (default 0.4)
|
||
- `angular_threshold`: Angular velocity threshold (default 0.5)
|
||
- `time_until_sleep`: How long to be still before sleeping (default 2.0s)
|
||
- Disable with `can_sleep(false)` or `RigidBodyActivation::cannot_sleep()`
|
||
|
||
### CCD (Continuous Collision Detection)
|
||
|
||
Prevents "tunneling" where fast objects pass through thin walls:
|
||
- **Hard CCD**: Shape-casting with substeps (expensive but accurate)
|
||
- **Soft CCD**: Predictive contacts (cheaper, good for medium-speed objects)
|
||
- Enable: `RigidBodyBuilder::ccd_enabled(true)` or `body.enable_ccd(true)`
|
||
- Soft: `set_soft_ccd_prediction(distance)`
|
||
- Active when velocity exceeds auto-computed threshold
|
||
|
||
### Mass Properties
|
||
|
||
Total mass = collider masses + additional mass:
|
||
- Collider mass: `density × volume` or set directly
|
||
- Additional mass: `set_additional_mass()` adds to total
|
||
- Auto-computed: mass, center of mass, angular inertia tensor
|
||
- Manual recompute: `recompute_mass_properties_from_colliders()`
|
||
|
||
### Dominance Groups
|
||
|
||
Bodies with higher dominance push lower ones but not vice versa:
|
||
- Range: `i8::MIN` to `i8::MAX`
|
||
- Default: 0 (all equal)
|
||
- Rarely needed - use for "heavy objects should always win" scenarios
|
||
|
||
### Contact Skin
|
||
|
||
Small margin around colliders (keeps objects slightly apart):
|
||
- Improves performance and stability
|
||
- Might create small visual gaps
|
||
- Set via `ColliderBuilder::contact_skin(thickness)`
|
||
|
||
### Motor Models
|
||
|
||
How motor spring constants scale with mass:
|
||
- **`MotorModel::AccelerationBased`** (default): Auto-scales with mass, easier to tune
|
||
- **`MotorModel::ForceBased`**: Absolute forces, mass-dependent behavior
|
||
|
||
## Common Usage Patterns
|
||
|
||
### Creating a Dynamic Object
|
||
|
||
```rust
|
||
let body = RigidBodyBuilder::dynamic()
|
||
.translation(vector![0.0, 10.0, 0.0])
|
||
.linvel(vector![1.0, 0.0, 0.0])
|
||
.build();
|
||
let body_handle = bodies.insert(body);
|
||
|
||
let collider = ColliderBuilder::ball(0.5)
|
||
.density(2700.0) // Aluminum
|
||
.friction(0.7)
|
||
.restitution(0.3)
|
||
.build();
|
||
colliders.insert_with_parent(collider, body_handle, &mut bodies);
|
||
```
|
||
|
||
### Raycasting
|
||
|
||
```rust
|
||
let query_pipeline = broad_phase.as_query_pipeline(
|
||
&QueryDispatcher,
|
||
&bodies,
|
||
&colliders,
|
||
QueryFilter::default()
|
||
);
|
||
|
||
let ray = Ray::new(point![0.0, 10.0, 0.0], vector![0.0, -1.0, 0.0]);
|
||
if let Some((handle, toi)) = query_pipeline.cast_ray(&ray, Real::MAX, true) {
|
||
let hit_point = ray.origin + ray.dir * toi;
|
||
println!("Hit {:?} at {:?}, distance = {}", handle, hit_point, toi);
|
||
}
|
||
```
|
||
|
||
### Applying Forces vs Impulses
|
||
|
||
```rust
|
||
// IMPULSE: Instant change (jumping, explosions)
|
||
body.apply_impulse(vector![0.0, 500.0, 0.0], true); // Jump!
|
||
|
||
// FORCE: Continuous (thrust, wind) - call every frame
|
||
body.add_force(vector![0.0, 100.0, 0.0], true); // Rocket thrust
|
||
```
|
||
|
||
### Creating a Joint
|
||
|
||
```rust
|
||
let joint = RevoluteJointBuilder::new()
|
||
.local_anchor1(point![1.0, 0.0, 0.0])
|
||
.local_anchor2(point![-1.0, 0.0, 0.0])
|
||
.limits([0.0, std::f32::consts::PI / 2.0]) // 0-90° rotation
|
||
.build();
|
||
let joint_handle = joints.insert(body1, body2, joint, true);
|
||
```
|
||
|
||
### Character Controller
|
||
|
||
```rust
|
||
let controller = KinematicCharacterController {
|
||
slide: true,
|
||
autostep: Some(CharacterAutostep::default()),
|
||
max_slope_climb_angle: 45.0_f32.to_radians(),
|
||
snap_to_ground: Some(CharacterLength::Relative(0.2)),
|
||
..Default::default()
|
||
};
|
||
|
||
let desired_movement = vector![input_x, 0.0, input_z] * speed * dt;
|
||
let movement = controller.move_shape(
|
||
dt, &bodies, &colliders, &query_pipeline,
|
||
character_shape, &character_pos, desired_movement,
|
||
QueryFilter::default(), |_| {}
|
||
);
|
||
character_pos.translation.vector += movement.translation;
|
||
```
|
||
|
||
### Collision Events
|
||
|
||
```rust
|
||
use std::sync::mpsc::channel;
|
||
|
||
let (collision_send, collision_recv) = channel();
|
||
let (force_send, force_recv) = channel();
|
||
let event_handler = ChannelEventCollector::new(collision_send, force_send);
|
||
|
||
// In physics step
|
||
physics_pipeline.step(..., &event_handler);
|
||
|
||
// After physics
|
||
while let Ok(event) = collision_recv.try_recv() {
|
||
match event {
|
||
CollisionEvent::Started(h1, h2, _) => println!("Collision!"),
|
||
CollisionEvent::Stopped(h1, h2, _) => println!("Separated"),
|
||
}
|
||
}
|
||
```
|
||
|
||
## Performance Optimization Tips
|
||
|
||
1. **Sleeping**: Let objects at rest sleep (default behavior)
|
||
2. **Shape choice**: Ball/Cuboid/Capsule >> Convex Hull >> TriMesh
|
||
3. **Solver iterations**: Lower `num_solver_iterations` if accuracy isn't critical
|
||
4. **Parallel**: Enable `parallel` feature for multi-core
|
||
5. **Broadphase**: Keep objects reasonably distributed (not all in one spot)
|
||
6. **CCD**: Only enable for fast objects that need it
|
||
7. **Event generation**: Only enable events on colliders that need them
|
||
8. **Collision groups**: Filter unnecessary collision checks
|
||
9. **Fixed timestep**: Use fixed `dt`, accumulate remainder for smooth rendering
|
||
|
||
## Common Patterns & Best Practices
|
||
|
||
### Handle Storage
|
||
```rust
|
||
// Store handles, not references
|
||
struct Player {
|
||
body_handle: RigidBodyHandle,
|
||
collider_handle: ColliderHandle,
|
||
}
|
||
|
||
// Access when needed
|
||
let player_body = &mut bodies[player.body_handle];
|
||
```
|
||
|
||
### 2D Game in 3D Engine
|
||
```rust
|
||
let body = RigidBodyBuilder::dynamic()
|
||
.locked_axes(
|
||
LockedAxes::TRANSLATION_LOCKED_Z |
|
||
LockedAxes::ROTATION_LOCKED_X |
|
||
LockedAxes::ROTATION_LOCKED_Y
|
||
)
|
||
.build();
|
||
```
|
||
|
||
### One-Way Platforms (via hooks)
|
||
```rust
|
||
struct OneWayPlatform;
|
||
impl PhysicsHooks for OneWayPlatform {
|
||
fn filter_contact_pair(&self, context: &PairFilterContext) -> Option<SolverFlags> {
|
||
// Allow contact only if player is above platform
|
||
if player_above_platform(context) {
|
||
Some(SolverFlags::COMPUTE_IMPULSES)
|
||
} else {
|
||
None // No collision
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Compound Shapes
|
||
```rust
|
||
// Multiple colliders on one body
|
||
let body_handle = bodies.insert(RigidBodyBuilder::dynamic().build());
|
||
|
||
colliders.insert_with_parent(
|
||
ColliderBuilder::cuboid(1.0, 1.0, 1.0).translation(vector![0.0, 1.0, 0.0]).build(),
|
||
body_handle, &mut bodies
|
||
);
|
||
colliders.insert_with_parent(
|
||
ColliderBuilder::ball(0.5).translation(vector![0.0, 3.0, 0.0]).build(),
|
||
body_handle, &mut bodies
|
||
);
|
||
// Now the body has a box + ball shape
|
||
```
|
||
|
||
## Troubleshooting
|
||
|
||
### Objects Tunneling Through Walls
|
||
- Enable CCD: `body.enable_ccd(true)`
|
||
- Increase wall thickness
|
||
- Reduce timestep (`dt`)
|
||
- Increase `num_solver_iterations`
|
||
|
||
### Unstable Simulation (Jittering, Explosions)
|
||
- Reduce mass ratios (avoid 1kg vs 1000kg objects)
|
||
- Increase `num_solver_iterations`
|
||
- Check for conflicting constraints
|
||
- Verify joint anchors are reasonable
|
||
- Reduce timestep if using large `dt`
|
||
|
||
### Poor Performance
|
||
- Check sleeping is enabled (`can_sleep(true)`)
|
||
- Use simpler shapes (capsules instead of meshes)
|
||
- Enable `parallel` feature
|
||
- Reduce `num_solver_iterations` if acceptable
|
||
- Use collision groups to avoid unnecessary checks
|
||
- Only enable events on colliders that need them
|
||
|
||
### Bodies Stuck/Not Moving
|
||
- Check if sleeping: `body.wake_up(true)`
|
||
- Verify mass > 0 (check collider density)
|
||
- Check locked axes aren't preventing movement
|
||
- Verify gravity scale isn't 0
|
||
|
||
## File Statistics
|
||
|
||
- **95 total Rust files** in `src/`
|
||
- **Top files by public function count:**
|
||
- `rigid_body.rs`: 126 functions
|
||
- `collider.rs`: 118 functions
|
||
- `rigid_body_components.rs`: 56 functions
|
||
- `generic_joint.rs`: 47 functions
|
||
- `query_pipeline.rs`: 29 functions
|
||
|
||
## Documentation Improvements
|
||
|
||
### Session 1: Comprehensive API Documentation
|
||
Comprehensively documented **300+ public functions** across **45+ files**:
|
||
|
||
**Fully Documented Modules:**
|
||
1. **PhysicsPipeline** - Main simulation loop
|
||
2. **RigidBody** (~60 methods) - All position, velocity, force, impulse, damping, CCD, locking methods
|
||
3. **RigidBodySet** - All collection management methods
|
||
4. **RigidBodyBuilder** (~40 methods) - All configuration methods
|
||
5. **Collider** (~50 methods) - All property accessors and setters
|
||
6. **ColliderSet** - All collection methods
|
||
7. **ColliderBuilder** (~60 methods) - All shape constructors and configuration
|
||
8. **All 6 joint types** - Comprehensive docs for Fixed, Revolute, Prismatic, Spherical, Rope, Spring
|
||
9. **ImpulseJointSet** - All joint collection methods
|
||
10. **QueryPipeline** - All spatial query methods
|
||
11. **EventHandler & events** - Complete event system
|
||
12. **InteractionGroups** - Collision filtering
|
||
13. **IntegrationParameters** - Simulation settings
|
||
14. **IslandManager** - Sleep/wake system
|
||
15. **CCDSolver** - Tunneling prevention
|
||
16. **BroadPhaseBvh, NarrowPhase** - Collision detection
|
||
17. **CharacterController** - Player movement
|
||
18. **ContactPair** - Contact information
|
||
19. **All major enums/flags**: RigidBodyType, LockedAxes, ActiveEvents, ActiveHooks, ActiveCollisionTypes, CoefficientCombineRule, MotorModel, CollisionEvent, QueryFilter
|
||
|
||
**Documentation Style:**
|
||
All functions include:
|
||
- **Plain language** ("hitbox" not "geometric entity")
|
||
- **Real-world use cases** (when/why to use)
|
||
- **Code examples** (copy-paste ready)
|
||
- **Value guides** (friction 0-1, density values for real materials)
|
||
- **Warnings** (teleporting, performance costs, common mistakes)
|
||
- **Comparisons** (forces vs impulses, mass vs density, when to use each)
|
||
|
||
### Session 2: Documentation Example Testing
|
||
**Converted 75+ ignored documentation examples to be tested by `cargo test --doc`**
|
||
|
||
**Goal:** Ensure all documentation examples remain valid and compilable as the codebase evolves.
|
||
|
||
**Files with Fixed Examples:**
|
||
|
||
*Dynamics Module (33 examples):*
|
||
- `dynamics/rigid_body.rs` (13)
|
||
- `dynamics/rigid_body_set.rs` (8)
|
||
- `dynamics/rigid_body_components.rs` (1) - LockedAxes
|
||
- `dynamics/coefficient_combine_rule.rs` (1)
|
||
- `dynamics/integration_parameters.rs` (1)
|
||
- `dynamics/island_manager.rs` (1)
|
||
- `dynamics/joint/rope_joint.rs` (1)
|
||
- `dynamics/joint/revolute_joint.rs` (1)
|
||
- `dynamics/joint/generic_joint.rs` (1) - JointMotor
|
||
- `dynamics/joint/impulse_joint/impulse_joint_set.rs` (5)
|
||
|
||
*Geometry Module (10 examples):*
|
||
- `geometry/interaction_groups.rs` (1)
|
||
- `geometry/collider_set.rs` (4)
|
||
- `geometry/collider_components.rs` (1) - ActiveCollisionTypes
|
||
- `geometry/contact_pair.rs` (2)
|
||
- `geometry/mod.rs` (1) - CollisionEvent
|
||
- `geometry/interaction_graph.rs` (1)
|
||
|
||
*Pipeline Module (14 examples):*
|
||
- `pipeline/query_pipeline.rs` (9) - Raycasting, shape casting, point queries
|
||
- `pipeline/event_handler.rs` (3) - ActiveEvents, EventHandler trait, ChannelEventCollector
|
||
- `pipeline/physics_pipeline.rs` (1)
|
||
- `pipeline/collision_pipeline.rs` (1)
|
||
|
||
*Control Module (1 example):*
|
||
- `control/character_controller.rs` (1) - Complete character controller setup
|
||
|
||
*Data Module (25 examples):*
|
||
- `data/arena.rs` (25) - All Arena API methods
|
||
|
||
*Other Modules (4 examples):*
|
||
- `dynamics/joint/multibody_joint/multibody_joint_set.rs` (1)
|
||
|
||
**Conversion Pattern:**
|
||
```rust
|
||
// Before:
|
||
/// ```ignore
|
||
/// let body = RigidBodyBuilder::dynamic().build();
|
||
/// bodies.insert(body);
|
||
/// ```
|
||
|
||
// After:
|
||
/// ```
|
||
/// # use rapier3d::prelude::*;
|
||
/// # let mut bodies = RigidBodySet::new();
|
||
/// let body_handle = bodies.insert(RigidBodyBuilder::dynamic());
|
||
/// ```
|
||
```
|
||
|
||
Hidden lines (prefixed with `#`) provide setup code while keeping examples readable.
|
||
|
||
**Key Fixes Required for Compilation:**
|
||
|
||
1. **Removed unnecessary `.build()` calls**: Builders implement `Into<T>`, so:
|
||
- `RigidBodyBuilder::dynamic().build()` → `RigidBodyBuilder::dynamic()`
|
||
- `ColliderBuilder::ball(0.5).build()` → `ColliderBuilder::ball(0.5)`
|
||
- These work directly with `insert()` and `insert_with_parent()`
|
||
|
||
2. **Fixed API calls to match actual implementation:**
|
||
- `&QueryDispatcher` → `narrow_phase.query_dispatcher()` (QueryPipeline needs a dispatcher reference)
|
||
- Added `NarrowPhase::new()` setup for query pipeline examples
|
||
|
||
3. **Corrected property/field names:**
|
||
- `hit.toi` → `hit.time_of_impact` (RayIntersection struct)
|
||
- `collider.shape()` → `collider.shared_shape()` (when printing/debugging)
|
||
|
||
4. **Added required setup for complex examples:**
|
||
- `project_point()` example: Added `IntegrationParameters`, `broad_phase.set_aabb()` call
|
||
- Character controller: Changed to `Ball::new(0.5)` instead of shape reference
|
||
- Joint examples: Fixed to use `Vector::y_axis()` instead of implicit axis
|
||
|
||
5. **Fixed joint constructor calls:**
|
||
- `RevoluteJoint::new()` → `RevoluteJoint::new(Vector::y_axis())` (axis required)
|
||
- `PrismaticJoint::new(...)` → `PrismaticJoint::new(Vector::x_axis())` (axis required)
|
||
|
||
**Remaining Work:**
|
||
- `geometry/collider.rs` has 12 ignored examples still marked as `ignore` (these are intentionally left as `ignore` for documentation purposes where full compilation context would be overly verbose)
|
||
|
||
**Impact:**
|
||
- ✅ Documentation examples now compile with `cargo test --doc`
|
||
- ✅ Examples stay correct as codebase evolves (tests will catch API changes)
|
||
- ✅ Copy-paste ready code that actually works
|
||
- ✅ Improved documentation quality and developer experience
|
||
- ✅ Builders work seamlessly without explicit `.build()` calls
|
||
|
||
## Examples Directory
|
||
|
||
`examples3d/` contains many demonstrations:
|
||
|
||
- `primitives3.rs` - Showcase of basic shapes
|
||
- `keva3.rs` - Large tower of blocks (stress test)
|
||
- `platform3.rs` - Moving kinematic platforms
|
||
- `joints3.rs` - All joint types demonstrated
|
||
- `character_controller3.rs` - Character movement
|
||
- `vehicle_controller3.rs` - Vehicle physics
|
||
- `ccd3.rs` - Fast bullets with CCD
|
||
- `sensor3.rs` - Trigger zones
|
||
- `despawn3.rs` - Removing objects
|
||
- `debug_boxes3.rs` - Visual debugging
|
||
- `rotating_floor_stacks3.rs` - **Custom example**: 20 pyramids (10×10 cube bases) on slowly rotating floor
|
||
|
||
**Run**: `cargo run --release --bin all_examples3`
|
||
|
||
## Building & Testing
|
||
|
||
```bash
|
||
# Development build
|
||
cargo build
|
||
|
||
# Release build (much faster!)
|
||
cargo build --release
|
||
|
||
# Run all 3D examples
|
||
cargo run --release --bin all_examples3
|
||
|
||
# Run all 2D examples
|
||
cargo run --release --bin all_examples2
|
||
|
||
# Run tests
|
||
cargo test
|
||
|
||
# With parallelism
|
||
cargo build --features parallel --release
|
||
|
||
# With SIMD
|
||
cargo build --features simd-stable --release
|
||
|
||
# Benchmarks
|
||
cargo run --release --manifest-path benchmarks3d/Cargo.toml
|
||
```
|
||
|
||
## Cargo Features
|
||
|
||
- `parallel` - Multi-threaded solving (big performance gain on multi-core)
|
||
- `simd-stable` - SIMD optimizations on stable Rust
|
||
- `simd-nightly` - More SIMD opts on nightly
|
||
- `serde-serialize` - Snapshot/restore support
|
||
- `enhanced-determinism` - Stricter determinism (disables SIMD)
|
||
- `debug-render` - Visual debugging helpers
|
||
- `profiler` - Detailed performance counters
|
||
- `dim2` / `dim3` - 2D or 3D (set by crate, not user)
|
||
- `f32` / `f64` - Precision (set by crate, not user)
|
||
|
||
## Resources
|
||
|
||
- **Official Site**: https://rapier.rs
|
||
- **User Guide**: https://rapier.rs/docs/
|
||
- **API Reference**: https://docs.rs/rapier3d
|
||
- **Discord**: https://discord.gg/vt9DJSW
|
||
- **GitHub**: https://github.com/dimforge/rapier
|
||
- **Blog**: https://www.dimforge.com/blog
|
||
- **Crates.io**: https://crates.io/crates/rapier3d
|
||
- **NPM** (JS/WASM): Available for web development
|
||
|
||
## Related Dimforge Projects
|
||
|
||
- **Parry**: Collision detection library (Rapier's foundation)
|
||
- **Salva**: SPH fluid simulation
|
||
- **nphysics**: Previous-gen physics engine (deprecated, use Rapier)
|
||
- **nalgebra**: Linear algebra library
|
||
- **Bevy_rapier**: Integration with Bevy game engine
|
||
|
||
## Quick Reference Card
|
||
|
||
### Most Common Operations
|
||
|
||
```rust
|
||
// Create world
|
||
let mut bodies = RigidBodySet::new();
|
||
let mut colliders = ColliderSet::new();
|
||
let mut joints = ImpulseJointSet::new();
|
||
let mut pipeline = PhysicsPipeline::new();
|
||
|
||
// Add dynamic ball
|
||
let body = bodies.insert(RigidBodyBuilder::dynamic().translation(vector![0.0, 5.0, 0.0]).build());
|
||
colliders.insert_with_parent(ColliderBuilder::ball(0.5).build(), body, &mut bodies);
|
||
|
||
// Add static floor
|
||
let floor = bodies.insert(RigidBodyBuilder::fixed().build());
|
||
colliders.insert_with_parent(ColliderBuilder::cuboid(10.0, 0.1, 10.0).build(), floor, &mut bodies);
|
||
|
||
// Simulate
|
||
pipeline.step(&gravity, ¶ms, &mut islands, &mut broad_phase, &mut narrow_phase,
|
||
&mut bodies, &mut colliders, &mut joints, &mut multibody_joints,
|
||
&mut ccd_solver, &(), &());
|
||
|
||
// Query
|
||
let pos = bodies[body].translation();
|
||
let vel = bodies[body].linvel();
|
||
|
||
// Modify
|
||
bodies[body].apply_impulse(vector![0.0, 100.0, 0.0], true);
|
||
bodies[body].set_linvel(vector![1.0, 0.0, 0.0], true);
|
||
```
|
||
|
||
### Material Presets
|
||
|
||
```rust
|
||
// Ice
|
||
.friction(0.01).restitution(0.1)
|
||
|
||
// Wood
|
||
.friction(0.5).restitution(0.2)
|
||
|
||
// Rubber
|
||
.friction(1.0).restitution(0.8)
|
||
|
||
// Metal
|
||
.friction(0.6).restitution(0.3)
|
||
|
||
// Bouncy ball
|
||
.friction(0.7).restitution(0.9)
|
||
```
|
||
|
||
### Common Densities (kg/m³)
|
||
|
||
```rust
|
||
.density(1000.0) // Water
|
||
.density(2700.0) // Aluminum
|
||
.density(7850.0) // Steel
|
||
.density(11340.0) // Lead
|
||
.density(920.0) // Ice
|
||
.density(1.2) // Air
|
||
```
|
||
|
||
This documentation provides complete coverage of Rapier's architecture, APIs, usage patterns, and best practices for both beginners and advanced users!
|