quaternion

From Teverse

Quaternions are based on complex numbers, so they're harder to understand than things such as Euler angles. We use quaternions for rotations as they allow for us to easily interpolate them, they're more efficient and don't experience gimbal lock.

Example: Rotating an Object

-- Create a 1x1x1 block
local block = engine.block("test")
block.size = vector3(1,1,1)
block.position = vector3(0,30,-10)

-- Create a 1 degree rotation on the Y Axis
-- quaternion() creates a new quaternion rotation
-- We are using setEuler to convert the Euler vector to the quaternion
-- (Because Euler is easy for us to understand!)
local rotation = quaternion():setEuler( vector3(0, math.rad(1), 0) )

while true do
	-- This essentially adds the 1 degree rotation to the block's current rotation.
	-- Note the multiplication rather than addition.
	block.rotation = block.rotation * rotation
	wait()
end

Example: Looking at an Object

-- Create two 1x1x1 blocks
local block = engine.block("watcher")
block.size = vector3(1, 1, 1)
block.position = vector3(0, 30, -10)

local target = engine.block("target")
target.size = vector3(1, 1, 1)
target.position = vector3(0, 30, 10)

-- Start a loop
while true do
	-- Move the block that we're watching by a little
	target.position = target.position - vector3(0, 0.1, 0.1)
	
	-- Calculate the direction to the target
	local dir = target.position - block.position
	
	-- Create a new rotation that looks towards the dir
	local rot = block.rotation:setLookRotation(dir)
	
	-- Set the block's rotation
	block.rotation = rot
	
	wait()
end

Example: Getting lookVector

-- This code would get the lookVector and upVector of a block.
local forward = block.rotation * vector3(0,0,1)
local upwards = block.rotation * vector3(0,1,0)

Constructors

quaternion

quaternion quaternion(number x, number y, number z, number w)

Properties

x

Type: number

y

Type: number

z

Type: number

w

Type: number

Operators

quaternion * quaternion

quaternion * vector3

Methods

lerp

quaternion quaternion:lerp(quaternion target, number t)
returns an interpolated copy of the quaternion.
t is clamped between 0 and 1. If t is 0, the returned quaternion will be unchanged. If t is 1, the returned quaternion will be target

.

slerp

quaternion quaternion:slerp(quaternion target, number t)
returns an interpolated copy of the quaternion.
t is not clamped on this function

.

dot

number quaternion:dot(quaternion other)

angle

number quaternion:angle(quaternion other)

normal

quaternion quaternion:normal()
Returns a normalized copy of the quaternion.

inverse

quaternion quaternion:inverse()
Returns an inversed copy of the quaternion.

rotateTowards

quaternion quaternion:rotateTowards(quaternion to, number maxDegreesDelta)
Returns a copy of the quaternion that is rotated towards to.

getAngleAxis

number angle, vector3 axis quaternion:getAngleAxis()

setAngleAxis

quaternion quaternion:setAngleAxis(number angle, vector3 axis)
Creates a rotation which rotates angle degrees around axis and sets the current quaternion.

getEuler

vector3 quaternion:getEuler()
Converts the quaternion into Euler angles.

setEuler

quaternion quaternion:setEuler(vector3 euler)

setFromToRotation

quaternion quaternion:setFromToRotation(vector3 fromDirection, vector3 toDirection)
Sets the quaternion to one that rotates from fromDirection to toDirection.

setLookRotation

quaternion quaternion:setLookRotation(vector3 forward, vector3 upwards)
Sets the quaternion with the specified forward and upwards directions. By default, upwards is (0,1,0).