Class: Entity

Methods

attachComponent(componentType, componentValue)

Attach component to the entity. If the component is already attached, do nothing.

Parameters:

Name	Type	Description
`componentType`	string	Component type
`componentValue`	object	Component value

Fires:

event:onEntitiesUpdated

Example

const meshUUID = 'b9936cb6-0e73-4398-a06f-0355d8a96fca';
const meshRefComponent = { value : meshUUID, submeshIndex : 0 };
entity.attachComponent('mesh_ref', meshRefComponent);

detachComponent(componentType)

Detach component from the entity. If the component is not attached to the entity, do nothing.

Parameters:

Name	Type	Description
`componentType`	string	Component type

Example

entity.detachComponent('mesh_ref');

getAncestors() → {Array.<Entity>}

Get the entity's ancestors. The ancestors are returned in ascending order, i.e. beginning with the entity's direct parent and ending with its highest ancestor.

Returns:

Entity's ancestors.

Type:: Array.<Entity>

(async) getChildren() → {Array.<Entity>}

Get the direct children of the entity. To get all of its descendants, you must call this function recursively.

Returns:

Entity's direct children.

Type:: Array.<Entity>

getComponent(componentType) → {object}

Get the specified component's value.

Parameters:

Name	Type	Description
`componentType`	string	Component type

Returns:

Specified component's value.

Type:: object

Example

const localTransform = entity.getComponent('local_transform');
// do something with localTransform.position

getComponents() → {object}

Get components attached to the entity.

Returns:

A collection of keys and values, where key is the component type and its value is the corresponding component value.

Type:: object

Example

const components = entity.getComponents();
for(const componentType in components)
{
     const componentValue = components[componentType];
     // do something with componentType, componentValue
}

getComponentTypes() → {Array.<string>}

Get the types of all the components attached to the entity.

Returns:

Component types.

Type:: Array.<string>

Example

const componentTypes = entity.getComponentTypes();
// componentTypes = ['debug_name', 'local_transform', ...]

getEUID() → {string}

Get entity UUID. This identifier can be shared by multiple instances of the same entity, across linked scenes.

Returns:

Entity UUID.

Type:: string

getExternalComponentState(componentType) → {ExternalComponentState}

Get the component state of an external entity.

Parameters:

Name	Type	Description
`componentType`	string	The component type

Returns:

External component state.

Type:: ExternalComponentState

Example

const materialIsOverridden = entity.getExternalComponentState('material') === 'overridden';

getExternalState(componentType) → {ExternalEntityState}

Get the state of an external entity.

Parameters:

Name	Type	Description
`componentType`	string	The component type

Returns:

External entity state.

Type:: ExternalEntityState

Example

const entityIsOverridden = entity.getExternalState() === 'overridden';

getGlobalAABB() → {AABB}

Calculate and return the entity's global AABB, or Axis Aligned Bounding Box. If the entity doesn't have a local AABB, a default local AABB of { min : [-1, -1, -1], max : [1, 1, 1] } is used in the calculation of its global AABB.

Returns:

Global AABB.

Type:: AABB

Example

const aabb = entity.getGlobalAABB();
// The minimum point of the aabb is aabb.min[0], aabb.min[1], aabb.min[2]
// The maximum point of the aabb is aabb.max[0], aabb.max[1], aabb.max[2]

getGlobalMatrix(stopAtParentopt) → {mat4}

Get the global matrix of the entity.

Parameters:

Name	Type	Attributes	Default	Description
`stopAtParent`	Entity \| null	<optional>	null	An ancestor of the entity. If specified, returns the global matrix of the entity relative to this ancestor entity's local space

Returns:

Global matrix.

Type:: mat4

getGlobalTransform(stopAtParentopt) → {Transform}

Get the global transform of the entity.

Parameters:

Name	Type	Attributes	Default	Description
`stopAtParent`	Entity \| null	<optional>	null	An ancestor of the entity. If specified, returns the global transform of the entity relative to this ancestor entity's local space

Returns:

Global transform.

Type:: Transform

getID() → {string}

Get the entity's rtid, or unique runtime identifier. This identifier is the unique way to target a specific entity instance.

Returns:

rtid.

Type:: string

getLocalMatrix() → {mat4}

Get the local matrix of the entity.

Returns:

Local matrix.

Type:: mat4

getName(defaultNameopt) → {string}

Get the entity's name stored in the debug_name component.

Parameters:

Name	Type	Attributes	Default	Description
`defaultName`	boolean	<optional>	true	If false, an empty string is returned if the entity does not have a debug_name component attached. If true, "No name" would be returned in that case.

Returns:

Entity's name.

Type:: string

getParent() → {Entity}

Get the entity's parent.

Returns:

Entity's parent.

Type:: Entity

getRootLinker() → {Entity|null}

Get root linker (i.e. entity with scene_ref component) of this entity.

Returns:

Root linker, or null if entity isn't external.

Type:: Entity | null

hasChildren() → {boolean}

Check if the entity has children.

Returns:

Has children state.

Type:: boolean

hasParent() → {boolean}

Check if the entity has a parent.

Returns:

Has parent state.

Type:: boolean

isAttached(componentType) → {boolean}

Return true if the specified component is attached to the entity.

Parameters:

Name	Type	Description
`componentType`	string	Component type

Returns:

Attached component state.

Type:: boolean

Example

const hasRigidbody = entity.isAttached('rigid_body');

isExternal() → {boolean}

Return true if the entity belongs to another scene.

Returns:

External state.

Type:: boolean

isSame(entity) → {boolean}

Return true if the entity is the same instance of the specified entity, i.e. they have the same rtid.

Parameters:

Name	Type	Description
`entity`	Entity

Returns:

Entity parity.

Type:: boolean

isSelected() → {boolean}

Return true if the entity is currently selected. This state can be changed by calling select and unselect.

Returns:

Selected state.

Type:: boolean

isTransient() → {boolean}

Return true if the entity is a transient entity.

See: createTransientEntity

Returns:

Transient state.

Type:: boolean

isVisible() → {boolean}

Check whether or not the entity is visible. This state can be changed by calling setVisibility.

Returns:

Visibility state.

Type:: boolean

lookAt(target)

Set the global orientation to make the entity look at the target point.

Parameters:

Name	Type	Description
`target`	SDK_Vec3	Point to look at in global space

Fires:

event:onEntitiesUpdated

(async) reparent(parent, keepGlobalTransformopt)

Reparent entity to a given parent.

Parameters:

Name	Type	Attributes	Default	Description
`parent`	Entity			Parent entity
`keepGlobalTransform`	boolean	<optional>	true	Recalculate entity local transform after reparenting in order to preserve their previous global transform

Fires:

save()

Save the entity in the scene asset. Updates the entity in all running sessions of the scene. To save multiple entities at once, it is recommended to use SDK3DVerse.engineAPI.saveEntities.

select(keepOldSelectionopt, triggeredByopt)

Select entity. The entity will become highlighted.

Parameters:

Name	Type	Attributes	Default	Description
`keepOldSelection`	boolean	<optional>	false	Set to true to keep old selection, i.e. old selection stays highlighted
`triggeredBy`	string	<optional>	'select'	The `triggeredBy` string passed to event:onEntitySelectionChanged

See: unselect

Fires:

event:onEntitySelectionChanged

Example

entity.select();

setComponent(componentType, componentValue)

Set the specified component's value. If the component is not attached to the entity, do nothing.

Parameters:

Name	Type	Description
`componentType`	string	Component type
`componentValue`	object	Component value

Fires:

event:onEntitiesUpdated

Example

const materialUUID = 'b9936cb6-0e73-4398-a06f-0355d8a96fca';
const materialRef = { value : materialUUID };
entity.setComponent('material_ref', materialRef);

setGlobalTransform(globalTransform)

Set the entity's global transform. The expected transform properties are optional. For example, to only set global position (and not orientation and scale) you can specify a Transform that only has a position property.

Parameters:

Name	Type	Description
`globalTransform`	Transform	Global transform

Fires:

event:onEntitiesUpdated

Example

const transform =
{
     position : [0,0,0],
     orientation : [0,0,0,1],
     scale : [1,1,1]
};
entity1.setGlobalTransform(transform);
entity2.setGlobalTransform({ position : [0, 0, 0] });

setOrAttachComponent(componentType, componentValue)

Set the specified component's value. If the component is not attached to the entity, attach the component and set the specified value.

Parameters:

Name	Type	Description
`componentType`	string	Component type
`componentValue`	object	Component value

Fires:

event:onEntitiesUpdated

Example

const materialUUID = 'b9936cb6-0e73-4398-a06f-0355d8a96fca';
const materialRef = { value : materialUUID };
entity.setOrAttachComponent('material_ref', materialRef);

setScriptInputValues(scriptUUID, inputValues)

Set input values of a script attached to the entity. If entity does not have a script_map component, do nothing.

Parameters:

Name	Type	Description
`scriptUUID`	string	Script UUID
`inputValues`	object	Input values of script. The inputs that were specified will have their values updated. An object in the form `{ inputName : inputValue, ... }`

Fires:

event:onEntitiesUpdated

Example

entity.setScriptInputValues(scriptUUID, { walkSpeed : 1, runSpeed : 5 });

(async) setVisibility(isVisible)

Set visibility.

Parameters:

Name	Type	Description
`isVisible`	boolean	Set to false if entity should be hidden, true otherwise.

Fires:

event:onEntityVisibilityChanged

unselect(triggeredByopt)

Unselect entity. If the entity was selected, the entity will become unhighlighted.

Parameters:

Name	Type	Attributes	Default	Description
`triggeredBy`	string	<optional>	'unselect'	The `triggeredBy` string passed to event:onEntitySelectionChanged

See: select

Fires:

event:onEntitySelectionChanged

Example

entity.unselect();