Threejs Presence3D API Reference

Presence3D automatically implements Avatars, Mouse Pointers and Presence Controls into a Three.js application.

How to use

To initialize the Presence3D component, you can follow our quickstart guide.

Usage

import { Presence3D } from "@superviz/threejs-plugin";

const threeJSPresence = new Presence3D(scene, camera, camera, {
  isAvatarsEnabled: true,
  isLaserEnabled: true,
  isNameEnabled: true,
  isMouseEnabled: true,
  renderLocalAvatar: true,
  avatarConfig: {
    height: 0,
    scale: 1,
    laserOrigin: { x: 0, y: 0, z: 0 },
  },
});

room.addComponent(threeJSPresence);

When initializing the Presence3D you must pass the scene, camera, and one player to its constructor. The player's property is the element where the participant's avatar will be placed. Optionally, you can use an options object as the last argument in the constructor.

The table below shows the arguments passed on the constructor object:

Name	Type	Description
scene	Scene	Required. The ThreeJS scene object, already loaded.
camera	Camera	Required. The ThreeJS scene’s camera, previously created.
player	Object3D	Required. The 3D object you want your avatar to be added to. For first-person experiences, you can use camera objects here.
options	ThreeJsComponentOptions	Use this object to change configurations on how avatars, mouse cursors, and lasers will be placed into your 3D model.

Methods

follow()

The follow() method, when called with a participant id as an argument, allows other participants to follow the referenced participant on the ThreeJS scene. You can, after, call the method without parameters to stop following the participant.

Example:

// Pass a participant ID to start following it
threeJSPresence.follow("<PARTICIPANT_ID>");

// Call the method without parameters to stop following the past participant
threeJSPresence.follow();

goTo()

The goTo() method, when called with a participant ID as an argument, allows other participants to quickly jump to the referenced participant position on the ThreeJS model, facilitating quick location of participants.

Example:

threeJSPresence.goTo("<PARTICIPANT_ID>");

Types Definition

ThreeJsComponentOptions

Type: object

An object describing the options when initializing the Presence3D for ThreeJS.t

Name	Type	Description
avatarConfig	AvatarConfig	Configuration for the avatar, like scale, position, on laser settings.
isAvatarsEnabled	boolean	Enable or disable the need for an avatar in the room. Default value: true
isLaserEnabled	boolean	Enable or disable laser pointers. If isAvatarsEnabled is set to false, this will also be false. Default value: true
isMouseEnabled	boolean	Enable or disable Mouse presence within the 3D model. Default value: true
isNameEnabled	boolean	Enable or disable showing the participant's name on top of the avatars. Default value: true
renderLocalAvatar	boolean	When set true, the participant avatar will be displayed, emulating a third-person view. When set false, the view for the participant will be in the first person. Default value: false

Example:

{
  isAvatarsEnabled: true,
  isLaserEnabled: true,
  isMouseEnabled: true,
  isNameEnabled: true,
  renderLocalAvatar: false,
  avatarConfig: {
    height: 1.6,
    scale: 1,
    laserOrigin: {
      x: 0,
      y: 0,
      z: 0
    }
  }
}

AvatarConfig

Type: object

An object describing the configuration for the avatar, like scale, position, and laser configuration.

Name	Type	Description
height	number	Required. The scale you want your avatar to be rendered, in pixels.
scale	number	Required. The height you want your avatar to be positioned from the ground, in pixels.
laserOrigin	Position	Required. Represents the origin position of your laser beam in relation to your avatar model.

Example:

avatarConfig: {
  height: 1.6,
  scale: 1,
  laserOrigin: {
    x: 0,
    y: 0,
    z: 0
  }
}

Position

Type: object

Represents the origin position of your laser beam in relation to your avatar model.

Name	Type	Description
x	number	Required. Represents the x-axis (horizontal) position.
y	number	Required. Represents the y-axis (vertical) position.
z	number	Required. Represents the z-axis (depth) position.

Example:

laserOrigin: {
  x: 0,
  y: 0,
  z: 0
}