Entity

An Entity is an object that exists in your 2D/3D world.

Function Description
addChild(entity) Makes the specified entity a child of the current Entity.
camera() Returns the Camera within the world where the Entity exists. This could be a UI camera or a Scene camera.
children() Returns the array of child Entities that this Entity has.
color() Returns the color of the Entity’s 3D Model in RGBA (Red, Green, Blue, Alpha) format.
component(name) Searches for the component with the specified name in the current Entity and returns it if it’s found. Otherwise, returns null.
components() Returns an array containing all the entity’s components (also known as nodes).
createComponent(type, name) Creates a new component (Node) and activates it. Currently these components can be created programmatically: Animation, 3D Model, and If Collide.
When creating a 3D Model node this way, a mesh must be set before functions like setPosition() can be used on it.
Please see setMesh() for more notes on recommended usage.
forceInit() Forces a newly created Entity to initialize right away.
globalDepth() Returns the depth of the Entity in a 2D World.
id() Returns the Entity’s unique id. Each instance of the Entity in the Scene will have a different id.
isCharacter() Returns if the Entity is a Character (vs an Object).
isRemoved() Returns if the Entity has been removed or not.
isVisible() Returns if the Entity is visible.
level() Returns the LevelSector that the Entity exists in. This refers to the Scene Selector “level” at the bottom of the screen in a 2D/3D World.
linkedEntities() Returns the array of Entities linked to this one with the Linker.
localAABB() Returns the local “axis-aligned bounding box” for the Entity. These coordinates form a box with the minimum corner at (left, bottom, near) and the maximum corner at (right, top, far). Useful for checking the size of your Entity and for ray casting.
name() Returns the Asset name assigned to Entity.
parent() Returns the Entity’s parent, or null if it doesn’t have one.
physics() Returns the Physics Component of the Entity. null is returned if physics is not enabled for this Entity (the checkbox on the Start node).
position() Returns the Entity’s position relative to its parent. If the Entity has no parent, the result of this function will be no different than worldPosition.
remove() Removes the Entity from the Scene.
removeComponent(component) Removes the given component on the next frame.
rotation() Returns the rotation of the Entity in degrees (Vec3).
rotationQuat() Returns the rotation of the Entity in Quaternion.
scale() Returns the scale of the Entity in Vec3.
setAnimate(value) Enables/disables animation on the Entity. In this case, “animation” is referring to the position, rotation, and scale animations in the editor.
setCastShadows(value) Enables/disables shadow casting of all 3D Models within the Entity at once.
setColor(r, g, b, a) Sets the color of every 3D model within the Entity. Uses RGB (Red, Green, Blue) format. The minimum value is 0 and the maximum is 255. For example, {r:0, g:0, b:0} is black and {r:255, g:255, b:255} is white. Alpha is an optional parameter and sets the opacity of the 3D Model.
setGlobalDepth(value) Set the depth of the Entity in a 2D World.
setOpacity(value) Sets opacity of every 3D model and animation in the Entity.
setPosition(x, y, z) Sets the position of the Entity relative to the Entity’s parent. If the Entity has no parent, this sets the world position of the Entity.
setWorldPosition(x, y, z) Sets the world position of the Entity, not relative to any parent.
setReceiveShadows(value) Enables/disables shadow receiving of all 3D Models within the Entity at once.
setRotation(x, y, z) Sets the rotation value of the Entity, in degrees. This will affect the rotation of every 3D Model within the Entity.
setRotationQuat(value) Sets rotation value in Quaternion.
setScale(x, y, z) Sets the scale of the Entity. This will affect the scale of every 3D Model within the Entity.
setTexture(name) Applies a new texture to all 3D Models within the Entity. The texture should be present in Sprite Editor.
setVisible(value) Sets the visibility of the Entity; true if the Entity is visible, false if not.
transform() Returns the transformation matrix of the Entity.
transformedAABB() Returns the relative “axis-aligned bounding box” for the Entity. These coordinates form a box with the minimum corner at (left, bottom, near) and the maximum corner at (right, top, far). Useful for checking the size of your Entity relative to its parent, and for ray casting.
transformedOBB() Returns the “oriented bounding box” for the Entity relative to its parent. OBB is more precise but more performance-heavy than AABB.
worldAABB() Returns the world (absolute) “axis-aligned bounding box” for the Entity. These coordinates form a box with the minimum corner at (left, bottom, near) and the maximum corner at (right, top, far). Useful for checking the size of your Entity and for ray casting.
worldOBB() Returns the “oriented bounding box” for the Entity. OBB is more precise but more performance-heavy than AABB.
worldPosition() Returns the entity’s position coordinates in the world (absolute position).

addChild(entity)

Makes the specified entity a child of the current Entity.

Entity entity the Entity object that will become the child of the Entity you’re calling the method on.

let ent = this.scene().create('Cone');
this.entity().addChild(ent);

↑ Back to top


camera()

Returns the Camera within the world where the Entity exists. This could be a UI camera or a Scene camera.

Returns

Camera The Camera within the world where the Entity exists.

↑ Back to top


children()

Returns the array of child Entites that this Entity has.

Returns

array The array of children Entities that this Entity has.

let children = this.entity().children();
// reset position of all children
for (i = 0; i <children.length; i++){
  children[i].setPosition(0, 0, 0);
}

↑ Back to top


color()

Returns the color of the Entity’s 3D Model in RGBA (Red, Green, Blue, Alpha) format. The minimum value is 0 and the maximum is 255. For example, {r:0, g:0, b:0, a:1} is black and {r:255, g:255, b:255, a:1} is white.
Note, if the Entity has multiple 3D Model nodes, this function will return the color of the first one that was created.

Returns

Object {r, g, b, a} color pigment of the Entity’s 3D Model.

let ent = this.scene().create("Cube");
log(ent.color().r); // result: the red component of the cube's color.

↑ Back to top


component(name)

Searches for the component with the specified name in the current Entity and returns it if it’s found. Otherwise, returns null. Note that if you have multiple components with the same name, component() will simply return the first one it finds. It’s advised to give your components unique names to avoid bugs.

Parameters

string name – The name of the component to search for.

Returns

Component The Component object found with the given name.

let collide = this.entity().component('If Collide');
if(collide){ // check that collide is not null
  let obj = collide.collisionObject();
}

↑ Back to top


components()

Returns an array containing all the components in the Entity’s mind map.

Returns

Array – array of components

↑ Back to top


createComponent(type, name)

Creates a new component (Node) and activates it. Currently these components can be created programmatically: Animation, 3D Model, and If Collide.
When creating a 3D Model node this way, a mesh must be set before functions like setPosition() can be used on it.
Please see setMesh() for more notes on recommended usage.

Parameters

string type – Possible inputs: “Animation”, “3D Model”, or “If Collide”
string name – The name of the new component.

Returns

Component the newly created component (Animation, 3D Model, or If Collide).

let modelComp = this.entity().createComponent("3D Model", "myModel");
modelComp.setMesh(this.attribute("meshAttribute"));
modelComp.setPosition(0, 10, 0); // now that a mesh is set, any Model 3D functions can be used

let animComp = this.entity().createComponent("Animation", "myAnim");
animComp.setAnimation(this.attribute("bounceAnimation"));

let collideComp = this.entity().createComponent("If Collide", "myCollide");
collideComp.setActive(true);

↑ Back to top


forceInit()

Normally Entities are initialized (which includes running their scripts’ init() functions) on the next frame. Calling this function on a newly created Entity will initialize right away instead. This can be useful if you have variables or functions being created in the Entity’s init() function that will need to be accessed immediately by the Entity creating it. Check out the simple example below.

// first entity
function start(){
    let ent = this.scene().create('Enemy');
    ent.forceInit();
    // without forceInit(), this call would fail because ent isn't initialized yet:
    ent.testFunction("Hello World");
}

// spawned entity
function init(){
    this.entity().testFunction = (string) => log(string); // logs the string passed to it
}

↑ Back to top


globalDepth()

Returns the global depth of the Entity. 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 Entity

↑ Back to top


id()

Returns the Entity’s unique id. Each instance of the Entity in the Scene will have a different id, including Entities that are made using this.scene().create().

Returns

number – the Entity’s id

↑ Back to top


isCharacter()

Returns if the Entity is a Character (vs an Object).

Returns

boolean true if the Entity is a Character, false if the Entity is not.

↑ Back to top


isRemoved()

Returns if the Entity has been removed or not.

Returns

boolean true if the Entity is has been removed, false if not.

↑ Back to top


isVisible()

Returns if the Entity is visible.

Returns

boolean true if the Entity is visible, false if the Entity is not.

↑ Back to top


level()

Returns the LevelSector that the Entity exists in. This refers to the Scene Selector “level” at the bottom of the screen in a 2D/3D World.

Returns

LevelSector The LevelSector that the Entity exists in.

// remove all cubes from level 5
let cubes = this.scene().find("Cube");
for (int i=0; i<cubes.length; i++){
  if (cubes[i].level().name() == "5"){
    cubes[i].remove();
  }
}

↑ Back to top


linkedEntities()

Returns the array of Entities linked to this one with the Linker.

Returns

Array of Entities linked to this one.

↑ Back to top


localAABB()

Returns the local “axis-aligned bounding box” for the Entity. These coordinates form a box with the minimum corner at (left, bottom, near) and the maximum corner at (right, top, far). Useful for checking the size of your Entity and for ray casting.

Returns

AABB AABB object containing relative AABB data

↑ Back to top


name()

Returns the Asset name assigned to Entity.

Returns

string name of the Asset assigned to the Entity.

↑ Back to top


parent()

Returns the Entity’s parent, or null if it doesn’t have one.

Returns

Entity the parent Entity of this Entity, or null if no parent exists.

let parent = this.entity().parent();

↑ Back to top


physics()

Returns the Physics Component of the Entity. null is returned if physics is not enabled for this Entity (the checkbox on the Start node).

Returns

Physics Component the Physics Component of the entity

let physics = this.entity().physics();
if(physics){ // check that physics is not null
  physics.setLinearVelocity(0, 20, 0);
}

↑ Back to top


position()

Returns the Entity’s position relative to its parent. If the Entity has no parent, the result of this function will be no different than worldPosition.

Returns

Vec3 {x, y, z} relative coordinates of the Entity.

let pos = this.entity().position();
log('X position = ' + pos.x);

↑ Back to top


remove()

Removes the Entity from the Scene. Note that if you try to access this Entity after it has been removed, you’ll get a null reference error. To protect from this, check this.entity().isRemoved() first.

//Remove an entity if it goes further than 10 units on the X axis.
let pos = this.entity().position()
if(pos.x > 10){
  this.entity().remove();
}

↑ Back to top


removeComponent(component)

Removes the given component on the next frame. The component object is required as a parameter; this can be found by name with this.entity().component(name) for example.

Parameters

Component component The component to remove

↑ Back to top


rotation()

Returns the rotation of the Entity in degrees (Vec3).

Returns

Vec3 The {x, y, z} rotation value of the Entity, in degrees.

↑ Back to top


rotationQuat()

Returns the rotation of the Entity in Quaternion.

Returns

Quaternion The rotation value in Quaternion.

↑ Back to top


scale()

Returns the scale of the Entity in Vec3.

Returns

Vec3 The {x, y, z} scale value of the Entity.

↑ Back to top


setAnimate(value)

Enables/disables animation on the Entity. In this case, “animation” is referring to the position, rotation, and scale animations in the editor.

Parameters

boolean value – True if enabled, false if disabled.

↑ Back to top


setCastShadows(value)

Enables/disables shadow casting of all 3D Models within the Entity at once.

Parameters

boolean value – True if enabled, false if disabled.

↑ Back to top


setColor(r, g, b, a)

Sets the color of every 3D model within the Entity. Uses RGB (Red, Green, Blue) format. The minimum value is 0 and the maximum is 255. For example, {r:0, g:0, b:0} is black and {r:255, g:255, b:255} is white. Alpha is an optional parameter and sets the opacity of the 3D Model.

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
number a – (Optional) The alpha component of the color. Range: 0-255

↑ Back to top


setGlobalDepth(value)

Sets the global depth of the Entity. 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 Entity

↑ Back to top


setOpacity(value)

Sets opacity of every 3D model and animation in the Entity.

Parameters

number value – Range: 0-1. The lower the value, the less opaque the Entity becomes.

↑ Back to top


setPosition(x, y, z)

Sets the position of the Entity relative to the Entity’s parent. If the Entity has no parent, this sets the world position of the Entity.

Parameters

number x – X coordinate in 3D space
number y – Y coordinate in 3D space
number z – Z coordinate in 3D space

↑ Back to top


setWorldPosition(x, y, z)

Sets the world position of the Entity, not relative to any parent.

Parameters

number x – X coordinate in 3D space
number y – Y coordinate in 3D space
number z – Z coordinate in 3D space

↑ Back to top


setReceiveShadows(value)

Enables/disables shadow receiving of all 3D Models within the Entity at once.

Parameters

boolean value – True if enabled, false if disabled.

↑ Back to top


setRotation(x, y, z)

Sets the rotation value of the Entity, in degrees. This will affect the rotation of every 3D Model within the Entity. Note that if you go past 360 degrees in either direction, the rotation will reset back to under 360 to avoid numbers getting extremely large. For example, if you pass 365 to this function and then checked the rotation with this.entity().rotation();, it would return 5.

Parameters

number x – the X rotation of the Entity
number y – the Y rotation of the Entity
number z – the Z rotation of the Entity

↑ Back to top


setRotationQuat(value)

Sets rotation value in Quaternion.

Parameters

Quaternion value – The Quaternion rotation value to be set

↑ Back to top


setScale(x, y, z)

Sets the scale of the Entity. This will affect the scale of every 3D Model within the Entity.

Parameters

number x – The scale of the Entity on the x axis
number y – The scale of the Entity on the y axis
number z – The scale of the Entity on the z axis

↑ Back to top


setTexture(name)

Applies a new texture to all 3D Models within the Entity. The texture should be present in Sprite Editor.

Parameters

string name – The name of the texture to be applied.

if(health <= 0.5){
  this.entity().setTexture('Damaged Texture');
}

↑ Back to top


setVisible(value)

Sets the visibility of the Entity; true if the Entity is visible, false if not.

Parameters

boolean value – the visibility of the Entity.

↑ Back to top


transform()

Returns the transformation matrix of the Entity.

Returns

Mat4 the Mat4 transformation matrix of the Entity.

↑ Back to top


transformedAABB()

Returns the relative “axis-aligned bounding box” for the Entity. These coordinates form a box with the minimum corner at (left, bottom, near) and the maximum corner at (right, top, far). Useful for checking the size of your Entity relative to its parent, and for ray casting.

Returns

AABB AABB object containing relative AABB data

↑ Back to top


transformedOBB()

Returns the “oriented bounding box” for the Entity relative to its parent. OBB is more precise but more performance-heavy than AABB.

Returns

OBB OBB object containing relative OBB data

↑ Back to top


worldAABB()

Returns the world (absolute) “axis-aligned bounding box” for the Entity. These coordinates form a box with the minimum corner at (left, bottom, near) and the maximum corner at (right, top, far). Useful for checking the size of your Entity and for ray casting.

Returns

AABB AABB object containing world AABB data

↑ Back to top


worldOBB()

Returns the “oriented bounding box” for the Entity. OBB is more precise but more performance-heavy than AABB.

Returns

OBB OBB object containing OBB data

↑ Back to top


worldPosition()

Returns the entity’s position coordinates in the world (absolute position).

Returns

Vec3 the {x, y, z} world coordinates of the Entity

let pos = this.worldPosition();
log('X World Position = ' + pos.x);

↑ Back to top

Did you find this page useful?

Please give it a rating:

Please provide some feedback!

This is very helpful to us.

Tell us how we can improve this post?