Introduction to Unity math APIs

Understand the different math APIs Unity provides and how they compare.

Read time 3 minutes

Last updated 6 days ago

Unity provides two different sets of math APIs for math functions and structures commonly required in Unity projects:

Unity Engine math APIs: A set of mutually compatible APIs in the
```
UnityEngine
```
namespace. This includes the
```
Mathf
```
class for common math functions, including trignomometric, logarithmic, and other oprations. It also includes the
```
UnityEngine.Random
```
class for random number generation, and classes for data structures such as
```
Vector2
```
,
```
Vector3
```
,
```
Matrix4x4
```
, and
```
Quaternion
```
.
Unity Mathematics APIs: A set of mutually compatible APIs in the
```
Unity.Mathematics
```
namespace that provide Burst-compilable and Single Instruction, Multiple Data (SIMD)-friendly alternatives to the
```
UnityEngine
```
math APIs. This includes the
```
math
```
static class for common math functions, the
```
Unity.Mathematics.Random
```
class for random number generation, and data structures such as
```
float2
```
,
```
float3
```
,
```
float4
```
,
```
float4x4
```
, and
```
quaternion
```
.

Compatibility of UnityEngine math and Unity Mathematics

The

UnityEngine

and

Unity.Mathematics

APIs have important implementation differences. If your application relies on specific behaviors of one, you'll usually need to reimplement them to get equivalent behavior in the other.

You can use both

UnityEngine

and

Unity.Mathematics

APIs in your project, but it might impact the performance of your application because the conversions between the

UnityEngine

and

Unity.Mathematics

types, such as

Vector3

float3

, are performance-intensive.

In general, for performance reasons the following is recommended:

In code compiled just-in-time (JIT) with the Mono scripting backend: use
```
UnityEngine
```
math APIs rather than
```
Unity.Mathematics
```
.
In code compiled ahead-of-time (AOT) with Burst: use Unity Mathematics by default and only use the
```
UnityEngine
```
math APIs when necessary.

Converting between UnityEngine math and Unity.Mathematics

To migrate code between the

UnityEngine

and

Unity.Mathematics

APIs, you must do the following:

Replace types from one API with their equivalents from the other. For example, replace usages of
```
Vector4
```
with
```
float4
```
, and
```
Quaternion
```
with
```
quaternion
```
if migrating from
```
UnityEngine
```
to
```
Unity.Mathematics
```
APIs.
Update any operators involved in matrices or vectors. For example, the
```
Matrix4x4
```
multiplication operator implements matrix multiplication, but the
```
float4x4
```
multiplication operator implements componentwise multiplication.
Convert degrees to radians where applicable.
Update your code's random number generation.
```
Unity.Mathematics.Random
```
works differently to
```
UnityEngine.Random
```
. You can completely control random number generation with
```
Random
```
in
```
Unity.Mathematics
```
, and it's instanced, rather than static. It's also exclusive with its upper bound, which is important to bear in mind if you want to convert
```
UnityEngine
```
code which is sensitive to the bounds. For more information, refer to Unity Mathematics programming reference.

The following table provides an overview of some of the key equivalent types and members in the two APIs:

Feature	UnityEngine math	Unity Mathematics
Namespace	`UnityEngine`	`Unity.Mathematics`
Scalar math class	`Mathf` (static)	`math` (static)
Scalar type	`float`	`float`
2D Vectors	`Vector2`	`float2`
3D Vectors	`Vector3`	`float3`
4D Vectors	`Vector4`	`float4`
Integers	`Vector2Int` , `Vector3Int`	`int2` , `int3` , `int4`
Quaternions	`Quaternion`	`quaternion`
Matrices	`Matrix4x4`	`float4x4` , `float3x3` , `float2x2`
Random	`UnityEngine.Random`	`Unity.Mathematics.Random`
Mod	`Mathf.Repeat` or `%`	`math.modf`
Epsilon	`Mathf.Epsilon`	`math.EPSILON`
Dot product	`Vector3.Dot`	`math.dot`
Cross product	`Vector3.Cross`	`math.cross`
Lerp (vector)	`Vector3.Lerp`	`math.lerp(float3, float3, t)`
Slerp (quaternion)	`Quaternion.Slerp`	`math.slerp`
Matrix multiply	`a * b`	`math.mul(a, b)`

For a comprehensive list of equivalent functions and types, refer to the respective API references.

Documentation

Development

User Acquisition

Monetization

Industry

Unity Engine

User Manual

Script Reference

Unity Engine

Introduction to Unity math APIs

Compatibility of UnityEngine math and Unity Mathematics

Converting between UnityEngine math and Unity.Mathematics

Feature

UnityEngine math

Unity Mathematics

Additional resources