# gemath
`gemath` is a math crate for game/engine code that cares about **making invalid math hard to write**.
Instead of “just vectors and matrices”, `gemath` leans into **type-level correctness**:
- **Type-level units** (e.g. `Meters`, `Pixels`) and **type-level coordinate spaces** (e.g. `World`, `Local`, `Screen`) are carried by core types: `Vec*<Unit, Space>`, `Mat*<Unit, Space>`, `Quat<Unit, Space>`, and friends.
- **Typed angles** (`Radians` / `Degrees`) are the default posture: rotation APIs take angle types, not “mystery `f32`”.
- **Fallible operations are explicit**: “can this fail?” shows up in the type (`Option`) and in naming (`try_*`, `checked_*`), with a crate-wide policy.
If you like `glam`’s ergonomics but want the compiler to help you keep your spaces/units/angles straight, `gemath` is built for that.
## The killer feature: Unit + Space tags that don’t get in your way
Use `()`/`()` when you don’t care — or opt into safety by tagging your math:
```rust
use gemath::{Meters, Pixels, Screen, Vec2, World};
let p_world: Vec2<Meters, World> = Vec2::new(10.0, 20.0);
let p_screen: Vec2<Pixels, Screen> = Vec2::new(640.0, 360.0);
// let _oops = p_world + p_screen;
// ^ does not compile: different Unit and Space tags
```
## Typed angles (Degrees/Radians) by default
```rust
use gemath::{Degrees, Vec2};
let v: Vec2<(), ()> = Vec2::new(1.0, 0.0);
let v90 = v.rotate_deg(Degrees(90.0));
assert!((v90 - Vec2::new(0.0, 1.0)).length() < 1e-5);
```
## Geometry + collision helpers with structured “hit” results
```rust
use gemath::{ray2_circle_cast, Circle, Ray2, Vec2};
let circle: Circle<(), ()> = Circle::new(Vec2::new(0.0, 0.0), 1.0);
let ray: Ray2<(), ()> = Ray2::new(Vec2::new(-2.0, 0.0), Vec2::new(1.0, 0.0));
let hit = ray2_circle_cast(ray, circle).unwrap();
assert!((hit.t - 1.0).abs() < 1e-6);
assert!((hit.point - Vec2::new(-1.0, 0.0)).length() < 1e-6);
assert!((hit.normal - Vec2::new(-1.0, 0.0)).length() < 1e-6);
```
## Docs for contributors (start here)
The developer docs live in `docs/`:
- **Docs index**: `docs/README.md`
- **Feature flags / minimal builds**: `docs/FEATURES.md`
- **Build + test matrix**: `docs/DEVELOPMENT.md`
- **Copy/paste cookbook**: `docs/COOKBOOK.md`
- **API conventions**: `docs/API_CONVENTIONS.md`
- **Design notes (fallible ops, scalar policy, spatial prototypes)**: `docs/`
## `no_std` posture (real, tested)
`gemath` is designed so you can keep the “core math” tiny:
```bash
# minimal no_std build (no allocation)
cargo build --no-default-features --features libm
```
For the full supported/tested matrix (including `alloc`, `geometry`, `collision`, `spatial`, `serde`, `mint`), see `docs/DEVELOPMENT.md`.