Handles entities and communicates with the rendering engine.
Namespaces#
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.
Name | Type | Attributes | Description |
---|---|---|---|
entity | Entity | <repeatable> | Entity containing a script_map component |
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.
- 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.
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 | | <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 }
.
- Type:
- object
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.
Name | Type | Description |
---|---|---|
entities | Array.<Entity> | Entities to delete |
(async) deleteExternalEntities(entities)#
Delete external entities. They can be restored with restoreExternalEntities.
Name | Type | Description |
---|---|---|
entities | Array.<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.
Name | Type | Attributes | Description |
---|---|---|---|
entity | Entity | <repeatable> | Entity containing a script_map component |
SDK3DVerse.engineAPI.detachClientFromScripts(entity);
(async) detachExternalComponent(entities, componentType)#
Detach component from external entities. The component can be restored with restoreExternalComponent.
discardOverriddenComponent(entities, componentType)#
Discard overridden component of specified type in entities.
discardOverriddenComponents(entities)#
Discard all overridden components of entities.
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.
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.
- Type:
- Array.<Entity>
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.
Name | Type | Description |
---|---|---|
componentFilter | ComponentFilter | Component filter containing mandatory and forbidden components |
Entities that pass the component filter.
- Type:
- Array.<Entity>
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.
Name | Type | Description |
---|---|---|
euid | string | Entity uuid |
Entities with same euid.
- Type:
- Array.<Entity>
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.
Name | Type | Attributes | Description |
---|---|---|---|
entityNames | string | <repeatable> | Entity names |
Entities having the specified names.
- Type:
- Array.<Entity>
const entities = await SDK3DVerse.engineAPI.findEntitiesByNames('my sphere', 'my cube', 'cat');
fireEvent(eventMapUUID, eventName, targetEntitiesopt, dataObjectopt)#
Fire an event found in an event map with eventMapUUID.
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
eventMapUUID | string | The eventMap asset UUID | ||
eventName | string | The event name from the eventMap | ||
targetEntities | Array.<Entity> | <optional> | [] | Fire event only on specified target 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.
Name | Type | Description |
---|---|---|
settingsType | string | The settings type |
Default readonly settings of specified type.
- Type:
- SceneSettings
const { gravity } = SDK3DVerse.engineAPI.getDefaultSceneSettings('physics');
getEntity(entityRTID) → {Entity}#
Get entity.
Name | Type | Description |
---|---|---|
entityRTID | string | Entity runtime identitifier, or rtid |
- See
Entity.
- Type:
- Entity
(async) getRootEntities() → {Array.<Entity>}#
Get entities at the root of the scene.
- Type:
- Array.<Entity>
getSceneSettings(settingsType) → {SceneSettings}#
Get scene settings of specified type.
Name | Type | Description |
---|---|---|
settingsType | string | The settings type |
Scene settings.
- Type:
- SceneSettings
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
- Type:
- object
getSelectedEntities() → {Array.<Entity>}#
Get all currently selected entities.
- See
selectEntity
Selected entities.
- Type:
- Array.<Entity>
onEnterTrigger(callback)#
Registers the callback function to the enter_trigger
physics event.
Name | Type | Description |
---|---|---|
callback | TriggerCallback | The callback function |
SDK3DVerse.engineAPI.onEnterTrigger((entity, triggerEntity) => { console.log(entity, " entered trigger of ", triggerEntity); });
onExitTrigger(callback)#
Registers the callback function to the exit_trigger
physics event.
Name | Type | Description |
---|---|---|
callback | TriggerCallback | The callback function |
SDK3DVerse.engineAPI.onExitTrigger((entity, triggerEntity) => { console.log(entity, " exited trigger of ", triggerEntity); });
(async) overrideComponent(entities, componentType)#
Override component of specified type in entities.
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.
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.
- Type:
- PhysicsRaycastResult
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);
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.
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.
Name | Type | Description |
---|---|---|
eventMapUUID | string | Event map UUID |
eventName | string | Name of the event |
callback | function | Callback function |
SDK3DVerse.engineAPI.registerToEvent(eventMapUUID, eventName, (event) => { const { emitterEntity, dataObject } = event; console.log(`${emitterEntity} emitted the event ${eventName} with this data:`, dataObject); });
reparentEntities(entities, parent, keepGlobalTransformopt)#
Reparent multiple entities to a given parent.
(async) restoreExternalComponent(entities, componentType)#
Restore a component in external entities that had been detached with detachExternalComponent
restoreExternalEntities(entities)#
Restore external entities that were deleted with deleteExternalEntities.
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.
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
entities | Array.<Entity> | | <optional> | null | If null, then all unsaved entities (i.e. entities that have been modified since the last call to |
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.
Name | Type | Description |
---|---|---|
settings | SceneSettingsMap | Scene settings |
selectEntities(entities, keepOldSelectionopt, triggeredByopt)#
Select multiple entities. Selected entities are highlighted.
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 |
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).
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.
Name | Type | Description |
---|---|---|
eventMapUUID | string | Event map UUID |
eventName | string | Name of the event |
callback | function | Callback function |
unselectAllEntities(triggeredByopt)#
Unselect all entities.
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
triggeredBy | string | <optional> | 'unselectAllEntities' | The |
SDK3DVerse.engineAPI.unselectAllEntities();