Quaternion in Godot – Complete Guide

In the realm of 3D game development, mastering rotations is akin to a magician mastering their spells. Without this foundational skill, it’s tough to bring to life the rich, dynamic interactions we expect in modern games. Enter quaternions – a complex yet powerful tool in any game developer’s toolkit, especially with the rising popularity of the Godot Engine and its latest release, Godot 4. Whether you are an aspiring game developer or a seasoned programmer seeking to brush up on 3D math concepts, understanding quaternions is a critical step towards achieving smooth and glitch-free rotations in your 3D worlds.

What is a Quaternion?

Imagine arranging your 3D models in a scene, only to find them jarringly snapping or gimbaling as you animate their rotations. This is often due to the limitations of traditional Euler angles and the infamous “gimbal lock”. Quaternions come to the rescue by encoding rotations in a way that avoids these issues, offering a more stable and efficient method to handle 3D orientations and angular displacements. More than just a mathematical curiosity, quaternions are a practical solution that preserves the sanity of game developers everywhere.

Why Should I Learn About Quaternions?

Quaternions may initially seem intimidating, but their usefulness in game development cannot be overstated. They:

– Allow for smooth interpolations (slerp) between rotations, which is vital for fluid animations.
– Reduce computational complexity compared to rotation matrices, leading to better performance.
– Avoid gimbal lock, ensuring that your game’s camera and character rotations are seamless and natural-looking.

By learning about quaternions, you expand your toolkit, enabling you to implement sophisticated rotation-related features with ease. As they are an integral part of Godot 4’s Quaternion class, understanding them lets you harness the full potential of the engine’s 3D capabilities. Let’s dive into the code and unlock the magic of quaternions!

CTA Small Image

Creating and Using Quaternions in Godot 4

Before delving into complex rotations, you must first understand how to create and use quaternions. Godot 4 provides a Quaternion class with intuitive methods to handle common tasks. Here are some essential examples of how to create and manipulate quaternions in your game:

var quat_identity = Quat()  # An identity quaternion, represents no rotation
var quat_from_euler = Quat(Vector3(1.5708, 0, 0))  # Create a quaternion from Euler angles (in radians)
var quat_from_axis_angle = Quat(Vector3(0, 1, 0), 1.5708)  # Create quaternion from an axis and angle (in radians)

The above code snippets showcase how to initialize a quaternion. By default, the identity quaternion (`Quat()`) has no effect on an object’s orientation. Creating quaternions from Euler angles or an axis with an angle is also straightforward.

Applying Quaternion Rotations to 3D Objects

Once you have a quaternion, you can apply it to 3D objects. Here’s how you can rotate a Spatial Node, such as a 3D model in your scene, using a quaternion:

# First, let's create a quaternion representing a 90 degree rotation around the y-axis
var quat_y_90 = Quat(Vector3(0, 1, 0), deg2rad(90))

func _ready():
    var my_3d_model = $My3DModel  # Assume My3DModel is a Spatial Node
    my_3d_model.rotation = quat_y_90.get_euler()

We created a quaternion to represent a 90-degree rotation around the Y-axis. In `_ready()`, we apply this quaternion’s rotation to `My3DModel` by converting the quaternion back to Euler angles with `.get_euler()`.

Combining Quaternions for Complex Rotations

Quaternions can be combined to create complex rotations. Here’s an example showing how to chain rotations:

# Let's say we want to rotate around the y-axis, then around the x-axis
var quat_y = Quat(Vector3(0, 1, 0), deg2rad(90))  # 90 degrees around y-axis
var quat_x = Quat(Vector3(1, 0, 0), deg2rad(45))  # 45 degrees around x-axis
var combined_quat = quat_y * quat_x  # Combine the rotations

And to apply this combined quaternion to a 3D object:

func apply_combined_rotation(node_path):
    var node = get_node(node_path) as Spatial
    if node:
        node.rotation = combined_quat.get_euler()

This function `apply_combined_rotation` takes a node path, finds the Spatial node, and sets its rotation to our combined quaternion after converting it to Euler angles.

Interpolating Between Quaternions

Interpolating between quaternions allows for smooth transitions. Here’s how to interpolate, or ‘slerp’, between two quaternions in Godot 4:

# Assume quat_start and quat_end are predefined quaternions representing start and end rotations
var t = 0.0  # Interpolation factor between 0.0 (start) and 1.0 (end)

func _process(delta):
    t += delta  # increase t by the frame-time to advance the interpolation
    var interpolated_quat = quat_start.slerp(quat_end, t)
    $My3DModel.rotation = interpolated_quat.get_euler()
    if t >= 1.0: t = 0  # Reset t to 0 to loop the interpolation

This snippet smoothly transitions a model’s rotation from `quat_start` to `quat_end`. The interpolation factor `t` is increased over time, creating a lerp animation that is visually appealing.

Through these examples, we’ve covered the creation, application, combination, and interpolation of quaternions in Godot 4. Become comfortable with these fundamentals, and you’ll unlock new dimensions of rotation manipulation for your 3D game development projects!Continuing to explore quaternions in Godot 4, let’s delve into some practical use-cases where these mathematical constructs excel. Quaternions are extremely useful not just in basic rotations, but also in dynamic scenarios such as orienting objects towards certain directions, creating complex animation sequences, and managing camera controls. Below are several code examples to demonstrate these advanced uses of quaternions.

Rotating an object to face a target is a common need in games. With quaternions, this can be done smoothly and efficiently, as shown in the following example:

# Assuming 'self' is the node that should orient towards 'target_position'
func look_at_smoothly(target_position, delta):
    var current_direction = global_transform.basis.z.normalized()
    var target_direction = (target_position - global_transform.origin).normalized()
    var dot = current_direction.dot(target_direction)
    # Check if the object is not already facing the target direction
    if dot < 0.9999:
        var angle = current_direction.angle_to(target_direction)
        var axis = current_direction.cross(target_direction).normalized()
        var rot_quat = Quat(axis, angle)
        var slerped_quat = global_transform.basis.get_quat().slerp(rot_quat, delta * 5.0)  # Use '5.0' as a speed factor
        global_transform.basis = Basis(slerped_quat)

This script smoothly orients an object towards `target_position` by calculating the cross product to get the rotation axis and using the angle between the current and target directions. `slerp` is used to gradually align the object’s forward direction with the target, providing a smooth rotation effect.

Another fascinating application of quaternions is in camera control systems, where quaternions preclude sudden flips when looking up and down or side to side:

# For a camera control system that avoids gimbal lock
func rotate_camera(x_rot_speed, y_rot_speed):
    var camera_rotation = $Camera.global_transform.basis.get_quat()
    var x_quat = Quat(Vector3(1, 0, 0), x_rot_speed)
    var y_quat = Quat(Vector3(0, 1, 0), y_rot_speed)
    camera_rotation = x_quat * camera_rotation * y_quat
    $Camera.global_transform.basis = Basis(camera_rotation)

To rotate a camera based on mouse movement, we apply horizontal (y-axis) and vertical (x-axis) rotations through quaternions, ensuring that no matter how we move the camera, it won’t experience gimbal lock.

Quaternions also facilitate more natural character movement. In the following example, we use quaternion-based rotation combined with lerping to make a character face the direction it’s moving:

# Assuming this is in a character controller script
var move_direction = Vector3()
var rotation_speed = 5.0

func _physics_process(delta):
    # 'move_direction' should be calculated based on player input
    if move_direction.length() > 0:
        var current_rot = global_transform.basis.get_quat()
        var target_rot = Quat(move_direction.normalized(), 0)
        var lerped_rot = current_rot.slerp(target_rot, rotation_speed * delta)
        global_transform.basis = Basis(lerped_rot)

Here `move_direction` is the vector where the character should move. By lerping the character’s current rotation towards the target direction, it turns smoothly as it starts walking in that direction.

For players to dynamically change the orientation of objects, such as to control the rotation of a turret or steering wheel, quaternions again prove their value:

# Example of dynamic object rotation based on user input
func rotate_object_based_on_input(input_vector, delta):
    var rotation_quat = Quat(input_vector, delta * 3.0)  # Assuming input_vector is a normalized Vector3, '3.0' is a speed factor
    self.global_transform.basis *= Basis(rotation_quat)

Providing `input_vector` based on user input determines the axis of rotation, and a speed factor scales the delta time to control the rotation speed.

Finally, let’s look at quaternion-based recoil animation for a first-person shooter game:

var recoil_quaternion = Quat()

func apply_recoil(recoil_amount):
    recoil_quaternion *= Quat(Vector3(-1, 0, 0), recoil_amount)  # Assuming recoil happens vertically

func _process(delta):
    if recoil_quaternion.length() > 0.01:
        $Gun.rotation = $Gun.rotation.slerp($Gun.rotation * recoil_quaternion, 10.0 * delta)  # Smooth out the recoil effect
        recoil_quaternion = recoil_quaternion.slerp(Quat(), 15.0 * delta)  # Recover from recoil
        recoil_quaternion = Quat()  # Reset quaternion when recoil is minimal

This snippet shows a simple recoil effect by tilting the gun upwards every time the player fires. The quaternion-based animation allows for a fluid recoil and recovery sequence.

Throughout these examples, we have tapped into the immense capability of quaternions to manage rotations across a variety of gameplay elements in Godot 4. With some practice and creativity, you’ll be capable of constructing a world of smooth and responsive movements in your 3D games.Quaternions not only play a key role in orientation and smooth transitions but are also indispensable for simulating physics and handling user interactions. In this next section, we’ll look at more advanced usage scenarios and provide practical code examples to demonstrate quaternion operations in Godot 4.

Simulating realistic object rotation in response to physics can give your game an edge in immersion. For instance, when simulating the effects of wind on an airplane or the way a space ship might maneuver through zero gravity, quaternions can model complex, non-linear rotations that would otherwise be challenging with Euler angles. Below is a simple example showing how a spaceship might rotate on its local axes in response to player controls:

# Spaceship control using quaternions and physics
func apply_spaceship_rotation(pitch: float, yaw: float, roll: float):
    var pitch_quat = Quat(transform.basis.x, pitch)
    var yaw_quat = Quat(transform.basis.y, yaw)
    var roll_quat = Quat(transform.basis.z, roll)
    transform.basis = transform.basis.rotated(pitch_quat).rotated(yaw_quat).rotated(roll_quat)

Quaternions also allow for reactive and dynamic object rotations, such as those needed in interactive environments. For example, when programming a door that opens as the player approaches, a quaternion can be used to rotate the door smoothly around its hinge:

# Reactive door opening mechanism
var open_rotation = Quat(Vector3(0, 1, 0), deg2rad(90))  # 90 degrees around the Y axis
var close_rotation = Quat()  # Identity quaternion for a closed door
var is_door_open = false

func toggle_door():
    if is_door_open:
        $Door.rotation = close_rotation.get_euler()
        $Door.rotation = open_rotation.get_euler()
    is_door_open = !is_door_open

For third-person games where the camera needs to follow the character from behind, quaternions provide an optimal solution to calculate the desired camera position and rotation, thereby ensuring a lag-free and smooth tracking of the player character:

# Third-person camera follow logic
var follow_distance = 4.0  # How far the camera should stay behind the character
var follow_height = 1.5  # The height offset from the character

func _process(delta):
    var target_pos = $Character.global_transform.origin + Vector3(0, follow_height, 0)
    var direction_to_character = (target_pos - $Camera.global_transform.origin).normalized()
    var desired_position = target_pos - direction_to_character * follow_distance
    $Camera.global_transform.origin = desired_position
    $Camera.look_at(target_pos, Vector3.UP)

Additionally, vehicle simulations in games benefit significantly from quaternion-based rotations. For example, when a car needs to respond to uneven terrain or tilt during sharp turns, quaternions can provide a realistic portrayal of the vehicle’s body orientation:

# Vehicle tilt during a turn based on steering input
var tilt_angle_max = deg2rad(15)  # Maximum tilt angle of the car
var steering_input = 0.0  # Should be updated based on user input (between -1 and 1)

func _process(delta):
    var current_tilt = transform.basis.to_quat()
    var desired_tilt = current_tilt * Quat(Vector3(0, 0, 1), steering_input * tilt_angle_max)
    transform.basis = Basis(desired_tilt)

Lastly, interactivity in puzzle games sometimes requires objects to rotate to specific orientations when the player interacts with them. Here’s how to achieve precision with quaternion operations:

# Rotating puzzle pieces to a specific orientation
var correct_orientation = Quat(Vector3(0, 0, -1), deg2rad(180))  # Assuming the correct orientation is 180-degrees flipped

func align_puzzle_piece(piece_path, delta):
    var piece = get_node(piece_path)
    var current_rot = piece.global_transform.basis.get_quat()
    piece.global_transform.basis = Basis(current_rot.slerp(correct_orientation, delta * 2.0))  # Smooth alignment

These advanced scenarios showcase the versatility of quaternions in Godot 4. They offer an elegant solution for creating responsive and lifelike rotations that contribute to a more dynamic and interactive gaming experience. As we continue to explore different facets of game development, quaternions remain a core component in setting the stage for realistic and immersive 3D environments.

Furthering Your Game Development Journey with Godot

Embarking on the journey of game development can be a challenging but rewarding experience. In the sea of knowledge and skills waiting to be explored, you’ve already shown your dedication by learning about quaternions in Godot 4. To take the next step in this exciting adventure, we encourage you to check out our Godot Game Development Mini-Degree. This program is designed to build on what you have learned and broaden your horizons, offering comprehensive courses covering everything from 2D and 3D asset creation to programming in GDScript.

Whether you’re just starting or looking to enhance your capabilities, our Mini-Degree has something for you. By completing real-world projects, you’ll not only gain valuable knowledge but also work towards building a portfolio that showcases your skills. This can be a game-changer for your career, opening doors to numerous opportunities in the ever-growing game development industry.

If you’re eager to expand your skills even further, delve into our broader collection of Godot courses. These will provide you with a solid understanding of various game development aspects and help you realize your potential as a game developer. Remember, the path to mastery is a persistent journey, and at Zenva, we are thrilled to be part of your learning adventure!


As we wrap up our exploration of quaternions in the Godot 4 game engine, remember that the skills you’ve learned here are just the beginning of what you can achieve. Having a solid grasp of quaternion rotations will undoubtedly set a foundation for you to create more immersive and interactive 3D games. To continue building upon this knowledge, and to truly elevate your game development skills, we invite you once again to join our Godot Game Development Mini-Degree. It’s the perfect next step for aspiring game creators like you, seeking to make a mark in the industry.

At Zenva, we pride ourselves on helping students reach their goals by providing the highest quality coding and game development education. Whether you’re working on your first project or gearing up to enter the professional realm, we’re here to support you every step of the way. So dive into our courses, challenge yourself with new projects, and above all, keep embracing the joy of creating something incredible. Your journey in game development is just getting started, and the possibilities are as limitless as your imagination!

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.