• API

Datatypes

# Quaternion

A Quaternion represents rotation and direction in 3D space, consisting of x, y, z, and w components. They are crucial for 3D movement and rotation, offering advantages such as avoiding gimbal lock.

## Properties

Returns the rotation of a Quaternion in Euler angles representation. Usually used for debugging and visualizing rotations.

``````local quaternion = Quaternion.new(0, 0, 0, 1)
local euler = quaternion.eulerAngles

print(euler) -- (0, 0, 0)
``````

Returns a normalized copy of the Quaternion. Useful for ensuring the Quaternion has a magnitude of 1.

``````local quaternion = Quaternion.new(0, 0, 0, 1)
local normalized = quaternion.normalized

print(normalized) -- (0, 0, 0, 1)
``````

Represents the x component of the Quaternion. It is the imaginary part of the Quaternion.

``````local quaternion = Quaternion.new(0, 0, 0, 1)
print(quaternion.x) -- 0
``````

Represents the y component of the Quaternion. It is the imaginary part of the Quaternion.

``````local quaternion = Quaternion.new(0, 0, 0, 1)
print(quaternion.y) -- 0
``````

Represents the z component of the Quaternion.

``````local quaternion = Quaternion.new(0, 0, 0, 1)
print(quaternion.z) -- 0
``````

Represents the w (scalar) component of the Quaternion.

``````local quaternion = Quaternion.new(0, 0, 0, 1)
print(quaternion.w) -- 1
``````

Represents a Quaternion for no rotation.

Represents a small number greater than zero for comparison.

``````local epsilon = Quaternion.kEpsilon
print(epsilon) -- 1e-6
``````

## Methods

Checks if two Quaternions or objects are equal.

``````local a = Quaternion.new(0, 0, 0, 1)
local b = Quaternion.new(0, 0, 0, 1)

local equal = a:Equals(b)
print(equal) -- true
``````

#### Parameters

##### other
Quaternion

The Quaternion to compare with.

#### Returns

boolean

Returns true if the Quaternions are equal.

Assigns new values to the Quaternion's components.

``````local quaternion = Quaternion.new(0, 0, 0, 1)
quaternion:Set(1, 1, 1, 1)
``````

#### Parameters

##### newX

number

The new x component.

##### newY

number

The new y component.

##### newZ

number

The new z component.

##### newW

number

The new w component.

#### Returns

void

Aligns the Quaternion's z-axis towards a target direction.

``````local quaternion = Quaternion.new(0, 0, 0, 1)
local target = Vector3.new(0, 0, 1)

quaternion:SetLookRotation(target)
``````

#### Parameters

##### view
Vector3

The target direction vector.

#### Returns

void

Sets the Quaternion to rotate from one direction to another.

``````local quaternion = Quaternion.new(0, 0, 0, 1)
local from = Vector3.new(0, 0, 0)
local to = Vector3.new(0, 0, 1)

quaternion:SetFromToRotation(from, to)
``````

#### Parameters

##### fromDirection
Vector3

The vector to rotate from.

##### toDirection
Vector3

The vector to rotate to.

#### Returns

void

Modifies the quaternion to a unit length version of itself.

``````local quaternion = Quaternion.new(0, 0, 0, 1)
quaternion:Normalize()
``````

#### Returns

void

Creates a Quaternion that rotates from one direction to another.

``````local from = Vector3.new(0, 0, 0)
local to = Vector3.new(0, 0, 1)

local quaternion = Quaternion.FromToRotation(from, to)
``````

#### Parameters

##### fromDirection
Vector3

The vector to rotate from.

##### toDirection
Vector3

The vector to rotate to.

#### Returns

Quaternion

A rotation from fromDirection to toDirection.

Returns the inverse of the Quaternion.

``````local quaternion = Quaternion.new(0, 0, 0, 1)
local inverse = Quaternion.Inverse(quaternion)
``````

#### Parameters

##### rotation
Quaternion

The rotation to inverse.

#### Returns

Quaternion

The inverse rotation.

Gradually changes a Quaternion from one rotation to another.

``````local a = Quaternion.new(0, 0, 0, 1)
local b = Quaternion.new(0, 0, 1, 0)
local t = 0.5

local slerp = Quaternion.Slerp(a, b, t)
``````

#### Parameters

##### a
Quaternion

The starting rotation.

##### b
Quaternion

The end rotation.

##### t

number

The amount to interpolate.

#### Returns

Quaternion

An interpolated quaternion rotation.

Interpolates a Quaternion over an arbitrary range.

``````local a = Quaternion.new(0, 0, 0, 1)
local b = Quaternion.new(0, 0, 1, 0)
local t = 0.5

local slerp = Quaternion.SlerpUnclamped(a, b, t)
``````

#### Parameters

##### a
Quaternion

The starting rotation.

##### b
Quaternion

The end rotation.

##### t

number

The unclamped interpolation amount.

#### Returns

Quaternion

An interpolated quaternion rotation.

Linearly interpolates between two quaternions.

``````local a = Quaternion.new(0, 0, 0, 1)
local b = Quaternion.new(0, 0, 1, 0)
local t = 0.5

local lerp = Quaternion.Lerp(a, b, t)
``````

#### Parameters

##### a
Quaternion

The starting rotation.

##### b
Quaternion

The end rotation.

##### t

number

The amount to interpolate.

#### Returns

Quaternion

An interpolated quaternion rotation.

The 'LerpUnclamped' method is similar to Lerp, but here the interpolation factor isn't clamped to the range [0, 1].

``````local a = Quaternion.new(0, 0, 0, 1)
local b = Quaternion.new(0, 0, 1, 0)
local t = 0.5

local lerp = Quaternion.LerpUnclamped(a, b, t)
``````

#### Parameters

##### a
Quaternion

The starting rotation.

##### b
Quaternion

The end rotation.

##### t

number

The unclamped interpolation amount.

#### Returns

Quaternion

Returns a Quaternion that is interpolated over an arbitrary range.

Creates a Quaternion rotation around an axis by a specified angle.

``````local angle = 90
local axis = Vector3.new(0, 1, 0)

local quaternion = Quaternion.AngleAxis(angle, axis)
``````

#### Parameters

##### angle

number

The angle of rotation.

##### axis
Vector3

The rotation axis.

#### Returns

Quaternion

A Quaternion around the specified axis with the given angle.

Provides a quaternion that makes an object face towards a specified direction.

``````local forward = Vector3.new(0, 0, 1)
local upwards = Vector3.new(0, 1, 0)

local quaternion = Quaternion.LookRotation(forward, upwards)
``````

#### Parameters

##### forward
Vector3

The direction to be faced.

##### upwards
Vector3

The direction to be used as 'upwards'.

#### Returns

Quaternion

A Quaternion that aligns an object's forward direction towards the specified direction.

Multiplies two Quaternions together.

``````local a = Quaternion.new(0, 0, 0, 1)
local b = Quaternion.new(0, 0, 1, 0)

local multiplied = Quaternion.Multiply(a, b)
print(multiplied) -- (0, 0, 0, -1)
``````

#### Parameters

##### a
Quaternion

The first Quaternion.

##### b
Quaternion

The second Quaternion.

#### Returns

Quaternion

The product of the two Quaternions.

Calculates the dot product of two quaternions.

``````local a = Quaternion.new(0, 0, 0, 1)
local b = Quaternion.new(0, 0, 1, 0)

local dot = Quaternion.Dot(a, b)
``````

#### Parameters

##### a
Quaternion

The first quaternion.

##### b
Quaternion

The second quaternion.

#### Returns

number

The dot product of the two quaternions.

Returns the angle in degrees between two rotations.

``````local a = Quaternion.new(0, 0, 0, 1)
local b = Quaternion.new(0, 0, 1, 0)

local angle = Quaternion.Angle(a, b)
``````

#### Parameters

##### a
Quaternion

The first rotation.

##### b
Quaternion

The second rotation.

#### Returns

number

The angle in degrees between the two rotations.

Creates a Quaternion rotation from Euler angles.

``````local x = 0
local y = 0
local z = 0

local quaternion = Quaternion.Euler(x, y, z)
``````

#### Parameters

##### x

number

The angle around the x-axis in degrees.

##### y

number

The angle around the y-axis in degrees.

##### z

number

The angle around the z-axis in degrees.

#### Returns

Quaternion

A Quaternion from the Euler angles.

Gradually changes a Quaternion towards a target rotation.

``````local from = Quaternion.new(0, 0, 0, 1)
local to = Quaternion.new(0, 0, 1, 0)
local maxDegreesDelta = 0.5

local rotated = Quaternion.RotateTowards(from, to, maxDegreesDelta)
``````

#### Parameters

##### from
Quaternion

The current rotation.

##### to
Quaternion

The target rotation.

##### maxDegreesDelta

number

The maximum number of degrees to rotate by in each call.

#### Returns

Quaternion

A Quaternion rotated towards the target.

Modifies the quaternion to a unit length version of itself.

``````local quaternion = Quaternion.new(0, 0, 0, 1)
local normalized = Quaternion.Normalize(quaternion)
``````

#### Parameters

##### q
Quaternion

The Quaternion to be normalized.

#### Returns

Quaternion

The normalized version of the quaternion.