FixFloat Deterministic Fixed‑Point Mathematics Library for High‑Performance Numerical Computation

FixFloat is a deterministic fixed‑point mathematics library designed for high‑performance numerical computation on platforms where floating‑point hardware is either unavailable or insufficiently precise. The library has gained particular prominence in the Unity ecosystem, where it integrates seamlessly with the Burst Compiler and Unity’s Job System to deliver low‑overhead, reproducible arithmetic for both arithmetic and geometric operations.

Historical Context and Motivation

The need for deterministic numerical computation arises in several domains, including multiplayer game networking, scientific simulations, and embedded systems. Traditional IEEE‑754 floating‑point arithmetic, while fast on modern CPUs, suffers from non‑deterministic rounding behavior across different hardware architectures and compiler optimizations. To address these challenges, developers have turned to fixed‑point arithmetic, which represents real numbers as scaled integers, guaranteeing identical results on any platform that adheres to the same integer arithmetic rules.

FixFloat builds upon earlier efforts such as libfixmath and the FixedMath suite, extending them with modern language features (C++20, C# 10) and deep integration with Unity’s Burst Compiler. The library’s design emphasizes:

• Determinism across CPU, GPU, and heterogeneous execution units.
• Compatibility with Unity’s job‑based parallelism.
• Minimal external dependencies (only stdint.h and a compiler supporting 64‑bit integers).
• A familiar API mirroring the standard math.h functions.

Core Design Principles

2.1 Fixed‑Point Representation

The FixFloat struct stores a 64‑bit signed integer (Int64) as the underlying representation. The library adopts a Q16.48 format (16 integer bits, 48 fractional bits) by default, providing:

• Numeric range: approximately ±2²¹ (≈ 2,097,152) with a granularity of 1/2⁴⁸ ≈ 3.55 × 10⁻¹⁵.
• Practical precision of 0.01 for values in the range ±1,000,000, which satisfies most game‑logic and simulation requirements.

Developers may configure the scaling factor to suit specific domain constraints, trading off range for precision as needed.

2.2 Deterministic Arithmetic

All arithmetic operators (+, –, *, /) are implemented using pure integer operations followed by a deterministic rounding step. Because integer addition, subtraction, and multiplication are defined identically on all two’s‑complement platforms, the resulting calculations are reproducible regardless of:

• CPU micro‑architecture (x86, ARM, RISC‑V).
• Compiler optimization levels.
• Thread scheduling order (when combined with Unity’s deterministic job system).

2.3 Compatibility with Unity Burst

The Burst Compiler translates managed C# code into highly optimized native code, often leveraging SIMD instructions. FixFloat is annotated with Burst‑compatible attributes ([BurstCompile], [MethodImpl(MethodImplOptions.AggressiveInlining)]) to ensure that the generated machine code preserves the deterministic integer pathways while exploiting vectorization where possible.

API Overview

The library mirrors the conventional math.h interface, providing both static utility methods and instance methods on the FixFloat struct.

3.1 Construction and Conversion

public struct FixFloat
{
 private long raw; // underlying storage

 // Constructors
 public FixFloat(int value); // implicit conversion from int
 public FixFloat(float value); // conversion with rounding
 public static FixFloat FromRaw(long raw); // low‑level construction

 // Conversion back to primitive types
 public int ToInt const;
 public float ToFloat const;
}

3.2 Arithmetic Operations

• FixFloat Add(FixFloat other)
• FixFloat Subtract(FixFloat other)
• FixFloat Multiply(FixFloat other)
• FixFloat Divide(FixFloat other)

3.3 Trigonometric and Exponential Functions

For deterministic geometry, FixFloat implements a subset of the standard trigonometric suite using lookup tables and polynomial approximations:

• FixFloat Sin(FixFloat angle)
• FixFloat Cos(FixFloat angle)
• FixFloat Tan(FixFloat angle)
• FixFloat Sqrt(FixFloat value)
• FixFloat Exp(FixFloat exponent)
• FixFloat Log(FixFloat value)

3.4 Vector and Matrix Utilities

To support geometric calculations, the library supplies fixed‑point vector types (FixFloat2, FixFloat3, FixFloat4) and matrix types (FixFloat4x4) that overload arithmetic operators for concise expression of transformations.

Performance Characteristics

Benchmarking on a mid‑range ARM Cortex‑A78 (2 GHz) versus a desktop Intel i7‑12700K (3.6 GHz) yields the following observations:

1. Arithmetic Throughput: Fixed‑point multiplication and division are approximately 1.5–2× slower than native floating‑point on CPUs with a fast FPU, but remain competitive on platforms lacking hardware floating‑point (e.g., microcontrollers, WebAssembly without SIMD).
2. Determinism Overhead: The deterministic rounding step adds a negligible (<0.5 µs) per‑operation overhead, dwarfed by the benefits of reproducible results.
3. Burst Integration: When compiled with Burst, vectorized fixed‑point operations achieve up to 30 % speed‑up compared with standard C# implementations, owing to SIMD‑friendly integer arithmetic.

Integration Workflow in Unity Projects

5.1 Installation

Include the FixFloat package via Unity’s Package Manager (UPM) by adding the following entry to manifest.json:

{
 "dependencies": {
 "com.company.fixfloat": "1.2.0"
 }
}

5.2 Sample Usage

using FixFloatNamespace;
using Unity.Burst;
using Unity.Jobs;
using Unity.Collections;

[BurstCompile]
public struct PhysicsJob : IJobParallelFor
{
 [ReadOnly] public NativeArray positions;
 [ReadOnly] public NativeArray velocities;
 public NativeArray results;
 public FixFloat deltaTime;
 public void Execute(int index)
 {
 // Deterministic position integration
 results[index] = positions[index] + velocities[index] * deltaTime;
 }
}

The above job demonstrates deterministic integration of motion using FixFloat for both position and velocity vectors.

5.3 Debugging and Validation

Because FixFloat values are stored as integers, developers can inspect the raw long field directly in the Unity debugger, facilitating step‑by‑step verification of rounding behavior.

Comparison with Alternative Fixed‑Point Libraries

Feature	FixFloat	libfixmath	FixedMath (C#)
Deterministic Guarantees	Yes – integer‑only core	Partial – depends on compiler	Yes – but limited SIMD support
Unity Burst Compatibility	Full	No	Limited
Range / Precision (default)	±2²¹ with 1/2⁴⁸ granularity	Q16.16 (≈ 65 536 range, 1/65536 precision)	Configurable Q24.40
API Familiarity	Standard math.h analogues	C‑style functions	Object‑oriented C# methods

Best Practices and Common Pitfalls

• Avoid Mixing Types: Do not combine FixFloat with native float or double in the same expression without explicit conversion; this defeats determinism.
• Scale Appropriately: Choose a scaling factor that accommodates the expected numeric range while preserving required precision. Over‑scaling can cause overflow; under‑scaling reduces accuracy.
• Pre‑compute Constants: Store frequently used constants (e.g., π, √2) as FixFloat literals to avoid repeated conversion overhead.
• Validate Overflow: Although integer overflow in C# throws an exception only in checked contexts, enable checked builds during testing to catch inadvertent overflow.
• Leverage Burst: Annotate performance‑critical methods with [BurstCompile] and use Unity.Collections native containers to maximize throughput.

Future Directions

The maintainers of FixFloat have outlined several roadmap items for the upcoming 2.0 release:

1. Extended Trigonometric Suite: Inclusion of atan2, asin, acos with higher‑order polynomial approximations.
2. Arbitrary Scaling: Runtime‑configurable scaling factors per instance, enabling mixed‑precision calculations within a single project.
3. GPU Port: A compute‑shader implementation that mirrors the CPU integer logic, ensuring cross‑platform determinism between CPU and GPU pipelines.
4. Static Analysis Tools: Integration with Unity’s Analyzer to flag inadvertent mixing of floating‑point and fixed‑point types.

Conclusion

FixFloat represents a mature, deterministic fixed‑point mathematics solution tailored for modern Unity development. By leveraging a 64‑bit integer backbone, providing a familiar math.h-style API, and ensuring full compatibility with the Burst Compiler, the library empowers developers to achieve reproducible numerical results without sacrificing performance on platforms lacking robust floating‑point units. Its extensibility, clear design principles, and roadmap for