# ADR-003: Pure C# Geometry & Math Library

**Status**: Accepted
**Date**: 2026-04-27
**Engine**: Unity 2022.3.62f3c1
**GDD Requirements Addressed**: Combat Logic (hit detection), Form Switch SM (attack style shapes), Enemy AI (distance/range checks)

---

## Context

L0 must not reference `UnityEngine`, but Combat Logic requires geometric intersection tests (circle vs rect vs sector), Form Switch SM needs distance calculations, and all systems need basic math utilities. A self-contained geometry/math library is required.

## Decision

**Build a minimal geometry library implementing only what Nightborn's combat systems actually need.**

### Type Inventory

| Type | Fields | Methods | Consumer |
|------|--------|---------|----------|
| `Vector3` | `float X, Y, Z` | `Distance(Vector3)`, `Normalize()`, `Length`, `Dot`, `Cross`, `+`, `-`, `*` | All modules |
| `Circle` | `Vector3 Center`, `float Radius` | `Intersects(Circle)`, `Intersects(Rect)`, `Contains(Vector3)` | Combat (Mist form AOE) |
| `Rect` | `Vector3 Center`, `float Width`, `float Height`, `float Rotation` | `Intersects(Circle)`, `Intersects(Rect)`, `Contains(Vector3)` | Combat (Wolf form dash) |
| `Sector` | `Vector3 Origin`, `float Radius`, `float Angle`, `float Direction` | `Intersects(Circle)`, `Contains(Vector3)` | Combat (Human form parry fan) |
| `MathUtil` | — | `Clamp`, `Lerp`, `InverseLerp`, `Remap`, `Approximately` | All modules |

### Explicitly Out of Scope

- Full 3D geometry library — Nightborn is top-down/isometric, needs XZ plane only
- Matrix operations — use `System.Numerics.Matrix4x4` (.NET Standard 2.1 built-in)
- Physics collision engine — only static intersection tests between geometric shapes

### Why Not System.Numerics.Vector3

`System.Numerics.Vector3` is available but its field names and method surface overlap with Unity's Vector3. Self-building avoids confusion for external developers juggling two Vector3 types. If SIMD performance becomes needed later, switching to System.Numerics is a drop-in replacement.

## Consequences

- Combat hit detection is fully self-contained and testable without Unity
- Geometric types precisely match game needs (Sector directly addresses Human form's parry shape detection)
- Tradeoff: maintaining a micro math library (~500 lines maximum)
- If complex physics is needed later, re-evaluate against third-party libraries