User

Allows access to user information.

When extending BasePlugin, these functions can be accessed via this.user.*

When extending BaseComponent, these functions can be accessed via this.plugin.user.*

Functions

getID() : Promise<string>

Returns the identifier of the user.

const id = await this.user.getID()
console.log(id) // => 'user-id'

getDisplayName() : Promise<string>

Returns the display name of the user.

const name = await this.user.getDisplayName()
console.log(name) // => 'John Doe'

isAdmin() : Promise<boolean>

Returns true if the user is an admin in this space and false otherwise. Admins are able to edit objects.

const isAdmin = await this.user.isAdmin()
console.log(isAdmin) // => true

isMuted() : Promise<boolean>

Returns true if the user is muted and false if their microphone is 'on air'.

const isMuted = await this.user.isMuted()
console.log(isMuted) // => true

Also see the core.user.audio.mute-change hook to receive a callback when the microphone mute state changes.

getInitialPosition() : Promise<Vector3>

Returns the position that the user will be in when they enter the space, in the form: { x: number, y: number, z: number }.

const position = await this.user.getInitialPosition()
console.log(position) // => { x: 1, y: 0, z: 2 }

getPosition() : Promise<Vector3>

Returns the position of the user, in the form: { x: number, y: number, z: number }.

const position = await this.user.getPosition()
console.log(position) // => { x: 2, y: 0, z: 3 }

setPosition(x: number, y: number, z: number, instant = false, keepFollow = true) : Promise<void>

Sets the position of the user.

await this.user.setPosition(2, 0, 3)

getOrientation(deg = false) : Promise<number>

Returns the orientation of the user in degrees, if deg === true, or radians, if deg === false. Default is in radians.

const orientation = await this.user.getOrientation()
console.log(orientation) // => 1.5708

setOrientation(orient: number, deg = false) : void

Sets the orientation of the user in degrees, if deg === true, or radians, if deg === false. Default is in radians.

this.user.setOrientation(1.5708)

getTilt(deg = false): Promise<number>

Returns the tilt value of the user in degrees, if deg === true, or radians, if deg === false. Default is in radians.

const tilt = await this.user.getTilt()
console.log(tilt) // => 0.0115

setTilt(tilt: number, deg = false) : void

Sets the tilt value of the user in degrees, if deg === true, or radians, if deg === false. Default is in radians.

this.user.setTilt(0.0115)

getZoom() : Promise<number>

Returns the zoom level of the user.

const zoom = await this.user.getZoom()
console.log(zoom) // => 12

setZoom(zoom: number) : Promise<boolean>

Sets the zoom level of the user.

Final zoom value is clamped between the "Minimum Zoom Distance" and "Maximum Zoom Distance" settings found in the Editor > World tab.

const success = await this.user.setZoom(12)
console.log(success) // => true

getViewMode() : Promise<string>

Returns the view mode of the user, which will be one of: "swivel", "advanced" or "first-person".

const viewMode = await this.user.getViewMode()
console.log(viewMode) // => "advanced"

setViewMode(mode: string, options?: ViewModeOptions) : Promise<boolean>

Sets the view mode of the user, which should be one of: "swivel", "advanced" or "first-person", as well as configuration options if provided.

Properties available for the options parameter

const success = await this.user.setViewMode("advanced")
console.log(success) // => true
// OR
const success = await this.user.setViewMode(
	"first-person",
	{
		pointerLock: true,
		fullscreen: true
	}
)
console.log(success) // => true

getFollow() : Promise<boolean>

Returns true if the user is following another user or object, false otherwise.

const isFollowing = await this.user.getFollow()
console.log(isFollowing) // => false

setFollow(id: string) : void

Sets the user to follow the object with a matching identifier. Can be an object or another user.

this.user.setFollow('042ed071-649c-4601-9a30-669a59c9e1ee')

releaseFollow() : void

Stops the user from following the user or object that they are currently following, if any.

this.user.releaseFollow()

getProperty(userID: string, property: string) : Promise<any>

Returns a property that had been assigned to the specified user by calling user.setProperties() from this plugin. Leave userID blank to get the property on the current user.

const color = await this.user.getProperty('', 'color')
console.log(color) // => '#2DCA8C'

getProperties(userID: string) : Promise<UserProps>

Returns all properties that had been assigned to the specified user by calling user.setProperties() from this plugin. Leave userID blank to get the property on the current user.

const props = await this.user.getProperties('')
console.log(props) // => { id: 'long-form-id:user-id', name: 'John Doe', user_id: 'user-id', role: 'presenter', color: '#2DCA8C' }

setProperties(newProps: UserProps) : Promise<void>

Sets properties for this user within the context of this plugin.

Properties will be merged in. Fields not specified will be left unchanged. Prefix property names with space: if you want the value to be specific to an individual space and not carry over into multiple spaces.

await this.user.setProperties({ color: '#2DCA8C' })

getNearbyUsers() : Promise<UserProps[]>

Returns a list of users who are within rendering range.

Each user has the form: { id: string, name: string, userID: string, role: string, distance: number }

const nearbyUsers = await this.user.getNearbyUsers()
console.log(nearbyUsers) // => [{ id: 'long-form-id:user-id', name: 'John Doe', userID: 'user-id', role: 'presenter', distance: 0.5 }]

registerAvatar(props: AvatarProps) : Promise<void>

Registers a custom avatar that users can select in the Profile > Select Avatar menu. See Custom Avatars for more information. The props object can contain these fields:

await this.user.registerAvatar({
  id: 'com.myplugin.myavatar',
  name: 'My Avatar',
  type: 'humanoid',
  imageURL: this.paths.absolute('./preview.jpg'),
  properties: { url: '...' },
  height: 1.8,
  walkingSpeed: 2,
  runningSpeed: 4,
  hookOnSetup: 'myplugin.onSetup'
})

unregisterAvatar(id: string) : void

Removes an avatar that was registered.

this.user.unregisterAvatar('com.myplugin.myavatar')

getAvatarData() : Promise<AvatarProps | null>

Returns the user's avatar data, or null if the user does not have a custom avatar selected.

See user.registerAvatar(props) for details of the fields returned. It also includes the extra fields pluginID and pluginName which represents the plugin which was used to register the avatar.

const avatarData = await this.user.getAvatarData()
console.log(avatarData) // => { id: 'com.myplugin.myavatar', name: 'My Avatar', type: 'humanoid', imageURL: 'https://example.com/preview.jpg', properties: { url: '...' }, height: 1.8, walkingSpeed: 2, runningSpeed: 4, hookOnSetup: 'myplugin.onSetup', pluginID: 'com.myplugin', pluginName: 'My Plugin' }

setAvatarData(props: AvatarProps) : Promise<void>

Switches the user to the specified avatar data, which may prompt the user to confirm if they want to switch avatars.

See user.registerAvatar(props) for details of the fields that can be specified.

await this.user.setAvatarData({
  id: 'com.myplugin.myavatar',
  name: 'My Avatar',
  type: 'humanoid',
  imageURL: 'https://example.com/preview.jpg', // or this.paths.absolute('./preview.jpg')
  properties: { url: '...' },
  height: 1.8,
  walkingSpeed: 2,
  runningSpeed: 4,
  hookOnSetup: 'myplugin.onSetup'
})

overrideAvatarAnimation(props: AnimationProps | null) : Promise<boolean>

Performs a custom animation override on the current avatar. All users will see the animation. This can be used to play once-off animations or to perform looping animations that are stopped only when the user tries to move around. You can also pass in null to this function to cancel any existing animation overrides.

Returns true if the animation was played until the end, or false if it was cancelled.

Note that all animation names must exclude the type prefix. For example, if you want to play a sit animation on the humanoid skeleton, just specify sit and the app will look for and play a humanoid.sit animation if the user's avatar is a humanoid type.

Also see objects.registerAnimations(url) for loading custom animations, or custom avatars for creating your own avatar and attaching custom animations to it.

const success = await this.user.overrideAvatarAnimation({
  animation_start: 'sit_start',
  animation: 'sit_loop',
  animation_end: 'sit_end',
  loop: true,
  fixed_movement: { x: 0, y: 0, z: 0 },
  cancel_mode: 'smooth',
  merge: true
})
console.log(success) // => true

showShutdownScreen(msg: string, title: string, btnText: string) : void

Shows an orange overlay indicating that the app has been shutdown.

this.user.showShutdownScreen("You have been removed from this space.", "Kicked Out", "Reload")

showAvatarSelectPopup() : void

Shows the screen that allows a user to select their avatar.

this.user.showAvatarSelectPopup()

sendAnalytics(key, value) : void

Send custom analytics data to the backend. Enterprise customers may use this to submit data for custom reports that they request from their Vatom representative.

this.user.sendAnalytics("IdOfUserEnteringThirdRoom", "userEvan123")