Avatar

• Properties • Methods • Signals • Type Definitions • Method Details • Signal Details •

Description

Supported Script Types: Assignment Client Scripts

The Avatar API is used to manipulate scriptable avatars on the domain. This API is a subset of the MyAvatar API. To enable this API, set Agent.isAvatar to true.

For Interface, client entity, and avatar scripts, see MyAvatar.

Example

Create a scriptable avatar.

(function () {
    Agent.setIsAvatar(true);
    print("Position: " + JSON.stringify(Avatar.position));  // 0, 0, 0
}());

Properties

Name Type Summary
position Vec3

The position of the avatar.
scale number

The scale of the avatar. The value can be set to anything between 0.005 and 1000.0. When the scale value is fetched, it may temporarily be further limited by the domain's settings.

Default Value: 1.0

density number

The density of the avatar in kg/m3. The density is used to work out its mass in the application of physics. Read-only.
handPosition Vec3

A user-defined hand position, in world coordinates. The position moves with the avatar but is otherwise not used or changed by Interface.
bodyYaw number

The left or right rotation about an axis running from the head to the feet of the avatar. Yaw is sometimes called "heading".
bodyPitch number

The rotation about an axis running from shoulder to shoulder of the avatar. Pitch is sometimes called "elevation".
bodyRoll number

The rotation about an axis running from the chest to the back of the avatar. Roll is sometimes called "bank".
orientation Quat

The orientation of the avatar.
headOrientation Quat

The orientation of the avatar's head.
headPitch number

The rotation about an axis running from ear to ear of the avatar's head. Pitch is sometimes called "elevation".
headYaw number

The rotation left or right about an axis running from the base to the crown of the avatar's head. Yaw is sometimes called "heading".
headRoll number

The rotation about an axis running from the nose to the back of the avatar's head. Roll is sometimes called "bank".
velocity Vec3

The current velocity of the avatar.
angularVelocity Vec3

The current angular velocity of the avatar.
audioLoudness number

The instantaneous loudness of the audio input that the avatar is injecting into the domain.
audioAverageLoudness number

The rolling average loudness of the audio input that the avatar is injecting into the domain.
displayName string

The avatar's display name.
sessionDisplayName string

displayName's sanitized and default version defined by the avatar mixer rather than Interface clients. The result is unique among all avatars present in the domain at the time.
lookAtSnappingEnabled boolean

true if the avatar's eyes snap to look at another avatar's eyes when the other avatar is in the line of sight and also has lookAtSnappingEnabled == true.

Default Value: true

skeletonModelURL string

The avatar's FST file.
attachmentData Array.<AttachmentData>

Information on the avatar's attachments.

Deprecated: This property is deprecated and will be removed. Use avatar entities instead.
jointNames Array.<string>

The list of joints in the current avatar model. Read-only.
sessionUUID Uuid

Unique ID of the avatar in the domain. Read-only.
sensorToWorldMatrix Mat4

The scale, rotation, and translation transform from the user's real world to the avatar's size, orientation, and position in the virtual world. Read-only.
controllerLeftHandMatrix Mat4

The rotation and translation of the left hand controller relative to the avatar. Read-only.
controllerRightHandMatrix Mat4

The rotation and translation of the right hand controller relative to the avatar. Read-only.
sensorToWorldScale number

The scale that transforms dimensions in the user's real world to the avatar's size in the virtual world. Read-only.
hasPriority boolean

true if the avatar is in a "hero" zone, false if it isn't. Read-only.
hasScriptedBlendshapes boolean

true if blend shapes are controlled by scripted actions, otherwise false. Set this to true before using the MyAvatar.setBlendshape method, and set back to false after you no longer want scripted control over the blend shapes.

Note: This property will automatically be set to true if the Controller system has valid facial blend shape actions.

Default Value: false

hasProceduralBlinkFaceMovement boolean

true if avatars blink automatically by animating facial blend shapes, false if automatic blinking is disabled. Set to false to fully control the blink facial blend shapes via the MyAvatar.setBlendshape method.

Default Value: true

hasProceduralEyeFaceMovement boolean

true if the facial blend shapes for an avatar's eyes adjust automatically as the eyes move, false if this automatic movement is disabled. Set this property to true to prevent the iris from being obscured by the upper or lower lids. Set to false to fully control the eye blend shapes via the MyAvatar.setBlendshape method.

Default Value: true

hasAudioEnabledFaceMovement boolean

true if the avatar's mouth blend shapes animate automatically based on detected microphone input, false if this automatic movement is disabled. Set this property to false to fully control the mouth facial blend shapes via the MyAvatar.setBlendshape method.

Default Value: true

Methods

Name Return Value Summary
attach None

Attaches a model to your avatar. For example, you can give your avatar a hat to wear, a guitar to hold, or a surfboard to stand on.

Deprecated: This function is deprecated and will be removed. Use avatar entities instead.
clearAvatarEntity None

Deprecated: This function is deprecated and will be removed.
clearJointData None

Clears joint translations and rotations set by script for a specific joint. This restores all motion from the default animation system including inverse kinematics for that joint.

Note: This is slightly faster than the function variation that specifies the joint name.
clearJointData None

Clears joint translations and rotations set by script for a specific joint. This restores all motion from the default animation system including inverse kinematics for that joint.

Note: This is slightly slower than the function variation that specifies the joint index.
clearJointsData None

Clears all joint translations and rotations that have been set by script. This restores all motion from the default animation system including inverse kinematics for all joints.
detachAll None

Detaches all instances of a particular model from either a specific joint or all joints.

Deprecated: This function is deprecated and will be removed. Use avatar entities instead.
detachOne None

Detaches the most recently attached instance of a particular model from either a specific joint or any joint.

Deprecated: This function is deprecated and will be removed. Use avatar entities instead.
getAbsoluteJointRotationInObjectFrame Quat

Gets the rotation of a joint relative to the avatar.

Warning: Not able to be used in the Avatar API.
getAbsoluteJointTranslationInObjectFrame Vec3

Gets the translation of a joint relative to the avatar.

Warning: Not able to be used in the Avatar API.
getAnimationDetails Avatar.AnimationDetails

Gets the details of the current avatar animation that is being or was recently played.
getAttachmentData Array.<AttachmentData>

Gets information about the models currently attached to your avatar.

Deprecated: This function is deprecated and will be removed. Use avatar entities instead.
getAttachmentsVariant Array.<AttachmentData>

Gets information about the models currently attached to your avatar.

Deprecated: This function is deprecated and will be removed. Use avatar entities instead.
getAvatarEntityData AvatarEntityMap

Gets details of all avatar entities.

Warning: Potentially an expensive call. Do not use if possible.
getControllerLeftHandMatrix Mat4

Gets the rotation and translation of the left hand controller relative to the avatar.
getControllerRightHandMatrix Mat4

Gets the rotation and translation of the right hand controller relative to the avatar.
getDataRate number

Gets the amount of avatar mixer data being generated by the avatar.
getDomainMaxScale number

Gets the maximum scale allowed for this avatar in the current domain. This value can change as the user changes avatars or when changing domains.
getDomainMinScale number

Gets the minimum scale allowed for this avatar in the current domain. This value can change as the user changes avatars or when changing domains.
getEyeHeight number

Gets the current eye height of the avatar. This height is only an estimate and might be incorrect for avatars that are missing standard joints.
getHandState HandState

Gets the pointing state of the hands to control where the laser emanates from. If the right index finger is pointing, the laser emanates from the tip of that finger, otherwise it emanates from the palm.
getHeight number

Gets the current height of the avatar. This height is only an estimate and might be incorrect for avatars that are missing standard joints.
getJointIndex number

Gets the joint index for a named joint. The joint index value is the position of the joint in the array returned by MyAvatar.getJointNames, or Avatar.getJointNames if using the Avatar API.
getJointNames Array.<string>

Gets the names of all the joints in the current avatar.
getJointRotation Quat

Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see Avatar Standards.
getJointRotation Quat

Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see Avatar Standards.
getJointRotations Array.<Quat>

Gets the rotations of all joints in the current avatar. Each joint's rotation is relative to its parent joint.
getJointTranslation Vec3

Gets the translation of a joint relative to its parent, in model coordinates.

Warning: These coordinates are not necessarily in meters.

For information on the joint hierarchy used, see Avatar Standards.
getJointTranslation Vec3

Gets the translation of a joint relative to its parent, in model coordinates.

Warning: These coordinates are not necessarily in meters.

For information on the joint hierarchy used, see Avatar Standards.
getJointTranslations Array.<Vec3>

Gets the translations of all joints in the current avatar. Each joint's translation is relative to its parent joint, in model coordinates.

Warning: These coordinates are not necessarily in meters.
getSensorToWorldMatrix Mat4

Gets the transform from the user's real world to the avatar's size, orientation, and position in the virtual world.
getSensorToWorldScale number

Gets the scale that transforms dimensions in the user's real world to the avatar's size in the virtual world.
getTargetScale number

Gets the target scale of the avatar without any restrictions on permissible values imposed by the domain. In contrast, the scale property's value may be limited by the domain's settings.
getUpdateRate number

Gets the update rate of avatar mixer data being generated by the avatar.
isJointDataValid boolean

Checks that the data for a joint are valid.
isJointDataValid boolean

Checks if the data for a joint are valid.
resetLastSent None

Deprecated: This function is deprecated and will be removed.
sendAvatarDataPacket number

Deprecated: This function is deprecated and will be removed.
sendIdentityPacket number

Deprecated: This function is deprecated and will be removed.
setAbsoluteJointRotationInObjectFrame boolean

Sets the rotation of a joint relative to the avatar.

Warning: Not able to be used in the Avatar API.
setAbsoluteJointTranslationInObjectFrame boolean

Sets the translation of a joint relative to the avatar.

Warning: Not able to be used in the Avatar API.
setAttachmentData None

Sets all models currently attached to your avatar. For example, if you retrieve attachment data using MyAvatar.getAttachmentData or Avatar.getAttachmentData, make changes to it, and then want to update your avatar's attachments per the changed data. You can also remove all attachments by using setting attachmentData to null.

Deprecated: This function is deprecated and will be removed. Use avatar entities instead.
setAttachmentsVariant None

Sets all models currently attached to your avatar. For example, if you retrieve attachment data using MyAvatar.getAttachmentsVariant or Avatar.getAttachmentsVariant, make changes to it, and then want to update your avatar's attachments per the changed data.

Deprecated: This function is deprecated and will be removed. Use avatar entities instead.
setAvatarEntityData None

Sets all avatar entities from an object.

Warning: Potentially an expensive call. Do not use if possible.
setBlendshape None

Sets the value of a blend shape to animate your avatar's face. In order for other users to see the resulting animations on your avatar's face, set hasScriptedBlendshapes to true. When you are done using this API, set hasScriptedBlendshapes back to false when the animation is complete.
setForceFaceTrackerConnected None

Enables blend shapes set using Avatar.setBlendshape or MyAvatar.setBlendshape to be transmitted to other users so that they can see the animation of your avatar's face.

Deprecated: This method is deprecated and will be removed. Use the Avatar.hasScriptedBlendshapes or MyAvatar.hasScriptedBlendshapes property instead.
setHandState None

Sets the pointing state of the hands to control where the laser emanates from. If the right index finger is pointing, the laser emanates from the tip of that finger, otherwise it emanates from the palm.
setJointData None

Sets a specific joint's rotation and position relative to its parent, in model coordinates.

Warning: These coordinates are not necessarily in meters.

Setting joint data completely overrides/replaces all motion from the default animation system including inverse kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.
setJointData None

Sets a specific joint's rotation and position relative to its parent, in model coordinates.

Warning: These coordinates are not necessarily in meters.

Setting joint data completely overrides/replaces all motion from the default animation system including inverse kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.
setJointMappingsFromNetworkReply None

Deprecated: This function is deprecated and will be removed.
setJointRotation None

Sets a specific joint's rotation relative to its parent.

Setting joint data completely overrides/replaces all motion from the default animation system including inverse kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.
setJointRotation None

Sets a specific joint's rotation relative to its parent.

Setting joint data completely overrides/replaces all motion from the default animation system including inverse kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.
setJointRotations None

Sets the rotations of all joints in the current avatar. Each joint's rotation is relative to its parent joint.

Setting joint data completely overrides/replaces all motion from the default animation system including inverse kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.
setJointTranslation None

Sets a specific joint's translation relative to its parent, in model coordinates.

Warning: These coordinates are not necessarily in meters.

Setting joint data completely overrides/replaces all motion from the default animation system including inverse kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.
setJointTranslation None

Sets a specific joint's translation relative to its parent, in model coordinates.

Warning: These coordinates are not necessarily in meters.

Setting joint data completely overrides/replaces all motion from the default animation system including inverse kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.
setJointTranslations None

Sets the translations of all joints in the current avatar. Each joint's translation is relative to its parent joint, in model coordinates.

Warning: These coordinates are not necessarily in meters.

Setting joint data completely overrides/replaces all motion from the default animation system including inverse kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.
setRawJointData None

Sets joint translations and rotations from raw joint data.

Deprecated: This function is deprecated and will be removed.
setSessionUUID None

Deprecated: This function is deprecated and will be removed.
setSkeletonModelURL None

Sets the avatar's skeleton model.
startAnimation None

Starts playing an animation on the avatar.
stopAnimation None

Stops playing the current animation.
update None

Deprecated: This function is deprecated and will be removed.
updateAvatarEntity None

Deprecated: This function is deprecated and will be removed.

Signals

Name Summary
displayNameChanged

Triggered when the avatar's displayName property value changes.
lookAtSnappingChanged

Triggered when the avatar's lookAtSnappingEnabled property value changes.
sessionDisplayNameChanged

Triggered when the avatar's sessionDisplayName property value changes.
sessionUUIDChanged

Triggered when the avatar's sessionUUID property value changes.
skeletonModelURLChanged

Triggered when the avatar's model (i.e., skeletonModelURL property value) changes.

Type Definitions

AnimationDetails
Type: object

The details of an animation that is playing.

Properties

Name Type Summary
role string

Not used.
url string

The URL to the animation file. Animation files need to be in glTF or FBX format but only need to contain the avatar skeleton and animation data. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs respectively).

Warning: glTF animations currently do not always animate correctly.
fps number

The frames per second(FPS) rate for the animation playback. 30 FPS is normal speed.
priority number

Not used.
loop boolean

true if the animation should loop, false if it shouldn't.
hold boolean

Not used.
firstFrame number

The frame the animation should start at.
lastFrame number

The frame the animation should stop at.
running boolean

Not used.
currentFrame number

The current frame being played.
startAutomatically boolean

Not used.
allowTranslation boolean

Not used.

Method Details

(static) attach( modelURL, jointNameopt, translationopt, rotationopt, scaleopt, isSoftopt, allowDuplicatesopt, useSavedopt )

Attaches a model to your avatar. For example, you can give your avatar a hat to wear, a guitar to hold, or a surfboard to stand on.

Deprecated: This function is deprecated and will be removed. Use avatar entities instead.

Parameters

Name Type Attributes Default Value Description
modelURL string

The URL of the glTF, FBX, or OBJ model to attach. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs respectively).
jointName string <optional>
 ""

The name of the avatar joint (see MyAvatar.getJointNames or Avatar.getJointNames) to attach the model to.
translation Vec3 <optional>
 Vec3.ZERO

The offset to apply to the model relative to the joint position.
rotation Quat <optional>
 Quat.IDENTITY

The rotation to apply to the model relative to the joint orientation.
scale number <optional>
 1.0

The scale to apply to the model.
isSoft boolean <optional>
 false

If the model has a skeleton, set this to true so that the bones of the attached model's skeleton are rotated to fit the avatar's current pose. isSoft is used, for example, to have clothing that moves with the avatar.

If true, the translation, rotation, and scale parameters are ignored.
allowDuplicates boolean <optional>
 false

If true then more than one copy of any particular model may be attached to the same joint; if false then the same model cannot be attached to the same joint.
useSaved boolean <optional>
 true

Not used.
Example

Attach a cowboy hat to your avatar's head.

var attachment = {
    modelURL: "https://apidocs.vircadia.dev/models/cowboy-hat.fbx",
    jointName: "Head",
    translation: {"x": 0, "y": 0.25, "z": 0},
    rotation: {"x": 0, "y": 0, "z": 0, "w": 1},
    scale: 0.01,
    isSoft: false
};

 MyAvatar.attach(attachment.modelURL,
                 attachment.jointName,
                 attachment.translation,
                 attachment.rotation,
                 attachment.scale,
                 attachment.isSoft);

// Note: If using from the Avatar API, replace "MyAvatar" with "Avatar".
(static) clearAvatarEntity( entityID, requiresRemovalFromTreeopt )

Deprecated: This function is deprecated and will be removed.

Parameters

Name Type Attributes Default Value Description
entityID Uuid

The entity ID.
requiresRemovalFromTree boolean <optional>
 true

unused
(static) clearJointData( index )

Clears joint translations and rotations set by script for a specific joint. This restores all motion from the default animation system including inverse kinematics for that joint.

Note: This is slightly faster than the function variation that specifies the joint name.

Parameters

Name Type Description
index number

The index of the joint.
(static) clearJointData( name )

Clears joint translations and rotations set by script for a specific joint. This restores all motion from the default animation system including inverse kinematics for that joint.

Note: This is slightly slower than the function variation that specifies the joint index.

Parameters

Name Type Description
name string

The name of the joint.
Example

Offset and restore the position of your avatar's head.

// Stretch your avatar's neck.
MyAvatar.setJointTranslation("Neck", Vec3.multiply(2, MyAvatar.getJointTranslation("Neck")));

// Restore your avatar's neck after 5s.
Script.setTimeout(function () {
    MyAvatar.clearJointData("Neck");
}, 5000);

// Note: If using from the Avatar API, replace all occurrences of "MyAvatar" with "Avatar".
(static) clearJointsData( )

Clears all joint translations and rotations that have been set by script. This restores all motion from the default animation system including inverse kinematics for all joints.

Example

Set your avatar to it's default T-pose for a while.

// Set all joint translations and rotations to defaults.
var i, length, rotation, translation;
for (i = 0, length = MyAvatar.getJointNames().length; i < length; i++) {
    rotation = MyAvatar.getDefaultJointRotation(i);
    translation = MyAvatar.getDefaultJointTranslation(i);
    MyAvatar.setJointData(i, rotation, translation);
}

// Restore your avatar's motion after 5s.
Script.setTimeout(function () {
    MyAvatar.clearJointsData();
}, 5000);

// Note: If using from the Avatar API, replace all occurrences of "MyAvatar" with "Avatar".
(static) detachAll( modelURL, jointNameopt )

Detaches all instances of a particular model from either a specific joint or all joints.

Deprecated: This function is deprecated and will be removed. Use avatar entities instead.

Parameters

Name Type Attributes Default Value Description
modelURL string

The URL of the model to detach.
jointName string <optional>
 ""

The name of the joint to detach the model from. If "", then the model is detached from all joints.
(static) detachOne( modelURL, jointNameopt )

Detaches the most recently attached instance of a particular model from either a specific joint or any joint.

Deprecated: This function is deprecated and will be removed. Use avatar entities instead.

Parameters

Name Type Attributes Default Value Description
modelURL string

The URL of the model to detach.
jointName string <optional>
 ""

The name of the joint to detach the model from. If "", then the most recently attached model is removed from which ever joint it was attached to.
(static) getAbsoluteJointRotationInObjectFrame( index ) → {Quat}
Returns: Quat.IDENTITY.

Gets the rotation of a joint relative to the avatar.

Warning: Not able to be used in the Avatar API.

Parameters

Name Type Description
index number

The index of the joint. Not used.
(static) getAbsoluteJointTranslationInObjectFrame( index ) → {Vec3}
Returns: Vec3.ZERO.

Gets the translation of a joint relative to the avatar.

Warning: Not able to be used in the Avatar API.

Parameters

Name Type Description
index number

The index of the joint. Not used.
(static) getAnimationDetails( ) → {Avatar.AnimationDetails}
Returns: The current or recent avatar animation.

Gets the details of the current avatar animation that is being or was recently played.

Example

Report the current animation details.

var animationDetails = Avatar.getAnimationDetails();
print("Animation details: " + JSON.stringify(animationDetails));
(static) getAttachmentData( ) → {Array.<AttachmentData>}
Returns: Information about all models attached to your avatar.

Gets information about the models currently attached to your avatar.

Deprecated: This function is deprecated and will be removed. Use avatar entities instead.

Example

Report the URLs of all current attachments.

var attachments = MyAvatar.getaAttachmentData();
for (var i = 0; i < attachments.length; i++) {
    print(attachments[i].modelURL);
}

// Note: If using from the Avatar API, replace "MyAvatar" with "Avatar".
(static) getAttachmentsVariant( ) → {Array.<AttachmentData>}
Returns: Information about all models attached to your avatar.

Gets information about the models currently attached to your avatar.

Deprecated: This function is deprecated and will be removed. Use avatar entities instead.
(static) getAvatarEntityData( ) → {AvatarEntityMap}
Returns: Details of all avatar entities.

Gets details of all avatar entities.

Warning: Potentially an expensive call. Do not use if possible.

Example

Report the current avatar entities.

var avatarEntityData = Avatar.getAvatarEntityData();
print("Avatar entities: " + JSON.stringify(avatarEntityData));
(static) getControllerLeftHandMatrix( ) → {Mat4}
Returns: The rotation and translation of the left hand controller relative to the avatar.

Gets the rotation and translation of the left hand controller relative to the avatar.

Example

Report the left hand controller matrix.

var leftHandMatrix = MyAvatar.getControllerLeftHandMatrix();
print("Controller left hand matrix: " + JSON.stringify(leftHandMatrix));
print("Rotation: " + JSON.stringify(Mat4.extractRotation(leftHandMatrix)));
print("Translation: " + JSON.stringify(Mat4.extractTranslation(leftHandMatrix)));
print("Scale: " + JSON.stringify(Mat4.extractScale(leftHandMatrix))); // Always 1,1,1.

// Note: If using from the Avatar API, replace "MyAvatar" with "Avatar".
(static) getControllerRightHandMatrix( ) → {Mat4}
Returns: The rotation and translation of the right hand controller relative to the avatar.

Gets the rotation and translation of the right hand controller relative to the avatar.
(static) getDataRate( rateNameopt ) → {number}
Returns: The data rate in kbps.

Gets the amount of avatar mixer data being generated by the avatar.

Parameters

Name Type Attributes Default Value Description
rateName AvatarDataRate <optional>
 ""

The type of avatar mixer data to get the data rate of.
(static) getDomainMaxScale( ) → {number}
Returns: The maximum scale allowed for this avatar in the current domain.

Gets the maximum scale allowed for this avatar in the current domain. This value can change as the user changes avatars or when changing domains.
(static) getDomainMinScale( ) → {number}
Returns: The minimum scale allowed for this avatar in the current domain.

Gets the minimum scale allowed for this avatar in the current domain. This value can change as the user changes avatars or when changing domains.
(static) getEyeHeight( ) → {number}
Returns: The eye height of the avatar.

Gets the current eye height of the avatar. This height is only an estimate and might be incorrect for avatars that are missing standard joints.
(static) getHandState( ) → {HandState}
Returns: The pointing state of the hand.

Gets the pointing state of the hands to control where the laser emanates from. If the right index finger is pointing, the laser emanates from the tip of that finger, otherwise it emanates from the palm.
(static) getHeight( ) → {number}
Returns: The height of the avatar.

Gets the current height of the avatar. This height is only an estimate and might be incorrect for avatars that are missing standard joints.
(static) getJointIndex( name ) → {number}
Returns: The index of the joint if valid, otherwise -1.

Gets the joint index for a named joint. The joint index value is the position of the joint in the array returned by MyAvatar.getJointNames, or Avatar.getJointNames if using the Avatar API.

Parameters

Name Type Description
name string

The name of the joint.
Example

Report the index of your avatar's left arm joint.

print(JSON.stringify(MyAvatar.getJointIndex("LeftArm")));

// Note: If using from the Avatar API, replace "MyAvatar" with "Avatar".
(static) getJointNames( ) → {Array.<string>}
Returns: The joint names.

Gets the names of all the joints in the current avatar.

Example

Report the names of all the joints in your current avatar.

print(JSON.stringify(MyAvatar.getJointNames()));

// Note: If using from the Avatar API, replace "MyAvatar" with "Avatar".
(static) getJointRotation( index ) → {Quat}
Returns: The rotation of the joint relative to its parent.

Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see Avatar Standards.

Parameters

Name Type Description
index number

The index of the joint.
(static) getJointRotation( name ) → {Quat}
Returns: The rotation of the joint relative to its parent.

Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see Avatar Standards.

Parameters

Name Type Description
name string

The name of the joint.
Example

Report the rotation of your avatar's hips joint.

print(JSON.stringify(MyAvatar.getJointRotation("Hips")));

// Note: If using from the Avatar API, replace "MyAvatar" with "Avatar".
(static) getJointRotations( ) → {Array.<Quat>}
Returns: The rotations of all joints relative to each's parent. The values are in the same order as the array returned by MyAvatar.getJointNames, or Avatar.getJointNames if using the Avatar API.

Gets the rotations of all joints in the current avatar. Each joint's rotation is relative to its parent joint.

Example

Report the rotations of all your avatar's joints.

print(JSON.stringify(MyAvatar.getJointRotations()));

// Note: If using from the Avatar API, replace all "MyAvatar" with "Avatar".
(static) getJointTranslation( index ) → {Vec3}
Returns: The translation of the joint relative to its parent, in model coordinates.

Gets the translation of a joint relative to its parent, in model coordinates.

Warning: These coordinates are not necessarily in meters.

For information on the joint hierarchy used, see Avatar Standards.

Parameters

Name Type Description
index number

The index of the joint.
(static) getJointTranslation( name ) → {Vec3}
Returns: The translation of the joint relative to its parent, in model coordinates.

Gets the translation of a joint relative to its parent, in model coordinates.

Warning: These coordinates are not necessarily in meters.

For information on the joint hierarchy used, see Avatar Standards.

Parameters

Name Type Description
name number

The name of the joint.
Example

Report the translation of your avatar's hips joint.

print(JSON.stringify(MyAvatar.getJointRotation("Hips")));

// Note: If using from the Avatar API, replace "MyAvatar" with "Avatar".
(static) getJointTranslations( ) → {Array.<Vec3>}
Returns: The translations of all joints relative to each's parent, in model coordinates. The values are in the same order as the array returned by MyAvatar.getJointNames, or Avatar.getJointNames if using the Avatar API.

Gets the translations of all joints in the current avatar. Each joint's translation is relative to its parent joint, in model coordinates.

Warning: These coordinates are not necessarily in meters.
(static) getSensorToWorldMatrix( ) → {Mat4}
Returns: The scale, rotation, and translation transform from the user's real world to the avatar's size, orientation, and position in the virtual world.

Gets the transform from the user's real world to the avatar's size, orientation, and position in the virtual world.

Example

Report the sensor to world matrix.

var sensorToWorldMatrix = MyAvatar.getSensorToWorldMatrix();
print("Sensor to woprld matrix: " + JSON.stringify(sensorToWorldMatrix));
print("Rotation: " + JSON.stringify(Mat4.extractRotation(sensorToWorldMatrix)));
print("Translation: " + JSON.stringify(Mat4.extractTranslation(sensorToWorldMatrix)));
print("Scale: " + JSON.stringify(Mat4.extractScale(sensorToWorldMatrix)));

// Note: If using from the Avatar API, replace "MyAvatar" with "Avatar".
(static) getSensorToWorldScale( ) → {number}
Returns: The scale that transforms dimensions in the user's real world to the avatar's size in the virtual world.

Gets the scale that transforms dimensions in the user's real world to the avatar's size in the virtual world.
(static) getTargetScale( ) → {number}
Returns: The target scale of the avatar.

Gets the target scale of the avatar without any restrictions on permissible values imposed by the domain. In contrast, the scale property's value may be limited by the domain's settings.

Example

Compare the target and current avatar scales.

print("Current avatar scale: " + MyAvatar.scale);
print("Target avatar scale:  " + MyAvatar.getTargetScale());

// Note: If using from the Avatar API, replace all occurrences of "MyAvatar" with "Avatar".
(static) getUpdateRate( rateNameopt ) → {number}
Returns: The update rate in Hz.

Gets the update rate of avatar mixer data being generated by the avatar.

Parameters

Name Type Attributes Default Value Description
rateName AvatarUpdateRate <optional>
 ""

The type of avatar mixer data to get the update rate of.
(static) isJointDataValid( index ) → {boolean}
Returns: true if the joint data are valid, false if not.

Checks that the data for a joint are valid.

Parameters

Name Type Description
index number

The index of the joint.
(static) isJointDataValid( name ) → {boolean}
Returns: true if the joint data are valid, false if not.

Checks if the data for a joint are valid.

Parameters

Name Type Description
name string

The name of the joint.
(static) resetLastSent( )

Deprecated: This function is deprecated and will be removed.
(static) sendAvatarDataPacket( sendAllopt ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed.

Parameters

Name Type Attributes Default Value Description
sendAll boolean <optional>
 false

Send all.
(static) sendIdentityPacket( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed.
(static) setAbsoluteJointRotationInObjectFrame( index, rotation ) → {boolean}
Returns: false.

Sets the rotation of a joint relative to the avatar.

Warning: Not able to be used in the Avatar API.

Parameters

Name Type Description
index number

The index of the joint. Not used.
rotation Quat

The rotation of the joint relative to the avatar. Not used.
(static) setAbsoluteJointTranslationInObjectFrame( index, translation ) → {boolean}
Returns: false.

Sets the translation of a joint relative to the avatar.

Warning: Not able to be used in the Avatar API.

Parameters

Name Type Description
index number

The index of the joint. Not used.
translation Vec3

The translation of the joint relative to the avatar. Not used.
(static) setAttachmentData( attachmentData )

Sets all models currently attached to your avatar. For example, if you retrieve attachment data using MyAvatar.getAttachmentData or Avatar.getAttachmentData, make changes to it, and then want to update your avatar's attachments per the changed data. You can also remove all attachments by using setting attachmentData to null.

Deprecated: This function is deprecated and will be removed. Use avatar entities instead.

Parameters

Name Type Description
attachmentData Array.<AttachmentData>

The attachment data defining the models to have attached to your avatar. Use null to remove all attachments.
Example

Remove a hat attachment if your avatar is wearing it.

var hatURL = "https://apidocs.vircadia.dev/models/cowboy-hat.fbx";
var attachments = MyAvatar.getAttachmentData();

for (var i = 0; i < attachments.length; i++) {
    if (attachments[i].modelURL === hatURL) {
        attachments.splice(i, 1);
        MyAvatar.setAttachmentData(attachments);
        break;
    }
 }

// Note: If using from the Avatar API, replace all occurrences of "MyAvatar" with "Avatar".
(static) setAttachmentsVariant( variant )

Sets all models currently attached to your avatar. For example, if you retrieve attachment data using MyAvatar.getAttachmentsVariant or Avatar.getAttachmentsVariant, make changes to it, and then want to update your avatar's attachments per the changed data.

Deprecated: This function is deprecated and will be removed. Use avatar entities instead.

Parameters

Name Type Description
variant Array.<AttachmentData>

The attachment data defining the models to have attached to your avatar.
(static) setAvatarEntityData( avatarEntityData )

Sets all avatar entities from an object.

Warning: Potentially an expensive call. Do not use if possible.

Parameters

Name Type Description
avatarEntityData AvatarEntityMap

Details of the avatar entities.
(static) setBlendshape( name, value )

Sets the value of a blend shape to animate your avatar's face. In order for other users to see the resulting animations on your avatar's face, set hasScriptedBlendshapes to true. When you are done using this API, set hasScriptedBlendshapes back to false when the animation is complete.

Parameters

Name Type Description
name string

The name of the blendshape, per the Avatar Standards.
value number

A value between 0.0 and 1.0.
Example

Open your avatar's mouth wide.

MyAvatar.hasScriptedBlendshapes = true;
MyAvatar.setBlendshape("JawOpen", 1.0);

// Note: If using from the Avatar API, replace "MyAvatar" with "Avatar".
(static) setForceFaceTrackerConnected( connected )

Enables blend shapes set using Avatar.setBlendshape or MyAvatar.setBlendshape to be transmitted to other users so that they can see the animation of your avatar's face.

Deprecated: This method is deprecated and will be removed. Use the Avatar.hasScriptedBlendshapes or MyAvatar.hasScriptedBlendshapes property instead.

Parameters

Name Type Description
connected boolean

true to enable blend shape changes to be transmitted to other users, false to disable.
(static) setHandState( state )

Sets the pointing state of the hands to control where the laser emanates from. If the right index finger is pointing, the laser emanates from the tip of that finger, otherwise it emanates from the palm.

Parameters

Name Type Description
state HandState

The pointing state of the hand.
(static) setJointData( index, rotation, translation )

Sets a specific joint's rotation and position relative to its parent, in model coordinates.

Warning: These coordinates are not necessarily in meters.

Setting joint data completely overrides/replaces all motion from the default animation system including inverse kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

Parameters

Name Type Description
index number

The index of the joint.
rotation Quat

The rotation of the joint relative to its parent.
translation Vec3

The translation of the joint relative to its parent, in model coordinates.
Example

Set your avatar to it's default T-pose for a while.
Avatar in T-pose

// Set all joint translations and rotations to defaults.
var i, length, rotation, translation;
for (i = 0, length = MyAvatar.getJointNames().length; i < length; i++) {
    rotation = MyAvatar.getDefaultJointRotation(i);
    translation = MyAvatar.getDefaultJointTranslation(i);
    MyAvatar.setJointData(i, rotation, translation);
}

// Restore your avatar's motion after 5s.
Script.setTimeout(function () {
    MyAvatar.clearJointsData();
}, 5000);

// Note: If using from the Avatar API, replace all occurrences of "MyAvatar" with "Avatar".
(static) setJointData( name, rotation, translation )

Sets a specific joint's rotation and position relative to its parent, in model coordinates.

Warning: These coordinates are not necessarily in meters.

Setting joint data completely overrides/replaces all motion from the default animation system including inverse kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

Parameters

Name Type Description
name string

The name of the joint.
rotation Quat

The rotation of the joint relative to its parent.
translation Vec3

The translation of the joint relative to its parent, in model coordinates.
(static) setJointMappingsFromNetworkReply( )

Deprecated: This function is deprecated and will be removed.
(static) setJointRotation( index, rotation )

Sets a specific joint's rotation relative to its parent.

Setting joint data completely overrides/replaces all motion from the default animation system including inverse kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

Parameters

Name Type Description
index number

The index of the joint.
rotation Quat

The rotation of the joint relative to its parent.
(static) setJointRotation( name, rotation )

Sets a specific joint's rotation relative to its parent.

Setting joint data completely overrides/replaces all motion from the default animation system including inverse kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

Parameters

Name Type Description
name string

The name of the joint.
rotation Quat

The rotation of the joint relative to its parent.
Example

Set your avatar to its default T-pose then rotate its right arm.
Avatar in T-pose with arm rotated

// Set all joint translations and rotations to defaults.
var i, length, rotation, translation;
for (i = 0, length = MyAvatar.getJointNames().length; i < length; i++) {
    rotation = MyAvatar.getDefaultJointRotation(i);
    translation = MyAvatar.getDefaultJointTranslation(i);
    MyAvatar.setJointData(i, rotation, translation);
}

// Rotate the right arm.
var newArmRotation = { x: 0.47, y: 0.22, z: -0.02, w: 0.87 };
MyAvatar.setJointRotation("RightArm", newArmRotation);

// Restore your avatar's motion after 5s.
Script.setTimeout(function () {
    MyAvatar.clearJointsData();
}, 5000);

// Note: If using from the Avatar API, replace all occurrences of "MyAvatar" with "Avatar".
(static) setJointRotations( jointRotations )

Sets the rotations of all joints in the current avatar. Each joint's rotation is relative to its parent joint.

Setting joint data completely overrides/replaces all motion from the default animation system including inverse kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

Parameters

Name Type Description
jointRotations Array.<Quat>

The rotations for all joints in the avatar. The values are in the same order as the array returned by MyAvatar.getJointNames, or Avatar.getJointNames if using the Avatar API.
Example

Set your avatar to its default T-pose then rotate its right arm.
Avatar in T-pose

// Set all joint translations and rotations to defaults.
var i, length, rotation, translation;
for (i = 0, length = MyAvatar.getJointNames().length; i < length; i++) {
    rotation = MyAvatar.getDefaultJointRotation(i);
    translation = MyAvatar.getDefaultJointTranslation(i);
    MyAvatar.setJointData(i, rotation, translation);
}

// Get all join rotations.
var jointRotations = MyAvatar.getJointRotations();

// Update the rotation of the right arm in the array.
jointRotations[MyAvatar.getJointIndex("RightArm")] = { x: 0.47, y: 0.22, z: -0.02, w: 0.87 };

// Update all joint rotations.
MyAvatar.setJointRotations(jointRotations);

// Restore your avatar's motion after 5s.
Script.setTimeout(function () {
    MyAvatar.clearJointsData();
}, 5000);

// Note: If using from the Avatar API, replace all occurrences of "MyAvatar" with "Avatar".
(static) setJointTranslation( index, translation )

Sets a specific joint's translation relative to its parent, in model coordinates.

Warning: These coordinates are not necessarily in meters.

Setting joint data completely overrides/replaces all motion from the default animation system including inverse kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

Parameters

Name Type Description
index number

The index of the joint.
translation Vec3

The translation of the joint relative to its parent, in model coordinates.
(static) setJointTranslation( name, translation )

Sets a specific joint's translation relative to its parent, in model coordinates.

Warning: These coordinates are not necessarily in meters.

Setting joint data completely overrides/replaces all motion from the default animation system including inverse kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

Parameters

Name Type Description
name string

The name of the joint.
translation Vec3

The translation of the joint relative to its parent, in model coordinates.
Example

Stretch your avatar's neck. Depending on the avatar you are using, you will either see a gap between the head and body or you will see the neck stretched.
Avatar with neck stretched

// Stretch your avatar's neck.
MyAvatar.setJointTranslation("Neck", Vec3.multiply(2, MyAvatar.getJointTranslation("Neck")));

// Restore your avatar's neck after 5s.
Script.setTimeout(function () {
    MyAvatar.clearJointData("Neck");
}, 5000);

// Note: If using from the Avatar API, replace all occurrences of "MyAvatar" with "Avatar".
(static) setJointTranslations( translations )

Sets the translations of all joints in the current avatar. Each joint's translation is relative to its parent joint, in model coordinates.

Warning: These coordinates are not necessarily in meters.

Setting joint data completely overrides/replaces all motion from the default animation system including inverse kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

Parameters

Name Type Description
translations Array.<Vec3>

The translations for all joints in the avatar, in model coordinates. The values are in the same order as the array returned by MyAvatar.getJointNames, or Avatar.getJointNames if using the Avatar API.
(static) setRawJointData( data )

Sets joint translations and rotations from raw joint data.

Deprecated: This function is deprecated and will be removed.

Parameters

Name Type Description
data Array.<JointData>

The raw joint data.
(static) setSessionUUID( sessionUUID )

Deprecated: This function is deprecated and will be removed.

Parameters

Name Type Description
sessionUUID Uuid

Session UUID.
(static) setSkeletonModelURL( url )

Sets the avatar's skeleton model.

Parameters

Name Type Description
url string

The avatar's FST file.
(static) startAnimation( url, fpsopt, priorityopt, loopopt, holdopt, firstFrameopt, lastFrameopt, maskedJointsopt )

Starts playing an animation on the avatar.

Parameters

Name Type Attributes Default Value Description
url string

The animation file's URL. Animation files need to be in glTF or FBX format but only need to contain the avatar skeleton and animation data. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs respectively).

Warning: glTF animations currently do not always animate correctly.
fps number <optional>
 30

The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed.
priority number <optional>
 1

Not used.
loop boolean <optional>
 false

true if the animation should loop, false if it shouldn't.
hold boolean <optional>
 false

Not used.
firstFrame number <optional>
 0

The frame at which the animation starts.
lastFrame number <optional>
 3.403e+38

The frame at which the animation stops.
maskedJoints Array.<string> <optional>
 []

The names of joints that should not be animated.
(static) stopAnimation( )

Stops playing the current animation.
(static) update( deltaTime )

Deprecated: This function is deprecated and will be removed.

Parameters

Name Type Description
deltaTime number

Delta time.
(static) updateAvatarEntity( entityID, entityData )

Deprecated: This function is deprecated and will be removed.

Parameters

Name Type Description
entityID Uuid

The entity ID.
entityData ArrayBuffer

Entity data.

Signal Details

displayNameChanged( )
Returns: Signal

Triggered when the avatar's displayName property value changes.

Example

Report when your avatar display name changes.

MyAvatar.displayNameChanged.connect(function () {
    print("Avatar display name changed to: " + MyAvatar.displayName);
});

// Note: If using from the Avatar API, replace "MyAvatar" with "Avatar".
lookAtSnappingChanged( enabled )
Returns: Signal

Triggered when the avatar's lookAtSnappingEnabled property value changes.

Parameters

Name Type Description
enabled boolean

true if look-at snapping is enabled, false if not.
Example

Report when your look-at snapping setting changes.

MyAvatar.lookAtSnappingChanged.connect(function () {
    print("Avatar look-at snapping changed to: " + MyAvatar.lookAtSnappingEnabled);
});

// Note: If using from the Avatar API, replace "MyAvatar" with "Avatar".
sessionDisplayNameChanged( )
Returns: Signal

Triggered when the avatar's sessionDisplayName property value changes.

Example

Report when your avatar's session display name changes.

MyAvatar.sessionDisplayNameChanged.connect(function () {
    print("Avatar session display name changed to: " + MyAvatar.sessionDisplayName);
});

// Note: If using from the Avatar API, replace "MyAvatar" with "Avatar".
sessionUUIDChanged( )
Returns: Signal

Triggered when the avatar's sessionUUID property value changes.

Example

Report when your avatar's session UUID changes.

MyAvatar.sessionUUIDChanged.connect(function () {
    print("Avatar session UUID changed to: " + MyAvatar.sessionUUID);
});

// Note: If using from the Avatar API, replace "MyAvatar" with "Avatar".
skeletonModelURLChanged( )
Returns: Signal

Triggered when the avatar's model (i.e., skeletonModelURL property value) changes.

Example

Report when your avatar's skeleton model changes.

MyAvatar.skeletonModelURLChanged.connect(function () {
    print("Skeleton model changed to: " + MyAvatar.skeletonModelURL);
});

// Note: If using from the Avatar API, replace "MyAvatar" with "Avatar".