|
| 1 | +# FixedMathSharp agent instructions |
| 2 | + |
| 3 | +## Project intent and architecture |
| 4 | +- 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 | +- Most API surface lives in value-type numerics (`Fixed64`, `Vector2d`, `Vector3d`, `FixedQuaternion`, `Fixed3x3`, `Fixed4x4`) plus bounds types (`BoundingBox`, `BoundingSphere`, `BoundingArea`) implementing `IBound`. |
| 6 | +- Keep operations deterministic and allocation-light; many methods use `m_rawValue` and `[MethodImpl(MethodImplOptions.AggressiveInlining)]` for hot paths. |
| 7 | +- `FixedMath` and `FixedTrigonometry` are the shared algorithm backbones; extension classes in `src/FixedMathSharp/Numerics/Extensions/` are thin forwarding wrappers, not alternate implementations. |
| 8 | + |
| 9 | +## Build and test workflows |
| 10 | +- Solution: `FixedMathSharp.sln` with library project and test project. |
| 11 | +- Target frameworks are multi-targeted in both projects: `net48;net8`. |
| 12 | +- Typical local workflow: |
| 13 | + - `dotnet restore` |
| 14 | + - `dotnet build --configuration Debug --no-restore` |
| 15 | + - `dotnet test --configuration Debug` |
| 16 | +- CI detail from `.github/workflows/dotnet.yml`: |
| 17 | + - Linux runs `net48` tests via Mono + `xunit.console.exe` and `net8` via `dotnet test -f net8`. |
| 18 | + - Windows runs `dotnet test` for both TFMs. |
| 19 | +- Packaging/versioning comes from `src/FixedMathSharp/FixedMathSharp.csproj`: GitVersion variables are consumed when present, otherwise version falls back to `0.0.0`. |
| 20 | + |
| 21 | +## Code conventions specific to this repo |
| 22 | +- Prefer `Fixed64` constants (`Fixed64.Zero`, `Fixed64.One`, `FixedMath.PI`) over primitive literals in math-heavy code. |
| 23 | +- Preserve saturating/guarded semantics in operators and math helpers (for example `Fixed64` add/sub overflow behavior). |
| 24 | +- When touching bounds logic, maintain cross-type dispatch shape in `Intersects(IBound)` and shared clamping projection via `IBoundExtensions.ProjectPointWithinBounds`. |
| 25 | +- Serialization compatibility is intentional: |
| 26 | + - MessagePack attributes on serializable structs (`[MessagePackObject]`, `[Key]`) across TFMs. |
| 27 | + - Conditional serializers in tests (`BinaryFormatter` for `NET48`, `System.Text.Json` for `NET8`). |
| 28 | +- `ThreadLocalRandom` is marked `[Obsolete]`; new deterministic RNG work should prefer `DeterministicRandom` and `DeterministicRandom.FromWorldFeature(...)` in `src/FixedMathSharp/Utility/DeterministicRandom.cs`. |
| 29 | + |
| 30 | +## Testing patterns to mirror |
| 31 | +- Tests are xUnit (`tests/FixedMathSharp.Tests`). Keep one feature area per test file (e.g., `Vector3d.Tests.cs`, `Bounds/BoundingBox.Tests.cs`). |
| 32 | +- Use helper assertions from `tests/FixedMathSharp.Tests/Support/FixedMathTestHelper.cs` for tolerance/range checks rather than ad-hoc epsilon logic. |
| 33 | +- For deterministic RNG changes, validate same-seed reproducibility and bounds/argument exceptions like in `DeterministicRandom.Tests.cs`. |
| 34 | + |
| 35 | +## Agent editing guidance |
| 36 | +- Keep public API shape stable unless the task explicitly requests API changes. |
| 37 | +- 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. |
0 commit comments