Quaternion
A quaternion representing a rotation in 3D space. Quaternions avoid gimbal lock and provide smooth interpolation between orientations. The quaternion is stored as four components (x, y, z, w). Use the identity method to reset to the identity quaternion (0, 0, 0, 1), which represents no rotation. Commonly used with Matrix4 for 3D transformations in WebGL rendering.
Constructor
new Quaternion([x], [y], [z], [w])
Parameters
| name | type | optional | default | description |
|---|---|---|---|---|
| x | number | Yes | 0 | The x component. |
| y | number | Yes | 0 | The y component. |
| z | number | Yes | 0 | The z component. |
| w | number | Yes | 1 | The w component. |
Scope: static
Source: src/math/Quaternion.js#L27
Since: 3.0.0
Public Members
onChangeCallback
onChangeCallback: function
Description:
This callback is invoked, if set, each time a value in this quaternion is changed. The callback is passed one argument, a reference to this quaternion.
Source: src/math/Quaternion.js#L91
Since: 3.50.0
w
w: number
Description:
The w component of this Quaternion.
Source: src/math/Quaternion.js#L170
Since: 3.0.0
x
x: number
Description:
The x component of this Quaternion.
Source: src/math/Quaternion.js#L104
Since: 3.0.0
y
y: number
Description:
The y component of this Quaternion.
Source: src/math/Quaternion.js#L126
Since: 3.0.0
z
z: number
Description:
The z component of this Quaternion.
Source: src/math/Quaternion.js#L148
Since: 3.0.0
Public Methods
add
<instance> add(v)
Description:
Add a given Quaternion or Vector to this Quaternion. Addition is component-wise.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| v | Phaser.Math.Quaternion | Phaser.Math.Vector4 | No | The Quaternion or Vector to add to this Quaternion. |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L248
Since: 3.0.0
calculateW
<instance> calculateW()
Description:
Calculates and sets the w component of this Quaternion based on the current x, y, and z components, so that the Quaternion has unit length. Assumes the x, y, and z values are already known and that their combined squared length does not exceed 1.
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L779
Since: 3.0.0
conjugate
<instance> conjugate()
Description:
Converts this Quaternion to its conjugate by negating the x, y, and z components while leaving w unchanged. For a unit quaternion, the conjugate is equivalent to the inverse and represents the opposite rotation.
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L668
Since: 3.0.0
copy
<instance> copy(src)
Description:
Copy the components of a given Quaternion or Vector into this Quaternion.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| src | Phaser.Math.Quaternion | Phaser.Math.Vector4 | No | The Quaternion or Vector to copy the components from. |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L192
Since: 3.0.0
dot
<instance> dot(v)
Description:
Calculate the dot product of this Quaternion and the given Quaternion or Vector.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| v | Phaser.Math.Quaternion | Phaser.Math.Vector4 | No | The Quaternion or Vector to dot product with this Quaternion. |
Returns: number - The dot product of this Quaternion and the given Quaternion or Vector.
Source: src/math/Quaternion.js#L382
Since: 3.0.0
fromMat3
<instance> fromMat3(mat)
Description:
Sets this Quaternion from the rotation represented by the given Matrix3, using the algorithm from Ken Shoemake's 1987 SIGGRAPH article "Quaternion Calculus and Fast Animation".
Parameters:
| name | type | optional | description |
|---|---|---|---|
| mat | Phaser.Math.Matrix3 | No | The Matrix3 to convert from. |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L986
Since: 3.0.0
identity
<instance> identity()
Description:
Resets this Quaternion to the identity quaternion (0, 0, 0, 1), which represents no rotation.
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L504
Since: 3.0.0
invert
<instance> invert()
Description:
Calculates the multiplicative inverse of this Quaternion and sets the result. The inverse undoes the rotation represented by this Quaternion. If the Quaternion has zero length, no change is made.
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L640
Since: 3.0.0
length
<instance> length()
Description:
Calculate the length of this Quaternion.
Returns: number - The length of this Quaternion.
Source: src/math/Quaternion.js#L314
Since: 3.0.0
lengthSq
<instance> lengthSq()
Description:
Calculate the length of this Quaternion squared.
Returns: number - The length of this Quaternion, squared.
Source: src/math/Quaternion.js#L332
Since: 3.0.0
lerp
<instance> lerp(v, [t])
Description:
Linearly interpolate this Quaternion towards the given Quaternion or Vector.
Parameters:
| name | type | optional | default | description |
|---|---|---|---|---|
| v | Phaser.Math.Quaternion | Phaser.Math.Vector4 | No | The Quaternion or Vector to interpolate towards. | |
| t | number | Yes | 0 | The percentage of interpolation. |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L397
Since: 3.0.0
multiply
<instance> multiply(b)
Description:
Multiply this Quaternion by the given Quaternion or Vector.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| b | Phaser.Math.Quaternion | Phaser.Math.Vector4 | No | The Quaternion or Vector to multiply this Quaternion by. |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L544
Since: 3.0.0
normalize
<instance> normalize()
Description:
Normalizes this Quaternion, scaling it to unit length. If the Quaternion has zero length, no change is made.
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L350
Since: 3.0.0
rotateX
<instance> rotateX(rad)
Description:
Rotate this Quaternion on the X axis.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| rad | number | No | The rotation angle in radians. |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L689
Since: 3.0.0
rotateY
<instance> rotateY(rad)
Description:
Rotate this Quaternion on the Y axis.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| rad | number | No | The rotation angle in radians. |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L719
Since: 3.0.0
rotateZ
<instance> rotateZ(rad)
Description:
Rotate this Quaternion on the Z axis.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| rad | number | No | The rotation angle in radians. |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L749
Since: 3.0.0
rotationTo
<instance> rotationTo(a, b)
Description:
Sets this Quaternion to represent the shortest arc rotation from unit vector a to unit vector b. This is the minimum rotation needed to align a with b. Both vectors must be normalized before calling this method.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| a | Phaser.Math.Vector3 | No | The starting unit vector. |
| b | Phaser.Math.Vector3 | No | The target unit vector. |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L425
Since: 3.0.0
scale
<instance> scale(scale)
Description:
Scale this Quaternion by the given value.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| scale | number | No | The value to scale this Quaternion by. |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L292
Since: 3.0.0
set
<instance> set([x], [y], [z], [w], [update])
Description:
Set the components of this Quaternion and optionally call the onChangeCallback.
Parameters:
| name | type | optional | default | description |
|---|---|---|---|---|
| x | number | object | Yes | 0 | The x component, or an object containing x, y, z, and w components. |
| y | number | Yes | 0 | The y component. |
| z | number | Yes | 0 | The z component. |
| w | number | Yes | 0 | The w component. |
| update | boolean | Yes | true | Call the onChangeCallback? |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L207
Since: 3.0.0
setAxes
<instance> setAxes(view, right, up)
Description:
Sets this Quaternion from the given view, right, and up axis vectors. The three vectors are written into a temporary Matrix3, which is then converted to a normalized quaternion. All three vectors should be mutually orthogonal unit vectors.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| view | Phaser.Math.Vector3 | No | The view (forward) axis. |
| right | Phaser.Math.Vector3 | No | The right axis. |
| up | Phaser.Math.Vector3 | No | The up axis. |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L471
Since: 3.0.0
setAxisAngle
<instance> setAxisAngle(axis, rad)
Description:
Sets this Quaternion to represent a rotation of rad radians around the given normalized axis vector.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| axis | Phaser.Math.Vector3 | No | The normalized axis vector around which to rotate. |
| rad | number | No | The rotation angle in radians. |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L518
Since: 3.0.0
setFromEuler
<instance> setFromEuler(euler, [update])
Description:
Sets this Quaternion from the given Euler object. The conversion respects the Euler's rotation order (e.g., 'XYZ', 'YXZ', 'ZXY', 'ZYX', 'YZX', 'XZY'), producing the equivalent quaternion rotation.
Parameters:
| name | type | optional | default | description |
|---|---|---|---|---|
| euler | Phaser.Math.Euler | No | The Euler object to convert from. | |
| update | boolean | Yes | true | Run the onChangeCallback? |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L800
Since: 3.50.0
setFromRotationMatrix
<instance> setFromRotationMatrix(mat4)
Description:
Sets the rotation of this Quaternion from the given Matrix4.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| mat4 | Phaser.Math.Matrix4 | No | The Matrix4 to set the rotation from. |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L911
Since: 3.50.0
slerp
<instance> slerp(b, t)
Description:
Performs a spherical linear interpolation (slerp) between this Quaternion and the given Quaternion or Vector. Unlike lerp, slerp interpolates along the shortest arc on the unit sphere, maintaining constant angular velocity and producing smooth, natural-looking rotations.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| b | Phaser.Math.Quaternion | Phaser.Math.Vector4 | No | The Quaternion or Vector to interpolate towards. |
| t | number | No | The interpolation factor, typically in the range [0, 1]. |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L574
Since: 3.0.0
subtract
<instance> subtract(v)
Description:
Subtract a given Quaternion or Vector from this Quaternion. Subtraction is component-wise.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| v | Phaser.Math.Quaternion | Phaser.Math.Vector4 | No | The Quaternion or Vector to subtract from this Quaternion. |
Returns: Phaser.Math.Quaternion - This Quaternion.
Source: src/math/Quaternion.js#L270
Since: 3.0.0