Quaternion

The Quaternion class represents a 4-dimensional quaternion used primarily for efficient and smooth rotation operations in 3D space. Quaternions are typically utilized in game development and 3D graphics applications to handle complex rotations without encountering issues like gimbal lock.

Usage

To use this class, add the following require at the top of your script:

local Quaternion = require 'engine/math/quaternion'

Reference

Operators

*

*(Quaternion lhs, Vector3 rhs): Vector3

Rotate a Vector3 by this Quaternion

-

-(): Quaternion

Negation (inverse orientation)

==

==(Quaternion lhs, Quaternion rhs): boolean

Approximate equality (dot > 0.999999)

new

static new(x, y, z, w)

Create new Quaternion

Parameters

• x (number): x component
• y (number): y component
• z (number): z component
• w (number): w component

Returns

• Quaternion: quaternion

set

set(x, y, z, w)

Set components of the quaternion

Parameters

• x (number): x component
• y (number): y component
• z (number): z component
• w (number): w component

clone

clone()

Clone the quaternion

Returns

• Quaternion: clone

get

get()

Return the components as array

Returns

• number: The X component
• number: The Y component
• number: The Z component
• number: The W component

toData

toData()

Returns the components as table

Returns

• table: components

dot

static dot(a, b)

Calculates dot product of quaternion

Parameters

• a
• b

Returns

• number: product

angle

static angle(a, b)

Calculates ange between 2 quaternions

Parameters

• a (Quaternion): first quaternion
• b (Quaternion): second quaternion

Returns

• number: in degrees

fromAngleAxis

static fromAngleAxis(angle, axis)

Creates a new quaternion from angle and axis

Parameters

• angle (number): angle in degrees
• axis (Vector3): axis vector

Returns

• Quaternion: quaternion

equals

equals(b)

Checks if two quaternions are equal

Parameters

• b (Quaternion): second quaternion

Returns

• boolean: comparison result

fromEuler

static fromEuler(x, y, z)

Creates new quaternion from euler angles

Parameters

• x (number): x axis rotation in degrees
• y (number): y axis rotation in degrees
• z (number): z axis rotation in degrees

Returns

• Quaternion: quaternion

setFromEuler

setFromEuler(x, y, z)

Set quaternion values based on euler angles

Parameters

• x (number): x axis rotation in degrees
• y (number): y axis rotation in degrees
• z (number): z axis rotation in degrees

normalized

normalized()

Return normalized version of quaternion

Returns

• Quaternion: quaternion

normalize

normalize()

Normalize quaternion

Returns

• Quaternion: itself

fromToRotation

static fromToRotation(from, to)

Returns a quaternion representing the rotation from one vector to another.

Parameters

• from (Vector3): The starting direction vector
• to (Vector3): The target direction vector

Returns

• Quaternion: quaternion that rotates from to align with to

setFromToRotation

setFromToRotation(from, to)

Sets this quaternion to represent the rotation from one vector to another

Parameters

• from (Vector3): starting direction
• to (Vector3): target direction

Returns

• Quaternion: quaternion, updated in place

inverse

inverse()

Calculate inverse of this quaternion

Returns

• Quaternion: quaternion

lerp

static lerp(q1, q2, t)

Linear interpolation from one quaternion to another one

Parameters

• q1 (Quaternion): first quaternion
• q2 (Quaternion): second quaternion
• t (number): position between 0 and 1 where to interpolate

Returns

• Quaternion: interpolated quaternion

lookRotation

static lookRotation(forward, up)

Create a quaternion to look at a target direction

Parameters

• forward (Vector3): direction to look at
• up (Vector3): up direction

Returns

• Quaternion: rotation

setIdentity

setIdentity()

Set identity quaternion

slerp

static slerp(from, to, t)

Spherical linear interpolation from one quaternion to another one

Parameters

• from (Quaternion): first quaternion
• to (Quaternion): second quaternion
• t (number): position between 0 and 1 where to interpolate

Returns

• Quaternion: interpolated quaternion

rotateTowards

static rotateTowards(from, to, maxDegreesDelta)

Rotate the source quaternion towards the destination quaternion but only to a maximum degree

Parameters

• from (Quaternion): source quaternion
• to (Quaternion): destination quaternion
• maxDegreesDelta (number): maximim degrees to rotate.

Returns

• Quaternion: quaternion

toAngleAxis

toAngleAxis()

Convert quaternion to angle and axis

Returns

• table: of angle in degrees as number and axis as Vector3

toEulerAngles

toEulerAngles()

Convert to euler angles

Returns

• Vector3: euler angles as Vector3

forward

forward()

Multiply with forward vector3 0/0/1

Returns

• Vector3: the new vector

mulVec3

mulVec3(point)

Multiply Quaternion with Vector3

Parameters

• point (Vector3): the vector to multiply with

Returns

• Vector3: result vector