# quaternion

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)`

Type: number

Type: number

Type: number

Type: number

## 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).