Namespace: SDK3DVerse

Handles the starting and joining of sessions. See the following methods: startSession, joinSession, joinOrStartSession. These are the entry points of any 3dverse app.

Namespaces

engineAPI
notifier

Members

(readonly) cameraControllerType :object

Readonly object which contains the available camera controller types.

For more information on the navigation controls of these controllers, use the Scene Editor, or check the Scene Editor doc. The 'Enable Camera Orbit' icon in the Scene Editor's Canvas toolbar can be toggled to switch between the Orbital and Editor camera controllers. The 'Help' icon in the Canvas toolbar provides more information on the navigation controls.

Type:

object

Properties

Name	Type	Default	Description
`none`	int	-1
`orbit`	int	1	Orbital camera controller. Camera rotates around point that is clicked but can also move around in 3D world
`editor`	int	4	Editor camera controller. Camera moves freely in 3D world and can look around. It's the default camera controller

See: setViewports
setControllerType

Example

SDK3DVerse.cameraControllerType.editor

(readonly) PhysicsQueryFilterFlag :object

Readonly object which contains the bit flags used to apply a filter on physics bodies hit by physicsRaycast.

A physics body encountered by a ray can be either considered as:

a block (stopping the ray when the ray hits it), or
a touch (non-blocking, i.e. allowing the ray to pass through it)

The flags specify which physics body types block the ray, and whether the non-blocking body types should be returned as touches in the PhysicsRaycastResult. There are two physics body types considered:

static (for static bodies), and
dynamic (for rigid bodies and kinematic rigid bodies)

Type:

object

Properties

Name	Type	Default	Description
`dynamic_block`	number	2	Dynamic bodies are blocking
`static_block`	number	4	Static bodies are blocking
`distance_agnostic_block`	number	1	This is a performance hint. Specifies there is no need to look for the closest block - any blocking body along the ray's path is returned as block. Touches aren't recorded
`record_touches`	number	8	Ray records non-blocking bodies on its path as touches. Ignored if specified with distance_agnostic_block

See: physicsRaycast
PhysicsQueryFilterFlags

Example

SDK3DVerse.PhysicsQueryFilterFlag.dynamic_block

Methods

disableInputs()

Disable input events on canvas (mouse/keyboard/gamepad). This will impact onMouseEvent, and disable any camera controller that is used by a Viewport camera.

Example

SDK3DVerse.disableInputs();

(async) disconnectFromSession()

Disconnect from the session that was previously started or joined with one of the following calls: startSession, joinSession, joinOrStartSession. Note: this only removes the current client from the ongoing session.

If there are other clients in the session, the session will still run, but if the session does not have any other clients in it, it will close automatically.

Fires:

event:onConnectionClosed

Example

await SDK3DVerse.disconnectFromSession();

enableInputs()

Enable input events on the canvas (mouse/keyboard/gamepad). This should be used after an explicit call to disableInputs as inputs are enabled by default.

Example

SDK3DVerse.enableInputs();

(async) findSessions(params) → {Array.<SessionInfo>}

Get the list of sessions already open for a given scene. Can be used to get the session id of a particular session you want to join using joinSession.

Parameters:

Name	Type	Description
`params`	object
`userToken`	string	3dverse user token or public token
`sceneUUID`	string	UUID of scene

Returns:

Array of SessionInfo. Each SessionInfo element pertains to a session open on the scene with params.sceneUUID.

Type:: Array.<SessionInfo>

Example

const sessions = await SDK3DVerse.findSessions({userToken : publicToken, sceneUUID});
if(sessions.length > 0)
{
     const sessionId = sessions[0].session_id;
     await SDK3DVerse.joinSession({sessionId, userToken : publicToken, canvas: document.getElementById('display-canvas')});
}

getClientUUID() → {string}

Get UUID of current client.

Returns:

The current client's UUID.

Type:: string

Example

const clientUUID = SDK3DVerse.getClientUUID();

getClientUUIDs() → {Array.<string>}

Get the UUIDs of all clients in session, including the current client. The first UUID returned is that of the current client.

Returns:

Array of client UUIDs.

Type:: Array.<string>

getSessionId() → {string}

Get the id of the current session joined or started by a call to startSession, joinSession, or joinOrStartSession.

Returns:

Current session id.

Type:: string

Example

const sessionId = SDK3DVerse.getSessionId();

getVersion() → {string}

Get the Livelink.js SDK version.

Returns:

Livelink.js SDK version.

Type:: string

(async) installExtension(extensionClass, parameters) → {SDK3DVerse_ExtensionInterface}

Installs one or more of the available Livelink.js SDK extensions.

Parameters:

Name	Type	Description
`extensionClass`	SDK3DVerse_ExtensionInterface	SDK3DVerse_Gizmos_Ext / SDK3DVerse_LabelDisplay_Ext / SDK3DVerse_ClientDisplay_Ext
`parameters`	object	Extension parameters, see documentation for each extension.

Returns:

Instantiated extension.

Type:: SDK3DVerse_ExtensionInterface

isRendererConnected() → {boolean}

Check if the renderer is connected.

Returns:

Type:: boolean

isTransientSession() → {boolean|undefined}

Returns whether the session is transient or not. If it's transient then all changes that would be normally persistent become transient.

Returns:

True if the session is transient. If not connected to a session, then it returns undefined.

Type:: boolean | undefined

(async) joinOrStartSession(params) → {boolean}

Join an existing 3dverse session if one exists for a given scene (with optional constraints), or else create one, and begin streaming to a canvas element in your app.

Once this function is resolved, it is guaranteed that the renderer has connected and that the editor has connected (if params.connectToEditor was true). Once the renderer and editor have connected, then engineAPI, cameraAPI, Entity, EntityTemplate and Viewport can be used.

Parameters:

Name	Type	Attributes	Default	Description
`params`	object
`sceneUUID`	string			The UUID for the scene you wish to open
`userToken`	string			Your 3dverse user token or public token
`canvas`	HTMLCanvasElement			The HTMLCanvasElement element that will be used to display the stream, whose size will be set by its parent
`constraints`	SessionConstraints	<optional>		Constraints for the session that 3dverse might try to join
`isTransient`	boolean	<optional>	false	Set to true to create or join a transient session. All changes that would be normally persistent become transient
`connectToEditor`	boolean	<optional>	true	Set to true to enable making transient or persistent edits to the scene graph
`startSimulation`	'no' \| 'yes' \| 'on-assets-loaded'	<optional>	'no'	'yes' to start simulation after connecting to new session, 'on-assets-loaded' to wait for assets to load first
`createDefaultCamera`	boolean	<optional>	true	Creates default camera
`viewportProperties`	ViewportInfo	<optional>		Additional viewport settings (such as the controller to use). Not used if createDefaultCamera is false
`maxDimension`	number	<optional>	1920	Limit the rendered resolution to a maximum dimension
`onFindingSession`	function	<optional>		Callback to know when we've begun looking for a session to join (to give more detailed loading feedback to users). This callback will be triggered immediately, but can be triggered again (along with the other callbacks) if a session connection fails and we have to restart
`onStartingStreamer`	function	<optional>		Callback to know when the streamer connection has begun (to give more detailed loading feedback to users)
`onConnectingToEditor`	function	<optional>		Callback to know when the editor connection has started (to give more detailed loading feedback to users)
`onLoadingAssets`	function	<optional>		Callback to know when we're connected and now waiting for assets to finish loading (to give more detailed loading feedback to users). Will only be called if `startSimulation` is 'on-assets-loaded', and assets are not yet loaded after editor connection
`defaultCameraSpeed`	string \| float	<optional>	'auto'	The speed of the camera controller to set after the session is joined. The 'auto' value uses the scene aabb to determine the most suitable speed, or it can be set to a float value in meters per second
`hardwareDecoding`	boolean	<optional>	true	Set to true to enable hardware decoding of video streams
`showLoadingOverlay`	boolean	<optional>	true	Set to false to skip the loading overlay

Fires:

event:onConnectionClosed

Returns:

True if the session was started, false if the session was joined.

Type:: boolean

Example

// This joins or starts a session on a scene with sceneUUID. Frames will begin streaming to
// the HTML canvas element with id 'my-canvas-id'.
// A viewport covering the entire canvas will be created, and a default camera will be created
// and associated to the viewport. The camera will be set up with the editor camera controller,
// and so the user will be able to navigate in the scene.
const sessionStarted = await SDK3DVerse.joinOrStartSession(
{
     sceneUUID,
     userToken: publicToken,
     canvas: document.getElementById('my-canvas-id')
});

(async) joinSession(params)

Join an existing 3dverse session and begin streaming to a canvas element in your app. If the session with the provided params.sessionId was not found, an error is thrown.

Parameters:

Name	Type	Attributes	Default	Description
`params`	object
`sessionId`	string			The ID for the session you wish to join. Can be retrieved using findSessions
`userToken`	string			Your 3dverse user token or public token
`canvas`	HTMLCanvasElement			The HTMLCanvasElement that will be used to display the stream, whose size will be set by its parent
`connectToEditor`	boolean	<optional>	true	Set to true to enable making transient or persistent edits to the scene graph
`createDefaultCamera`	boolean	<optional>	true	Create default camera
`viewportProperties`	ViewportInfo	<optional>		Additional viewport settings (such as the controller to use). Not used if createDefaultCamera is false
`maxDimension`	number	<optional>	1920	Limit the rendered resolution to a maximum dimension
`onStartingStreamer`	function	<optional>		Callback to know when the streamer connection has begun (to give more detailed loading feedback to users)
`onConnectingToEditor`	function	<optional>		Callback to know when the editor connection has started (to give more detailed loading feedback to users)
`defaultCameraSpeed`	string \| float	<optional>	'auto'	The speed of the camera controller to set after the session is joined. The 'auto' value uses the scene aabb to determine the most suitable speed, or it can be set to a float value in meters per second
`hardwareDecoding`	boolean	<optional>	true	Set to true to enable hardware decoding of video streams
`showLoadingOverlay`	boolean	<optional>	true	Set to false to skip the loading overlay

Fires:

event:onConnectionClosed

Example

// This joins an existing session with sessionId. Frames will begin streaming to
// the HTML canvas element with id 'my-canvas-id'.
// A viewport covering the entire canvas will be created, and a default camera will be created
// and associated to the viewport. The camera will be set up with the editor camera controller,
// and so the user will be able to navigate in the scene.
const sessions = await SDK3DVerse.findSessions({userToken : publicToken, sceneUUID});
const sessionId = sessions[0].session_id;
try
{
     await SDK3DVerse.joinSession(
     {
         sessionId,
         userToken: publicToken,
         canvas: document.getElementById('my-canvas-id')
     });
}
catch(e)
{
     console.log(`Session with id: ${sessionId} was not found.`);
}

(async) onEditorConnected() → {Promise}

A promise which will resolve once the editor has connected. The editor must be connected before proceeding with any operations that involve Entity objects.

Returns:

Promise object.

Type:: Promise

Example

await SDK3DVerse.onEditorConnected();

(async) onRendererConnected() → {Promise}

A promise which will resolve once the renderer has connected. The renderer must be connected before using methods from cameraAPI or engineAPI.

Returns:

Promise object.

Type:: Promise

Example

await SDK3DVerse.onRendererConnected();

setCanvas(canvas)

Set canvas element, used to display streamed frames.

Parameters:

Name	Type	Description
`canvas`	HTMLCanvasElement	The HTMLCanvasElement used to display streamed frames

Example

SDK3DVerse.setCanvas(document.getElementById('my-canvas-id'));

setInactivityCallback(callback)

Sets a callback that is called when the client is considered inactive (if the client hasn't relayed any inputs for five minutes).

Parameters:

Name	Type	Description
`callback`	InactivityCallback	Inactivity callback whose functionality determines whether or not to disconnect client from session once the client has become inactive. See code example below for more information.

Example

SDK3DVerse.setInactivityCallback((resumeCallback) =>
{
     const answer = prompt("Are you still there?");
     if(answer === "yes")
     {
         // Client has 30 seconds for resumeCallback() to be called before
         // they will be automatically disconnected.
         resumeCallback();
     }
     else
     {
         console.log("Client will be disconnected from session");
     }
});

setInputRelayFrequency(inputRelayFrequency)

Set frequency at which inputs (keyboards, gamepads, touchscreen...) are relayed to the renderer. Without calling this function, the default input relay frequency is 100 ms.

Parameters:

Name	Type	Description
`inputRelayFrequency`	number	Input relay frequency in milliseconds

setResolution(width, height, streamingScale)

Set resolution of display area in real-time.

Parameters:

Name	Type	Default	Description
`width`	number		Canvas width in pixels
`height`	number		Canvas height in pixels
`streamingScale`	number	1.0	Scale applied on width and height of streamed frame. The dimensions of the streamed frame received by the SDK client will be widthscale x heightscale, but the canvas frame will be width x height.

setUpperAlignment(value)

Set to true to force the canvas to align on the next largest dimension during a setResolution. In that case a container that will center the canvas (as shown in the sample here) and hide the overflow is suggested. See example below for recommended styling of the container.

Parameters:

Name	Type	Description
`value`	boolean

Example

.canvas-container
{
    position: relative;
    display: flex;
    flex-direction: column;
    justify-content: center;
    overflow: hidden;
}

(async) startSession(params)

Create a new 3dverse session and begin streaming to a canvas element in your app.

Parameters:

Name	Type	Attributes	Default	Description
`params`	object
`sceneUUID`	string			The UUID for the scene you wish to open
`userToken`	string			Your 3dverse user token or public token
`canvas`	HTMLCanvasElement			The HTMLCanvasElement that will be used to display the stream, whose size will be set by its parent
`isTransient`	boolean	<optional>	false	Set to true to create a transient session. All changes that would be normally persistent become transient
`connectToEditor`	boolean	<optional>	true	Set to true to enable making transient or persistent edits to the scene graph
`startSimulation`	'no' \| 'yes' \| 'on-assets-loaded'	<optional>	'no'	'yes' to start simulation after connecting, 'on-assets-loaded' to wait for assets to load first
`createDefaultCamera`	boolean	<optional>	true	Create default camera
`viewportProperties`	ViewportInfo	<optional>		Additional viewport settings (such as the controller to use). Not used if createDefaultCamera is false
`maxDimension`	number	<optional>	1920	Limit the rendered resolution to a maximum dimension
`onStartingStreamer`	function	<optional>		Callback to know when the streamer connection has begun (to give more detailed loading feedback to users)
`onConnectingToEditor`	function	<optional>		Callback to know when the editor connection has started (to give more detailed loading feedback to users)
`onLoadingAssets`	function	<optional>		Callback to know when we're connected and now waiting for assets to finish loading (to give more detailed loading feedback to users). Will only be called if `startSimulation` is 'on-assets-loaded', and assets are not yet loaded after editor connection
`defaultCameraSpeed`	string \| float	<optional>	'auto'	The speed of the camera controller to set after the session is joined. The 'auto' value uses the scene aabb to determine the most suitable speed, or it can be set to a float value in meters per second
`hardwareDecoding`	boolean	<optional>	true	Set to true to enable hardware decoding of video streams
`showLoadingOverlay`	boolean	<optional>	true	Set to false to skip the loading overlay

Fires:

event:onConnectionClosed

Example

// This starts a session on a scene with sceneUUID. Frames will begin streaming to
// the HTML canvas element with id 'my-canvas-id'.
// A viewport covering the entire canvas will be created, and a default camera will be created
// and associated to the viewport. The camera will be set up with the editor camera controller,
// and so the user will be able to navigate in the scene.
await SDK3DVerse.startSession(
{
     sceneUUID,
     userToken: publicToken,
     canvas: document.getElementById('my-canvas-id')
});