Overte C++ Documentation
MyAvatar.h
1 //
2 // MyAvatar.h
3 // interface/src/avatar
4 //
5 // Created by Mark Peng on 8/16/13.
6 // Copyright 2012 High Fidelity, Inc.
7 // Copyright 2021 Vircadia contributors.
8 // Copyright 2022-2023 Overte e.V.
9 //
10 // Distributed under the Apache License, Version 2.0.
11 // See the accompanying file LICENSE or http://www.apache.org/licenses/LICENSE-2.0.html
12 // SPDX-License-Identifier: Apache-2.0
13 //
14 
15 #ifndef hifi_MyAvatar_h
16 #define hifi_MyAvatar_h
17 
18 #include <bitset>
19 #include <memory>
20 
21 #include <glm/glm.hpp>
22 
23 #include <QUuid>
24 
25 #include <AvatarConstants.h>
26 #include <avatars-renderer/Avatar.h>
27 #include <avatars-renderer/ScriptAvatar.h>
28 #include <controllers/Pose.h>
29 #include <controllers/Actions.h>
30 #include <EntityItem.h>
31 #include <HelperScriptEngine.h>
32 #include <ThreadSafeValueCache.h>
33 #include <Rig.h>
34 #include <SettingHandle.h>
35 #include <Sound.h>
36 #include <shared/Camera.h>
37 #include <ScriptValue.h>
38 
39 #include "AtRestDetector.h"
40 #include "MyCharacterController.h"
41 #include "RingBufferHistory.h"
42 
43 class AvatarActionHold;
44 class ModelItemID;
45 class MyHead;
46 class DetailedMotionState;
47 class ScriptEngine;
48 using ScriptEnginePointer = std::shared_ptr<ScriptEngine>;
49 
50 enum LocomotionRelativeMovementMode {
51  MOVEMENT_HMD_RELATIVE = 0,
52  MOVEMENT_HAND_RELATIVE,
53  MOVEMENT_HAND_RELATIVE_LEVELED
54 };
55 
56 enum eyeContactTarget {
57  LEFT_EYE,
58  RIGHT_EYE,
59  MOUTH
60 };
61 
62 enum AudioListenerMode {
63  FROM_HEAD = 0,
64  FROM_CAMERA,
65  CUSTOM
66 };
67 
68 Q_DECLARE_METATYPE(AudioListenerMode);
69 
70 class MyAvatar : public Avatar {
71  Q_OBJECT
72  friend class AnimStats;
73 
74  /*@jsdoc
75  * Your avatar is your in-world representation of you. The <code>MyAvatar</code> API is used to manipulate the avatar.
76  * For example, you can customize the avatar's appearance, run custom avatar animations,
77  * change the avatar's position within the domain, or manage the avatar's collisions with the environment and other avatars.
78  *
79  * <p>For assignment client scripts, see {@link Avatar}.</p>
80  *
81  * @namespace MyAvatar
82  *
83  * @hifi-interface
84  * @hifi-client-entity
85  * @hifi-avatar
86  *
87  * @comment IMPORTANT: This group of properties is copied from AvatarData.h; they should NOT be edited here.
88  * @property {Vec3} position - The position of the avatar.
89  * @property {number} scale=1.0 - The scale of the avatar. The value can be set to anything between <code>0.005</code> and
90  * <code>1000.0</code>. When the scale value is fetched, it may temporarily be further limited by the domain's settings.
91  * @property {number} density - The density of the avatar in kg/m<sup>3</sup>. The density is used to work out its mass in
92  * the application of physics. <em>Read-only.</em>
93  * @property {Vec3} handPosition - A user-defined hand position, in world coordinates. The position moves with the avatar
94  * but is otherwise not used or changed by Interface.
95  * @property {number} bodyYaw - The left or right rotation about an axis running from the head to the feet of the avatar.
96  * Yaw is sometimes called "heading".
97  * @property {number} bodyPitch - The rotation about an axis running from shoulder to shoulder of the avatar. Pitch is
98  * sometimes called "elevation".
99  * @property {number} bodyRoll - The rotation about an axis running from the chest to the back of the avatar. Roll is
100  * sometimes called "bank".
101  * @property {Quat} orientation - The orientation of the avatar.
102  * @property {Quat} headOrientation - The orientation of the avatar's head.
103  * @property {number} headPitch - The rotation about an axis running from ear to ear of the avatar's head. Pitch is
104  * sometimes called "elevation".
105  * @property {number} headYaw - The rotation left or right about an axis running from the base to the crown of the avatar's
106  * head. Yaw is sometimes called "heading".
107  * @property {number} headRoll - The rotation about an axis running from the nose to the back of the avatar's head. Roll is
108  * sometimes called "bank".
109  * @property {Vec3} velocity - The current velocity of the avatar.
110  * @property {Vec3} angularVelocity - The current angular velocity of the avatar.
111  * @property {number} audioLoudness - The instantaneous loudness of the audio input that the avatar is injecting into the
112  * domain.
113  * @property {number} audioAverageLoudness - The rolling average loudness of the audio input that the avatar is injecting
114  * into the domain.
115  * @property {string} displayName - The avatar's display name.
116  * @property {string} sessionDisplayName - <code>displayName's</code> sanitized and default version defined by the avatar
117  * mixer rather than Interface clients. The result is unique among all avatars present in the domain at the time.
118  * @property {boolean} lookAtSnappingEnabled=true - <code>true</code> if the avatar's eyes snap to look at another avatar's
119  * eyes when the other avatar is in the line of sight and also has <code>lookAtSnappingEnabled == true</code>.
120  * @property {string} skeletonModelURL - The avatar's FST file.
121  * @property {string[]} jointNames - The list of joints in the current avatar model. <em>Read-only.</em>
122  * @property {Uuid} sessionUUID - Unique ID of the avatar in the domain. <em>Read-only.</em>
123  * @property {Mat4} sensorToWorldMatrix - The scale, rotation, and translation transform from the user's real world to the
124  * avatar's size, orientation, and position in the virtual world. <em>Read-only.</em>
125  * @property {Mat4} controllerLeftHandMatrix - The rotation and translation of the left hand controller relative to the
126  * avatar. <em>Read-only.</em>
127  * @property {Mat4} controllerRightHandMatrix - The rotation and translation of the right hand controller relative to the
128  * avatar. <em>Read-only.</em>
129  * @property {number} sensorToWorldScale - The scale that transforms dimensions in the user's real world to the avatar's
130  * size in the virtual world. <em>Read-only.</em>
131  * @property {boolean} hasPriority - <code>true</code> if the avatar is in a "hero" zone, <code>false</code> if it isn't.
132  * <em>Read-only.</em>
133  * @property {boolean} hasScriptedBlendshapes=false - <code>true</code> if blend shapes are controlled by scripted actions,
134  * otherwise <code>false</code>. Set this to <code>true</code> before using the {@link MyAvatar.setBlendshape} method,
135  * and set back to <code>false</code> after you no longer want scripted control over the blend shapes.
136  * <p><strong>Note:</strong> This property will automatically be set to <code>true</code> if the controller system has
137  * valid facial blend shape actions.</p>
138  * @property {boolean} hasProceduralBlinkFaceMovement=true - <code>true</code> if avatars blink automatically by animating
139  * facial blend shapes, <code>false</code> if automatic blinking is disabled. Set to <code>false</code> to fully control
140  * the blink facial blend shapes via the {@link MyAvatar.setBlendshape} method.
141  * @property {boolean} hasProceduralEyeFaceMovement=true - <code>true</code> if the facial blend shapes for an avatar's eyes
142  * adjust automatically as the eyes move, <code>false</code> if this automatic movement is disabled. Set this property
143  * to <code>true</code> to prevent the iris from being obscured by the upper or lower lids. Set to <code>false</code> to
144  * fully control the eye blend shapes via the {@link MyAvatar.setBlendshape} method.
145  * @property {boolean} hasAudioEnabledFaceMovement=true - <code>true</code> if the avatar's mouth blend shapes animate
146  * automatically based on detected microphone input, <code>false</code> if this automatic movement is disabled. Set
147  * this property to <code>false</code> to fully control the mouth facial blend shapes via the
148  * {@link MyAvatar.setBlendshape} method.
149  *
150  * @comment IMPORTANT: This group of properties is copied from Avatar.h; they should NOT be edited here.
151  * @property {Vec3} skeletonOffset - Can be used to apply a translation offset between the avatar's position and the
152  * registration point of the 3D model.
153  *
154  * @property {Vec3} qmlPosition - A synonym for <code>position</code> for use by QML.
155  * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
156  *
157  * @property {Vec3} feetPosition - The position of the avatar's feet.
158  * @property {boolean} shouldRenderLocally=true - If <code>true</code> then your avatar is rendered for you in Interface,
159  * otherwise it is not rendered for you (but it is still rendered for other users).
160  * @property {Vec3} motorVelocity=Vec3.ZERO - The target velocity of your avatar to be achieved by a scripted motor.
161  * @property {number} motorTimescale=1000000 - The timescale for the scripted motor to achieve the target
162  * <code>motorVelocity</code> avatar velocity. Smaller values result in higher acceleration.
163  * @property {string} motorReferenceFrame="camera" - Reference frame of the <code>motorVelocity</code>. Must be one of the
164  * following: <code>"camera"</code>, <code>"avatar"</code>, and <code>"world"</code>.
165  * @property {string} motorMode="simple" - The Type of scripted motor behavior: <code>"simple"</code> to use the
166  * <code>motorTimescale</code> time scale; <code>"dynamic"</code> to use character controller timescales.
167  * @property {string} collisionSoundURL="Body_Hits_Impact.wav" - The sound that's played when the avatar experiences a
168  * collision. It can be a mono or stereo 16-bit WAV file running at either 24kHz or 48kHz. The latter is down-sampled
169  * by the audio mixer, so all audio effectively plays back at a 24khz. 48kHz RAW files are also supported.
170  * @property {number} audioListenerMode=0 - Specifies the listening position when hearing spatialized audio. Must be one
171  * of the following property values:
172  * <ul>
173  * <li><code>MyAvatar.audioListenerModeHead</code></li>
174  * <li><code>MyAvatar.audioListenerModeCamera</code></li>
175  * <li><code>MyAvatar.audioListenerModeCustom</code></li>
176  * </ul>
177  * @property {number} audioListenerModeHead=0 - The audio listening position is at the avatar's head. <em>Read-only.</em>
178  * @property {number} audioListenerModeCamera=1 - The audio listening position is at the camera. <em>Read-only.</em>
179  * @property {number} audioListenerModeCustom=2 - The audio listening position is at a the position specified by set by the
180  * <code>customListenPosition</code> and <code>customListenOrientation</code> property values. <em>Read-only.</em>
181  * @property {Vec3} customListenPosition=Vec3.ZERO - The listening position used when the <code>audioListenerMode</code>
182  * property value is <code>audioListenerModeCustom</code>.
183  * @property {Quat} customListenOrientation=Quat.IDENTITY - The listening orientation used when the
184  * <code>audioListenerMode</code> property value is <code>audioListenerModeCustom</code>.
185  * @property {number} rotationRecenterFilterLength - Configures how quickly the avatar root rotates to recenter its facing
186  * direction to match that of the user's torso based on head and hands orientation. A smaller value makes the
187  * recentering happen more quickly. The minimum value is <code>0.01</code>.
188  * @property {number} rotationThreshold - The angle in radians that the user's torso facing direction (based on head and
189  * hands orientation) can differ from that of the avatar before the avatar's root is rotated to match the user's torso.
190  * @property {boolean} enableStepResetRotation - If <code>true</code> then after the user's avatar takes a step, the
191  * avatar's root immediately rotates to recenter its facing direction to match that of the user's torso based on head
192  * and hands orientation.
193  * @property {boolean} enableDrawAverageFacing - If <code>true</code>, debug graphics are drawn that show the average
194  * facing direction of the user's torso (based on head and hands orientation). This can be useful if you want to try
195  * out different filter lengths and thresholds.
196  *
197  * @property {Vec3} leftHandPosition - The position of the left hand in avatar coordinates if it's being positioned by
198  * controllers, otherwise {@link Vec3(0)|Vec3.ZERO}. <em>Read-only.</em>
199  * @property {Vec3} rightHandPosition - The position of the right hand in avatar coordinates if it's being positioned by
200  * controllers, otherwise {@link Vec3(0)|Vec3.ZERO}. <em>Read-only.</em>
201  * @property {Vec3} leftHandTipPosition - The position 0.3m in front of the left hand's position, in the direction along the
202  * palm, in avatar coordinates. If the hand isn't being positioned by a controller, the value is
203  * {@link Vec3(0)|Vec3.ZERO}. <em>Read-only.</em>
204  * @property {Vec3} rightHandTipPosition - The position 0.3m in front of the right hand's position, in the direction along
205  * the palm, in avatar coordinates. If the hand isn't being positioned by a controller, the value is
206  * {@link Vec3(0)|Vec3.ZERO}. <em>Read-only.</em>
207  *
208  * @property {Pose} leftHandPose - The left hand's pose as determined by the hand controllers, relative to the avatar.
209  * <em>Read-only.</em>
210  * @property {Pose} rightHandPose - The right hand's pose as determined by the hand controllers, relative to the avatar.
211  * <em>Read-only.</em>
212  * @property {Pose} leftHandTipPose - The left hand's pose as determined by the hand controllers, relative to the avatar,
213  * with the position adjusted by 0.3m along the direction of the palm. <em>Read-only.</em>
214  * @property {Pose} rightHandTipPose - The right hand's pose as determined by the hand controllers, relative to the avatar,
215  * with the position adjusted by 0.3m along the direction of the palm. <em>Read-only.</em>
216  *
217  * @property {boolean} isAway - <code>true</code> if your avatar is away (i.e., inactive), <code>false</code> if it is
218  * active.
219  *
220  * @property {boolean} centerOfGravityModelEnabled=true - <code>true</code> if the avatar hips are placed according to
221  * the center of gravity model that balances the center of gravity over the base of support of the feet. Set the
222  * value to <code>false</code> for default behavior where the hips are positioned under the head.
223  * @property {boolean} hmdLeanRecenterEnabled=true - <code>true</code> IF the avatar is re-centered to be under the
224  * head's position. In room-scale VR, this behavior is what causes your avatar to follow your HMD as you walk around
225  * the room. Setting the value <code>false</code> is useful if you want to pin the avatar to a fixed position.
226  * @property {boolean} collisionsEnabled - Set to <code>true</code> to enable the avatar to collide with the environment,
227  * <code>false</code> to disable collisions with the environment. May return <code>true</code> even though the value
228  * was set <code>false</code> because the zone may disallow collisionless avatars.
229  * @property {boolean} otherAvatarsCollisionsEnabled - Set to <code>true</code> to enable the avatar to collide with other
230  * avatars, <code>false</code> to disable collisions with other avatars.
231  * @property {boolean} characterControllerEnabled - Synonym of <code>collisionsEnabled</code>.
232  * <p class="important">Deprecated: This property is deprecated and will be removed. Use <code>collisionsEnabled</code>
233  * instead.</p>
234  * @property {boolean} useAdvancedMovementControls - Returns and sets the value of the Interface setting, Settings >
235  * Controls > Walking. Note: Setting the value has no effect unless Interface is restarted.
236  * @property {boolean} showPlayArea - Returns and sets the value of the Interface setting, Settings > Controls > Show room
237  * boundaries while teleporting.
238  * <p><strong>Note:</strong> Setting the value has no effect unless Interface is restarted.</p>
239  *
240  * @property {number} yawSpeed=75 - The mouse X sensitivity value in Settings > General. <em>Read-only.</em>
241  * @property {number} pitchSpeed=50 - The mouse Y sensitivity value in Settings > General. <em>Read-only.</em>
242  *
243  * @property {boolean} hmdRollControlEnabled=true - If <code>true</code>, the roll angle of your HMD turns your avatar
244  * while flying.
245  * @property {number} hmdRollControlDeadZone=8 - The amount of HMD roll, in degrees, required before your avatar turns if
246  * <code>hmdRollControlEnabled</code> is enabled.
247  * @property {number} hmdRollControlRate If <code>MyAvatar.hmdRollControlEnabled</code> is true, this value determines the
248  * maximum turn rate of your avatar when rolling your HMD in degrees per second.
249  *
250  * @property {number} userHeight=1.75 - The height of the user in sensor space.
251  * @property {number} userEyeHeight=1.65 - The estimated height of the user's eyes in sensor space. <em>Read-only.</em>
252  *
253  * @property {Uuid} SELF_ID - UUID representing "my avatar". Only use for local-only entities in situations
254  * where MyAvatar.sessionUUID is not available (e.g., if not connected to a domain). Note: Likely to be deprecated.
255  * <em>Read-only.</em>
256  *
257  * @property {number} walkSpeed - The walk speed of your avatar on desktop.
258  * @property {number} sprintSpeed - The sprint (run) speed of your avatar on desktop. VR doesn't have sprinting.
259  * @property {number} vrWalkSpeed - The walk speed of your avatar in VR.
260  * the value.</p>
261  * @property {MyAvatar.SitStandModelType} userRecenterModel - Controls avatar leaning and recentering behavior.
262  * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
263  * @property {boolean} isInSittingState - <code>true</code> if the user wearing the HMD is determined to be sitting;
264  * <code>false</code> if the user wearing the HMD is determined to be standing. This can affect whether the avatar
265  * is allowed to stand, lean or recenter its footing, depending on user preferences.
266  * The property value automatically updates as the user sits or stands. Setting the property value overrides the current
267  * sitting / standing state, which is updated when the user next sits or stands.
268  * @property {boolean} isSitStandStateLocked - <code>true</code> to lock the avatar sitting/standing state, i.e., use this
269  * to disable automatically changing state.
270  * <p class="important">Deprecated: This property is deprecated and will be removed.
271  * See also: <code>getUserRecenterModel</code> and <code>setUserRecenterModel</code>.</p>
272  * @property {boolean} allowTeleporting - <code>true</code> if teleporting is enabled in the Interface settings,
273  * <code>false</code> if it isn't. <em>Read-only.</em>
274  * @property {number} cameraBoomLength - The third-person camera distance. Limited to between 0.5 and 25. Below 0.5 the camera will be put into first-person mode. Changing this property has no effect unless the camera is already in third-person mode. See {@link Camera.mode}.
275  *
276  * @borrows Avatar.getDomainMinScale as getDomainMinScale
277  * @borrows Avatar.getDomainMaxScale as getDomainMaxScale
278  * @borrows Avatar.getEyeHeight as getEyeHeight
279  * @borrows Avatar.getHeight as getHeight
280  * @borrows Avatar.setHandState as setHandState
281  * @borrows Avatar.getHandState as getHandState
282  * @borrows Avatar.setRawJointData as setRawJointData
283  * @borrows Avatar.setJointData as setJointData
284  * @borrows Avatar.setJointRotation as setJointRotation
285  * @borrows Avatar.setJointTranslation as setJointTranslation
286  * @borrows Avatar.clearJointData as clearJointData
287  * @borrows Avatar.isJointDataValid as isJointDataValid
288  * @borrows Avatar.getJointRotation as getJointRotation
289  * @borrows Avatar.getJointTranslation as getJointTranslation
290  * @borrows Avatar.getJointRotations as getJointRotations
291  * @borrows Avatar.getJointTranslations as getJointTranslations
292  * @borrows Avatar.setJointRotations as setJointRotations
293  * @borrows Avatar.setJointTranslations as setJointTranslations
294  * @borrows Avatar.clearJointsData as clearJointsData
295  * @borrows Avatar.getJointIndex as getJointIndex
296  * @borrows Avatar.getJointNames as getJointNames
297  * @borrows Avatar.setBlendshape as setBlendshape
298  * @borrows Avatar.updateAvatarEntity as updateAvatarEntity
299  * @borrows Avatar.clearAvatarEntity as clearAvatarEntity
300  * @borrows Avatar.setForceFaceTrackerConnected as setForceFaceTrackerConnected
301  * @borrows Avatar.setSkeletonModelURL as setSkeletonModelURL
302  * @comment Avatar.getAvatarEntityData as getAvatarEntityData - Don't borrow because implementation is different.
303  * @comment Avatar.setAvatarEntityData as setAvatarEntityData - Don't borrow because implementation is different.
304  * @borrows Avatar.getSensorToWorldMatrix as getSensorToWorldMatrix
305  * @borrows Avatar.getSensorToWorldScale as getSensorToWorldScale
306  * @borrows Avatar.getControllerLeftHandMatrix as getControllerLeftHandMatrix
307  * @borrows Avatar.getControllerRightHandMatrix as getControllerRightHandMatrix
308  * @borrows Avatar.getDataRate as getDataRate
309  * @borrows Avatar.getUpdateRate as getUpdateRate
310  * @borrows Avatar.displayNameChanged as displayNameChanged
311  * @borrows Avatar.sessionDisplayNameChanged as sessionDisplayNameChanged
312  * @borrows Avatar.skeletonModelURLChanged as skeletonModelURLChanged
313  * @borrows Avatar.lookAtSnappingChanged as lookAtSnappingChanged
314  * @borrows Avatar.sessionUUIDChanged as sessionUUIDChanged
315  * @borrows Avatar.sendAvatarDataPacket as sendAvatarDataPacket
316  * @borrows Avatar.sendIdentityPacket as sendIdentityPacket
317  * @borrows Avatar.setSessionUUID as setSessionUUID
318  * @comment Avatar.getAbsoluteJointRotationInObjectFrame as getAbsoluteJointRotationInObjectFrame - Don't borrow because implementation is different.
319  * @comment Avatar.getAbsoluteJointTranslationInObjectFrame as getAbsoluteJointTranslationInObjectFrame - Don't borrow because implementation is different.
320  * @comment Avatar.setAbsoluteJointRotationInObjectFrame as setAbsoluteJointRotationInObjectFrame - Don't borrow because implementation is different.
321  * @comment Avatar.setAbsoluteJointTranslationInObjectFrame as setAbsoluteJointTranslationInObjectFrame - Don't borrow because implementation is different.
322  * @borrows Avatar.getTargetScale as getTargetScale
323  * @borrows Avatar.resetLastSent as resetLastSent
324  */
325  // FIXME: `glm::vec3 position` is not accessible from QML, so this exposes position in a QML-native type
326  Q_PROPERTY(QVector3D qmlPosition READ getQmlPosition)
327  QVector3D getQmlPosition() { auto p = getWorldPosition(); return QVector3D(p.x, p.y, p.z); }
328 
329  Q_PROPERTY(glm::vec3 feetPosition READ getWorldFeetPosition WRITE goToFeetLocation)
330  Q_PROPERTY(bool shouldRenderLocally READ getShouldRenderLocally WRITE setShouldRenderLocally)
331  Q_PROPERTY(glm::vec3 motorVelocity READ getScriptedMotorVelocity WRITE setScriptedMotorVelocity)
332  Q_PROPERTY(float motorTimescale READ getScriptedMotorTimescale WRITE setScriptedMotorTimescale)
333  Q_PROPERTY(QString motorReferenceFrame READ getScriptedMotorFrame WRITE setScriptedMotorFrame)
334  Q_PROPERTY(QString motorMode READ getScriptedMotorMode WRITE setScriptedMotorMode)
335  Q_PROPERTY(QString collisionSoundURL READ getCollisionSoundURL WRITE setCollisionSoundURL)
336  Q_PROPERTY(AudioListenerMode audioListenerMode READ getAudioListenerMode WRITE setAudioListenerMode)
337  Q_PROPERTY(AudioListenerMode audioListenerModeHead READ getAudioListenerModeHead)
338  Q_PROPERTY(AudioListenerMode audioListenerModeCamera READ getAudioListenerModeCamera)
339  Q_PROPERTY(AudioListenerMode audioListenerModeCustom READ getAudioListenerModeCustom)
340  Q_PROPERTY(glm::vec3 customListenPosition READ getCustomListenPosition WRITE setCustomListenPosition)
341  Q_PROPERTY(glm::quat customListenOrientation READ getCustomListenOrientation WRITE setCustomListenOrientation)
342  Q_PROPERTY(float rotationRecenterFilterLength READ getRotationRecenterFilterLength WRITE setRotationRecenterFilterLength)
343  Q_PROPERTY(float rotationThreshold READ getRotationThreshold WRITE setRotationThreshold)
344  Q_PROPERTY(bool enableStepResetRotation READ getEnableStepResetRotation WRITE setEnableStepResetRotation)
345  Q_PROPERTY(bool enableDrawAverageFacing READ getEnableDrawAverageFacing WRITE setEnableDrawAverageFacing)
346  //TODO: make gravity feature work Q_PROPERTY(glm::vec3 gravity READ getGravity WRITE setGravity)
347 
348  Q_PROPERTY(glm::vec3 leftHandPosition READ getLeftHandPosition)
349  Q_PROPERTY(glm::vec3 rightHandPosition READ getRightHandPosition)
350  Q_PROPERTY(glm::vec3 leftHandTipPosition READ getLeftHandTipPosition)
351  Q_PROPERTY(glm::vec3 rightHandTipPosition READ getRightHandTipPosition)
352 
353  Q_PROPERTY(controller::Pose leftHandPose READ getLeftHandPose)
354  Q_PROPERTY(controller::Pose rightHandPose READ getRightHandPose)
355  Q_PROPERTY(controller::Pose leftHandTipPose READ getLeftHandTipPose)
356  Q_PROPERTY(controller::Pose rightHandTipPose READ getRightHandTipPose)
357 
358  Q_PROPERTY(bool isAway READ getIsAway WRITE setAway)
359 
360  Q_PROPERTY(bool centerOfGravityModelEnabled READ getCenterOfGravityModelEnabled WRITE setCenterOfGravityModelEnabled)
361  Q_PROPERTY(bool hmdLeanRecenterEnabled READ getHMDLeanRecenterEnabled WRITE setHMDLeanRecenterEnabled)
362  Q_PROPERTY(bool collisionsEnabled READ getCollisionsEnabled WRITE setCollisionsEnabled)
363  Q_PROPERTY(bool otherAvatarsCollisionsEnabled READ getOtherAvatarsCollisionsEnabled WRITE setOtherAvatarsCollisionsEnabled)
364  Q_PROPERTY(bool characterControllerEnabled READ getCharacterControllerEnabled WRITE setCharacterControllerEnabled)
365  Q_PROPERTY(bool useAdvancedMovementControls READ useAdvancedMovementControls WRITE setUseAdvancedMovementControls)
366  Q_PROPERTY(bool showPlayArea READ getShowPlayArea WRITE setShowPlayArea)
367 
368  Q_PROPERTY(float yawSpeed MEMBER _yawSpeed)
369  Q_PROPERTY(float hmdYawSpeed MEMBER _hmdYawSpeed)
370  Q_PROPERTY(float pitchSpeed MEMBER _pitchSpeed)
371 
372  Q_PROPERTY(bool hmdRollControlEnabled READ getHMDRollControlEnabled WRITE setHMDRollControlEnabled)
373  Q_PROPERTY(float hmdRollControlDeadZone READ getHMDRollControlDeadZone WRITE setHMDRollControlDeadZone)
374  Q_PROPERTY(float hmdRollControlRate READ getHMDRollControlRate WRITE setHMDRollControlRate)
375 
376  Q_PROPERTY(float userHeight READ getUserHeight WRITE setUserHeight)
377  Q_PROPERTY(float userEyeHeight READ getUserEyeHeight)
378 
379  Q_PROPERTY(QUuid SELF_ID READ getSelfID CONSTANT)
380 
381  Q_PROPERTY(float walkSpeed READ getWalkSpeed WRITE setWalkSpeed);
382  Q_PROPERTY(float sprintSpeed READ getSprintSpeed WRITE setSprintSpeed NOTIFY sprintSpeedChanged);
383  Q_PROPERTY(float vrWalkSpeed READ getVrWalkSpeed WRITE setVrWalkSpeed NOTIFY vrWalkSpeedChanged);
384  Q_PROPERTY(bool isInSittingState READ getIsInSittingState WRITE setIsInSittingState);
385  Q_PROPERTY(MyAvatar::SitStandModelType userRecenterModel READ getUserRecenterModel WRITE setUserRecenterModel); // Deprecated
386  Q_PROPERTY(bool isSitStandStateLocked READ getIsSitStandStateLocked WRITE setIsSitStandStateLocked); // Deprecated
387  Q_PROPERTY(MyAvatar::AllowAvatarStandingPreference standingMode READ getAllowAvatarStandingPreference WRITE setAllowAvatarStandingPreference NOTIFY standingModeChanged);
388  Q_PROPERTY(bool allowTeleporting READ getAllowTeleporting)
389  Q_PROPERTY(float cameraBoomLength MEMBER _boomLength)
390 
391  const QString DOMINANT_LEFT_HAND = "left";
392  const QString DOMINANT_RIGHT_HAND = "right";
393  const QString DEFAULT_HMD_AVATAR_ALIGNMENT_TYPE = "head";
394 
395  using Clock = std::chrono::system_clock;
396  using TimePoint = Clock::time_point;
397 
398  const bool DEFAULT_STRAFE_ENABLED = true;
399 public:
400 
401  /*@jsdoc
402  * The <code>DriveKeys</code> API provides constant numeric values that represent different logical keys that drive your
403  * avatar and camera.
404  *
405  * @namespace DriveKeys
406  *
407  * @hifi-interface
408  * @hifi-client-entity
409  * @hifi-avatar
410  *
411  * @property {number} TRANSLATE_X - Move the user's avatar in the direction of its x-axis, if the camera isn't in
412  * independent or mirror modes.
413  * @property {number} TRANSLATE_Y - Move the user's avatar in the direction of its y-axis, if the camera isn't in
414  * independent or mirror modes.
415  * @property {number} TRANSLATE_Z - Move the user's avatar in the direction of its z-axis, if the camera isn't in
416  * independent or mirror modes.
417  * @property {number} YAW - Rotate the user's avatar about its y-axis at a rate proportional to the control value, if the
418  * camera isn't in independent or mirror modes.
419  * @property {number} STEP_TRANSLATE_X - No action.
420  * @property {number} STEP_TRANSLATE_Y - No action.
421  * @property {number} STEP_TRANSLATE_Z - No action.
422  * @property {number} STEP_YAW - Rotate the user's avatar about its y-axis in a step increment, if the camera isn't in
423  * independent or mirror modes.
424  * @property {number} PITCH - Rotate the user's avatar head and attached camera about its negative x-axis (i.e., positive
425  * values pitch down) at a rate proportional to the control value, if the camera isn't in HMD, independent, or mirror
426  * modes.
427  * @property {number} ZOOM - Zoom the camera in or out.
428  * @property {number} DELTA_YAW - Rotate the user's avatar about its y-axis by an amount proportional to the control value,
429  * if the camera isn't in independent or mirror modes.
430  * @property {number} DELTA_PITCH - Rotate the user's avatar head and attached camera about its negative x-axis (i.e.,
431  * positive values pitch down) by an amount proportional to the control value, if the camera isn't in HMD, independent,
432  * or mirror modes.
433  */
434 
435  /*@jsdoc
436  * <p>Logical keys that drive your avatar and camera.</p>
437  * <table>
438  * <thead>
439  * <tr><th>Value</th><th>Description</th></tr>
440  * </thead>
441  * <tbody>
442  * <tr><td><code>{@link DriveKeys|DriveKeys.TRANSLATE_X}</code></td><td>Move the user's avatar in the direction of its
443  * x-axis, if the camera isn't in independent or mirror modes.</td></tr>
444  * <tr><td><code>{@link DriveKeys|DriveKeys.TRANSLATE_Y}</code></td><td>Move the user's avatar in the direction of its
445  * -axis, if the camera isn't in independent or mirror modes.</td></tr>
446  * <tr><td><code>{@link DriveKeys|DriveKeys.TRANSLATE_Z}</code></td><td>Move the user's avatar in the direction of its
447  * z-axis, if the camera isn't in independent or mirror modes.</td></tr>
448  * <tr><td><code>{@link DriveKeys|DriveKeys.YAW}</code></td><td>Rotate the user's avatar about its y-axis at a rate
449  * proportional to the control value, if the camera isn't in independent or mirror modes.</td></tr>
450  * <tr><td><code>{@link DriveKeys|DriveKeys.STEP_TRANSLATE_X}</code></td><td>No action.</td></tr>
451  * <tr><td><code>{@link DriveKeys|DriveKeys.STEP_TRANSLATE_Y}</code></td><td>No action.</td></tr>
452  * <tr><td><code>{@link DriveKeys|DriveKeys.STEP_TRANSLATE_Z}</code></td><td>No action.</td></tr>
453  * <tr><td><code>{@link DriveKeys|DriveKeys.STEP_YAW}</code></td><td>Rotate the user's avatar about its y-axis in a
454  * step increment, if the camera isn't in independent or mirror modes.</td></tr>
455  * <tr><td><code>{@link DriveKeys|DriveKeys.PITCH}</code></td><td>Rotate the user's avatar head and attached camera
456  * about its negative x-axis (i.e., positive values pitch down) at a rate proportional to the control value, if the
457  * camera isn't in HMD, independent, or mirror modes.</td></tr>
458  * <tr><td><code>{@link DriveKeys|DriveKeys.ZOOM}</code></td><td>Zoom the camera in or out.</td></tr>
459  * <tr><td><code>{@link DriveKeys|DriveKeys.DELTA_YAW}</code></td><td>Rotate the user's avatar about its y-axis by an
460  * amount proportional to the control value, if the camera isn't in independent or mirror modes.</td></tr>
461  * <tr><td><code>{@link DriveKeys|DriveKeys.DELTA_PITCH}</code></td><td>Rotate the user's avatar head and attached
462  * camera about its negative x-axis (i.e., positive values pitch down) by an amount proportional to the control
463  * value, if the camera isn't in HMD, independent, or mirror modes.</td></tr>
464  * </tbody>
465  * </table>
466  * @typedef {number} DriveKey
467  */
468  enum DriveKeys {
469  TRANSLATE_X = 0,
470  TRANSLATE_Y,
471  TRANSLATE_Z,
472  YAW,
473  STEP_TRANSLATE_X,
474  STEP_TRANSLATE_Y,
475  STEP_TRANSLATE_Z,
476  STEP_YAW,
477  PITCH,
478  ZOOM,
479  DELTA_YAW,
480  DELTA_PITCH,
481  MAX_DRIVE_KEYS
482  };
483  Q_ENUM(DriveKeys)
484 
485  /*@jsdoc
486  * <p>Specifies different avatar leaning and recentering behaviors.</p>
487  * <p class="important">Deprecated: This type is deprecated and will be removed.</p>
488  * <table>
489  * <thead>
490  * <tr><th>Value</th><th>Name</th><th>Description</th></tr>
491  * </thead>
492  * <tbody>
493  * <tr><td><code>0</code></td><td>ForceSit</td><td>Assumes the user is seated in the real world. Disables avatar
494  * leaning regardless of what the avatar is doing in the virtual world (i.e., avatar always recenters).</td></tr>
495  * <tr><td><code>1</code></td><td>ForceStand</td><td>Assumes the user is standing in the real world. Enables avatar
496  * leaning regardless of what the avatar is doing in the virtual world (i.e., avatar leans, then if leans too far it
497  * recenters).</td></tr>
498  * <tr><td><code>2</code></td><td>Auto</td><td>Interface detects when the user is standing or seated in the real world.
499  * Avatar leaning is disabled when the user is sitting (i.e., avatar always recenters), and avatar leaning is enabled
500  * when the user is standing (i.e., avatar leans, then if leans too far it recenters).</td></tr>
501  * <tr><td><code>3</code></td><td>DisableHMDLean</td><td><p>Both avatar leaning and recentering are disabled regardless of
502  * what the user is doing in the real world and no matter what their avatar is doing in the virtual world. Enables
503  * the avatar to sit on the floor when the user sits on the floor.</p>
504  * <p><strong>Note:</strong> Experimental.</p></td></tr>
505  * </tbody>
506  * </table>
507  * @typedef {number} MyAvatar.SitStandModelType
508  */
509  enum SitStandModelType {
510  ForceSit = 0,
511  ForceStand,
512  Auto,
513  DisableHMDLean,
514  NumSitStandTypes
515  };
516  Q_ENUM(SitStandModelType)
517 
518  /*@jsdoc
519  * <table>
520  * <thead>
521  * <tr><th>Value</th><th>Name</th><th>Description</th></tr>
522  * </thead>
523  * <tbody>
524  * <tr>
525  * <td><code>0</code></td>
526  * <td>Standing</td>
527  * <td>The player's view has no special offset and can crouch unimpeded.</td>
528  * </tr>
529  * <tr>
530  * <td><code>1</code></td>
531  * <td>Seated</td>
532  * <td>The player's view is offset up to a standing position but allows them to lean down. <b>Note: Not implemented yet.</b></td>
533  * </tr>
534  * <tr>
535  * <td><code>2</code></td>
536  * <td>ForcedHeight</td>
537  * <td>The player's view is always kept in a standing position relative to the avatar.</td>
538  * </tr>
539  * </tbody>
540  * </table>
541  * @typedef {number} MyAvatar.AllowAvatarStandingPreference
542  */
543  enum class AllowAvatarStandingPreference : uint {
544  Standing,
545  Seated,
546  ForcedHeight,
547  Count,
548  Default = Standing
549  };
550  Q_ENUM(AllowAvatarStandingPreference)
551 
552  // Note: The option strings in setupPreferences (PreferencesDialog.cpp) must match this order.
553  enum class AllowAvatarLeaningPreference : uint {
554  WhenUserIsStanding,
555  Always,
556  Never,
557  AlwaysNoRecenter, // experimental
558  Count,
559  Default = Always
560  };
561  Q_ENUM(AllowAvatarLeaningPreference)
562 
563  static const std::array<QString, (uint)AllowAvatarStandingPreference::Count> allowAvatarStandingPreferenceStrings;
564  static const std::array<QString, (uint)AllowAvatarLeaningPreference::Count> allowAvatarLeaningPreferenceStrings;
565 
566  explicit MyAvatar(QThread* thread);
567  virtual ~MyAvatar();
568 
569  void instantiableAvatar() override {};
570  static void registerMetaTypes(ScriptEnginePointer engine);
571  void registerProperties(ScriptEnginePointer engine);
572 
573  AudioListenerMode getAudioListenerModeHead() const { return FROM_HEAD; }
574  AudioListenerMode getAudioListenerModeCamera() const { return FROM_CAMERA; }
575  AudioListenerMode getAudioListenerModeCustom() const { return CUSTOM; }
576 
577  void reset(bool andRecenter = false, bool andReload = true, bool andHead = true);
578 
579  void setCollisionWithOtherAvatarsFlags() override;
580 
581  /*@jsdoc
582  * Resets the sensor positioning of your HMD (if in use) and recenters your avatar body and head.
583  * @function MyAvatar.resetSensorsAndBody
584  */
585  Q_INVOKABLE void resetSensorsAndBody();
586 
587  /*@jsdoc
588  * Moves and orients the avatar, such that it is directly underneath the HMD, with toes pointed forward in the direction of
589  * the HMD.
590  * @function MyAvatar.centerBody
591  */
592  Q_INVOKABLE void centerBody(); // thread-safe
593 
594 
595  /*@jsdoc
596  * Clears inverse kinematics joint limit history.
597  * <p>The internal inverse-kinematics system maintains a record of which joints are "locked". Sometimes it is useful to
598  * forget this history to prevent contorted joints, e.g., after finishing with an override animation.</p>
599  * @function MyAvatar.clearIKJointLimitHistory
600  */
601  Q_INVOKABLE void clearIKJointLimitHistory(); // thread-safe
602 
603  void update(float deltaTime);
604  virtual void postUpdate(float deltaTime, const render::ScenePointer& scene) override;
605  void preDisplaySide(const RenderArgs* renderArgs);
606 
607  const glm::mat4& getHMDSensorMatrix() const { return _hmdSensorMatrix; }
608  const glm::vec3& getHMDSensorPosition() const { return _hmdSensorPosition; }
609  const glm::quat& getHMDSensorOrientation() const { return _hmdSensorOrientation; }
610 
611  /*@jsdoc
612  * Gets the avatar orientation. Suitable for use in QML.
613  * @function MyAvatar.setOrientationVar
614  * @param {object} newOrientationVar - The avatar's orientation.
615  */
616  Q_INVOKABLE void setOrientationVar(const QVariant& newOrientationVar);
617 
618  /*@jsdoc
619  * Gets the avatar orientation. Suitable for use in QML.
620  * @function MyAvatar.getOrientationVar
621  * @returns {object} The avatar's orientation.
622  */
623  Q_INVOKABLE QVariant getOrientationVar() const;
624 
625  // A method intended to be overriden by MyAvatar for polling orientation for network transmission.
626  glm::quat getOrientationOutbound() const override;
627 
628  // Pass a recent sample of the HMD to the avatar.
629  // This can also update the avatar's position to follow the HMD
630  // as it moves through the world.
631  void updateFromHMDSensorMatrix(const glm::mat4& hmdSensorMatrix);
632 
633  // compute the hip to hand average azimuth.
634  glm::vec2 computeHandAzimuth() const;
635 
636  // read the location of a hand controller and save the transform
637  void updateJointFromController(controller::Action poseKey, ThreadSafeValueCache<glm::mat4>& matrixCache);
638 
639  // best called at end of main loop, just before rendering.
640  // update sensor to world matrix from current body position and hmd sensor.
641  // This is so the correct camera can be used for rendering.
642  void updateSensorToWorldMatrix();
643 
644  void setRealWorldFieldOfView(float realWorldFov) { _realWorldFieldOfView.set(realWorldFov); }
645 
646  /*@jsdoc
647  * Gets the position in world coordinates of the point directly between your avatar's eyes assuming your avatar was in its
648  * default pose. This is a reference position; it does not change as your avatar's head moves relative to the avatar
649  * position.
650  * @function MyAvatar.getDefaultEyePosition
651  * @returns {Vec3} Default position between your avatar's eyes in world coordinates.
652  * @example <caption>Report your avatar's default eye position.</caption>
653  * var defaultEyePosition = MyAvatar.getDefaultEyePosition();
654  * print(JSON.stringify(defaultEyePosition));
655  */
656  Q_INVOKABLE glm::vec3 getDefaultEyePosition() const;
657 
658  float getRealWorldFieldOfView() { return _realWorldFieldOfView.get(); }
659 
660  /*@jsdoc
661  * Overrides the default avatar animations.
662  * <p>The avatar animation system includes a set of default animations along with rules for how those animations are blended
663  * together with procedural data (such as look at vectors, hand sensors etc.). <code>overrideAnimation()</code> is used to
664  * completely override all motion from the default animation system (including inverse kinematics for hand and head
665  * controllers) and play a set of specified animations. To end these animations and restore the default animations, use
666  * {@link MyAvatar.restoreAnimation}.</p>
667  * <p>Note: When using pre-built animation data, it's critical that the joint orientation of the source animation and target
668  * rig are equivalent, since the animation data applies absolute values onto the joints. If the orientations are different,
669  * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see
670  * <a href="https://docs.overte.org/create/avatars/avatar-standards.html">Avatar Standards</a>.</p>
671  * @function MyAvatar.overrideAnimation
672  * @param {string} url - The URL to the animation file. Animation files may be in glTF or FBX format, but only need to
673  * contain the avatar skeleton and animation data. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs
674  * respectively).
675  * <p><strong>Warning:</strong> glTF animations currently do not always animate correctly.</p>
676  * @param {number} fps - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed.
677  * @param {boolean} loop - <code>true</code> if the animation should loop, <code>false</code> if it shouldn't.
678  * @param {number} firstFrame - The frame to start the animation at.
679  * @param {number} lastFrame - The frame to end the animation at.
680  * @example <caption> Play a clapping animation on your avatar for three seconds. </caption>
681  * var ANIM_URL = "https://apidocs.overte.org/examples/ClapHands_Standing.fbx";
682  * MyAvatar.overrideAnimation(ANIM_URL, 30, true, 0, 53);
683  * Script.setTimeout(function () {
684  * MyAvatar.restoreAnimation();
685  * MyAvatar.clearIKJointLimitHistory();
686  * }, 3000);
687  */
688  Q_INVOKABLE void overrideAnimation(const QString& url, float fps, bool loop, float firstFrame, float lastFrame);
689 
690  /*@jsdoc
691  * Overrides the default hand poses that are triggered with controller buttons.
692  * Use {@link MyAvatar.restoreHandAnimation} to restore the default poses.
693  * @function MyAvatar.overrideHandAnimation
694  * @param isLeft {boolean} <code>true</code> to override the left hand, <code>false</code> to override the right hand.
695  * @param {string} url - The URL of the animation file. Animation files need to be in glTF or FBX format, but only need to
696  * contain the avatar skeleton and animation data. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs
697  * respectively).
698  * <p><strong>Warning:</strong> glTF animations currently do not always animate correctly.</p>
699  * @param {number} fps - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed.
700  * @param {boolean} loop - <code>true</code> if the animation should loop, <code>false</code> if it shouldn't.
701  * @param {number} firstFrame - The frame to start the animation at.
702  * @param {number} lastFrame - The frame to end the animation at.
703  * @example <caption> Override left hand animation for three seconds.</caption>
704  * var ANIM_URL = "https://apidocs.overte.org/examples/ClapHands_Standing.fbx";
705  * MyAvatar.overrideHandAnimation(isLeft, ANIM_URL, 30, true, 0, 53);
706  * Script.setTimeout(function () {
707  * MyAvatar.restoreHandAnimation();
708  * }, 3000);
709  */
710  Q_INVOKABLE void overrideHandAnimation(bool isLeft, const QString& url, float fps, bool loop, float firstFrame, float lastFrame);
711 
712  /*@jsdoc
713  * Restores the default animations.
714  * <p>The avatar animation system includes a set of default animations along with rules for how those animations are blended
715  * together with procedural data (such as look at vectors, hand sensors etc.). Playing your own custom animations will
716  * override the default animations. <code>restoreAnimation()</code> is used to restore all motion from the default
717  * animation system including inverse kinematics for hand and head controllers. If you aren't currently playing an override
718  * animation, this function has no effect.</p>
719  * @function MyAvatar.restoreAnimation
720  * @example <caption> Play a clapping animation on your avatar for three seconds. </caption>
721  * var ANIM_URL = "https://apidocs.overte.org/examples/ClapHands_Standing.fbx";
722  * MyAvatar.overrideAnimation(ANIM_URL, 30, true, 0, 53);
723  * Script.setTimeout(function () {
724  * MyAvatar.restoreAnimation();
725  * }, 3000);
726  */
727  Q_INVOKABLE void restoreAnimation();
728 
729  /*@jsdoc
730  * Restores the default hand animation state machine that is driven by the state machine in the avatar-animation JSON.
731  * <p>The avatar animation system includes a set of default animations along with rules for how those animations are blended
732  * together with procedural data (such as look at vectors, hand sensors etc.). Playing your own custom animations will
733  * override the default animations. <code>restoreHandAnimation()</code> is used to restore the default hand poses.
734  * If you aren't currently playing an override hand animation, this function has no effect.</p>
735  * @function MyAvatar.restoreHandAnimation
736  * @param isLeft {boolean} Set to true if using the left hand
737  * @example <caption> Override left hand animation for three seconds. </caption>
738  * var ANIM_URL = "https://apidocs.overte.org/examples/ClapHands_Standing.fbx";
739  * MyAvatar.overrideHandAnimation(isLeft, ANIM_URL, 30, true, 0, 53);
740  * Script.setTimeout(function () {
741  * MyAvatar.restoreHandAnimation();
742  * }, 3000);
743  */
744  Q_INVOKABLE void restoreHandAnimation(bool isLeft);
745 
746  /*@jsdoc
747  * Gets the current animation roles.
748  * <p>Each avatar has an avatar-animation.json file that defines which animations are used and how they are blended together
749  * with procedural data (such as look at vectors, hand sensors etc.). Each animation specified in the avatar-animation.json
750  * file is known as an animation role. Animation roles map to easily understandable actions that the avatar can perform,
751  * such as <code>"idleStand"</code>, <code>"idleTalk"</code>, or <code>"walkFwd"</code>. <code>getAnimationRoles()</code>
752  * is used get the list of animation roles defined in the avatar-animation.json.</p>
753  * @function MyAvatar.getAnimationRoles
754  * @returns {string[]} Array of role strings.
755  * @example <caption>Print the list of animation roles defined in the avatar's avatar-animation.json file to the debug log.</caption>
756  * var roles = MyAvatar.getAnimationRoles();
757  * print("Animation Roles:");
758  * for (var i = 0; i < roles.length; i++) {
759  * print(roles[i]);
760  * }
761  */
762  Q_INVOKABLE QStringList getAnimationRoles();
763 
764  /*@jsdoc
765  * Overrides a specific animation role.
766  * <p>Each avatar has an avatar-animation.json file that defines a set of animation roles. Animation roles map to easily
767  * understandable actions that the avatar can perform, such as <code>"idleStand"</code>, <code>"idleTalk"</code>, or
768  * <code>"walkFwd"</code>. To get the full list of roles, use {@ link MyAvatar.getAnimationRoles}.
769  * For each role, the avatar-animation.json defines when the animation is used, the animation clip (glTF or FBX) used, and
770  * how animations are blended together with procedural data (such as look at vectors, hand sensors etc.).
771  * <code>overrideRoleAnimation()</code> is used to change the animation clip (glTF or FBX) associated with a specified
772  * animation role. To end the role animation and restore the default, use {@link MyAvatar.restoreRoleAnimation}.</p>
773  * <p>Note: Hand roles only affect the hand. Other "main" roles, like "idleStand", "idleTalk", and "takeoffStand", are full
774  * body.</p>
775  * <p>Note: When using pre-built animation data, it's critical that the joint orientation of the source animation and target
776  * rig are equivalent, since the animation data applies absolute values onto the joints. If the orientations are different,
777  * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see
778  * <a href="https://docs.overte.org/create/avatars/avatar-standards.html">Avatar Standards</a>.
779  * @function MyAvatar.overrideRoleAnimation
780  * @param {string} role - The animation role to override
781  * @param {string} url - The URL to the animation file. Animation files need to be in glTF or FBX format, but only need to
782  * contain the avatar skeleton and animation data. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs
783  * respectively).
784  * <p><strong>Warning:</strong> glTF animations currently do not always animate correctly.</p>
785  * @param {number} fps - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed.
786  * @param {boolean} loop - <code>true</code> if the animation should loop, <code>false</code> if it shouldn't.
787  * @param {number} firstFrame - The frame the animation should start at.
788  * @param {number} lastFrame - The frame the animation should end at.
789  * @example <caption>The default avatar-animation.json defines an "idleStand" animation role. This role specifies that when the avatar is not moving,
790  * an animation clip of the avatar idling with hands hanging at its side will be used. It also specifies that when the avatar moves, the animation
791  * will smoothly blend to the walking animation used by the "walkFwd" animation role.
792  * In this example, the "idleStand" role animation clip has been replaced with a clapping animation clip. Now instead of standing with its arms
793  * hanging at its sides when it is not moving, the avatar will stand and clap its hands. Note that just as it did before, as soon as the avatar
794  * starts to move, the animation will smoothly blend into the walk animation used by the "walkFwd" animation role.</caption>
795  * // An animation of the avatar clapping its hands while standing. Restore default after 30s.
796  * var ANIM_URL = "https://apidocs.overte.org/examples/ClapHands_Standing.fbx";
797  * MyAvatar.overrideRoleAnimation("idleStand", ANIM_URL, 30, true, 0, 53);
798  * Script.setTimeout(function () {
799  * MyAvatar.restoreRoleAnimation();
800  * }, 30000);
801  */
802  Q_INVOKABLE void overrideRoleAnimation(const QString& role, const QString& url, float fps, bool loop, float firstFrame, float lastFrame);
803 
804  /*@jsdoc
805  * Restores a default role animation.
806  * <p>Each avatar has an avatar-animation.json file that defines a set of animation roles. Animation roles map to easily
807  * understandable actions that the avatar can perform, such as <code>"idleStand"</code>, <code>"idleTalk"</code>, or
808  * <code>"walkFwd"</code>. To get the full list of roles, use {@link MyAvatar.getAnimationRoles}. For each role,
809  * the avatar-animation.json defines when the animation is used, the animation clip (glTF or FBX) used, and how animations
810  * are blended together with procedural data (such as look-at vectors, hand sensors etc.). You can change the animation
811  * clip (glTF or FBX) associated with a specified animation role using {@link MyAvatar.overrideRoleAnimation}.
812  * <code>restoreRoleAnimation()</code> is used to restore a specified animation role's default animation clip. If you have
813  * not specified an override animation for the specified role, this function has no effect.
814  * @function MyAvatar.restoreRoleAnimation
815  * @param role {string} The animation role clip to restore.
816  */
817  Q_INVOKABLE void restoreRoleAnimation(const QString& role);
818 
819  // Adds handler(animStateDictionaryIn) => animStateDictionaryOut, which will be invoked just before each animGraph state update.
820  // The handler will be called with an animStateDictionaryIn that has all those properties specified by the (possibly empty)
821  // propertiesList argument. However for debugging, if the properties argument is null, all internal animGraph state is provided.
822  // The animStateDictionaryOut can be a different object than animStateDictionaryIn. Any properties set in animStateDictionaryOut
823  // will override those of the internal animation machinery.
824  // The animStateDictionaryIn may be shared among multiple handlers, and thus may contain additional properties specified when
825  // adding one of the other handlers. While any handler may change a value in animStateDictionaryIn (or supply different values in animStateDictionaryOut)
826  // a handler must not remove properties from animStateDictionaryIn, nor change property values that it does not intend to change.
827  // It is not specified in what order multiple handlers are called.
828  /*@jsdoc
829  * Adds an animation state handler function that is invoked just before each animation graph update. More than one
830  * animation state handler function may be added by calling <code>addAnimationStateHandler</code> multiple times. It is not
831  * specified in what order multiple handlers are called.
832  * <p>The animation state handler function is called with an {@link MyAvatar.AnimStateDictionary|AnimStateDictionary}
833  * "<code>animStateDictionaryIn</code>" parameter and is expected to return an
834  * {@link MyAvatar.AnimStateDictionary|AnimStateDictionary} "<code>animStateDictionaryOut</code>" object. The
835  * <code>animStateDictionaryOut</code> object can be the same object as <code>animStateDictionaryIn</code>, or it can be a
836  * different object. The <code>animStateDictionaryIn</code> may be shared among multiple handlers and thus may contain
837  * additional properties specified when adding the different handlers.</p>
838  * <p>A handler may change a value from <code>animStateDictionaryIn</code> or add different values in the
839  * <code>animStateDictionaryOut</code> returned. Any property values set in <code>animStateDictionaryOut</code> will
840  * override those of the internal animation machinery.</p>
841  * @function MyAvatar.addAnimationStateHandler
842  * @param {function} handler - The animation state handler function to add.
843  * @param {Array<string>|null} propertiesList - The list of {@link MyAvatar.AnimStateDictionary|AnimStateDictionary}
844  * properties that should be included in the parameter that the handler function is called with. If <code>null</code>
845  * then all properties are included in the call parameter.
846  * @returns {number} The ID of the animation state handler function if successfully added, <code>undefined</code> if not.
847  * @example <caption>Log all the animation state dictionary parameters for a short while.</caption>
848  * function animStateHandler(dictionary) {
849  * print("Anim state dictionary: " + JSON.stringify(dictionary));
850  * }
851  *
852  * var handler = MyAvatar.addAnimationStateHandler(animStateHandler, null);
853  *
854  * Script.setTimeout(function () {
855  * MyAvatar.removeAnimationStateHandler(handler);
856  * }, 100);
857  */
858  Q_INVOKABLE ScriptValue addAnimationStateHandler(const ScriptValue& handler, const ScriptValue& propertiesList) { return _skeletonModel->getRig().addAnimationStateHandler(handler, propertiesList); }
859 
860  /*@jsdoc
861  * Removes an animation state handler function.
862  * @function MyAvatar.removeAnimationStateHandler
863  * @param {number} handler - The ID of the animation state handler function to remove.
864  */
865  // Removes a handler previously added by addAnimationStateHandler.
866  Q_INVOKABLE void removeAnimationStateHandler(const ScriptValue& handler) { _skeletonModel->getRig().removeAnimationStateHandler(handler); }
867 
868 
869  /*@jsdoc
870  * Gets whether you do snap turns in HMD mode.
871  * @function MyAvatar.getSnapTurn
872  * @returns {boolean} <code>true</code> if you do snap turns in HMD mode; <code>false</code> if you do smooth turns in HMD
873  * mode.
874  */
875  Q_INVOKABLE bool getSnapTurn() const { return _useSnapTurn; }
876 
877  /*@jsdoc
878  * Sets whether you do snap turns or smooth turns in HMD mode.
879  * @function MyAvatar.setSnapTurn
880  * @param {boolean} on - <code>true</code> to do snap turns in HMD mode; <code>false</code> to do smooth turns in HMD mode.
881  */
882  Q_INVOKABLE void setSnapTurn(bool on) { _useSnapTurn = on; }
883 
884  /*@jsdoc
885  * Gets whether your avatar hovers when its feet are not on the ground.
886  * @function MyAvatar.hoverWhenUnsupported
887  * @returns {boolean} <code>true</code> if your avatar hovers when its feet are not on the ground, <code>false</code> if it
888  * falls.
889  */
890  // FIXME: Should be named, getHoverWhenUnsupported().
891  Q_INVOKABLE bool hoverWhenUnsupported() const { return _hoverWhenUnsupported; }
892 
893  /*@jsdoc
894  * Sets whether your avatar hovers when its feet are not on the ground.
895  * @function MyAvatar.setHoverWhenUnsupported
896  * @param {boolean} hover - <code>true</code> if your avatar hovers when its feet are not on the ground, <code>false</code>
897  * if it falls.
898  */
899  Q_INVOKABLE void setHoverWhenUnsupported(bool on) { _hoverWhenUnsupported = on; }
900 
901  /*@jsdoc
902  * Sets the avatar's dominant hand.
903  * @function MyAvatar.setDominantHand
904  * @param {string} hand - The dominant hand: <code>"left"</code> for the left hand or <code>"right"</code> for the right
905  * hand. Any other value has no effect.
906  */
907  Q_INVOKABLE void setDominantHand(const QString& hand);
908 
909  /*@jsdoc
910  * Gets the avatar's dominant hand.
911  * @function MyAvatar.getDominantHand
912  * @returns {string} <code>"left"</code> for the left hand, <code>"right"</code> for the right hand.
913  */
914  Q_INVOKABLE QString getDominantHand() const;
915 
916  /*@jsdoc
917  * Sets whether strafing is enabled.
918  * @function MyAvatar.setStrafeEnabled
919  * @param {boolean} enabled - <code>true</code> if strafing is enabled, <code>false</code> if it isn't.
920  */
921  Q_INVOKABLE void setStrafeEnabled(bool enabled);
922 
923  /*@jsdoc
924  * Gets whether strafing is enabled.
925  * @function MyAvatar.getStrafeEnabled
926  * @returns {boolean} <code>true</code> if strafing is enabled, <code>false</code> if it isn't.
927  */
928  Q_INVOKABLE bool getStrafeEnabled() const;
929 
930  /*@jsdoc
931  * Sets the HMD alignment relative to your avatar.
932  * @function MyAvatar.setHmdAvatarAlignmentType
933  * @param {string} type - <code>"head"</code> to align your head and your avatar's head, <code>"eyes"</code> to align your
934  * eyes and your avatar's eyes.
935  */
936  Q_INVOKABLE void setHmdAvatarAlignmentType(const QString& type);
937 
938  /*@jsdoc
939  * Gets the HMD alignment relative to your avatar.
940  * @function MyAvatar.getHmdAvatarAlignmentType
941  * @returns {string} <code>"head"</code> if aligning your head and your avatar's head, <code>"eyes"</code> if aligning your
942  * eyes and your avatar's eyes.
943  */
944  Q_INVOKABLE QString getHmdAvatarAlignmentType() const;
945 
946  /*@jsdoc
947  * Sets whether the avatar's hips are balanced over the feet or positioned under the head.
948  * @function MyAvatar.setCenterOfGravityModelEnabled
949  * @param {boolean} enabled - <code>true</code> to balance the hips over the feet, <code>false</code> to position the hips
950  * under the head.
951  */
952  Q_INVOKABLE void setCenterOfGravityModelEnabled(bool value) { _centerOfGravityModelEnabled = value; }
953 
954  /*@jsdoc
955  * Gets whether the avatar hips are being balanced over the feet or placed under the head.
956  * @function MyAvatar.getCenterOfGravityModelEnabled
957  * @returns {boolean} <code>true</code> if the hips are being balanced over the feet, <code>false</code> if the hips are
958  * being positioned under the head.
959  */
960  Q_INVOKABLE bool getCenterOfGravityModelEnabled() const { return _centerOfGravityModelEnabled; }
961 
962  /*@jsdoc
963  * Sets whether the avatar's position updates to recenter the avatar under the head. In room-scale VR, recentering
964  * causes your avatar to follow your HMD as you walk around the room. Disabling recentering is useful if you want to pin
965  * the avatar to a fixed position.
966  * @function MyAvatar.setHMDLeanRecenterEnabled
967  * @param {boolean} enabled - <code>true</code> to recenter the avatar under the head as it moves, <code>false</code> to
968  * disable recentering.
969  */
970  Q_INVOKABLE void setHMDLeanRecenterEnabled(bool value) { _hmdLeanRecenterEnabled = value; }
971 
972  /*@jsdoc
973  * Gets whether the avatar's position updates to recenter the avatar under the head. In room-scale VR, recentering
974  * causes your avatar to follow your HMD as you walk around the room.
975  * @function MyAvatar.getHMDLeanRecenterEnabled
976  * @returns {boolean} <code>true</code> if recentering is enabled, <code>false</code> if not.
977  */
978  Q_INVOKABLE bool getHMDLeanRecenterEnabled() const { return _hmdLeanRecenterEnabled; }
979 
980  /*@jsdoc
981  * Requests that the hand touch effect is disabled for your avatar. Any resulting change in the status of the hand touch
982  * effect will be signaled by {@link MyAvatar.shouldDisableHandTouchChanged}.
983  * <p>The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that
984  * it is really touching that object.</p>
985  * @function MyAvatar.requestEnableHandTouch
986  */
987  Q_INVOKABLE void requestEnableHandTouch();
988 
989  /*@jsdoc
990  * Requests that the hand touch effect is enabled for your avatar. Any resulting change in the status of the hand touch
991  * effect will be signaled by {@link MyAvatar.shouldDisableHandTouchChanged}.
992  * <p>The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that
993  * it is really touching that object.</p>
994  * @function MyAvatar.requestDisableHandTouch
995  */
996  Q_INVOKABLE void requestDisableHandTouch();
997 
998  /*@jsdoc
999  * Disables the hand touch effect on a specific entity.
1000  * <p>The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that
1001  * it is really touching that object.</p>
1002  * @function MyAvatar.disableHandTouchForID
1003  * @param {Uuid} entityID - The entity that the hand touch effect will be disabled for.
1004  */
1005  Q_INVOKABLE void disableHandTouchForID(const QUuid& entityID);
1006 
1007  /*@jsdoc
1008  * Enables the hand touch effect on a specific entity.
1009  * <p>The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that
1010  * it is really touching that object.</p>
1011  * @function MyAvatar.enableHandTouchForID
1012  * @param {Uuid} entityID - The entity that the hand touch effect will be enabled for.
1013  */
1014  Q_INVOKABLE void enableHandTouchForID(const QUuid& entityID);
1015 
1016  bool useAdvancedMovementControls() const { return _useAdvancedMovementControls.get(); }
1017  void setUseAdvancedMovementControls(bool useAdvancedMovementControls)
1018  { _useAdvancedMovementControls.set(useAdvancedMovementControls); }
1019 
1020  bool getAllowTeleporting() { return _allowTeleportingSetting.get(); }
1021  void setAllowTeleporting(bool allowTeleporting) { _allowTeleportingSetting.set(allowTeleporting); }
1022 
1023  bool getShowPlayArea() const { return _showPlayArea.get(); }
1024  void setShowPlayArea(bool showPlayArea) { _showPlayArea.set(showPlayArea); }
1025 
1026  void setHMDRollControlEnabled(bool value) { _hmdRollControlEnabled = value; }
1027  bool getHMDRollControlEnabled() const { return _hmdRollControlEnabled; }
1028  void setHMDRollControlDeadZone(float value) { _hmdRollControlDeadZone = value; }
1029  float getHMDRollControlDeadZone() const { return _hmdRollControlDeadZone; }
1030  void setHMDRollControlRate(float value) { _hmdRollControlRate = value; }
1031  float getHMDRollControlRate() const { return _hmdRollControlRate; }
1032 
1033  // get/set avatar data
1034  void resizeAvatarEntitySettingHandles(uint32_t maxIndex);
1035  void saveData();
1036  void saveAvatarEntityDataToSettings();
1037  void loadData();
1038  void loadAvatarEntityDataFromSettings();
1039 
1040  // Set what driving keys are being pressed to control thrust levels
1041  void clearDriveKeys();
1042  void setDriveKey(DriveKeys key, float val);
1043  void setSprintMode(bool sprint);
1044  float getDriveKey(DriveKeys key) const;
1045 
1046  /*@jsdoc
1047  * Gets the value of a drive key, regardless of whether it is disabled.
1048  * @function MyAvatar.getRawDriveKey
1049  * @param {DriveKey} key - The drive key.
1050  * @returns {number} The value of the drive key.
1051  */
1052  Q_INVOKABLE float getRawDriveKey(DriveKeys key) const;
1053 
1054  void relayDriveKeysToCharacterController();
1055 
1056  /*@jsdoc
1057  * Disables the action associated with a drive key.
1058  * @function MyAvatar.disableDriveKey
1059  * @param {DriveKey} key - The drive key to disable.
1060  * @example <caption>Disable rotating your avatar using the keyboard for a couple of seconds.</caption>
1061  * print("Disable");
1062  * MyAvatar.disableDriveKey(DriveKeys.YAW);
1063  * Script.setTimeout(function () {
1064  * print("Enable");
1065  * MyAvatar.enableDriveKey(YAW);
1066  * }, 5000);
1067  */
1068  Q_INVOKABLE void disableDriveKey(DriveKeys key);
1069 
1070  /*@jsdoc
1071  * Enables the action associated with a drive key. The action may have been disabled with
1072  * {@link MyAvatar.disableDriveKey|disableDriveKey}.
1073  * @function MyAvatar.enableDriveKey
1074  * @param {DriveKey} key - The drive key to enable.
1075  */
1076  Q_INVOKABLE void enableDriveKey(DriveKeys key);
1077 
1078  /*@jsdoc
1079  * Checks whether a drive key is disabled.
1080  * @function MyAvatar.isDriveKeyDisabled
1081  * @param {DriveKey} key - The drive key to check.
1082  * @returns {boolean} <code>true</code> if the drive key is disabled, <code>false</code> if it isn't.
1083  */
1084  Q_INVOKABLE bool isDriveKeyDisabled(DriveKeys key) const;
1085 
1086 
1087  /*@jsdoc
1088  * Recenter the avatar in the vertical direction, if <code>{@link MyAvatar|MyAvatar.hmdLeanRecenterEnabled}</code> is
1089  * <code>false</code>.
1090  * @function MyAvatar.triggerVerticalRecenter
1091  */
1092  Q_INVOKABLE void triggerVerticalRecenter();
1093 
1094  /*@jsdoc
1095  * Recenter the avatar in the horizontal direction, if <code>{@link MyAvatar|MyAvatar.hmdLeanRecenterEnabled}</code> is
1096  * <code>false</code>.
1097  * @function MyAvatar.triggerHorizontalRecenter
1098  */
1099  Q_INVOKABLE void triggerHorizontalRecenter();
1100 
1101  /*@jsdoc
1102  * Recenter the avatar's rotation, if <code>{@link MyAvatar|MyAvatar.hmdLeanRecenterEnabled}</code> is <code>false</code>.
1103  * @function MyAvatar.triggerRotationRecenter
1104  */
1105  Q_INVOKABLE void triggerRotationRecenter();
1106 
1107  /*@jsdoc
1108  * Gets whether the avatar is configured to keep its center of gravity under its head.
1109  * @function MyAvatar.isRecenteringHorizontally
1110  * @returns {boolean} <code>true</code> if the avatar is keeping its center of gravity under its head position,
1111  * <code>false</code> if not.
1112  */
1113  Q_INVOKABLE bool isRecenteringHorizontally() const;
1114 
1115  eyeContactTarget getEyeContactTarget();
1116 
1117  const MyHead* getMyHead() const;
1118 
1119  /*@jsdoc
1120  * Gets the current position of the avatar's "Head" joint.
1121  * @function MyAvatar.getHeadPosition
1122  * @returns {Vec3} The current position of the avatar's "Head" joint.
1123  * @example <caption>Report the current position of your avatar's head.</caption>
1124  * print(JSON.stringify(MyAvatar.getHeadPosition()));
1125  */
1126  Q_INVOKABLE glm::vec3 getHeadPosition() const { return getHead()->getPosition(); }
1127 
1128  /*@jsdoc
1129  * Gets the yaw of the avatar's head relative to its body.
1130  * @function MyAvatar.getHeadFinalYaw
1131  * @returns {number} The yaw of the avatar's head, in degrees.
1132  */
1133  Q_INVOKABLE float getHeadFinalYaw() const { return getHead()->getFinalYaw(); }
1134 
1135  /*@jsdoc
1136  * Gets the roll of the avatar's head relative to its body.
1137  * @function MyAvatar.getHeadFinalRoll
1138  * @returns {number} The roll of the avatar's head, in degrees.
1139  */
1140  Q_INVOKABLE float getHeadFinalRoll() const { return getHead()->getFinalRoll(); }
1141 
1142  /*@jsdoc
1143  * Gets the pitch of the avatar's head relative to its body.
1144  * @function MyAvatar.getHeadFinalPitch
1145  * @returns {number} The pitch of the avatar's head, in degrees.
1146  */
1147  Q_INVOKABLE float getHeadFinalPitch() const { return getHead()->getFinalPitch(); }
1148 
1149  /*@jsdoc
1150  * If a face tracker is connected and being used, gets the estimated pitch of the user's head scaled. This is scale such
1151  * that the avatar looks at the edge of the view frustum when the user looks at the edge of their screen.
1152  * @function MyAvatar.getHeadDeltaPitch
1153  * @returns {number} The pitch that the avatar's head should be if a face tracker is connected and being used, otherwise
1154  * <code>0</code>, in degrees.
1155  */
1156  Q_INVOKABLE float getHeadDeltaPitch() const { return getHead()->getDeltaPitch(); }
1157 
1158  /*@jsdoc
1159  * Gets the current position of the point directly between the avatar's eyes.
1160  * @function MyAvatar.getEyePosition
1161  * @returns {Vec3} The current position of the point directly between the avatar's eyes.
1162  * @example <caption>Report your avatar's current eye position.</caption>
1163  * var eyePosition = MyAvatar.getEyePosition();
1164  * print(JSON.stringify(eyePosition));
1165  */
1166  Q_INVOKABLE glm::vec3 getEyePosition() const { return getHead()->getEyePosition(); }
1167 
1168  /*@jsdoc
1169  * Gets the position of the avatar your avatar is currently looking at.
1170  * @function MyAvatar.getTargetAvatarPosition
1171  * @returns {Vec3} The position of the avatar beeing looked at.
1172  * @example <caption>Report the position of the avatar you're currently looking at.</caption>
1173  * print(JSON.stringify(MyAvatar.getTargetAvatarPosition()));
1174  */
1175  // FIXME: If not looking at an avatar, the most recently looked-at position is returned. This should be fixed to return
1176  // undefined or {NaN, NaN, NaN} or similar.
1177  Q_INVOKABLE glm::vec3 getTargetAvatarPosition() const { return _targetAvatarPosition; }
1178 
1179  /*@jsdoc
1180  * Gets information on the avatar your avatar is currently looking at.
1181  * @function MyAvatar.getTargetAvatar
1182  * @returns {ScriptAvatar} Information on the avatar being looked at, <code>null</code> if no avatar is being looked at.
1183  */
1184  Q_INVOKABLE ScriptAvatarData* getTargetAvatar() const;
1185 
1186 
1187  /*@jsdoc
1188  * Gets the position of the avatar's left hand, relative to the avatar, as positioned by a hand controller (e.g., Oculus
1189  * Touch or Vive).
1190  * <p>Note: The Leap Motion isn't part of the hand controller input system. (Instead, it manipulates the avatar's joints
1191  * for hand animation.)</p>
1192  * @function MyAvatar.getLeftHandPosition
1193  * @returns {Vec3} The position of the left hand in avatar coordinates if positioned by a hand controller, otherwise
1194  * <code>{@link Vec3(0)|Vec3.ZERO}</code>.
1195  * @example <caption>Report the position of your left hand relative to your avatar.</caption>
1196  * print(JSON.stringify(MyAvatar.getLeftHandPosition()));
1197  */
1198  Q_INVOKABLE glm::vec3 getLeftHandPosition() const;
1199 
1200  /*@jsdoc
1201  * Gets the position of the avatar's right hand, relative to the avatar, as positioned by a hand controller (e.g., Oculus
1202  * Touch or Vive).
1203  * <p>Note: The Leap Motion isn't part of the hand controller input system. (Instead, it manipulates the avatar's joints
1204  * for hand animation.)</p>
1205  * @function MyAvatar.getRightHandPosition
1206  * @returns {Vec3} The position of the right hand in avatar coordinates if positioned by a hand controller, otherwise
1207  * <code>{@link Vec3(0)|Vec3.ZERO}</code>.
1208  * @example <caption>Report the position of your right hand relative to your avatar.</caption>
1209  * print(JSON.stringify(MyAvatar.getLeftHandPosition()));
1210  */
1211  Q_INVOKABLE glm::vec3 getRightHandPosition() const;
1212 
1213  /*@jsdoc
1214  * Gets the position 0.3m in front of the left hand's position in the direction along the palm, in avatar coordinates, as
1215  * positioned by a hand controller.
1216  * @function MyAvatar.getLeftHandTipPosition
1217  * @returns {Vec3} The position 0.3m in front of the left hand's position in the direction along the palm, in avatar
1218  * coordinates. If the hand isn't being positioned by a controller, <code>{@link Vec3(0)|Vec3.ZERO}</code> is returned.
1219  */
1220  Q_INVOKABLE glm::vec3 getLeftHandTipPosition() const;
1221 
1222  /*@jsdoc
1223  * Gets the position 0.3m in front of the right hand's position in the direction along the palm, in avatar coordinates, as
1224  * positioned by a hand controller.
1225  * @function MyAvatar.getRightHandTipPosition
1226  * @returns {Vec3} The position 0.3m in front of the right hand's position in the direction along the palm, in avatar
1227  * coordinates. If the hand isn't being positioned by a controller, <code>{@link Vec3(0)|Vec3.ZERO}</code> is returned.
1228  */
1229  Q_INVOKABLE glm::vec3 getRightHandTipPosition() const;
1230 
1231 
1232  /*@jsdoc
1233  * Gets the pose (position, rotation, velocity, and angular velocity) of the avatar's left hand as positioned by a
1234  * hand controller (e.g., Oculus Touch or Vive).
1235  * <p>Note: The Leap Motion isn't part of the hand controller input system. (Instead, it manipulates the avatar's joints
1236  * for hand animation.) If you are using the Leap Motion, the return value's <code>valid</code> property will be
1237  * <code>false</code> and any pose values returned will not be meaningful.</p>
1238  * @function MyAvatar.getLeftHandPose
1239  * @returns {Pose} The pose of the avatar's left hand, relative to the avatar, as positioned by a hand controller.
1240  * @example <caption>Report the pose of your avatar's left hand.</caption>
1241  * print(JSON.stringify(MyAvatar.getLeftHandPose()));
1242  */
1243  Q_INVOKABLE controller::Pose getLeftHandPose() const;
1244 
1245  /*@jsdoc
1246  * Gets the pose (position, rotation, velocity, and angular velocity) of the avatar's left hand as positioned by a
1247  * hand controller (e.g., Oculus Touch or Vive).
1248  * <p>Note: The Leap Motion isn't part of the hand controller input system. (Instead, it manipulates the avatar's joints
1249  * for hand animation.) If you are using the Leap Motion, the return value's <code>valid</code> property will be
1250  * <code>false</code> and any pose values returned will not be meaningful.</p>
1251  * @function MyAvatar.getRightHandPose
1252  * @returns {Pose} The pose of the avatar's right hand, relative to the avatar, as positioned by a hand controller.
1253  * @example <caption>Report the pose of your avatar's right hand.</caption>
1254  * print(JSON.stringify(MyAvatar.getRightHandPose()));
1255  */
1256  Q_INVOKABLE controller::Pose getRightHandPose() const;
1257 
1258  /*@jsdoc
1259  * Gets the pose (position, rotation, velocity, and angular velocity) of the avatar's left hand, relative to the avatar, as
1260  * positioned by a hand controller (e.g., Oculus Touch or Vive), and translated 0.3m along the palm.
1261  * <p>Note: Leap Motion isn't part of the hand controller input system. (Instead, it manipulates the avatar's joints
1262  * for hand animation.) If you are using Leap Motion, the return value's <code>valid</code> property will be
1263  * <code>false</code> and any pose values returned will not be meaningful.</p>
1264  * @function MyAvatar.getLeftHandTipPose
1265  * @returns {Pose} The pose of the avatar's left hand, relative to the avatar, as positioned by a hand controller, and
1266  * translated 0.3m along the palm.
1267  */
1268  Q_INVOKABLE controller::Pose getLeftHandTipPose() const;
1269 
1270  /*@jsdoc
1271  * Gets the pose (position, rotation, velocity, and angular velocity) of the avatar's right hand, relative to the avatar, as
1272  * positioned by a hand controller (e.g., Oculus Touch or Vive), and translated 0.3m along the palm.
1273  * <p>Note: Leap Motion isn't part of the hand controller input system. (Instead, it manipulates the avatar's joints
1274  * for hand animation.) If you are using Leap Motion, the return value's <code>valid</code> property will be
1275  * <code>false</code> and any pose values returned will not be meaningful.</p>
1276  * @function MyAvatar.getRightHandTipPose
1277  * @returns {Pose} The pose of the avatar's right hand, relative to the avatar, as positioned by a hand controller, and
1278  * translated 0.3m along the palm.
1279  */
1280  Q_INVOKABLE controller::Pose getRightHandTipPose() const;
1281 
1282  AvatarWeakPointer getLookAtTargetAvatar() const { return _lookAtTargetAvatar; }
1283  void updateLookAtTargetAvatar();
1284  void computeMyLookAtTarget(const AvatarHash& hash);
1285  void snapOtherAvatarLookAtTargetsToMe(const AvatarHash& hash);
1286  void clearLookAtTargetAvatar();
1287 
1288  virtual void setJointRotations(const QVector<glm::quat>& jointRotations) override;
1289  virtual void setJointData(int index, const glm::quat& rotation, const glm::vec3& translation) override;
1290  virtual void setJointRotation(int index, const glm::quat& rotation) override;
1291  virtual void setJointTranslation(int index, const glm::vec3& translation) override;
1292  virtual void clearJointData(int index) override;
1293 
1294  virtual void setJointData(const QString& name, const glm::quat& rotation, const glm::vec3& translation) override;
1295  virtual void setJointRotation(const QString& name, const glm::quat& rotation) override;
1296  virtual void setJointTranslation(const QString& name, const glm::vec3& translation) override;
1297  virtual void clearJointData(const QString& name) override;
1298  virtual void clearJointsData() override;
1299 
1300  /*@jsdoc
1301  * Sets and locks a joint's position and orientation.
1302  * <p><strong>Note:</strong> Only works on the hips joint.</p>
1303  * @function MyAvatar.pinJoint
1304  * @param {number} index - The index of the joint.
1305  * @param {Vec3} position - The position of the joint in world coordinates.
1306  * @param {Quat} orientation - The orientation of the joint in world coordinates.
1307  * @returns {boolean} <code>true</code> if the joint was pinned, <code>false</code> if it wasn't.
1308  */
1309  Q_INVOKABLE bool pinJoint(int index, const glm::vec3& position, const glm::quat& orientation);
1310 
1311  bool isJointPinned(int index);
1312 
1313  /*@jsdoc
1314  * Clears a lock on a joint's position and orientation, as set by {@link MyAvatar.pinJoint|pinJoint}.
1315  * <p><strong>Note:</strong> Only works on the hips joint.</p>
1316  * @function MyAvatar.clearPinOnJoint
1317  * @param {number} index - The index of the joint.
1318  * @returns {boolean} <code>true</code> if the joint was unpinned, <code>false</code> if it wasn't.
1319  */
1320  Q_INVOKABLE bool clearPinOnJoint(int index);
1321 
1322  /*@jsdoc
1323  * Gets the maximum error distance from the most recent inverse kinematics (IK) solution.
1324  * @function MyAvatar.getIKErrorOnLastSolve
1325  * @returns {number} The maximum IK error distance.
1326  */
1327  Q_INVOKABLE float getIKErrorOnLastSolve() const;
1328 
1329  /*@jsdoc
1330  * Changes the user's avatar and associated descriptive name.
1331  * @function MyAvatar.useFullAvatarURL
1332  * @param {string} fullAvatarURL - The URL of the avatar's <code>.fst</code> file.
1333  * @param {string} [modelName=""] - Descriptive name of the avatar.
1334  */
1335  Q_INVOKABLE void useFullAvatarURL(const QUrl& fullAvatarURL, const QString& modelName = QString());
1336 
1337  /*@jsdoc
1338  * Gets the complete URL for the current avatar.
1339  * @function MyAvatar.getFullAvatarURLFromPreferences
1340  * @returns {string} The full avatar model name.
1341  * @example <caption>Report the URL for the current avatar.</caption>
1342  * print(MyAvatar.getFullAvatarURLFromPreferences());
1343  */
1344  Q_INVOKABLE QUrl getFullAvatarURLFromPreferences() const { return _fullAvatarURLFromPreferences; }
1345 
1346  /*@jsdoc
1347  * Gets the full avatar model name for the current avatar.
1348  * @function MyAvatar.getFullAvatarModelName
1349  * @returns {string} The full avatar model name.
1350  * @example <caption>Report the current full avatar model name.</caption>
1351  * print(MyAvatar.getFullAvatarModelName());
1352  */
1353  Q_INVOKABLE QString getFullAvatarModelName() const { return _fullAvatarModelName; }
1354 
1355  void resetFullAvatarURL();
1356 
1357  MyCharacterController* getCharacterController() { return &_characterController; }
1358  const MyCharacterController* getCharacterController() const { return &_characterController; }
1359 
1360  void updateMotors();
1361  void prepareForPhysicsSimulation();
1362  void nextAttitude(glm::vec3 position, glm::quat orientation); // Can be safely called at any time.
1363  void harvestResultsFromPhysicsSimulation(float deltaTime);
1364 
1365  const QString& getCollisionSoundURL() { return _collisionSoundURL; }
1366  void setCollisionSoundURL(const QString& url);
1367 
1368  SharedSoundPointer getCollisionSound();
1369  void setCollisionSound(SharedSoundPointer sound) { _collisionSound = sound; }
1370 
1371  void clearScriptableSettings();
1372 
1373  float getBoomLength() const { return _boomLength; }
1374  void setBoomLength(float boomLength) { _boomLength = boomLength; }
1375 
1376  float getPitchSpeed() const { return _pitchSpeed; }
1377  void setPitchSpeed(float speed) { _pitchSpeed = speed; }
1378 
1379  float getYawSpeed() const { return _yawSpeed; }
1380  void setYawSpeed(float speed) { _yawSpeed = speed; }
1381 
1382  float getHMDYawSpeed() const { return _hmdYawSpeed; }
1383  void setHMDYawSpeed(float speed) { _hmdYawSpeed = speed; }
1384 
1385  float getCameraSensitivity() const;
1386  void setCameraSensitivity(float cameraSensitivity);
1387 
1388  static const float ZOOM_MIN;
1389  static const float ZOOM_MAX;
1390  static const float ZOOM_DEFAULT;
1391 
1392  void destroyAnimGraph();
1393 
1394  AudioListenerMode getAudioListenerMode() { return _audioListenerMode; }
1395  void setAudioListenerMode(AudioListenerMode audioListenerMode);
1396  glm::vec3 getCustomListenPosition() { return _customListenPosition; }
1397  void setCustomListenPosition(glm::vec3 customListenPosition) { _customListenPosition = customListenPosition; }
1398  glm::quat getCustomListenOrientation() { return _customListenOrientation; }
1399  void setCustomListenOrientation(glm::quat customListenOrientation) { _customListenOrientation = customListenOrientation; }
1400 
1401  virtual void rebuildCollisionShape() override;
1402 
1403  const glm::vec2& getHipToHandController() const { return _hipToHandController; }
1404  void setHipToHandController(glm::vec2 currentHipToHandController) { _hipToHandController = currentHipToHandController; }
1405  const glm::vec2& getHeadControllerFacing() const { return _headControllerFacing; }
1406  void setHeadControllerFacing(glm::vec2 currentHeadControllerFacing) { _headControllerFacing = currentHeadControllerFacing; }
1407  const glm::vec2& getHeadControllerFacingMovingAverage() const { return _headControllerFacingMovingAverage; }
1408  void setHeadControllerFacingMovingAverage(glm::vec2 currentHeadControllerFacing) { _headControllerFacingMovingAverage = currentHeadControllerFacing; }
1409  float getCurrentStandingHeight() const { return _currentStandingHeight; }
1410  void setCurrentStandingHeight(float newMode) { _currentStandingHeight = newMode; }
1411  const glm::quat getAverageHeadRotation() const { return _averageHeadRotation; }
1412  void setAverageHeadRotation(glm::quat rotation) { _averageHeadRotation = rotation; }
1413  bool getResetMode() const { return _resetMode; }
1414  void setResetMode(bool hasBeenReset) { _resetMode = hasBeenReset; }
1415 
1416  void setControllerPoseInSensorFrame(controller::Action action, const controller::Pose& pose);
1417  controller::Pose getControllerPoseInSensorFrame(controller::Action action) const;
1418  controller::Pose getControllerPoseInWorldFrame(controller::Action action) const;
1419  controller::Pose getControllerPoseInAvatarFrame(controller::Action action) const;
1420 
1421  bool hasDriveInput() const;
1422 
1423  /*@jsdoc
1424  * Gets the current avatar entity IDs and their properties.
1425  * @function MyAvatar.getAvatarEntitiesVariant
1426  * @returns {MyAvatar.AvatarEntityData[]} The current avatar entity IDs and their properties.
1427  */
1428  Q_INVOKABLE QVariantList getAvatarEntitiesVariant();
1429 
1430  void removeWornAvatarEntity(const EntityItemID& entityID);
1431  void clearWornAvatarEntities();
1432  bool hasAvatarEntities() const;
1433 
1434  /*@jsdoc
1435  * Checks whether your avatar is flying.
1436  * @function MyAvatar.isFlying
1437  * @returns {boolean} <code>true</code> if your avatar is flying and not taking off or falling, <code>false</code> if not.
1438  */
1439  Q_INVOKABLE bool isFlying();
1440 
1441  /*@jsdoc
1442  * Checks whether your avatar is in the air.
1443  * @function MyAvatar.isInAir
1444  * @returns {boolean} <code>true</code> if your avatar is taking off, flying, or falling, otherwise <code>false</code>
1445  * because your avatar is on the ground.
1446  */
1447  Q_INVOKABLE bool isInAir();
1448 
1449  /*@jsdoc
1450  * Sets your preference for flying in your current desktop or HMD display mode. Note that your ability to fly also depends
1451  * on whether the domain you're in allows you to fly.
1452  * @function MyAvatar.setFlyingEnabled
1453  * @param {boolean} enabled - Set <code>true</code> if you want to enable flying in your current desktop or HMD display
1454  * mode, otherwise set <code>false</code>.
1455  */
1456  Q_INVOKABLE void setFlyingEnabled(bool enabled);
1457 
1458  /*@jsdoc
1459  * Gets your preference for flying in your current desktop or HMD display mode. Note that your ability to fly also depends
1460  * on whether the domain you're in allows you to fly.
1461  * @function MyAvatar.getFlyingEnabled
1462  * @returns {boolean} <code>true</code> if your preference is to enable flying in your current desktop or HMD display mode,
1463  * otherwise <code>false</code>.
1464  */
1465  Q_INVOKABLE bool getFlyingEnabled();
1466 
1467  /*@jsdoc
1468  * Sets your preference for flying in desktop display mode. Note that your ability to fly also depends on whether the domain
1469  * you're in allows you to fly.
1470  * @function MyAvatar.setFlyingDesktopPref
1471  * @param {boolean} enabled - Set <code>true</code> if you want to enable flying in desktop display mode, otherwise set
1472  * <code>false</code>.
1473  */
1474  Q_INVOKABLE void setFlyingDesktopPref(bool enabled);
1475 
1476  /*@jsdoc
1477  * Gets your preference for flying in desktop display mode. Note that your ability to fly also depends on whether the domain
1478  * you're in allows you to fly.
1479  * @function MyAvatar.getFlyingDesktopPref
1480  * @returns {boolean} <code>true</code> if your preference is to enable flying in desktop display mode, otherwise
1481  * <code>false</code>.
1482  */
1483  Q_INVOKABLE bool getFlyingDesktopPref();
1484 
1485  /*@jsdoc
1486  * Sets your preference for flying in HMD display mode. Note that your ability to fly also depends on whether the domain
1487  * you're in allows you to fly.
1488  * @function MyAvatar.setFlyingHMDPref
1489  * @param {boolean} enabled - Set <code>true</code> if you want to enable flying in HMD display mode, otherwise set
1490  * <code>false</code>.
1491  */
1492  Q_INVOKABLE void setFlyingHMDPref(bool enabled);
1493 
1494  /*@jsdoc
1495  * Gets your preference for flying in HMD display mode. Note that your ability to fly also depends on whether the domain
1496  * you're in allows you to fly.
1497  * @function MyAvatar.getFlyingHMDPref
1498  * @returns {boolean} <code>true</code> if your preference is to enable flying in HMD display mode, otherwise
1499  * <code>false</code>.
1500  */
1501  Q_INVOKABLE bool getFlyingHMDPref();
1502 
1503  /*@jsdoc
1504  * Set your preference for hand-relative movement.
1505  * @function MyAvatar.setHandRelativeMovement
1506  * @param {number} enabled - Set <code>true</code> if you want to enable hand-relative movement, otherwise set to <code>false</code>.
1507  *
1508  */
1509  Q_INVOKABLE void setMovementReference(int enabled);
1510 
1511  /*@jsdoc
1512  * Get your preference for hand-relative movement.
1513  * @function MyAvatar.getHandRelativeMovement
1514  * @returns {number} <code>true</code> if your preference is for user locomotion to be relative to the direction your
1515  * controller is pointing, otherwise <code>false</code>.
1516  */
1517  Q_INVOKABLE int getMovementReference();
1518 
1519  /*@jsdoc
1520  * Gets the target scale of the avatar. The target scale is the desired scale of the avatar without any restrictions on
1521  * permissible scale values imposed by the domain.
1522  * @function MyAvatar.getAvatarScale
1523  * @returns {number} The target scale for the avatar, range <code>0.005</code> &ndash; <code>1000.0</code>.
1524  */
1525  Q_INVOKABLE float getAvatarScale() const;
1526 
1527  /*@jsdoc
1528  * Sets the target scale of the avatar. The target scale is the desired scale of the avatar without any restrictions on
1529  * permissible scale values imposed by the domain.
1530  * @function MyAvatar.setAvatarScale
1531  * @param {number} scale - The target scale for the avatar, range <code>0.005</code> &ndash; <code>1000.0</code>.
1532  */
1533  Q_INVOKABLE void setAvatarScale(float scale);
1534 
1535  /*@jsdoc
1536  * Sets whether the avatar should collide with entities.
1537  * <p><strong>Note:</strong> A <code>false</code> value won't disable collisions if the avatar is in a zone that disallows
1538  * collisionless avatars. However, the <code>false</code> value will be set so that collisions are disabled as soon as the
1539  * avatar moves to a position where collisionless avatars are allowed.
1540  * @function MyAvatar.setCollisionsEnabled
1541  * @param {boolean} enabled - <code>true</code> to enable the avatar to collide with entities, <code>false</code> to
1542  * disable.
1543  */
1544  Q_INVOKABLE void setCollisionsEnabled(bool enabled);
1545 
1546  /*@jsdoc
1547  * Gets whether the avatar will currently collide with entities.
1548  * <p><strong>Note:</strong> The avatar will always collide with entities if in a zone that disallows collisionless avatars.
1549  * @function MyAvatar.getCollisionsEnabled
1550  * @returns {boolean} <code>true</code> if the avatar will currently collide with entities, <code>false</code> if it won't.
1551  */
1552  Q_INVOKABLE bool getCollisionsEnabled();
1553 
1554  /*@jsdoc
1555  * Sets whether the avatar should collide with other avatars.
1556  * @function MyAvatar.setOtherAvatarsCollisionsEnabled
1557  * @param {boolean} enabled - <code>true</code> to enable the avatar to collide with other avatars, <code>false</code>
1558  * to disable.
1559  */
1560  Q_INVOKABLE void setOtherAvatarsCollisionsEnabled(bool enabled);
1561 
1562  /*@jsdoc
1563  * Gets whether the avatar will collide with other avatars.
1564  * @function MyAvatar.getOtherAvatarsCollisionsEnabled
1565  * @returns {boolean} <code>true</code> if the avatar will collide with other avatars, <code>false</code> if it won't.
1566  */
1567  Q_INVOKABLE bool getOtherAvatarsCollisionsEnabled();
1568 
1569  /*@jsdoc
1570  * Gets the avatar's collision capsule: a cylinder with hemispherical ends that approximates the extents or the avatar.
1571  * <p><strong>Warning:</strong> The values returned are in world coordinates but aren't necessarily up to date with the
1572  * avatar's current position.</p>
1573  * @function MyAvatar.getCollisionCapsule
1574  * @returns {MyAvatar.CollisionCapsule} The avatar's collision capsule.
1575  */
1576  Q_INVOKABLE QVariantMap getCollisionCapsule() const;
1577 
1578  /*@jsdoc
1579  * @function MyAvatar.setCharacterControllerEnabled
1580  * @param {boolean} enabled - <code>true</code> to enable the avatar to collide with entities, <code>false</code> to
1581  * disable.
1582  * @deprecated This function is deprecated and will be removed. Use {@link MyAvatar.setCollisionsEnabled} instead.
1583  */
1584  Q_INVOKABLE void setCharacterControllerEnabled(bool enabled); // deprecated
1585 
1586  /*@jsdoc
1587  * @function MyAvatar.getCharacterControllerEnabled
1588  * @returns {boolean} <code>true</code> if the avatar will currently collide with entities, <code>false</code> if it won't.
1589  * @deprecated This function is deprecated and will be removed. Use {@link MyAvatar.getCollisionsEnabled} instead.
1590  */
1591  Q_INVOKABLE bool getCharacterControllerEnabled(); // deprecated
1592 
1593  /*@jsdoc
1594  * Gets the rotation of a joint relative to the avatar.
1595  * @comment Different behavior to the Avatar version of this method.
1596  * @function MyAvatar.getAbsoluteJointRotationInObjectFrame
1597  * @param {number} index - The index of the joint.
1598  * @returns {Quat} The rotation of the joint relative to the avatar.
1599  * @example <caption>Report the rotation of your avatar's head joint relative to your avatar.</caption>
1600  * var headIndex = MyAvatar.getJointIndex("Head");
1601  * var headRotation = MyAvatar.getAbsoluteJointRotationInObjectFrame(headIndex);
1602  * print("Head rotation: " + JSON.stringify(Quat.safeEulerAngles(headRotation))); // Degrees
1603  */
1604  virtual glm::quat getAbsoluteJointRotationInObjectFrame(int index) const override;
1605 
1606  /*@jsdoc
1607  * Gets the translation of a joint relative to the avatar.
1608  * @comment Different behavior to the Avatar version of this method.
1609  * @function MyAvatar.getAbsoluteJointTranslationInObjectFrame
1610  * @param {number} index - The index of the joint.
1611  * @returns {Vec3} The translation of the joint relative to the avatar.
1612  * @example <caption>Report the translation of your avatar's head joint relative to your avatar.</caption>
1613  * var headIndex = MyAvatar.getJointIndex("Head");
1614  * var headTranslation = MyAvatar.getAbsoluteJointTranslationInObjectFrame(headIndex);
1615  * print("Head translation: " + JSON.stringify(headTranslation));
1616  */
1617  virtual glm::vec3 getAbsoluteJointTranslationInObjectFrame(int index) const override;
1618 
1619  // all calibration matrices are in absolute sensor space.
1620  glm::mat4 getCenterEyeCalibrationMat() const;
1621  glm::mat4 getHeadCalibrationMat() const;
1622  glm::mat4 getSpine2CalibrationMat() const;
1623  glm::mat4 getHipsCalibrationMat() const;
1624  glm::mat4 getLeftFootCalibrationMat() const;
1625  glm::mat4 getRightFootCalibrationMat() const;
1626  glm::mat4 getRightArmCalibrationMat() const;
1627  glm::mat4 getLeftArmCalibrationMat() const;
1628  glm::mat4 getLeftHandCalibrationMat() const;
1629  glm::mat4 getRightHandCalibrationMat() const;
1630 
1631  void addHoldAction(AvatarActionHold* holdAction); // thread-safe
1632  void removeHoldAction(AvatarActionHold* holdAction); // thread-safe
1633  void updateHoldActions(const AnimPose& prePhysicsPose, const AnimPose& postUpdatePose);
1634 
1635 
1636  // derive avatar body position and orientation from the current HMD Sensor location.
1637  // results are in sensor frame (-z forward)
1638  glm::mat4 deriveBodyFromHMDSensor(const bool forceFollowYPos = false) const;
1639 
1640  glm::mat4 getSpine2RotationRigSpace() const;
1641 
1642  glm::vec3 computeCounterBalance();
1643 
1644  // derive avatar body position and orientation from using the current HMD Sensor location in relation to the previous
1645  // location of the base of support of the avatar.
1646  // results are in sensor frame (-z foward)
1647  glm::mat4 deriveBodyUsingCgModel();
1648 
1649  /*@jsdoc
1650  * Tests whether a vector is pointing in the general direction of the avatar's "up" direction (i.e., dot product of vectors
1651  * is <code>&gt; 0</code>).
1652  * @function MyAvatar.isUp
1653  * @param {Vec3} direction - The vector to test.
1654  * @returns {boolean} <code>true</code> if the direction vector is pointing generally in the direction of the avatar's "up"
1655  * direction.
1656  */
1657  Q_INVOKABLE bool isUp(const glm::vec3& direction) { return glm::dot(direction, _worldUpDirection) > 0.0f; }; // true iff direction points up wrt avatar's definition of up.
1658 
1659  /*@jsdoc
1660  * Tests whether a vector is pointing in the general direction of the avatar's "down" direction (i.e., dot product of
1661  * vectors is <code>&lt; 0</code>).
1662  * @function MyAvatar.isDown
1663  * @param {Vec3} direction - The vector to test.
1664  * @returns {boolean} <code>true</code> if the direction vector is pointing generally in the direction of the avatar's
1665  * "down" direction.
1666  */
1667  Q_INVOKABLE bool isDown(const glm::vec3& direction) { return glm::dot(direction, _worldUpDirection) < 0.0f; };
1668 
1669  void setUserHeight(float value);
1670  float getUserHeight() const;
1671  float getUserEyeHeight() const;
1672 
1673  virtual SpatialParentTree* getParentTree() const override;
1674  virtual glm::vec3 scaleForChildren() const override { return glm::vec3(getSensorToWorldScale()); }
1675 
1676  const QUuid& getSelfID() const { return AVATAR_SELF_ID; }
1677 
1678  void setIsInWalkingState(bool isWalking);
1679  bool getIsInWalkingState() const;
1680  void setIsInSittingState(bool isSitting);
1681  bool getIsInSittingState() const;
1682  void setUserRecenterModel(MyAvatar::SitStandModelType modelName); // Deprecated, will be removed.
1683  MyAvatar::SitStandModelType getUserRecenterModel() const; // Deprecated, will be removed.
1684  void setIsSitStandStateLocked(bool isLocked); // Deprecated, will be removed.
1685  bool getIsSitStandStateLocked() const; // Deprecated, will be removed.
1686  void setAllowAvatarStandingPreference(const AllowAvatarStandingPreference preference);
1687  AllowAvatarStandingPreference getAllowAvatarStandingPreference() const;
1688  void setAllowAvatarLeaningPreference(const AllowAvatarLeaningPreference preference);
1689  AllowAvatarLeaningPreference getAllowAvatarLeaningPreference() const;
1690  void setWalkSpeed(float value);
1691  float getWalkSpeed() const;
1692  void setSprintSpeed(float value);
1693  float getSprintSpeed() const;
1694  void setVrWalkSpeed(float value);
1695  float getVrWalkSpeed() const;
1696  void setSitStandStateChange(bool stateChanged);
1697  bool getSitStandStateChange() const;
1698  void updateSitStandState(float newHeightReading, float dt);
1699 
1700  QVector<QString> getScriptUrls();
1701 
1702  bool isReadyForPhysics() const;
1703 
1704  float computeStandingHeightMode(const controller::Pose& head);
1705  glm::quat computeAverageHeadRotation(const controller::Pose& head);
1706 
1707  glm::vec3 getNextPosition() { return _goToPending ? _goToPosition : getWorldPosition(); }
1708  void prepareAvatarEntityDataForReload();
1709 
1710  /*@jsdoc
1711  * Turns the avatar's head until it faces the target point within a +90/-90 degree range.
1712  * Once this method is called, API calls have full control of the head for a limited time.
1713  * If this method is not called for 2 seconds, the engine regains control of the head.
1714  * @function MyAvatar.setHeadLookAt
1715  * @param {Vec3} lookAtTarget - The target point in world coordinates.
1716  */
1717  Q_INVOKABLE void setHeadLookAt(const glm::vec3& lookAtTarget);
1718 
1719  /*@jsdoc
1720  * Gets the current target point of the head's look direction in world coordinates.
1721  * @function MyAvatar.getHeadLookAt
1722  * @returns {Vec3} The head's look-at target in world coordinates.
1723  */
1724  Q_INVOKABLE glm::vec3 getHeadLookAt() { return _lookAtCameraTarget; }
1725 
1726  /*@jsdoc
1727  * Returns control of the avatar's head to the engine, and releases control from API calls.
1728  * @function MyAvatar.releaseHeadLookAtControl
1729  */
1730  Q_INVOKABLE void releaseHeadLookAtControl();
1731 
1732  /*@jsdoc
1733  * Forces the avatar's eyes to look at a specified location. Once this method is called, API calls
1734  * full control of the eyes for a limited time. If this method is not called for 2 seconds,
1735  * the engine regains control of the eyes.
1736  * @function MyAvatar.setEyesLookAt
1737  * @param {Vec3} lookAtTarget - The target point in world coordinates.
1738  */
1739  Q_INVOKABLE void setEyesLookAt(const glm::vec3& lookAtTarget);
1740 
1741  /*@jsdoc
1742  * Gets the current target point of the eyes look direction in world coordinates.
1743  * @function MyAvatar.getEyesLookAt
1744  * @returns {Vec3} The eyes' look-at target in world coordinates.
1745  */
1746  Q_INVOKABLE glm::vec3 getEyesLookAt() { return _eyesLookAtTarget.get(); }
1747 
1748  /*@jsdoc
1749  * Returns control of the avatar's eyes to the engine, and releases control from API calls.
1750  * @function MyAvatar.releaseEyesLookAtControl
1751  */
1752  Q_INVOKABLE void releaseEyesLookAtControl();
1753 
1754  /*@jsdoc
1755  * Sets the point-at target for the <code>"point"</code> reaction that may be started with {@link MyAvatar.beginReaction}.
1756  * The point-at target is set only if it is in front of the avatar.
1757  * <p>Note: The <code>"point"</code> reaction should be started before calling this method.</p>
1758  * @function MyAvatar.setPointAt
1759  * @param {Vec3} pointAtTarget - The target to point at, in world coordinates.
1760  * @returns {boolean} <code>true</code> if the target point was set, <code>false</code> if it wasn't.
1761  */
1762  Q_INVOKABLE bool setPointAt(const glm::vec3& pointAtTarget);
1763 
1764  glm::quat getLookAtRotation() { return _lookAtYaw * _lookAtPitch; }
1765 
1766  /*@jsdoc
1767  * Creates a new grab that grabs an entity.
1768  * @function MyAvatar.grab
1769  * @param {Uuid} targetID - The ID of the entity to grab.
1770  * @param {number} parentJointIndex - The avatar joint to use to grab the entity.
1771  * @param {Vec3} offset - The target's local position relative to the joint.
1772  * @param {Quat} rotationalOffset - The target's local rotation relative to the joint.
1773  * @returns {Uuid} The ID of the new grab.
1774  * @example <caption>Create and grab an entity for a short while.</caption>
1775  * var entityPosition = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 }));
1776  * var entityRotation = MyAvatar.orientation;
1777  * var entityID = Entities.addEntity({
1778  * type: "Box",
1779  * position: entityPosition,
1780  * rotation: entityRotation,
1781  * dimensions: { x: 0.5, y: 0.5, z: 0.5 }
1782  * });
1783  * var rightHandJoint = MyAvatar.getJointIndex("RightHand");
1784  * var relativePosition = Entities.worldToLocalPosition(entityPosition, MyAvatar.SELF_ID, rightHandJoint);
1785  * var relativeRotation = Entities.worldToLocalRotation(entityRotation, MyAvatar.SELF_ID, rightHandJoint);
1786  * var grabID = MyAvatar.grab(entityID, rightHandJoint, relativePosition, relativeRotation);
1787  *
1788  * Script.setTimeout(function () {
1789  * MyAvatar.releaseGrab(grabID);
1790  * Entities.deleteEntity(entityID);
1791  * }, 10000);
1792  */
1793  Q_INVOKABLE const QUuid grab(const QUuid& targetID, int parentJointIndex,
1794  glm::vec3 positionalOffset, glm::quat rotationalOffset);
1795 
1796  /*@jsdoc
1797  * Releases (deletes) a grab to stop grabbing an entity.
1798  * @function MyAvatar.releaseGrab
1799  * @param {Uuid} grabID - The ID of the grab to release.
1800  */
1801  Q_INVOKABLE void releaseGrab(const QUuid& grabID);
1802 
1803  /*@jsdoc
1804  * Gets details of all avatar entities.
1805  * <p><strong>Warning:</strong> Potentially an expensive call. Do not use if possible.</p>
1806  * @function MyAvatar.getAvatarEntityData
1807  * @returns {AvatarEntityMap} Details of all avatar entities.
1808  * @example <caption>Report the current avatar entities.</caption>
1809  * var avatarEntityData = MyAvatar.getAvatarEntityData();
1810  * print("Avatar entities: " + JSON.stringify(avatarEntityData));
1811  */
1812  AvatarEntityMap getAvatarEntityData() const override;
1813 
1814  AvatarEntityMap getAvatarEntityDataNonDefault() const override;
1815 
1816  /*@jsdoc
1817  * Sets all avatar entities from an object.
1818  * @function MyAvatar.setAvatarEntityData
1819  * @param {AvatarEntityMap} avatarEntityData - Details of the avatar entities.
1820  */
1821  void setAvatarEntityData(const AvatarEntityMap& avatarEntityData) override;
1822 
1823  /*@jsdoc
1824  * @comment Uses the base class's JSDoc.
1825  */
1826  void updateAvatarEntity(const QUuid& entityID, const QByteArray& entityData) override;
1827 
1828  void avatarEntityDataToJson(QJsonObject& root) const override;
1829 
1830  void storeAvatarEntityDataPayload(const QUuid& entityID, const QByteArray& payload) override;
1831 
1832  /*@jsdoc
1833  * @comment Uses the base class's JSDoc.
1834  */
1835  int sendAvatarDataPacket(bool sendAll = false) override;
1836 
1837  void addAvatarHandsToFlow(const std::shared_ptr<Avatar>& otherAvatar);
1838 
1839  /*@jsdoc
1840  * Enables and disables flow simulation of physics on the avatar's hair, clothes, and body parts. See
1841  * {@link https://docs.overte.org/create/avatars/add-flow.html|Add Flow to Your Avatar} for more
1842  * information.
1843  * @function MyAvatar.useFlow
1844  * @param {boolean} isActive - <code>true</code> if flow simulation is enabled on the joint, <code>false</code> if it isn't.
1845  * @param {boolean} isCollidable - <code>true</code> to enable collisions in the flow simulation, <code>false</code> to
1846  * disable.
1847  * @param {Object<JointName, MyAvatar.FlowPhysicsOptions>} [physicsConfig] - Physics configurations for particular entity
1848  * and avatar joints.
1849  * @param {Object<JointName, MyAvatar.FlowCollisionsOptions>} [collisionsConfig] - Collision configurations for particular
1850  * entity and avatar joints.
1851  */
1852  Q_INVOKABLE void useFlow(bool isActive, bool isCollidable, const QVariantMap& physicsConfig = QVariantMap(), const QVariantMap& collisionsConfig = QVariantMap());
1853 
1854  /*@jsdoc
1855  * Gets the current flow configuration.
1856  * @function MyAvatar.getFlowData
1857  * @returns {MyAvatar.FlowData}
1858  */
1859  Q_INVOKABLE QVariantMap getFlowData();
1860 
1861  /*@jsdoc
1862  * Gets the indexes of currently colliding flow joints.
1863  * @function MyAvatar.getCollidingFlowJoints
1864  * @returns {number[]} The indexes of currently colliding flow joints.
1865  */
1866  Q_INVOKABLE QVariantList getCollidingFlowJoints();
1867 
1868  /*@jsdoc
1869  * Starts a sitting action for the avatar.
1870  * @function MyAvatar.beginSit
1871  * @param {Vec3} position - The position where the avatar should sit.
1872  * @param {Quat} rotation - The initial orientation of the seated avatar.
1873  */
1874  Q_INVOKABLE void beginSit(const glm::vec3& position, const glm::quat& rotation);
1875 
1876  /*@jsdoc
1877  * Ends a sitting action for the avatar.
1878  * @function MyAvatar.endSit
1879  * @param {Vec3} position - The position of the avatar when standing up.
1880  * @param {Quat} rotation - The orientation of the avatar when standing up.
1881  */
1882  Q_INVOKABLE void endSit(const glm::vec3& position, const glm::quat& rotation);
1883 
1884  /*@jsdoc
1885  * Gets whether the avatar is in a seated pose. The seated pose is set by calling {@link MyAvatar.beginSit}.
1886  * @function MyAvatar.isSeated
1887  * @returns {boolean} <code>true</code> if the avatar is in a seated pose, <code>false</code> if it isn't.
1888  */
1889  Q_INVOKABLE bool isSeated() { return _characterController.getSeated(); }
1890 
1891  int getOverrideJointCount() const;
1892  bool getFlowActive() const;
1893  bool getNetworkGraphActive() const;
1894 
1895  void updateEyesLookAtPosition(float deltaTime);
1896 
1897  // sets the reaction enabled and triggered parameters of the passed in params
1898  // also clears internal reaction triggers
1899  void updateRigControllerParameters(Rig::ControllerParameters& params);
1900 
1901  // Don't substitute verify-fail:
1902  virtual const QUrl& getSkeletonModelURL() const override { return _skeletonModelURL; }
1903 
1904  void debugDrawPose(controller::Action action, const char* channelName, float size);
1905 
1906  bool getIsJointOverridden(int jointIndex) const;
1907  glm::vec3 getLookAtPivotPoint();
1908  glm::vec3 getCameraEyesPosition(float deltaTime);
1909  bool isJumping();
1910  bool getHMDCrouchRecenterEnabled() const;
1911  bool isAllowedToLean() const;
1912  bool areFeetTracked() const { return _isBodyPartTracked._feet; }; // Determine if the feet are under direct control.
1913  bool areHipsTracked() const { return _isBodyPartTracked._hips; }; // Determine if the hips are under direct control.
1914 
1915 public slots:
1916 
1917  /*@jsdoc
1918  * @comment Uses the base class's JSDoc.
1919  */
1920  virtual void setSessionUUID(const QUuid& sessionUUID) override;
1921 
1922  /*@jsdoc
1923  * Increases the avatar's scale by five percent, up to a minimum scale of <code>1000</code>.
1924  * @function MyAvatar.increaseSize
1925  * @example <caption>Reset your avatar's size to default then grow it 5 times.</caption>
1926  * MyAvatar.resetSize();
1927  *
1928  * for (var i = 0; i < 5; i++){
1929  * print("Growing by 5 percent");
1930  * MyAvatar.increaseSize();
1931  * }
1932  */
1933  void increaseSize();
1934 
1935  /*@jsdoc
1936  * Decreases the avatar's scale by five percent, down to a minimum scale of <code>0.25</code>.
1937  * @function MyAvatar.decreaseSize
1938  * @example <caption>Reset your avatar's size to default then shrink it 5 times.</caption>
1939  * MyAvatar.resetSize();
1940  *
1941  * for (var i = 0; i < 5; i++){
1942  * print("Shrinking by 5 percent");
1943  * MyAvatar.decreaseSize();
1944  * }
1945  */
1946  void decreaseSize();
1947 
1948  /*@jsdoc
1949  * Resets the avatar's scale back to the default scale of <code>1.0</code>.
1950  * @function MyAvatar.resetSize
1951  */
1952  void resetSize();
1953 
1954  /*@jsdoc
1955  * @function MyAvatar.animGraphLoaded
1956  * @deprecated This function is deprecated and will be removed.
1957  */
1958  void animGraphLoaded();
1959 
1960  /*@jsdoc
1961  * Sets the amount of gravity applied to the avatar in the y-axis direction. (Negative values are downward.)
1962  * @function MyAvatar.setGravity
1963  * @param {number} gravity - The amount of gravity to be applied to the avatar, in m/s<sup>2</sup>.
1964  */
1965  void setGravity(float gravity);
1966 
1967  /*@jsdoc
1968  * Sets the amount of gravity applied to the avatar in the y-axis direction. (Negative values are downward.) The default
1969  * value is <code>-5</code> m/s<sup>2</sup>.
1970  * @function MyAvatar.getGravity
1971  * @returns {number} The amount of gravity currently applied to the avatar, in m/s<sup>2</sup>.
1972  */
1973  float getGravity();
1974 
1975  /*@jsdoc
1976  * Moves the avatar to a new position and/or orientation in the domain, with safe landing, while taking into account avatar
1977  * leg length.
1978  * @function MyAvatar.goToFeetLocation
1979  * @param {Vec3} position - The new position for the avatar, in world coordinates.
1980  * @param {boolean} [hasOrientation=false] - Set to <code>true</code> to set the orientation of the avatar.
1981  * @param {Quat} [orientation=Quat.IDENTITY] - The new orientation for the avatar.
1982  * @param {boolean} [shouldFaceLocation=false] - Set to <code>true</code> to position the avatar a short distance away from
1983  * the new position and orientate the avatar to face the position.
1984  */
1985  void goToFeetLocation(const glm::vec3& newPosition, bool hasOrientation = false,
1986  const glm::quat& newOrientation = glm::quat(), bool shouldFaceLocation = false);
1987 
1988  /*@jsdoc
1989  * Moves the avatar to a new position and/or orientation in the domain.
1990  * @function MyAvatar.goToLocation
1991  * @param {Vec3} position - The new position for the avatar, in world coordinates.
1992  * @param {boolean} [hasOrientation=false] - Set to <code>true</code> to set the orientation of the avatar.
1993  * @param {Quat} [orientation=Quat.IDENTITY] - The new orientation for the avatar.
1994  * @param {boolean} [shouldFaceLocation=false] - Set to <code>true</code> to position the avatar a short distance away from
1995  * the new position and orientate the avatar to face the position.
1996  * @param {boolean} [withSafeLanding=true] - Set to <code>false</code> to disable safe landing when teleporting.
1997  */
1998  void goToLocation(const glm::vec3& newPosition,
1999  bool hasOrientation = false, const glm::quat& newOrientation = glm::quat(),
2000  bool shouldFaceLocation = false, bool withSafeLanding = true);
2001  /*@jsdoc
2002  * Moves the avatar to a new position and (optional) orientation in the domain, with safe landing.
2003  * @function MyAvatar.goToLocation
2004  * @param {MyAvatar.GoToProperties} target - The goto target.
2005  */
2006  void goToLocation(const QVariant& properties);
2007 
2008  /*@jsdoc
2009  * Moves the avatar to a new position, with safe landing, and enables collisions.
2010  * @function MyAvatar.goToLocationAndEnableCollisions
2011  * @param {Vec3} position - The new position for the avatar, in world coordinates.
2012  */
2013  void goToLocationAndEnableCollisions(const glm::vec3& newPosition);
2014 
2015  /*@jsdoc
2016  * @function MyAvatar.safeLanding
2017  * @param {Vec3} position -The new position for the avatar, in world coordinates.
2018  * @returns {boolean} <code>true</code> if the avatar was moved, <code>false</code> if it wasn't.
2019  * @deprecated This function is deprecated and will be removed.
2020  */
2021  bool safeLanding(const glm::vec3& position);
2022 
2023 
2024  /*@jsdoc
2025  * @function MyAvatar.restrictScaleFromDomainSettings
2026  * @param {object} domainSettings - Domain settings.
2027  * @deprecated This function is deprecated and will be removed.
2028  */
2029  void restrictScaleFromDomainSettings(const QJsonObject& domainSettingsObject);
2030 
2031  /*@jsdoc
2032  * @function MyAvatar.clearScaleRestriction
2033  * @deprecated This function is deprecated and will be removed.
2034  */
2035  void clearScaleRestriction();
2036 
2037 
2038  /*@jsdoc
2039  * Adds a thrust to your avatar's current thrust to be applied for a short while.
2040  * @function MyAvatar.addThrust
2041  * @param {Vec3} thrust - The thrust direction and magnitude.
2042  * @deprecated This function is deprecated and will be removed. Use {@link MyAvatar|MyAvatar.motorVelocity} and related
2043  * properties instead.
2044  */
2045  // Set/Get update the thrust that will move the avatar around
2046  void addThrust(glm::vec3 newThrust) { _thrust += newThrust; };
2047 
2048  /*@jsdoc
2049  * Gets the thrust currently being applied to your avatar.
2050  * @function MyAvatar.getThrust
2051  * @returns {Vec3} The thrust currently being applied to your avatar.
2052  * @deprecated This function is deprecated and will be removed. Use {@link MyAvatar|MyAvatar.motorVelocity} and related
2053  * properties instead.
2054  */
2055  glm::vec3 getThrust() { return _thrust; };
2056 
2057  /*@jsdoc
2058  * Sets the thrust to be applied to your avatar for a short while.
2059  * @function MyAvatar.setThrust
2060  * @param {Vec3} thrust - The thrust direction and magnitude.
2061  * @deprecated This function is deprecated and will be removed. Use {@link MyAvatar|MyAvatar.motorVelocity} and related
2062  * properties instead.
2063  */
2064  void setThrust(glm::vec3 newThrust) { _thrust = newThrust; }
2065 
2066 
2067  /*@jsdoc
2068  * Updates avatar motion behavior from the Developer &gt; Avatar &gt; Enable Default Motor Control and Enable Scripted
2069  * Motor Control menu items.
2070  * @function MyAvatar.updateMotionBehaviorFromMenu
2071  */
2072  Q_INVOKABLE void updateMotionBehaviorFromMenu();
2073 
2074  /*@jsdoc
2075  * @function MyAvatar.setToggleHips
2076  * @param {boolean} enabled - Enabled.
2077  * @deprecated This function is deprecated and will be removed.
2078  */
2079  void setToggleHips(bool followHead);
2080 
2081  /*@jsdoc
2082  * Displays the base of support area debug graphics if in HMD mode. If your head goes outside this area your avatar's hips
2083  * are moved to counterbalance your avatar, and if your head moves too far then your avatar's position is moved (i.e., a
2084  * step happens).
2085  * @function MyAvatar.setEnableDebugDrawBaseOfSupport
2086  * @param {boolean} enabled - <code>true</code> to show the debug graphics, <code>false</code> to hide.
2087  */
2088  void setEnableDebugDrawBaseOfSupport(bool isEnabled);
2089 
2090  /*@jsdoc
2091  * Displays default pose debug graphics.
2092  * @function MyAvatar.setEnableDebugDrawDefaultPose
2093  * @param {boolean} enabled - <code>true</code> to show the debug graphics, <code>false</code> to hide.
2094  */
2095  void setEnableDebugDrawDefaultPose(bool isEnabled);
2096 
2097  /*@jsdoc
2098  * Displays animation debug graphics. By default, the animation poses used for rendering are displayed. However,
2099  * {@link MyAvatar.setDebugDrawAnimPoseName} can be used to set a specific animation node to display.
2100  * @function MyAvatar.setEnableDebugDrawAnimPose
2101  * @param {boolean} enabled - <code>true</code> to show the debug graphics, <code>false</code> to hide.
2102  */
2103  void setEnableDebugDrawAnimPose(bool isEnabled);
2104 
2105  /*@jsdoc
2106  * Sets the animation node to display when animation debug graphics are enabled with
2107  * {@link MyAvatar.setEnableDebugDrawAnimPose}.
2108  * @function MyAvatar.setDebugDrawAnimPoseName
2109  * @param {string} poseName - The name of the animation node to display debug graphics for. Use <code>""</code> to reset to
2110  * default.
2111  */
2112  void setDebugDrawAnimPoseName(QString poseName);
2113 
2114  /*@jsdoc
2115  * Displays position debug graphics.
2116  * @function MyAvatar.setEnableDebugDrawPosition
2117  * @param {boolean} enabled - <code>true</code> to show the debug graphics, <code>false</code> to hide.
2118  */
2119  void setEnableDebugDrawPosition(bool isEnabled);
2120 
2121  /*@jsdoc
2122  * Displays controller hand target debug graphics.
2123  * @function MyAvatar.setEnableDebugDrawHandControllers
2124  * @param {boolean} enabled - <code>true</code> to show the debug graphics, <code>false</code> to hide.
2125  */
2126  void setEnableDebugDrawHandControllers(bool isEnabled);
2127 
2128  /*@jsdoc
2129  * Displays sensor-to-world matrix debug graphics.
2130  * @function MyAvatar.setEnableDebugDrawSensorToWorldMatrix
2131  * @param {boolean} enable - <code>true</code> to show the debug graphics, <code>false</code> to hide.
2132  */
2133  void setEnableDebugDrawSensorToWorldMatrix(bool isEnabled);
2134 
2135  /*@jsdoc
2136  * Displays inverse kinematics targets debug graphics.
2137  * @function MyAvatar.setEnableDebugDrawIKTargets
2138  * @param {boolean} enabled - <code>true</code> to show the debug graphics, <code>false</code> to hide.
2139  */
2140  void setEnableDebugDrawIKTargets(bool isEnabled);
2141 
2142  /*@jsdoc
2143  * Displays inverse kinematics constraints debug graphics.
2144  * @function MyAvatar.setEnableDebugDrawIKConstraints
2145  * @param {boolean} enabled - <code>true</code> to show the debug graphics, <code>false</code> to hide.
2146  */
2147  void setEnableDebugDrawIKConstraints(bool isEnabled);
2148 
2149  /*@jsdoc
2150  * Displays inverse kinematics chains debug graphics.
2151  * @function MyAvatar.setEnableDebugDrawIKChains
2152  * @param {boolean} enabled - <code>true</code> to show the debug graphics, <code>false</code> to hide.
2153  */
2154  void setEnableDebugDrawIKChains(bool isEnabled);
2155 
2156  /*@jsdoc
2157  * Displays detailed collision debug graphics.
2158  * @function MyAvatar.setEnableDebugDrawDetailedCollision
2159  * @param {boolean} enabled - <code>true</code> to show the debug graphics, <code>false</code> to hide.
2160  */
2161  void setEnableDebugDrawDetailedCollision(bool isEnabled);
2162 
2163  /*@jsdoc
2164  * Gets whether your avatar mesh is visible.
2165  * @function MyAvatar.getEnableMeshVisible
2166  * @returns {boolean} <code>true</code> if your avatar's mesh is visible, otherwise <code>false</code>.
2167  */
2168  bool getEnableMeshVisible() const override;
2169 
2170  /*@jsdoc
2171  * @comment Uses the base class's JSDoc.
2172  */
2173  void clearAvatarEntity(const QUuid& entityID, bool requiresRemovalFromTree = true) override;
2174 
2175  /*@jsdoc
2176  * Sets whether your avatar mesh is visible to you.
2177  * @function MyAvatar.setEnableMeshVisible
2178  * @param {boolean} enabled - <code>true</code> to show your avatar mesh, <code>false</code> to hide.
2179  * @example <caption>Make your avatar invisible for 10s.</caption>
2180  * MyAvatar.setEnableMeshVisible(false);
2181  * Script.setTimeout(function () {
2182  * MyAvatar.setEnableMeshVisible(true);
2183  * }, 10000);
2184  */
2185  virtual void setEnableMeshVisible(bool isEnabled) override;
2186 
2187  /*@jsdoc
2188  * Sets whether inverse kinematics (IK) is enabled for your avatar.
2189  * @function MyAvatar.setEnableInverseKinematics
2190  * @param {boolean} enabled - <code>true</code> to enable IK, <code>false</code> to disable.
2191  */
2192  void setEnableInverseKinematics(bool isEnabled);
2193 
2194 
2195  /*@jsdoc
2196  * Gets the URL of the override animation graph.
2197  * <p>See {@link https://docs.overte.org/create/avatars/custom-animations.html|Custom Avatar Animations} for
2198  * information on animation graphs.</p>
2199  * @function MyAvatar.getAnimGraphOverrideUrl
2200  * @returns {string} The URL of the override animation graph JSON file. <code>""</code> if there is no override animation
2201  * graph.
2202  */
2203  QUrl getAnimGraphOverrideUrl() const; // thread-safe
2204 
2205  /*@jsdoc
2206  * Sets the animation graph to use in preference to the default animation graph.
2207  * <p>See {@link https://docs.overte.org/create/avatars/custom-animations.html|Custom Avatar Animations} for
2208  * information on animation graphs.</p>
2209  * @function MyAvatar.setAnimGraphOverrideUrl
2210  * @param {string} url - The URL of the animation graph JSON file to use. Set to <code>""</code> to clear an override.
2211  */
2212  void setAnimGraphOverrideUrl(QUrl value); // thread-safe
2213 
2214  /*@jsdoc
2215  * Gets the URL of animation graph (i.e., the avatar animation JSON) that's currently being used for avatar animations.
2216  * <p>See {@link https://docs.overte.org/create/avatars/custom-animations.html|Custom Avatar Animations} for
2217  * information on animation graphs.</p>
2218  * @function MyAvatar.getAnimGraphUrl
2219  * @returns {string} The URL of the current animation graph JSON file.
2220  * @Example <caption>Report the current avatar animation JSON being used.</caption>
2221  * print(MyAvatar.getAnimGraphUrl());
2222  */
2223  QUrl getAnimGraphUrl() const; // thread-safe
2224 
2225  /*@jsdoc
2226  * Sets the current animation graph (i.e., the avatar animation JSON) to use for avatar animations and makes it the default.
2227  * <p>See {@link https://docs.overte.org/create/avatars/custom-animations.html|Custom Avatar Animations} for
2228  * information on animation graphs.</p>
2229  * @function MyAvatar.setAnimGraphUrl
2230  * @param {string} url - The URL of the animation graph JSON file to use.
2231  */
2232  void setAnimGraphUrl(const QUrl& url); // thread-safe
2233 
2234  /*@jsdoc
2235  * Gets your listening position for spatialized audio. The position depends on the value of the
2236  * {@link Myavatar|audioListenerMode} property.
2237  * @function MyAvatar.getPositionForAudio
2238  * @returns {Vec3} Your listening position.
2239  */
2240  glm::vec3 getPositionForAudio();
2241 
2242  /*@jsdoc
2243  * Gets the orientation of your listening position for spatialized audio. The orientation depends on the value of the
2244  * {@link Myavatar|audioListenerMode} property.
2245  * @function MyAvatar.getOrientationForAudio
2246  * @returns {Quat} The orientation of your listening position.
2247  */
2248  glm::quat getOrientationForAudio();
2249 
2250  /*@jsdoc
2251  * @function MyAvatar.setModelScale
2252  * @param {number} scale - The scale.
2253  * @deprecated This function is deprecated and will be removed.
2254  */
2255  virtual void setModelScale(float scale) override;
2256 
2257  /*@jsdoc
2258  * Gets the list of reactions names that can be triggered using {@link MyAvatar.triggerReaction}.
2259  * <p>See also: {@link MyAvatar.getBeginEndReactions}.
2260  * @function MyAvatar.getTriggerReactions
2261  * @returns {string[]} List of reaction names that can be triggered using {@link MyAvatar.triggerReaction}.
2262  * @example <caption>List the available trigger reactions.</caption>
2263  * print("Trigger reactions:", JSON.stringify(MyAvatar.getTriggerReactions()));
2264  */
2265  QStringList getTriggerReactions() const;
2266 
2267 
2268  /*@jsdoc
2269  * Gets the list of reactions names that can be enabled using {@link MyAvatar.beginReaction} and
2270  * {@link MyAvatar.endReaction}.
2271  * <p>See also: {@link MyAvatar.getTriggerReactions}.
2272  * @function MyAvatar.getBeginEndReactions
2273  * @returns {string[]} List of reaction names that can be enabled using {@link MyAvatar.beginReaction} and
2274  * {@link MyAvatar.endReaction}.
2275  * @example <caption>List the available begin-end reactions.</caption>
2276  * print("Begin-end reactions:", JSON.stringify(MyAvatar.getBeginEndReactions()));
2277  */
2278  QStringList getBeginEndReactions() const;
2279 
2280  /*@jsdoc
2281  * Plays a reaction on the avatar. Once the reaction is complete it will stop playing.
2282  * <p>Only reaction names returned by {@link MyAvatar.getTriggerReactions} are available.</p>
2283  * @function MyAvatar.triggerReaction
2284  * @param {string} reactionName - The reaction to trigger.
2285  * @returns {boolean} <code>true</code> if the reaction was played, <code>false</code> if the reaction is not supported.
2286  */
2287  bool triggerReaction(QString reactionName);
2288 
2289  /*@jsdoc
2290  * Starts playing a reaction on the avatar. The reaction will continue to play until stopped using
2291  * {@link MyAvatar.endReaction} or superseded by another reaction.
2292  * <p>Only reactions returned by {@link MyAvatar.getBeginEndReactions} are available.</p>
2293  * @function MyAvatar.beginReaction
2294  * @param {string} reactionName - The reaction to start playing.
2295  * @returns {boolean} <code>true</code> if the reaction was started, <code>false</code> if the reaction is not supported.
2296  */
2297  bool beginReaction(QString reactionName);
2298 
2299  /*@jsdoc
2300  * Stops playing a reaction that was started using {@link MyAvatar.beginReaction}.
2301  * @function MyAvatar.endReaction
2302  * @param {string} reactionName - The reaction to stop playing.
2303  * @returns {boolean} <code>true</code> if the reaction was stopped, <code>false</code> if the reaction is not supported.
2304  */
2305  bool endReaction(QString reactionName);
2306 
2307 signals:
2308 
2309  /*@jsdoc
2310  * Triggered when the {@link MyAvatar|audioListenerMode} property value changes.
2311  * @function MyAvatar.audioListenerModeChanged
2312  * @returns {Signal}
2313  */
2314  void audioListenerModeChanged();
2315 
2316  /*@jsdoc
2317  * Triggered when the walk speed set for the "AnalogPlus" control scheme changes.
2318  * @function MyAvatar.vrWalkSpeedChanged
2319  * @param {number} speed - The new walk speed set for the "AnalogPlus" control scheme.
2320  * @returns {Signal}
2321  */
2322  void vrWalkSpeedChanged(float value);
2323 
2324  /*@jsdoc
2325  * Triggered when the desktop sprint (run) speed changes.
2326  * @function MyAvatar.sprintSpeedChanged
2327  * @param {number} speed -The new sprint speed set for the current control scheme.
2328  * @returns {Signal}
2329  */
2330  void sprintSpeedChanged(float value);
2331 
2332  /*@jsdoc
2333  * Triggered when {@link MyAvatar.standingMode} is changed.
2334  * @function MyAvatar.standingMode
2335  * @param {MyAvatar.StandingMode} mode
2336  * @returns {Signal}
2337  */
2338  void standingModeChanged(MyAvatar::AllowAvatarStandingPreference mode);
2339 
2340  /*@jsdoc
2341  * @function MyAvatar.transformChanged
2342  * @returns {Signal}
2343  * @deprecated This signal is deprecated and will be removed.
2344  */
2345  void transformChanged();
2346 
2347  /*@jsdoc
2348  * Triggered when the {@link MyAvatar|collisionSoundURL} property value changes.
2349  * @function MyAvatar.newCollisionSoundURL
2350  * @param {string} url - The URL of the new collision sound.
2351  * @returns {Signal}
2352  */
2353  void newCollisionSoundURL(const QUrl& url);
2354 
2355  /*@jsdoc
2356  * Triggered when the avatar collides with an entity.
2357  * @function MyAvatar.collisionWithEntity
2358  * @param {Collision} collision - Details of the collision.
2359  * @returns {Signal}
2360  * @example <caption>Report each time your avatar collides with an entity.</caption>
2361  * MyAvatar.collisionWithEntity.connect(function (collision) {
2362  * print("Your avatar collided with an entity.");
2363  * });
2364  */
2365  void collisionWithEntity(const Collision& collision);
2366 
2367  /*@jsdoc
2368  * Triggered when collisions with the environment are enabled or disabled.
2369  * @function MyAvatar.collisionsEnabledChanged
2370  * @param {boolean} enabled - <code>true</code> if collisions with the environment are enabled, <code>false</code> if
2371  * they're not.
2372  * @returns {Signal}
2373  */
2374  void collisionsEnabledChanged(bool enabled);
2375 
2376  /*@jsdoc
2377  * Triggered when collisions with other avatars are enabled or disabled.
2378  * @function MyAvatar.otherAvatarsCollisionsEnabledChanged
2379  * @param {boolean} enabled - <code>true</code> if collisions with other avatars are enabled, <code>false</code> if they're
2380  * not.
2381  * @returns {Signal}
2382  */
2383  void otherAvatarsCollisionsEnabledChanged(bool enabled);
2384 
2385  /*@jsdoc
2386  * Triggered when the avatar's animation graph being used changes.
2387  * @function MyAvatar.animGraphUrlChanged
2388  * @param {string} url - The URL of the new animation graph JSON file.
2389  * @returns {Signal}
2390  * @example <caption>Report when the current avatar animation JSON being used changes.</caption>
2391  * MyAvatar.animGraphUrlChanged.connect(function (url) {
2392  * print("Avatar animation JSON changed to: " + url);
2393  * }); */
2394  void animGraphUrlChanged(const QUrl& url);
2395 
2396  /*@jsdoc
2397  * Triggered when the avatar has been moved to a new position by one of the MyAvatar "goTo" functions.
2398  * @function MyAvatar.positionGoneTo
2399  * @returns {Signal}
2400  */
2401  // FIXME: Better name would be goneToLocation().
2402  void positionGoneTo();
2403 
2404  /*@jsdoc
2405  * Triggered when the avatar's model finishes loading.
2406  * @function MyAvatar.onLoadComplete
2407  * @returns {Signal}
2408  */
2409  void onLoadComplete();
2410 
2411  /*@jsdoc
2412  * Triggered when the avatar's model has failed to load.
2413  * @function MyAvatar.onLoadFailed
2414  * @returns {Signal}
2415  */
2416  void onLoadFailed();
2417 
2418  /*@jsdoc
2419  * Triggered when your avatar changes from being active to being away.
2420  * @function MyAvatar.wentAway
2421  * @returns {Signal}
2422  * @example <caption>Report when your avatar goes away.</caption>
2423  * MyAvatar.wentAway.connect(function () {
2424  * print("My avatar went away");
2425  * });
2426  * // In desktop mode, pres the Esc key to go away.
2427  */
2428  void wentAway();
2429 
2430  /*@jsdoc
2431  * Triggered when your avatar changes from being away to being active.
2432  * @function MyAvatar.wentActive
2433  * @returns {Signal}
2434  */
2435  void wentActive();
2436 
2437  /*@jsdoc
2438  * Triggered when the avatar's model (i.e., {@link MyAvatar|skeletonModelURL} property value) is changed.
2439  * <p>Synonym of {@link MyAvatar.skeletonModelURLChanged|skeletonModelURLChanged}.</p>
2440  * @function MyAvatar.skeletonChanged
2441  * @returns {Signal}
2442  */
2443  void skeletonChanged();
2444 
2445  /*@jsdoc
2446  * Triggered when the avatar's dominant hand changes.
2447  * @function MyAvatar.dominantHandChanged
2448  * @param {string} hand - The dominant hand: <code>"left"</code> for the left hand, <code>"right"</code> for the right hand.
2449  * @returns {Signal}
2450  */
2451  void dominantHandChanged(const QString& hand);
2452 
2453  /*@jsdoc
2454  * Triggered when the HMD alignment for your avatar changes.
2455  * @function MyAvatar.hmdAvatarAlignmentTypeChanged
2456  * @param {string} type - <code>"head"</code> if aligning your head and your avatar's head, <code>"eyes"</code> if aligning
2457  * your eyes and your avatar's eyes.
2458  * @returns {Signal}
2459  */
2460  void hmdAvatarAlignmentTypeChanged(const QString& type);
2461 
2462  /*@jsdoc
2463  * Triggered when the avatar's <code>sensorToWorldScale</code> property value changes.
2464  * @function MyAvatar.sensorToWorldScaleChanged
2465  * @param {number} scale - The scale that transforms dimensions in the user's real world to the avatar's size in the virtual
2466  * world.
2467  * @returns {Signal}
2468  */
2469  void sensorToWorldScaleChanged(float sensorToWorldScale);
2470 
2471  /*@jsdoc
2472  * Triggered when the avatar's size changes. This can be due to the user changing the size of their avatar or the domain
2473  * limiting the size of their avatar.
2474  * @function MyAvatar.scaleChanged
2475  * @returns {Signal}
2476  */
2477  void scaleChanged();
2478 
2479  /*@jsdoc
2480  * Triggered when the hand touch effect is enabled or disabled for the avatar.
2481  * <p>The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that
2482  * it is really touching that object.</p>
2483  * @function MyAvatar.shouldDisableHandTouchChanged
2484  * @param {boolean} disabled - <code>true</code> if the hand touch effect is disabled for the avatar,
2485  * <code>false</code> if it isn't disabled.
2486  * @returns {Signal}
2487  */
2488  void shouldDisableHandTouchChanged(bool shouldDisable);
2489 
2490  /*@jsdoc
2491  * Triggered when the hand touch is enabled or disabled on a specific entity.
2492  * <p>The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that
2493  * it is really touching that object.</p>
2494  * @function MyAvatar.disableHandTouchForIDChanged
2495  * @param {Uuid} entityID - The entity that the hand touch effect has been enabled or disabled for.
2496  * @param {boolean} disabled - <code>true</code> if the hand touch effect is disabled for the entity,
2497  * <code>false</code> if it isn't disabled.
2498  * @returns {Signal}
2499  */
2500  void disableHandTouchForIDChanged(const QUuid& entityID, bool disable);
2501 
2502 private slots:
2503  void leaveDomain();
2504  void updateCollisionCapsuleCache();
2505 
2506 protected:
2507  void handleChangedAvatarEntityData();
2508  void handleCanRezAvatarEntitiesChanged(bool canRezAvatarEntities);
2509  virtual void beParentOfChild(SpatiallyNestablePointer newChild) const override;
2510  virtual void forgetChild(SpatiallyNestablePointer newChild) const override;
2511  virtual void recalculateChildCauterization() const override;
2512 
2513 private:
2514  bool updateStaleAvatarEntityBlobs() const;
2515 
2516  bool requiresSafeLanding(const glm::vec3& positionIn, glm::vec3& positionOut);
2517 
2518  virtual QByteArray toByteArrayStateful(AvatarDataDetail dataDetail, bool dropFaceTracking) override;
2519 
2520  void simulate(float deltaTime, bool inView) override;
2521  void saveAvatarUrl();
2522  virtual void render(RenderArgs* renderArgs) override;
2523  virtual bool shouldRenderHead(const RenderArgs* renderArgs) const override;
2524  void setShouldRenderLocally(bool shouldRender) { _shouldRender = shouldRender; setEnableMeshVisible(shouldRender); }
2525  bool getShouldRenderLocally() const { return _shouldRender; }
2526  void setRotationRecenterFilterLength(float length);
2527  float getRotationRecenterFilterLength() const { return _rotationRecenterFilterLength; }
2528  void setRotationThreshold(float angleRadians);
2529  float getRotationThreshold() const { return _rotationThreshold; }
2530  void setEnableStepResetRotation(bool stepReset) { _stepResetRotationEnabled = stepReset; }
2531  bool getEnableStepResetRotation() const { return _stepResetRotationEnabled; }
2532  void setEnableDrawAverageFacing(bool drawAverage) { _drawAverageFacingEnabled = drawAverage; }
2533  bool getEnableDrawAverageFacing() const { return _drawAverageFacingEnabled; }
2534  virtual bool isMyAvatar() const override { return true; }
2535  virtual bool isMyAvatarURLProtected() const override;
2536  virtual int parseDataFromBuffer(const QByteArray& buffer) override;
2537  virtual glm::vec3 getSkeletonPosition() const override;
2538  int _skeletonModelChangeCount { 0 };
2539  void sanitizeAvatarEntityProperties(EntityItemProperties& properties) const;
2540 
2541  void saveAvatarScale();
2542 
2543  glm::vec3 getScriptedMotorVelocity() const { return _scriptedMotorVelocity; }
2544  float getScriptedMotorTimescale() const { return _scriptedMotorTimescale; }
2545  QString getScriptedMotorFrame() const;
2546  QString getScriptedMotorMode() const;
2547  void setScriptedMotorVelocity(const glm::vec3& velocity);
2548  void setScriptedMotorTimescale(float timescale);
2549  void setScriptedMotorFrame(QString frame);
2550  void setScriptedMotorMode(QString mode);
2551 
2552  // Avatar Entities
2553  bool findAvatarEntity(const QString& modelURL, const QString& jointName, QUuid& entityID);
2554  void addAvatarEntitiesToTree();
2555 
2556  // FIXME: Rename to clearAvatarEntity() once the API call is removed.
2557  void clearAvatarEntityInternal(const QUuid& entityID) override;
2558 
2559  bool cameraInsideHead(const glm::vec3& cameraPosition) const;
2560 
2561  void updateEyeContactTarget(float deltaTime);
2562 
2563  // These are made private for MyAvatar so that you will use the "use" methods instead
2564  /*@jsdoc
2565  * @comment Borrows the base class's JSDoc.
2566  */
2567  Q_INVOKABLE virtual void setSkeletonModelURL(const QUrl& skeletonModelURL) override;
2568 
2569  virtual void updatePalms() override {}
2570  void lateUpdatePalms();
2571  void setSitDriveKeysStatus(bool enabled);
2572 
2573  void clampTargetScaleToDomainLimits();
2574  void clampScaleChangeToDomainLimits(float desiredScale);
2575  glm::mat4 computeCameraRelativeHandControllerMatrix(const glm::mat4& controllerSensorMatrix) const;
2576 
2577  std::array<float, MAX_DRIVE_KEYS> _driveKeys;
2578  std::bitset<MAX_DRIVE_KEYS> _disabledDriveKeys;
2579 
2580  bool _enableFlying { false };
2581  bool _flyingPrefDesktop { true };
2582  bool _flyingPrefHMD { true };
2583  bool _wasPushing { false };
2584  bool _isPushing { false };
2585  bool _isBeingPushed { false };
2586  bool _isBraking { false };
2587  bool _isAway { false };
2588 
2589  // Indicates which parts of the body are under direct control (tracked).
2590  struct {
2591  bool _feet { false }; // Left or right foot.
2592  bool _feetPreviousUpdate{ false };// Value of _feet on the previous update.
2593  bool _hips{ false };
2594  bool _leftHand{ false };
2595  bool _rightHand{ false };
2596  bool _head{ false };
2597  } _isBodyPartTracked;
2598 
2599  float _boomLength { ZOOM_DEFAULT };
2600  float _yawSpeed; // degrees/sec
2601  float _hmdYawSpeed; // degrees/sec
2602  float _pitchSpeed; // degrees/sec
2603  int _movementReference{ 0 };
2604 
2605  glm::vec3 _thrust { 0.0f }; // impulse accumulator for outside sources
2606 
2607  glm::vec3 _actionMotorVelocity; // target local-frame velocity of avatar (default controller actions)
2608  glm::vec3 _scriptedMotorVelocity; // target local-frame velocity of avatar (analog script)
2609  float _scriptedMotorTimescale; // timescale for avatar to achieve its target velocity
2610  int _scriptedMotorFrame;
2611  int _scriptedMotorMode;
2612  quint32 _motionBehaviors;
2613  QString _collisionSoundURL;
2614 
2615  SharedSoundPointer _collisionSound;
2616 
2617  MyCharacterController _characterController;
2618  int32_t _previousCollisionMask { BULLET_COLLISION_MASK_MY_AVATAR };
2619 
2620  AvatarWeakPointer _lookAtTargetAvatar;
2621  glm::vec3 _targetAvatarPosition;
2622  bool _shouldRender { true };
2623  float _oculusYawOffset;
2624 
2625  eyeContactTarget _eyeContactTarget;
2626  float _eyeContactTargetTimer { 0.0f };
2627  ThreadSafeValueCache<glm::vec3> _eyesLookAtTarget { glm::vec3() };
2628  bool _scriptControlsEyesLookAt{ false };
2629  float _scriptEyesControlTimer{ 0.0f };
2630 
2631  glm::vec3 _trackedHeadPosition;
2632 
2633  const float MAX_LOOK_AT_TIME_SCRIPT_CONTROL = 2.0f;
2634  glm::quat _lookAtPitch;
2635  glm::quat _lookAtYaw;
2636  float _lookAtYawSpeed { 0.0f };
2637  glm::vec3 _lookAtCameraTarget;
2638  glm::vec3 _lookAtScriptTarget;
2639  bool _headLookAtActive { false };
2640  bool _shouldTurnToFaceCamera { false };
2641  bool _scriptControlsHeadLookAt { false };
2642  float _scriptHeadControlTimer { 0.0f };
2643  float _firstPersonSteadyHeadTimer { 0.0f };
2644  bool _pointAtActive { false };
2645  bool _isPointTargetValid { true };
2646 
2647  Setting::Handle<float> _realWorldFieldOfView;
2648  Setting::Handle<bool> _useAdvancedMovementControls;
2649  Setting::Handle<bool> _showPlayArea;
2650 
2651  // Smoothing.
2652  const float SMOOTH_TIME_ORIENTATION = 0.5f;
2653 
2654  // Smoothing data for blending from one position/orientation to another on remote agents.
2655  float _smoothOrientationTimer;
2656  glm::quat _smoothOrientationInitial;
2657  glm::quat _smoothOrientationTarget;
2658 
2659  // private methods
2660  void updateOrientation(float deltaTime);
2661  glm::vec3 calculateScaledDirection();
2662  glm::vec3 scaleMotorSpeed(const glm::vec3 forward, const glm::vec3 right);
2663  void updateActionMotor(float deltaTime);
2664  void updatePosition(float deltaTime);
2665  void updateViewBoom();
2666  void updateCollisionSound(const glm::vec3& penetration, float deltaTime, float frequency);
2667  void initHeadBones();
2668  void initAnimGraph();
2669  void initFlowFromFST();
2670  void updateHeadLookAt(float deltaTime);
2671  void resetHeadLookAt();
2672  void resetLookAtRotation(const glm::vec3& avatarPosition, const glm::quat& avatarOrientation);
2673  void resetPointAt();
2674  static glm::vec3 aimToBlendValues(const glm::vec3& aimVector, const glm::quat& frameOrientation);
2675  void centerBodyInternal(const bool forceFollowYPos = false);
2676 
2677  // Avatar Preferences
2678  QUrl _fullAvatarURLFromPreferences;
2679  QString _fullAvatarModelName;
2680  ThreadSafeValueCache<QUrl> _currentAnimGraphUrl;
2681  ThreadSafeValueCache<QUrl> _prefOverrideAnimGraphUrl;
2682  QUrl _fstAnimGraphOverrideUrl;
2683  bool _useSnapTurn { true };
2684  bool _hoverWhenUnsupported{ false };
2685  ThreadSafeValueCache<QString> _dominantHand { DOMINANT_RIGHT_HAND };
2686  ThreadSafeValueCache<QString> _hmdAvatarAlignmentType { DEFAULT_HMD_AVATAR_ALIGNMENT_TYPE };
2687  ThreadSafeValueCache<bool> _strafeEnabled{ DEFAULT_STRAFE_ENABLED };
2688 
2689  const float ROLL_CONTROL_DEAD_ZONE_DEFAULT = 8.0f; // degrees
2690  const float ROLL_CONTROL_RATE_DEFAULT = 114.0f; // degrees / sec
2691 
2692  bool _hmdRollControlEnabled { true };
2693  float _hmdRollControlDeadZone { ROLL_CONTROL_DEAD_ZONE_DEFAULT };
2694  float _hmdRollControlRate { ROLL_CONTROL_RATE_DEFAULT };
2695  std::atomic<bool> _hasScriptedBlendShapes { false };
2696  std::atomic<float> _rotationRecenterFilterLength { 4.0f };
2697  std::atomic<float> _rotationThreshold { 0.5235f }; // 30 degrees in radians
2698  std::atomic<bool> _stepResetRotationEnabled { true };
2699  std::atomic<bool> _drawAverageFacingEnabled { false };
2700 
2701  // working copy -- see AvatarData for thread-safe _sensorToWorldMatrixCache, used for outward facing access
2702  glm::mat4 _sensorToWorldMatrix { glm::mat4() };
2703 
2704  // cache of the current HMD sensor position and orientation in sensor space.
2705  glm::mat4 _hmdSensorMatrix;
2706  glm::quat _hmdSensorOrientation;
2707  glm::vec3 _hmdSensorPosition;
2708  // cache head controller pose in sensor space
2709  glm::vec2 _headControllerFacing; // facing vector in xz plane (sensor space)
2710  glm::vec2 _headControllerFacingMovingAverage { 0.0f, 0.0f }; // facing vector in xz plane (sensor space)
2711  glm::quat _averageHeadRotation { 0.0f, 0.0f, 0.0f, 1.0f };
2712 
2713  glm::vec2 _hipToHandController { 0.0f, 1.0f }; // spine2 facing vector in xz plane (spine2 space)
2714 
2715  float _currentStandingHeight { 0.0f };
2716  bool _resetMode { true };
2717  RingBufferHistory<int> _recentModeReadings;
2718 
2719  // cache of the current body position and orientation of the avatar's body,
2720  // in sensor space.
2721  glm::mat4 _bodySensorMatrix;
2722 
2723  struct FollowHelper {
2724  FollowHelper();
2725 
2726  CharacterController::FollowTimePerType _timeRemaining;
2727 
2728  void deactivate();
2729  void deactivate(CharacterController::FollowType type);
2730  void activate(CharacterController::FollowType type, const bool snapFollow);
2731  bool isActive() const;
2732  bool isActive(CharacterController::FollowType followType) const;
2733  void decrementTimeRemaining(float dt);
2734  bool shouldActivateRotation(const MyAvatar& myAvatar, const glm::mat4& desiredBodyMatrix, const glm::mat4& currentBodyMatrix, bool& shouldSnapOut) const;
2735  bool shouldActivateVertical(const MyAvatar& myAvatar, const glm::mat4& desiredBodyMatrix, const glm::mat4& currentBodyMatrix) const;
2736  bool shouldActivateHorizontal(const MyAvatar& myAvatar,
2737  const glm::mat4& desiredBodyMatrix,
2738  const glm::mat4& currentBodyMatrix,
2739  bool& resetModeOut,
2740  bool& goToWalkingStateOut) const;
2741  void prePhysicsUpdate(MyAvatar& myAvatar, const glm::mat4& bodySensorMatrix, const glm::mat4& currentBodyMatrix, bool hasDriveInput);
2742  glm::mat4 postPhysicsUpdate(MyAvatar& myAvatar, const glm::mat4& currentBodyMatrix);
2743  bool getForceActivateRotation() const;
2744  void setForceActivateRotation(bool val);
2745  bool getForceActivateVertical() const;
2746  void setForceActivateVertical(bool val);
2747  bool getForceActivateHorizontal() const;
2748  void setForceActivateHorizontal(bool val);
2749  std::atomic<bool> _forceActivateRotation { false };
2750  std::atomic<bool> _forceActivateVertical { false };
2751  std::atomic<bool> _forceActivateHorizontal { false };
2752  std::atomic<bool> _toggleHipsFollowing { true };
2753 
2754  private:
2755  bool shouldActivateHorizontal_userSitting(const MyAvatar& myAvatar,
2756  const glm::mat4& desiredBodyMatrix,
2757  const glm::mat4& currentBodyMatrix) const;
2758  bool shouldActivateHorizontal_userStanding(const MyAvatar& myAvatar,
2759  bool& resetModeOut,
2760  bool& goToWalkingStateOut) const;
2761  };
2762 
2763  FollowHelper _follow;
2764 
2765  bool isFollowActive(CharacterController::FollowType followType) const;
2766 
2767  bool _goToPending { false };
2768  bool _physicsSafetyPending { false };
2769  bool _goToSafe { true };
2770  bool _goToFeetAjustment { false };
2771  glm::vec3 _goToPosition;
2772  glm::quat _goToOrientation;
2773 
2774  std::unordered_set<int> _headBoneSet;
2775  std::unordered_set<SpatiallyNestablePointer> _cauterizedChildrenOfHead;
2776  bool _prevShouldDrawHead;
2777  bool _rigEnabled { true };
2778 
2779  bool _enableDebugDrawBaseOfSupport { false };
2780  bool _enableDebugDrawDefaultPose { false };
2781  bool _enableDebugDrawAnimPose { false };
2782  bool _enableDebugDrawHandControllers { false };
2783  bool _enableDebugDrawSensorToWorldMatrix { false };
2784  bool _enableDebugDrawIKTargets { false };
2785  bool _enableDebugDrawIKConstraints { false };
2786  bool _enableDebugDrawIKChains { false };
2787  bool _enableDebugDrawDetailedCollision { false };
2788 
2789  ThreadSafeValueCache<QString> _debugDrawAnimPoseName;
2790 
2791  mutable bool _cauterizationNeedsUpdate { false }; // do we need to scan children and update their "cauterized" state?
2792 
2793  AudioListenerMode _audioListenerMode;
2794  glm::vec3 _customListenPosition;
2795  glm::quat _customListenOrientation;
2796 
2797  AtRestDetector _leftHandAtRestDetector;
2798  AtRestDetector _rightHandAtRestDetector;
2799 
2800  // all poses are in sensor-frame
2801  std::map<controller::Action, controller::Pose> _controllerPoseMap;
2802  mutable std::mutex _controllerPoseMapMutex;
2803  mutable std::mutex _disableHandTouchMutex;
2804 
2805  bool _centerOfGravityModelEnabled { true };
2806  bool _hmdLeanRecenterEnabled { true };
2807  bool _hmdCrouchRecenterEnabled {
2808  true
2809  }; // Is MyAvatar allowed to recenter vertically (stand) when the user is sitting in the real world.
2810  bool _sprint { false };
2811 
2812  AnimPose _prePhysicsRoomPose;
2813  std::mutex _holdActionsMutex;
2814  std::vector<AvatarActionHold*> _holdActions;
2815 
2816  float MAX_AVATAR_MOVEMENT_PER_FRAME { 30.0f };
2817  glm::vec3 priorVelocity;
2818  glm::vec3 lastPosition;
2819  bool didTeleport();
2820  bool getIsAway() const { return _isAway; }
2821  void setAway(bool value);
2822  void sendPacket(const QUuid& entityID) const override;
2823 
2824  std::mutex _pinnedJointsMutex;
2825  std::vector<int> _pinnedJoints;
2826 
2827  void updateChildCauterization(SpatiallyNestablePointer object, bool cauterize);
2828 
2829  // height of user in sensor space, when standing erect.
2830  ThreadSafeValueCache<float> _userHeight { DEFAULT_AVATAR_HEIGHT };
2831  float _averageUserHeightSensorSpace { _userHeight.get() };
2832  bool _sitStandStateChange { false };
2833 
2834  // max unscaled forward movement speed
2835  ThreadSafeValueCache<float> _defaultWalkSpeed { DESKTOP_AVATAR_DEFAULT_WALKING_SPEED };
2836  ThreadSafeValueCache<float> _defaultSprintSpeed { DESKTOP_AVATAR_DEFAULT_SPRINT_SPEED };
2837  ThreadSafeValueCache<float> _vrWalkSpeed { VR_AVATAR_DEFAULT_WALKING_SPEED };
2838 
2839  float _walkSpeedScalar { AVATAR_WALK_SPEED_SCALAR };
2840  bool _isInWalkingState { false };
2841  ThreadSafeValueCache<bool> _isInSittingState { false };
2842  ThreadSafeValueCache<MyAvatar::AllowAvatarStandingPreference> _allowAvatarStandingPreference{
2843  MyAvatar::AllowAvatarStandingPreference::Default
2844  }; // The user preference of when MyAvatar may stand.
2845  ThreadSafeValueCache<MyAvatar::AllowAvatarLeaningPreference> _allowAvatarLeaningPreference{
2846  MyAvatar::AllowAvatarLeaningPreference::Default
2847  }; // The user preference of when MyAvatar may lean.
2848  float _sitStandStateTimer { 0.0f };
2849  float _tippingPoint { _userHeight.get() };
2850 
2851  // load avatar scripts once when rig is ready
2852  bool _shouldLoadScripts { false };
2853 
2854  bool _haveReceivedHeightLimitsFromDomain { false };
2855  int _disableHandTouchCount { 0 };
2856  bool _reloadAvatarEntityDataFromSettings { true };
2857 
2858  TimePoint _nextTraitsSendWindow;
2859 
2860  Setting::Handle<QString> _dominantHandSetting;
2861  Setting::Handle<bool> _strafeEnabledSetting;
2862  Setting::Handle<QString> _hmdAvatarAlignmentTypeSetting;
2863  Setting::Handle<float> _headPitchSetting;
2864  Setting::Handle<float> _scaleSetting;
2865  Setting::Handle<float> _yawSpeedSetting;
2866  Setting::Handle<float> _hmdYawSpeedSetting;
2867  Setting::Handle<float> _cameraSensitivitySetting;
2868  Setting::Handle<float> _pitchSpeedSetting;
2869  Setting::Handle<QUrl> _fullAvatarURLSetting;
2870  Setting::Handle<QUrl> _fullAvatarModelNameSetting;
2871  Setting::Handle<QUrl> _animGraphURLSetting;
2872  Setting::Handle<QString> _displayNameSetting;
2873  Setting::Handle<QUrl> _collisionSoundURLSetting;
2874  Setting::Handle<bool> _useSnapTurnSetting;
2875  Setting::Handle<bool> _hoverWhenUnsupportedSetting;
2876  Setting::Handle<float> _userHeightSetting;
2877  Setting::Handle<bool> _flyingHMDSetting;
2878  Setting::Handle<int> _movementReferenceSetting;
2879  Setting::Handle<int> _avatarEntityCountSetting;
2880  Setting::Handle<bool> _allowTeleportingSetting { "allowTeleporting", true };
2881  Setting::Handle<float> _vrWalkSpeedSetting;
2882  std::vector<Setting::Handle<QUuid>> _avatarEntityIDSettings;
2883  std::vector<Setting::Handle<QByteArray>> _avatarEntityDataSettings;
2884  Setting::Handle<QString> _allowAvatarStandingPreferenceSetting;
2885  Setting::Handle<QString> _allowAvatarLeaningPreferenceSetting;
2886 
2887  // AvatarEntities stuff:
2888  // We cache the "map of unfortunately-formatted-binary-blobs" because they are expensive to compute
2889  // Do not confuse these with AvatarData::_packedAvatarEntityData which are in wire-format.
2890  mutable AvatarEntityMap _cachedAvatarEntityBlobs;
2891 
2892  // We collect changes to AvatarEntities and then handle them all in one spot per frame: updateAvatarEntities().
2893  // Basically this is a "transaction pattern" with an extra complication: these changes can come from two
2894  // "directions" and the "authoritative source" of each direction is different, so maintain two distinct sets of
2895  // transaction lists;
2896  //
2897  // The _entitiesToDelete/Add/Update lists are for changes whose "authoritative sources" are already
2898  // correctly stored in _cachedAvatarEntityBlobs. These come from loadAvatarEntityDataFromSettings() and
2899  // setAvatarEntityData(). These changes need to be extracted from _cachedAvatarEntityBlobs and applied to
2900  // real EntityItems.
2901  std::vector<EntityItemID> _entitiesToDelete;
2902  std::vector<EntityItemID> _entitiesToAdd;
2903  std::vector<EntityItemID> _entitiesToUpdate;
2904  //
2905  // The _cachedAvatarEntityBlobsToDelete/Add/Update lists are for changes whose "authoritative sources" are
2906  // already reflected in real EntityItems. These changes need to be propagated to _cachedAvatarEntityBlobs
2907  // and eventually to settings.
2908  std::vector<EntityItemID> _cachedAvatarEntityBlobsToDelete;
2909  std::vector<EntityItemID> _cachedAvatarEntityBlobsToAddOrUpdate;
2910  std::vector<EntityItemID> _cachedAvatarEntityBlobUpdatesToSkip;
2911  //
2912  // Also these lists for tracking delayed changes to blobs and Settings
2913  mutable std::set<EntityItemID> _staleCachedAvatarEntityBlobs;
2914  //
2915  // keep a ScriptEngine around so we don't have to instantiate on the fly (these are very slow to create/delete)
2916  // TODO: profile if it performs better when script engine is on avatar thread or on its own thread
2917  // Own thread is safer from deadlocks
2918  mutable HelperScriptEngine _helperScriptEngine;
2919 
2920  bool _needToSaveAvatarEntitySettings { false };
2921 
2922  bool _reactionTriggers[NUM_AVATAR_TRIGGER_REACTIONS] { false, false };
2923  int _reactionEnabledRefCounts[NUM_AVATAR_BEGIN_END_REACTIONS] { 0, 0, 0 };
2924 
2925  mutable std::mutex _reactionLock;
2926 
2927  // used to prevent character from jumping after endSit is called.
2928  bool _endSitKeyPressComplete { false };
2929 
2930  glm::vec3 _cameraEyesOffset;
2931  float _landingAfterJumpTime { 0.0f };
2932 
2933  QTimer _addAvatarEntitiesToTreeTimer;
2934 };
2935 
2936 Q_DECLARE_METATYPE(MyAvatar::DriveKeys)
2937 
2938 ScriptValue audioListenModeToScriptValue(ScriptEngine* engine, const AudioListenerMode& audioListenerMode);
2939 bool audioListenModeFromScriptValue(const ScriptValue& object, AudioListenerMode& audioListenerMode);
2940 
2941 ScriptValue driveKeysToScriptValue(ScriptEngine* engine, const MyAvatar::DriveKeys& driveKeys);
2942 bool driveKeysFromScriptValue(const ScriptValue& object, MyAvatar::DriveKeys& driveKeys);
2943 
2944 bool isWearableEntity(const EntityItemPointer& entity);
2945 
2946 #endif // hifi_MyAvatar_h
Abstract ID for editing model items. Used in EntityItem JS API.
Definition: EntityItemID.h:28
Provides a wrapper around script engine that does not have ScriptManager.
Definition: HelperScriptEngine.h:31
Provides an engine-independent interface for a scripting engine.
Definition: ScriptEngine.h:93
[ScriptInterface] Provides an engine-independent interface for QScriptValue
Definition: ScriptValue.h:40