Avatar

Available in: Assignment Client Scripts

The Avatar API is used to manipulate scriptable avatars on the domain. This API is a subset of the MyAvatar API.

Note: In the examples, use "Avatar" instead of "MyAvatar".

Methods

Signals

Type Definitions

Properties:
Name Type Description
position Vec3
scale number
density number Read-only.
handPosition Vec3
bodyYaw number The rotation left or right 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
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
angularVelocity Vec3
audioLoudness number
audioAverageLoudness number
displayName string
sessionDisplayName string Sanitized, defaulted version displayName that is defined by the AvatarMixer rather than by Interface clients. The result is unique among all avatars present at the time.
lookAtSnappingEnabled boolean
skeletonModelURL string
attachmentData Array.<AttachmentData>
jointNames Array.<string> The list of joints in the current avatar model. Read-only.
sessionUUID Uuid Read-only.
sensorToWorldMatrix Mat4 Read-only.
controllerLeftHandMatrix Mat4 Read-only.
controllerRightHandMatrix Mat4 Read-only.
sensorToWorldScale number Read-only.

Methods

attach(modelURL, jointNameopt, translationopt, rotationopt, scaleopt, isSoftopt, allowDuplicatesopt, useSavedopt)
Attach 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.

Parameters:
Name Type Attributes Default 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 be 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
useSaved boolean <optional>
true
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);
clearAvatarEntity(entityID)
Parameters:
Name Type Description
entityID Uuid
clearJointData(index)
Clear 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.
clearJointData(name)
Clear 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.

// Move your avatar's head up by 25cm from where it should be.
MyAvatar.setJointTranslation("Neck", { x: 0, y: 0.25, z: 0 });

// Restore your avatar's head to its default position after 5s.
Script.setTimeout(function () {
   MyAvatar.clearJointData("Neck");
}, 5000);
clearJointsData()
Clear 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);
detachAll(modelURL, jointNameopt)
Detach all instances of a particular model from either a specific joint or all joints.
Parameters:
Name Type Attributes Default 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.
detachOne(modelURL, jointNameopt)
Detach the most recently attached instance of a particular model from either a specific joint or any joint.
Parameters:
Name Type Attributes Default 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.
getAbsoluteJointRotationInObjectFrame(index) → {Quat}
Parameters:
Name Type Description
index number
Returns:
Type: Quat
getAbsoluteJointTranslationInObjectFrame(index) → {Vec3}
Parameters:
Name Type Description
index number
Returns:
Type: Vec3
getAnimationDetails() → {Avatar.AnimationDetails}
Returns:
Type: Avatar.AnimationDetails
getAttachmentData() → {Array.<AttachmentData>}
Get information about all models currently attached to your avatar.
Returns:
Information about all models attached to your avatar.
Type: Array.< AttachmentData>
Example

Report the URLs of all current attachments.

var attachments = MyAvatar.getaAttachmentData();
for (var i = 0; i < attachments.length; i++) {
   print (attachments[i].modelURL);
}
getAttachmentsVariant() → {object}
Returns:
Type: object
getAvatarEntityData() → {object}
Returns:
Type: object
getControllerLeftHandMatrix() → {Mat4}
Returns:
Type: Mat4
getControllerRightHandMatrix() → {Mat4}
Returns:
Type: Mat4
getDataRate(rateNameopt) → {number}
Parameters:
Name Type Attributes Default Description
rateName string <optional>
""
Returns:
Type: number
getDomainMaxScale() → {number}
Returns the maximum scale allowed for this avatar in the current domain. This value can change as the user changes avatars or when changing domains.
Returns:
maximum scale allowed for this avatar in the current domain.
Type: number
getDomainMinScale() → {number}
Returns the minimum scale allowed for this avatar in the current domain. This value can change as the user changes avatars or when changing domains.
Returns:
minimum scale allowed for this avatar in the current domain.
Type: number
getEyeHeight() → {number}
Provides read only access to the current eye height of the avatar. This height is only an estimate and might be incorrect for avatars that are missing standard joints.
Returns:
Eye height of avatar in meters.
Type: number
getHandState() → {string}
Returns:
Type: string
getHeight() → {number}
Provides read only access to the current height of the avatar. This height is only an estimate and might be incorrect for avatars that are missing standard joints.
Returns:
Height of avatar in meters.
Type: number
getJointIndex(name) → {number}
Get 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.
Parameters:
Name Type Description
name string The name of the joint.
Returns:
The index of the joint.
Type: number
Example

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

print(JSON.stringify(MyAvatar.getJointIndex("LeftArm"));
getJointNames() → {Array.<string>}
Get the names of all the joints in the current avatar.
Returns:
The joint names.
Type: Array.<string>
Example

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

print(JSON.stringify(MyAvatar.getJointNames()));
getJointRotation(name) → {Quat}
Get 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.
Returns:
The rotation of the joint relative to its parent.
Type: Quat
Example

Report the rotation of your avatar's hips joint.

print(JSON.stringify(MyAvatar.getJointRotation("Hips")));
getJointRotation(index) → {Quat}
Get 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.
Returns:
The rotation of the joint relative to its parent.
Type: Quat
getJointRotations() → {Array.<Quat>}
Get the rotations of all joints in the current avatar. Each joint's rotation is relative to its parent joint.
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.
Type: Array.< Quat>
Example

Report the rotations of all your avatar's joints.

print(JSON.stringify(MyAvatar.getJointRotations()));
getJointTranslation(index) → {Vec3}
Get the translation 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.
Returns:
The translation of the joint relative to its parent.
Type: Vec3
getJointTranslation(name) → {Vec3}
Get the translation of a joint relative to its parent. For information on the joint hierarchy used, see Avatar Standards.
Parameters:
Name Type Description
name number The name of the joint.
Returns:
The translation of the joint relative to its parent.
Type: Vec3
Example

Report the translation of your avatar's hips joint.

print(JSON.stringify(MyAvatar.getJointRotation("Hips")));
getJointTranslations() → {Array.<Vec3>}
Returns:
Type: Array.< Vec3>
getSensorToWorldMatrix() → {Mat4}
Returns:
Type: Mat4
getSensorToWorldScale() → {number}
Returns:
Type: number
getTargetScale() → {number}
Returns:
Type: number
getUpdateRate(rateNameopt) → {number}
Parameters:
Name Type Attributes Default Description
rateName string <optional>
""
Returns:
Type: number
isJointDataValid(name) → {boolean}
Parameters:
Name Type Description
name string
Returns:
Type: boolean
isJointDataValid(index) → {boolean}
Parameters:
Name Type Description
index number
Returns:
Type: boolean
resetLastSent()
sendAvatarDataPacket(sendAllopt)
Parameters:
Name Type Attributes Default Description
sendAll boolean <optional>
false
sendIdentityPacket()
setAbsoluteJointRotationInObjectFrame(index, rotation) → {boolean}
Parameters:
Name Type Description
index number
rotation Quat
Returns:
Type: boolean
setAbsoluteJointTranslationInObjectFrame(index, translation) → {boolean}
Parameters:
Name Type Description
index number
translation Vec3
Returns:
Type: boolean
setAttachmentData(attachmentData)
Set 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.
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;
   }
}
setAttachmentsVariant(variant)
Parameters:
Name Type Description
variant object
setAvatarEntityData(avatarEntityData)
Parameters:
Name Type Description
avatarEntityData object
setBlendshape(name, value)
Parameters:
Name Type Description
name string
value number
setForceFaceTrackerConnected(connected)
Parameters:
Name Type Description
connected boolean
setHandState(state)
Parameters:
Name Type Description
state string
setJointData(name, rotation, translation)
Set a specific joint's rotation and position 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.
translation Vec3 The translation of the joint relative to its parent.
setJointData(index, rotation, translation)
Set a specific joint's rotation and position 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.
translation Vec3 The translation of the joint relative to its parent.
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);
setJointMappingsFromNetworkReply()
setJointRotation(name, rotation)
Set 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);
setJointRotation(index, rotation)
Set 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.
setJointRotations(jointRotations)
Set 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.
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);
setJointTranslation(name, translation)
Set a specific joint's translation 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.
translation Vec3 The translation of the joint relative to its parent.
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", { x: 0, y: 25, z: 0 });

// Restore your avatar's neck after 5s.
Script.setTimeout(function () {
   MyAvatar.clearJointData("Neck");
}, 5000);
setJointTranslation(index, translation)
Set a specific joint's translation 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.
translation Vec3 The translation of the joint relative to its parent.
setJointTranslations(translations)
Parameters:
Name Type Description
translations Array.<Vec3>
setRawJointData(data)
Parameters:
Name Type Description
data Array.<JointData>
setSessionUUID(sessionUUID)
Parameters:
Name Type Description
sessionUUID Uuid
startAnimation(url, fpsopt, priorityopt, loopopt, hold opt, firstFrameopt, lastFrameopt, maskedJointsopt)
Parameters:
Name Type Attributes Default Description
url string
fps number <optional>
30
priority number <optional>
1
loop boolean <optional>
false
hold boolean <optional>
false
firstFrame number <optional>
0
lastFrame number <optional>
3.403e+38
maskedJoints Array.<string> <optional>
[]
stopAnimation()
updateAvatarEntity(entityID, entityData)
Parameters:
Name Type Description
entityID Uuid
entityData string

Signals

displayNameChanged() → {Signal}
Returns:
Type: Signal
lookAtSnappingChanged(enabled) → {Signal}
Parameters:
Name Type Description
enabled boolean
Returns:
Type: Signal
sessionDisplayNameChanged() → {Signal}
Returns:
Type: Signal
sessionUUIDChanged() → {Signal}
Returns:
Type: Signal
skeletonModelURLChanged() → {Signal}
Returns:
Type: Signal

Type Definitions

AnimationDetails
Type: object
Properties:
Name Type Description
role string
url string
fps number
priority number
loop boolean
hold boolean
startAutomatically boolean
firstFrame number
lastFrame number
running boolean
currentFrame number
allowTranslation boolean