Users - Vircadia API Docs

Description

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts • Assignment Client Scripts

The Users API provides features to regulate your interaction with other users.

Properties

Name	Type	Summary
canKick	boolean	`true` if the domain server allows the client to kick (ban) avatars, otherwise `false`. Read-only.
requestsDomainListData	boolean	`true` if the client requests extra data from the mixers (such as positional data of an avatar they've ignored). Read-only.
NO_BAN	BanFlags	Do not ban user. Read-only.
BAN_BY_USERNAME	BanFlags	Ban user by username. Read-only.
BAN_BY_FINGERPRINT	BanFlags	Ban user by fingerprint. Read-only.
BAN_BY_IP	BanFlags	Ban user by IP address. Read-only.

Methods

Name	Return Value	Summary
`disableIgnoreRadius`	None	Disables the privacy shield.
`enableIgnoreRadius`	None	Enables the privacy shield.
`getAvatarGain`	number	Gets an avatar's gain (volume) for you and you only, or gets the master gain.
`getCanKick`	boolean	Gets whether the client can kick and ban users in the domain.
`getIgnoreRadiusEnabled`	boolean	Gets the status of the privacy shield.
`getIgnoreStatus`	boolean	Gets whether or not you have ignored a particular avatar.
`getPersonalMuteStatus`	boolean	Gets whether or not you have muted a particular avatar.
`ignore`	None	Ignores or un-ignores another avatar. Ignoring an avatar makes them disappear for you and you disappear for them.
`kick`	None	Kicks and bans a user. This removes them from the server and prevents them from returning. The ban is by user name (if available) and by machine fingerprint. The ban functionality can be controlled with flags. This function only works if you're an administrator of the domain you're in.
`mute`	None	Mutes a user's microphone for everyone. The mute is not permanent: the user can unmute themselves. This function only works if you're an administrator of the domain you're in.
`personalMute`	None	Mutes or un-mutes another avatar. Muting makes you unable to hear them and them unable to hear you.
`requestUsernameFromID`	None	Requests the user name and machine fingerprint associated with the given UUID. The user name is returned via a usernameFromIDReply signal. This function only works if you're an administrator of the domain you're in.
`setAvatarGain`	None	Sets an avatar's gain (volume) for you and you only, or sets the master gain.
`toggleIgnoreRadius`	None	Toggles the state of the privacy shield.

Signals

Name	Summary
`avatarDisconnected`	Triggered when a client has disconnected from the domain.
`canKickChanged`	Triggered when your ability to kick and ban users changes.
`enteredIgnoreRadius`	Triggered when another user enters the privacy shield.
`ignoreRadiusEnabledChanged`	Triggered when the privacy shield status changes.
`usernameFromIDReply`	Triggered in response to a requestUsernameFromID call. Provides the user name and machine fingerprint associated with a UUID.

Method Details

(static) disableIgnoreRadius( )
Disables the privacy shield.

(static) enableIgnoreRadius( )
Enables the privacy shield.

(static) getAvatarGain( nodeID ) → {number}
Returns: The gain, in dB.

Gets an avatar's gain (volume) for you and you only, or gets the master gain.

Parameters

Name	Type	Description
`nodeID`	Uuid	The session ID of the avatar to get the gain for, or `null` to get the master gain.

(static) getCanKick( ) → {boolean} Returns: `true` if the domain server allows the client to kick and ban users, otherwise `false`.
Gets whether the client can kick and ban users in the domain.

(static) getIgnoreRadiusEnabled( ) → {boolean} Returns: `true` if the privacy shield is enabled, `false` if it is disabled.
Gets the status of the privacy shield.

(static) getIgnoreStatus( sessionID ) → {boolean}
Returns: true if the avatar is being ignored, false if it isn't.

Gets whether or not you have ignored a particular avatar.

Parameters

Name	Type	Description
`sessionID`	Uuid	The session ID of the avatar to get the ignore status of.

(static) getPersonalMuteStatus( sessionID ) → {boolean}
Returns: true if the avatar is muted, false if it isn't.

Gets whether or not you have muted a particular avatar.

Parameters

Name	Type	Description
`sessionID`	Uuid	The session ID of the avatar to get the mute status of.

(static) ignore( sessionID, enableopt )

Ignores or un-ignores another avatar. Ignoring an avatar makes them disappear for you and you disappear for them.

Parameters

Name	Type	Attributes	Default Value	Description
`sessionID`	Uuid			The session ID of the avatar to ignore.
`enable`	boolean	<optional>	true	`true` to ignore, `false` to un-ignore.

Example

Ignore a nearby avatar for a few seconds.

var avatars = AvatarList.getAvatarsInRange(MyAvatar.position, 1000);
if (avatars.length > 1) {  // Skip own avatar which is provided in position 0.
    print("Ignore: " + avatars[1]);
    Users.ignore(avatars[1], true);
    Script.setTimeout(function () {
        print("Un-ignore: " + avatars[1]);
        Users.ignore(avatars[1], false);
    }, 5000);
} else {
    print("No avatars");
}

(static) kick( sessionID )

Kicks and bans a user. This removes them from the server and prevents them from returning. The ban is by user name (if available) and by machine fingerprint. The ban functionality can be controlled with flags.

This function only works if you're an administrator of the domain you're in.

Parameters

Name	Type	Description
`sessionID`	Uuid	The session ID of the user to kick and ban.
	BanFlags	Preferred ban flags. Bans a user by username (if available) and machine fingerprint by default.

(static) mute( sessionID )

Mutes a user's microphone for everyone. The mute is not permanent: the user can unmute themselves.

This function only works if you're an administrator of the domain you're in.

Parameters

Name	Type	Description
`sessionID`	Uuid	The session ID of the user to mute.

(static) personalMute( sessionID, muteEnabledopt )

Mutes or un-mutes another avatar. Muting makes you unable to hear them and them unable to hear you.

Parameters

Name	Type	Attributes	Default Value	Description
`sessionID`	Uuid			The session ID of the avatar to mute.
`muteEnabled`	boolean	<optional>	true	`true` to mute, `false` to un-mute.

(static) requestUsernameFromID( sessionID )

Requests the user name and machine fingerprint associated with the given UUID. The user name is returned via a usernameFromIDReply signal.

This function only works if you're an administrator of the domain you're in.

Parameters

Name	Type	Description
`sessionID`	Uuid	The session ID of the user to get the user name and machine fingerprint of.

Example

Report the user name and fingerprint of a nearby user.

function onUsernameFromIDReply(sessionID, userName, machineFingerprint, isAdmin) {
    print("Session:     " + sessionID);
    print("User name:   " + userName);
    print("Fingerprint: " + machineFingerprint);
    print("Is admin:    " + isAdmin);
}

Users.usernameFromIDReply.connect(onUsernameFromIDReply);

var avatars = AvatarList.getAvatarsInRange(MyAvatar.position, 1000);
if (avatars.length > 1) {  // Skip own avatar which is provided in position 0.
    print("Request data for: " + avatars[1]);
    Users.requestUsernameFromID(avatars[1]);
} else {
    print("No avatars");
}

(static) setAvatarGain( nodeID, gain )

Sets an avatar's gain (volume) for you and you only, or sets the master gain.

Parameters

Name	Type	Description
`nodeID`	Uuid	The session ID of the avatar to set the gain for, or `null` to set the master gain.
`gain`	number	The gain to set, in dB.

(static) toggleIgnoreRadius( )
Toggles the state of the privacy shield.

Signal Details

avatarDisconnected( sessionID )
Returns: Signal

Triggered when a client has disconnected from the domain.

Parameters

Name	Type	Description
`sessionID`	Uuid	The session ID of the client that has disconnected.

canKickChanged( canKick )
Returns: Signal

Triggered when your ability to kick and ban users changes.

Parameters

Name	Type	Description
`canKick`	boolean	`true` if you can kick and ban users, `false` if you can't.

enteredIgnoreRadius( ) Returns: Signal
Triggered when another user enters the privacy shield.

ignoreRadiusEnabledChanged( isEnabled )
Returns: Signal

Triggered when the privacy shield status changes.

Parameters

Name	Type	Description
`isEnabled`	boolean	`true` if the privacy shield is enabled, `false` if it isn't.

usernameFromIDReply( sessionID, userName, machineFingerprint, isAdmin )
Returns: Signal

Triggered in response to a requestUsernameFromID call. Provides the user name and machine fingerprint associated with a UUID.

Parameters

Name	Type	Description
`sessionID`	Uuid	The session ID of the client that the data is for.
`userName`	string	The user name of the client, if the requesting client is an administrator in the domain or the `sessionID` is that of the client, otherwise `""`.
`machineFingerprint`	Uuid	The machine fingerprint of the client, if the requesting client is an administrator in the domain or the `sessionID` is that of the client, otherwise Uuid.NULL.
`isAdmin`	boolean	`true` if the client is an administrator in the domain, `false` if not.