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¶

class Quaternion¶

module:

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:

new quaternion

Return type:

Quaternion

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 the quaternion

Returns:

the clone

Return type:

Quaternion

get()¶

Return the components as array

Returns:

the components

Return type:

number or number or number or number

toData()¶

Returns the components as table

Returns:

the components

Return type:

table

static dot()¶

Calculates dot product of quaternion

Returns:

dot product

Return type:

number

static angle(a, b)¶

Calculates ange between 2 quaternions

Parameters:

• a (Quaternion) – first quaternion

• b (Quaternion) – second quaternion

Returns:

angle in degrees

Return type:

number

static fromAngleAxis(angle, axis)¶

Creates a new quaternion from angle and axis

Parameters:

• angle (number) – angle in degrees

• axis (Vector3) – axis vector

Returns:

new quaternion

Return type:

Quaternion

equals(a, b)¶

Checks if two quaternions are equal

Parameters:

• a (Quaternion) – first quaternion

• b (Quaternion) – second quaternion

Returns:

the comparison result

Return type:

boolean

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:

new quaternion

Return type:

Quaternion

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()¶

Return normalized version of quaternion

Returns:

normalized quaternion

Return type:

Quaternion

normalize()¶

Normalize quaternion

Returns:

returns itself

Return type:

Quaternion

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:

A quaternion that rotates from to align with to

Return type:

Quaternion

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:

this quaternion, updated in place

Return type:

Quaternion

inverse()¶

Calculate inverse of this quaternion

Returns:

inverse quaternion

Return type:

Quaternion

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:

new interpolated quaternion

Return type:

Quaternion

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:

calculated rotation

Return type:

Quaternion

setIdentity()¶

Set identity quaternion

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:

new interpolated quaternion

Return type:

Quaternion

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:

result quaternion

Return type:

Quaternion

toAngleAxis()¶

Convert quaternion to angle and axis

Returns:

array of angle in degrees as number and axis as Vector3

Return type:

table

toEulerAngles()¶

Convert to euler angles

Returns:

the euler angles as Vector3

Return type:

Vector3

forward()¶

Multiply with forward vector3 0/0/1

Returns:

returns the new vector

Return type:

Vector3

mulVec3(point)¶

Multiply Quaternion with Vector3

Parameters:

point (Vector3) – the vector to multiply with

Returns:

the result vector

Return type:

Vector3