|
1 | 1 | # FixedMathSharp agent instructions |
2 | 2 |
|
3 | 3 | ## Project intent and architecture |
| 4 | + |
4 | 5 | - This repository is a deterministic fixed-point math library centered on `Fixed64` (`src/FixedMathSharp/Numerics/Fixed64.cs`) with Q32.32 representation (`SHIFT_AMOUNT_I = 32` in `src/FixedMathSharp/Core/FixedMath.cs`). |
5 | 6 | - Most API surface lives in value-type numerics (`Fixed64`, `Vector2d`, `Vector3d`, `FixedQuaternion`, `Fixed3x3`, `Fixed4x4`) plus bounds types (`BoundingBox`, `BoundingSphere`, `BoundingArea`) implementing `IBound`. |
6 | 7 | - Keep operations deterministic and allocation-light; many methods use `m_rawValue` and `[MethodImpl(MethodImplOptions.AggressiveInlining)]` for hot paths. |
7 | 8 | - `FixedMath` and `FixedTrigonometry` are the shared algorithm backbones; extension classes in `src/FixedMathSharp/Numerics/Extensions/` are thin forwarding wrappers, not alternate implementations. |
8 | 9 |
|
9 | 10 | ## Build and test workflows |
| 11 | + |
10 | 12 | - Solution: `FixedMathSharp.sln` with library project and test project. |
11 | 13 | - Target frameworks are configured in the respective `.csproj` files; `net8.0` is the primary TFM. |
12 | 14 | - Typical local workflow: |
|
19 | 21 | - Packaging/versioning comes from `src/FixedMathSharp/FixedMathSharp.csproj`: GitVersion variables are consumed when present, otherwise version falls back to `0.0.0`. |
20 | 22 |
|
21 | 23 | ## Code conventions specific to this repo |
| 24 | + |
22 | 25 | - Prefer `Fixed64` constants (`Fixed64.Zero`, `Fixed64.One`, `FixedMath.PI`) over primitive literals in math-heavy code. |
23 | 26 | - Preserve saturating/guarded semantics in operators and math helpers (for example `Fixed64` add/sub overflow behavior). |
24 | 27 | - When touching bounds logic, maintain cross-type dispatch shape in `Intersects(IBound)` and shared clamping projection via `IBoundExtensions.ProjectPointWithinBounds`. |
|
28 | 31 | - `ThreadLocalRandom` is marked `[Obsolete]`; new deterministic RNG work should prefer `DeterministicRandom` and `DeterministicRandom.FromWorldFeature(...)` in `src/FixedMathSharp/Utility/DeterministicRandom.cs`. |
29 | 32 |
|
30 | 33 | ## Testing patterns to mirror |
| 34 | + |
31 | 35 | - Tests are xUnit (`tests/FixedMathSharp.Tests`). Keep one feature area per test file (e.g., `Vector3d.Tests.cs`, `Bounds/BoundingBox.Tests.cs`). |
32 | 36 | - Use helper assertions from `tests/FixedMathSharp.Tests/Support/FixedMathTestHelper.cs` for tolerance/range checks rather than ad-hoc epsilon logic. |
33 | 37 | - For deterministic RNG changes, validate same-seed reproducibility and bounds/argument exceptions like in `DeterministicRandom.Tests.cs`. |
34 | 38 |
|
35 | 39 | ## Agent editing guidance |
| 40 | + |
36 | 41 | - Keep public API shape stable unless the task explicitly requests API changes. |
37 | 42 | - Match existing style (regions, XML docs, explicit namespaces, no implicit usings). |
38 | | -- Make focused edits in the relevant numeric/bounds module and update corresponding tests in the parallel test file. |
| 43 | +- Make focused edits in the relevant numeric/bounds module and update corresponding tests in the parallel test file. |
| 44 | +- For serialization changes, ensure MemoryPack attributes are correctly applied and roundtrip tests are updated. |
0 commit comments