# Unity.Mathematics: SIMD-oriented math types for Unity C#

> Unity.Mathematics gives Unity C# code shader-style vector, matrix, quaternion, and math APIs that the Burst compiler can translate into optimized native SIMD code. It fits compute-heavy Unity projects, but its work-in-progress API and custom licence require careful review before adoption.

**Unity-Technologies/Unity.Mathematics** — The C# math library used in Unity providing vector types and math functions with a shader like syntax

- Repository: https://github.com/Unity-Technologies/Unity.Mathematics
- Stars: 1,443 · Forks: 159
- Language: C#
- License: NOASSERTION
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/unity-technologies-unity-mathematics

## Why Unity.Mathematics exists in a Unity project

Unity.Mathematics addresses a specific mismatch between ordinary C# math APIs and the code that Unity's Burst compiler can optimize. Unity already has vector types such as Vector3, but this library offers an API shaped around graphics and shader conventions, including float3, float4, related vector and matrix forms, and quaternion. Its functions are exposed through the static Unity.Mathematics.math class and can be imported with `using static Unity.Mathematics.math`.

The intended users are SIMD and graphics developers working in Unity, particularly developers whose performance requirements make Burst compilation relevant. The README says the Burst compiler recognizes these types and can turn C# or IL into native code, using optimized SIMD types for the CPU on supported x64 and ARMv7a platforms. That is a narrower purpose than providing a general replacement for every .NET mathematics package. Its value comes from alignment with Burst rather than from the vector operations alone.

The project explicitly says the API is a work in progress and may introduce breaking changes in both API and underlying behavior. That statement matters more than the familiar syntax. A team can still find the design convenient while recognizing that an upgrade may require source changes. The listed releases, including 1.2.5 on 2021-11-08 and 1.2.4 on 2021-10-05, do not by themselves describe the current API surface or guarantee compatibility with a particular Unity release.

## How Burst recognizes Unity.Mathematics operations

The library's architecture is centered on types that Burst treats as built-in. According to the README naming guidance, C# already treats int and float as built-in types, while Burst extends that model to vectors, matrices, and quaternions. Their lower-case names, such as float3 and quaternion, are intended to identify them as part of this intrinsic set. Functions and operators in Unity.Mathematics.math follow the same convention and are described as intrinsics.

A typical operation constructs vectors, passes them to math functions, and stores a scalar result in another vector. The example normalizes two float3 values and calculates dot(v1, v2) after normalization. This is a direct representation of a common graphics calculation, but the README does not expose Unity.Mathematics as a separate execution engine. Instead, the relevant data path is source code using recognized types and operations, followed by Burst compilation into native code for the target CPU.

That design explains the library's naming choice. Shader-oriented code can use similar operation names and component layouts, which the README says helps when sharing or porting code between C# and shader environments. It does not mean that all C# and shader code is interchangeable. The repository gives no syntax-compatibility matrix, portability guide, or claim that types can be moved between runtimes without conversion.

The README also states that Burst recognizes a wider range of patterns for its SIMD types and math intrinsics than it does for the older Unity vector API. That is the principal technical difference from System.Numerics.Vectors, rather than a claim that either library provides a different mathematical result. Adoption therefore depends on how much the compilation path matters to the project.

## Installing com.unity.mathematics and running the README example

Unity projects should obtain the library through Unity's Package Manager by referencing the package `com.unity.mathematics`. The README does not give a package installation command, version selector, or registry configuration, so none can be added safely. It also points to the Unity forum's Welcome page for further details rather than publishing a fuller setup procedure here.

After adding the package, import the static math class, reference the Unity.Mathematics namespace, construct two vectors, normalize them, and calculate their dot product. The following example is copied from the README:

```csharp
using static Unity.Mathematics.math;
namespace MyNamespace
{
    using Unity.Mathematics;
    
    ...
    var v1 = float3(1,2,3);
    var v2 = float3(4,5,6);
    v1 = normalize(v1);
    v2 = normalize(v2);
    var v3 = dot(v1, v2);
    ...
}
```

The expected result is that `v1` and `v2` contain normalized components and `v3` contains their scalar dot product. The README does not document the numeric value of that result, so this article does not supply one. It also does not explain how the example is placed in a MonoBehaviour, a job, or another Burst-compatible execution context. A reader should first confirm that the package is visible to the Unity project and that the containing code is arranged for the intended Burst compilation path.

For contributors or users who intend to build the source rather than consume the package, the README gives a separate route: open `src\Unity.Mathematics.sln` in Visual Studio 2015 or MonoDevelop and compile in Debug\Release. That is an IDE operation, not a documented command-line workflow, and the repository does not list build prerequisites.

## Package setup versus source building in Unity.Mathematics

Package Manager is the normal route described for use in a Unity game, while the solution file exists for source compilation. These paths answer different needs. Package Manager supplies a package reference within Unity, whereas opening `src\Unity.Mathematics.sln` is aimed at building the library from the repository in one of two named development environments.

The repository layout includes source under `src`, documentation under `doc`, a test project named `Unity.Mathematics.TestProject`, and tooling under `Tools`. Based on that layout, testing and tooling are separated from the core source, but the README does not identify test commands, package dependencies, or a supported CI workflow. It would be inaccurate to present the test project as a documented verification command without that information.

Formatting is handled through `.editorconfig`, which is appropriate for consistent end-of-line and whitespace behavior. The README lists extensions for Visual Studio 2015, Visual Studio 2017, Visual Studio Code, and SublimeText. Those extensions support formatting only. They are not described as build dependencies or as necessary for using the package in Unity.

The contribution process is another boundary. The README says pull requests are not yet accepted because a Contributor License Agreement with sign-over functionality was still being prepared. Based on the stated reason, outside contributors cannot assume that a normal pull request is an accepted contribution route.

## Unity.Mathematics compared with System.Numerics.Vectors

The clearest documented alternative is System.Numerics.Vectors. The README says that System.Numerics.Vectors is similar to Unity's previous vector library and is more object-oriented, while Unity.Mathematics follows the math API used by graphics and shader developers. This is an API design difference, not a claim that one package performs arithmetic correctly while the other does not.

System.Numerics.Vectors is the relevant choice when existing .NET conventions and object-oriented vector APIs are the priority. Unity.Mathematics is the better fit when code should resemble HLSL or GLSL operations and when Burst can recognize the library's types and intrinsic patterns. The README specifically links Burst recognition to the decision not to use System.Numerics.Vectors.

That does not make Unity.Mathematics a universal replacement. Its API may still change, its package is obtained through Unity Package Manager, and its licence is the Unity Companion License rather than a standard GitHub-classified open source licence. The README describes no comparison for arbitrary .NET runtimes, editor tooling outside Unity, or workloads that are never processed by Burst. Those cases require checking package availability and licensing rather than relying on the SIMD-oriented API alone.

## Maintenance, upgrades, and the Unity Companion License

The repository is not archived, and its last push was on 2026-08-06. That is recent enough to avoid describing it as inactive, but the available release list still ends at version 1.2.5 from 2021-11-08. The repository also lists a release named Mathematics 1.2.2 from 2021-09-01. The difference between repository activity and the age of listed releases means package consumers should not infer a current support policy from either fact alone.

The README explicitly warns that breaking changes may occur in the API and underlying behavior. Upgrade planning should therefore include source review and compilation checks. The documentation does not provide a migration guide, a compatibility matrix for Unity editor versions, a semantic-versioning policy, or a rollback procedure. Those omissions are relevant to projects that cannot easily absorb math API changes.

Licensing is also project-specific. The repository identifies the Unity Companion License and directs readers to `LICENSE.md` for details. This review cannot determine from the README alone which distribution models, products, or internal uses are permitted or restricted. Organizations should read `LICENSE.md` themselves and confirm how the package will be embedded and distributed. The repository's contributor statement also says the existing UCL License does not yet cover the planned CLA sign-over process, which is relevant to contribution planning rather than ordinary use.

## Limits of the Unity.Mathematics adoption case

The clearest wrong-tool case is a standalone .NET application with no reason to compile through Unity Burst. In that situation, the central technical argument for Unity.Mathematics does not apply. System.Numerics.Vectors may be more consistent with the rest of an object-oriented .NET codebase, although the README does not claim it is faster in every situation.

A second limitation is API stability. The README's warning about breaking changes makes exact version control and integration planning part of the decision. Consumers who cannot tolerate source-level changes should not treat the recent repository push as proof that upgrade work is absent.

The documentation is also intentionally narrow. It does not describe licensing beyond pointing to `LICENSE.md`, dependency installation details, test invocation, platform-specific setup, numerical edge-case policy, or migration between older Unity vector types. Those are not reasons to claim the library is defective. They are concrete points that remain unverified in the README and therefore belong in an adoption checklist.

The project is most convincing as a Unity-specific computational library whose API is recognized by Burst. It is less convincing as a general math library chosen for syntax alone.

## Conclusion

Adopt Unity.Mathematics when Burst compilation, shader-like C# math code, and SIMD recognition are central to a Unity project. Do not choose it merely for general-purpose .NET math, especially if its work-in-progress API or custom licence does not fit your delivery requirements. Verify Package Manager compatibility, Burst compilation in the target environment, and the obligations in LICENSE.md before committing to it.

## FAQ

### How do I install Unity.Mathematics in a Unity project?

The README says to use Unity Package Manager and reference `com.unity.mathematics`. It does not provide a command-line installation command or registry configuration.

### Why does Unity.Mathematics use types such as float3 instead of Vector3?

The project presents float3, other vector types, matrices, and quaternions as built-in types recognized by Burst. The lower-case naming and shader-style API are intended to resemble graphics and shader conventions.

### Can I use Unity.Mathematics outside Unity?

The README focuses on use in Unity through Package Manager and on compilation by the Burst compiler. It does not document a general-purpose .NET installation or compatibility procedure for non-Unity applications.

## Sources

- [Issues](https://github.com/Unity-Technologies/Unity.Mathematics/issues)
- [README](https://github.com/Unity-Technologies/Unity.Mathematics/blob/master/README.md)
- [Releases](https://github.com/Unity-Technologies/Unity.Mathematics/releases)
- [Unity-Technologies/Unity.Mathematics on GitHub](https://github.com/Unity-Technologies/Unity.Mathematics)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/unity-technologies-unity-mathematics