Physics Component

This component is used for processing physics. You can find the physics menu in the Start node. To access these functions, you can use this.entity().physics().

Function	Description
activateBody()	When the body type is “kDynamic” and “Always Active” is disabled, the body will become inactive after a short period of time. This function activates it again.
affectedAsset()	Returns the affected asset set for the physics component. This decides what type of assets this body can interact with.
angularDamping()	Returns the angular damping factor. Angular damping simulates drag; the higher the value, the more this entity will resist rotation.
angularVelocity()	Returns the current angular velocity value of the object.
clearVelocities()	Sets angular and linear velocity to zero.
collisionData()	Returns an object containing collision data for this entity. Optionally an Entity can be passed to get data about one entity specifically.
collisionGroup()	Returns the collision group of the object.
disableDeactivation(value)	A body will become inactive after a short period of time if left alone. If you disable deactivation, the body will always stay active. This is recommended for Linker entities.
friction()	Returns the body’s friction value.
gravity()	Returns the gravity value affecting the entity. If it hasn’t been adjusted for this entity, this method will return the gravity value of the Scene.
hasCollision(entity)	Returns true if the given entity collides with the current one.
isPhysics()	Returns true if physics is enabled on this entity, false if not.
linearDamping()	Returns the linear damping factor. Linear damping simulates drag; the higher the value, the more this entity will resist translation.
linearFactor()	Returns “position factor” of the physics component. The linear factor determines how the physics engine affects specific linear/position axes. For instance of x=0, the physics engine will not calculate physics for that axis. If x=2.0, it will calculate physics magnified by 2.
linearVelocity()	Returns the current linear velocity value of the entity.
mass()	Returns the mass value of the entity. This defaults to 1.
mesh()	Returns the collision shape mesh if assigned. Null if a mesh is not being used as the collision shape.
parentEntity()	Returns the entity that this physics component belongs to.
predictedPosition(time)	Returns the predicted position of the body based on the given time.
rebuildShape()	Call this function to update the physics collision shape. This should be done if you change the shape or scale of your Entity in code.
restitution()	Returns the “Bounce” value of the physics component. The higher the value, the higher the bounce upon collision.
setAffectedAsset(value)	Sets the affected asset for the physics component. This decides what type of assets this body can interact with. Possible values: “kAll”, “kEnemy”, “kPlatform”, “kCoin”, “kCharacter”, “kPath”, Asset.
setAngularDamping(value)	Sets the angular damping factor, range 0-1. Angular damping simulates drag; the higher the value, the more this entity will resist rotation.
setAngularFactor(x, y, z)	Sets the “rotation factor” of the object. This determines how the physics engine affects specific angular/rotation axes. For instance of x=0, the physics engine will not calculate physics for that axis. If x=2.0, it will calculate physics magnified by 2.
setAngularVelocity(x, y, z)	Sets the angular velocity value of the object.
setCollisionGroup(group)	Set the collision group of the entity.
setCreated(value)	Enables/disables everything that is connected to the “Start” node.
setFriction(value)	Sets the friction value for the body.
setGravity(x, y, z)	Sets gravity value affecting this entity. This will override the gravity value in the scene, and will not affect other objects.
setLinearDamping(value)	Sets the linear damping factor, range 0-1. Linear damping simulates drag; the higher the value, the more this entity will resist translation.
setLinearFactor(x, y, z)	Sets the “position factor” of the object. This determines how the physics engine affects specific linear/position axes. For instance of x=0, the physics engine will not calculate physics for that axis. If x=2.0, it will calculate physics magnified by 2.
setLinearVelocity(x, y, z)	Sets the linear velocity of the entity.
setMass(value)	Sets the mass of the entity. A mass of 0 will not be affected by gravity.
setMesh(mesh)	Sets the mesh of the collision shape from a MeshModel script attribute.
setMesh(name)	Sets the mesh of the collision shape based on the name of the mesh.
setPhysics(value)	Enables/disables physics.
setRestitution(value)	Sets the “Bounce” value of the physics component. The higher the value, the higher the bounce upon collision.
setShapePosition(x, y, z)	Sets the collision shape position of the object. Note: you must call rebuildShape() after calling this for the change to be reflected in game.
setShapeRotation(x, y, z)	Sets the collision shape rotation of the object. Note: you must call rebuildShape() after calling this for the change to be reflected in game.
setShapeScale(x, y, z)	Sets the collision shape scale of the object. Note: you must call rebuildShape() after calling this for the change to be reflected in game.
setShapeType(type)	Sets the shape type. Highly recommended to use “kHullShape” over “kMeshShape”.
setType(value)	Sets the type of the physics body.
shapePosition()	Returns the position of the collision shape.
shapeRotation()	Returns the rotation of the collision shape.
shapeScale()	Returns the scale of the collision shape.
shapeType()	Returns the shape type of the collision shape.
type()	Returns the type of the physics body.

---

activateBody()

When the body type is “kDynamic” and “Always Active” is disabled, the body will get inactive after a short period of time. This function activates it back.

↑ Back to top

---

affectedAsset()

Returns the affected asset set for the physics component. This decides what type of assets this body can interact with. Possible values: “kAll”, “kEnemy”, “kPlatform”, “kCoin”, “kCharacter”, “kPath”, Asset.

Returns

string / Asset – the asset or group of assets this body can interact with

↑ Back to top

---

angularDamping()

Returns the angular damping factor. Angular damping simulates drag; the higher the value, the more this entity will resist rotation.

Returns

number – the angular damping factor, range 0-1

↑ Back to top

---

angularFactor()

Returns the “rotation factor” of the physics component. The angular factor determines how the physics engine affects specific angular/rotation axes. For instance of x=0, the physics engine will not calculate physics for that axis. If x=2.0, it will calculate physics magnified by 2.

Returns

Vec3 the {x, y, z} components of the angular factor.

↑ Back to top

---

angularVelocity()

Returns the current angular velocity value of the object.

Returns

Vec3 the {x, y, z} components of the angular velocity.

↑ Back to top

---

clearVelocities()

Sets angular and linear velocity to zero.

↑ Back to top

---

collisionData()

Returns an object containing collision data for this entity. Optionally an Entity can be passed to get data about one entity specifically.

The returned object will have these properties (Data types in parenthesis). Keep in mind that a property is accessed like this: this.entity().physics().collisionData().totalImpulse;.

entity – the entity that’s being collided with (Entity)
totalImpulse – the total impulse from all collision points (number)
collisionPoints – an array of objects containing data about each point of collision (array of Objects). Each object in the array has these properties:
– impulse – the impulse from the collision point (number)
– normal – the normal of the collision point (Vec3)
– position – the position of the collision point (Vec3)

Parameters

Entity (optional) an entity to check collision data with the current entity

Returns

Object – data object containing the information listed above

↑ Back to top

---

collisionGroup()

Returns the collision group of the object.

Returns

string possible values: kNone, kCharacter, kEnemy, kPlatform, kCoin

↑ Back to top

---

disableDeactivation(value)

A body will become inactive after a short period of time if left alone. If you disable deactivation, the body will always stay active. This is recommended for Linker entities.

Parameters

boolean value – true to keep the entity always active, false to allow it to become inactive as normal

↑ Back to top

---

friction()

Returns the body’s friction value. This can also be seen in the Start node unless altered at runtime.

Returns

number the friction value of the body

↑ Back to top

---

gravity()

Returns the gravity value affecting the entity. If it hasn’t been adjusted for this entity, this method will return the gravity value of the Scene.

Returns

number the current gravity value of the entity.

↑ Back to top

---

hasCollision(entity)

Returns true if the given entity collides with the current one.

Parameters

Entity entity the entity to check for a collision with

Returns

boolean true if the entities are colliding, false if not.

↑ Back to top

---

isPhysics()

Returns true if physics is enabled, false if not.

Returns

boolean true if physics is enabled, false if not.

↑ Back to top

---

linearDamping()

Returns the linear damping factor. Linear damping simulates drag; the higher the value, the more this entity will resist translation. Default value: 0

Returns

number the linear damping, range 0-1.

↑ Back to top

---

linearFactor()

Returns “position factor” of the physics component. The linear factor determines how the physics engine affects specific linear/position axes. For instance of x=0, the physics engine will not calculate physics for that axis. If x=2.0, it will calculate physics magnified by 2.

Returns

Vec3 the {x, y, z} linear factor.

↑ Back to top

---

linearVelocity()

Returns the current linear velocity value of the entity.

Returns

Vec3 the {x, y, z} linear velocity of the entity.

↑ Back to top

---

mass()

Returns the mass value of the entity. This defaults to 1.

Returns

number the mass of the entity

↑ Back to top

---

mesh()

Returns the collision shape mesh if assigned. Null if a mesh is not being used as the collision shape.

Returns

MeshModel the object of the collision shape mesh

↑ Back to top

---

parentEntity()

Returns the entity that this physics component belongs to.

Returns

Entity the parent entity of the physics component

↑ Back to top

---

predictedPosition(time)

Returns the predicted position of the body based on the given time.

Parameters

number time – the number of seconds from now that you’d like to predict the position of the entity

Returns

Vec3 entity’s predicted {x, y, z} position after time based on its current Velocity.

↑ Back to top

---

rebuildShape()

Call this function to update the physics collision shape. This should be done if you change the shape or scale of your Entity in code.

↑ Back to top

---

restitution()

Returns the “Bounce” value of the physics component. The higher the value, the higher the bounce upon collision.

Returns

number the “Bounce” value of the physics component

↑ Back to top

---

setAffectedAsset(value)

Sets the affected asset for the physics component. This decides what type of assets this body can interact with. Possible values: “kAll”, “kEnemy”, “kPlatform”, “kCoin”, “kCharacter”, “kPath”, Asset.

Parameters

string value / Asset value – the asset or group of assets this body can interact with

↑ Back to top

---

setAngularDamping()

Sets the angular damping factor, range 0-1. Angular damping simulates drag; the higher the value, the more this entity will resist rotation.

Parameters

number value – the angular damping factor

↑ Back to top

---

setAngularFactor(x, y, z)

Sets the “rotation factor” of the object. This determines how the physics engine affects specific angular/rotation axes. For instance of x=0, the physics engine will not calculate physics for that axis. If x=2.0, it will calculate physics magnified by 2.

Parameters

number x – the x component of the new angular factor
number y – the y component of the new angular factor
number z – the z component of the new angular factor

↑ Back to top

---

setAngularVelocity(x, y, z)

Sets the angular velocity value of the object.

Parameters

number x – the x component of the new angular velocity
number y – the y component of the new angular velocity
number z – the z component of the new angular velocity

↑ Back to top

---

setCollisionGroup(group)

Set the collision group of the entity.

Parameters

string group – possible values: kNone, kCharacter, kEnemy, kPlatform, kCoin

↑ Back to top

---

setCreated(value)

Enables/disables everything that is connected to the “Start” node.

Parameters

boolean value – true to enable, false to disable

↑ Back to top

---

setFriction(value)

Sets the friction value for the body. This can also be changed in the Start node.

Parameters

number value – the new friction value

↑ Back to top

---

setGravity(x, y, z)

Sets gravity value affecting this entity. This will override the gravity value in the scene, and will not affect other objects.

Parameters

number x – the x component of the new gravity
number y – the y component of the new gravity
number z – the z component of the new gravity

↑ Back to top

---

setLinearDamping(value)

Sets the linear damping factor, range 0-1. Linear damping simulates drag; the higher the value, the more this entity will resist translation.

Parameters

number value – the linear damping factor

↑ Back to top

---

setLinearFactor(x, y, z)

Sets the “position factor” of the object. This determines how the physics engine affects specific linear/position axes. For instance of x=0, the physics engine will not calculate physics for that axis. If x=2.0, it will calculate physics magnified by 2.

Parameters

number x – the x component of the new linear factor
number y – the y component of the new linear factor
number z – the z component of the new linear factor

↑ Back to top

---

setLinearVelocity(x, y, z)

Sets the linear velocity of the entity.

Parameters

number x – the x component of the new linear velocity
number y – the y component of the new linear velocity
number z – the z component of the new linear velocity

↑ Back to top

---

setMass(value)

Sets the mass of the entity. A mass of 0 will not be affected by gravity.

Parameters

number value – the new mass of the entity

↑ Back to top

---

setMesh(mesh)

Sets the mesh of the collision shape from a MeshModel script attribute.

Parameters

MeshModel mesh – the new mesh for the collision shape

↑ Back to top

---

setMesh(name)

Sets the mesh of the collision shape based on the name of the mesh.

Parameters

string name – the new mesh for the collision shape

↑ Back to top

---

setPhysics(value)

Enables/disables physics.

Parameters

boolean value – true to enable physics, false to disable

↑ Back to top

---

setRestitution(value)

Sets the “Bounce” value of the physics component. The higher the value, the higher the bounce upon collision.

Parameters

number value – the new “Bounce” value

↑ Back to top

---

setShapePosition(x, y, z)

Sets the collision shape position of the object. Note: you must call rebuildShape() after calling this for the change to be reflected in game.

Parameters

number x – the x component of the new shape position
number y – the y component of the new shape position
number z – the z component of the new shape position

↑ Back to top

---

setShapeRotation(x, y, z)

Sets the collision shape rotation of the object. Note: you must call rebuildShape() after calling this for the change to be reflected in game.

Parameters

number x – the x component of the new shape rotation
number y – the y component of the new shape rotation
number z – the z component of the new shape rotation

↑ Back to top

---

setShapeScale(x, y, z)

Sets the collision shape scale of the object. Note: you must call rebuildShape() after calling this for the change to be reflected in game.

Parameters

number x – the x component of the new shape scale
number y – the y component of the new shape scale
number z – the z component of the new shape scale

↑ Back to top

---

setShapeType(type)

Sets the shape type. Highly recommended to use “kHullShape” over “kMeshShape”.

Parameters

string type – Possible values: “kCubeShape”, “kSphereShape”, “kCylinderShape”, “kHullShape”, “kMeshShape”.

↑ Back to top

---

setType(value)

Sets the type of the physics body.
kStatic – body is static and will never be moved but other objects can collide with it. Used for ground or walls in your game.
kDynamic – body is fully dynamic and can bounce off of other object and be affected by gravity.
kKinematic – body can be moved by directly setting position and rotation and will not react to other bodies collision or gravity. Used as obstacles or elevator platforms.
kNone – no physics enabled

Parameters

string type – Possible values: kStatic, kDynamic, kKinematic, kNone

↑ Back to top

---

shapePosition()

Returns the position of the collision shape.

Returns

Vec3 the {x, y, z} position of the collision shape

↑ Back to top

---

shapeRotation()

Returns the rotation of the collision shape.

Returns

Vec3 the {x, y, z} rotation of the collision shape

↑ Back to top

---

shapeScale()

Returns the scale of the collision shape.

Returns

Vec3 the {x, y, z} scale of the collision shape

↑ Back to top

---

shapeType()

Returns the shape type of the collision shape.

Returns

string Possible values: “kCubeShape”, “kSphereShape”, “kCylinderShape”, “kHullShape”, “kMeshShape”.

↑ Back to top

---

type()

Returns the type of the physics body. kStatic – body is static and will never be moved but other objects can collide with it. Used for ground or walls in your game.
kDynamic – body is fully dynamic and can bounce off of other object and be affected by gravity.
kKinematic – body can be moved by directly setting position and rotation and will not react to other bodies collision or gravity. Used as obstacles or elevator platforms.
kNone – no physics enabled

Returns

string Possible values: kStatic, kDynamic, kKinematic, kNone

let ph = this.entity().physics();
if(ph && ph.type() == 'kDynamic'){
  //Dynamic mode
}else{
  //Static or Kinematic mode
}

↑ 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.

Property	Description
max	The Vec3 {right, top, far} maximum value of the AABB.
min	The Vec3 {left, bottom, near} minimum value of the AABB.

---

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)

Property	Description
arr	The array that represents the matrix.

Function	Description
rotate(x, y, z, angle)	Post-multiplies this matrix by the matrix corresponding to the specified rotation about the specified axis.
scale(x, y, z)	Post-multiplies this matrix by the matrix corresponding to the specified scale transformation.
translate(x, y, z)	Post-multiplies this matrix by the matrix corresponding to the specified translation.

Static Function	Description
createIdentity()	Creates and returns a 4×4 identity matrix.
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.
createRotation(quat)	Creates a rotation matrix based on the given Quaternion.
createTranslation(x, y, z)	Creates a translation matrix based on the given x, y, z coordinates.
inverse(matrix)	Returns the inverse of the given matrix.
multiply(matrix1, matrix2)	Multipies the given matrices together.
transformPoint(matrix, vector)	Transforms the specified point by this matrix, and returns the result.
transformVector(matrix, vector)	Transforms the specified vector by this matrix by treating the fourth (w) coordinate as zero, and returns the result.

---

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

Property	Description
center	Vec3 the {x, y, z} center of the OBB
extents	Vec3 the {x, y, z} extents of the OBB
xAxis	Vec3 the x-axis orientation axes
yAxis	Vec3 the y-axis orientation axes
zAxis	Vec3 the z-axis orientation axes

---

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

Scene

The Scene API handles aspects of game at the 2D/3D world level.

Function	Description
addChild(entity)	Adds the given Entity as a child of the Scene.
addLevel(name)	Adds a level to the queue of levels to be displayed. The engine will look for a Level Section (aka Scene) with the given name and schedule it for adding. As soon as the engine needs a new level section to display, it will look for scheduled ones first.
addScoreCoin(value)	Increases the user’s coins by the amount given in value. You can also pass a negative value to decrease the user’s coins. Note: A coin is typically something the user can spend, while a point is not.
addScorePoint(value)	Increases the user’s score by the amount given in value. You can also pass a negative value to decrease the user’s points. Note: A coin is typically something the user can spend, while a point is not.
bestCoins()	Returns the highest value of coins in the current 2D/3D World.
bestGlobalCoins()	Returns the highest amount of coins in the entire game.
bestGlobalPoints()	Returns the highest amount of points in the entire game.
bestPoints()	Returns the highest amount of points in the current 2D/3D World.
camera()	Returns the Camera of the Scene.
characters()	Returns an array of Characters that are currently in the Scene. Remember, there are two kinds of assets that can be placed in a Scene: characters and objects.
clone(originalEntity)	Clones originalEntity and returns a copy of it. Note that the cloned entity’s start() function will be ran when it is cloned.
create(name, parent)	Creates a new Entity using the Asset with the specified name, Asset, or id.
createLinker(name)	Creates and returns a new Linker with the given name (optional).
currentCoins()	Returns the current amount of coins in the 2D/3D World.
currentGlobalCoins()	Returns the current amount of coins in the overall game.
currentGlobalPoints()	Returns the current amount of points in the overall game.
currentLevelName()	Returns the name of the current level.
currentPoints()	Returns the current amount of points in the 2D/3D World.
decreaseCoins(value)	Decreases the user’s coins by the amount given in value.
decreaseCurrentPoints(value)	Decreases the user’s points by the amount given in value.
decreaseTotalPoints(value)	Decreases the given value from the total points in the current 2D/3D World.
entities()	Returns an array of all Entities in the Scene.
find(name)	Returns the array of Entities with the specified name.
findFirst(name)	Returns the first Entity found in the scene with the given name. Useful if you’re sure you only have one Object in the Scene with that name. Returns null if the Entity is not found.
path()	Returns Path object of the Scene.
physicsWorld()	Returns the Scene’s PhysicsWorld object. For more information, look at the PhysicsWorld API reference page.
purgeLevel()	Removes the current first level section.
pushNavigation(name)	Activates a Navigation button with the given name on the current UI, as if the user touched it.
rayTest(from, to)	Returns objects (AABBs) that collide with a ray between the two given Vec3 coordinates. The object returned has the properties bodies and sensors.
restart()	Restarts the scene.
setBackgroundColor(r, g, b)	Sets the background color of the Scene.
setGravity(x, y, z)	Sets the gravity of the Scene.
setScorePoint(value)	Sets the current points to the given value. Note: A coin is typically something the user can spend, while a point is not.
setShadowsEnabled(enabled)	Use this function to turn shadows on or off globally. This can make your game run better on certain devices. Defaults to true (shadows on).
setSpeed(value)	Sets the path speed.
shadowsEnabled()	Returns whether shadows are enabled in the Scene.
speed()	Returns the path speed.
totalCoins()	Returns the total amount of coins in the current 2D/3D World. Note: A coin is typically something the user can spend, while a point is not.
totalGlobalCoins()	Returns the total amount of coins in the overall game.
totalGlobalPoints()	Returns the total amount of points in the overall game.
totalPoints()	Returns the total amount of points in the current 2D/3D World. Note: A coin is typically something the user can spend, while a point is not.

---

addChild(entity)

Adds the given Entity as a child of the Scene.

Parameters

Entity entity – the Entity to add to the Scene.

↑ Back to top

---

addLevel(name)

Adds a level to the queue of levels to be displayed. The engine will look for a Level Section (aka Scene) with the given name and schedule it for adding. As soon as the engine needs a new level section to display, it will look for scheduled ones first.

Parameters

string name – the name of the level to be added

// scheduling levels sections ahead of time. Keep in mind that all level sections will not be placed all at once, but based on current distance.
function init(){
  this.scene().addLevel('LevelM1');
  this.scene().addLevel('LevelM2');
  this.scene().addLevel('LevelM3');
  this.scene().addLevel('LevelM2');
  this.scene().addLevel('LevelM1');
}

↑ Back to top

---

addScoreCoin(value)

Increases the user’s coins by the amount given in value. You can also pass a negative value to decrease the user’s coins. Note: A coin is typically something the user can spend, while a point is not.

Parameters

number value – the number to increase the coins by.

log(this.scene().totalCoins()); // output: 5
this.scene().addScoreCoin(2);
log(this.scene().totalCoins()); // output: 7

↑ Back to top

---

addScorePoint(value)

Increases the user’s score by the amount given in value. You can also pass a negative value to decrease the user’s points. Note: A coin is typically something the user can spend, while a point is not.

Parameters

number value – the number to increase the score by.

  this.scene().addScorePoint(45);

↑ Back to top

---

bestCoins()

Returns the highest value of coins in the current 2D/3D World.

Returns

number the highest value of coins in the current 2D/3D World

↑ Back to top

---

bestGlobalCoins()

Returns the highest amount of coins in the entire game.

Returns

number the highest amount of coins in the entire game

↑ Back to top

---

bestGlobalPoints()

Returns the highest amount of points in the entire game.

Returns

number the highest amount of points in the entire game

↑ Back to top

---

bestPoints()

Returns the highest amount of points in the current 2D/3D World.

Returns

number the highest amount of points in the current 2D/3D World

↑ Back to top

---

camera()

Returns the Camera of the Scene.

Returns

Camera the Camera object of the Scene

↑ Back to top

---

characters()

Returns an array of Characters that are currently in the Scene. Remember, there are two kinds of assets that can be placed in a Scene: characters and objects.

Returns

array an array of Entities with the Character label in the Scene.

this.scene().characters()[0].setPosition(0, 0, 0); //set the position of the first character returned by characters()

↑ Back to top

---

clone(originalEntity)

Clones originalEntity and returns a copy of it. Note that the cloned entity’s start() function will be ran when it is cloned.

Parameters

Entity originalEntity – the Entity you’d like to copy

Returns

Entity the new entity

// clone the current entity
let entity = this.scene().findFirst("Cone");
let copiedEntity = this.scene().clone(entity);
this.scene.addChild(copiedEntity);

↑ Back to top

---

create(name, parent)

Creates a new Entity using the Asset with the specified name, Asset, or id. For using an id, see attribute().

Parameters

string/Asset/number name – The asset the new Entity should use.
Scene/LevelSector parent – (Optional) the parent Entity or LevelSector

Returns

Entity The entity that was just created.

let ent = this.scene().create('Obstacle1');
ent.setPosition(0, 20, 0);

↑ Back to top

---

createLinker()

Creates and returns a new Linker with the given name (optional). After creation, use methods like setEntities(a, b) and setPosition(vec3) to set up your linker.

Parameters

string the name of the linker (optional)

Returns

Linker the new linker

↑ Back to top

---

currentCoins()

Returns the current amount of coins in the 2D/3D World.

Returns

number the current amount of coins in the 2D/3D World

↑ Back to top

---

currentGlobalCoins()

Returns the current amount of coins in the overall game.

Returns

number the current amount of coins in the overall game

↑ Back to top

---

currentGlobalPoints()

Returns the current amount of points in the overall game.

Returns

number the current amount of points in the overall game

↑ Back to top

---

currentLevelName()

Returns the name of the current level.

Returns

string the name of the current level

↑ Back to top

---

currentPoints()

Returns the current amount of points in the 2D/3D World.

Returns

number the current amount of points in the 2D/3D World

↑ Back to top

---

decreaseCoins(value)

Decreases the user’s coins by the amount given in value.

Parameters

number value – the amount to decrease the coins by

↑ Back to top

---

decreaseCurrentPoints(value)

Decreases the user’s points by the amount given in value.

Parameters

number value – the amount to decrease the points by

↑ Back to top

---

decreaseTotalPoints(value)

Decreases the given value from the total points in the current 2D/3D World.

Parameters

number value – the amount to decrease the total points by

↑ Back to top

---

entities()

Returns an array of all Entities in the Scene.

Returns

array – the entities in the Scene

↑ Back to top

---

find(name)

Returns the array of Entities with the specified name.

Parameters

string name – The name of the Entity to be searched for.

Returns

array The array of Entities which match that name.

let ents = this.scene().find('myObstacle');
for(let i = 0; i < ents.length; i++){
  // increase the y position of each entity
  let ent = ents[i];
  let pos = ent.position();
  ent.setPosition(pos.x, pos.y + 1, pos.z);
}

let player = this.scene().find('Character')[0]; // use this shorthand if you're confident in only getting one result from the search

↑ Back to top

---

findFirst(name)

Returns the first Entity found in the scene with the given name. Useful if you’re sure you only have one Object in the Scene with that name. Returns null if the Entity is not found.

Parameters

string name – The name of the Entity to be searched for.

Returns

Entity – the entity found with the given name

↑ Back to top

---

path()

Returns Path object of the Scene.

Returns

ScenePath the Scene’s path object

↑ Back to top

---

physicsWorld()

Returns the Scene’s PhysicsWorld object. For more information, look at the PhysicsWorld API reference page.

Returns

PhysicsWorld the Scene’s physics world object

↑ Back to top

---

purgeLevel()

Removes the current first level section.

↑ Back to top

---

pushNavigation(name)

Activates a Navigation button with the given name on the current UI, as if the user touched it.

Parameters

string name – the name of the button to push

↑ Back to top

---

rayTest(from, to)

Returns objects (AABBs) that collide with a ray between the two given Vec3 coordinates. Optionally takes a filter as the third parameter, such as: “kAll”, “kSensor”, “kEnemy”, “kPlatform”, “kCoin”, “kCharacter”.

The object returned by this function has the properties {bodies, sensors} which are each arrays. The bodies and sensors objects have the properties {object, hitPoint}.

Parameters

Vec3 from – the starting coordinate
Vec3 to – the ending coordinate
string filter – optional

Returns

Object with properties {bodies, sensors}.

// choose an object as the Selected Character with ray testing. pt is where the user tapped.

let ray = cam.screenRay(pt);
let rtst = this.scene().rayTest(
        ray.origin,
        ray.origin.add(ray.direction.scale(100))
    );
    
    for (let i = 0; i < rtst.bodies.length; ++i) {
        let hit = rtst.bodies[i];
        Settings.selectedCharacter = hit.object.parentEntity().name();
        return;
    }
    

↑ Back to top

---

restart()

Restarts the scene.

↑ Back to top

---

setBackgroundColor(r, g, b)

Sets the background color of the Scene.

Parameters

number r – the red component of the color
number g – the green component of the color
number b – the blue component of the color

↑ Back to top

---

setGravity(x, y, z)

Sets the gravity of the Scene.

Parameters

number x – the x-axis component of the new gravity
number y – the y-axis component of the new gravity
number z – the z-axis component of the new gravity

↑ Back to top

---

setScorePoint(value)

Sets the current points to the given value. Note: A coin is typically something the user can spend, while a point is not.

Parameters

number value – the new score value

↑ Back to top

---

setShadowsEnabled(enabled)

Use this function to turn shadows on or off globally. This can make your game run better on certain devices. Defaults to true (shadows on).

Parameters

boolean enabled – turn on/off shadows globally.

↑ Back to top

---

setSpeed(value)

Sets the path speed.

Parameters

number value – the new path speed

↑ Back to top

---

shadowsEnabled()

Returns whether shadows are enabled in the Scene.

Returns

boolean – true if shadows are enabled, false if not.

↑ Back to top

---

speed()

Returns the path speed.

Returns

number the current path speed

↑ Back to top

---

totalCoins()

Returns the total amount of coins in the current 2D/3D World. Note: A coin is typically something the user can spend, while a point is not.

Returns

number the total amount of coins in the current 2D/3D World

↑ Back to top

---

totalGlobalCoins()

Returns the total amount of coins in the overall game.

Returns

number the total amount of coins in the overall game

↑ Back to top

---

totalGlobalPoints()

Returns the total amount of points in the overall game.

Returns

number the total amount of points in the overall game

↑ Back to top

---

totalPoints()

Returns the total amount of points in the current 2D/3D World. Note: A coin is typically something the user can spend, while a point is not.

Returns

number the total amount of points in the current 2D/3D World

↑ Back to top

Ui

Function	Description
camera()	Returns the Ui’s Camera object. The Ui has an independent camera from the 3D world it’s attached to. It’s recommended to only use the Ui’s Camera for things like screenToWorld() (See the Camera API for more info).
create(name, parent)	Create a new Entity within the Ui based on the given asset name. A parent entity can be passed optionally.
find(name)	Returns the array of Entities, Buttons, or Images with the specified name.
playBackgroundMusic()	Plays the background music of this Ui.
stopBackgroundMusic()	Stops playing the background music of this Ui.

---

camera()

Returns the Ui’s Camera object. The Ui has an independent camera from the 3D world it’s attached to. It’s recommended to only use the Ui’s Camera for things like screenToWorld() (See the Camera API for more info).

Returns

Camera the Ui’s Camera object

↑ Back to top

---

create(name, parent)

Create a new Entity within the Ui based on the given asset name. A parent entity can be passed optionally.

Parameters

string name – the asset the new Entity should contain
Entity parent (optional) the parent of the newly created Entity

↑ Back to top

---

find(name)

Returns the array of Entities, Buttons, or Images with the specified name.

Parameters

string name – the name of the objects you wish to find

Returns

array the array of Ui objects with the specified name

↑ Back to top

---

playBackgroundMusic()

Plays the background music of this Ui.

↑ Back to top

---

stopBackgroundMusic()

Stops playing the background music of this Ui.

↑ Back to top

This is where API Reference will go