| Property | Type | Description |
|---|---|---|
id | Uuid | Entity ID. |
properties | {@link Entities.EntityProperties} | Entity properties. |
MyAvatar API is used to manipulate the avatar.
* For example, you can customize the avatar's appearance, run custom avatar animations,
- * change the avatar's position within the domain, or manage the avatar's collisions with other objects.
+ * change the avatar's position within the domain, or manage the avatar's collisions with the environment and other avatars.
+ *
+ * For assignment client scripts, see {@link Avatar}.
* * @namespace MyAvatar * @@ -69,17 +71,20 @@ class MyAvatar : public Avatar { * @hifi-avatar * * @comment IMPORTANT: This group of properties is copied from AvatarData.h; they should NOT be edited here. - * @property {Vec3} position - * @property {number} scale - Returns the clamped scale of the avatar. - * @property {number} density Read-only. - * @property {Vec3} handPosition + * @property {Vec3} position - The position of the avatar. + * @property {number} scale=1.0 - The scale of the avatar. When setting, the value is limited to between0.005
+ * and 1000.0. When getting, the value may temporarily be further limited by the domain's settings.
+ * @property {number} density - The density of the avatar in kg/m3. The density is used to work out its mass in
+ * the application of physics. Read-only.
+ * @property {Vec3} handPosition - A user-defined hand position, in world coordinates. The position moves with the avatar
+ * but is otherwise not used or changed by Interface.
* @property {number} bodyYaw - The rotation left or right about an axis running from the head to the feet of the avatar.
* Yaw is sometimes called "heading".
* @property {number} bodyPitch - The rotation about an axis running from shoulder to shoulder of the avatar. Pitch is
* sometimes called "elevation".
* @property {number} bodyRoll - The rotation about an axis running from the chest to the back of the avatar. Roll is
* sometimes called "bank".
- * @property {Quat} orientation
+ * @property {Quat} orientation - The orientation of the avatar.
* @property {Quat} headOrientation - The orientation of the avatar's head.
* @property {number} headPitch - The rotation about an axis running from ear to ear of the avatar's head. Pitch is
* sometimes called "elevation".
@@ -87,22 +92,31 @@ class MyAvatar : public Avatar {
* head. Yaw is sometimes called "heading".
* @property {number} headRoll - The rotation about an axis running from the nose to the back of the avatar's head. Roll is
* sometimes called "bank".
- * @property {Vec3} velocity
- * @property {Vec3} angularVelocity
- * @property {number} audioLoudness
- * @property {number} audioAverageLoudness
- * @property {string} displayName
- * @property {string} sessionDisplayName - 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.
- * @property {boolean} lookAtSnappingEnabled
- * @property {string} skeletonModelURL
- * @property {AttachmentData[]} attachmentData
+ * @property {Vec3} velocity - The current velocity of the avatar.
+ * @property {Vec3} angularVelocity - The current angular velocity of the avatar.
+ * @property {number} audioLoudness - The instantaneous loudness of the audio input that the avatar is injecting into the
+ * domain.
+ * @property {number} audioAverageLoudness - The rolling average loudness of the audio input that the avatar is injecting
+ * into the domain.
+ * @property {string} displayName - The avatar's display name.
+ * @property {string} sessionDisplayName - Sanitized, defaulted version of displayName that is defined by the
+ * avatar mixer rather than by Interface clients. The result is unique among all avatars present in the domain at the
+ * time.
+ * @property {boolean} lookAtSnappingEnabled=true - If true, the avatar's eyes snap to look at another avatar's
+ * eyes if generally in the line of sight and the other avatar also has lookAtSnappingEnabled == true.
+ * @property {string} skeletonModelURL - The URL of the avatar model's .fst file.
+ * @property {AttachmentData[]} attachmentData - Information on the attachments worn by the avatar.audioListenerModeHeadaudioListenerModeCameraaudioListenerModeCustom
+ * Myavatar.audioListenerModeHeadMyavatar.audioListenerModeCameraMyavatar.audioListenerModeCustom
* @property {number} audioListenerModeHead=0 - The audio listening position is at the avatar's head. Read-only.
* @property {number} audioListenerModeCamera=1 - The audio listening position is at the camera. Read-only.
* @property {number} audioListenerModeCustom=2 - The audio listening position is at a the position specified by set by the
@@ -135,10 +149,12 @@ class MyAvatar : public Avatar {
* property value is audioListenerModeCustom.
* @property {Quat} customListenOrientation=Quat.IDENTITY - The listening orientation used when the
* audioListenerMode property value is audioListenerModeCustom.
- * @property {boolean} hasScriptedBlendshapes=false - Blendshapes will be transmitted over the network if set to true.
- * @property {boolean} hasProceduralBlinkFaceMovement=true - procedural blinking will be turned on if set to true.
- * @property {boolean} hasProceduralEyeFaceMovement=true - procedural eye movement will be turned on if set to true.
- * @property {boolean} hasAudioEnabledFaceMovement=true - If set to true, voice audio will move the mouth Blendshapes while MyAvatar.hasScriptedBlendshapes is enabled.
+ * @property {boolean} hasScriptedBlendshapes=false - Blendshapes will be transmitted over the network if set to true.true then procedural blinking is turned on.
+ * @property {boolean} hasProceduralEyeFaceMovement=true - If true then procedural eye movement is turned on.
+ * @property {boolean} hasAudioEnabledFaceMovement=true - If true then voice audio will move the mouth
+ * blendshapes while MyAvatar.hasScriptedBlendshapes is enabled.
* @property {number} rotationRecenterFilterLength
* @property {number} rotationThreshold
* @property {boolean} enableStepResetRotation
@@ -169,16 +185,18 @@ class MyAvatar : public Avatar {
* @property {boolean} hmdLeanRecenterEnabled=true - If true then the avatar is re-centered to be under the
* head's position. In room-scale VR, this behavior is what causes your avatar to follow your HMD as you walk around
* the room. Setting the value false is useful if you want to pin the avatar to a fixed position.
- * @property {boolean} collisionsEnabled - Set to true to enable collisions for the avatar, false
- * to disable collisions. May return true even though the value was set false because the
- * zone may disallow collisionless avatars.
- * @property {boolean} otherAvatarsCollisionsEnabled
- * @property {boolean} characterControllerEnabled - Synonym of collisionsEnabled.
+ * @property {boolean} collisionsEnabled - Set to true to enable the avatar to collide with the environment,
+ * false to disable collisions with the environment. May return true even though the value
+ * was set false because the zone may disallow collisionless avatars.
+ * @property {boolean} otherAvatarsCollisionsEnabled - Set to true to enable the avatar to collide with other
+ * avatars, false to disable collisions with other avatars.
+ * @property {boolean} characterControllerEnabled - Synonym of collisionsEnabled.collisionsEnabled instead.
* @property {boolean} useAdvancedMovementControls - Returns and sets the value of the Interface setting, Settings >
- * Walking and teleporting. Note: Setting the value has no effect unless Interface is restarted.
- * @property {boolean} showPlayArea - Returns and sets the value of the Interface setting, Settings > Show room boundaries
- * while teleporting. Note: Setting the value has no effect unless Interface is restarted.
+ * Controls > Walking. Note: Setting the value has no effect unless Interface is restarted.
+ * @property {boolean} showPlayArea - Returns and sets the value of the Interface setting, Settings > Controls > Show room
+ * boundaries while teleporting.hmdRollControlEnabled is enabled.
- * @property {number} hmdRollControlRate If hmdRollControlEnabled is true, this value determines the maximum turn rate of
- * your avatar when rolling your HMD in degrees per second.
+ * @property {number} hmdRollControlRate If MyAvatar.hmdRollControlEnabled is true, this value determines the
+ * maximum turn rate of your avatar when rolling your HMD in degrees per second.
*
* @property {number} userHeight=1.75 - The height of the user in sensor space.
* @property {number} userEyeHeight=1.65 - The estimated height of the user's eyes in sensor space. Read-only.
@@ -237,8 +255,8 @@ class MyAvatar : public Avatar {
* @borrows Avatar.attach as attach
* @borrows Avatar.detachOne as detachOne
* @borrows Avatar.detachAll as detachAll
- * @borrows Avatar.getAvatarEntityData as getAvatarEntityData
- * @borrows Avatar.setAvatarEntityData as setAvatarEntityData
+ * @comment Avatar.getAvatarEntityData as getAvatarEntityData - Don't borrow because implementation is different.
+ * @comment Avatar.setAvatarEntityData as setAvatarEntityData - Don't borrow because implementation is different.
* @borrows Avatar.getSensorToWorldMatrix as getSensorToWorldMatrix
* @borrows Avatar.getSensorToWorldScale as getSensorToWorldScale
* @borrows Avatar.getControllerLeftHandMatrix as getControllerLeftHandMatrix
@@ -253,10 +271,10 @@ class MyAvatar : public Avatar {
* @borrows Avatar.sendAvatarDataPacket as sendAvatarDataPacket
* @borrows Avatar.sendIdentityPacket as sendIdentityPacket
* @borrows Avatar.setSessionUUID as setSessionUUID
- * @borrows Avatar.getAbsoluteJointRotationInObjectFrame as getAbsoluteJointRotationInObjectFrame
- * @borrows Avatar.getAbsoluteJointTranslationInObjectFrame as getAbsoluteJointTranslationInObjectFrame
- * @borrows Avatar.setAbsoluteJointRotationInObjectFrame as setAbsoluteJointRotationInObjectFrame
- * @borrows Avatar.setAbsoluteJointTranslationInObjectFrame as setAbsoluteJointTranslationInObjectFrame
+ * @comment Avatar.getAbsoluteJointRotationInObjectFrame as getAbsoluteJointRotationInObjectFrame - Don't borrow because implementation is different.
+ * @comment Avatar.getAbsoluteJointTranslationInObjectFrame as getAbsoluteJointTranslationInObjectFrame - Don't borrow because implementation is different.
+ * @comment Avatar.setAbsoluteJointRotationInObjectFrame as setAbsoluteJointRotationInObjectFrame - Don't borrow because implementation is different.
+ * @comment Avatar.setAbsoluteJointTranslationInObjectFrame as setAbsoluteJointTranslationInObjectFrame - Don't borrow because implementation is different.
* @borrows Avatar.getTargetScale as getTargetScale
* @borrows Avatar.resetLastSent as resetLastSent
*/
@@ -393,8 +411,9 @@ public:
/**jsdoc
- * The internal inverse-kinematics system maintains a record of which joints are "locked". Sometimes it is useful to forget this history, to prevent
- * contorted joints.
+ * Clears inverse kinematics joint limit history.
+ * The internal inverse-kinematics system maintains a record of which joints are "locked". Sometimes it is useful to + * forget this history, to prevent contorted joints.
* @function MyAvatar.clearIKJointLimitHistory */ Q_INVOKABLE void clearIKJointLimitHistory(); // thread-safe @@ -441,7 +460,7 @@ public: void setRealWorldFieldOfView(float realWorldFov) { _realWorldFieldOfView.set(realWorldFov); } /**jsdoc - * Get the position in world coordinates of the point directly between your avatar's eyes assuming your avatar was in its + * Gets the position in world coordinates of the point directly between your avatar's eyes assuming your avatar was in its * default pose. This is a reference position; it does not change as your avatar's head moves relative to the avatar * position. * @function MyAvatar.getDefaultEyePosition @@ -455,15 +474,16 @@ public: float getRealWorldFieldOfView() { return _realWorldFieldOfView.get(); } /**jsdoc - * The avatar animation system includes a set of default animations along with rules for how those animations are blended - * together with procedural data (such as look at vectors, hand sensors etc.). overrideAnimation() is used to completely - * override all motion from the default animation system (including inverse kinematics for hand and head controllers) and - * play a set of specified animations. To end these animations and restore the default animations, use - * {@link MyAvatar.restoreAnimation}.The avatar animation system includes a set of default animations along with rules for how those animations are blended
+ * together with procedural data (such as look at vectors, hand sensors etc.). overrideAnimation() is used to
+ * completely override all motion from the default animation system (including inverse kinematics for hand and head
+ * controllers) and play a set of specified animations. To end these animations and restore the default animations, use
+ * {@link MyAvatar.restoreAnimation}.
Note: When using pre-built animation data, it's critical that the joint orientation of the source animation and target * rig are equivalent, since the animation data applies absolute values onto the joints. If the orientations are different, * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see - * Avatar Standards.
+ * Avatar Standards. * @function MyAvatar.overrideAnimation * @param url {string} The URL to the animation file. Animation files need to be .FBX format, but only need to contain the * avatar skeleton and animation data. @@ -482,10 +502,12 @@ public: Q_INVOKABLE void overrideAnimation(const QString& url, float fps, bool loop, float firstFrame, float lastFrame); /**jsdoc - * The avatar animation system includes a set of default animations along with rules for how those animations are blended together with - * procedural data (such as look at vectors, hand sensors etc.). Playing your own custom animations will override the default animations. - * restoreAnimation() is used to restore all motion from the default animation system including inverse kinematics for hand and head - * controllers. If you aren't currently playing an override animation, this function will have no effect. + * Restores the default animations. + *The avatar animation system includes a set of default animations along with rules for how those animations are blended
+ * together with procedural data (such as look at vectors, hand sensors etc.). Playing your own custom animations will
+ * override the default animations. restoreAnimation() is used to restore all motion from the default
+ * animation system including inverse kinematics for hand and head controllers. If you aren't currently playing an override
+ * animation, this function has no effect.
Each avatar has an avatar-animation.json file that defines which animations are used and how they are blended together
+ * with procedural data (such as look at vectors, hand sensors etc.). Each animation specified in the avatar-animation.json
+ * file is known as an animation role. Animation roles map to easily understandable actions that the avatar can perform,
+ * such as "idleStand", "idleTalk", or "walkFwd". getAnimationRoles()
+ * is used get the list of animation roles defined in the avatar-animation.json.
Each avatar has an avatar-animation.json file that defines a set of animation roles. Animation roles map to easily
+ * understandable actions that the avatar can perform, such as "idleStand", "idleTalk", or
+ * "walkFwd". To get the full list of roles, use {@ link MyAvatar.getAnimationRoles}.
+ * For each role, the avatar-animation.json defines when the animation is used, the animation clip (.FBX) used, and how
+ * animations are blended together with procedural data (such as look at vectors, hand sensors etc.).
+ * overrideRoleAnimation() is used to change the animation clip (.FBX) associated with a specified animation
+ * role. To end the role animation and restore the default, use {@link MyAvatar.restoreRoleAnimation}.
Note: Hand roles only affect the hand. Other 'main' roles, like 'idleStand', 'idleTalk', 'takeoffStand' are full body.
*Note: When using pre-built animation data, it's critical that the joint orientation of the source animation and target * rig are equivalent, since the animation data applies absolute values onto the joints. If the orientations are different, * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see - * Avatar Standards. + * Avatar Standards. * @function MyAvatar.overrideRoleAnimation * @param role {string} The animation role to override * @param url {string} The URL to the animation file. Animation files need to be .FBX format, but only need to contain the avatar skeleton and animation data. @@ -548,13 +574,15 @@ public: Q_INVOKABLE void overrideRoleAnimation(const QString& role, const QString& url, float fps, bool loop, float firstFrame, float lastFrame); /**jsdoc - * Each avatar has an avatar-animation.json file that defines a set of animation roles. Animation roles map to easily understandable actions that - * the avatar can perform, such as "idleStand", "idleTalk", or "walkFwd". To get the full list of roles, use getAnimationRoles(). For each role, - * the avatar-animation.json defines when the animation is used, the animation clip (.FBX) used, and how animations are blended together with - * procedural data (such as look at vectors, hand sensors etc.). You can change the animation clip (.FBX) associated with a specified animation - * role using overrideRoleAnimation(). - * restoreRoleAnimation() is used to restore a specified animation role's default animation clip. If you have not specified an override animation - * for the specified role, this function will have no effect. + * Restores a default role animation. + *
Each avatar has an avatar-animation.json file that defines a set of animation roles. Animation roles map to easily
+ * understandable actions that the avatar can perform, such as "idleStand", "idleTalk", or
+ * "walkFwd". To get the full list of roles, use {#link MyAvatar.getAnimationRoles}. For each role,
+ * the avatar-animation.json defines when the animation is used, the animation clip (.FBX) used, and how animations are
+ * blended together with procedural data (such as look-at vectors, hand sensors etc.). You can change the animation clip
+ * (.FBX) associated with a specified animation role using {@link MyAvatar.overrideRoleAnimation}.
+ * restoreRoleAnimation() is used to restore a specified animation role's default animation clip. If you have
+ * not specified an override animation for the specified role, this function has no effect.
* @function MyAvatar.restoreRoleAnimation
* @param role {string} The animation role clip to restore.
*/
@@ -599,6 +627,7 @@ public:
* @param {string} hand
*/
Q_INVOKABLE void setDominantHand(const QString& hand);
+
/**jsdoc
* @function MyAvatar.getDominantHand
* @returns {string}
@@ -610,6 +639,7 @@ public:
* @param {string} hand
*/
Q_INVOKABLE void setHmdAvatarAlignmentType(const QString& hand);
+
/**jsdoc
* @function MyAvatar.getHmdAvatarAlignmentType
* @returns {string}
@@ -617,45 +647,61 @@ public:
Q_INVOKABLE QString getHmdAvatarAlignmentType() const;
/**jsdoc
- * @function MyAvatar.setCenterOfGravityModelEnabled
- * @param {boolean} enabled
- */
+ * @function MyAvatar.setCenterOfGravityModelEnabled
+ * @param {boolean} enabled
+ */
Q_INVOKABLE void setCenterOfGravityModelEnabled(bool value) { _centerOfGravityModelEnabled = value; }
+
/**jsdoc
- * @function MyAvatar.getCenterOfGravityModelEnabled
- * @returns {boolean}
- */
+ * @function MyAvatar.getCenterOfGravityModelEnabled
+ * @returns {boolean}
+ */
Q_INVOKABLE bool getCenterOfGravityModelEnabled() const { return _centerOfGravityModelEnabled; }
/**jsdoc
* @function MyAvatar.setHMDLeanRecenterEnabled
* @param {boolean} enabled
*/
Q_INVOKABLE void setHMDLeanRecenterEnabled(bool value) { _hmdLeanRecenterEnabled = value; }
+
/**jsdoc
* @function MyAvatar.getHMDLeanRecenterEnabled
* @returns {boolean}
*/
Q_INVOKABLE bool getHMDLeanRecenterEnabled() const { return _hmdLeanRecenterEnabled; }
+
/**jsdoc
- * Request to enable hand touch effect globally
+ * Requests that the hand touch effect is disabled for your avatar. Any resulting change in the status of the hand touch
+ * effect will be signaled by {@link MyAvatar.shouldDisableHandTouchChanged}.
+ *
The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that + * it is really touching that object.
* @function MyAvatar.requestEnableHandTouch */ Q_INVOKABLE void requestEnableHandTouch(); + /**jsdoc - * Request to disable hand touch effect globally + * Requests that the hand touch effect is enabled for your avatar. Any resulting change in the status of the hand touch + * effect will be signaled by {@link MyAvatar.shouldDisableHandTouchChanged}. + *The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that + * it is really touching that object.
* @function MyAvatar.requestDisableHandTouch */ Q_INVOKABLE void requestDisableHandTouch(); + /**jsdoc - * Disables hand touch effect on a specific entity + * Disables the hand touch effect on a specific entity. + *The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that + * it is really touching that object.
* @function MyAvatar.disableHandTouchForID - * @param {Uuid} entityID - ID of the entity that will disable hand touch effect + * @param {Uuid} entityID - The entity that the hand touch effect will be disabled for. */ Q_INVOKABLE void disableHandTouchForID(const QUuid& entityID); + /**jsdoc - * Enables hand touch effect on a specific entity + * Enables the hand touch effect on a specific entity. + *The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that + * it is really touching that object.
* @function MyAvatar.enableHandTouchForID - * @param {Uuid} entityID - ID of the entity that will enable hand touch effect + * @param {Uuid} entityID - The entity that the hand touch effect will be enabled for. */ Q_INVOKABLE void enableHandTouchForID(const QUuid& entityID); @@ -712,6 +758,7 @@ public: * @param {DriveKeys} key */ Q_INVOKABLE void enableDriveKey(DriveKeys key); + /**jsdoc * @function MyAvatar.isDriveKeyDisabled * @param {DriveKeys} key @@ -741,10 +788,10 @@ public: Q_INVOKABLE void triggerRotationRecenter(); /**jsdoc - *The isRecenteringHorizontally function returns true if MyAvatar - *is translating the root of the Avatar to keep the center of gravity under the head. - *isActive(Horizontal) is returned. - *@function MyAvatar.isRecenteringHorizontally + * Gets whether or not the avatar is configured to keep its center of gravity under its head. + * @function MyAvatar.isRecenteringHorizontally + * @returns {boolean}true if the avatar is keeping its center of gravity under its head position,
+ * false if not.
*/
Q_INVOKABLE bool isRecenteringHorizontally() const;
@@ -753,7 +800,7 @@ public:
const MyHead* getMyHead() const;
/**jsdoc
- * Get the current position of the avatar's "Head" joint.
+ * Gets the current position of the avatar's "Head" joint.
* @function MyAvatar.getHeadPosition
* @returns {Vec3} The current position of the avatar's "Head" joint.
* @example Note: The Leap Motion isn't part of the hand controller input system. (Instead, it manipulates the avatar's joints * for hand animation.)
* @function MyAvatar.getLeftHandPosition @@ -823,7 +871,7 @@ public: Q_INVOKABLE glm::vec3 getLeftHandPosition() const; /**jsdoc - * Get the position of the avatar's right hand as positioned by a hand controller (e.g., Oculus Touch or Vive).Note: The Leap Motion isn't part of the hand controller input system. (Instead, it manipulates the avatar's joints * for hand animation.)
* @function MyAvatar.getRightHandPosition @@ -848,7 +896,7 @@ public: /**jsdoc - * Get the pose (position, rotation, velocity, and angular velocity) of the avatar's left hand as positioned by a + * Gets the pose (position, rotation, velocity, and angular velocity) of the avatar's left hand as positioned by a * hand controller (e.g., Oculus Touch or Vive).Note: The Leap Motion isn't part of the hand controller input system. (Instead, it manipulates the avatar's joints
* for hand animation.) If you are using the Leap Motion, the return value's valid property will be
@@ -861,7 +909,7 @@ public:
Q_INVOKABLE controller::Pose getLeftHandPose() const;
/**jsdoc
- * Get the pose (position, rotation, velocity, and angular velocity) of the avatar's left hand as positioned by a
+ * Gets the pose (position, rotation, velocity, and angular velocity) of the avatar's left hand as positioned by a
* hand controller (e.g., Oculus Touch or Vive).
*
Note: The Leap Motion isn't part of the hand controller input system. (Instead, it manipulates the avatar's joints
* for hand animation.) If you are using the Leap Motion, the return value's valid property will be
@@ -935,7 +983,7 @@ public:
Q_INVOKABLE void useFullAvatarURL(const QUrl& fullAvatarURL, const QString& modelName = QString());
/**jsdoc
- * Get the complete URL for the current avatar.
+ * Gets the complete URL for the current avatar.
* @function MyAvatar.getFullAvatarURLFromPreferences
* @returns {string} The full avatar model name.
* @example
true if your avatar is flying and not taking off or falling, otherwise
- * false.
+ * @returns {boolean} true if your avatar is flying and not taking off or falling, false if not.
*/
Q_INVOKABLE bool isFlying();
/**jsdoc
- * Check whether your avatar is in the air or not.
+ * Checks whether your avatar is in the air or not.
* @function MyAvatar.isInAir
* @returns {boolean} true if your avatar is taking off, flying, or falling, otherwise false
* because your avatar is on the ground.
@@ -1040,7 +1088,7 @@ public:
Q_INVOKABLE bool isInAir();
/**jsdoc
- * Set your preference for flying in your current desktop or HMD display mode. Note that your ability to fly also depends
+ * Sets your preference for flying in your current desktop or HMD display mode. Note that your ability to fly also depends
* on whether the domain you're in allows you to fly.
* @function MyAvatar.setFlyingEnabled
* @param {boolean} enabled - Set true if you want to enable flying in your current desktop or HMD display
@@ -1049,7 +1097,7 @@ public:
Q_INVOKABLE void setFlyingEnabled(bool enabled);
/**jsdoc
- * Get your preference for flying in your current desktop or HMD display mode. Note that your ability to fly also depends
+ * Gets your preference for flying in your current desktop or HMD display mode. Note that your ability to fly also depends
* on whether the domain you're in allows you to fly.
* @function MyAvatar.getFlyingEnabled
* @returns {boolean} true if your preference is to enable flying in your current desktop or HMD display mode,
@@ -1058,7 +1106,7 @@ public:
Q_INVOKABLE bool getFlyingEnabled();
/**jsdoc
- * Set your preference for flying in desktop display mode. Note that your ability to fly also depends on whether the domain
+ * Sets your preference for flying in desktop display mode. Note that your ability to fly also depends on whether the domain
* you're in allows you to fly.
* @function MyAvatar.setFlyingDesktopPref
* @param {boolean} enabled - Set true if you want to enable flying in desktop display mode, otherwise set
@@ -1067,7 +1115,7 @@ public:
Q_INVOKABLE void setFlyingDesktopPref(bool enabled);
/**jsdoc
- * Get your preference for flying in desktop display mode. Note that your ability to fly also depends on whether the domain
+ * Gets your preference for flying in desktop display mode. Note that your ability to fly also depends on whether the domain
* you're in allows you to fly.
* @function MyAvatar.getFlyingDesktopPref
* @returns {boolean} true if your preference is to enable flying in desktop display mode, otherwise
@@ -1076,7 +1124,7 @@ public:
Q_INVOKABLE bool getFlyingDesktopPref();
/**jsdoc
- * Set your preference for flying in HMD display mode. Note that your ability to fly also depends on whether the domain
+ * Sets your preference for flying in HMD display mode. Note that your ability to fly also depends on whether the domain
* you're in allows you to fly.
* @function MyAvatar.setFlyingHMDPref
* @param {boolean} enabled - Set true if you want to enable flying in HMD display mode, otherwise set
@@ -1085,7 +1133,7 @@ public:
Q_INVOKABLE void setFlyingHMDPref(bool enabled);
/**jsdoc
- * Get your preference for flying in HMD display mode. Note that your ability to fly also depends on whether the domain
+ * Gets your preference for flying in HMD display mode. Note that your ability to fly also depends on whether the domain
* you're in allows you to fly.
* @function MyAvatar.getFlyingHMDPref
* @returns {boolean} true if your preference is to enable flying in HMD display mode, otherwise
@@ -1120,38 +1168,53 @@ public:
Q_INVOKABLE bool getCollisionsEnabled();
/**jsdoc
- * @function MyAvatar.setOtherAvatarsCollisionsEnabled
- * @param {boolean} enabled
- */
+ * @function MyAvatar.setOtherAvatarsCollisionsEnabled
+ * @param {boolean} enabled
+ */
Q_INVOKABLE void setOtherAvatarsCollisionsEnabled(bool enabled);
/**jsdoc
- * @function MyAvatar.getOtherAvatarsCollisionsEnabled
- * @returns {boolean}
- */
+ * @function MyAvatar.getOtherAvatarsCollisionsEnabled
+ * @returns {boolean}
+ */
Q_INVOKABLE bool getOtherAvatarsCollisionsEnabled();
/**jsdoc
- * @function MyAvatar.getCollisionCapsule
- * @returns {object}
- */
+ * @function MyAvatar.getCollisionCapsule
+ * @returns {object}
+ */
Q_INVOKABLE QVariantMap getCollisionCapsule() const;
/**jsdoc
* @function MyAvatar.setCharacterControllerEnabled
* @param {boolean} enabled
- * @deprecated
+ * @deprecated Use {@link MyAvatar.setCollisionsEnabled} instead.
*/
Q_INVOKABLE void setCharacterControllerEnabled(bool enabled); // deprecated
/**jsdoc
* @function MyAvatar.getCharacterControllerEnabled
* @returns {boolean}
- * @deprecated
+ * @deprecated Use {@link MyAvatar.getCollisionsEnabled} instead.
*/
Q_INVOKABLE bool getCharacterControllerEnabled(); // deprecated
+ /**jsdoc
+ * @comment Different behavior to the Avatar version of this method.
+ * Gets the rotation of a joint relative to the avatar.
+ * @function MyAvatar.getAbsoluteJointRotationInObjectFrame
+ * @param {number} index - The index of the joint.
+ * @returns {Quat} The rotation of the joint relative to the avatar.
+ */
virtual glm::quat getAbsoluteJointRotationInObjectFrame(int index) const override;
+
+ /**jsdoc
+ * @comment Different behavior to the Avatar version of this method.
+ * Gets the translation of a joint relative to the avatar.
+ * @function MyAvatar.getAbsoluteJointTranslationInObjectFrame
+ * @param {number} index - The index of the joint.
+ * @returns {Vec3} The translation of the joint relative to the avatar.
+ */
virtual glm::vec3 getAbsoluteJointTranslationInObjectFrame(int index) const override;
// all calibration matrices are in absolute sensor space.
@@ -1241,34 +1304,56 @@ public:
void prepareAvatarEntityDataForReload();
/**jsdoc
- * Create a new grab.
+ * Creates a new grab, that grabs an entity.
* @function MyAvatar.grab
- * @param {Uuid} targetID - id of grabbed thing
- * @param {number} parentJointIndex - avatar joint being used to grab
- * @param {Vec3} offset - target's positional offset from joint
- * @param {Quat} rotationalOffset - target's rotational offset from joint
- * @returns {Uuid} id of the new grab
+ * @param {Uuid} targetID - The ID of the entity to grab.
+ * @param {number} parentJointIndex - The avatar joint to use to grab the entity.
+ * @param {Vec3} offset - The target's local positional relative to the joint.
+ * @param {Quat} rotationalOffset - The target's local rotation relative to the joint.
+ * @returns {Uuid} The ID of the new grab.
*/
Q_INVOKABLE const QUuid grab(const QUuid& targetID, int parentJointIndex,
glm::vec3 positionalOffset, glm::quat rotationalOffset);
/**jsdoc
- * Release (delete) a grab.
+ * Releases (deletes) a grab, to stop grabbing an entity.
* @function MyAvatar.releaseGrab
- * @param {Uuid} grabID - id of grabbed thing
+ * @param {Uuid} grabID - The ID of the grab to release.
*/
Q_INVOKABLE void releaseGrab(const QUuid& grabID);
+ /**jsdoc
+ * Gets the avatar entities as binary data.
+ * @function MyAvatar.getAvatarEntityData
+ * @override
+ * @returns {AvatarEntityMap}
+ */
AvatarEntityMap getAvatarEntityData() const override;
+
+ /**jsdoc
+ * Sets the avatar entities from binary data.
+ * @function MyAvatar.setAvatarEntityData
+ * @param {AvatarEntityMap} avatarEntityData
+ */
void setAvatarEntityData(const AvatarEntityMap& avatarEntityData) override;
+
+ /**jsdoc
+ * @comment Uses the base class's JSDoc.
+ */
void updateAvatarEntity(const QUuid& entityID, const QByteArray& entityData) override;
+
void avatarEntityDataToJson(QJsonObject& root) const override;
+
+ /**jsdoc
+ * @function MyAvatar.sendAvatarDataPacket
+ * @param {boolean} sendAll
+ */
int sendAvatarDataPacket(bool sendAll = false) override;
public slots:
/**jsdoc
- * Increase the avatar's scale by five percent, up to a minimum scale of 1000.
+ * Increases the avatar's scale by five percent, up to a minimum scale of 1000.
* @function MyAvatar.increaseSize
* @example 0.25.
+ * Decreases the avatar's scale by five percent, down to a minimum scale of 0.25.
* @function MyAvatar.decreaseSize
* @example 1.0.
+ * Resets the avatar's scale back to the default scale of 1.0.
* @function MyAvatar.resetSize
*/
void resetSize();
@@ -1317,7 +1402,7 @@ public slots:
float getGravity();
/**jsdoc
- * Move the avatar to a new position and/or orientation in the domain, while taking into account Avatar leg-length.
+ * Moves the avatar to a new position and/or orientation in the domain, while taking into account Avatar leg-length.
* @function MyAvatar.goToFeetLocation
* @param {Vec3} position - The new position for the avatar, in world coordinates.
* @param {boolean} [hasOrientation=false] - Set to true to set the orientation of the avatar.
@@ -1330,7 +1415,7 @@ public slots:
bool shouldFaceLocation);
/**jsdoc
- * Move the avatar to a new position and/or orientation in the domain.
+ * Moves the avatar to a new position and/or orientation in the domain.
* @function MyAvatar.goToLocation
* @param {Vec3} position - The new position for the avatar, in world coordinates.
* @param {boolean} [hasOrientation=false] - Set to true to set the orientation of the avatar.
@@ -1395,61 +1480,70 @@ public slots:
/**jsdoc
- * ####### Why Q_INVOKABLE?
* @function MyAvatar.updateMotionBehaviorFromMenu
*/
Q_INVOKABLE void updateMotionBehaviorFromMenu();
/**jsdoc
- * @function MyAvatar.setToggleHips
- * @param {boolean} enabled
- */
+ * @function MyAvatar.setToggleHips
+ * @param {boolean} enabled
+ */
void setToggleHips(bool followHead);
+
/**jsdoc
- * @function MyAvatar.setEnableDebugDrawBaseOfSupport
- * @param {boolean} enabled
- */
+ * @function MyAvatar.setEnableDebugDrawBaseOfSupport
+ * @param {boolean} enabled
+ */
void setEnableDebugDrawBaseOfSupport(bool isEnabled);
+
/**jsdoc
* @function MyAvatar.setEnableDebugDrawDefaultPose
* @param {boolean} enabled
*/
void setEnableDebugDrawDefaultPose(bool isEnabled);
+
/**jsdoc
* @function MyAvatar.setEnableDebugDrawAnimPose
* @param {boolean} enabled
*/
void setEnableDebugDrawAnimPose(bool isEnabled);
+
/**jsdoc
* @function MyAvatar.setEnableDebugDrawPosition
* @param {boolean} enabled
*/
void setEnableDebugDrawPosition(bool isEnabled);
+
/**jsdoc
* @function MyAvatar.setEnableDebugDrawHandControllers
* @param {boolean} enabled
*/
void setEnableDebugDrawHandControllers(bool isEnabled);
+
/**jsdoc
* @function MyAvatar.setEnableDebugDrawSensorToWorldMatrix
* @param {boolean} enabled
*/
void setEnableDebugDrawSensorToWorldMatrix(bool isEnabled);
+
/**jsdoc
* @function MyAvatar.setEnableDebugDrawIKTargets
* @param {boolean} enabled
*/
void setEnableDebugDrawIKTargets(bool isEnabled);
+
/**jsdoc
* @function MyAvatar.setEnableDebugDrawIKConstraints
* @param {boolean} enabled
*/
void setEnableDebugDrawIKConstraints(bool isEnabled);
+
/**jsdoc
* @function MyAvatar.setEnableDebugDrawIKChains
* @param {boolean} enabled
*/
void setEnableDebugDrawIKChains(bool isEnabled);
+
/**jsdoc
* @function MyAvatar.setEnableDebugDrawDetailedCollision
* @param {boolean} enabled
@@ -1457,23 +1551,20 @@ public slots:
void setEnableDebugDrawDetailedCollision(bool isEnabled);
/**jsdoc
- * Get whether or not your avatar mesh is visible.
+ * Gets whether or not your avatar mesh is visible.
* @function MyAvatar.getEnableMeshVisible
* @returns {boolean} true if your avatar's mesh is visible, otherwise false.
*/
bool getEnableMeshVisible() const override;
/**jsdoc
- * ####### TODO; Should this really be exposed in the API?
* @function MyAvatar.storeAvatarEntityDataPayload
+ * @deprecated This function is deprecated and will be removed.
*/
void storeAvatarEntityDataPayload(const QUuid& entityID, const QByteArray& payload) override;
/**jsdoc
- * ####### Does override change functionality? If so, document here and don't borrow; if not, borrow and don't document here.
- * @function MyAvatar.clearAvatarEntity
- * @param {Uuid} entityID
- * @param {boolean} [requiresRemovalFromTree]
+ * @comment Uses the base class's JSDoc.
*/
void clearAvatarEntity(const QUuid& entityID, bool requiresRemovalFromTree = true) override;
@@ -1483,7 +1574,7 @@ public slots:
void sanitizeAvatarEntityProperties(EntityItemProperties& properties) const;
/**jsdoc
- * Set whether or not your avatar mesh is visible.
+ * Sets whether or not your avatar mesh is visible.
* @function MyAvatar.setEnableMeshVisible
* @param {boolean} visible - true to set your avatar mesh visible; false to set it invisible.
* @example true if collisions with the environment are enabled, false if
+ * they're not.
* @returns {Signal}
*/
void collisionsEnabledChanged(bool enabled);
/**jsdoc
- * Triggered when collisions with other avatars enabled or disabled
+ * Triggered when collisions with other avatars are enabled or disabled.
* @function MyAvatar.otherAvatarsCollisionsEnabledChanged
- * @param {boolean} enabled
+ * @param {boolean} enabled - true if collisions with other avatars are enabled, false if they're
+ * not.
* @returns {Signal}
*/
void otherAvatarsCollisionsEnabledChanged(bool enabled);
/**jsdoc
- * Triggered when avatar's animation url changes
+ * Triggered when the avatar's animation changes.
* @function MyAvatar.animGraphUrlChanged
- * @param {url} url
+ * @param {url} url - The URL of the new animation.
* @returns {Signal}
*/
void animGraphUrlChanged(const QUrl& url);
@@ -1672,18 +1765,24 @@ signals:
void scaleChanged();
/**jsdoc
- * Triggered when hand touch is globally enabled or disabled
+ * Triggered when the hand touch effect is enabled or disabled for the avatar.
+ * The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that + * it is really touching that object.
* @function MyAvatar.shouldDisableHandTouchChanged - * @param {boolean} shouldDisable + * @param {boolean} disabled -true if the hand touch effect is disabled for the avatar,
+ * false if it isn't disabled.
* @returns {Signal}
*/
void shouldDisableHandTouchChanged(bool shouldDisable);
/**jsdoc
- * Triggered when hand touch is enabled or disabled for an specific entity
+ * Triggered when the hand touch is enabled or disabled on a specific entity.
+ * The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that + * it is really touching that object.
* @function MyAvatar.disableHandTouchForIDChanged - * @param {Uuid} entityID - ID of the entity that will enable hand touch effect - * @param {boolean} disable + * @param {Uuid} entityID - The entity that the hand touch effect has been enabled or disabled for. + * @param {boolean} disabled -true if the hand touch effect is disabled for the entity,
+ * false if it isn't disabled.
* @returns {Signal}
*/
void disableHandTouchForIDChanged(const QUuid& entityID, bool disable);
diff --git a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h
index 98aa255641..11940ad76a 100644
--- a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h
+++ b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h
@@ -215,17 +215,17 @@ public:
Q_INVOKABLE virtual glm::vec3 getDefaultJointTranslation(int index) const;
/**jsdoc
- * Provides read only access to the default joint rotations in avatar coordinates.
+ * Provides read-only access to the default joint rotations in avatar coordinates.
* The default pose of the avatar is defined by the position and orientation of all bones
* in the avatar's model file. Typically this is a T-pose.
* @function MyAvatar.getAbsoluteDefaultJointRotationInObjectFrame
- * @param index {number} -The joint index.
+ * @param index {number} - The joint index.
* @returns {Quat} The rotation of this joint in avatar coordinates.
*/
Q_INVOKABLE virtual glm::quat getAbsoluteDefaultJointRotationInObjectFrame(int index) const;
/**jsdoc
- * Provides read only access to the default joint translations in avatar coordinates.
+ * Provides read-only access to the default joint translations in avatar coordinates.
* The default pose of the avatar is defined by the position and orientation of all bones
* in the avatar's model file. Typically this is a T-pose.
* @function MyAvatar.getAbsoluteDefaultJointTranslationInObjectFrame
@@ -261,52 +261,51 @@ public:
// world-space to avatar-space rigconversion functions
/**jsdoc
- * @function MyAvatar.worldToJointPoint
- * @param {Vec3} position
- * @param {number} [jointIndex=-1]
- * @returns {Vec3}
- */
+ * @function MyAvatar.worldToJointPoint
+ * @param {Vec3} position
+ * @param {number} [jointIndex=-1]
+ * @returns {Vec3}
+ */
Q_INVOKABLE glm::vec3 worldToJointPoint(const glm::vec3& position, const int jointIndex = -1) const;
/**jsdoc
- * @function MyAvatar.worldToJointDirection
- * @param {Vec3} direction
- * @param {number} [jointIndex=-1]
- * @returns {Vec3}
- */
+ * @function MyAvatar.worldToJointDirection
+ * @param {Vec3} direction
+ * @param {number} [jointIndex=-1]
+ * @returns {Vec3}
+ */
Q_INVOKABLE glm::vec3 worldToJointDirection(const glm::vec3& direction, const int jointIndex = -1) const;
/**jsdoc
- * @function MyAvatar.worldToJointRotation
- * @param {Quat} rotation
- * @param {number} [jointIndex=-1]
- * @returns {Quat}
+ * @function MyAvatar.worldToJointRotation
+ * @param {Quat} rotation
+ * @param {number} [jointIndex=-1]
+ * @returns {Quat}
*/
Q_INVOKABLE glm::quat worldToJointRotation(const glm::quat& rotation, const int jointIndex = -1) const;
-
/**jsdoc
- * @function MyAvatar.jointToWorldPoint
- * @param {vec3} position
- * @param {number} [jointIndex=-1]
- * @returns {Vec3}
- */
+ * @function MyAvatar.jointToWorldPoint
+ * @param {vec3} position
+ * @param {number} [jointIndex=-1]
+ * @returns {Vec3}
+ */
Q_INVOKABLE glm::vec3 jointToWorldPoint(const glm::vec3& position, const int jointIndex = -1) const;
/**jsdoc
- * @function MyAvatar.jointToWorldDirection
- * @param {Vec3} direction
- * @param {number} [jointIndex=-1]
- * @returns {Vec3}
- */
+ * @function MyAvatar.jointToWorldDirection
+ * @param {Vec3} direction
+ * @param {number} [jointIndex=-1]
+ * @returns {Vec3}
+ */
Q_INVOKABLE glm::vec3 jointToWorldDirection(const glm::vec3& direction, const int jointIndex = -1) const;
/**jsdoc
- * @function MyAvatar.jointToWorldRotation
- * @param {Quat} rotation
- * @param {number} [jointIndex=-1]
- * @returns {Quat}
- */
+ * @function MyAvatar.jointToWorldRotation
+ * @param {Quat} rotation
+ * @param {number} [jointIndex=-1]
+ * @returns {Quat}
+ */
Q_INVOKABLE glm::quat jointToWorldRotation(const glm::quat& rotation, const int jointIndex = -1) const;
virtual void setSkeletonModelURL(const QUrl& skeletonModelURL) override;
@@ -321,7 +320,7 @@ public:
float radius1, float radius2, const glm::vec4& color);
/**jsdoc
- * Set the offset applied to the current avatar. The offset adjusts the position that the avatar is rendered. For example,
+ * Sets the offset applied to the current avatar. The offset adjusts the position that the avatar is rendered. For example,
* with an offset of { x: 0, y: 0.1, z: 0 }, your avatar will appear to be raised off the ground slightly.
* @function MyAvatar.setSkeletonOffset
* @param {Vec3} offset - The skeleton offset to set.
@@ -337,7 +336,7 @@ public:
Q_INVOKABLE void setSkeletonOffset(const glm::vec3& offset);
/**jsdoc
- * Get the offset applied to the current avatar. The offset adjusts the position that the avatar is rendered. For example,
+ * Gets the offset applied to the current avatar. The offset adjusts the position that the avatar is rendered. For example,
* with an offset of { x: 0, y: 0.1, z: 0 }, your avatar will appear to be raised off the ground slightly.
* @function MyAvatar.getSkeletonOffset
* @returns {Vec3} The current skeleton offset.
@@ -349,7 +348,7 @@ public:
virtual glm::vec3 getSkeletonPosition() const;
/**jsdoc
- * Get the position of a joint in the current avatar.
+ * Gets the position of a joint in the current avatar.
* @function MyAvatar.getJointPosition
* @param {number} index - The index of the joint.
* @returns {Vec3} The position of the joint in world coordinates.
@@ -357,7 +356,7 @@ public:
Q_INVOKABLE glm::vec3 getJointPosition(int index) const;
/**jsdoc
- * Get the position of a joint in the current avatar.
+ * Gets the position of a joint in the current avatar.
* @function MyAvatar.getJointPosition
* @param {string} name - The name of the joint.
* @returns {Vec3} The position of the joint in world coordinates.
@@ -367,7 +366,7 @@ public:
Q_INVOKABLE glm::vec3 getJointPosition(const QString& name) const;
/**jsdoc
- * Get the position of the current avatar's neck in world coordinates.
+ * Gets the position of the current avatar's neck in world coordinates.
* @function MyAvatar.getNeckPosition
* @returns {Vec3} The position of the neck in world coordinates.
* @example