Skip to content
API

Quaternion

A quaternion-based representation of a rotation.

Constructors

Constructor Name Return Type Description Tags
Quaternion.New([number x, number y, number z, number w]) Quaternion Constructs a Quaternion with the given values. Defaults to 0, 0, 0, 1. None
Quaternion.New(Rotation r) Quaternion Constructs a Quaternion with the given Rotation. None
Quaternion.New(Vector3 axis, number angle) Quaternion Constructs a Quaternion representing a rotation of angle degrees around the axis of the Vector3. None
Quaternion.New(Vector3 from, Vector3 to) Quaternion Constructs a Quaternion between the from and to of the Vector3s. None
Quaternion.New(Quaternion q) Quaternion Copies the given Quaternion. None

Constants

Constant Name Return Type Description Tags
Quaternion.IDENTITY Quaternion Predefined Quaternion with no rotation. None

Properties

Property Name Return Type Description Tags
x number The x component of the Quaternion. Read-Write
y number The y component of the Quaternion. Read-Write
z number The z component of the Quaternion. Read-Write
w number The w component of the Quaternion. Read-Write

Functions

Function Name Return Type Description Tags
GetRotation() Rotation Get the Rotation representation of the Quaternion. None
GetForwardVector() Vector3 Forward unit vector rotated by the quaternion. None
GetRightVector() Vector3 Right unit vector rotated by the quaternion. None
GetUpVector() Vector3 Up unit vector rotated by the quaternion. None

Class Functions

Class Function Name Return Type Description Tags
Quaternion.Slerp(Quaternion from, Quaternion to, number progress) Quaternion Spherical interpolation between two quaternions by the specified progress amount and returns the resultant, normalized Quaternion. None

Operators

Operator Name Return Type Description Tags
Quaternion + Quaternion Quaternion Component-wise addition. None
Quaternion - Quaternion Quaternion Component-wise subtraction. None
Quaternion * Quaternion Quaternion Compose two quaternions, with the result applying the right rotation first, then the left rotation second. None
Quaternion * number Quaternion Multiplies each component by the right-side number. None
Quaternion * Vector3 Vector3 Rotates the right-side vector and returns the result. None
Quaternion / number Quaternion Divides each component by the right-side number. None
-Quaternion Quaternion Returns the inverse rotation. None

Examples

Example using:

Slerp

GetRotation

GetRightVector

GetUpVector

GetForwardVector

Quaternion.Slerp is a function for finding a quaternion that is part way between two other quaternions. Since quaternions represent rotations, this means a rotation that is part way between two other rotations. When combined with a tick function or loop, we can use it to smoothly animate something rotating.

Quaternion.GetRotation is useful if you need to convert a quaternion into a rotation variable. (For passing to functions like CoreObject:SetWorldRotation() for example.)

We can also access various unit vectors, as transformed by the quaternion, via Quaternion:GetForwardVector, Quaternion:GetRightVector, andQuaternion:GetUpVector.

local propCubeTemplate = script:GetCustomProperty("CubeTemplate")
local myObject = World.SpawnAsset(propCubeTemplate,
    { position = Vector3.New(500, 0, 500)})

local startQuat = Quaternion.IDENTITY
local endQuat = Quaternion.New(Vector3.UP, 120)

local steps = 300
local objectPos = myObject:GetWorldPosition()
for i = 1, steps do
    -- Rotate this quaternion over time
    local currentQuat = Quaternion.Slerp(startQuat, endQuat, i/steps)
    myObject:SetWorldRotation(currentQuat:GetRotation())

    CoreDebug.DrawLine(objectPos, objectPos + currentQuat:GetForwardVector() * 1000,
        { thickness = 5, color = Color.RED })
    CoreDebug.DrawLine(objectPos, objectPos + currentQuat:GetRightVector() * 1000,
        { thickness = 5, color = Color.GREEN })
    CoreDebug.DrawLine(objectPos, objectPos + currentQuat:GetUpVector() * 1000,
        { thickness = 5, color = Color.BLUE })

    Task.Wait()
end

print("Tah dah!")

See also: Quaternion.New | CoreObject.GetCustomProperty | World.SpawnAsset | CoreDebug.DrawLine | Vector3.New | Color.RED | Task.Wait | CoreLua.print


Example using:

New

IDENTITY

There are several different ways to create new Quaternions.

local sqrt2over2 = math.sqrt(2) / 2

-- Makes an identity Quaternion. (Rotates by 0 degrees.)
local identityQuat = Quaternion.New()

-- You can also access the identity quaternion via the static property:
local otherIdentityQuat = Quaternion.IDENTITY

-- Creates a quaternion from a rotation.
local rotationQuaternion = Quaternion.New(Rotation.New(Vector3.RIGHT, Vector3.UP))

-- Creates a quaternion from an axis and an angle.
local axisQuaternion = Quaternion.New(Vector3.UP, 90)

-- Creates a quaternion that rotates from one vector to another.
local fromToQuaternion = Quaternion.New(Vector3.FORWARD, Vector3.RIGHT)

-- Creates a quaternion that is a copy of an existing quaternion.
local copyQuaternion = Quaternion.New(rotationQuaternion)

-- You can also create a quaternion by directly assigning x, y, z, w values,
-- but this is not recommended unless you are VERY sure you understand
-- how quaternions represent rotations.
-- This rotation is identical to rotationQuaternion, above - 90 degrees around the z axis.
local directQuaternion = Quaternion.New(0, 0, sqrt2over2, sqrt2over2)

See also: Rotation.New | Vector3.RIGHT


Example using:

Quaternion*Quaternion

Quaternion*Vector3

-Quaternion

Multiplying a vector (or another quaternion!) by a quaternion applies the quaternion to the vector/quaternion.

-- Multiplying two components will produce a quaternion that is the composite result.
local rotate90Degrees = Quaternion.New(Vector3.UP, 90)
local rotate180Degrees = rotate90Degrees * rotate90Degrees
local rotate360Degrees =  rotate180Degrees * rotate90Degrees * rotate90Degrees

-- Multiplying a vector by a quaternion will produce a vector that has been rotated by the quaternion.
local rotatedVector = rotate90Degrees * Vector3.FORWARD
-- rotatedVector is now equal to Vector3.RIGHT, because it has been rotated 90 degrees

-- You can also invert a quaternian using the minus-sign. Note that this is NOT the same
-- as inverting the components. This produces a reversed rotation instead.
-- This example rotates a vector by 90 degrees, and then back, leaving it unchanged.
local forwardVector = rotate90Degrees * -rotate90Degrees * Vector3.FORWARD

See also: Quaternion.New | Vector3.UP


Example using:

x

y

z

w

You can read or set the components of a quaternion directly, although this is not recommended unless you are extremely familiar with quaternions.

local myQuaternion = Quaternion.New()
myQuaternion.x = 0
myQuaternion.y = 0
myQuaternion.z = math.sqrt(2)/2
myQuaternion.w = math.sqrt(2)/2
-- myQuaternion is now a 90 degree rotation about the Z axis!

See also: Quaternion.New



Last update: March 1, 2021