Handles entities and communicates with the rendering engine.
Namespace
engineAPI
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. |
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.
# 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:
# 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. |
# 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.
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.
# getSceneSettings(settingsType) → {SceneSettings}
Get scene settings of specified type.
Parameters:
Name | Type | Description |
---|---|---|
settingsType |
string
|
The settings type |
Scene settings.
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 subscenestriangleCount
: Triangle count of scenetotalTriangleCount
: Triangle count of scene and all its subscenes
object
# getSelectedEntities() → {Array.<Entity>}
Get all currently selected entities.
- See:
-
selectEntity
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:
# 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).
# 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 |
An object containing information on what physics body the ray was blocked by, and what other bodies it touched along the way.
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 |
# 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 |
# 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 |
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 |
# 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 |
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:
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).
# 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 |
- See:
Example
SDK3DVerse.engineAPI.unselectAllEntities();