Rotation and Orientation in Unity

Rotations in 3D applications are usually represented in one of two ways: Quaternions or Euler angles. Each has its own uses and drawbacks. Unity uses Quaternions internally, but shows values of the equivalent Euler angles in the InspectorA Unity window that displays information about the currently selected GameObject, Asset or Project Settings, alowing you to inspect and edit the values. More info
See in Glossary to make it easy for you to edit.

Euler angles and quaternions

Euler angles

Euler angles are represented by three angle values for X, Y and Z that are applied sequentially. To apply a Euler rotation to a particular GameObjectThe fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More info
See in Glossary, each rotation value is applied in turn, as a rotation around its corresponding axis.

• Benefit: Euler angles have an intuitive “human readable” format, consisting of three angles.
• Benefit: Euler angles can represent the rotation from one orientation to another through a turn of more than 180 degrees
• Limitation: Euler angles suffer from Gimbal Lock. When applying the three rotations in turn, it is possible for the first or second rotation to result in the third axis pointing in the same direction as one of the previous axes. This means a “degree of freedom” has been lost, because the third rotation value cannot be applied around a unique axis.

Quaternions

Quaternions can be used to represent the orientation or rotation of a GameObject. This representation internally consists of four numbers (referenced in Unity as x, y, z & w) however these numbers don’t represent angles or axes and you never normally need to access them directly. Unless you are particularly interested in delving into the mathematics of Quaternions, you only really need to know that a Quaternion represents a rotation in 3D space and you never normally need to know or modify the x, y & z properties.

In the same way that a Vector can represent either a position or a direction (where the direction is measured from the origin), a Quaternion can represent either an orientation or a rotation - where the rotation is measured from the rotational “origin” or “Identity”. It is because the rotation is measured in this way - from one orientation to another - that a quaternion can’t represent a rotation beyond 180 degrees.

• Benefit: Quaternion rotations do not suffer from Gimbal Lock.
• Limitation: A single quaternion cannot represent a rotation exceeding 180 degrees in any direction.
• Limitation: The numeric representation of a Quaternion is not intuitively understandable.

Unity stores all GameObject rotations internally as Quaternions, because the benefits outweigh the limitations.

The Transform Inspector displays the rotation using Euler angles, because this is easier to understand and edit. Unity converts new values into the Inspector for the rotation of a GameObject into a new Quaternion rotation value for the GameObject.

As a side-effect, it is possible in the Inspector to enter a value of, say, X: 0, Y: 365, Z: 0 for a GameObject’s rotation. This value is not possible to represent as a quaternion, so when you enter Play mode, the GameObject’s rotation values change to X: 0, Y: 5, Z: 0. This is because Unity converts rotation to a Quaternion which does not have the concept of a full 360-degree rotation plus 5 degrees, and instead is set to orient the same way as the result of the rotation.

Implications for scripting

When dealing with handling rotations in your scriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
See in Glossary, you should use the Quaternion class and its functions to create and modify rotational values. There are some situations where it is valid to use Euler angles, but you should bear in mind: - You should use the Quaternion Class functions that deal with Euler angles - Retrieving, modifying, and re-applying Euler values from a rotation can cause unintentional side-effects.

Creating and manipulating quaternions directly

Unity’s Quaternion class has a number of functions which allow you to create and manipulate rotations without needing to use Euler angles at all. For example:

Creating:

• Quaternion.LookRotation
• Quaternion.AngleAxis
• Quaternion.FromToRotation

Manipulating:

• Quaternion.Slerp
• Quaternion.Inverse
• Quaternion.RotateTowards
• Transform.Rotate & Transform.RotateAround

However sometimes it’s desirable to use Euler angles in your scripts. In this case it’s important to note that you must keep your angles in variables, and only use them to apply them as Euler angles to your rotation. While it’s possible to retrieve Euler angles from a quaternion, if you retrieve, modify and re-apply, problems are likely to arise.

Here are some examples of mistakes commonly made using a hypothetical example of trying to rotate a GameObject around the X axis at 10 degrees per second. This is what you should avoid:

// rotation scripting mistake #1
// the mistake here is that we are modifying the x value of a quaternion
// this value does not represent an angle, and does not produce desired results
    
void Update () 
    {
    var rot = transform.rotation;
    rot.x += Time.deltaTime * 10;
    transform.rotation = rot;
        
    }

// rotation scripting mistake #2
// Read, modify, then write the Euler values from a Quaternion.
// Because these values are calculated from a Quaternion,
// each new rotation might return very different Euler angles, which might suffer from gimbal lock.
        
void Update () 
    {
        var angles = transform.rotation.eulerAngles;
        angles.x += Time.deltaTime * 10;
        transform.rotation = Quaternion.Euler(angles);
    }

And here is an example of using Euler angles in script correctly:

// Rotation scripting with Euler angles correctly.
// Store the Euler angle in a class variable, and only use it to
// apply it as a Euler angle, but never rely on reading the Euler back.
        
float x;
void Update () 
    {
        x += Time.deltaTime * 10;
        transform.rotation = Quaternion.Euler(x,0,0);
    }

See documentation on Quaternion.Euler for more details.

Implications for Animation

Many 3D authoring packages, and Unity’s own internal Animation window, allow you to use Euler angles to specify rotations during an animation.

These rotations values can frequently exceed ranges expressable by quaternions. For example, if a GameObject rotates 720 degrees, this could be represented by Euler angles X: 0, Y: 720, Z:0. But this is not representable by a Quaternion value.

Unity’s Animation Window

Within Unity’s own animation window, there are options which allow you to specify how the rotation should be interpolated - using Quaternion or Euler interpolation. By specifying Euler interpolation you are telling Unity that you want the full range of motion specified by the angles. With Quaternion rotation however, you are saying you simply want the rotation to end at a particular orientation, and Unity uses Quaternion interpolation and rotate across the shortest distance to get there. See Using Animation Curves for more information on this.

External Animation Sources

When importing animation from external sources, these files usually contain rotational keyframe animation in Euler format. Unity’s default behaviour is to resample these animations and generate a new Quaternion keyframe for every frame in the animation, in an attempt to avoid any situations where the rotation between keyframesA frame that marks the start or end point of a transition in an animation. Frames in between the keyframes are called inbetweens.
See in Glossary may exceed the Quaternion’s valid range.

For example, imagine two keyframes, 6 frames apart, with values for X as 0 on the first keyframe and 270 on the second keyframe. Without resampling, a quaternion interpolation between these two keyframes would rotate 90 degrees in the opposite direction, because that is the shortest way to get from the first orientation to the second orientation. However by resampling and adding a keyframe on every frame, there are now only 45 degrees between keyframes so the rotation works correctly.

There are still some situations where - even with resampling - the quaternion representation of the imported animation may not match the original closely enough, For this reason, in Unity 5.3 and onwards there is the option to turn off animation resampling, so that you can instead use the original Euler animation keyframes at runtime. For more information, see Animation Import of Euler Curve Rotations.