Trail

A Trail is a node that creates a trail behind the Entity.

globalDepth()

Returns the global depth of the Trail node. Depth decides which object is on top in a 2D World. A higher value will be above a lower number in the Scene.

Returns

number – The global depth of the Trail

↑ Back to top

setColor(r, g, b, a)

Sets the color of the trail.

Parameters

number red – the red component of the new color
number green – the green component of the new color
number blue – the blue component of the new color
number alpha – (Optional) the opacity component of the new color, max 255

let trail = this.entity().component("Trail");
trail.setColor(193, 66, 66); // set the trail to be red

↑ Back to top

setGlobalDepth(value)

Sets the global depth of the Animation node. Depth decides which object is on top in a 2D World. A higher value will be above a lower number in the Scene.

Parameters

number value – The global depth of the Animation

↑ Back to top

setUpVector(value)

Sets the “up vector” of the Trail. This changes the orientation of the tail, which is useful for 2D games. The range is 0-1 for the x, y, and z values.

Parameters

Vec3 value – The new “up vector”

↑ Back to top

upVector()

Returns the “up vector” of the Trail.

Returns

Vec3 – The Trail’s “up vector”

↑ Back to top

Quaternion

The Quaternion class represents a quaternion. Quaternions are used to describe rotation in 3D space. Quaternion contains several helpful static functions, which can be called like this: Quaternion.multiply(quat1, quat2). Objects of the Quaternion class have 4 number properties: x, y, z, and w.

inverse()

Inverts the quaternion.

Returns

boolean true if the inversion was successful, false if not

↑ Back to top

toEuler()

Converts from Quaternion to Euler angles (in degrees).

Returns

Vec3 the {x, y, z} yaw, pitch, and roll Euler angles

↑ Back to top

angle(quat1, quat2)

Returns the angle between two Quaternions.

Parameters

Quaternion quat1 – the first Quaternion
Quaternion quat2 – the second Quaternion

Returns

number – the resulting angle

↑ Back to top

fromEuler(pitch, yaw, roll)

Converts from Euler angles to Quaternion.

Parameters

number pitch – the x-axis component
number yaw – the y-axis component
number roll – the z-axis component

Returns

Quaternion the resulting Quaternion

↑ Back to top

lerp(quat1, quat2, t)

Interpolates between two quaternions using linear interpolation and returns the result. Less accurate than slerp() but more efficient. The interpolation curve for linear interpolation between quaternions gives a straight line in quaternion space.

Parameters

Quaternion quat1 – the first Quaternion
Quaternion quat2 – the second Quaternion
number t the interpolation coefficient

Returns

Quaternion the resulting Quaternion

↑ Back to top

lookAt(lookStart, lookEnd)

Returns a Quaternion oriented to the given 3D coordinates.

Parameters

Vec3 lookStart – the first set of 3D coordinates
Vec3 lookEnd – the second set of 3D coordinates

Returns

Quaternion – the resulting Quaternion

let _target;

function start(){
    _target = this.scene().findFirst("Cube");
}

function update(dt){
    // rotate the projectile to face the target
    let currentQuat = this.entity().rotationQuat();
    let nextQuat = Quaternion.lookAt(this.entity().position(), _target.position());
    nextQuat = Quaternion.slerp(currentQuat, nextQuat, 0.5);
    this.entity().setRotationQuat(nextQuat);

    // move the projectile toward the target in an arcing movement
    let mat = Mat4.createRotation(nextQuat);
    let forward = Mat4.transformPoint(mat, new Vec3(1, 1, -1));
    let curPos = this.entity().position();
    this.entity().setPosition(
        curPos.x + 0.1 * forward.x,
        curPos.y + 0.1 * forward.y,
        curPos.z + 0.1 * forward.z);
}

↑ Back to top

multiply(quat1, quat2)

Multiplies the given Quaternions and returns the result.

Parameters

Quaternion quat1 – the first Quaternion
Quaternion quat2 – the second Quaternion

Returns

Quaternion – the resulting Quaternion

↑ Back to top

slerp(quat1, quat2, alpha)

Interpolates between two Quaternions using spherical spline interpolation and returns the result. More accurate than lerp() but less efficient. Spherical spline interpolation provides smooth transitions between different orientations and is often useful for animating models or cameras in 3D.

Parameters

Quaternion quat1 – the first Quaternion
Quaternion quat2 – the second Quaternion
number t the interpolation coefficient

Returns

Quaternion the resulting Quaternion

↑ Back to top

AABB

Represents the “axis-aligned bounding box” for the object. These coordinates form a box with the minimum corner at (left, bottom, near) and the maximum corner at (right, top, far). Together this can be used to ascertain the size of the bounding box.

max

The Vec3 {right, top, far} maximum value of the AABB.

↑ Back to top

min

The Vec3 {left, bottom, near} minimum value of the AABB.

↑ Back to top

Event

The Event class allows you to fire (broadcast) global events and subscribe to them. Here’s an example:

//// SENDER
let data = true; // this could be any value
eventName = "Some Name";
Event.fire(eventName, data);

//// RECEIVER
let SNCallback = function(data){
  log("callback: " + data);
};

function start(){
  Event.addListener("Some Name", SNCallback);
}
function onRemove(){
  Event.removeListener("Some Name", SNCallback);
}

EasingFunctions

EasingFunctions is a helper class with a collection of easing functions. Easing functions are used to calculate interpolation to create an animation.

These functions take a value from 0 to 1 representing how far into the animation you are (0 = beginning, 1 = end). Think of this as the “percent complete”. You can use easing functions in an update loop to update your object every frame. The Animation action nodes have all this set up for you already.

This is a simplified example of how we use EasingFunctions in a position animation node. This example makes my entity fall to position {0, 0, 0} with a bounce out animation.

let duration = 5;               // length of the animation in seconds
let phaseT = 0;                 // how far into the animation we are (percentage complete)
let target = new Vec3(0, 0, 0); // the ending position of my object
let done = false;               // flag to detect when to stop animating

let animObj;                    // the object we're animating
let startPos;                   // our object's initial position

function start(){
	animObj = this.entity();
	startPos = animObj.position();
}

function update(dt) {
	if (done) return; // don't run this code if the animation is complete
	phaseT += dt / duration; // calculate the time difference since the last update call
	phaseT = Math.min(phaseT, 1); // don't allow the percentage complete to go over 100%

	// Pass the percentage complete into the EasingFunction, 
	// which will return the factor we need to multiply by to
	// find our target position for this frame:
	let anim = EasingFunctions.outBounce(phaseT); 

	// determine the new position based on the starting position, target position, and animation factor:
	let aPos = new Vec3;
	aPos.x = startPos.x * (1 - anim) + target.x * anim;
	aPos.y = startPos.y * (1 - anim) + target.y * anim;
	aPos.z = startPos.z * (1 - anim) + target.z * anim;

	// set the new position
	animObj.setPosition(aPos.x, aPos.y, aPos.z);

	if (phaseT == 1) {
		// if we reach 100% complete, set the flag to stop running the animation code
		done = true;
	}
}

Supported Easing Functions

Here is a website with graphs of all the easing functions, for visualization.

EasingFunctions = {
    linear
    inQuad
    outQuad
    inOutQuad
    inCube
    outCube
    inOutCube
    inQuart
    outQuart
    inOutQuart
    inQuint
    outQuint
    inOutQuint
    inSine
    outSine
    inOutSine
    inExpo
    outExpo
    inOutExpo
    inCirc
    outCirc
    inOutCirc
    inBack
    outBack
    inOutBack
    inBounce
    outBounce
    inOutBounce
    inElastic
    outElastic
    inOutElastic
}

Mat4

The Mat4 class represents a 4×4 matrix. Mat4 contains several helpful static functions, which can be called like this: Mat4.createRotation(quat)

arr

array – the array that represents the matrix

↑ Back to top

rotate(x, y, z, angle)

Post-multiplies this matrix by the matrix corresponding to the specified rotation about the specified axis.

Parameters

number x – the x-axis to rotate about
number y – the y-axis to rotate about
number z – the z-axis to rotate about
number angle – the angle of the rotation (radians)

↑ Back to top

scale(x, y, z)

Post-multiplies this matrix by the matrix corresponding to the specified scale transformation.

Parameters

number x – the amount to scale along the x-axis
number y – the amount to scale along the y-axis
number z – the amount to scale along the z-axis

↑ Back to top

translate(x, y, z)

Post-multiplies this matrix by the matrix corresponding to the specified translation.

Parameters

number x – the amount to translate along the x-axis
number y – the amount to translate along the y-axis
number z – the amount to translate along the z-axis

↑ Back to top

createIdentity()

Creates and returns a 4×4 identity matrix.

Returns

Mat4 matrix – A new identity matrix

↑ Back to top

createOrthographic(left, right, bottom, top, near, far)

Creates an orthographic projection transformation matrix. The parameters form a rectangular cuboid that defines the visible area of rendering.

Parameters

number left – farthest left on the x-axis
number right – farthest right on the x-axis
number bottom – farthest down on the y-axis
number top – farthest up on the y-axis
number near – closest on the z-axis
number far – furthest on the z-axis

Returns

Mat4 – the resulting orthographic projection matrix

↑ Back to top

createRotation(quat)

Creates a rotation matrix based on the given Quaternion.

Parameters

Quaternion quat – the Quaternion representation of the rotation

Returns

Mat4 – the resulting rotation matrix

↑ Back to top

createTranslation(x, y, z)

Creates a translation matrix based on the given x, y, z coordinates.

Parameters

number x – the translation on the x-axis
number y – the translation on the y-axis
number z – the translation on the z-axis

Returns

Mat4 – the resulting translation matrix

↑ Back to top

inverse(matrix)

Returns the inverse of the given matrix.

Parameters

Mat4 matrix – the matrix to be inverted

Returns

Mat4 – the inverted matrix

↑ Back to top

multiply(matrix1, matrix2)

Multipies the given matrices together.

Parameters

Mat4 matrix1 – the first matrix to multiply
Mat4 matrix2 – the second matrix to multiply

Parameters

Mat4 – the resulting matrix

↑ Back to top

transformPoint(matrix, point)

Transforms the specified point by this matrix, and returns the result.

Parameters

Mat4 matrix – the transformation matrix
Vec3 point – the point to transform

Returns

Vec3 – the transformed point

↑ Back to top

transformVector(matrix, vector)

Transforms the specified vector by this matrix by treating the fourth (w) coordinate as zero, and returns the result.

Parameters

Mat4 matrix – the transformation matrix
Vec3 vector – the vector to transform

Returns

Vec3 – the transformed vector

↑ Back to top

OBB

The OBB class represents an “oriented bounding box” for an object. OBB is more precise but more performance-heavy than AABB. The list below isn’t of functions but properties, so you can call them like this: this.entity().worldOBB().center

center

Vec3 the {x, y, z} center of the OBB

↑ Back to top

extents

Vec3 the {x, y, z} extents of the OBB

↑ Back to top

xAxis

Vec3 the x-axis orientation axes

↑ Back to top

yAxis

Vec3 the y-axis orientation axes

↑ Back to top

zAxis

Vec3 the z-axis orientation axes

↑ Back to top