AvatarManager - Vircadia API Docs

Description

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

The AvatarManager API provides information about avatars within the current domain. The avatars available are those that Interface has displayed and therefore knows about.

Warning: This API is also provided to Interface, client entity, and avatar scripts as the synonym, "AvatarList". For assignment client scripts, see the separate AvatarList API.

Methods

Name	Return Value	Summary
`findParabolaIntersectionVector`	ParabolaToAvatarIntersectionResult	Deprecated: This function is deprecated and will be removed.
`findRayIntersection`	RayToAvatarIntersectionResult	Find the first avatar intersected by a PickRay.
`findRayIntersectionVector`	RayToAvatarIntersectionResult	Deprecated: This function is deprecated and will be removed.
`getAvatar`	ScriptAvatar	Gets information about an avatar.
`getAvatarDataRate`	number	Gets the amount of avatar mixer data being generated by an avatar other than your own.
`getAvatarIdentifiers`	Array.<Uuid>	Gets the IDs of all avatars known about in the domain. Your own avatar is included in the list as a `null` value.
`getAvatarSimulationRate`	number	Gets the simulation rate of an avatar other than your own.
`getAvatarsInRange`	Array.<Uuid>	Gets the IDs of all avatars known about within a specified distance from a point. Your own avatar's ID is included in the list if it is in range.
`getAvatarSortCoefficient`	number	Deprecated: This function is deprecated and will be removed.
`getAvatarUpdateRate`	number	Gets the update rate of avatar mixer data being generated by an avatar other than your own.
`getPalData`	Object.<"data", Array.<AvatarManager.PalData>>	Gets PAL (People Access List) data for one or more avatars. Using this method is faster than iterating over each avatar and obtaining data about each individually.
`isAvatarInRange`	boolean	Checks whether there is an avatar within a specified distance from a point.
`processAvatarDataPacket`	None	Deprecated: This function is deprecated and will be removed.
`processAvatarIdentityPacket`	None	Deprecated: This function is deprecated and will be removed.
`processBulkAvatarTraits`	None	Deprecated: This function is deprecated and will be removed.
`processKillAvatar`	None	Deprecated: This function is deprecated and will be removed.
`sessionUUIDChanged`	None	Deprecated: This function is deprecated and will be removed.
`setAvatarSortCoefficient`	None	Deprecated: This function is deprecated and will be removed.
`setEnableDebugDrawOtherSkeletons`	None	Displays other avatars skeletons debug graphics.
`updateAvatarRenderStatus`	None	Deprecated: This function is deprecated and will be removed.

Signals

Name	Summary
`avatarAddedEvent`	Triggered when an avatar arrives in the domain.
`avatarRemovedEvent`	Triggered when an avatar leaves the domain.
`avatarSessionChangedEvent`	Triggered when an avatar's session ID changes.

Type Definitions

PalData
Type: object

PAL (People Access List) data for an avatar.

Properties

Name	Type	Summary
sessionUUID	Uuid	The avatar's session ID. `""` if the avatar is your own.
sessionDisplayName	string	The avatar's display name, sanitized and versioned, as defined by the avatar mixer. It is unique among all avatars present in the domain at the time.
audioLoudness	number	The instantaneous loudness of the audio input that the avatar is injecting into the domain.
isReplicated	boolean	Deprecated: This property is deprecated and will be removed.
position	Vec3	The position of the avatar.
palOrbOffset	number	The vertical offset from the avatar's position that an overlay orb should be displayed at.

Method Details

(static) findParabolaIntersectionVector( pick, avatarsToInclude, avatarsToDiscard ) → {ParabolaToAvatarIntersectionResult}
Returns: Intersection result.

Deprecated: This function is deprecated and will be removed.

Parameters

Name	Type	Description
`pick`	PickParabola	Pick.
`avatarsToInclude`	Array.<Uuid>	Avatars to include.
`avatarsToDiscard`	Array.<Uuid>	Avatars to discard.

(static) findRayIntersection( ray, avatarsToIncludeopt, avatarsToDiscardopt, pickAgainstMeshopt ) → {RayToAvatarIntersectionResult}
Returns: The result of the search for the first intersected avatar.

Find the first avatar intersected by a PickRay.

Parameters

Name	Type	Attributes	Default Value	Description
`ray`	PickRay			The ray to use for finding avatars.
`avatarsToInclude`	Array.<Uuid>	<optional>	[]	If not empty then search is restricted to these avatars.
`avatarsToDiscard`	Array.<Uuid>	<optional>	[]	Avatars to ignore in the search.
`pickAgainstMesh`	boolean	<optional>	true	If `true` then the exact intersection with the avatar mesh is calculated, if `false` then the intersection is approximate.

Example

Find the first avatar directly in front of you.

var pickRay = {
    origin: MyAvatar.position,
    direction: Quat.getFront(MyAvatar.orientation)
};

var intersection = AvatarManager.findRayIntersection(pickRay);
if (intersection.intersects) {
    print("Avatar found: " + JSON.stringify(intersection));
} else {
    print("No avatar found.");
}

(static) findRayIntersectionVector( ray, avatarsToInclude, avatarsToDiscard, pickAgainstMesh ) → {RayToAvatarIntersectionResult}
Returns: Intersection result.

Deprecated: This function is deprecated and will be removed.

Parameters

Name	Type	Description
`ray`	PickRay	Ray.
`avatarsToInclude`	Array.<Uuid>	Avatars to include.
`avatarsToDiscard`	Array.<Uuid>	Avatars to discard.
`pickAgainstMesh`	boolean	Pick against mesh.

(static) getAvatar( avatarID ) → {ScriptAvatar}
Returns: Information about the avatar.

Gets information about an avatar.

Parameters

Name	Type	Description
`avatarID`	Uuid	The ID of the avatar.

(static) getAvatarDataRate( sessionID, rateNameopt ) → {number}
Returns: The data rate in kbps; 0 if the avatar is your own.

Gets the amount of avatar mixer data being generated by an avatar other than your own.

Parameters

Name	Type	Attributes	Default Value	Description
`sessionID`	Uuid			The ID of the avatar whose data rate you're retrieving.
`rateName`	AvatarDataRate	<optional>	""	The type of avatar mixer data to get the data rate of.

(static) getAvatarIdentifiers( ) → {Array.<Uuid>} Returns: The IDs of all known avatars in the domain.
Gets the IDs of all avatars known about in the domain. Your own avatar is included in the list as a `null` value. Example Report the IDS of all avatars within the domain. `var avatars = AvatarManager.getAvatarIdentifiers(); print("Avatars in the domain: " + JSON.stringify(avatars)); // A null item is included for your avatar.`

(static) getAvatarIdentifiers( ) → {Array.<Uuid>}
Returns: The IDs of all known avatars in the domain.

Gets the IDs of all avatars known about in the domain. Your own avatar is included in the list as a null value.

Example

Report the IDS of all avatars within the domain.

var avatars = AvatarManager.getAvatarIdentifiers();
print("Avatars in the domain: " + JSON.stringify(avatars));
// A null item is included for your avatar.

(static) getAvatarSimulationRate( sessionID, rateNameopt ) → {number}
Returns: The simulation rate in Hz; 0 if the avatar is your own.

Gets the simulation rate of an avatar other than your own.

Parameters

Name	Type	Attributes	Default Value	Description
`sessionID`	Uuid			The ID of the avatar whose simulation you're retrieving.
`rateName`	AvatarSimulationRate	<optional>	""	The type of avatar data to get the simulation rate of.

(static) getAvatarsInRange( position, range ) → {Array.<Uuid>}
Returns: The IDs of all known avatars within the search distance from the position.

Gets the IDs of all avatars known about within a specified distance from a point. Your own avatar's ID is included in the list if it is in range.

Parameters

Name	Type	Description
`position`	Vec3	The point about which the search is performed.
`range`	number	The search radius.

Example

Report the IDs of all avatars within 10m of your avatar.

var RANGE = 10;
var avatars = AvatarManager.getAvatarsInRange(MyAvatar.position, RANGE);
print("Nearby avatars: " + JSON.stringify(avatars));
print("Own avatar: " + MyAvatar.sessionUUID);

(static) getAvatarSortCoefficient( name ) → {number}
Returns: Value.

Deprecated: This function is deprecated and will be removed.

Parameters

Name	Type	Description
`name`	string	Name.

(static) getAvatarUpdateRate( sessionID, rateNameopt ) → {number}
Returns: The update rate in Hz; 0 if the avatar is your own.

Gets the update rate of avatar mixer data being generated by an avatar other than your own.

Parameters

Name	Type	Attributes	Default Value	Description
`sessionID`	Uuid			The ID of the avatar whose update rate you're retrieving.
`rateName`	AvatarUpdateRate	<optional>	""	The type of avatar mixer data to get the update rate of.

(static) getPalData( avatarIDsopt ) → {Object.<"data", Array.<AvatarManager.PalData>>}
Returns: An array of objects, each object being the PAL data for an avatar.

Gets PAL (People Access List) data for one or more avatars. Using this method is faster than iterating over each avatar and obtaining data about each individually.

Parameters

Name	Type	Attributes	Default Value	Description
`avatarIDs`	Array.<string>	<optional>	[]	The IDs of the avatars to get the PAL data for. If empty, then PAL data is obtained for all avatars.

Example

Report the PAL data for an avatar nearby.

var palData = AvatarManager.getPalData();
print("PAL data for one avatar: " + JSON.stringify(palData.data[0]));

(static) isAvatarInRange( position, range ) → {boolean}
Returns: true if there's an avatar within the specified distance of the point, false if not.

Checks whether there is an avatar within a specified distance from a point.

Parameters

Name	Type	Description
`position`	string	The test position.
`range`	string	The test distance.

(static) processAvatarDataPacket( message, sendingNode )

Deprecated: This function is deprecated and will be removed.

Parameters

Name	Type	Description
`message`	object	Message.
`sendingNode`	object	Sending node.

(static) processAvatarIdentityPacket( message, sendingNode )

Deprecated: This function is deprecated and will be removed.

Parameters

Name	Type	Description
`message`	object	Message.
`sendingNode`	object	Sending node.

(static) processBulkAvatarTraits( message, sendingNode )

Deprecated: This function is deprecated and will be removed.

Parameters

Name	Type	Description
`message`	object	Message.
`sendingNode`	object	Sending node.

(static) processKillAvatar( message, sendingNode )

Deprecated: This function is deprecated and will be removed.

Parameters

Name	Type	Description
`message`	object	Message.
`sendingNode`	object	Sending node.

(static) sessionUUIDChanged( sessionUUID, oldSessionUUID )

Deprecated: This function is deprecated and will be removed.

Parameters

Name	Type	Description
`sessionUUID`	Uuid	New session ID.
`oldSessionUUID`	Uuid	Old session ID.

(static) setAvatarSortCoefficient( name, value )

Deprecated: This function is deprecated and will be removed.

Parameters

Name	Type	Description
`name`	string	Name
`value`	number	Value.

(static) setEnableDebugDrawOtherSkeletons( enabled )

Displays other avatars skeletons debug graphics.

Parameters

Name	Type	Description
`enabled`	boolean	`true` to show the debug graphics, `false` to hide.

(static) updateAvatarRenderStatus( shouldRenderAvatars )

Deprecated: This function is deprecated and will be removed.

Parameters

Name	Type	Description
`shouldRenderAvatars`	boolean	Should render avatars.

Signal Details

avatarAddedEvent( sessionUUID )
Returns: Signal

Triggered when an avatar arrives in the domain.

Parameters

Name	Type	Description
`sessionUUID`	Uuid	The ID of the avatar that arrived in the domain.

Example

Report when an avatar arrives in the domain.

AvatarManager.avatarAddedEvent.connect(function (sessionID) {
    print("Avatar arrived: " + sessionID);
});

// Note: If using from the AvatarList API, replace "AvatarManager" with "AvatarList".

avatarRemovedEvent( sessionUUID )
Returns: Signal

Triggered when an avatar leaves the domain.

Parameters

Name	Type	Description
`sessionUUID`	Uuid	The ID of the avatar that left the domain.

Example

Report when an avatar leaves the domain.

AvatarManager.avatarRemovedEvent.connect(function (sessionID) {
    print("Avatar left: " + sessionID);
});

// Note: If using from the AvatarList API, replace "AvatarManager" with "AvatarList".

avatarSessionChangedEvent( newSessionUUID, oldSessionUUID )
Returns: Signal

Triggered when an avatar's session ID changes.

Parameters

Name	Type	Description
`newSessionUUID`	Uuid	The new session ID.
`oldSessionUUID`	Uuid	The old session ID.

Example

Report when an avatar's session ID changes.

AvatarManager.avatarSessionChangedEvent.connect(function (newSessionID, oldSessionID) {
    print("Avatar session ID changed from " + oldSessionID + " to " + newSessionID);
});

// Note: If using from the AvatarList API, replace "AvatarManager" with "AvatarList".