Users

Description

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

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

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.

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, or machine fingerprint otherwise.

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, or machine fingerprint otherwise.

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.
(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.