stingray.Quaternion object reference

Description

Represents a rotation in the quaternion formulation (x, y, z, w).

Note that it is not strictly necessary to understand quaternions to use these obejcts; you can just treat them as opaque representations of rotations.

NOTE: Quaternion objects are temporary. You can only use them in the frame in which they were generated. If you need to save a Quaternion across multiple frames, use a QuaternionBox instead. For more information, see Object Lifetimes and Userdata Binding.

Constructors and accessors

stingray.Actor.rotation() stingray.Camera.local_rotation() stingray.Camera.world_rotation() stingray.GoogleVR.controller_orientation() stingray.GwNavTagVolume.navtag() stingray.GwNavTraversal.get_triangle_navtag() stingray.GwNavWorld.database_triangle() stingray.HumanIK.character_get_effector_transform() stingray.HumanIK.character_get_node_transform() stingray.HumanIK.character_node_get_limits() stingray.Joint.d6_drive_position() stingray.LevelResource.unit_rotation() stingray.Light.local_rotation() stingray.Light.world_rotation() stingray.LODObject.local_rotation() stingray.LODObject.world_rotation() stingray.Matrix4x4.rotation() stingray.Mesh.local_rotation() stingray.Mesh.world_rotation() stingray.Quaternion() stingray.Quaternion.axis_angle() stingray.Quaternion.conjugate() stingray.Quaternion.from_elements() stingray.Quaternion.from_euler_angles_xyz() stingray.Quaternion.from_matrix4x4() stingray.Quaternion.identity() stingray.Quaternion.inverse() stingray.Quaternion.lerp() stingray.Quaternion.look() stingray.Quaternion.multiply() stingray.Quaternion.normalize() stingray.Quaternion.set_xyzw() stingray.QuaternionBox.unbox() stingray.SceneGraphComponent.local_rotation() stingray.SceneGraphComponent.world_rotation() stingray.SceneGraphNode.local_rotation() stingray.SceneGraphNode.world_rotation() stingray.Sensor.orientation_sensor_rotation() stingray.TransformComponent.local_rotation() stingray.TransformComponent.world_rotation() stingray.Unit.delta_rotation() stingray.Unit.local_rotation() stingray.Unit.world_rotation()

Related sample code

Appkit: /simple_project.lua Appkit: /unit_controller.lua Basic template: /player.lua Character template: /player.lua Vehicle template: /player.lua Oculus VR template: /flow_callbacks.lua Oculus VR template: /player.lua Oculus VR template: /project.lua Steam VR template: /flow_callbacks.lua Steam VR template: /player.lua

Other related reference items

	stingray.QuaternionBox
	ps4_keyboard_options
	stingray.Actor.debug_draw() stingray.Actor.teleport_rotation() stingray.AnimationStateMachineComponent.set_constraint_target() stingray.Camera.set_local_rotation() stingray.EntityManager.spawn() stingray.GwNavBoxObstacle.create() stingray.GwNavCylinderObstacle.create() stingray.GwNavGeneration.set_current_navtag() stingray.GwNavGraph.create() stingray.GwNavTagVolume.create() stingray.GwNavWorld.visual_debug_draw_line() stingray.GwNavWorld.visual_debug_draw_text() stingray.Hololens.attach_entity() stingray.Hololens.create_anchor() stingray.Joint.set_d6_drive_position() stingray.Light.set_local_rotation() stingray.LODObject.set_local_rotation() stingray.Material.set_color() stingray.Material.set_vector4() stingray.Matrix4x4.from_quaternion() stingray.Matrix4x4.from_quaternion_position() stingray.Matrix4x4.set_rotation() stingray.Mesh.set_local_rotation() stingray.Oculus.set_tracking_space() stingray.PhysicsWorld.linear_capsule_sweep() stingray.PhysicsWorld.linear_obb_sweep() stingray.PhysicsWorld.overlap() stingray.Quaternion() stingray.QuaternionBox() stingray.QuaternionBox.store() stingray.ScatterSystem.make_observer() stingray.ScatterSystem.move_observer() stingray.ScatterSystem.spawn() stingray.SceneGraphComponent.set_local_rotation() stingray.SceneGraphNode.set_local_rotation() stingray.SteamVR.set_tracking_space() stingray.TransformComponent.link() stingray.TransformComponent.link_to_scene_graph() stingray.TransformComponent.set_local_rotation() stingray.Unit.animation_set_constraint_target() stingray.Unit.set_local_rotation() stingray.Unit.teleport_local_rotation() stingray.UnitSynchronizer.spawn_unit() stingray.VectorField.add() stingray.VectorField.change() stingray.World.create_particles() stingray.World.load_level() stingray.World.load_level_with_object_sets() stingray.World.move_particles() stingray.World.spawn_unit() stingray.WwiseWorld.make_auto_source() stingray.WwiseWorld.make_manual_source() stingray.WwiseWorld.trigger_event()
	Math

Related help topics

	Playtesting Your Game > Optimize memory usage
	The Interactive Plug-in SDK > Extend the Editor > Use extensions to define plug-in behaviors > Register an action

Functions

angle ( quat ) : number Returns the rotation angle represented by this quaternion.

Parameters

quat :

stingray.Quaternion

The quaternion whose rotation angle will be returned.

Returns

number

The rotation angle of the quaternion's up vector around the facing direction, expressed in radians.

axis_angle ( axis, angle ) : stingray.Quaternion Creates a new quaternion that represents a rotation with the specified angle around the specified axis.

Parameters

axis :	stingray.Vector3	The main axis for the quaternion.
angle :	number	The angle around the main axis, expressed in radians.

Returns

stingray.Quaternion

The newly created quaternion.

Equivalent to stingray.Quaternion().

Related sample code

Creating meshes procedurally

conjugate ( quat ) : stingray.Quaternion Returns the conjugate of the specified quaternion: a quaternion where the X, Y and Z values are negated, but the W component remains unchanged.

Parameters

quat :

stingray.Quaternion

The quaternion whose conjugate will be returned.

Returns

stingray.Quaternion

The conjugate of quat.

decompose ( quat ) : stingray.Vector3, number Decomposes the specified quaternion into a facing direction and a rotation angle.

Parameters

quat :

stingray.Quaternion

The quaternion to decompose.

Returns

stingray.Vector3	The X, Y and Z values that define the facing direction of the quaternion.
number	The rotation of the quaternion's up vector around the facing direction, expressed in radians.

dot ( quat_a, quat_b ) : number Returns the dot product of the two specified quaternions.

Parameters

quat_a :	stingray.Quaternion	The first quaternion.
quat_b :	stingray.Quaternion	The second quaternion.

Returns

number

The dot product.

equal ( quat_a, quat_b ) : boolean Indicates whether or not the two quaternions are equivalent.

Parameters

quat_a :	stingray.Quaternion	The first quaternion.
quat_b :	stingray.Quaternion	The second quaternion.

Returns

boolean

true if all members of the two quaternions are equal, or false otherwise.

forward ( quat ) : stingray.Vector3 Returns the forward axis of the rotation represented in the specified quaternion.

Parameters

quat :

stingray.Quaternion

The quaternion whose axis will be retrieved.

Returns

stingray.Vector3

The forward axis of the quaternion rotation.

Related sample code

Vehicle template: /vehicle_follow_cam.lua

from_elements ( x, y, z, w ) : stingray.Quaternion Creates a new Quaternion from the given elements.

Parameters

x :	number	The X element.
y :	number	The Y element.
z :	number	The Z element.
w :	number	The W element.

Returns

stingray.Quaternion

The newly created quaternion.

Related sample code

Vehicle template: /vehicle_follow_cam.lua

from_euler_angles_xyz ( x, y, z ) : stingray.Quaternion Creates a new Quaternion from Euler angles.

Parameters

x :	number	The euler X axis rotation, expressed in degrees.
y :	number	The euler Y axis rotation, expressed in degrees.
z :	number	The euler Z axis rotation, expressed in degrees.

Returns

stingray.Quaternion

The newly created quaternion.

from_matrix4x4 ( matrix ) : stingray.Quaternion Creates a new quaternion from the rotation expressed in the specified matrix.

Parameters

matrix :

stingray.Matrix4x4

A matrix that contains the rotation you want to extract.

Returns

stingray.Quaternion

The newly created quaternion.

Related sample code

Vehicle template: /vehicle_follow_cam.lua

identity ( ) : stingray.Quaternion Returns the identity quaternion, which represents no change in rotation.

Parameters

This function does not accept any parameters.

Returns

stingray.Quaternion

The identity quaternion.

Related sample code

Basic template: /project.lua Character template: /project.lua Vehicle template: /project.lua Steam VR template: /project.lua

inverse ( quat ) : stingray.Quaternion Inverts the specified quaternion, and returns the result.

Parameters

quat :

stingray.Quaternion

The quaternion to be inverted.

Returns

stingray.Quaternion

The inverted rotation.

Related sample code

Vehicle template: /vehicle_follow_cam.lua

is_valid ( quat ) : boolean Indicates whether or not the quaternion is composed entirely of valid values.

Parameters

quat :

stingray.Quaternion

The quaternion to test.

Returns

boolean

Returns true if all components of the quaternion are valid numbers, or false if any component is #NaN or #INF.

lerp ( quat_a, quat_b, t ) : stingray.Quaternion Produces a new rotation by interpolating, or "lerping", between the two specified quaternions.

Parameters

quat_a :	stingray.Quaternion	The first quaternion.
quat_b :	stingray.Quaternion	The second quaternion.
t :	number	The ratio, or interpolation point, between the two quaternions. May be any value between 0 and 1 inclusive. Values closer to 0 produce rotations closer to quat_a; values closer to 1 produce rotations closer to quat_b.

Returns

stingray.Quaternion

The resulting Quaternion.

The lerp performed by this function is a normalized lerp, or nlerp, which usually gives the best result.

Related sample code

Vehicle template: /vehicle_follow_cam.lua

look ( dir, up ) : stingray.Quaternion Creates a new quaternion with the rotation needed in order to be facing in the specified direction, with the specified up vector.

Parameters

dir :	stingray.Vector3	The forward direction for the quaternion.
up :	stingray.Vector3?	Optional; specifies the up vector for the new quaternion. If omitted, the positive direction of the Z axis is used: (0,0,1). The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.Quaternion

The newly created quaternion.

matrix4x4 ( quat ) : stingray.Matrix4x4 Converts the rotation expressed by the specified quaternion into a Matrix4x4.

Parameters

quat :

stingray.Quaternion

The quaternion to convert.

Returns

stingray.Matrix4x4

A Matrix4x4 that expresses the same rotation as the quaternion.

multiply ( quat_a, quat_b ) : stingray.Quaternion Multiplies the two specified quaternions together, and returns the result.

Parameters

quat_a :	stingray.Quaternion	The first quaternion.
quat_b :	stingray.Quaternion	The second quaternion.

Returns

stingray.Quaternion

The product of the multiplication.

This creates the rotation you would get by first rotating the object by quat_b, then rotating it by quat_a.

Related sample code

Vehicle template: /vehicle_follow_cam.lua

norm ( quat ) : number Returns the norm, or length, of the specified quaternion.

Parameters

quat :

stingray.Quaternion

The quaternion whose length will be returned.

Returns

number

The length of the quaternion.

normalize ( quat ) : stingray.Quaternion Normalizes the specified quaternion, and returns the result.

Parameters

quat :

stingray.Quaternion

The quaternion to be normalized.

Returns

stingray.Quaternion

The normalized rotation.

right ( quat ) : stingray.Vector3 Returns the right axis of the rotation represented in the specified quaternion.

Parameters

quat :

stingray.Quaternion

The quaternion whose axis will be retrieved.

Returns

stingray.Vector3

The right axis of the quaternion rotation.

rotate ( quat, vector ) : stingray.Vector3 Rotates the specified vector by the specified quaternion, and returns the result.

Parameters

quat :	stingray.Quaternion	The quaternion that will be used to rotate the vector.
vector :	stingray.Vector3	The vector to be rotated.

Returns

stingray.Vector3

The vector after rotation.

set_xyzw ( quat, x, y, z, w ) : stingray.Quaternion Sets all of the individual component values of the specified quaternion from individual floating-point values.

Parameters

quat :	stingray.Quaternion	The quaternion to set up.
x :	number	The new X component value for the quaternion's main axis.
y :	number	The new Y component value for the quaternion's main axis.
z :	number	The new Z component value for the quaternion's main axis.
w :	number	The new W component value, defining the rotation of the up vector around the quaternion's main axis.

Returns

stingray.Quaternion

The resulting quaternion.

to_elements ( quat ) : number, number, number, number Decomposes the specified quaternion into its four component values.

Parameters

quat :

stingray.Quaternion

The quaternion to decompose into its elements.

Returns

number	The X component value of the quaternion's axis.
number	The Y component value of the quaternion's axis.
number	The Z component value of the quaternion's axis.
number	The W component value: the rotation of the local up vector around the quaternion's axis.

to_euler_angles_xyz ( quat ) : number, number, number Returns the quaternion euler angles.

Parameters

quat :

stingray.Quaternion

The quaternion to convert.

Returns

number	The euler X axis rotation, expressed in degrees.
number	The euler Y axis rotation, expressed in degrees.
number	The euler Z axis rotation, expressed in degrees.

Related sample code

Oculus VR template: /project.lua

to_string ( quat ) : string Returns a string representation of the specified quaternion.

Parameters

quat :

stingray.Quaternion

The quaternion to return as a string.

Returns

string

The string representation.

Use this function only for debugging purposes.

up ( quat ) : stingray.Vector3 Returns the up axis of the rotation represented in the specified quaternion.

Parameters

quat :

stingray.Quaternion

The quaternion whose axis will be retrieved.

Returns

stingray.Vector3

The up axis of the quaternion rotation.