SDK3DVerse. engineAPI

Handles entities and communicates with the rendering engine.

Namespaces

cameraAPI

Methods

assignClientToScripts(…entity)

Assign client to all scripts attached to the entity. This allows the client's inputs to be used within the scripts. Specify multiple entities to attach client to the scripts of all those entities at once.

Parameters:
NameTypeAttributesDescription
entityEntity<repeatable>

Entity containing a script_map component

Example
SDK3DVerse.engineAPI.assignClientToScripts(entity);

canEdit() → {boolean}

Determines if you can make transient and persistent edits to the scene. Signifies Entity.save in addition to SDK3DVerse.engineAPI.saveEntities will function. Will always be false if not connected to the editor.

To connect to editor check the connectToEditor option when you startSession, joinSession, or joinOrStartSession.

Returns:

Return true if the scene is editable.

Type: 
boolean

(async) castScreenSpaceRay(x, y, selectEntityopt, keepOldSelectionopt, seekExternalLinkeropt, planeNormalopt, planeDistanceFromOriginopt) → {object}

Casts a ray into the scene and returns the entity, the world space position and the world space normal that the ray hits or "picks". If the ray does not hit anything, entity is null. X and Y coordinates are expected to be viewport coordinates, i.e. the same coordinate system used in certain MouseEvents (mouseup, dblclick, etc.).

If selectEntity is true, the picked entity will be broadcasted in the event onEntitySelectionChanged, and will be highlighted. If keepOldSelection is true, the previously selected entities will also be broadcasted in the event, and will also stay highlighted.

Parameters:
NameTypeAttributesDefaultDescription
xnumber

X coordinate

ynumber

Y coordinate

selectEntityboolean<optional>
false

Set to true to select entity. Selected entities are highlighted

keepOldSelectionboolean<optional>
false

Set to true to keep old selection, i.e. old selection stays highlighted

seekExternalLinkerboolean<optional>
true

Set to false to avoid selecting linkers before the picked entity

planeNormalSDK_Vec3 | null<optional>
null

If picking does not encounter any entity, an intersection is computed on a defined plane represented in Hessian normal form by a unit length normal vector and a distance. Ignored on a viewport with an orthographic projection.

planeDistanceFromOriginnumber<optional>
0

The signed distance from the origin to the plane. Ignored on a viewport with an orthographic projection.

Returns:

An object defined as follows { entity : Entity | null, pickedPosition : SDK_Vec3, pickedNormal : SDK_Vec3 }.

Type: 
object
Example
const canvas = document.getElementById('my_canvas_id');
canvas.addEventListener('mouseup', async (e) =>
{
     const selectEntity     = true;
     const keepOldSelection = e.ctrlKey;
     const {entity, pickedPosition, pickedNormal} = await SDK3DVerse.engineAPI.castScreenSpaceRay(e.clientX, e.clientY, selectEntity, keepOldSelection);
     entity ? console.log('Selected entity', entity.getName()) : console.log('No entity selected');

}, false);

(async) deleteEntities(entities)

Delete entities.

Parameters:
NameTypeDescription
entitiesArray.<Entity>

Entities to delete

(async) deleteExternalEntities(entities)

Delete external entities. They can be restored with restoreExternalEntities.

Parameters:
NameTypeDescription
entitiesArray.<Entity>

External entities to delete

detachClientFromScripts(…entity)

Detach client from all scripts attached to the entity. This stops the scripts from accessing the client's inputs. Specify multiple entities to detach client from the scripts of all those entities at once.

Parameters:
NameTypeAttributesDescription
entityEntity<repeatable>

Entity containing a script_map component

Example
SDK3DVerse.engineAPI.detachClientFromScripts(entity);

(async) detachExternalComponent(entities, componentType)

Detach component from external entities. The component can be restored with restoreExternalComponent.

Parameters:
NameTypeDescription
entitiesArray.<Entity>

External entities

componentTypestring

The component type

discardOverriddenComponent(entities, componentType)

Discard overridden component of specified type in entities.

Parameters:
NameTypeDescription
entitiesArray.<Entity>

Entities

componentTypestring

The component type

discardOverriddenComponents(entities)

Discard all overridden components of entities.

Parameters:
NameTypeDescription
entitiesArray.<Entity>

Entities

(async) findEntities(nameOrEUID, componentFilteropt) → {Array.<Entity>}

Retrieve list of entities whose name or euid matches nameOrEUID and whose components passes the specified component filter. See Components.

Parameters:
NameTypeAttributesDefaultDescription
nameOrEUIDstring

Entity name or euid

componentFilterComponentFilter<optional>
{ mandatoryComponents : [], forbiddenComponents : [] }

Component filter containing mandatory and forbidden components

Returns:

Entities that match the name or EUID and component filter.

Type: 
Array.<Entity>
Example
const componentFilter = { mandatoryComponents : ['box_geometry'], forbiddenComponents : ['rigid_body']};
const entities = await SDK3DVerse.engineAPI.findEntities('my entity name', componentFilter);

(async) findEntitiesByComponents(componentFilter) → {Array.<Entity>}

Retrieve list of entities whose components pass the specified component filter. See Components.

Parameters:
NameTypeDescription
componentFilterComponentFilter

Component filter containing mandatory and forbidden components

Returns:

Entities that pass the component filter.

Type: 
Array.<Entity>
Example
const componentFilter = { mandatoryComponents : ['physics_material', 'rigid_body'], forbiddenComponents : ['sphere_geometry'] };
const entities = await SDK3DVerse.engineAPI.findEntitiesByComponents(componentFilter);

(async) findEntitiesByEUID(euid) → {Array.<Entity>}

Find entities by their euid.

Parameters:
NameTypeDescription
euidstring

Entity uuid

Returns:

Entities with same euid.

Type: 
Array.<Entity>
Example
const entities = await SDK3DVerse.engineAPI.findEntitiesByEUID('027ed09b-4a33-49eb-b1bf-10aa5eb4c7c1');

(async) findEntitiesByNames(…entityNames) → {Array.<Entity>}

Find entities by their name. Name is case-sensitive.

Parameters:
NameTypeAttributesDescription
entityNamesstring<repeatable>

Entity names

Returns:

Entities having the specified names.

Type: 
Array.<Entity>
Example
const entities = await SDK3DVerse.engineAPI.findEntitiesByNames('my sphere', 'my cube', 'cat');

fireEvent(eventMapUUID, eventName, entitiesopt, dataObjectopt)

Fire an event found in an event map with eventMapUUID.

Parameters:
NameTypeAttributesDefaultDescription
eventMapUUIDstring

The eventMap asset UUID

eventNamestring

The event name from the eventMap

entitiesArray.<Entity><optional>
[]

Fire event only on specified entities

dataObjectobject<optional>
{}

The input data of the event. The expected object properties are defined by the input descriptor of the event in the event map.

getDefaultSceneSettings(settingsType) → {SceneSettings}

Get default readonly scene settings of specified type.

Parameters:
NameTypeDescription
settingsTypestring

The settings type

Returns:

Default readonly settings of specified type.

Type: 
SceneSettings
Example
const { gravity } = SDK3DVerse.engineAPI.getDefaultSceneSettings('physics');

getEntity(entityRTID) → {Entity}

Get entity.

Parameters:
NameTypeDescription
entityRTIDstring

Entity runtime identitifier, or rtid

Returns:

Entity.

Type: 
Entity

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

Get entities at the root of the scene.

Returns:
Type: 
Array.<Entity>

getSceneSettings(settingsType) → {SceneSettings}

Get scene settings of specified type.

Parameters:
NameTypeDescription
settingsTypestring

The settings type

Returns:

Scene settings.

Type: 
SceneSettings
Example
const { maxTextureSize, enableTextureStreaming } = SDK3DVerse.engineAPI.getSceneSetting('display');

getSceneStats() → {object}

Get scene statistics, such as the entity count and triangle count.

Returns:

An object defined as follows { entityCount : number, triangleCount : number, totalTriangleCount : number }.

  • entityCount : Entity count of scene and all its subscenes
  • triangleCount : Triangle count of scene
  • totalTriangleCount : Triangle count of scene and all its subscenes
Type: 
object

getSelectedEntities() → {Array.<Entity>}

Get all currently selected entities.

See
Returns:

Selected entities.

Type: 
Array.<Entity>

(async) instantiateEntities(parent, entityTemplates) → {Array.<Entity>}

Instantiate entities with different entity templates.

Parameters:
NameTypeDescription
parentEntity | null

The parent entity, set to null for the root

entityTemplatesArray.<EntityTemplate>

The entity templates

See
  • instantiateEntity

Returns:

The instantiated entities.

Type: 
Array.<Entity>

onEnterTrigger(callback)

Registers the callback function to the enter_trigger physics event.

Parameters:
NameTypeDescription
callbackTriggerCallback

The callback function

Example
SDK3DVerse.engineAPI.onEnterTrigger((entity, triggerEntity) =>
{
    console.log(entity, " entered trigger of ", triggerEntity);
});

onExitTrigger(callback)

Registers the callback function to the exit_trigger physics event.

Parameters:
NameTypeDescription
callbackTriggerCallback

The callback function

Example
SDK3DVerse.engineAPI.onExitTrigger((entity, triggerEntity) =>
{
    console.log(entity, " exited trigger of ", triggerEntity);
});

(async) overrideComponent(entities, componentType)

Override component of specified type in entities.

Parameters:
NameTypeDescription
entitiesArray.<Entity>

Entities

componentTypestring

The component type

pauseAnimationSequence(animationSequenceUUID, linkeropt)

Pause the animation sequence. If the animation sequence belongs to a linked scene then the linker referencing that scene must be specified.

Parameters:
NameTypeAttributesDefaultDescription
animationSequenceUUIDstring

Animation sequence UUID

linkerEntity | null<optional>
null

Linker entity. This must be specified to target an animation sequence which belongs to a linked scene

See
  • playAnimationSequence

  • stopAnimationSequence

pauseSimulation()

Pause the simulation (e.g: physics and script assets listening to the event 'start' in the system.events event map).

(async) physicsRaycast(origin, direction, rayLength, filterFlagsopt, maxNumTouchesopt) → {PhysicsRaycastResult}

Cast a ray into the physics scene and get the results of what the ray hits.

Parameters:
NameTypeAttributesDefaultDescription
originSDK_Vec3

Point in global space to cast the ray from

directionSDK_Vec3

Direction to cast the ray

rayLengthnumber

Magnitude of the ray

filterFlagsPhysicsQueryFilterFlags<optional>
SDK3DVerse.PhysicsQueryFilterFlag.dynamic_block | SDK3DVerse.PhysicsQueryFilterFlag.static_block

See more about which filter flags you can set. Dynamic and static bodies are blocking by default.

maxNumTouchesnumber<optional>
12

If SDK3DVerse.PhysicsQueryFilterFlag.record_touches was set in filterFlags, then specifies the maximum number of touches the ray records

Returns:

An object containing information on what physics body the ray was blocked by, and what other bodies it touched along the way.

Type: 
PhysicsRaycastResult
Example
const origin = [0,0,0];
const direction = [0,0,1];
const rayLength = 20;
const filterFlags = SDK3DVerse.PhysicsQueryFilterFlag.dynamic_block | SDK3DVerse.PhysicsQueryFilterFlag.record_touches;

// Returns dynamic body (if the ray hit one) in block, and all static bodies encountered along the way in touches
const { block, touches } = await SDK3DVerse.engineAPI.physicsRaycast(origin, direction, rayLength, filterFlags);

playAnimationSequence(animationSequenceUUID, settingsopt, linkeropt)

Play the animation sequence from the current offset or from a specified seek offset with a playback speed. A negative playback speed will cause the animation sequence to play in reverse. If the animation sequence belongs to a linked scene then the linker referencing that scene must be specified.

Parameters:
NameTypeAttributesDefaultDescription
animationSequenceUUIDstring

Animation sequence UUID

settingsobject<optional>

Playback settings

playbackSpeedfloat<optional>
1.0

Playback speed, can be negative to reverse play

seekOffsetfloat<optional>

The time offset to begin playing from. It's normalized in the [0.0, 1.0] range, so it's relative to the animation sequence duration. If not specified, the animation sequence will begin playing from its current offset

linkerEntity | null<optional>
null

Linker entity. This must be specified to target an animation sequence which belongs to a linked scene

See
  • pauseAnimationSequence

  • stopAnimationSequence

Example
// Play
SDK3DVerse.engineAPI.playAnimationSequence(animationSequenceUUID);
// Play in reverse
SDK3DVerse.engineAPI.playAnimationSequence(animationSequenceUUID, { playbackSpeed : -1.0 });

propagateSceneSettings(settings)

Propagate scene settings, allowing settings to be updated at runtime. Propagated scene settings are transient, meaning the scene settings will be seen by other clients, but will not be saved.

Parameters:
NameTypeDescription
settingsSceneSettingsMap

Scene settings

registerToEvent(eventMapUUID, eventName, callback)

Register callback function to the event named eventName belonging to the specified event map with UUID eventMapUUID. Event maps are assets grouping events that can be fired with fireEvent.

Parameters:
NameTypeDescription
eventMapUUIDstring

Event map UUID

eventNamestring

Name of the event

callbackfunction

Callback function

reparentEntities(entities, parent, keepGlobalTransformopt)

Reparent multiple entities to a given parent.

Parameters:
NameTypeAttributesDefaultDescription
entitiesArray.<Entity>

Entities

parentEntity

Parent entity

keepGlobalTransformboolean<optional>
true

Recalculate entity local transform after reparenting in order to preserve their previous global transform

(async) restoreExternalComponent(entities, componentType)

Restore a component in external entities that had been detached with detachExternalComponent

Parameters:
NameTypeDescription
entitiesArray.<Entity>

External entities

componentTypestring

The component type to restore

restoreExternalEntities(entities)

Restore external entities that were deleted with deleteExternalEntities.

Parameters:
NameTypeDescription
entitiesArray.<Entity>

External entities

saveEntities(entitiesopt)

Save entity-related changes, allowing modified entities to be updated at runtime as well as saved. Saved changes are persistent, meaning the modified entities will be seen by other clients of running sessions referencing this scene and saved in the scene asset.

Parameters:
NameTypeAttributesDefaultDescription
entitiesArray.<Entity> | null<optional>
null

If null, then all unsaved entities (i.e. entities that have been modified since the last call to saveEntities or Entity.save) are saved

Example
SDK3DVerse.engineAPI.saveEntities();

saveSceneSettings(settings)

Save scene settings, allowing settings to be updated at runtime as well as saved. Saved scene settings are persistent, meaning the scene settings will be seen by other clients and will be saved.

Parameters:
NameTypeDescription
settingsSceneSettingsMap

Scene settings

selectEntities(entities, keepOldSelectionopt, triggeredByopt)

Select multiple entities. Selected entities are highlighted.

Parameters:
NameTypeAttributesDefaultDescription
entitiesArray.<Entity>

Entities to select

keepOldSelectionboolean<optional>
false

Set to true to keep old selection, i.e. old selection stays highlighted

triggeredBystring<optional>
'selectEntities'

The triggeredBy string passed to event:onEntitySelectionChanged

Example
SDK3DVerse.engineAPI.selectEntities([entity1, entity2, entity3]);

startSimulation()

Start the simulation (e.g: physics and script assets listening to the event 'start' in the system.events event map).

stopAnimationSequence(animationSequenceUUID, linkeropt)

Stop the animation sequence e.g pause and reset seek offset to 0. If the animation sequence belongs to a linked scene then the linker referencing that scene must be specified.

Parameters:
NameTypeAttributesDefaultDescription
animationSequenceUUIDstring

Animation sequence UUID

linkerEntity | null<optional>
null

Linker entity. This must be specified to target an animation sequence which belongs to a linked scene

See
  • playAnimationSequence

  • pauseAnimationSequence

stopSimulation()

Stop the simulation (e.g: physics and script assets listening to the event 'start' in the system.events event map).

unregisterFromEvent(eventMapUUID, eventName, callback)

Unregister callback function from the event named eventName belonging to the specified event map with UUID eventMapUUID. Event maps are assets grouping events that can be fired with fireEvent.

Parameters:
NameTypeDescription
eventMapUUIDstring

Event map UUID

eventNamestring

Name of the event

callbackfunction

Callback function

unselectAllEntities(triggeredByopt)

Unselect all entities.

Parameters:
NameTypeAttributesDefaultDescription
triggeredBystring<optional>
'unselectAllEntities'

The triggeredBy string passed to event:onEntitySelectionChanged

Example
SDK3DVerse.engineAPI.unselectAllEntities();