Entity

Entity

An Entity is a generic container of data.
This data is wrapped in Components, which usually provide isolated features (transforms, geometries, materials, scripts and so on).
By setting components to an entity, the entity will get the functionality provided by the components.
For example, an entity with a TransformComponent and a LightComponent will be a light source in 3D space.
Note that when attaching components to an entity, methods of the component will be injected into the entity, extending its interface.

Constructor

new Entity(world, nameopt, idopt)

Parameters:
Name Type Attributes Description
world World

The World this entity will be part of after calling .addToWorld().

name string <optional>

Entity name.

id number <optional>

Entity id.

Members

_scriptContext

Contains the script context for this entity. Created on demand.

isOccluded :boolean

True if the entity is occluded by other objects (only for 'DynamicOcclusion' culling mode)

isVisible :boolean

True if the entity is within the frustum and not occluded

name

Sets the entity's name.

name

Returns the entity's name.

publicEntity

Gets the public api Entity object for this internal api Entity object.

skip :boolean

Set to true to skip all processing (rendering, script updating, et cetera) of the entity.

Default Value:
  • false

static :boolean

Mark entity as static.
Non static entities become roots in the tree of combined ones so one can have statics under a moving node that
combines but you can still move the parent node.

Default Value:
  • false

Methods

(static) addRotation(rotation) → {Entity}

Rotates the entity with the given amount. Injected on entities with a transformComponent

Parameters:
Name Type Description
rotation Vector3 | Array.<number>

(static) addTranslation(translation) → {Entity}

Translates the entity with the given amount. Injected on entities with a transformComponent

Parameters:
Name Type Description
translation Vector3 | Array.<number>

(static) attachChild(childEntity, keepTransform) → {Entity}

Attaches the supplied entity to this entity as a child. Injected on entities with a transformComponent

Parameters:
Name Type Description
childEntity Entity
keepTransform boolean

If enabled will preserve the world transform of the child entity

(static) children() → {EntitySelection}

Returns an EntitySelection of the children of this entity. Injected on entities with a transformComponent

(static) detachChild(childEntity, keepTransform) → {Entity}

Detaches the supplied entity from this entity. Injected on entities with a transformComponent

Parameters:
Name Type Description
childEntity Entity
keepTransform boolean

If enabled will preserve the world transform of the child entity

(static) forPublicEntity(publicEntity) → {Entity}

Gets the internal api Entity object for a specified public api Entity object.

Parameters:
Name Type Description
publicEntity PublicEntity

The public api Entity object.

(static) getRotation() → {Vector3}

Returns the local rotation of the entity. Injected on entities with a transformComponent

(static) getScale() → {Vector3}

Returns the local scale of the entity. Injected on entities with a transformComponent

(static) getTranslation() → {Vector3}

Returns the local translation of the entity. Injected on entities with a transformComponent

(static) hide() → {Entity}

Hides the entity and its children. Injected on entities with a transformComponent

(static) isHidden() → {boolean}

Returns the 'hidden' status of this entity. The entity may still be hidden if one of its ancestors is hidden.
Injected on entities with a transformComponent

(static) isVisiblyHidden() → {boolean}

Returns whether the entity or any of its ancestors are hidden. Injected on entities with a transformComponent

(static) lookAt(lookAtPoint) → {Entity}

Orients the entity so it faces the supplied look at point. Injected on entities with a transformComponent

Parameters:
Name Type Description
lookAtPoint Vector3 | Array.<number>

(static) move(translation) → {Entity}

Translates the entity with the supplied amount multipled by the entity's orientation. Injected on entities with a
transformComponent

Parameters:
Name Type Description
translation Vector3 | Array.<number>

(static) parent() → {EntitySelection}

Returns an EntitySelection of the parent of this entity. Injected on entities with a transformComponent

(static) setRotation(angle) → {Entity}

Sets the rotation of this entity. Injected on entities with a transformComponent

Parameters:
Name Type Description
angle Vector3 | Array.<number>

rotation angles, in radians.

(static) setScale(scale) → {Entity}

Sets the scale of this entity. Injected on entities with a transformComponent

Parameters:
Name Type Description
scale Vector3 | Array.<number>

(static) show() → {Entity}

Clears the hidden flag on this entity. The entity may still not show if it has a hidden ancestor. Injected on
entities with a transformComponent

(static) traverse({@function, levelopt) → {Entity}

Traverses the entity hierarchy downwards starting from this entity and applies a function to all entities
traversed. Traversal can be stopped if the function returns 'false'. Injected on entities with a
transformComponent

Parameters:
Name Type Attributes Default Description
{@function

(entity: Entity, level: number) : boolean} callback The function to be applied to traversed
entities. Takes an entity and the current deph level and returns a boolean.
If call back return true/object: traverse the rest of the tree
If call back return false: stop traverse the rest of the tree

level number <optional>
0

(static) traverseUp({@function) → {Entity}

Traverses the entity hierarchy upwards starting from this entity and applies a function to all entities traversed.
Traversal can be stopped if the function returns 'false'.
Injected on entities with a transformComponent

Parameters:
Name Type Description
{@function

(entity: Entity) : boolean} callback The function to be applied to traversed entities. Takes an
entity and returns a boolean.

addToWorld(recursiveopt) → {Entity}

Add the entity to the world, making it active and processed by systems and managers.

Parameters:
Name Type Attributes Default Description
recursive boolean <optional>
true

Add children of the transform hierarchy recursively.

clearAttribute(attribute) → {Entity}

Clears an attribute of the entity.

Parameters:
Name Type Description
attribute string

clearComponent(type) → {Entity}

Remove a component of a specific type from entity.

Parameters:
Name Type Description
type string

Type of component to remove (eg. 'meshDataComponent').

clearData(key) → {Entity}

Removes a value from the script context's entityData map.

Parameters:
Name Type Description
key string

The name of the value to remove from entityData.

clearTag(tag) → {Entity}

Clears a tag on an entity.

Parameters:
Name Type Description
tag string
Example
// Remove 'alive' tag if hit points drops to zero
if (hero.getAttribute('hit-points') <= 0) {
    hero.clearTag('alive');
}

getAttribute(attribute) → {*}

Gets the value of the specified attribute.

Parameters:
Name Type Description
attribute string
Example
// Check hit points on monster entity
if (monster.getAttribute('hit-points') <= 0) {
    console.log('The hero triumphs!');
}

getComponent(type) → {Component}

Retrieve a component of a specific type.

Parameters:
Name Type Description
type string

Type of component to retrieve (eg. 'transformComponent').

getComponents() → {Array.<Component>}

Get all the components attached to this entity.

getData(key) → {Object|undefined}

Retrieves a value from the script context's entityData map.

Parameters:
Name Type Description
key string

The name of the value to lookup in entityData.

hasAttribute(attribute) → {boolean}

Checks whether an entity has an attribute or not.

Parameters:
Name Type Description
attribute string

hasComponent(type) → {boolean}

Checks if a component of a specific type is present or not.

Parameters:
Name Type Description
type string

Type of component to check for (eg. 'meshDataComponent').

hasTag(tag) → {boolean}

Checks whether an entity has a tag or not.

Parameters:
Name Type Description
tag string
Example
if (banana.hasTag('yellow')) {
    console.log('The banana is yellow');
}

removeFromWorld(recursiveopt) → {Entity}

Remove entity from the world.

Parameters:
Name Type Attributes Default Description
recursive boolean <optional>
true

Remove children of the transform hierarchy recursively.

resetData()

Resets the entity's script context entityData object to its initial
(empty) state.

set() → {Entity}

Sets components on the entity or tries to create and set components out of the supplied parameters.

Example
// Create three entities with different components, add them to world
var sphereEntity = new Entity(world).set(sphere, material, [2, 0, 0]).addToWorld();
var lightEntity = new Entity(world).set(light, [0, 1, 0]).addToWorld();
var spinningEntity = new Entity(world).set(box, material, [-2, 0, 0], script).addToWorld();

setAttribute(attribute, value) → {Entity}

Sets an attribute and its value on the entity.

Parameters:
Name Type Description
attribute string
value
Example
// Create an entity with tags and attributes, and add it to world
var hero = world.createEntity()
                .setTag('hero')
                .setAttribute('hit-points', 30)
                .setAttribute('attack-power', 3)
                .setTag('alive')
                .addToWorld();

setComponent(component) → {Entity}

Set component of a certain type on entity. The operation has no effect if the entity already contains a component
of the same type.

Parameters:
Name Type Description
component Component

Component to set on the entity.

setData(key, value) → {Entity}

Sets a value in the script context's entityData map.

Parameters:
Name Type Description
key string

The name to associate with the data for future lookup.

value Object

The data to be stored.

setTag(tag) → {Entity}

Adds a tag to the entity.

Parameters:
Name Type Description
tag string
Example
var banana = world.createEntity().setTag('fruit').setTag('green');

toString() → {string}

validateReplaceTo(replaceToEntity, recursive)

Validate if this entity can be replaced to replaceToEntity

Parameters:
Name Type Description
replaceToEntity Entity

target to replace to

recursive Boolean

replace recursively or not

Throws:

Error if any component in this entity or entity children cannot be replaced to the component in replaceToEntity, it will throw exception.