collide 0.7.0

Simple extensible collision management
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

# Collide

[![crates.io](https://img.shields.io/crates/v/collide)](https://crates.io/crates/collide)
[![docs.rs](https://img.shields.io/docsrs/collide)](https://docs.rs/collide)

A dimension-generic collision detection ecosystem for Rust. All traits and types work in any dimension (2D, 3D, N-D) and with any numeric type (f32, f64, etc.).

## Crates

| Crate | Description |
|---|---|
| [`collide`](https://crates.io/crates/collide) | Core traits: `Collider`, `BoundingVolume`, `Bounded`, `Transformable`, `SpatialPartition` |
| [`collide-sphere`](https://crates.io/crates/collide-sphere) | Sphere collider (center + radius). Simplest and most efficient collider type |
| [`collide-capsule`](https://crates.io/crates/collide-capsule) | Capsule collider (two endpoints + radius). Also represents spheres, lines, points |
| [`collide-convex`](https://crates.io/crates/collide-convex) | Convex hull collider (N points + radius). GJK/EPA algorithm. Handles arbitrary convex shapes |
| [`collide-ray`](https://crates.io/crates/collide-ray) | Ray type (origin + direction). Shape crates implement `Collider<Ray>` via feature flags |
| [`collision-detection`](https://crates.io/crates/collision-detection) | Collision manager with brute force, spatial partitioning, and BVH algorithms |

## Core Traits

### Collider

The fundamental trait. Implement `collision_info` to define how two shapes collide. Override `check_collision` with a cheap pre-check (bounding sphere, AABB) to skip expensive narrow-phase tests.

```rust
use collide::{Collider, CollisionInfo};

impl Collider for MyShape {
    type Vector = Vec3;

    fn check_collision(&self, other: &Self) -> bool {
        // Optional: cheap broad-phase check
        self.bounding_sphere_overlaps(other)
    }

    fn collision_info(&self, other: &Self) -> Option<CollisionInfo<Vec3>> {
        // Precise narrow-phase collision detection
    }
}
```

### BoundingVolume + Bounded

For BVH-based collision detection. `BoundingVolume` defines overlap testing and merging. `Bounded<B>` is generic over the volume type, so a collider can provide multiple bounding representations.

```rust
use collide::{BoundingVolume, Bounded};

impl BoundingVolume for MySphere {
    fn overlaps(&self, other: &Self) -> bool { /* distance check */ }
    fn merged(&self, other: &Self) -> Self { /* enclosing sphere */ }
}

impl Bounded<MySphere> for MyConvex {
    fn bounding_volume(&self) -> MySphere { /* compute enclosing sphere */ }
}
```

### Wrapper Types

**`BoundedCollider<B, C>`** wraps a collider with a bounding volume for automatic pre-checks. Nestable for cascading broad-to-narrow checks.

**`Transformed<C, T>`** wraps a collider with a transform. Requires `Transformable<T>` on the shape and `Transform<V>` (from `vector-space`) on the transform type.

### SpatialPartition

Maps colliders to spatial cells for hash-based acceleration. Used by `collision-detection` for O(n×k) algorithms.

## Shape Hierarchy

```
Sphere          center + radius              Copy, cheapest
Capsule         two endpoints + radius       Copy, handles elongated shapes
Convex          N points + radius            Clone, arbitrary convex hulls (GJK/EPA)
```

Each shape crate can enable ray support via feature flag `ray`, which implements `Collider<Ray>`.

## Design Goals

1. **Dimension-generic**: No feature may introduce dimension-specific or type-specific assumptions. This is the core principle.
2. **Interoperability**: Share colliders across physics engines via the `Collider` trait.
3. **Extensibility**: New collider types without breaking existing implementations.

This project is designed for use with AI coding assistants. The API surface is small and consistent: a single generic `Collider` trait with two methods, composable wrapper types (`BoundedCollider`, `Transformed`), and uniform feature flags across shape crates. All public types implement standard traits (`Clone`, `Debug`) and use `CollisionInfo<V>` as the universal result type.