Vampire-Act-Base/docs/architecture/adr-003.md

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