Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

Unity Mathematics APIs

Use the collection of SIMD-friendly, Burst-compilable math APIs in the Unity.Mathematics namespace to access common mathematical operations, including trigonometric and logarithmic functions, random number generation, and working with vectors, matrices, and quaternions.
Read time 5 minutesLast updated 8 days ago
The APIs in the 
Unity.Mathematics
namespace are a Burst-compilable C# math library that provides vector types and math functions that have a shader-like syntax, similar to Single Instruction, Multiple Data (SIMD) or High-Level Shading Language (HLSL).
Unity Mathematics offers a Burst-compilable alternative to Unity's standard Unity Engine math APIs. Unity Mathematics implements vector and matrix types such as 
float3
, 
quaternion
, 
float3×3
, and 
float4×4
. It also includes elementary functions such as min, max, fabs, sin, cos, sqrt, normalize, dot, and cross.
To use Unity Mathematics, add 
using Unity.Mathematics
to your code.
Prefer Unity Mathematics APIs over Unity Engine math APIs in Burst-compiled code. For code that isn't Burst compiled, prefer Unity Engine math APIs.

Naming convention

In C# 
int
and 
float
are built-in types. The Burst compiler extends this set of built-in types to also include vectors, matrices, and quaternions. The Burst compiler already has implementations of these types, and can use them to generate better code than for custom types.
To signify that these types are built-in, their type names are in all lower case. The operators on these built-in types in 
Unity.Mathematics.math
 are intrinsics and are always in lower case. This convention has the added benefit of making the library highly compatible with shader code and makes porting or sharing code between the two easier.

4×4 matrices

To create a 4×4 transformation matrix, use the constructors in 
float4x4
 to assign one value to all elements of the matrix, or individually set all 16 elements directly:
// Unity Mathematics examplevoid Build4x4UnityMathematics(){   var c0 = new float4(1.0f, 0.0f, 0.0f, 0.0f);   var c1 = new float4(0.0f, 1.0f, 0.0f, 0.0f);   var c2 = new float4(0.0f, 0.0f, 1.0f, 0.0f);   var c3 = new float4(0.0f, 0.0f, 0.0f, 1.0f);   var m = new float4x4(c0, c1, c2, c3);}

Multiplying a 4×4 matrix

The 
Unity.Mathematics
and 
UnityEngine
APIs define the 
*
operator differently. The 
*
operator for 
float4x4
 implements componentwise multiplication. If you multiply a 
float4x4
of all 1s with 0.5 on the diagonal, you get back the half identity because the upper and lower triangles of the matrix are multiplied by the respective zero entries from 
f4x4_HalfIdentity
:
// Unity Mathematics examplevoid 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}

Multiplying a 4×4 matrix and a 4D vector

Use the 
math.mul
 method to multiply a 4×4 matrix and a 4D vector. If you supply a 
float4x4
as the first parameter and a 
float4
as the second, it performs a 4×4 matrix multiplication with a 4×1 column vector, which returns a 4×1 column vector as a 
float4
.
math.mul
can also multiply a 1×4 row vector by a 4×4 matrix to produce a 1×4 row vector by taking a 
float4
as the first parameter and a 
float4×4
as the second. Unity Mathematics stores the row vector in a 
float4
and it isn't treated as a separate type.
// Unity Mathematics examplevoid Multiply4x4AndVector4UnityMathematics(){   float4 result1 = math.mul(f4x4, f4); // 4x4 * 4x1 = 4x1   float4 result2 = math.mul(f4, f4x4); // 1x4 * 4x4 = 1x4}

Vector multiplication

To multiply vectors, use the 
*
operator:
// Unity Mathematics examplevoid ComponentwiseVectorMultiplyUnityMathematics(){   var v0 = new float4(2.0f, 4.0f, 6.0f, 8.0f);   var v1 = new float4(1.0f, -1.0f, 1.0f, -1.0f);   var result = v0 * v1;   // result == new float4(2.0f, -4.0f, 6.0f, -8.0f).}
This is a common way of writing SIMD code, which applies a single instruction to multiple data elements. Other operators such as addition, subtraction, and division work in the same way.

Quaternion multiplication

To rotate a quaternion, use the 
AxisAngle
 method. You need to specify the axis of rotation and the angle of rotation, in that order. All are in radians rather than degrees. 
math.mul
multiplies the quaternion, just as with matrices and vectors.
// Unity Mathematics examplevoid 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);}

Random numbers

To generate random numbers, you must create and manage the random number generator state yourself with the 
Random
 struct. You can control the random number generator state explicitly, which is useful if you're using parallel code, or if you want to make sure that one source of random numbers is seeded differently than another source. You can also have as many 
Random
instances as you like.
Once you set up the state, use 
NextFloat
 to get random floats. By default it returns random numbers between 
[0, 1)
, exclusive:
// Unity Mathematics examplevoid RandomNumberUnityMathematics(){   // Choose some non-zero seed and set up the random number generator state.   uint seed = 1;   Unity.Mathematics.Random rng = new Unity.Mathematics.Random(seed);   // [0, 1) exclusive   float randomFloat1 = rng.NextFloat();   // [-5, 5) exclusive   float randomFloat2 = rng.NextFloat(-5.0f, 5.0f);}

Additional resources