Documentation Sign in

Namespace

engineAPI

Handles entities and communicates with the rendering engine.

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:
Name Type Attributes Description
entity Entity <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.

Return true if the scene is editable.

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:
Name Type Attributes Default Description
x number

X coordinate
y number

Y coordinate
selectEntity boolean <optional>
 false

Set to true to select entity. Selected entities are highlighted
keepOldSelection boolean <optional>
 false

Set to true to keep old selection, i.e. old selection stays highlighted
seekExternalLinker boolean <optional>
 true

Set to false to avoid selecting linkers before the picked entity
planeNormal SDK_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.
planeDistanceFromOrigin number <optional>
 0

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

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

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 computeBoundingBoxes() → {object}

Compute the bounding boxes of the scene and all its linked external scenes.

An object defined as follows { [sceneUUID]: { aabb : AABB, entities : Array.<Entity>(), parentLinker : Entity } }.

object

# async deleteEntities(entities)

Delete entities.

Parameters:
Name Type Description
entities Array.<Entity>

Entities to delete

# async deleteExternalEntities(entities)

Delete external entities. They can be restored with restoreExternalEntities.

Parameters:
Name Type Description
entities Array.<Entity>

External entities to delete

# async detachExternalComponent(entities, componentType)

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

Parameters:
Name Type Description
entities Array.<Entity>

External entities
componentType string

The component type

# discardOverriddenComponent(entities, componentType)

Discard overridden component of specified type in entities.

Parameters:
Name Type Description
entities Array.<Entity>

Entities
componentType string

The component type

# discardOverriddenComponents(entities)

Discard all overridden components of entities.

Parameters:
Name Type Description
entities Array.<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:
Name Type Attributes Default Description
nameOrEUID string

Entity name or euid
componentFilter ComponentFilter <optional>
 { mandatoryComponents : [], forbiddenComponents : [] }

Component filter containing mandatory and forbidden components

Entities that match the name or EUID and component filter.

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:
Name Type Description
componentFilter ComponentFilter

Component filter containing mandatory and forbidden components

Entities that pass the component filter.

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:
Name Type Description
euid string

Entity uuid

Entities with same euid.

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:
Name Type Attributes Description
entityNames string <repeatable>

Entity names

Entities having the specified names.

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:
Name Type Attributes Default Description
eventMapUUID string

The eventMap asset UUID
eventName string

The event name from the eventMap
entities Array.<Entity> <optional>
 []

Fire event only on specified entities
dataObject object <optional>
 {}

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

# getDefaultSceneSettings(settingsType) → {SceneSettings}

Get default readonly scene settings of specified type.

Parameters:
Name Type Description
settingsType string

The settings type

Default readonly settings of specified type.

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

# getEntity(entityRTID) → {Entity}

Get entity.

Parameters:
Name Type Description
entityRTID string

Entity runtime identitifier, or rtid
See:

Entity.

Entity

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

Get entities at the root of the scene.

Array.<Entity>

# getSceneSettings(settingsType) → {SceneSettings}

Get scene settings of specified type.

Parameters:
Name Type Description
settingsType string

The settings type

Scene settings.

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

# getSceneStats() → {object}

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

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
object

# getSelectedEntities() → {Array.<Entity>}

Get all currently selected entities.

See:

Selected entities.

Array.<Entity>

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

Instantiate entities with different entity templates.

Parameters:
Name Type Description
parent Entity | null

The parent entity, set to null for the root
entityTemplates Array.<EntityTemplate>

The entity templates
See:

  • instantiateEntity

The instantiated entities.

Array.<Entity>

# onEnterTrigger(callback)

Registers the callback function to the enter_trigger physics event.

Parameters:
Name Type Description
callback TriggerCallback

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

# onExitTrigger(callback)

Registers the callback function to the exit_trigger physics event.

Parameters:
Name Type Description
callback TriggerCallback

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

# async overrideComponent(entities, componentType)

Override component of specified type in entities.

Parameters:
Name Type Description
entities Array.<Entity>

Entities
componentType string

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:
Name Type Attributes Default Description
animationSequenceUUID string

Animation sequence UUID
linker Entity | 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).

See:

# 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:
Name Type Attributes Default Description
origin SDK_Vec3

Point in global space to cast the ray from
direction SDK_Vec3

Direction to cast the ray
rayLength number

Magnitude of the ray
filterFlags PhysicsQueryFilterFlags <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.
maxNumTouches number <optional>
 12

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

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

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:
Name Type Attributes Default Description
animationSequenceUUID string

Animation sequence UUID
settings object <optional>

Playback settings
playbackSpeed float <optional>
 1.0

Playback speed, can be negative to reverse play
seekOffset float <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
linker Entity | 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:
Name Type Description
settings SceneSettingsMap

Scene settings
See:

# 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:
Name Type Description
eventMapUUID string

Event map UUID
eventName string

Name of the event
callback function

Callback function
See:

# reparentEntities(entities, parent, keepGlobalTransformopt)

Reparent multiple entities to a given parent.

Parameters:
Name Type Attributes Default Description
entities Array.<Entity>

Entities
parent Entity

Parent entity
keepGlobalTransform boolean <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:
Name Type Description
entities Array.<Entity>

External entities
componentType string

The component type to restore

# restoreExternalEntities(entities)

Restore external entities that were deleted with deleteExternalEntities.

Parameters:
Name Type Description
entities Array.<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:
Name Type Attributes Default Description
entities Array.<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:
Name Type Description
settings SceneSettingsMap

Scene settings
See:

# selectEntities(entities, keepOldSelectionopt, triggeredByopt)

Select multiple entities. Selected entities are highlighted.

Parameters:
Name Type Attributes Default Description
entities Array.<Entity>

Entities to select
keepOldSelection boolean <optional>
 false

Set to true to keep old selection, i.e. old selection stays highlighted
triggeredBy string <optional>
 'selectEntities'

The triggeredBy string passed to event:onEntitySelectionChanged
See:
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).

See:

# 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:
Name Type Attributes Default Description
animationSequenceUUID string

Animation sequence UUID
linker Entity | 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).

See:

# 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:
Name Type Description
eventMapUUID string

Event map UUID
eventName string

Name of the event
callback function

Callback function
See:

# unselectAllEntities(triggeredByopt)

Unselect all entities.

Parameters:
Name Type Attributes Default Description
triggeredBy string <optional>
 'unselectAllEntities'

The triggeredBy string passed to event:onEntitySelectionChanged
See:
Example
SDK3DVerse.engineAPI.unselectAllEntities();