Introduction to Unity math APIs

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 to 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:

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

Additional resources

• Unity Engine math APIs
• Unity Mathematics APIs