Users

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.