Vec2

The Vec2 class represents a vector in 2D space. Here is how you initialize one and get values from it.

let pos = new Vec2(0, 1);
log(pos); // output: {0, 1}
log(pos.x); // output: 0

Here’s more examples of its usage.

let a = new Vec2(1, 3);
let b = new Vec2(3, 7);
let sum = a.add(b); 
let length = a.length();
let sqrLength = a.sqrLength(); //squared length
let normalized = a.normalize();
let diff = a.sub(b);
let dotProduct = a.dot(b);
let distanceBetweenPoints = a.distance(b);

let factor = 2;
let scaled = a.scale(factor); 

let alpha = 0.5;
let lerp = a.lerp(b, alpha); 

let pivot = new Vec2(3,1);
let angle = Math.PI/4;
let rotated = rotateByAngle(pivot, angle);

let c = new Vec3(101, null);
let cxe = c.isXEmpty(); //false
let cye = c.isYEmpty(); //true

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

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

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

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
}

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);
}

This is where API Reference will go