Home › API Reference › Quaternion

Quaternion

Type	Struct (value type)
Namespace	`UnityEngine`
Used by	`Transform.rotation`, `Instantiate`, `Rigidbody.MoveRotation`

Quaternion

A Quaternion stores a rotation. Internally it's four numbers (x, y, z, w) that you should never edit directly. Instead, you create and combine rotations with the helper methods on this page. You can think in degrees and let Unity do the math.

Describing a rotation as three angles (X, Y, Z) is like steering with three dials, one per axis. It works most of the time, but in some positions two dials end up turning the same way and you lose one direction of control. This is called gimbal lock. A quaternion is more like saying "point along this arrow, then twist this much". It has no dials, so nothing can jam. You don't need to understand the four numbers, just like you don't need to understand a car engine to drive.

Static Properties

Name	Description
`Quaternion.identity`	"No rotation". Use it when spawning something that shouldn't be rotated.

Properties

Name	Type	Description
`eulerAngles`	`Vector3`	The rotation as X/Y/Z degrees. Reading it can give surprising (but equivalent) numbers.

Static Methods

Method	Returns	Description
`Euler(x, y, z)`	`Quaternion`	Make a rotation from degrees. The most common way to create one.
`AngleAxis(angle, axis)`	`Quaternion`	Rotate `angle` degrees around an axis, e.g. `AngleAxis(90, Vector3.up)`.
`LookRotation(forward, up = Vector3.up)`	`Quaternion`	A rotation that faces a direction.
`FromToRotation(from, to)`	`Quaternion`	The rotation that turns one direction into another. E.g. align an object with a slope.
`RotateTowards(from, to, maxDegrees)`	`Quaternion`	Turn toward a target by at most `maxDegrees`. Constant turn speed, never overshoots.
`Slerp(a, b, t)`	`Quaternion`	A rotation part-way between `a` and `b`. Smooth blending.
`Angle(a, b)`	`float`	Degrees between two rotations.
`Inverse(q)`	`Quaternion`	The opposite rotation.

Operators

Code	Meaning
`a * b`	Combine: first apply `b`, then `a`. Order matters: `a * b` is usually not the same as `b * a`.
`q * vector`	Rotate a Vector3 by `q`. E.g. `transform.rotation * Vector3.forward` equals `transform.forward`.

Code Samples

Setting a rotation with degrees

transform.rotation = Quaternion.Euler(0f, 90f, 0f); // face +X (turned right 90 degrees)

Turn smoothly to face a target (turret)

using UnityEngine;

public class SmoothTurret : MonoBehaviour
{
    [SerializeField] private Transform target;
    [SerializeField] private float turnSpeed = 90f; // degrees per second

    void Update()
    {
        Vector3 dir = target.position - transform.position;
        dir.y = 0f; // stay level: only turn left/right
        if (dir == Vector3.zero) return;

        Quaternion wanted = Quaternion.LookRotation(dir);
        transform.rotation = Quaternion.RotateTowards(
            transform.rotation, wanted, turnSpeed * Time.deltaTime);
    }
}

Spawn a bullet with a random spread

Quaternion spread = Quaternion.Euler(Random.Range(-3f, 3f), Random.Range(-3f, 3f), 0f);
Instantiate(bulletPrefab, muzzle.position, muzzle.rotation * spread);

Keep your own angle instead of reading eulerAngles

using UnityEngine;

public class MouseLook : MonoBehaviour
{
    [SerializeField] private float sensitivity = 2f;
    private float pitch; // up/down, kept by us so it never "flips"
    private float yaw;   // left/right

    void Update()
    {
        yaw   += Input.GetAxis("Mouse X") * sensitivity;
        pitch -= Input.GetAxis("Mouse Y") * sensitivity;
        pitch  = Mathf.Clamp(pitch, -80f, 80f); // don't look past straight up/down

        transform.rotation = Quaternion.Euler(pitch, yaw, 0f);
    }
}

What happens at runtime

Quaternion.Euler(x, y, z) converts your degrees into a quaternion. Unity applies them in the order Z, then X, then Y.
When you read eulerAngles, Unity converts back. Many different sets of angles describe the same rotation, so you might get (180, 0, 180) where you expected (0, 180, 0). Both are correct; they're just two ways of writing it.
Like Vector3, Quaternion is a struct: it's copied on assignment and creates no garbage.

Common Mistakes

Setting x/y/z/w directly. rotation.y = 90 does not mean 90 degrees. Use Quaternion.Euler.
Adding to eulerAngles every frame and reading them back. Can jump or flip near 90 degrees on X. Keep your own float angles (see the MouseLook example).
LookRotation(Vector3.zero) logs "Look rotation viewing vector is zero". Check that the direction isn't zero first.
Wrong multiplication order. transform.rotation * extra rotates around the object's own axes; extra * transform.rotation rotates around world axes.

Quaternion

Static Properties

Properties

Static Methods

Operators

Code Samples

Setting a rotation with degrees

Turn smoothly to face a target (turret)

Spawn a bullet with a random spread

Keep your own angle instead of reading eulerAngles

What happens at runtime

Common Mistakes

See also