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