diff --git a/assignment-client/src/AgentScriptingInterface.h b/assignment-client/src/AgentScriptingInterface.h index 1242634dd5..b1a8aaff96 100644 --- a/assignment-client/src/AgentScriptingInterface.h +++ b/assignment-client/src/AgentScriptingInterface.h @@ -18,8 +18,8 @@ #include "Agent.h" /**jsdoc - * The Agent API enables an assignment client to emulate an avatar. In particular, setting isAvatar = - * true connects the assignment client to the avatar and audio mixers and enables the {@link Avatar} API to be used. + * The Agent API enables an assignment client to emulate an avatar. Setting isAvatar = true connects + * the assignment client to the avatar and audio mixers, and enables the {@link Avatar} API to be used. * * @namespace Agent * @@ -29,13 +29,13 @@ * false. * @property {boolean} isPlayingAvatarSound - true if the script has a sound to play, otherwise false. * Sounds are played when isAvatar is true, from the position and with the orientation of the - * scripted avatar's head.Read-only. + * scripted avatar's head. Read-only. * @property {boolean} isListeningToAudioStream - true if the agent is "listening" to the audio stream from the * domain, otherwise false. * @property {boolean} isNoiseGateEnabled - true if the noise gate is enabled, otherwise false. When * enabled, the input audio stream is blocked (fully attenuated) if it falls below an adaptive threshold. - * @property {number} lastReceivedAudioLoudness - The current loudness of the audio input, nominal range 0.0 (no - * sound) – 1.0 (the onset of clipping). Read-only. + * @property {number} lastReceivedAudioLoudness - The current loudness of the audio input. Nominal range [0.0 (no + * sound) – 1.0 (the onset of clipping)]. Read-only. * @property {Uuid} sessionUUID - The unique ID associated with the agent's current session in the domain. Read-only. */ class AgentScriptingInterface : public QObject { @@ -63,9 +63,9 @@ public: public slots: /**jsdoc - * Sets whether or not the script should emulate an avatar. + * Sets whether the script should emulate an avatar. * @function Agent.setIsAvatar - * @param {boolean} isAvatar - true if the script should act as if an avatar, otherwise false. + * @param {boolean} isAvatar - true if the script emulates an avatar, otherwise false. * @example Make an assignment client script emulate an avatar. * (function () { * Agent.setIsAvatar(true); @@ -76,9 +76,14 @@ public slots: void setIsAvatar(bool isAvatar) const { _agent->setIsAvatar(isAvatar); } /**jsdoc - * Checks whether or not the script is emulating an avatar. + * Checks whether the script is emulating an avatar. * @function Agent.isAvatar - * @returns {boolean} true if the script is acting as if an avatar, otherwise false. + * @returns {boolean} true if the script is emulating an avatar, otherwise false. + * @example Check whether the agent is emulating an avatar. + * (function () { + * print("Agent is avatar: " + Agent.isAvatar()); + * print("Agent is avatar: " + Agent.isAvatar); // Same result. + * }()); */ bool isAvatar() const { return _agent->isAvatar(); } @@ -86,7 +91,15 @@ public slots: * Plays a sound from the position and with the orientation of the emulated avatar's head. No sound is played unless * isAvatar == true. * @function Agent.playAvatarSound - * @param {SoundObject} avatarSound - The sound to play. + * @param {SoundObject} avatarSound - The sound played. + * @example Play a sound from an emulated avatar. + * (function () { + * Agent.isAvatar = true; + * var sound = SoundCache.getSound(Script.resourcesPath() + "sounds/sample.wav"); + * Script.setTimeout(function () { // Give the sound time to load. + * Agent.playAvatarSound(sound); + * }, 1000); + * }()); */ void playAvatarSound(SharedSoundPointer avatarSound) const { _agent->playAvatarSound(avatarSound); } diff --git a/assignment-client/src/avatars/ScriptableAvatar.h b/assignment-client/src/avatars/ScriptableAvatar.h index 37e82947ae..fbe5675bd8 100644 --- a/assignment-client/src/avatars/ScriptableAvatar.h +++ b/assignment-client/src/avatars/ScriptableAvatar.h @@ -20,7 +20,7 @@ /**jsdoc * The Avatar API is used to manipulate scriptable avatars on the domain. This API is a subset of the - * {@link MyAvatar} API. To enable this API, set {@link Agent|Agent.isAvatatr} to true. + * {@link MyAvatar} API. To enable this API, set {@link Agent|Agent.isAvatar} to true. * *

For Interface, client entity, and avatar scripts, see {@link MyAvatar}.

* @@ -30,13 +30,13 @@ * * @comment IMPORTANT: This group of properties is copied from AvatarData.h; they should NOT be edited here. * @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 between 0.005 - * and 1000.0. When getting, the value may temporarily be further limited by the domain's settings. + * @property {number} scale=1.0 - 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. * @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. + * @property {number} bodyYaw - The left or right rotation 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". @@ -57,13 +57,12 @@ * @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.
+ * @property {string} sessionDisplayName - 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. + * @property {boolean} lookAtSnappingEnabled=true - 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. + * @property {string} skeletonModelURL - The avatar's FST file. + * @property {AttachmentData[]} attachmentData - Information on the avatar's attachments.
* Deprecated: Use avatar entities instead. * @property {string[]} jointNames - The list of joints in the current avatar model. Read-only. * @property {Uuid} sessionUUID - Unique ID of the avatar in the domain. Read-only. @@ -75,6 +74,12 @@ * avatar. Read-only. * @property {number} sensorToWorldScale - The scale that transforms dimensions in the user's real world to the avatar's * size in the virtual world. Read-only. + * + * @example Create a scriptable avatar. + * (function () { + * Agent.setIsAvatar(true); + * print("Position: " + JSON.stringify(Avatar.position)); // 0, 0, 0 + * }()); */ class ScriptableAvatar : public AvatarData, public Dependency { @@ -90,14 +95,14 @@ public: /**jsdoc * Starts playing an animation on the avatar. * @function Avatar.startAnimation - * @param {string} url - The URL to the animation file. Animation files need to be .FBX format but only need to contain + * @param {string} url - 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. * @param {number} [fps=30] - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. * @param {number} [priority=1] - Not used. * @param {boolean} [loop=false] - true if the animation should loop, false if it shouldn't. * @param {boolean} [hold=false] - Not used. - * @param {number} [firstFrame=0] - The frame the animation should start at. - * @param {number} [lastFrame=3.403e+38] - The frame the animation should stop at. + * @param {number} [firstFrame=0] - The frame at which the animation starts. + * @param {number} [lastFrame=3.403e+38] - The frame at which the animation stops. * @param {string[]} [maskedJoints=[]] - The names of joints that should not be animated. */ /// Allows scripts to run animations. @@ -115,6 +120,9 @@ public: * Gets the details of the current avatar animation that is being or was recently played. * @function Avatar.getAnimationDetails * @returns {Avatar.AnimationDetails} The current or recent avatar animation. + * @example Report the current animation details. + * var animationDetails = Avatar.getAnimationDetails(); + * print("Animation details: " + JSON.stringify(animationDetails)); */ Q_INVOKABLE AnimationDetails getAnimationDetails(); @@ -146,18 +154,21 @@ public: bool getHasAudioEnabledFaceMovement() const override { return _headData->getHasAudioEnabledFaceMovement(); } /**jsdoc - * Gets the avatar entities as binary data. - *

Warning: Potentially a very expensive call. Do not use if possible.

+ * Gets details of all avatar entities. + *

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

* @function Avatar.getAvatarEntityData - * @returns {AvatarEntityMap} The avatar entities as binary data. + * @returns {AvatarEntityMap} Details of the avatar entities. + * @example Report the current avatar entities. + * var avatarEntityData = Avatar.getAvatarEntityData(); + * print("Avatar entities: " + JSON.stringify(avatarEntityData)); */ Q_INVOKABLE AvatarEntityMap getAvatarEntityData() const override; /**jsdoc - * Sets the avatar entities from binary data. + * Sets all avatar entities from an object. *

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

* @function Avatar.setAvatarEntityData - * @param {AvatarEntityMap} avatarEntityData - The avatar entities as binary data. + * @param {AvatarEntityMap} avatarEntityData - Details of the avatar entities. */ Q_INVOKABLE void setAvatarEntityData(const AvatarEntityMap& avatarEntityData) override; diff --git a/interface/src/avatar/MyAvatar.cpp b/interface/src/avatar/MyAvatar.cpp index e0e9b5b648..12c260ccde 100644 --- a/interface/src/avatar/MyAvatar.cpp +++ b/interface/src/avatar/MyAvatar.cpp @@ -3542,8 +3542,8 @@ void MyAvatar::clearScaleRestriction() { /**jsdoc * A teleport target. * @typedef {object} MyAvatar.GoToProperties - * @property {Vec3} position - The new position for the avatar, in world coordinates. - * @property {Quat} [orientation] - The new orientation for the avatar. + * @property {Vec3} position - The avatar's new position. + * @property {Quat} [orientation] - The avatar's new orientation. */ void MyAvatar::goToLocation(const QVariant& propertiesVar) { qCDebug(interfaceapp, "MyAvatar QML goToLocation"); @@ -3902,8 +3902,7 @@ void MyAvatar::setCollisionWithOtherAvatarsFlags() { } /**jsdoc - * A collision capsule is a cylinder with hemispherical ends. It is used, in particular, to approximate the extents of an - * avatar. + * A collision capsule is a cylinder with hemispherical ends. It is often used to approximate the extents of an avatar. * @typedef {object} MyAvatar.CollisionCapsule * @property {Vec3} start - The bottom end of the cylinder, excluding the bottom hemisphere. * @property {Vec3} end - The top end of the cylinder, excluding the top hemisphere. @@ -5361,12 +5360,12 @@ void MyAvatar::addAvatarHandsToFlow(const std::shared_ptr& otherAvatar) /**jsdoc * Physics options to use in the flow simulation of a joint. * @typedef {object} MyAvatar.FlowPhysicsOptions - * @property {boolean} [active=true] - true to enable flow on the joint, false if it isn't., - * @property {number} [radius=0.01] - The thickness of segments and knots. (Needed for collisions.) + * @property {boolean} [active=true] - true to enable flow on the joint, otherwise false. + * @property {number} [radius=0.01] - The thickness of segments and knots (needed for collisions). * @property {number} [gravity=-0.0096] - Y-value of the gravity vector. * @property {number} [inertia=0.8] - Rotational inertia multiplier. * @property {number} [damping=0.85] - The amount of damping on joint oscillation. - * @property {number} [stiffness=0.0] - How stiff each thread is. + * @property {number} [stiffness=0.0] - The stiffness of each thread. * @property {number} [delta=0.55] - Delta time for every integration step. */ /**jsdoc @@ -5454,18 +5453,18 @@ void MyAvatar::useFlow(bool isActive, bool isCollidable, const QVariantMap& phys * that has been configured. * @property {Object} collisions - The collisions configuration for each joint that * has collisions configured. - * @property {Object} threads - The threads hat have been configured, with the name of the first joint as - * the ThreadName and an array of the indexes of all the joints in the thread as the value. + * @property {Object} threads - The threads that have been configured, with the first joint's name as the + * ThreadName and value as an array of the indexes of all the joints in the thread. */ /**jsdoc * A set of physics options currently used in flow simulation. * @typedef {object} MyAvatar.FlowPhysicsData - * @property {boolean} active - true to enable flow on the joint, false if it isn't., + * @property {boolean} active - true to enable flow on the joint, otherwise false. * @property {number} radius - The thickness of segments and knots. (Needed for collisions.) * @property {number} gravity - Y-value of the gravity vector. * @property {number} inertia - Rotational inertia multiplier. * @property {number} damping - The amount of damping on joint oscillation. - * @property {number} stiffness - How stiff each thread is. + * @property {number} stiffness - The stiffness of each thread. * @property {number} delta - Delta time for every integration step. * @property {number[]} jointIndices - The indexes of the joints the options are applied to. */ diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index 8951bc7fed..3159348871 100755 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -72,13 +72,13 @@ class MyAvatar : public Avatar { * * @comment IMPORTANT: This group of properties is copied from AvatarData.h; they should NOT be edited here. * @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 between 0.005 - * and 1000.0. When getting, the value may temporarily be further limited by the domain's settings. + * @property {number} scale=1.0 - 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. * @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. + * @property {number} bodyYaw - The left or right rotation 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". @@ -99,13 +99,12 @@ class MyAvatar : public Avatar { * @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.
+ * @property {string} sessionDisplayName - 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. + * @property {boolean} lookAtSnappingEnabled=true - 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. + * @property {string} skeletonModelURL - The avatar's FST file. + * @property {AttachmentData[]} attachmentData - Information on the avatar's attachments.
* Deprecated: Use avatar entities instead. * @property {string[]} jointNames - The list of joints in the current avatar model. Read-only. * @property {Uuid} sessionUUID - Unique ID of the avatar in the domain. Read-only. @@ -149,12 +148,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} hasScriptedBlendshapes=false - true to transmit blendshapes over the network.
* Note: Currently doesn't work. Use {@link MyAvatar.setForceFaceTrackerConnected} instead. - * @property {boolean} hasProceduralBlinkFaceMovement=true - If 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 {boolean} hasProceduralBlinkFaceMovement=true - true if procedural blinking is turned on. + * @property {boolean} hasProceduralEyeFaceMovement=true - true if procedural eye movement is turned on. + * @property {boolean} hasAudioEnabledFaceMovement=true - true to move the mouth blendshapes with voice audio + * when MyAvatar.hasScriptedBlendshapes is enabled. * @property {number} rotationRecenterFilterLength - Configures how quickly the avatar root rotates to recenter its facing * direction to match that of the user's torso based on head and hands orientation. A smaller value makes the * recentering happen more quickly. The minimum value is 0.01. @@ -178,23 +177,23 @@ class MyAvatar : public Avatar { * the palm, in avatar coordinates. If the hand isn't being positioned by a controller, the value is * {@link Vec3(0)|Vec3.ZERO}. Read-only. * - * @property {Pose} leftHandPose - The pose of the left hand as determined by the hand controllers, relative to the avatar. + * @property {Pose} leftHandPose - The left hand's pose as determined by the hand controllers, relative to the avatar. * Read-only. - * @property {Pose} rightHandPose - The pose right hand position as determined by the hand controllers, relative to the - * avatar. Read-only. - * @property {Pose} leftHandTipPose - The pose of the left hand as determined by the hand controllers, relative to the - * avatar, with the position adjusted to be 0.3m along the direction of the palm. Read-only. - * @property {Pose} rightHandTipPose - The pose of the right hand as determined by the hand controllers, relative to the - * avatar, with the position adjusted by 0.3m along the direction of the palm. Read-only. + * @property {Pose} rightHandPose - The right hand's pose as determined by the hand controllers, relative to the avatar. + * Read-only. + * @property {Pose} leftHandTipPose - The left hand's pose as determined by the hand controllers, relative to the avatar, + * with the position adjusted by 0.3m along the direction of the palm. Read-only. + * @property {Pose} rightHandTipPose - The right hand's pose as determined by the hand controllers, relative to the avatar, + * with the position adjusted by 0.3m along the direction of the palm. Read-only. * * @property {number} energy - Deprecated: This property will be removed from the API. * @property {boolean} isAway - true if your avatar is away (i.e., inactive), false if it is * active. * - * @property {boolean} centerOfGravityModelEnabled=true - If true then the avatar hips are placed according to - * the center of gravity model that balances the center of gravity over the base of support of the feet. Setting the - * value false results in the default behavior where the hips are positioned under the head. - * @property {boolean} hmdLeanRecenterEnabled=true - If true then the avatar is re-centered to be under the + * @property {boolean} centerOfGravityModelEnabled=true - true if the avatar hips are placed according to + * the center of gravity model that balances the center of gravity over the base of support of the feet. Set the + * value to false for default behavior where the hips are positioned under the head. + * @property {boolean} hmdLeanRecenterEnabled=true - true IF 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 the avatar to collide with the environment, @@ -227,9 +226,9 @@ class MyAvatar : public Avatar { * where MyAvatar.sessionUUID is not available (e.g., if not connected to a domain). Note: Likely to be deprecated. * Read-only. * - * @property {number} walkSpeed - Adjusts the walk speed of your avatar. - * @property {number} walkBackwardSpeed - Adjusts the walk backward speed of your avatar. - * @property {number} sprintSpeed - Adjusts the sprint speed of your avatar. + * @property {number} walkSpeed - The walk speed of your avatar. + * @property {number} walkBackwardSpeed - The walk backward speed of your avatar. + * @property {number} sprintSpeed - The sprint speed of your avatar. * @property {MyAvatar.SitStandModelType} userRecenterModel - Controls avatar leaning and recentering behavior. * @property {number} isInSittingState - true if your avatar is sitting (avatar leaning is disabled, * recenntering is enabled), false if it is standing (avatar leaning is enabled, and avatar recenters if it @@ -237,8 +236,8 @@ class MyAvatar : public Avatar { * user sits or stands, unless isSitStandStateLocked == true. Setting the property value overrides the * current siting / standing state, which is updated when the user next sits or stands unless * isSitStandStateLocked == true. - * @property {boolean} isSitStandStateLocked - true locks the avatar sitting / standing state, i.e., disables - * automatically changing it based on the user sitting or standing. + * @property {boolean} isSitStandStateLocked - true to lock the avatar sitting/standing state, i.e., use this + * to disable automatically changing state. * @property {boolean} allowTeleporting - true if teleporting is enabled in the Interface settings, * false if it isn't. Read-only. * @@ -396,7 +395,7 @@ public: * 8PITCHRotate the user's avatar head and attached camera about its negative * x-axis (i.e., positive values pitch down) at a rate proportional to the control value, if the camera isn't in HMD, * independent, or mirror modes. - * 9ZOOMZooms the camera in or out. + * 9ZOOMZoom the camera in or out. * 10DELTA_YAWRotate the user's avatar about its y-axis by an amount proportional * to the control value, if the camera isn't in independent or mirror modes. * 11DELTA_PITCHRotate the user's avatar head and attached camera about its @@ -471,13 +470,14 @@ public: void setCollisionWithOtherAvatarsFlags() override; /**jsdoc - * Resets the sensor positioning of your HMD (if used) and recenters your avatar body and head. + * Resets the sensor positioning of your HMD (if in use) and recenters your avatar body and head. * @function MyAvatar.resetSensorsAndBody */ Q_INVOKABLE void resetSensorsAndBody(); /**jsdoc - * Moves and orients the avatar, such that it is directly underneath the HMD, with toes pointed forward. + * Moves and orients the avatar, such that it is directly underneath the HMD, with toes pointed forward in the direction of + * the HMD. * @function MyAvatar.centerBody */ Q_INVOKABLE void centerBody(); // thread-safe @@ -486,7 +486,7 @@ public: /**jsdoc * 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.

+ * forget this history to prevent contorted joints, e.g., after finishing with an override animation.

* @function MyAvatar.clearIKJointLimitHistory */ Q_INVOKABLE void clearIKJointLimitHistory(); // thread-safe @@ -502,14 +502,14 @@ public: /**jsdoc * Gets the avatar orientation. Suitable for use in QML. * @function MyAvatar.setOrientationVar - * @param {object} newOrientationVar - The avatar orientation. + * @param {object} newOrientationVar - The avatar's orientation. */ Q_INVOKABLE void setOrientationVar(const QVariant& newOrientationVar); /**jsdoc * Gets the avatar orientation. Suitable for use in QML. * @function MyAvatar.getOrientationVar - * @returns {object} The avatar orientation. + * @returns {object} The avatar's orientation. */ Q_INVOKABLE QVariant getOrientationVar() const; @@ -558,9 +558,9 @@ public: *

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 + * @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. * @param fps {number} The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. * @param loop {boolean} Set to true if the animation should loop. @@ -572,6 +572,7 @@ public: * MyAvatar.overrideAnimation(ANIM_URL, 30, true, 0, 53); * Script.setTimeout(function () { * MyAvatar.restoreAnimation(); + * MyAvatar.clearIKJointLimitHistory(); * }, 3000); */ Q_INVOKABLE void overrideAnimation(const QString& url, float fps, bool loop, float firstFrame, float lastFrame); @@ -617,18 +618,18 @@ public: *

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 + * 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 + * 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. + * @param 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. * @param fps {number} The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. * @param loop {boolean} Set to true if the animation should loop * @param firstFrame {number} The frame the animation should start at @@ -653,9 +654,9 @@ public: *

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 + * 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}. + * (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 @@ -688,10 +689,9 @@ public: * @function MyAvatar.addAnimationStateHandler * @param {function} handler - The animation state handler function to add. * @param {Array|null} propertiesList - The list of {@link MyAvatar.AnimStateDictionary|AnimStateDictionary} - * properties that should be included the in parameter that the handler function is called with. If null + * properties that should be included in the parameter that the handler function is called with. If null * then all properties are included in the call parameter. - * @returns {number} The ID of the animation state handler function if successfully added, undefined if not - * successfully added. + * @returns {number} The ID of the animation state handler function if successfully added, undefined if not. * @example Log all the animation state dictionary parameters for a short while. * function animStateHandler(dictionary) { * print("Anim state dictionary: " + JSON.stringify(dictionary)); @@ -715,7 +715,7 @@ public: /**jsdoc - * Gets whether or not you do snap turns in HMD mode. + * Gets whether you do snap turns in HMD mode. * @function MyAvatar.getSnapTurn * @returns {boolean} true if you do snap turns in HMD mode; false if you do smooth turns in HMD * mode. @@ -761,7 +761,7 @@ public: Q_INVOKABLE QString getHmdAvatarAlignmentType() const; /**jsdoc - * Sets whether the avatar hips are balanced over the feet or positioned under the head. + * Sets whether the avatar's hips are balanced over the feet or positioned under the head. * @function MyAvatar.setCenterOfGravityModelEnabled * @param {boolean} enabled - true to balance the hips over the feet, false to position the hips * under the head. @@ -777,7 +777,7 @@ public: Q_INVOKABLE bool getCenterOfGravityModelEnabled() const { return _centerOfGravityModelEnabled; } /**jsdoc - * Sets whether or not the avatar's position updates to recenter the avatar under the head. In room-scale VR, recentering + * Sets whether the avatar's position updates to recenter the avatar under the head. In room-scale VR, recentering * causes your avatar to follow your HMD as you walk around the room. Disabling recentering is useful if you want to pin * the avatar to a fixed position. * @function MyAvatar.setHMDLeanRecenterEnabled @@ -787,7 +787,7 @@ public: Q_INVOKABLE void setHMDLeanRecenterEnabled(bool value) { _hmdLeanRecenterEnabled = value; } /**jsdoc - * Gets whether or not the avatar's position updates to recenter the avatar under the head. In room-scale VR, recentering + * Gets whether the avatar's position updates to recenter the avatar under the head. In room-scale VR, recentering * causes your avatar to follow your HMD as you walk around the room. * @function MyAvatar.getHMDLeanRecenterEnabled * @returns {boolean} true if recentering is enabled, false if not. @@ -864,7 +864,7 @@ public: float getDriveKey(DriveKeys key) const; /**jsdoc - * Gets the value of a drive key, regardless of whether or not it is disabled. + * Gets the value of a drive key, regardless of whether it is disabled. * @function MyAvatar.getRawDriveKey * @param {MyAvatar.DriveKeys} key - The drive key. * @returns {number} The value of the drive key. @@ -889,14 +889,15 @@ public: Q_INVOKABLE void disableDriveKey(DriveKeys key); /**jsdoc - * Enables the acction associated with a drive key. + * Enables the action associated with a drive key. The action may have been disabled with + * {@link MyAvatar.disableDriveKey|disableDriveKey}. * @function MyAvatar.enableDriveKey * @param {MyAvatar.DriveKeys} key - The drive key to enable. */ Q_INVOKABLE void enableDriveKey(DriveKeys key); /**jsdoc - * Checks whether or not a drive key is disabled. + * Checks whether a drive key is disabled. * @function MyAvatar.isDriveKeyDisabled * @param {DriveKeys} key - The drive key to check. * @returns {boolean} true if the drive key is disabled, false if it isn't. @@ -925,7 +926,7 @@ public: Q_INVOKABLE void triggerRotationRecenter(); /**jsdoc - * Gets whether or not the avatar is configured to keep its center of gravity under its head. + * Gets whether 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. @@ -967,8 +968,8 @@ public: Q_INVOKABLE float getHeadFinalPitch() const { return getHead()->getFinalPitch(); } /**jsdoc - * If a face tracker is connected and being used, gets the estimated pitch of the user's head scaled such that the avatar - * looks at the edge of the view frustum when the user looks at the edge of their screen. + * If a face tracker is connected and being used, gets the estimated pitch of the user's head scaled. This is scale such + * that the avatar looks at the edge of the view frustum when the user looks at the edge of their screen. * @function MyAvatar.getHeadDeltaPitch * @returns {number} The pitch that the avatar's head should be if a face tracker is connected and being used, otherwise * 0, in degrees. @@ -1080,8 +1081,8 @@ public: /**jsdoc * Gets the pose (position, rotation, velocity, and angular velocity) of the avatar's left hand, relative to the avatar, as * positioned by a hand controller (e.g., Oculus Touch or Vive), and translated 0.3m along the palm. - *

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 + *

Note: 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 Leap Motion, the return value's valid property will be * false and any pose values returned will not be meaningful.

* @function MyAvatar.getLeftHandTipPose * @returns {Pose} The pose of the avatar's left hand, relative to the avatar, as positioned by a hand controller, and @@ -1092,8 +1093,8 @@ public: /**jsdoc * Gets the pose (position, rotation, velocity, and angular velocity) of the avatar's right hand, relative to the avatar, as * positioned by a hand controller (e.g., Oculus Touch or Vive), and translated 0.3m along the palm. - *

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 + *

Note: 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 Leap Motion, the return value's valid property will be * false and any pose values returned will not be meaningful.

* @function MyAvatar.getRightHandTipPose * @returns {Pose} The pose of the avatar's right hand, relative to the avatar, as positioned by a hand controller, and @@ -1247,14 +1248,14 @@ public: void clearWornAvatarEntities(); /**jsdoc - * Checks whether your avatar is flying or not. + * Checks whether your avatar is flying. * @function MyAvatar.isFlying * @returns {boolean} true if your avatar is flying and not taking off or falling, false if not. */ Q_INVOKABLE bool isFlying(); /**jsdoc - * Checks whether your avatar is in the air or not. + * Checks whether your avatar is in the air. * @function MyAvatar.isInAir * @returns {boolean} true if your avatar is taking off, flying, or falling, otherwise false * because your avatar is on the ground. @@ -1332,9 +1333,9 @@ public: Q_INVOKABLE void setAvatarScale(float scale); /**jsdoc - * Sets whether or not the avatar should collide with entities. + * Sets whether the avatar should collide with entities. *

Note: A false value won't disable collisions if the avatar is in a zone that disallows - * collisionless avatars, however the false value will be set so that collisions are disabled as soon as the + * collisionless avatars. However, the false value will be set so that collisions are disabled as soon as the * avatar moves to a position where collisionless avatars are allowed. * @function MyAvatar.setCollisionsEnabled * @param {boolean} enabled - true to enable the avatar to collide with entities, false to @@ -1343,7 +1344,7 @@ public: Q_INVOKABLE void setCollisionsEnabled(bool enabled); /**jsdoc - * Gets whether or not the avatar will currently collide with entities. + * Gets whether the avatar will currently collide with entities. *

Note: The avatar will always collide with entities if in a zone that disallows collisionless avatars. * @function MyAvatar.getCollisionsEnabled * @returns {boolean} true if the avatar will currently collide with entities, false if it won't. @@ -1351,7 +1352,7 @@ public: Q_INVOKABLE bool getCollisionsEnabled(); /**jsdoc - * Sets whether or not the avatar should collide with other avatars. + * Sets whether the avatar should collide with other avatars. * @function MyAvatar.setOtherAvatarsCollisionsEnabled * @param {boolean} enabled - true to enable the avatar to collide with other avatars, false * to disable. @@ -1359,7 +1360,7 @@ public: Q_INVOKABLE void setOtherAvatarsCollisionsEnabled(bool enabled); /**jsdoc - * Gets whether or not the avatar will collide with other avatars. + * Gets whether the avatar will collide with other avatars. * @function MyAvatar.getOtherAvatarsCollisionsEnabled * @returns {boolean} true if the avatar will collide with other avatars, false if it won't. */ @@ -1395,6 +1396,10 @@ public: * @function MyAvatar.getAbsoluteJointRotationInObjectFrame * @param {number} index - The index of the joint. * @returns {Quat} The rotation of the joint relative to the avatar. + * @example Report the rotation of your avatar's head joint relative to your avatar. + * var headIndex = MyAvatar.getJointIndex("Head"); + * var headRotation = MyAvatar.getAbsoluteJointRotationInObjectFrame(headIndex); + * print("Head rotation: " + JSON.stringify(Quat.safeEulerAngles(headRotation))); // Degrees */ virtual glm::quat getAbsoluteJointRotationInObjectFrame(int index) const override; @@ -1404,6 +1409,10 @@ public: * @function MyAvatar.getAbsoluteJointTranslationInObjectFrame * @param {number} index - The index of the joint. * @returns {Vec3} The translation of the joint relative to the avatar. + * @example Report the translation of your avatar's head joint relative to your avatar. + * var headIndex = MyAvatar.getJointIndex("Head"); + * var headTranslation = MyAvatar.getAbsoluteJointTranslationInObjectFrame(headIndex); + * print("Head translation: " + JSON.stringify(headTranslation)); */ virtual glm::vec3 getAbsoluteJointTranslationInObjectFrame(int index) const override; @@ -1500,36 +1509,56 @@ public: void prepareAvatarEntityDataForReload(); /**jsdoc - * Creates a new grab, that grabs an entity. + * Creates a new grab that grabs an entity. * @function MyAvatar.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 {Vec3} offset - The target's local position relative to the joint. * @param {Quat} rotationalOffset - The target's local rotation relative to the joint. * @returns {Uuid} The ID of the new grab. + * @example Create and grab an entity for a short while. + * var entityPosition = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })); + * var entityRotation = MyAvatar.orientation; + * var entityID = Entities.addEntity({ + * type: "Box", + * position: entityPosition, + * rotation: entityRotation, + * dimensions: { x: 0.5, y: 0.5, z: 0.5 } + * }); + * var rightHandJoint = MyAvatar.getJointIndex("RightHand"); + * var relativePosition = Entities.worldToLocalPosition(entityPosition, MyAvatar.SELF_ID, rightHandJoint); + * var relativeRotation = Entities.worldToLocalRotation(entityRotation, MyAvatar.SELF_ID, rightHandJoint); + * var grabID = MyAvatar.grab(entityID, rightHandJoint, relativePosition, relativeRotation); + * + * Script.setTimeout(function () { + * MyAvatar.releaseGrab(grabID); + * Entities.deleteEntity(entityID); + * }, 10000); */ Q_INVOKABLE const QUuid grab(const QUuid& targetID, int parentJointIndex, glm::vec3 positionalOffset, glm::quat rotationalOffset); /**jsdoc - * Releases (deletes) a grab, to stop grabbing an entity. + * Releases (deletes) a grab to stop grabbing an entity. * @function MyAvatar.releaseGrab * @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. + * Gets details of all avatar entities. * @function MyAvatar.getAvatarEntityData - * @override - * @returns {AvatarEntityMap} The avatar entities as binary data. + * @returns {AvatarEntityMap} Details of the avatar entities. + * @example Report the current avatar entities. + * var avatarEntityData = MyAvatar.getAvatarEntityData(); + * print("Avatar entities: " + JSON.stringify(avatarEntityData)); */ AvatarEntityMap getAvatarEntityData() const override; /**jsdoc - * Sets the avatar entities from binary data. + * Sets all avatar entities from an object. * @function MyAvatar.setAvatarEntityData - * @param {AvatarEntityMap} avatarEntityData - The avatar entities as binary data. + * @param {AvatarEntityMap} avatarEntityData - Details of the avatar entities. */ void setAvatarEntityData(const AvatarEntityMap& avatarEntityData) override; @@ -1549,7 +1578,7 @@ public: /**jsdoc * Enables and disables flow simulation of physics on the avatar's hair, clothes, and body parts. See - * {@link https://docs.highfidelity.com/create/avatars/create-avatars/add-flow.html|Add Flow to Your Avatar} for more + * {@link https://docs.highfidelity.com/create/avatars/add-flow.html|Add Flow to Your Avatar} for more * information. * @function MyAvatar.useFlow * @param {boolean} isActive - true if flow simulation is enabled on the joint, false if it isn't. @@ -1585,7 +1614,7 @@ public slots: * MyAvatar.resetSize(); * * for (var i = 0; i < 5; i++){ - * print ("Growing by 5 percent"); + * print("Growing by 5 percent"); * MyAvatar.increaseSize(); * } */ @@ -1598,7 +1627,7 @@ public slots: * MyAvatar.resetSize(); * * for (var i = 0; i < 5; i++){ - * print ("Shrinking by 5 percent"); + * print("Shrinking by 5 percent"); * MyAvatar.decreaseSize(); * } */ @@ -1695,7 +1724,7 @@ public slots: /**jsdoc - * Adds a thrust to your avatar's current thrust, to be applied for a short while. + * Adds a thrust to your avatar's current thrust to be applied for a short while. * @function MyAvatar.addThrust * @param {Vec3} thrust - The thrust direction and magnitude. * @deprecated Use {@link MyAvatar|MyAvatar.motorVelocity} and related properties instead. @@ -1735,7 +1764,9 @@ public slots: void setToggleHips(bool followHead); /**jsdoc - * Displays base of support of feet debug graphics. + * Displays the base of support area debug graphics if in HMD mode. If your head goes outside this area your avatar's hips + * are moved to counterbalance your avatar, and if your head moves too far then your avatar's position is moved (i.e., a + * step happens). * @function MyAvatar.setEnableDebugDrawBaseOfSupport * @param {boolean} enabled - true to show the debug graphics, false to hide. */ @@ -1805,7 +1836,7 @@ public slots: void setEnableDebugDrawDetailedCollision(bool isEnabled); /**jsdoc - * Gets whether or not your avatar mesh is visible. + * Gets whether your avatar mesh is visible. * @function MyAvatar.getEnableMeshVisible * @returns {boolean} true if your avatar's mesh is visible, otherwise false. */ @@ -1830,7 +1861,7 @@ public slots: void sanitizeAvatarEntityProperties(EntityItemProperties& properties) const; /**jsdoc - * Sets whether or not your avatar mesh is visible to you. + * Sets whether your avatar mesh is visible to you. * @function MyAvatar.setEnableMeshVisible * @param {boolean} enabled - true to show your avatar mesh, false to hide. * @example Make your avatar invisible for 10s. @@ -1842,7 +1873,7 @@ public slots: virtual void setEnableMeshVisible(bool isEnabled) override; /**jsdoc - * Sets whether or not inverse kinematics (IK) for your avatar. + * Sets whether inverse kinematics (IK) is enabled for your avatar. * @function MyAvatar.setEnableInverseKinematics * @param {boolean} enabled - true to enable IK, false to disable. */ @@ -1854,7 +1885,8 @@ public slots: *

See {@link https://docs.highfidelity.com/create/avatars/custom-animations.html|Custom Avatar Animations} for * information on animation graphs.

* @function MyAvatar.getAnimGraphOverrideUrl - * @returns {string} The URL of the override animation graph. "" if there is no override animation graph. + * @returns {string} The URL of the override animation graph JSON file. "" if there is no override animation + * graph. */ QUrl getAnimGraphOverrideUrl() const; // thread-safe @@ -1863,25 +1895,27 @@ public slots: *

See {@link https://docs.highfidelity.com/create/avatars/custom-animations.html|Custom Avatar Animations} for * information on animation graphs.

* @function MyAvatar.setAnimGraphOverrideUrl - * @param {string} url - The URL of the animation graph to use. Set to "" to clear an override. + * @param {string} url - The URL of the animation graph JSON file to use. Set to "" to clear an override. */ void setAnimGraphOverrideUrl(QUrl value); // thread-safe /**jsdoc - * Gets the URL of animation graph that's currently being used for avatar animations. + * Gets the URL of animation graph (i.e., the avatar animation JSON) that's currently being used for avatar animations. *

See {@link https://docs.highfidelity.com/create/avatars/custom-animations.html|Custom Avatar Animations} for * information on animation graphs.

* @function MyAvatar.getAnimGraphUrl - * @returns {string} The URL of the current animation graph. + * @returns {string} The URL of the current animation graph JSON file. + * @Example Report the current avatar animation JSON being used. + * print(MyAvatar.getAnimGraphUrl()); */ QUrl getAnimGraphUrl() const; // thread-safe /**jsdoc - * Sets the current animation graph to use for avatar animations and makes it the default. + * Sets the current animation graph (i.e., the avatar animation JSON) to use for avatar animations and makes it the default. *

See {@link https://docs.highfidelity.com/create/avatars/custom-animations.html|Custom Avatar Animations} for * information on animation graphs.

* @function MyAvatar.setAnimGraphUrl - * @param {string} url - The URL of the animation graph to use. + * @param {string} url - The URL of the animation graph JSON file to use. */ void setAnimGraphUrl(const QUrl& url); // thread-safe @@ -1963,11 +1997,14 @@ signals: void otherAvatarsCollisionsEnabledChanged(bool enabled); /**jsdoc - * Triggered when the avatar's animation graph URL changes. + * Triggered when the avatar's animation graph being used changes. * @function MyAvatar.animGraphUrlChanged - * @param {string} url - The URL of the new animation graph. + * @param {string} url - The URL of the new animation graph JSON file. * @returns {Signal} - */ + * @example Report when the current avatar animation JSON being used changes. + * MyAvatar.animGraphUrlChanged.connect(function (url) { + * print("Avatar animation JSON changed to: " + url); + * }); */ void animGraphUrlChanged(const QUrl& url); /**jsdoc diff --git a/libraries/animation/src/AnimInverseKinematics.h b/libraries/animation/src/AnimInverseKinematics.h index d5a110ea76..6d58ecedec 100644 --- a/libraries/animation/src/AnimInverseKinematics.h +++ b/libraries/animation/src/AnimInverseKinematics.h @@ -66,24 +66,23 @@ public: * ValueName

Description * * - * 0RelaxToUnderPosesThis is a blend between PreviousSolution and - * UnderPoses: it is 15/16 PreviousSolution and 1/16 UnderPoses. This - * provides some of the benefits of using UnderPoses so that the underlying animation is still visible, - * while at the same time converging faster then using the UnderPoses only initial solution. - * 1RelaxToLimitCenterPosesThis is a blend between - * Previous Solution and LimitCenterPoses: it is 15/16 PreviousSolution and - * 1/16 LimitCenterPoses. This should converge quickly because it is close to the previous solution, but - * still provides the benefits of avoiding limb locking. + * 0RelaxToUnderPosesThis is a blend: it is 15/16 PreviousSolution + * and 1/16 UnderPoses. This provides some of the benefits of using UnderPoses so that the + * underlying animation is still visible, while at the same time converging faster then using the + * UnderPoses as the only initial solution. + * 1RelaxToLimitCenterPosesThis is a blend: it is 15/16 + * PreviousSolution and 1/16 LimitCenterPoses. This should converge quickly because it is + * close to the previous solution, but still provides the benefits of avoiding limb locking. * 2PreviousSolutionThe IK system will begin to solve from the same position and * orientations for each joint that was the result from the previous frame.
- * Pros: because the end effectors typically do not move much from frame to frame, this is likely to converge quickly + * Pros: As the end effectors typically do not move much from frame to frame, this is likely to converge quickly * to a valid solution.
* Cons: If the previous solution resulted in an awkward or uncomfortable posture, the next frame will also be * awkward and uncomfortable. It can also result in locked elbows and knees. - * 3UnderPosesThe IK occurs at one of the top-most layers, it has access to the + * 3UnderPosesThe IK occurs at one of the top-most layers. It has access to the * full posture that was computed via canned animations and blends. We call this animated set of poses the "under * pose". The under poses are what would be visible if IK was completely disabled. Using the under poses as the - * initial conditions of the CCD solve will cause some of the animated motion to be blended in to the result of the + * initial conditions of the CCD solve will cause some of the animated motion to be blended into the result of the * IK. This can result in very natural results, especially if there are only a few IK targets enabled. On the other * hand, because the under poses might be quite far from the desired end effector, it can converge slowly in some * cases, causing it to never reach the IK target in the allotted number of iterations. Also, in situations where all @@ -93,7 +92,7 @@ public: * constraints. This can prevent the IK solution from getting locked or stuck at a particular constraint. For * example, if the arm is pointing straight outward from the body, as the end effector moves towards the body, at * some point the elbow should bend to accommodate. However, because the CCD solver is stuck at a local maximum, it - * will not rotate the elbow, unless the initial conditions already has the elbow bent, which is the case for + * will not rotate the elbow, unless the initial conditions already have the elbow bent, which is the case for * LimitCenterPoses. When all the IK targets are enabled, this result will provide a consistent starting * point for each IK solve, hopefully resulting in a consistent, natural result. * diff --git a/libraries/animation/src/AnimOverlay.h b/libraries/animation/src/AnimOverlay.h index 623672143e..1ad4e100db 100644 --- a/libraries/animation/src/AnimOverlay.h +++ b/libraries/animation/src/AnimOverlay.h @@ -34,17 +34,21 @@ public: * 0FullBodyBoneSetAll joints. * 1UpperBodyBoneSetOnly the "Spine" joint and its children. * 2LowerBodyBoneSetOnly the leg joints and their children. - * 3LeftArmBoneSetJoints that are children of the "LeftShoulder" joint. - * 4RightArmBoneSetJoints that are children of the "RightShoulder" + * 3LeftArmBoneSetJoints that are the children of the "LeftShoulder" * joint. - * 5AboveTheHeadBoneSetJoints that are children of the "Head" joint. - * 6BelowTheHeadBoneSetJoints that are NOT children of the "head" + * 4RightArmBoneSetJoints that are the children of the "RightShoulder" + * joint. + * 5AboveTheHeadBoneSetJoints that are the children of the "Head" + * joint. + * 6BelowTheHeadBoneSetJoints that are NOT the children of the "head" * joint. * 7HeadOnlyBoneSetThe "Head" joint. * 8SpineOnlyBoneSetThe "Spine" joint. * 9EmptyBoneSetNo joints. - * 10LeftHandBoneSetjoints that are children of the "LeftHand" joint. - * 11RightHandBoneSetJoints that are children of the "RightHand" joint. + * 10LeftHandBoneSetjoints that are the children of the "LeftHand" + * joint. + * 11RightHandBoneSetJoints that are the children of the "RightHand" + * joint. * 12HipsOnlyBoneSetThe "Hips" joint. * 13BothFeetBoneSetThe "LeftFoot" and "RightFoot" joints. * diff --git a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h index cec440eb1a..87e6af5bb3 100644 --- a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h +++ b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h @@ -203,7 +203,7 @@ public: /**jsdoc * Gets the default rotation of a joint (in the current avatar) relative to its parent. *

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

+ * Avatar Standards.

* @function MyAvatar.getDefaultJointRotation * @param {number} index - The joint index. * @returns {Quat} The default rotation of the joint if the joint index is valid, otherwise {@link Quat(0)|Quat.IDENTITY}. @@ -214,7 +214,7 @@ public: * Gets the default translation of a joint (in the current avatar) 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.

+ * Avatar Standards.

* @function MyAvatar.getDefaultJointTranslation * @param {number} index - The joint index. * @returns {Vec3} The default translation of the joint (in model coordinates) if the joint index is valid, otherwise @@ -223,22 +223,30 @@ public: Q_INVOKABLE virtual glm::vec3 getDefaultJointTranslation(int index) const; /**jsdoc - * Provides read-only access to the default joint rotations in avatar coordinates. + * Gets 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. - * @returns {Quat} The rotation of this joint in avatar coordinates. + * @returns {Quat} The default rotation of the joint in avatar coordinates. + * @example Report the default rotation of your avatar's head joint relative to your avatar. + * var headIndex = MyAvatar.getJointIndex("Head"); + * var defaultHeadRotation = MyAvatar.getAbsoluteDefaultJointRotationInObjectFrame(headIndex); + * print("Default head rotation: " + JSON.stringify(Quat.safeEulerAngles(defaultHeadRotation))); // Degrees */ Q_INVOKABLE virtual glm::quat getAbsoluteDefaultJointRotationInObjectFrame(int index) const; /**jsdoc - * Provides read-only access to the default joint translations in avatar coordinates. + * Gets 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 * @param index {number} - The joint index. - * @returns {Vec3} The position of this joint in avatar coordinates. + * @returns {Vec3} The default position of the joint in avatar coordinates. + * @example Report the default translation of your avatar's head joint relative to your avatar. + * var headIndex = MyAvatar.getJointIndex("Head"); + * var defaultHeadTranslation = MyAvatar.getAbsoluteDefaultJointTranslationInObjectFrame(headIndex); + * print("Default head translation: " + JSON.stringify(defaultHeadTranslation)); */ Q_INVOKABLE virtual glm::vec3 getAbsoluteDefaultJointTranslationInObjectFrame(int index) const; @@ -459,7 +467,7 @@ public: Q_INVOKABLE virtual quint16 getParentJointIndex() const override { return SpatiallyNestable::getParentJointIndex(); } /**jsdoc - * sets the joint of the entity or avatar that the avatar is parented to. + * Sets the joint of the entity or avatar that the avatar is parented to. * @function MyAvatar.setParentJointIndex * @param {number} parentJointIndex - he joint of the entity or avatar that the avatar should be parented to. Use * 65535 or -1 to parent to the entity or avatar's position and orientation rather than a diff --git a/libraries/avatars/src/AvatarData.cpp b/libraries/avatars/src/AvatarData.cpp index 317d9ec903..39dfaa8a1a 100755 --- a/libraries/avatars/src/AvatarData.cpp +++ b/libraries/avatars/src/AvatarData.cpp @@ -2802,7 +2802,7 @@ glm::vec3 AvatarData::getAbsoluteJointTranslationInObjectFrame(int index) const /**jsdoc * Information on an attachment worn by the avatar. * @typedef {object} AttachmentData - * @property {string} modelUrl - The URL of the model file. Models can be .FBX or .OBJ format. + * @property {string} modelUrl - The URL of the model file. Models can be FBX or OBJ format. * @property {string} jointName - The offset to apply to the model relative to the joint position. * @property {Vec3} translation - The offset from the joint that the attachment is positioned at. * @property {Vec3} rotation - The rotation applied to the model relative to the joint orientation. @@ -3015,6 +3015,10 @@ float AvatarData::_avatarSortCoefficientSize { 8.0f }; float AvatarData::_avatarSortCoefficientCenter { 0.25f }; float AvatarData::_avatarSortCoefficientAge { 1.0f }; +/**jsdoc + * An object with the UUIDs of avatar entities as keys and avatar entity properties objects as values. + * @typedef {Object.} AvatarEntityMap + */ QScriptValue AvatarEntityMapToScriptValue(QScriptEngine* engine, const AvatarEntityMap& value) { QScriptValue obj = engine->newObject(); for (auto entityID : value.keys()) { diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index e2d24465cb..00e7e67923 100755 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -61,10 +61,6 @@ using AvatarSharedPointer = std::shared_ptr; using AvatarWeakPointer = std::weak_ptr; using AvatarHash = QHash; -/**jsdoc - * An object with the UUIDs of avatar entities as keys and binary blobs, being the entity properties, as values. - * @typedef {Object.>} AvatarEntityMap - */ using AvatarEntityMap = QMap; using PackedAvatarEntityMap = QMap; // similar to AvatarEntityMap, but different internal format using AvatarEntityIDs = QSet; @@ -439,13 +435,13 @@ class AvatarData : public QObject, public SpatiallyNestable { // IMPORTANT: The JSDoc for the following properties should be copied to MyAvatar.h and ScriptableAvatar.h. /* * @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 between 0.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 + * @property {number} scale=1.0 - 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. + * @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 + * @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. + * @property {number} bodyYaw - The left or right rotation 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". @@ -461,28 +457,27 @@ class AvatarData : public QObject, public SpatiallyNestable { * sometimes called "bank". * @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 + * @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 + * @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.
+ * @property {string} sessionDisplayName - 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. + * @property {boolean} lookAtSnappingEnabled=true - 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. + * @property {string} skeletonModelURL - The avatar's FST file. + * @property {AttachmentData[]} attachmentData - Information on the avatar's attachments.
* Deprecated: Use avatar entities instead. * @property {string[]} jointNames - The list of joints in the current avatar model. Read-only. * @property {Uuid} sessionUUID - Unique ID of the avatar in the domain. Read-only. - * @property {Mat4} sensorToWorldMatrix - The scale, rotation, and translation transform from the user's real world to the + * @property {Mat4} sensorToWorldMatrix - 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. - * @property {Mat4} controllerLeftHandMatrix - The rotation and translation of the left hand controller relative to the + * @property {Mat4} controllerLeftHandMatrix - The rotation and translation of the left hand controller relative to the * avatar. Read-only. - * @property {Mat4} controllerRightHandMatrix - The rotation and translation of the right hand controller relative to the + * @property {Mat4} controllerRightHandMatrix - The rotation and translation of the right hand controller relative to the * avatar. Read-only. - * @property {number} sensorToWorldScale - The scale that transforms dimensions in the user's real world to the avatar's + * @property {number} sensorToWorldScale - The scale that transforms dimensions in the user's real world to the avatar's * size in the virtual world. Read-only. */ Q_PROPERTY(glm::vec3 position READ getWorldPosition WRITE setPositionViaScript) @@ -785,7 +780,7 @@ public: /**jsdoc * Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see - * Avatar Standards. + * Avatar Standards. * @function Avatar.getJointRotation * @param {number} index - The index of the joint. * @returns {Quat} The rotation of the joint relative to its parent. @@ -796,7 +791,7 @@ public: * 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.

+ * Avatar Standards.

* @function Avatar.getJointTranslation * @param {number} index - The index of the joint. * @returns {Vec3} The translation of the joint relative to its parent, in model coordinates. @@ -897,7 +892,7 @@ public: Q_INVOKABLE virtual void clearJointData(const QString& name); /**jsdoc - * Checks that the data for a joint are valid. + * Checks if the data for a joint are valid. * @function Avatar.isJointDataValid * @param {string} name - The name of the joint. * @returns {boolean} true if the joint data are valid, false if not. @@ -906,7 +901,7 @@ public: /**jsdoc * Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see - * Avatar Standards. + * Avatar Standards. * @function Avatar.getJointRotation * @param {string} name - The name of the joint. * @returns {Quat} The rotation of the joint relative to its parent. @@ -921,7 +916,7 @@ public: * 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.

+ * Avatar Standards.

* @function Avatar.getJointTranslation * @param {number} name - The name of the joint. * @returns {Vec3} The translation of the joint relative to its parent, in model coordinates. @@ -1062,8 +1057,13 @@ public: * your avatar's face, use {@link Avatar.setForceFaceTrackerConnected} or {@link MyAvatar.setForceFaceTrackerConnected}. * @function Avatar.setBlendshape * @param {string} name - The name of the blendshape, per the - * {@link https://docs.highfidelity.com/create/avatars/create-avatars/avatar-standards.html#blendshapes Avatar Standards}. + * {@link https://docs.highfidelity.com/create/avatars/avatar-standards.html#blendshapes Avatar Standards}. * @param {number} value - 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". */ Q_INVOKABLE void setBlendshape(QString name, float val) { _headData->setBlendshape(name, val); } @@ -1170,7 +1170,7 @@ public: * @example Report the URLs of all current attachments. * var attachments = MyAvatar.getaAttachmentData(); * for (var i = 0; i < attachments.length; i++) { - * print (attachments[i].modelURL); + * print(attachments[i].modelURL); * } * * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". @@ -1318,6 +1318,14 @@ public: * @function Avatar.getSensorToWorldMatrix * @returns {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. + * @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". */ // thread safe Q_INVOKABLE glm::mat4 getSensorToWorldMatrix() const; @@ -1335,6 +1343,14 @@ public: * Gets the rotation and translation of the left hand controller relative to the avatar. * @function Avatar.getControllerLeftHandMatrix * @returns {Mat4} 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". */ // thread safe Q_INVOKABLE glm::mat4 getControllerLeftHandMatrix() const; @@ -1409,6 +1425,12 @@ signals: * Triggered when the avatar's displayName property value changes. * @function Avatar.displayNameChanged * @returns {Signal} + * @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". */ void displayNameChanged(); @@ -1416,6 +1438,12 @@ signals: * Triggered when the avatar's sessionDisplayName property value changes. * @function Avatar.sessionDisplayNameChanged * @returns {Signal} + * @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". */ void sessionDisplayNameChanged(); @@ -1423,6 +1451,12 @@ signals: * Triggered when the avatar's model (i.e., skeletonModelURL property value) is changed. * @function Avatar.skeletonModelURLChanged * @returns {Signal} + * @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". */ void skeletonModelURLChanged(); @@ -1431,6 +1465,12 @@ signals: * @function Avatar.lookAtSnappingChanged * @param {boolean} enabled - true if look-at snapping is enabled, false if not. * @returns {Signal} + * @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". */ void lookAtSnappingChanged(bool enabled); @@ -1438,6 +1478,12 @@ signals: * Triggered when the avatar's sessionUUID property value changes. * @function Avatar.sessionUUIDChanged * @returns {Signal} + * @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". */ void sessionUUIDChanged();