Class Quat

A quaternion representing rotation in 3D space. Quaternions are typically used to represent rotations in 3D applications, offering advantages over Euler angles including no gimbal lock and more efficient interpolation.

A new Quat is the identity rotation. Build a rotation with setFromEulerAngles, setFromAxisAngle, setFromDirections or setFromMat4, and read one back with getEulerAngles or getAxisAngle. Angles are in degrees throughout. Rotations combine by multiplication: a.mul(b) and r.mul2(a, b) both compute a * b, the same product Mat4 uses, and transformVector applies a rotation to a Vec3. Interpolate with slerp for constant angular speed, or with the cheaper lerp when the two rotations are close together.

Methods modify the quaternion they are called on and return it for chaining. Use clone for an independent copy and copy to overwrite. The static constants IDENTITY and ZERO are frozen shared instances, and the quaternion returned by GraphNode#getRotation is internal storage to be treated as read-only.

Example

// Rotate an entity 90 degrees about the world Y axis
const rotation = new Quat().setFromAxisAngle(Vec3.UP, 90);
entity.setRotation(rotation);

Example

// Turn smoothly towards a target orientation each frame
const smoothed = new Quat().slerp(entity.getRotation(), targetRotation, 0.1);
entity.setRotation(smoothed);

Index

Constructors

constructor

Properties

w x y z IDENTITY ZERO

Constructors

constructor

new Quat(x?: number, y?: number, z?: number, w?: number): Quat
Creates a new Quat instance.
Parameters
- Optionalx: number
  The x value. Defaults to 0.
- Optionaly: number
  The y value. Defaults to 0.
- Optionalz: number
  The z value. Defaults to 0.
- Optionalw: number
  The w value. Defaults to 1.
Returns Quat
Example
```
const q1 = new Quat(); // defaults to 0, 0, 0, 1
const q2 = new Quat(1, 2, 3, 4);
```
- Defined in core/math/quat.js:68
new Quat(arr: number[]): Quat
Creates a new Quat instance.
Parameters
- arr: number[]
  The array to set the quaternion values from.
Returns Quat
Example
```
const q = new Quat([1, 2, 3, 4]);
```
- Defined in core/math/quat.js:68

Properties

w

w: number

The w component of the quaternion.

x

x: number

The x component of the quaternion.

y

y: number

The y component of the quaternion.

z

z: number

The z component of the quaternion.

`Static` `Readonly`IDENTITY

IDENTITY: Quat = ...

A constant quaternion set to [0, 0, 0, 1] (the identity). Represents no rotation.

`Static` `Readonly`ZERO

ZERO: Quat = ...

A constant quaternion set to [0, 0, 0, 0].

Methods

clone

clone(): Quat
Returns an identical copy of the specified quaternion.

Returns Quat
A new quaternion identical to this one.
Example
```
const q = new Quat(-0.11, -0.15, -0.46, 0.87);
const qclone = q.clone();

console.log("The result of the cloning is: " + qclone.toString());
```
- Defined in core/math/quat.js:116

copy

copy(rhs: Quat): Quat
Copies the contents of a source quaternion to a destination quaternion.
Parameters
- rhs: Quat
  The quaternion to be copied.
Returns Quat
Self for chaining.
Example
```
const src = new Quat();
const dst = new Quat();
dst.copy(src);
console.log("The two quaternions are " + (src.equals(dst) ? "equal" : "different"));
```
- Defined in core/math/quat.js:153

dot

dot(other: Quat): number
Calculates the dot product of two quaternions.
Parameters
- other: Quat
  The quaternion to calculate the dot product with.
Returns number
The dot product of the two quaternions.
Example
```
const a = new Quat(1, 0, 0, 0);
const b = new Quat(0, 1, 0, 0);
console.log("Dot product: " + a.dot(b)); // Outputs 0
```
- Defined in core/math/quat.js:172

equals

equals(rhs: Quat): boolean
Reports whether two quaternions are equal.
Parameters
- rhs: Quat
  The quaternion to be compared against.
Returns boolean
True if the quaternions are equal and false otherwise.
Example
```
const a = new Quat();
const b = new Quat();
console.log("The two quaternions are " + (a.equals(b) ? "equal" : "different"));
```
- Defined in core/math/quat.js:186

equalsApprox

equalsApprox(rhs: Quat, epsilon?: number): boolean
Reports whether two quaternions are equal using an absolute error tolerance.
Parameters
- rhs: Quat
  The quaternion to be compared against.
- Optionalepsilon: number = 1e-6
  The maximum difference between each component of the two quaternions. Defaults to 1e-6.
Returns boolean
True if the quaternions are equal and false otherwise.
Example
```
const a = new Quat();
const b = new Quat();
console.log("The two quaternions are approximately " + (a.equalsApprox(b, 1e-9) ? "equal" : "different"));
```
- Defined in core/math/quat.js:202

fromArray

fromArray(
arr: number[] | ArrayBufferView<ArrayBufferLike>,
offset?: number,
): Quat
Set the values of the quaternion from an array.
Parameters
- arr: number[] | ArrayBufferView<ArrayBufferLike>
  The array to set the quaternion values from.
- Optionaloffset: number = 0
  The zero-based index at which to start copying elements from the array. Default is 0.
Returns Quat
Self for chaining.
Example
```
const q = new Quat();
q.fromArray([20, 10, 5, 0]);
// q is set to [20, 10, 5, 0]
```
- Defined in core/math/quat.js:826

getAxisAngle

getAxisAngle(axis: Vec3): number
Gets the rotation axis and angle for a given quaternion. If a quaternion is created with setFromAxisAngle, this method will return the same values as provided in the original parameter list OR functionally equivalent values.
Parameters
- axis: Vec3
  The 3-dimensional vector to receive the axis of rotation.
Returns number
Angle, in degrees, of the rotation.
Example
```
const q = new Quat();
q.setFromAxisAngle(new Vec3(0, 1, 0), 90);
const v = new Vec3();
const angle = q.getAxisAngle(v);
// Outputs 90
console.log(angle);
// Outputs [0, 1, 0]
console.log(v.toString());
```
- Defined in core/math/quat.js:226

getEulerAngles

getEulerAngles(eulers?: Vec3): Vec3
Converts this quaternion to Euler angles, specified in degrees. The decomposition uses an intrinsic XYZ order, representing the angles required to achieve the quaternion's orientation by rotating sequentially: first around the X-axis, then around the newly transformed Y-axis, and finally around the resulting Z-axis.
Parameters
- Optionaleulers: Vec3 = ...
  An optional 3-dimensional vector to receive the calculated Euler angles (output parameter). If not provided, a new Vec3 object will be allocated and returned.
Returns Vec3
The 3-dimensional vector holding the Euler angles in degrees. This will be the same object passed in as the eulers parameter (if one was provided).
Example
```
const q = new Quat();
q.setFromAxisAngle(Vec3.UP, 90);
const e = new Vec3();
q.getEulerAngles(e);
// Outputs [0, 90, 0]
console.log(e.toString());
```
- Defined in core/math/quat.js:268

invert

invert(src?: Quat): Quat
Generates the inverse of the specified quaternion.
Parameters
- Optionalsrc: Quat = ...
  The quaternion to invert. If not set, the operation is done in place.
Returns Quat
Self for chaining.
Example
```
// Create a quaternion rotated 180 degrees around the y-axis
const rot = new Quat().setFromEulerAngles(0, 180, 0);

// Invert in place
rot.invert();
```
- Defined in core/math/quat.js:307

length

length(): number
Returns the magnitude of the specified quaternion.

Returns number
The magnitude of the specified quaternion.
Example
```
const q = new Quat(0, 0, 0, 5);
const len = q.length();
// Outputs 5
console.log("The length of the quaternion is: " + len);
```
- Defined in core/math/quat.js:321

lengthSq

lengthSq(): number
Returns the magnitude squared of the specified quaternion.

Returns number
The magnitude squared of the quaternion.
Example
```
const q = new Quat(3, 4, 0, 0);
const lenSq = q.lengthSq();
// Outputs 25
console.log("The length squared of the quaternion is: " + lenSq);
```
- Defined in core/math/quat.js:335

lerp

lerp(lhs: Quat, rhs: Quat, alpha: number): Quat
Performs a linear interpolation between two quaternions. The result of the interpolation is written to the quaternion calling the function.
Parameters
- lhs: Quat
  The quaternion to interpolate from.
- rhs: Quat
  The quaternion to interpolate to.
- alpha: number
  The unclamped interpolation factor. Values between 0 and 1 interpolate between lhs and rhs; values outside this range extrapolate beyond them.
Returns Quat
Self for chaining.
Example
```
const q1 = new Quat(-0.11, -0.15, -0.46, 0.87);
const q2 = new Quat(-0.21, -0.21, -0.67, 0.68);

const result = new Quat();
result.lerp(q1, q2, 0);   // Return q1
result.lerp(q1, q2, 0.5); // Return the midpoint interpolant
result.lerp(q1, q2, 1);   // Return q2
```
- Defined in core/math/quat.js:358

mul

mul(rhs: Quat): Quat

Returns the result of multiplying the specified quaternions together.

Parameters

rhs: Quat
The quaternion used as the second multiplicand of the operation.

Returns Quat

Self for chaining.

Example

const a = new Quat().setFromEulerAngles(0, 30, 0);
const b = new Quat().setFromEulerAngles(0, 60, 0);

// a becomes a 90 degree rotation around the Y axis
// In other words, a = a * b
a.mul(b);

console.log("The result of the multiplication is: " + a.toString());

mul2

mul2(lhs: Quat, rhs: Quat): Quat
Returns the result of multiplying the specified quaternions together.
Parameters
- lhs: Quat
  The quaternion used as the first multiplicand of the operation.
- rhs: Quat
  The quaternion used as the second multiplicand of the operation.
Returns Quat
Self for chaining.
Example
```
const a = new Quat().setFromEulerAngles(0, 30, 0);
const b = new Quat().setFromEulerAngles(0, 60, 0);
const r = new Quat();

// r is set to a 90 degree rotation around the Y axis
// In other words, r = a * b
r.mul2(a, b);
```
- Defined in core/math/quat.js:435

mulScalar

mulScalar(scalar: number, src?: Quat): Quat
Multiplies each element of a quaternion by a number.
Parameters
- scalar: number
  The number to multiply by.
- Optionalsrc: Quat = ...
  The quaternion to scale. If not set, the operation is done in place.
Returns Quat
Self for chaining.
Example
```
const q = new Quat(1, 2, 3, 4);
q.mulScalar(2);
// q is now [2, 4, 6, 8]
```
- Defined in core/math/quat.js:412

normalize

normalize(src?: Quat): Quat
Normalizes the specified quaternion.
Parameters
- Optionalsrc: Quat = ...
  The quaternion to normalize. If not set, the operation is done in place.
Returns Quat
Self for chaining.
Example
```
const v = new Quat(0, 0, 0, 5);
v.normalize();
// Outputs [0, 0, 0, 1]
console.log(v.toString());
```
- Defined in core/math/quat.js:465

set

set(x: number, y: number, z: number, w: number): Quat
Sets the specified quaternion to the supplied numerical values.
Parameters
- x: number
  The x component of the quaternion.
- y: number
  The y component of the quaternion.
- z: number
  The z component of the quaternion.
- w: number
  The w component of the quaternion.
Returns Quat
Self for chaining.
Example
```
const q = new Quat();
q.set(1, 0, 0, 0);

// Outputs 1, 0, 0, 0
console.log("The result of the quaternion set is: " + q.toString());
```
- Defined in core/math/quat.js:496

setFromAxisAngle

setFromAxisAngle(axis: Vec3, angle: number): Quat
Sets a quaternion from an angular rotation around an axis.
Parameters
- axis: Vec3
  World space axis around which to rotate. Should be normalized.
- angle: number
  Angle to rotate around the given axis in degrees.
Returns Quat
Self for chaining.
Example
```
const q = new Quat();
q.setFromAxisAngle(Vec3.UP, 90);
```
- Defined in core/math/quat.js:515

setFromDirections

setFromDirections(from: Vec3, to: Vec3): Quat
Set the quaternion that represents the shortest rotation from one direction to another.
Parameters
- from: Vec3
  The direction to rotate from. It should be normalized.
- to: Vec3
  The direction to rotate to. It should be normalized.
Returns Quat
Self for chaining.
Example
```
const q = new Quat();
const from = new Vec3(0, 0, 1);
const to = new Vec3(0, 1, 0);
q.setFromDirections(from, to);
```
- Defined in core/math/quat.js:678

setFromEulerAngles

setFromEulerAngles(ex: number | Vec3, ey?: number, ez?: number): Quat
Sets this quaternion to represent a rotation specified by Euler angles in degrees. The rotation is applied using an intrinsic XYZ order: first around the X-axis, then around the newly transformed Y-axis, and finally around the resulting Z-axis.
Parameters
- ex: number | Vec3
  The angle to rotate around the X-axis in degrees, or a Vec3 object containing the X, Y, and Z angles in degrees in its respective components (ex.x, ex.y, ex.z).
- Optionaley: number
  The angle to rotate around the Y-axis in degrees. This parameter is only used if ex is provided as a number.
- Optionalez: number
  The angle to rotate around the Z-axis in degrees. This parameter is only used if ex is provided as a number.
Returns Quat
The quaternion itself (this), now representing the orientation from the specified XYZ Euler angles. Allows for method chaining.
Example
```
// Create a quaternion from 3 individual Euler angles (interpreted as X, Y, Z order)
const q1 = new Quat();
q1.setFromEulerAngles(45, 90, 180); // 45 deg around X, then 90 deg around Y', then 180 deg around Z''
console.log("From numbers:", q1.toString());
```
Example
```
// Create the same quaternion from a Vec3 containing the angles (X, Y, Z)
const anglesVec = new Vec3(45, 90, 180);
const q2 = new Quat();
q2.setFromEulerAngles(anglesVec);
console.log("From Vec3:", q2.toString()); // Should match q1
```
- Defined in core/math/quat.js:555

setFromMat4

setFromMat4(m: Mat4): Quat
Converts the specified 4x4 matrix to a quaternion. Note that since a quaternion is purely a representation for orientation, only the rotational part of the matrix is used.
Parameters
- m: Mat4
  The 4x4 matrix to convert.
Returns Quat
Self for chaining.
Example
```
// Create a 4x4 rotation matrix of 180 degrees around the y-axis
const rot = new Mat4().setFromAxisAngle(Vec3.UP, 180);

// Convert to a quaternion
const q = new Quat().setFromMat4(rot);
```
- Defined in core/math/quat.js:596

slerp

slerp(lhs: Quat, rhs: Quat, alpha: number): Quat
Performs a spherical interpolation between two quaternions. The result of the interpolation is written to the quaternion calling the function.
Parameters
- lhs: Quat
  The quaternion to interpolate from.
- rhs: Quat
  The quaternion to interpolate to.
- alpha: number
  The unclamped interpolation factor. Values between 0 and 1 interpolate between lhs and rhs; values outside this range extrapolate beyond them.
Returns Quat
Self for chaining.
Example
```
const q1 = new Quat(-0.11, -0.15, -0.46, 0.87);
const q2 = new Quat(-0.21, -0.21, -0.67, 0.68);

const result = new Quat();
result.slerp(q1, q2, 0);   // Return q1
result.slerp(q1, q2, 0.5); // Return the midpoint interpolant
result.slerp(q1, q2, 1);   // Return q2
```
- Defined in core/math/quat.js:724

toArray

toArray(arr?: number[], offset?: number): number[]
Parameters
- Optionalarr: number[]
  The array to populate with the quaternion's number components. If not specified, a new array is created.
- Optionaloffset: number
  The zero-based index at which to start copying elements to the array. Default is 0.
Returns number[]
The quaternion as an array.
- Defined in core/math/quat.js:849
toArray(arr: ArrayBufferView, offset?: number): ArrayBufferView
Parameters
- arr: ArrayBufferView
  The array to populate with the quaternion's number components. If not specified, a new array is created.
- Optionaloffset: number
  The zero-based index at which to start copying elements to the array. Default is 0.
Returns ArrayBufferView
The quaternion as an array.
- Defined in core/math/quat.js:857

toString

toString(): string
Converts the quaternion to string form.

Returns string
The quaternion in string form.
Example
```
const q = new Quat(0, 0, 0, 1);
// Outputs [0, 0, 0, 1]
console.log(q.toString());
```
- Defined in core/math/quat.js:844

transformVector

transformVector(vec: Vec3, res?: Vec3): Vec3
Transforms a 3-dimensional vector by the specified quaternion.
Parameters
- vec: Vec3
  The 3-dimensional vector to be transformed.
- Optionalres: Vec3 = ...
  An optional 3-dimensional vector to receive the result of the transformation.
Returns Vec3
The transformed vector (res if specified, otherwise a new Vec3).
Example
```
// Create a 3-dimensional vector
const v = new Vec3(1, 2, 3);

// Create a quaternion rotation
const q = new Quat().setFromEulerAngles(10, 20, 30);

const tv = q.transformVector(v);
```
- Defined in core/math/quat.js:796

Class Quat

Example

Example

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Quat

Example

Parameters

Returns Quat

Example

Properties

w

x

y

z

Static ReadonlyIDENTITY

Static ReadonlyZERO

Methods

clone

Returns Quat

Example

copy

Parameters

Returns Quat

Example

dot

Parameters

Returns number

Example

equals

Parameters

Returns boolean

Example

equalsApprox

Parameters

Returns boolean

Example

fromArray

Parameters

Returns Quat

Example

getAxisAngle

Parameters

Returns number

Example

getEulerAngles

Parameters

Returns Vec3

Example

invert

Parameters

Returns Quat

Example

length

Returns number

Example

lengthSq

Returns number

Example

lerp

Parameters

Returns Quat

Example

mul

Parameters

Returns Quat

Example

mul2

Parameters

Returns Quat

Example

mulScalar

Parameters

Returns Quat

Example

`Static` `Readonly`IDENTITY

`Static` `Readonly`ZERO