Avatar

Description

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.

Supported Script Types: Assignment Client Scripts

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 is the avatar in a Hero zone? Read-only.

Example

Create a scriptable avatar.

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

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.

Note: Attached models are models only; they are not entities and can not be manipulated using the Entities API. Nor can you use this function to attach an entity (such as a sphere or a box) to your avatar.

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 slower than the function variation that specifies the joint index.

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.

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 blendshape to animate your avatar's face. To enable other users to see the resulting animation of your avatar's face, use Avatar.setForceFaceTrackerConnected or MyAvatar.setForceFaceTrackerConnected.
setForceFaceTrackerConnected None Enables blendshapes 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.
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.

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) is changed.

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 .FBX format but only need to contain the avatar skeleton and animation data.
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.

Note: Attached models are models only; they are not entities and can not be manipulated using the Entities API. Nor can you use this function to attach an entity (such as a sphere or a box) to your avatar.

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 attach. Models can be .FBX or .OBJ format.
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://s3.amazonaws.com/hifi-public/tony/cowboy-hat.fbx",
    jointName: "Head",
    translation: {"x": 0, "y": 0.25, "z": 0},
    rotation: {"x": 0, "y": 0, "z": 0, "w": 1},
    scale: 1,
    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 Requires removal from tree.
(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) 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) 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 the 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( 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) 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) 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://s3.amazonaws.com/hifi-public/tony/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 blendshape to animate your avatar's face. To enable other users to see the resulting animation of your avatar's face, use Avatar.setForceFaceTrackerConnected or MyAvatar.setForceFaceTrackerConnected.

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.setForceFaceTrackerConnected(true);
MyAvatar.setBlendshape("JawOpen", 1.0);

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

Enables blendshapes 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.

Parameters

Name Type Description
connected boolean true to enable blendshape 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( 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) 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) 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( 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) 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) 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) 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 the FBX format but only need to contain the avatar skeleton and animation data.
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 Array.<byte> 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) is changed.

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