Unity.Mathematics Documentation

Unity Mathematics is a C# math library designed with a shader-like syntax (similar to HLSL or SIMD) to facilitate high-performance math operations. It is optimized for use with the Burst compiler to compile C# into efficient native code.

Supported Vector and Matrix Types:

• floatN (e.g., float2, float3, float4)
• quaternion
• float3x3
• float4x4

Supported Elementary Functions:

• Basic: min, max, fabs, etc.
• Trigonometric/Geometric: sin, cos, sqrt, normalize, dot, cross, etc.

The quaternion type is a core component of Unity.Mathematics designed as a drop-in replacement for float3x3 in many contexts.

Key features include:

• Matrix Compatibility: quaternion can be used to initialize matrices and supports the mul function just like float3x3.
• Named Constructors: It provides the same set of named constructors as the equivalent float3x3 type for common transform operations.
• Inversion: Use inverse or fastinverse for inverting quaternions.

Unity Mathematics uses lowercase names for its core types and intrinsic operators to align with HLSL shader code and Burst compiler built-in types.

• Types: Vectors (typeN), matrices (typeNxN), and quaternions (quaternion) are written in all lowercase.
• Operators: Mathematical functions in Unity.Mathematics.math are intrinsics and are always lowercase.

This convention facilitates frictionless code sharing between C# (via Burst) and shader code.

The Random type is a basic PRNG based on the xor-shift algorithm. It is designed to be lightweight with a small state and avoids integer multiplication, making it efficient on lower-tier vector instruction sets.

Capabilities:

• Drawing uniformly random values for basic scalar and vector types.
• Generating uniformly random directions and rotations.

Warning: Because Random is implemented as a struct to support Burst, you must ensure it is properly initialized. A zero-initialized Random instance (e.g., default(Random)) will perpetually generate only zeros due to the nature of the xor-shift algorithm.

In Unity.Mathematics, the * operator for float4x4 performs componentwise multiplication, which differs from the behavior in UnityEngine. Multiplying two matrices with the * operator multiplies each corresponding element together.

void OperatorMultiply4x4UnityMathematics()
{
   float4x4 result = f4x4_Ones * f4x4_HalfIdentity;
   // result:
   // 0.5, 0.0, 0.0, 0.0,
   // 0.0, 0.5, 0.0, 0.0,
   // 0.0, 0.0, 0.5, 0.0,
   // 0.0, 0.0, 0.0, 0.5
}

To use the library, add using Unity.Mathematics; to your namespace. For easier access to the math functions, you can also use using static Unity.Mathematics.math; to call functions like float3(), normalize(), and dot() directly without a class prefix.

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);
    ...
}

To apply a rotation to an existing quaternion, you can create a rotation quaternion using quaternion.AxisAngle and then combine it with your target orientation using math.mul.

Note that quaternion.AxisAngle expects the angle in radians, not degrees. You can use math.radians() to convert from degrees. math.mul performs quaternion multiplication, which is the standard way to compose rotations, similar to how matrices and vectors are multiplied.

// Unity Mathematics example
void QuaternionMultiplicationUnityMathematics()
{
   var axis = new float3(0.0f, 1.0f, 0.0f);
   var q = quaternion.AxisAngle(axis,math.radians(45.0f));
   var orientation = quaternion.Euler(
       math.radians(45.0f),
       math.radians(90.0f),
       math.radians(180.0f));
   var result = math.mul(q, orientation);
}

To optimize for Burst compilation, use the Unity.Mathematics package by default and only use Mathf when necessary.

Performance Warning:

• Burst Compilation: Use Unity.Mathematics for best performance with Burst.
• Mono Compiler: If your project uses the Mono compiler (and not Burst), continue using Mathf for mathematical operations, as Unity.Mathematics may not provide performance benefits in that context.
• Type Conversions: Avoid frequent conversions between UnityEngine types (e.g., Vector3) and Unity.Mathematics types (e.g., float3), as these conversions are performance-intensive.