gemath 0.1.0

Type-safe game math with type-level units/spaces, typed angles, and explicit fallible ops (plus optional geometry/collision).
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

# Feature flags & minimal builds

`gemath` is intentionally **modular**: you can build “just vectors”, “just collision”, or “just scalar helpers” without pulling in the rest of the crate.

## Default feature set

By default:

- `default = ["std", "full"]`
- You get `std` + most modules enabled.

If you want a minimal footprint, disable defaults and opt in to exactly what you need.

## Platform/runtime features

- **`std`** *(default)*:
  - Builds with the Rust standard library.
  - Enables the internal `math` capability (float math backend wrappers).
- **`libm`**:
  - For `no_std` builds that still need float math (sin/cos/sqrt/etc).
  - Enables the internal `math` capability via the `libm` crate.
- **`alloc`**:
  - For `no_std` targets that provide an allocator and want allocation-backed APIs.
  - Only meaningful when `std` is disabled.

## The internal “capability” feature

- **`math`**:
  - Internal capability used by `std` and `libm`.
  - It exists to keep “float math backend selection” explicit and feature-gated.

## Module features (high-signal overview)

### Core safety posture

- **`angle`**: typed angles (`Degrees`, `Radians`)
- **`unit_vec`**: unit-vector wrappers (`UnitVec2/3/4`) that enforce normalization invariants

### Linear algebra

- **`vec2`**, **`vec3`**, **`vec4`**
- **`mat2`**, **`mat3`**, **`mat4`**
- **`quat`**

### Geometry & collision

- **`geometry`**: primitives (rays/segments/circle/sphere/plane/capsules/OBBs)
- **`collision`**: intersection helpers and raycasts (with structured hit results for representative APIs)

### Allocation-backed modules

These require `std` *or* `alloc`:

- **`polygon2`**: `Polygon2` backed by `Vec<Vec2>`
- **`spatial`**: broadphase prototypes (uniform grid / quadtree / BVH)

## Bundle features

- **`full`**:
  - Enables most module features (including `geometry`, `collision`, `spatial`, and `polygon2`).
  - Does *not* automatically enable optional interop (`serde`, `mint`).

## Optional integrations

- **`serde`**: enables `serde` derives for many core types (proc macros by design)
- **`mint`**: enables `mint` conversions for interop with other math crates

## Minimal feature sets (common use cases)

All examples below are for depending on `gemath` from another crate.

### Minimal `no_std` math helpers (no vectors)

```toml
[dependencies]
gemath = { version = "0.1", default-features = false, features = ["libm", "scalar"] }
```

### Minimal `Vec2` (`no_std`)

```toml
[dependencies]
gemath = { version = "0.1", default-features = false, features = ["libm", "vec2"] }
```

### Geometry primitives (`no_std`)

```toml
[dependencies]
gemath = { version = "0.1", default-features = false, features = ["libm", "geometry"] }
```

### Collision helpers (`no_std`)

```toml
[dependencies]
gemath = { version = "0.1", default-features = false, features = ["libm", "collision"] }
```

### Allocation-backed spatial structures (`no_std + alloc`)

```toml
[dependencies]
gemath = { version = "0.1", default-features = false, features = ["libm", "alloc", "spatial"] }
```

## Gotchas

- **`no_std` without `libm`**: if you disable `std` and enable modules that need float math, you must enable `libm`.
- **Allocation-backed modules**: `polygon2` and `spatial` require `std` or `alloc`.