collision-detection 0.7.0

A generic collision detection library based on the `collide` crate
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
111

# Collision Detection

[![crates.io](https://img.shields.io/crates/v/collision-detection)](https://crates.io/crates/collision-detection)
[![docs.rs](https://img.shields.io/docsrs/collision-detection)](https://docs.rs/collision-detection)
[![pages](https://img.shields.io/badge/docs-GitLab%20Pages-blue)](https://porky11.gitlab.io/collision-detection)

A generic collision manager built on the [collide](https://crates.io/crates/collide) ecosystem. Manages collections of colliders with stable indices and provides multiple collision detection algorithms from O(n²) brute force to O(n log n) BVH.

Works in any dimension (2D, 3D, N-D) with any numeric type.

## Quick Start

```rust
use collision_detection::CollisionManager;
use collide_sphere::Sphere;

// Create a manager for sphere colliders, indexed by u32 IDs
let mut manager = CollisionManager::<Sphere<Vec3>, u32>::new();

// Insert colliders with associated object IDs
let player_idx = manager.insert_collider(Sphere::new(player_pos, 0.5), PLAYER_ID);
let enemy_idx = manager.insert_collider(Sphere::new(enemy_pos, 0.5), ENEMY_ID);

// Update positions by replacing colliders
manager.replace_collider(player_idx, Sphere::new(new_player_pos, 0.5));

// Compute all collisions
let collisions = manager.compute_inner_collisions();
for (collider_idx, hits) in &collisions {
    for hit in hits {
        println!("Object {} hit object {}", collider_idx, hit.index);
        let push_vector = hit.info.vector; // displacement to resolve collision
    }
}
```

## Layers

There is no built-in layer/mask system. Instead, use **separate `CollisionManager` instances** as layers.

```rust
// Static level geometry — never collides with itself
let mut static_layer = CollisionManager::<Sphere<Vec3>, u32>::new();
static_layer.insert_collider(wall_sphere, WALL_ID);
static_layer.insert_collider(floor_sphere, FLOOR_ID);

// Dynamic objects — need mutual collision
let mut dynamic_layer = CollisionManager::<Sphere<Vec3>, u32>::new();
dynamic_layer.insert_collider(player_sphere, PLAYER_ID);
dynamic_layer.insert_collider(enemy_sphere, ENEMY_ID);

// Dynamic vs dynamic
let dynamic_collisions = dynamic_layer.compute_inner_collisions();

// Dynamic vs static — no compute_inner_collisions on static layer
let static_collisions = dynamic_layer.compute_collisions_with(&static_layer);
```

Each layer uses one collider type for maximum efficiency. For mixed shapes, use an enum:

```rust
enum Shape { Sphere(Sphere<Vec3>), Capsule(Capsule<Vec3>) }
impl Collider for Shape { /* dispatch to inner type */ }
```

## Collision Algorithms

Every manager supports three algorithm variants. Pick the one that matches your trait bounds and performance needs:

| Method | Complexity | Required Traits |
|---|---|---|
| `compute_inner_collisions()` | O(n²) | `Collider` |
| `compute_inner_collisions_spatial()` | O(n×k) | `Collider + SpatialPartition` |
| `compute_inner_collisions_bvh::<V>()` | O(n log n) | `Collider + Bounded<V>` |

Same for `compute_collisions_with` / `_spatial` / `_bvh`.

### Brute Force

Tests all pairs. No additional traits needed. Use for small scenes (<100 objects) or as a baseline.

### Spatial Partitioning

Groups colliders into cells via `SpatialPartition`. Only tests pairs sharing a cell. Best for uniformly distributed objects of similar size.

### BVH

Builds a bounding volume hierarchy via `Bounded<V>`. The type parameter `V` selects which bounding volume to use (e.g. `Sphere` for bounding spheres). Best for scenes with objects of varying sizes.

## Broad-Phase Pre-Check

All algorithms call `Collider::check_collision` before the more expensive `Collider::collision_info`. Override `check_collision` on your collider with a cheap test (bounding sphere, AABB) to skip unnecessary narrow-phase GJK/EPA calls.

## The Collide Ecosystem

| Crate | Description |
|---|---|
| [`collide`](https://crates.io/crates/collide) | Core traits (`Collider`, `Bounded`, `Transformable`, `SpatialPartition`) |
| [`collide-sphere`](https://crates.io/crates/collide-sphere) | Sphere collider — simplest and fastest |
| [`collide-capsule`](https://crates.io/crates/collide-capsule) | Capsule collider — good for elongated shapes |
| [`collide-convex`](https://crates.io/crates/collide-convex) | Convex hull collider — arbitrary shapes via GJK/EPA |
| [`collide-ray`](https://crates.io/crates/collide-ray) | Ray type for intersection queries |
| [`collision-detection`](https://crates.io/crates/collision-detection) | This crate — collision manager |

## Performance

- O(1) insert/remove by index
- O(n²) brute force, O(n×k) spatial partitioning, O(n log n) BVH
- Zero heap allocations after initial setup

This project is designed for use with AI coding assistants. Consistent API across all algorithm variants (same return type, same collision info structure), composable wrapper types (`BoundedCollider`, `Transformed`), and uniform naming conventions (`compute_inner_collisions` / `_spatial` / `_bvh`).