"far-grab" {@link Entities.ActionType|ActionType} moves and rotates an entity to a target position and
* orientation, optionally relative to another entity. Collisions between the entity and the user's avatar are disabled during
* the far-grab.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-FarGrab
+ * @property {Uuid} otherID=null - If an entity ID, the targetPosition and targetRotation are
+ * relative to the entity's position and rotation.
+ * @property {Uuid} otherJointIndex=null - If a joint index in the otherID entity, the targetPosition
+ * and targetRotation are relative to the entity joint's position and rotation.
* @property {Vec3} targetPosition=0,0,0 - The target position.
* @property {Quat} targetRotation=0,0,0,1 - The target rotation.
- * @property {Uuid} otherID=null - If an entity ID, the targetPosition and targetRotation are
- * relative to this entity's position and rotation.
* @property {number} linearTimeScale=3.4e+38 - Controls how long it takes for the entity's position to catch up with the
* target position. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the action
* is applied using an exponential decay.
@@ -33,6 +35,7 @@
* target orientation. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the
* action is applied using an exponential decay.
*/
+// The properties are per ObjectActionTractor.
class AvatarActionFarGrab : public ObjectActionTractor {
public:
AvatarActionFarGrab(const QUuid& id, EntityItemPointer ownerEntity);
diff --git a/interface/src/avatar/AvatarActionHold.cpp b/interface/src/avatar/AvatarActionHold.cpp
index 5fb9c9a0ee..3ac9f63649 100644
--- a/interface/src/avatar/AvatarActionHold.cpp
+++ b/interface/src/avatar/AvatarActionHold.cpp
@@ -447,16 +447,16 @@ bool AvatarActionHold::updateArguments(QVariantMap arguments) {
/**jsdoc
* The "hold" {@link Entities.ActionType|ActionType} positions and rotates an entity relative to an avatar's hand.
* Collisions between the entity and the user's avatar are disabled during the hold.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-Hold
* @property {Uuid} holderID=MyAvatar.sessionUUID - The ID of the avatar holding the entity.
+ * @property {string} hand=right - The hand holding the entity: "left" or "right".
* @property {Vec3} relativePosition=0,0,0 - The target position relative to the avatar's hand.
* @property {Vec3} relativeRotation=0,0,0,1 - The target rotation relative to the avatar's hand.
* @property {number} timeScale=3.4e+38 - Controls how long it takes for the entity's position and rotation to catch up with
* the target. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the action is
* applied using an exponential decay.
- * @property {string} hand=right - The hand holding the entity: "left" or "right".
* @property {boolean} kinematic=false - If true, the entity is made kinematic during the action; the entity won't
* lag behind the hand but constraint actions such as "hinge" won't act properly.
* @property {boolean} kinematicSetVelocity=false - If true and kinematic is true, the
diff --git a/interface/src/scripting/TestScriptingInterface.h b/interface/src/scripting/TestScriptingInterface.h
index 897f955a74..dffda3ece0 100644
--- a/interface/src/scripting/TestScriptingInterface.h
+++ b/interface/src/scripting/TestScriptingInterface.h
@@ -165,14 +165,14 @@ public slots:
/**jsdoc
* Set number of cycles texture size is required to be stable
- * @function Entities.setMinimumGPUTextureMemStabilityCount
+ * @function Test.setMinimumGPUTextureMemStabilityCount
* @param {number} count - Number of cycles to wait
*/
Q_INVOKABLE void setMinimumGPUTextureMemStabilityCount(int count);
/**jsdoc
* Check whether all textures have been loaded.
- * @function Entities.isTextureLoadingComplete
+ * @function Test.isTextureLoadingComplete
* @returns {boolean} true texture memory usage is not increasing
*/
Q_INVOKABLE bool isTextureLoadingComplete();
diff --git a/libraries/entities/src/AmbientLightPropertyGroup.h b/libraries/entities/src/AmbientLightPropertyGroup.h
index 591ea6a6fa..d1e0ea0e55 100644
--- a/libraries/entities/src/AmbientLightPropertyGroup.h
+++ b/libraries/entities/src/AmbientLightPropertyGroup.h
@@ -28,7 +28,7 @@ class EntityTreeElementExtraEncodeData;
class ReadBitstreamToTreeParams;
/**jsdoc
- * Ambient light is defined by the following properties.
+ * Ambient light is defined by the following properties:
* @typedef {object} Entities.AmbientLight
* @property {number} ambientIntensity=0.5 - The intensity of the light.
* @property {string} ambientURL="" - A cube map image that defines the color of the light coming from each direction. If
diff --git a/libraries/entities/src/AnimationPropertyGroup.cpp b/libraries/entities/src/AnimationPropertyGroup.cpp
index 7e97787ff2..03cd3a0742 100644
--- a/libraries/entities/src/AnimationPropertyGroup.cpp
+++ b/libraries/entities/src/AnimationPropertyGroup.cpp
@@ -48,16 +48,18 @@ bool operator!=(const AnimationPropertyGroup& a, const AnimationPropertyGroup& b
/**jsdoc
- * The AnimationProperties are used to configure an animation.
+ * An animation is configured by the following properties:
* @typedef {object} Entities.AnimationProperties
* @property {string} url="" - The URL of the FBX file that has the animation.
+ * @property {boolean} allowTranslation=true - true to enable translations contained in the animation to be
+ * played, false to disable translations.
* @property {number} fps=30 - The speed in frames/s that the animation is played at.
* @property {number} firstFrame=0 - The first frame to play in the animation.
* @property {number} lastFrame=100000 - The last frame to play in the animation.
* @property {number} currentFrame=0 - The current frame being played in the animation.
* @property {boolean} running=false - If true then the animation should play.
- * @property {boolean} loop=true - If true then the animation should be continuously repeated in a loop.
- * @property {boolean} hold=false - If true then the rotations and translations of the last frame played should be
+ * @property {boolean} loop=true - If true then the animation is continuously repeated in a loop.
+ * @property {boolean} hold=false - If true then the rotations and translations of the last frame played are
* maintained when the animation stops playing.
*/
void AnimationPropertyGroup::copyToScriptValue(const EntityPropertyFlags& desiredProperties, QScriptValue& properties, QScriptEngine* engine, bool skipDefaults, EntityItemProperties& defaultEntityProperties) const {
diff --git a/libraries/entities/src/BloomPropertyGroup.h b/libraries/entities/src/BloomPropertyGroup.h
index a1f9b6d748..12743c9298 100644
--- a/libraries/entities/src/BloomPropertyGroup.h
+++ b/libraries/entities/src/BloomPropertyGroup.h
@@ -31,9 +31,8 @@ static const float INITIAL_BLOOM_THRESHOLD { 0.7f };
static const float INITIAL_BLOOM_SIZE { 0.9f };
/**jsdoc
- * Bloom is defined by the following properties.
+ * Bloom is defined by the following properties:
* @typedef {object} Entities.Bloom
- *
* @property {number} bloomIntensity=0.25 - The intensity of the bloom effect.
* @property {number} bloomThreshold=0.7 - The threshold for the bloom effect.
* @property {number} bloomSize=0.9 - The size of the bloom effect.
diff --git a/libraries/entities/src/EntityDynamicInterface.cpp b/libraries/entities/src/EntityDynamicInterface.cpp
index 1115559342..4586b665ee 100644
--- a/libraries/entities/src/EntityDynamicInterface.cpp
+++ b/libraries/entities/src/EntityDynamicInterface.cpp
@@ -94,47 +94,48 @@ variables. These argument variables are used by the code which is run when bull
#include "EntityItem.h"
/**jsdoc
-* An entity action may be one of the following types:
-*| Value | Type | Description | Arguments |
|---|---|---|---|
"far-grab" | Avatar action | -*Moves and rotates an entity to a target position and orientation, optionally relative to another entity. Collisions -* between the entity and the user's avatar are disabled during the far-grab. | -*{@link Entities.ActionArguments-FarGrab} |
"hold" | Avatar action | -*Positions and rotates an entity relative to an avatar's hand. Collisions between the entity and the user's avatar -* are disabled during the hold. | -*{@link Entities.ActionArguments-Hold} |
"offset" | Object action | -*Moves an entity so that it is a set distance away from a target point. | -*{@link Entities.ActionArguments-Offset} |
"tractor" | Object action | -*Moves and rotates an entity to a target position and orientation, optionally relative to another entity. | -*{@link Entities.ActionArguments-Tractor} |
"travel-oriented" | Object action | -*Orients an entity to align with its direction of travel. | -*{@link Entities.ActionArguments-TravelOriented} |
"hinge" | Object constraint | -*Lets an entity pivot about an axis or connects two entities with a hinge joint. | -*{@link Entities.ActionArguments-Hinge} |
"slider" | Object constraint | -*Lets an entity slide and rotate along an axis, or connects two entities that slide and rotate along a shared -* axis. | -*{@link Entities.ActionArguments-Slider|ActionArguments-Slider} |
"cone-twist" | Object constraint | -*Connects two entities with a joint that can move through a cone and can twist. | -*{@link Entities.ActionArguments-ConeTwist} |
"ball-socket" | Object constraint | -*Connects two entities with a ball and socket joint. | -*{@link Entities.ActionArguments-BallSocket} |
"spring" | Synonym for "tractor". Legacy value. | ||
An entity action may be one of the following types:
+ *| Value | Type | Description | Arguments |
|---|---|---|---|
"far-grab" | Avatar action | + *Moves and rotates an entity to a target position and orientation, optionally relative to another entity. Collisions + * between the entity and the user's avatar are disabled during the far-grab. | + *{@link Entities.ActionArguments-FarGrab} |
"hold" | Avatar action | + *Positions and rotates an entity relative to an avatar's hand. Collisions between the entity and the user's avatar + * are disabled during the hold. | + *{@link Entities.ActionArguments-Hold} |
"offset" | Object action | + *Moves an entity so that it is a set distance away from a target point. | + *{@link Entities.ActionArguments-Offset} |
"tractor" | Object action | + *Moves and rotates an entity to a target position and orientation, optionally relative to another entity. | + *{@link Entities.ActionArguments-Tractor} |
"travel-oriented" | Object action | + *Orients an entity to align with its direction of travel. | + *{@link Entities.ActionArguments-TravelOriented} |
"hinge" | Object constraint | + *Lets an entity pivot about an axis or connects two entities with a hinge joint. | + *{@link Entities.ActionArguments-Hinge} |
"slider" | Object constraint | + *Lets an entity slide and rotate along an axis, or connects two entities that slide and rotate along a shared + * axis. | + *{@link Entities.ActionArguments-Slider|ActionArguments-Slider} |
"cone-twist" | Object constraint | + *Connects two entities with a joint that can move through a cone and can twist. | + *{@link Entities.ActionArguments-ConeTwist} |
"ball-socket" | Object constraint | + *Connects two entities with a ball and socket joint. | + *{@link Entities.ActionArguments-BallSocket} |
"spring" | Synonym for "tractor".
+ * Deprecated. | ||
"Box", "Shape", and "Sphere" depending on changes to
- * the shape property set for entities of these types.) Read-only.
- * @property {EntityHostType} entityHostType="domain" - How this entity will behave, including if and how it is sent to other people.
- * The value can only be set at entity creation by using the entityHostType parameter in
- * {@link Entities.addEntity}. Read-only.
- * @property {boolean} avatarEntity=false - If true then the entity is an avatar entity; An avatar entity follows you to each domain you visit,
- * rendering at the same world coordinates unless it's parented to your avatar. Value cannot be changed after the entity is created.entityHostType parameter in
- * {@link Entities.addEntity}. clientOnly is an alias. Read-only.
- * @property {boolean} localEntity=false - If true then the entity is a local entity; Local entities only render for you and are not sent over the wire.
- * Value cannot be changed after the entity is created.entityHostType parameter in
- * {@link Entities.addEntity}. Read-only.
+ * @property {Entities.EntityType} type - The entity's type. You cannot change the type of an entity after it's created.
+ * However, its value may switch among "Box", "Shape", and "Sphere" depending on
+ * changes to the shape property set for entities of these types. Read-only.
+ *
+ * @property {Entities.EntityHostType} entityHostType="domain" - How the entity is hosted and sent to others for display.
+ * The value can only be set at entity creation by one of the {@link Entities.addEntity} methods. Read-only.
+ * @property {boolean} avatarEntity=false - true if the entity is an {@link Entities.EntityHostType|avatar entity},
+ * false if it isn't. The value is per the entityHostType property value, set at entity creation
+ * by one of the {@link Entities.addEntity} methods. Read-only.
+ * @property {boolean} clientOnly=false - A synonym for avatarEntity. Read-only.
+ * @property {boolean} localEntity=false - true if the entity is a {@link Entities.EntityHostType|local entity},
+ * false if it isn't. The value is per the entityHostType property value, set at entity creation
+ * by one of the {@link Entities.addEntity} methods. Read-only.
+ *
* @property {Uuid} owningAvatarID=Uuid.NULL - The session ID of the owning avatar if avatarEntity is
* true, otherwise {@link Uuid(0)|Uuid.NULL}. Read-only.
*
@@ -648,19 +648,21 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* entity's properties other than locked cannot be changed, and the entity cannot be deleted.
* @property {boolean} visible=true - Whether or not the entity is rendered. If true then the entity is rendered.
* @property {boolean} canCastShadow=true - Whether or not the entity can cast a shadow. Currently applicable only to
- * {@link Entities.EntityType|Model} and {@link Entities.EntityType|Shape} entities. Shadows are cast if inside a
- * {@link Entities.EntityType|Zone} entity with castShadows enabled in its
- * {@link Entities.EntityProperties-Zone|keyLight} property.
- * @property {boolean} isVisibleInSecondaryCamera=true - Whether or not the entity is rendered in the secondary camera. If true then the entity is rendered.
- * @property {RenderLayer} renderLayer="world" - In which layer this entity renders.
- * @property {PrimitiveMode} primitiveMode="solid" - How this entity's geometry is rendered.
- * @property {boolean} ignorePickIntersection=false - If true, picks ignore the entity.
+ * {@link Entities.EntityProperties-Model|Model} and {@link Entities.EntityProperties-Shape|Shape} entities. Shadows are
+ * cast if inside a {@link Entities.EntityProperties-Zone|Zone} entity with castShadows enabled in its
+ * keyLight property.
+ * @property {boolean} isVisibleInSecondaryCamera=true - true if the entity is rendered in the secondary camera,
+ * false if it isn't.
+ * @property {Entities.RenderLayer} renderLayer="world" - Which layer the entity renders in.
+ * @property {Entities.PrimitiveMode} primitiveMode="solid" - How the entity's geometry is rendered.
+ * @property {boolean} ignorePickIntersection=false - true if {@link Picks} and {@link RayPick} ignore the entity,
+ * false if they don't.
*
- * @property {Vec3} position=0,0,0 - The position of the entity.
- * @property {Quat} rotation=0,0,0,1 - The orientation of the entity with respect to world coordinates.
+ * @property {Vec3} position=0,0,0 - The position of the entity in world coordinates.
+ * @property {Quat} rotation=0,0,0,1 - The orientation of the entity in world coordinates.
* @property {Vec3} registrationPoint=0.5,0.5,0.5 - The point in the entity that is set to the entity's position and is rotated
- * about, {@link Vec3(0)|Vec3.ZERO} – {@link Vec3(0)|Vec3.ONE}. A value of {@link Vec3(0)|Vec3.ZERO} is the entity's
- * minimum x, y, z corner; a value of {@link Vec3(0)|Vec3.ONE} is the entity's maximum x, y, z corner.
+ * about, range {@link Vec3(0)|Vec3.ZERO} – {@link Vec3(0)|Vec3.ONE}. A value of {@link Vec3(0)|Vec3.ZERO} is the
+ * entity's minimum x, y, z corner; a value of {@link Vec3(0)|Vec3.ONE} is the entity's maximum x, y, z corner.
*
* @property {Vec3} naturalPosition=0,0,0 - The center of the entity's unscaled mesh model if it has one, otherwise
* {@link Vec3(0)|Vec3.ZERO}. Read-only.
@@ -668,81 +670,83 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* {@link Vec3(0)|Vec3.ONE}. Read-only.
*
* @property {Vec3} velocity=0,0,0 - The linear velocity of the entity in m/s with respect to world coordinates.
- * @property {number} damping=0.39347 - How much to slow down the linear velocity of an entity over time, 0.0
- * – 1.0. A higher damping value slows down the entity more quickly. The default value is for an
- * exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to 1/e = 0.368 of its
- * initial value.
+ * @property {number} damping=0.39347 - How much the linear velocity of an entity slows down over time, range
+ * 0.0 – 1.0. A higher damping value slows down the entity more quickly. The default value
+ * is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to 1/e = 0.368
+ * of its initial value.
* @property {Vec3} angularVelocity=0,0,0 - The angular velocity of the entity in rad/s with respect to its axes, about its
* registration point.
- * @property {number} angularDamping=0.39347 - How much to slow down the angular velocity of an entity over time,
+ * @property {number} angularDamping=0.39347 - How much the angular velocity of an entity slows down over time, range
* 0.0 – 1.0. A higher damping value slows down the entity more quickly. The default value
* is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to 1/e = 0.368
* of its initial value.
*
* @property {Vec3} gravity=0,0,0 - The acceleration due to gravity in m/s2 that the entity should move with, in
- * world coordinates. Set to { x: 0, y: -9.8, z: 0 } to simulate Earth's gravity. Gravity is applied to an
- * entity's motion only if its dynamic property is true. If changing an entity's
- * gravity from {@link Vec3(0)|Vec3.ZERO}, you need to give it a small velocity in order to kick
- * off physics simulation.
- * The gravity value is applied in addition to the acceleration value.
+ * world coordinates. Use a value of { x: 0, y: -9.8, z: 0 } to simulate Earth's gravity. Gravity is applied
+ * to an entity's motion only if its dynamic property is true. The gravity value is
+ * applied in addition to the acceleration value.
+ * If changing an entity's gravity from {@link Vec3(0)|Vec3.ZERO}, you need to give it a small
+ * velocity in order to kick off physics simulation.
dynamic property is
- * true. If changing an entity's acceleration from {@link Vec3(0)|Vec3.ZERO}, you need to give it
- * a small velocity in order to kick off physics simulation.
- * The acceleration value is applied in addition to the gravity value.
- * @property {number} restitution=0.5 - The "bounciness" of an entity when it collides, 0.0 –
+ * true. The acceleration value is applied in addition to the gravity value.
+ * If changing an entity's acceleration from {@link Vec3(0)|Vec3.ZERO}, you need to give it a small
+ * velocity in order to kick off physics simulation.
+ * @property {number} restitution=0.5 - The "bounciness" of an entity when it collides, range Warning: Other apps may also use this property, so make sure you handle data stored by other apps:
+ * edit only your bit and leave the rest of the data intact. You can use Deprecated: Use PolyLines instead. To apply a material to an entity, set the material entity's If the string represents an array (starts with 0.0 –
* 0.99. The higher the value, the more bouncy.
- * @property {number} friction=0.5 - How much to slow down an entity when it's moving against another, 0.0 –
- * 10.0. The higher the value, the more quickly it slows down. Examples: 0.1 for ice,
+ * @property {number} friction=0.5 - How much an entity slows down when it's moving against another, range 0.0
+ * – 10.0. The higher the value, the more quickly it slows down. Examples: 0.1 for ice,
* 0.9 for sandpaper.
- * @property {number} density=1000 - The density of the entity in kg/m3, 100 for balsa wood –
- * 10000 for silver. The density is used in conjunction with the entity's bounding box volume to work out its
- * mass in the application of physics.
+ * @property {number} density=1000 - The density of the entity in kg/m3, range 100 for balsa wood
+ * – 10000 for silver. The density is used in conjunction with the entity's bounding box volume to work
+ * out its mass in the application of physics.
*
* @property {boolean} collisionless=false - Whether or not the entity should collide with items per its
- * collisionMask modes.
* @example property. If "projected"true then the entity does not collide. A synonym is ignoreForCollisions.
+ * collisionMask property. If true then the entity does not collide.
+ * @property {boolean} ignoreForCollisions - Synonym for collisionless.
* @property {CollisionMask} collisionMask=31 - What types of items the entity should collide with.
* @property {string} collidesWith="static,dynamic,kinematic,myAvatar,otherAvatar," - Synonym for collisionMask,
* in text format.
- * @property {string} collisionSoundURL="" - The sound to play when the entity experiences a collision. Valid file formats are
- * as per the {@link SoundCache} object.
+ * @property {string} collisionSoundURL="" - The sound that's played when the entity experiences a collision. Valid file
+ * formats are per {@link SoundObject}.
* @property {boolean} dynamic=false - Whether or not the entity should be affected by collisions. If true then
- * the entity's movement is affected by collisions. A synonym is collisionsWillMove.
+ * the entity's movement is affected by collisions.
+ * @property {boolean} collisionsWillMove - A synonym for dynamic.
*
- * @property {string} href="" - A "hifi://" metaverse address that a user is taken to when they click on the entity.
+ * @property {string} href="" - A "hifi://" metaverse address that a user is teleported to when they click on the entity.
* @property {string} description="" - A description of the href property value.
*
- * @property {string} userData="" - Used to store extra data about the entity in JSON format. WARNING: Other apps such as the
- * Create app can also use this property, so make sure you handle data stored by other apps — edit only your bit and
- * leave the rest of the data intact. You can use JSON.parse() to parse the string into a JavaScript object
- * which you can manipulate the properties of, and use JSON.stringify() to convert the object into a string to
- * put in the property.
+ * @property {string} userData="" - Used to store extra data about the entity in JSON format.
+ * JSON.parse() to parse the string into
+ * a JavaScript object which you can manipulate the properties of, and use JSON.stringify() to convert the
+ * object into a string to put back in the property.userData, but only accessible by server entity scripts, assignment
+ * client scripts, and users who have "Can Get and Set Private User Data" permissions in the domain.
*
* @property {string} script="" - The URL of the client entity script, if any, that is attached to the entity.
- * @property {number} scriptTimestamp=0 - Intended to be used to indicate when the client entity script was loaded. Should be
+ * @property {number} scriptTimestamp=0 - Used to indicate when the client entity script was loaded. Should be
* an integer number of milliseconds since midnight GMT on January 1, 1970 (e.g., as supplied by Date.now().
* If you update the property's value, the script is re-downloaded and reloaded. This is how the "reload"
* button beside the "script URL" field in properties tab of the Create app works.
* @property {string} serverScripts="" - The URL of the server entity script, if any, that is attached to the entity.
*
- * @property {Uuid} parentID=Uuid.NULL - The ID of the entity or avatar that this entity is parented to. {@link Uuid(0)|Uuid.NULL}
- * if the entity is not parented.
- * @property {number} parentJointIndex=65535 - The joint of the entity or avatar that this entity is parented to. Use
+ * @property {Uuid} parentID=Uuid.NULL - The ID of the entity or avatar that the entity is parented to.
+ * {@link Uuid(0)|Uuid.NULL} if the entity is not parented.
+ * @property {number} parentJointIndex=65535 - The joint of the entity or avatar that the entity is parented to. Use
* 65535 or -1 to parent to the entity or avatar's position and orientation rather than a joint.
* @property {Vec3} localPosition=0,0,0 - The position of the entity relative to its parent if the entity is parented,
- * otherwise the same value as position. If the entity is parented to an avatar and is an avatarEntity
+ * otherwise the same value as position. If the entity is parented to an avatar and is an avatar entity
* so that it scales with the avatar, this value remains the original local position value while the avatar scale changes.
* @property {Quat} localRotation=0,0,0,1 - The rotation of the entity relative to its parent if the entity is parented,
* otherwise the same value as rotation.
* @property {Vec3} localVelocity=0,0,0 - The velocity of the entity relative to its parent if the entity is parented,
* otherwise the same value as velocity.
* @property {Vec3} localAngularVelocity=0,0,0 - The angular velocity of the entity relative to its parent if the entity is
- * parented, otherwise the same value as position.
+ * parented, otherwise the same value as angularVelocity.
* @property {Vec3} localDimensions - The dimensions of the entity. If the entity is parented to an avatar and is an
- * avatarEntity so that it scales with the avatar, this value remains the original dimensions value while the
+ * avatar entity so that it scales with the avatar, this value remains the original dimensions value while the
* avatar scale changes.
*
* @property {Entities.BoundingBox} boundingBox - The axis-aligned bounding box that tightly encloses the entity.
@@ -753,57 +757,59 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* unnecessary entity server updates. Scripts should not change this property's value.
*
* @property {string} actionData="" - Base-64 encoded compressed dump of the actions associated with the entity. This property
- * is typically not used in scripts directly; rather, functions that manipulate an entity's actions update it.
- * The size of this property increases with the number of actions. Because this property value has to fit within a High
- * Fidelity datagram packet there is a limit to the number of actions that an entity can have, and edits which would result
- * in overflow are rejected. Read-only.
+ * is typically not used in scripts directly; rather, functions that manipulate an entity's actions update it, e.g.,
+ * {@link Entities.addAction}. The size of this property increases with the number of actions. Because this property value
+ * has to fit within a High Fidelity datagram packet there is a limit to the number of actions that an entity can have, and
+ * edits which would result in overflow are rejected. Read-only.
* @property {Entities.RenderInfo} renderInfo - Information on the cost of rendering the entity. Currently information is only
* provided for Model entities. Read-only.
*
- * @property {boolean} cloneable=false - If true then the entity can be cloned via {@link Entities.cloneEntity}.
+ * @property {boolean} cloneable=false - If true then the domain or avatar entity can be cloned via
+ * {@link Entities.cloneEntity}.
* @property {number} cloneLifetime=300 - The entity lifetime for clones created from this entity.
* @property {number} cloneLimit=0 - The total number of clones of this entity that can exist in the domain at any given time.
* @property {boolean} cloneDynamic=false - If true then clones created from this entity will have their
* dynamic property set to true.
* @property {boolean} cloneAvatarEntity=false - If true then clones created from this entity will be created as
- * avatar entities: their avatarEntity property will be set to true.
+ * avatar entities.
* @property {Uuid} cloneOriginID - The ID of the entity that this entity was cloned from.
*
- * @property {Entities.Grab} grab - The grab-related properties.
+ * @property {Entities.Grab} grab - The entity's grab-related properties.
*
* @property {string} itemName="" - Certifiable name of the Marketplace item.
* @property {string} itemDescription="" - Certifiable description of the Marketplace item.
* @property {string} itemCategories="" - Certifiable category of the Marketplace item.
- * @property {string} itemArtist="" - Certifiable artist that created the Marketplace item.
+ * @property {string} itemArtist="" - Certifiable artist that created the Marketplace item.
* @property {string} itemLicense="" - Certifiable license URL for the Marketplace item.
* @property {number} limitedRun=4294967295 - Certifiable maximum integer number of editions (copies) of the Marketplace item
* allowed to be sold.
* @property {number} editionNumber=0 - Certifiable integer edition (copy) number or the Marketplace item. Each copy sold in
* the Marketplace is numbered sequentially, starting at 1.
* @property {number} entityInstanceNumber=0 - Certifiable integer instance number for identical entities in a Marketplace
- * item. A Marketplace item may have identical parts. If so, then each is numbered sequentially with an instance number.
+ * item. A Marketplace item may have multiple, identical parts. If so, then each is numbered sequentially with an instance
+ * number.
* @property {string} marketplaceID="" - Certifiable UUID for the Marketplace item, as used in the URL of the item's download
* and its Marketplace Web page.
* @property {string} certificateID="" - Hash of the entity's static certificate JSON, signed by the artist's private key.
* @property {number} staticCertificateVersion=0 - The version of the method used to generate the certificateID.
*
- * @see The different entity types have additional properties as follows:
+ * @comment The different entity types have additional properties as follows:
* @see {@link Entities.EntityProperties-Box|EntityProperties-Box}
- * @see {@link Entities.EntityProperties-Sphere|EntityProperties-Sphere}
- * @see {@link Entities.EntityProperties-Shape|EntityProperties-Shape}
- * @see {@link Entities.EntityProperties-Model|EntityProperties-Model}
- * @see {@link Entities.EntityProperties-Text|EntityProperties-Text}
+ * @see {@link Entities.EntityProperties-Gizmo|EntityProperties-Gizmo}
+ * @see {@link Entities.EntityProperties-Grid|EntityProperties-Grid}
* @see {@link Entities.EntityProperties-Image|EntityProperties-Image}
- * @see {@link Entities.EntityProperties-Web|EntityProperties-Web}
- * @see {@link Entities.EntityProperties-ParticleEffect|EntityProperties-ParticleEffect}
+ * @see {@link Entities.EntityProperties-Light|EntityProperties-Light}
* @see {@link Entities.EntityProperties-Line|EntityProperties-Line}
+ * @see {@link Entities.EntityProperties-Material|EntityProperties-Material}
+ * @see {@link Entities.EntityProperties-Model|EntityProperties-Model}
+ * @see {@link Entities.EntityProperties-ParticleEffect|EntityProperties-ParticleEffect}
* @see {@link Entities.EntityProperties-PolyLine|EntityProperties-PolyLine}
* @see {@link Entities.EntityProperties-PolyVox|EntityProperties-PolyVox}
- * @see {@link Entities.EntityProperties-Grid|EntityProperties-Grid}
- * @see {@link Entities.EntityProperties-Gizmo|EntityProperties-Gizmo}
- * @see {@link Entities.EntityProperties-Light|EntityProperties-Light}
+ * @see {@link Entities.EntityProperties-Shape|EntityProperties-Shape}
+ * @see {@link Entities.EntityProperties-Sphere|EntityProperties-Sphere}
+ * @see {@link Entities.EntityProperties-Text|EntityProperties-Text}
+ * @see {@link Entities.EntityProperties-Web|EntityProperties-Web}
* @see {@link Entities.EntityProperties-Zone|EntityProperties-Zone}
- * @see {@link Entities.EntityProperties-Material|EntityProperties-Material}
*/
/**jsdoc
@@ -812,20 +818,23 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* when the entity is created. If its shape property value is subsequently changed then the entity's
* type will be reported as "Sphere" if the shape is set to "Sphere",
* otherwise it will be reported as "Shape".
+ *
* @typedef {object} Entities.EntityProperties-Box
+ * @see {@link Entities.EntityProperties-Shape|EntityProperties-Shape}
*/
/**jsdoc
- * The "Light" {@link Entities.EntityType|EntityType} adds local lighting effects.
- * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ * The "Light" {@link Entities.EntityType|EntityType} adds local lighting effects. It has properties in addition
+ * to the common {@link Entities.EntityProperties|EntityProperties}.
+ *
* @typedef {object} Entities.EntityProperties-Light
- * @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. Entity surface outside these dimensions are not lit
+ * @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. Surfaces outside these dimensions are not lit
* by the light.
* @property {Color} color=255,255,255 - The color of the light emitted.
* @property {number} intensity=1 - The brightness of the light.
* @property {number} falloffRadius=0.1 - The distance from the light's center at which intensity is reduced by 25%.
* @property {boolean} isSpotlight=false - If true then the light is directional, emitting along the entity's
- * local negative z-axis; otherwise the light is a point light which emanates in all directions.
+ * local negative z-axis; otherwise, the light is a point light which emanates in all directions.
* @property {number} exponent=0 - Affects the softness of the spotlight beam: the higher the value the softer the beam.
* @property {number} cutoff=1.57 - Affects the size of the spotlight beam: the higher the value the larger the beam.
* @example "Line" {@link Entities.EntityType|EntityType} draws thin, straight lines between a sequence of two or more
- * points. Deprecated: Use PolyLines instead.
- * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ * points. It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ * linePoints.
@@ -871,41 +881,46 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
*/
/**jsdoc
- * The "Material" {@link Entities.EntityType|EntityType} modifies the existing materials on entities and avatars.
- * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
- * To apply a material to an entity, set the material entity's parentID property to the entity ID.
+ * The "Material" {@link Entities.EntityType|EntityType} modifies existing materials on entities and avatars. It
+ * has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ * parentID property to the entity ID.
* To apply a material to an avatar, set the material entity's parentID property to the avatar's session UUID.
* To apply a material to your avatar such that it persists across domains and log-ins, create the material as an avatar entity
- * by setting the entityHostType parameter in {@link Entities.addEntity} to "avatar".
- * Material entities render as non-scalable spheres if they don't have their parent set.
+ * by setting the entityHostType parameter in {@link Entities.addEntity} to "avatar" and set the
+ * entity's parentID property to MyAvatar.SELF_ID.
+ * Material entities render as non-scalable spheres if they don't have their parent set.#name to the URL, the
- * material with that name in the {@link MaterialResource} will be applied to the entity.
- * Alternatively, set the property value to "materialData" to use the materialData property
- * for the {@link MaterialResource} values.
- * @property {number} priority=0 - The priority for applying the material to its parent. Only the highest priority material is
+ * @property {Vec3} dimensions=0.1,0.1,0.1 - Used when materialMappingMode == "projected".
+ * @property {string} materialURL="" - URL to a {@link Entities.MaterialResource|MaterialResource}. If you append
+ * "#name" to the URL, the material with that name in the {@link Entities.MaterialResource|MaterialResource}
+ * will be applied to the entity. Alternatively, set the property value to "materialData" to use the
+ * materialData property for the {@link Entities.MaterialResource|MaterialResource} values.
+ * @property {string} materialData="" - Used to store {@link Entities.MaterialResource|MaterialResource} data as a JSON string.
+ * You can use JSON.parse() to parse the string into a JavaScript object which you can manipulate the
+ * properties of, and use JSON.stringify() to convert the object into a string to put in the property.
+ * @property {number} priority=0 - The priority for applying the material to its parent. Only the highest priority material is
* applied, with materials of the same priority randomly assigned. Materials that come with the model have a priority of
* 0.
* @property {string} parentMaterialName="0" - Selects the mesh part or parts within the parent to which to apply the material.
* If in the format "mat::string", all mesh parts with material name "string" are replaced.
- * Otherwise the property value is parsed as an unsigned integer, specifying the mesh part index to modify. If "all",
- * all mesh parts will be replaced. If an array (starts with "[" and ends with "]"), the string will be
- * split at each "," and each element will be parsed as either a number or a string if it starts with
- * "mat::". In other words, "[0,1,mat::string,mat::string2]" will replace mesh parts 0 and 1, and any
- * mesh parts with material "string" or "string2". Do not put spaces around the commas. Invalid values
- * are parsed to 0.
+ * If "all" then all mesh parts are replaced.
+ * Otherwise the property value is parsed as an unsigned integer, specifying the mesh part index to modify.
+ * "[" and ends with "]"), the string is split
+ * at each "," and each element parsed as either a number or a string if it starts with "mat::".
+ * For example, "[0,1,mat::string,mat::string2]" will replace mesh parts 0 and 1, and any mesh parts with
+ * material "string" or "string2". Do not put spaces around the commas. Invalid values are parsed
+ * to 0."uv" or
- * "projected". In "uv" mode, the material will be evaluated within the UV space of the mesh it is applied to. In
- * "projected" mode, the 3D transform of the Material Entity will be used to evaluate the texture coordinates for the material.
+ * "projected". In "uv" mode, the material is evaluated within the UV space of the mesh it is
+ * applied to. In "projected" mode, the 3D transform (position, rotation, and dimensions) of the Material
+ * entity is used to evaluate the texture coordinates for the material.
* @property {Vec2} materialMappingPos=0,0 - Offset position in UV-space of the top left of the material, range
* { x: 0, y: 0 } – { x: 1, y: 1 }.
* @property {Vec2} materialMappingScale=1,1 - How much to scale the material within the parent's UV-space.
* @property {number} materialMappingRot=0 - How much to rotate the material within the parent's UV-space, in degrees.
- * @property {string} materialData="" - Used to store {@link MaterialResource} data as a JSON string. You can use
- * JSON.parse() to parse the string into a JavaScript object which you can manipulate the properties of, and
- * use JSON.stringify() to convert the object into a string to put in the property.
- * @property {boolean} materialRepeat=true - If true, the material will repeat. If false, fragments outside of texCoord 0 - 1 will be discarded.
- * Works in both "uv" and "projected" modes.
+ * @property {boolean} materialRepeat=true - If true, the material repeats. If false, fragments
+ * outside of texCoord 0 – 1 will be discarded. Works in both "uv" and
"Model" {@link Entities.EntityType|EntityType} displays an FBX or OBJ model.
- * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ * The "Model" {@link Entities.EntityType|EntityType} displays a glTF, FBX, or OBJ model. When adding an entity,
+ * if no dimensions value is specified then the model is automatically sized to its
+ * {@link Entities.EntityProperties|naturalDimensions}. It has properties in addition to the common
+ * {@link Entities.EntityProperties|EntityProperties}.
+ *
* @typedef {object} Entities.EntityProperties-Model
* @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. When adding an entity, if no dimensions
* value is specified then the model is automatically sized to its
* {@link Entities.EntityProperties|naturalDimensions}.
- * @property {Vec3} modelScale - The scale factor applied to the model's dimensions. Deprecated.
- * @property {Color} color=255,255,255 - Currently not used.
- * @property {string} modelURL="" - The URL of the FBX of OBJ model. Baked FBX models' URLs end in ".baked.fbx".Deprecated: This property is deprecated and will be removed.
* @property {string} textures="" - A JSON string of texture name, URL pairs used when rendering the model in place of the * model's original textures. Use a texture name from theoriginalTextures property to override that texture.
* Only the texture names and URLs to be overridden need be specified; original textures are used where there are no
@@ -948,6 +968,7 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* @property {string} originalTextures="{}" - A JSON string of texture name, URL pairs used in the model. The property value is
* filled in after the entity has finished rezzing (i.e., textures have loaded). You can use JSON.parse() to
* parse the JSON string into a JavaScript object of name, URL pairs. Read-only.
+ * @property {Color} color=255,255,255 - Currently not used.
*
* @property {ShapeType} shapeType="none" - The shape of the collision hull used if collisions are enabled.
* @property {string} compoundShapeURL="" - The model file to use for the compound shape if shapeType is
@@ -955,22 +976,22 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
*
* @property {Entities.AnimationProperties} animation - An animation to play on the model.
*
- * @property {Quat[]} jointRotations=[] - Joint rotations applied to the model; [] if none are applied or the
+ * @property {Quat[]} jointRotations=[]] - Joint rotations applied to the model; [] if none are applied or the
* model hasn't loaded. The array indexes are per {@link Entities.getJointIndex|getJointIndex}. Rotations are relative to
- * each joint's parent.jointRotationsSet value to true.
- * @property {boolean[]} jointRotationsSet=[] - true values for joints that have had rotations applied,
+ * each joint's parent.
+ * Joint rotations can be set by {@link Entities.setLocalJointRotation|setLocalJointRotation} and similar functions, or
+ * by setting the value of this property. If you set a joint rotation using this property you also need to set the
+ * corresponding jointRotationsSet value to true.
true values for joints that have had rotations applied,
* false otherwise; [] if none are applied or the model hasn't loaded. The array indexes are per
* {@link Entities.getJointIndex|getJointIndex}.
- * @property {Vec3[]} jointTranslations=[] - Joint translations applied to the model; [] if none are applied or
+ * @property {Vec3[]} jointTranslations=[]] - Joint translations applied to the model; [] if none are applied or
* the model hasn't loaded. The array indexes are per {@link Entities.getJointIndex|getJointIndex}. Rotations are relative
- * to each joint's parent.Joint translations can be set by {@link Entities.setLocalJointTranslation|setLocalJointTranslation} and similar
* functions, or by setting the value of this property. If you set a joint translation using this property you also need to
- * set the corresponding jointTranslationsSet value to true.
- * @property {boolean[]} jointTranslationsSet=[] - true values for joints that have had translations applied,
+ * set the corresponding jointTranslationsSet value to true.
true values for joints that have had translations applied,
* false otherwise; [] if none are applied or the model hasn't loaded. The array indexes are per
* {@link Entities.getJointIndex|getJointIndex}.
* @property {boolean} relayParentJoints=false - If true and the entity is parented to an avatar, then the
@@ -990,98 +1011,103 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
*/
/**jsdoc
- * The "ParticleEffect" {@link Entities.EntityType|EntityType} displays a particle system that can be used to
+ * The "ParticleEffect" {@link Entities.EntityType|EntityType} displays a particle system that can be used to
* simulate things such as fire, smoke, snow, magic spells, etc. The particles emanate from an ellipsoid or part thereof.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ *
* @typedef {object} Entities.EntityProperties-ParticleEffect
-
- * @property {boolean} isEmitting=true - If true then particles are emitted.
+ * @property {boolean} isEmitting=true - true if particles are being emitted, false if they aren't.
* @property {number} maxParticles=1000 - The maximum number of particles to render at one time. Older particles are deleted if
* necessary when new ones are created.
* @property {number} lifespan=3s - How long, in seconds, each particle lives.
* @property {number} emitRate=15 - The number of particles per second to emit.
* @property {number} emitSpeed=5 - The speed, in m/s, that each particle is emitted at.
- * @property {number} speedSpread=1 - The spread in speeds at which particles are emitted at. If emitSpeed == 5
- * and speedSpread == 1, particles will be emitted with speeds in the range 4m/s – 6m/s.
+ * @property {number} speedSpread=1 - The spread in speeds at which particles are emitted at. For example, if
+ * emitSpeed == 5 and speedSpread == 1, particles will be emitted with speeds in the range
+ * 4 – 6m/s.
* @property {Vec3} emitAcceleration=0,-9.8,0 - The acceleration that is applied to each particle during its lifetime. The
* default is Earth's gravity value.
- * @property {Vec3} accelerationSpread=0,0,0 - The spread in accelerations that each particle is given. If
+ * @property {Vec3} accelerationSpread=0,0,0 - The spread in accelerations that each particle is given. For example, if
* emitAccelerations == {x: 0, y: -9.8, z: 0} and accelerationSpread ==
* {x: 0, y: 1, z: 0}, each particle will have an acceleration in the range {x: 0, y: -10.8, z: 0}
* – {x: 0, y: -8.8, z: 0}.
* @property {Vec3} dimensions - The dimensions of the particle effect, i.e., a bounding box containing all the particles
- * during their lifetimes, assuming that emitterShouldTrail is false. Read-only.
+ * during their lifetimes, assuming that emitterShouldTrail == false. Read-only.
* @property {boolean} emitterShouldTrail=false - If true then particles are "left behind" as the emitter moves,
- * otherwise they stay with the entity's dimensions.
+ * otherwise they stay within the entity's dimensions.
*
* @property {Quat} emitOrientation=-0.707,0,0,0.707 - The orientation of particle emission relative to the entity's axes. By
* default, particles emit along the entity's local z-axis, and azimuthStart and azimuthFinish
* are relative to the entity's local x-axis. The default value is a rotation of -90 degrees about the local x-axis, i.e.,
* the particles emit vertically.
- * @property {Vec3} emitDimensions=0,0,0 - The dimensions of the shape from which particles are emitted. The shape is specified with
- * shapeType.
+ *
+ * @property {ShapeType} shapeType="ellipsoid" - The shape from which particles are emitted.
+ * @property {string} compoundShapeURL="" - The model file to use for the compound shape if shapeType ==
+ * "compound".
+ * @property {Vec3} emitDimensions=0,0,0 - The dimensions of the shape from which particles are emitted.
* @property {number} emitRadiusStart=1 - The starting radius within the shape at which particles start being emitted;
* range 0.0 – 1.0 for the center to the surface, respectively.
* Particles are emitted from the portion of the shape that lies between emitRadiusStart and the
* shape's surface.
* @property {number} polarStart=0 - The angle in radians from the entity's local z-axis at which particles start being emitted
* within the shape; range 0 – Math.PI. Particles are emitted from the portion of the
- * shape that lies between polarStart and polarFinish. Only used if shapeType is
- * ellipsoid or sphere.
+ * shape that lies between polarStart and polarFinish. Only used if shapeType is
+ * "ellipsoid" or "sphere".
* @property {number} polarFinish=0 - The angle in radians from the entity's local z-axis at which particles stop being emitted
* within the shape; range 0 – Math.PI. Particles are emitted from the portion of the
- * shape that lies between polarStart and polarFinish. Only used if shapeType is
- * ellipsoid or sphere.
+ * shape that lies between polarStart and polarFinish. Only used if shapeType is
+ * "ellipsoid" or "sphere".
* @property {number} azimuthStart=-Math.PI - The angle in radians from the entity's local x-axis about the entity's local
* z-axis at which particles start being emitted; range -Math.PI – Math.PI. Particles are
- * emitted from the portion of the shape that lies between azimuthStart and azimuthFinish.
- * Only used if shapeType is ellipsoid, sphere, or circle.
+ * emitted from the portion of the shape that lies between azimuthStart and azimuthFinish.
+ * Only used if shapeType is "ellipsoid", "sphere", or "circle".
* @property {number} azimuthFinish=Math.PI - The angle in radians from the entity's local x-axis about the entity's local
* z-axis at which particles stop being emitted; range -Math.PI – Math.PI. Particles are
- * emitted from the portion of the shape that lies between azimuthStart and azimuthFinish.
- * Only used if shapeType is ellipsoid, sphere, or circle..
+ * emitted from the portion of the shape that lies between azimuthStart and azimuthFinish.
+ * Only used if shapeType is "ellipsoid", "sphere", or "circle".
*
* @property {string} textures="" - The URL of a JPG or PNG image file to display for each particle. If you want transparency,
* use PNG format.
* @property {number} particleRadius=0.025 - The radius of each particle at the middle of its life.
- * @property {number} radiusStart=NaN - The radius of each particle at the start of its life. If NaN, the
+ * @property {number} radiusStart=null - The radius of each particle at the start of its life. If null, the
* particleRadius value is used.
- * @property {number} radiusFinish=NaN - The radius of each particle at the end of its life. If NaN, the
+ * @property {number} radiusFinish=null - The radius of each particle at the end of its life. If null, the
* particleRadius value is used.
- * @property {number} radiusSpread=0 - The spread in radius that each particle is given. If particleRadius == 0.5
- * and radiusSpread == 0.25, each particle will have a radius in the range 0.25 –
- * 0.75.
+ * @property {number} radiusSpread=0 - The spread in radius that each particle is given. For example, if
+ * particleRadius == 0.5 and radiusSpread == 0.25, each particle will have a radius in the range
+ * 0.25 – 0.75.
* @property {Color} color=255,255,255 - The color of each particle at the middle of its life.
- * @property {ColorFloat} colorStart={} - The color of each particle at the start of its life. If any of the component values are
- * undefined, the color value is used.
- * @property {ColorFloat} colorFinish={} - The color of each particle at the end of its life. If any of the component values are
- * undefined, the color value is used.
- * @property {Color} colorSpread=0,0,0 - The spread in color that each particle is given. If
+ * @property {ColorFloat} colorStart=null,null,null - The color of each particle at the start of its life. If any of the
+ * component values are undefined, the color value is used.
+ * @property {ColorFloat} colorFinish=null,null,null - The color of each particle at the end of its life. If any of the
+ * component values are undefined, the color value is used.
+ * @property {Color} colorSpread=0,0,0 - The spread in color that each particle is given. For example, if
* color == {red: 100, green: 100, blue: 100} and colorSpread ==
* {red: 10, green: 25, blue: 50}, each particle will have a color in the range
* {red: 90, green: 75, blue: 50} – {red: 110, green: 125, blue: 150}.
- * @property {number} alpha=1 - The alpha of each particle at the middle of its life.
- * @property {number} alphaStart=NaN - The alpha of each particle at the start of its life. If NaN, the
+ * @property {number} alpha=1 - The opacity of each particle at the middle of its life.
+ * @property {number} alphaStart=null - The opacity of each particle at the start of its life. If null, the
* alpha value is used.
- * @property {number} alphaFinish=NaN - The alpha of each particle at the end of its life. If NaN, the
+ * @property {number} alphaFinish=null - The opacity of each particle at the end of its life. If null, the
* alpha value is used.
- * @property {number} alphaSpread=0 - The spread in alpha that each particle is given. If alpha == 0.5
- * and alphaSpread == 0.25, each particle will have an alpha in the range 0.25 –
- * 0.75.
- * @property {number} particleSpin=0 - The spin of each particle at the middle of its life. In the range -2*PI – 2*PI.
- * @property {number} spinStart=NaN - The spin of each particle at the start of its life. In the range -2*PI – 2*PI.
- * If NaN, the particleSpin value is used.
- * @property {number} spinFinish=NaN - The spin of each particle at the end of its life. In the range -2*PI – 2*PI.
- * If NaN, the particleSpin value is used.
- * @property {number} spinSpread=0 - The spread in spin that each particle is given. In the range 0 – 2*PI. If particleSpin == PI
- * and spinSpread == PI/2, each particle will have a spin in the range PI/2 – 3*PI/2.
- * @property {boolean} rotateWithEntity=false - Whether or not the particles' spin will rotate with the entity. If false, when particleSpin == 0, the particles will point
- * up in the world. If true, they will point towards the entity's up vector, based on its orientation.
- * @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated.
- *
- * @property {ShapeType} shapeType="ellipsoid" - The shape of the collision hull used if collisions are enabled.
- * @property {string} compoundShapeURL="" - The model file to use for the compound shape if shapeType is
- * "compound".
+ * @property {number} alphaSpread=0 - The spread in alpha that each particle is given. For example, if
+ * alpha == 0.5 and alphaSpread == 0.25, each particle will have an alpha in the range
+ * 0.25 – 0.75.
+ * @property {Entities.Pulse} pulse - Color and alpha pulse.
+ * Deprecated: This property is deprecated and will be removed.
+ * @property {number} particleSpin=0 - The rotation of each particle at the middle of its life, range -2 * Math.PI
+ * – 2 * Math.PI radians.
+ * @property {number} spinStart=null - The rotation of each particle at the start of its life, range -2 * Math.PI
+ * – 2 * Math.PI radians. If null, the particleSpin value is used.
+ * @property {number} spinFinish=null - The rotation of each particle at the end of its life, range -2 * Math.PI
+ * – 2 * Math.PI radians. If null, the particleSpin value is used.
+ * @property {number} spinSpread=0 - The spread in spin that each particle is given, range 0 –
+ * 2 * Math.PI radians. For example, if particleSpin == Math.PI and
+ * spinSpread == Math.PI / 2, each particle will have a rotation in the range Math.PI / 2 –
+ * 3 * Math.PI / 2.
+ * @property {boolean} rotateWithEntity=false - true to make the particles' rotations relative to the entity's
+ * instantaneous rotation, false to make them relative to world coordinates. If true with
+ * particleSpin == 0, the particles keep oriented per the entity's orientation.
*
* @example Create a ball of green smoke.
* particles = Entities.addEntity({
@@ -1102,27 +1128,30 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
*/
/**jsdoc
- * The "PolyLine" {@link Entities.EntityType|EntityType} draws textured, straight lines between a sequence of
- * points.
- * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ * The "PolyLine" {@link Entities.EntityType|EntityType} draws textured, straight lines between a sequence of
+ * points. It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ *
* @typedef {object} Entities.EntityProperties-PolyLine
- * @property {Vec3} dimensions=1,1,1 - The dimensions of the entity, i.e., the size of the bounding box that contains the
- * lines drawn.
- * @property {Vec3[]} linePoints=[] - The sequence of points to draw lines between. The values are relative to the entity's
- * position. A maximum of 70 points can be specified. Must be specified in order for the entity to render.
- * @property {Vec3[]} normals=[] - The normal vectors for the line's surface at the linePoints. The values are
+ * @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity, i.e., the size of the bounding box that contains the
+ * lines drawn. Read-only.
+ * @property {Vec3[]} linePoints=[]] - The sequence of points to draw lines between. The values are relative to the entity's
+ * position. A maximum of 70 points can be specified.
+ * @property {Vec3[]} normals=[]] - The normal vectors for the line's surface at the linePoints. The values are
* relative to the entity's orientation. Must be specified in order for the entity to render.
- * @property {number[]} strokeWidths=[] - The widths, in m, of the line at the linePoints. Must be specified in
+ * @property {number[]} strokeWidths=[]] - The widths, in m, of the line at the linePoints. Must be specified in
* order for the entity to render.
- * @property {Vec3[]} strokeColors=[] - The base colors of each point, which are multiplied with the color of the texture, going from 0-1.
- * If strokeColors.length < the number of points, color is used for the remaining points.
- * @property {Color} color=255,255,255 - Used as the color for each point if strokeColors is too short.
+ * @property {Vec3[]} strokeColors=[]] - The base colors of each point, with values in the range 0.0,0.0,0.0
+ * — 1.0,1.0,1.0. These colors are multiplied with the color of the texture. If there are more line
+ * points than stroke colors, the color property value is used for the remaining points.
+ * Warning: The ordinate values are in the range 0.0 — 1.0.
+ * @property {Color} color=255,255,255 - Used as the color for each point if strokeColors doesn't have a value for
+ * the point.
* @property {string} textures="" - The URL of a JPG or PNG texture to use for the lines. If you want transparency, use PNG
* format.
* @property {boolean} isUVModeStretch=true - If true, the texture is stretched to fill the whole line, otherwise
* the texture repeats along the line.
- * @property {bool} glow=false - If true, the alpha of the strokes will drop off farther from the center.
- * @property {bool} faceCamera=false - If true, each line segment will rotate to face the camera.
+ * @property {boolean} glow=false - If true, the opacity of the strokes drops off away from the line center.
+ * @property {boolean} faceCamera=false - If true, each line segment rotates to face the camera.
* @example Draw a textured "V".
* var entity = Entities.addEntity({
* type: "PolyLine",
@@ -1147,12 +1176,13 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
*/
/**jsdoc
- * The "PolyVox" {@link Entities.EntityType|EntityType} displays a set of textured voxels.
+ * The "PolyVox" {@link Entities.EntityType|EntityType} displays a set of textured voxels.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
* If you have two or more neighboring PolyVox entities of the same size abutting each other, you can display them as joined by
- * configuring their voxelSurfaceStyle and neighbor ID properties.
- * PolyVox entities uses a library from Volumes of Fun. Their
- * library documentation may be useful to read.
+ * configuring their voxelSurfaceStyle and various neighbor ID properties.
+ * PolyVox entities uses a library from Volumes of Fun. Their
+ * library documentation may be useful to read.
+ *
* @typedef {object} Entities.EntityProperties-PolyVox
* @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity.
* @property {Vec3} voxelVolumeSize=32,32,32 - Integer number of voxels along each axis of the entity, in the range
@@ -1167,24 +1197,24 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* rejected.
* @property {Entities.PolyVoxSurfaceStyle} voxelSurfaceStyle=2 - The style of rendering the voxels' surface and how
* neighboring PolyVox entities are joined.
- * @property {string} xTextureURL="" - URL of the texture to map to surfaces perpendicular to the entity's local x-axis. JPG or
- * PNG format. If no texture is specified the surfaces display white.
- * @property {string} yTextureURL="" - URL of the texture to map to surfaces perpendicular to the entity's local y-axis. JPG or
- * PNG format. If no texture is specified the surfaces display white.
- * @property {string} zTextureURL="" - URL of the texture to map to surfaces perpendicular to the entity's local z-axis. JPG or
- * PNG format. If no texture is specified the surfaces display white.
- * @property {Uuid} xNNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's -ve local x-axis direction,
- * if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
- * @property {Uuid} yNNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's -ve local y-axis direction,
- * if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
- * @property {Uuid} zNNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's -ve local z-axis direction,
- * if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
- * @property {Uuid} xPNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's +ve local x-axis direction,
- * if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
- * @property {Uuid} yPNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's +ve local y-axis direction,
- * if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
- * @property {Uuid} zPNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's +ve local z-axis direction,
- * if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
+ * @property {string} xTextureURL="" - The URL of the texture to map to surfaces perpendicular to the entity's local x-axis.
+ * JPG or PNG format. If no texture is specified the surfaces display white.
+ * @property {string} yTextureURL="" - The URL of the texture to map to surfaces perpendicular to the entity's local y-axis.
+ * JPG or PNG format. If no texture is specified the surfaces display white.
+ * @property {string} zTextureURL="" - The URL of the texture to map to surfaces perpendicular to the entity's local z-axis.
+ * JPG or PNG format. If no texture is specified the surfaces display white.
+ * @property {Uuid} xNNeighborID=Uuid.NULL - The ID of the neighboring PolyVox entity in the entity's -ve local x-axis
+ * direction, if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
+ * @property {Uuid} yNNeighborID=Uuid.NULL - The ID of the neighboring PolyVox entity in the entity's -ve local y-axis
+ * direction, if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
+ * @property {Uuid} zNNeighborID=Uuid.NULL - The ID of the neighboring PolyVox entity in the entity's -ve local z-axis
+ * direction, if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
+ * @property {Uuid} xPNeighborID=Uuid.NULL - The ID of the neighboring PolyVox entity in the entity's +ve local x-axis
+ * direction, if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
+ * @property {Uuid} yPNeighborID=Uuid.NULL - The ID of the neighboring PolyVox entity in the entity's +ve local y-axis
+ * direction, if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
+ * @property {Uuid} zPNeighborID=Uuid.NULL - The ID of the neighboring PolyVox entity in the entity's +ve local z-axis
+ * direction, if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
* @example Create a textured PolyVox sphere.
* var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 }));
* var texture = "http://public.highfidelity.com/cozza13/tuscany/Concrete2.jpg";
@@ -1203,12 +1233,14 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The "Shape" {@link Entities.EntityType|EntityType} displays an entity of a specified shape.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ *
* @typedef {object} Entities.EntityProperties-Shape
* @property {Entities.Shape} shape="Sphere" - The shape of the entity.
* @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity.
* @property {Color} color=255,255,255 - The color of the entity.
- * @property {number} alpha=1 - The alpha of the shape.
- * @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated.
+ * @property {number} alpha=1 - The opacity of the entity, range 0.0 – 1.0.
+ * @property {Entities.Pulse} pulse - Color and alpha pulse.
+ * Deprecated: This property is deprecated and will be removed.
* @example Create a cylinder.
* var shape = Entities.addEntity({
* type: "Shape",
@@ -1225,30 +1257,39 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* when the entity is created. If its shape property value is subsequently changed then the entity's
* type will be reported as "Box" if the shape is set to "Cube",
* otherwise it will be reported as "Shape".
+ *
* @typedef {object} Entities.EntityProperties-Sphere
+ * @see {@link Entities.EntityProperties-Shape|EntityProperties-Shape}
*/
/**jsdoc
* The "Text" {@link Entities.EntityType|EntityType} displays a 2D rectangle of text in the domain.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ *
* @typedef {object} Entities.EntityProperties-Text
* @property {Vec3} dimensions=0.1,0.1,0.01 - The dimensions of the entity.
* @property {string} text="" - The text to display on the face of the entity. Text wraps if necessary to fit. New lines can be
* created using \n. Overflowing lines are not displayed.
* @property {number} lineHeight=0.1 - The height of each line of text (thus determining the font size).
* @property {Color} textColor=255,255,255 - The color of the text.
- * @property {number} textAlpha=1.0 - The text alpha.
+ * @property {number} textAlpha=1.0 - The opacity of the text.
* @property {Color} backgroundColor=0,0,0 - The color of the background rectangle.
- * @property {number} backgroundAlpha=1.0 - The background alpha.
- * @property {BillboardMode} billboardMode="none" - If "none", the entity is not billboarded. If "yaw", the entity will be
- * oriented to follow your camera around the y-axis. If "full" the entity will be oriented to face your camera. The following deprecated
- * behavior is also supported: you can also set "faceCamera" to true to set billboardMode to "yaw", and you can set
- * "isFacingAvatar" to true to set billboardMode to "full". Setting either to false sets the mode to "none"
+ * @property {number} backgroundAlpha=1.0 - The opacity of the background.
+ * @property {Entities.Pulse} pulse - Color and alpha pulse.
+ * Deprecated: This property is deprecated and will be removed.
* @property {number} leftMargin=0.0 - The left margin, in meters.
* @property {number} rightMargin=0.0 - The right margin, in meters.
* @property {number} topMargin=0.0 - The top margin, in meters.
* @property {number} bottomMargin=0.0 - The bottom margin, in meters.
- * @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated.
+ * @property {BillboardMode} billboardMode="none" - Whether the entity is billboarded to face the camera.
+ * @property {boolean} faceCamera - true if billboardMode is "yaw", otherwise
+ * false. Setting this property to false sets the billboardMode to
+ * "none".
+ * Deprecated: This property is deprecated and will be removed.
+ * @property {boolean} isFacingAvatar - true if billboardMode is "full", otherwise
+ * false. Setting this property to false sets the billboardMode to
+ * "none".
+ * Deprecated: This property is deprecated and will be removed.
* @example Create a text entity.
* var text = Entities.addEntity({
* type: "Text",
@@ -1262,28 +1303,36 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
*/
/**jsdoc
- * The "Web" {@link Entities.EntityType|EntityType} displays a browsable Web page. Each user views their own copy
- * of the Web page: if one user navigates to another page on the entity, other users do not see the change; if a video is being
- * played, users don't see it in sync.
- * The entity has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ * The "Web" {@link Entities.EntityType|EntityType} displays a browsable web page. Each user views their own copy
+ * of the web page: if one user navigates to another page on the entity, other users do not see the change; if a video is being
+ * played, users don't see it in sync. It has properties in addition to the common
+ * {@link Entities.EntityProperties|EntityProperties}.
+ *
* @typedef {object} Entities.EntityProperties-Web
* @property {Vec3} dimensions=0.1,0.1,0.01 - The dimensions of the entity.
- * @property {Color} color=255,255,255 - The color of the web surface.
- * @property {number} alpha=1 - The alpha of the web surface.
- * @property {BillboardMode} billboardMode="none" - If "none", the entity is not billboarded. If "yaw", the entity will be
- * oriented to follow your camera around the y-axis. If "full" the entity will be oriented to face your camera. The following deprecated
- * behavior is also supported: you can also set "faceCamera" to true to set billboardMode to "yaw", and you can set
- * "isFacingAvatar" to true to set billboardMode to "full". Setting either to false sets the mode to "none"
- * @property {string} sourceUrl="" - The URL of the Web page to display. This value does not change as you or others navigate
+ * @property {string} sourceUrl="" - The URL of the web page to display. This value does not change as you or others navigate
* on the Web entity.
+ * @property {Color} color=255,255,255 - The color of the web surface.
+ * @property {number} alpha=1 - The opacity of the web surface.
+ * @property {Entities.Pulse} pulse - Color and alpha pulse.
+ * Deprecated: This property is deprecated and will be removed.
+ * @property {BillboardMode} billboardMode="none" - Whether the entity is billboarded to face the camera.
+ * @property {boolean} faceCamera - true if billboardMode is "yaw", otherwise
+ * false. Setting this property to false sets the billboardMode to
+ * "none".
+ * Deprecated: This property is deprecated and will be removed.
+ * @property {boolean} isFacingAvatar - true if billboardMode is "full", otherwise
+ * false. Setting this property to false sets the billboardMode to
+ * "none".
+ * Deprecated: This property is deprecated and will be removed.
* @property {number} dpi=30 - The resolution to display the page at, in dots per inch. If you convert this to dots per meter
* (multiply by 1 / 0.0254 = 39.3701) then multiply dimensions.x and dimensions.y by that value
* you get the resolution in pixels.
- * @property {string} scriptURL="" - The URL of a JavaScript file to inject into the Web page.
- * @property {number} maxFPS=10 - The maximum update rate for the Web content, in frames/second.
+ * @property {string} scriptURL="" - The URL of a JavaScript file to inject into the web page.
+ * @property {number} maxFPS=10 - The maximum update rate for the web content, in frames/second.
* @property {WebInputMode} inputMode="touch" - The user input mode to use.
- * @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated.
- * @property {boolean} showKeyboardFocusHighlight - Whether or not to show the keyboard focus highlight when this entity has focus.
+ * @property {boolean} showKeyboardFocusHighlight=true - true to highlight the entity when it has keyboard focus,
+ * false to not display the highlight.
* @example Create a Web entity displaying at 1920 x 1080 resolution.
* var METERS_TO_INCHES = 39.3701;
* var entity = Entities.addEntity({
@@ -1303,74 +1352,54 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The "Zone" {@link Entities.EntityType|EntityType} is a volume of lighting effects and avatar permissions.
- * Avatar interaction events such as {@link Entities.enterEntity} are also often used with a Zone entity.
- * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
- * @typedef {object} Entities.EntityProperties-Zone
- * @property {Vec3} dimensions=0.1,0.1,0.1 - The size of the volume in which the zone's lighting effects and avatar permissions
- * have effect.
+ * Avatar interaction events such as {@link Entities.enterEntity} are also often used with a Zone entity. It has properties in
+ * addition to the common {@link Entities.EntityProperties|EntityProperties}.
*
- * @property {ShapeType} shapeType="box" - The shape of the volume in which the zone's lighting effects and avatar
+ * @typedef {object} Entities.EntityProperties-Zone
+ * @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the volume in which the zone's lighting effects and avatar
+ * permissions have effect.
+ *
+ * @property {ShapeType} shapeType="box" - The shape of the volume in which the zone's lighting effects and avatar
* permissions have effect. Reverts to the default value if set to "none", or set to "compound"
* and compoundShapeURL is "".
* @property {string} compoundShapeURL="" - The model file to use for the compound shape if shapeType is
* "compound".
*
- * @property {string} keyLightMode="inherit" - Configures the key light in the zone. Possible values:
- * "inherit": The key light from any enclosing zone continues into this zone.
- * "disabled": The key light from any enclosing zone and the key light of this zone are disabled in this
- * zone.
- * "enabled": The key light properties of this zone are enabled, overriding the key light of from any
- * enclosing zone.
+ * @property {Entities.ComponentMode} keyLightMode="inherit" - Configures the key light in the zone.
* @property {Entities.KeyLight} keyLight - The key light properties of the zone.
*
- * @property {string} ambientLightMode="inherit" - Configures the ambient light in the zone. Possible values:
- * "inherit": The ambient light from any enclosing zone continues into this zone.
- * "disabled": The ambient light from any enclosing zone and the ambient light of this zone are disabled in
- * this zone.
- * "enabled": The ambient light properties of this zone are enabled, overriding the ambient light from any
- * enclosing zone.
+ * @property {Entities.ComponentMode} ambientLightMode="inherit" - Configures the ambient light in the zone.
* @property {Entities.AmbientLight} ambientLight - The ambient light properties of the zone.
*
- * @property {string} skyboxMode="inherit" - Configures the skybox displayed in the zone. Possible values:
- * "inherit": The skybox from any enclosing zone is dislayed in this zone.
- * "disabled": The skybox from any enclosing zone and the skybox of this zone are disabled in this zone.
- * "enabled": The skybox properties of this zone are enabled, overriding the skybox from any enclosing zone.
+ * @property {Entities.ComponentMode} skyboxMode="inherit" - Configures the skybox displayed in the zone.
* @property {Entities.Skybox} skybox - The skybox properties of the zone.
*
- * @property {string} hazeMode="inherit" - Configures the haze in the zone. Possible values:
- * "inherit": The haze from any enclosing zone continues into this zone.
- * "disabled": The haze from any enclosing zone and the haze of this zone are disabled in this zone.
- * "enabled": The haze properties of this zone are enabled, overriding the haze from any enclosing zone.
+ * @property {Entities.ComponentMode} hazeMode="inherit" - Configures the haze in the zone.
* @property {Entities.Haze} haze - The haze properties of the zone.
*
- * @property {string} bloomMode="inherit" - Configures the bloom in the zone. Possible values:
- * "inherit": The bloom from any enclosing zone continues into this zone.
- * "disabled": The bloom from any enclosing zone and the bloom of this zone are disabled in this zone.
- * "enabled": The bloom properties of this zone are enabled, overriding the bloom from any enclosing zone.
+ * @property {Entities.ComponentMode} bloomMode="inherit" - Configures the bloom in the zone.
* @property {Entities.Bloom} bloom - The bloom properties of the zone.
*
- * @property {boolean} flyingAllowed=true - If true then visitors can fly in the zone; otherwise they cannot.
- * Only works on domain entities.
+ * @property {boolean} flyingAllowed=true - If true then visitors can fly in the zone; otherwise, they cannot.
+ * Only works for domain entities.
* @property {boolean} ghostingAllowed=true - If true then visitors with avatar collisions turned off will not
- * collide with content in the zone; otherwise visitors will always collide with content in the zone. Only works on domain entities.
+ * collide with content in the zone; otherwise, visitors will always collide with content in the zone. Only works for domain
+ * entities.
* @property {string} filterURL="" - The URL of a JavaScript file that filters changes to properties of entities within the
* zone. It is periodically executed for each entity in the zone. It can, for example, be used to not allow changes to
- * certain properties.
- *
- * @property {string} avatarPriority="inherit" - Configures the update priority of contained avatars to other clients.
- * "inherit": Priority from enclosing zones is unchanged.
- * "crowd": Priority in this zone is the normal priority.
- * "hero": Avatars in this zone will have an increased update priority
+ * certain properties:
*
- *
* function filter(properties) {
- * // Test and edit properties object values,
+ * // Check and edit properties object values,
* // e.g., properties.modelURL, as required.
* return properties;
* }
*
*
+ * @property {Entities.AvatarPriorityMode} avatarPriority="inherit" - Configures the priority of updates from avatars in the
+ * zone to other clients.
+ *
* @example Create a zone that casts a red key light along the x-axis.
* var zone = Entities.addEntity({
* type: "Zone",
@@ -1388,20 +1417,30 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The "Image" {@link Entities.EntityType|EntityType} displays an image on a 2D rectangle in the domain.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ *
* @typedef {object} Entities.EntityProperties-Image
+ * @property {Vec3} dimensions=0.1,0.1,0.01 - The dimensions of the entity.
* @property {string} imageURL="" - The URL of the image to use.
- * @property {boolean} emissive=false - Whether or not the image should be emissive (unlit).
- * @property {boolean} keepAspectRatio=true - Whether or not the image should maintain its aspect ratio.
- * @property {BillboardMode} billboardMode="none" - If "none", the entity is not billboarded. If "yaw", the entity will be
- * oriented to follow your camera around the y-axis. If "full" the entity will be oriented to face your camera. The following deprecated
- * behavior is also supported: you can also set "faceCamera" to true to set billboardMode to "yaw", and you can set
- * "isFacingAvatar" to true to set billboardMode to "full". Setting either to false sets the mode to "none"
- * @property {Rect} subImage={ x: 0, y: 0, width: -1, height: -1 } - The portion of the image to display. If width or height are -1, defaults to
- * the full image in that dimension.
+ * @property {boolean} emissive=false - true fi the the image should be emissive (unlit), false if it
+ * shouldn't.
+ * @property {boolean} keepAspectRatio=true - true if the image should maintain its aspect ratio,
+ * false if it shouldn't.
+ * @property {Rect} subImage=0,0,0,0 - The portion of the image to display. If width or height are 0, it defaults
+ * to the full image in that dimension.
* @property {Color} color=255,255,255 - The color of the image.
- * @property {number} alpha=1 - The alpha of the image.
- * @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated.
- * @example Create a image entity.
+ * @property {number} alpha=1 - The opacity of the image.
+ * @property {Entities.Pulse} pulse - Color and alpha pulse.
+ * Deprecated: This property is deprecated and will be removed.
+ * @property {BillboardMode} billboardMode="none" - Whether the entity is billboarded to face the camera.
+ * @property {boolean} faceCamera - true if billboardMode is "yaw", otherwise
+ * false. Setting this property to false sets the billboardMode to
+ * "none".
+ * Deprecated: This property is deprecated and will be removed.
+ * @property {boolean} isFacingAvatar - true if billboardMode is "full", otherwise
+ * false. Setting this property to false sets the billboardMode to
+ * "none".
+ * Deprecated: This property is deprecated and will be removed.
+ * @example Create an image entity.
* var image = Entities.addEntity({
* type: "Image",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
@@ -1415,16 +1454,19 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The "Grid" {@link Entities.EntityType|EntityType} displays a grid on a 2D plane.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ *
* @typedef {object} Entities.EntityProperties-Grid
+ * @property {Vec3} dimensions - 0.1,0.1,0.01 - The dimensions of the entity.
* @property {Color} color=255,255,255 - The color of the grid.
- * @property {number} alpha=1 - The alpha of the grid.
+ * @property {number} alpha=1 - The opacity of the grid.
+ * @property {Entities.Pulse} pulse - Color and alpha pulse.
+ * Deprecated: This property is deprecated and will be removed.
* @property {boolean} followCamera=true - If true, the grid is always visible even as the camera moves to another
* position.
* @property {number} majorGridEvery=5 - Integer number of minorGridEvery intervals at which to draw a thick grid
* line. Minimum value = 1.
* @property {number} minorGridEvery=1 - Real number of meters at which to draw thin grid lines. Minimum value =
* 0.001.
- * @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated.
* @example Create a grid entity.
* var grid = Entities.addEntity({
* type: "Grid",
@@ -1440,8 +1482,10 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The "Gizmo" {@link Entities.EntityType|EntityType} displays an entity that could be used as UI.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ *
* @typedef {object} Entities.EntityProperties-Gizmo
- * @property {GizmoType} gizmoType="ring" - The gizmo type of the entity.
+ * @property {Vec3} dimensions=0.1,0.001,0.1 - The dimensions of the entity.
+ * @property {Entities.GizmoType} gizmoType="ring" - The gizmo type of the entity.
* @property {Entities.RingGizmo} ring - The ring gizmo properties.
*/
@@ -1850,7 +1894,7 @@ QScriptValue EntityItemProperties::copyToScriptValue(QScriptEngine* engine, bool
* @typedef {object} Entities.RenderInfo
* @property {number} verticesCount - The number of vertices in the entity.
* @property {number} texturesCount - The number of textures in the entity.
- * @property {number} textureSize - The total size of the textures in the entity, in bytes.
+ * @property {number} texturesSize - The total size of the textures in the entity, in bytes.
* @property {boolean} hasTransparent - Is true if any of the textures has transparency.
* @property {number} drawCalls - The number of draw calls required to render the entity.
*/
@@ -2832,6 +2876,13 @@ bool EntityItemProperties::getPropertyInfo(const QString& propertyName, EntityPr
return false;
}
+/**jsdoc
+ * Information about an entity property.
+ * @typedef {object} Entities.EntityPropertyInfo
+ * @property {number} propertyEnum - The internal number of the property.
+ * @property {string} minimum - The minimum numerical value the property may have, if available, otherwise "".
+ * @property {string} maximum - The maximum numerical value the property may have, if available, otherwise "".
+ */
QScriptValue EntityPropertyInfoToScriptValue(QScriptEngine* engine, const EntityPropertyInfo& propertyInfo) {
QScriptValue obj = engine->newObject();
obj.setProperty("propertyEnum", propertyInfo.propertyEnum);
diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h
index c3b0371029..0666bb98df 100644
--- a/libraries/entities/src/EntityScriptingInterface.h
+++ b/libraries/entities/src/EntityScriptingInterface.h
@@ -57,7 +57,7 @@ private:
};
/**jsdoc
- * The result of a {@link PickRay} search using {@link Entities.findRayIntersection|findRayIntersection}.
+ * The result of a {@link Entities.findRayIntersection|findRayIntersection} search using a {@link PickRay}.
* @typedef {object} Entities.RayToEntityIntersectionResult
* @property {boolean} intersects - true if the {@link PickRay} intersected an entity, otherwise
* false.
@@ -101,9 +101,43 @@ public:
};
/**jsdoc
- * The Entities API provides facilities to create and interact with entities. Entities are 2D and 3D objects that are visible
- * to everyone and typically are persisted to the domain. For Interface scripts, the entities available are those that
- * Interface has displayed and so knows about.
+ * The Entities API provides facilities to create and interact with entities. Entities are 2D or 3D objects
+ * displayed in-world. Depending on their {@link Entities.EntityHostType|EntityHostType}, they may persist in the domain as
+ * "domain" entities, travel to different domains with a user as "avatar" entities, or be visible only to an individual user as
+ * "local" entities (a.k.a. "overlays").
+ *
+ * Note: For Interface scripts, the entities available to scripts are those that Interface has displayed and so knows
+ * about.
+ *
+ * Entity Methods
+ *
+ * Some of the API's signals correspond to entity methods that are called, if present, in the entity being interacted with.
+ * The client or server entity script must expose them as a property. However, unlike {@link Entities.callEntityMethod}, server
+ * entity scripts do not need to list them in an remotelyCallable property. The entity methods are called with
+ * parameters per their corresponding signal.
+ *
+ *
+ * Method Name Corresponding Signal clickDownOnEntity{@link Entities.clickDownOnEntity} clickReleaseOnEntity{@link Entities.clickReleaseOnEntity} collisionWithEntity{@link Entities.collisionWithEntity} enterEntity{@link Entities.enterEntity} holdingClickOnEntity{@link Entities.holdingClickOnEntity} hoverEnterEntity{@link Entities.hoverEnterEntity} hoverLeaveEntity{@link Entities.hoverLeaveEntity} hoverOverEntity{@link Entities.hoverOverEntity} leaveEntity{@link Entities.leaveEntity} mouseDoublePressOnEntity{@link Entities.mouseDoublePressOnEntity} mouseMoveOnEntity{@link Entities.mouseMoveOnEntity} mouseMoveEventDeprecated: This is a synonym for
+ * mouseMoveOnEntity. mousePressOnEntity{@link Entities.mousePressOnEntity} mouseReleaseOnEntity{@link Entities.mouseReleaseOnEntity}
+ * See {@link Entities.clickDownOnEntity} for an example.
*
* @namespace Entities
*
@@ -113,8 +147,8 @@ public:
* @hifi-server-entity
* @hifi-assignment-client
*
- * @property {Uuid} keyboardFocusEntity - Get or set the {@link Entities.EntityType|Web} entity that has keyboard focus.
- * If no entity has keyboard focus, get returns null; set to null or {@link Uuid(0)|Uuid.NULL} to
+ * @property {Uuid} keyboardFocusEntity - The {@link Entities.EntityProperties-Web|Web} entity that has keyboard focus. If no
+ * Web entity has keyboard focus, get returns null; set to null or {@link Uuid(0)|Uuid.NULL} to
* clear keyboard focus.
*/
/// handles scripting of Entity commands from JS passed to assigned clients
@@ -150,17 +184,20 @@ public:
const QVector& entityIdsToInclude, const QVector& entityIdsToDiscard);
/**jsdoc
- * Get the properties of multiple entities.
- * @function Entities.getMultipleEntityProperties
- * @param {Uuid[]} entityIDs - The IDs of the entities to get the properties of.
- * @param {string[]|string} [desiredProperties=[]] - Either string with property name or array of the names of the properties
- * to get. If the array is empty, all properties are returned.
- * @returns {Entities.EntityProperties[]} The properties of the entity if the entity can be found, otherwise an empty object.
- * @example Retrieve the names of the nearby entities
- * var SEARCH_RADIUS = 50; // meters
- * var entityIds = Entities.findEntities(MyAvatar.position, SEARCH_RADIUS);
- * var propertySets = Entities.getMultipleEntityProperties(entityIds, "name");
- * print("Nearby entity names: " + JSON.stringify(propertySets));
+ * Gets the properties of multiple entities.
+ * @function Entities.getMultipleEntityProperties
+ * @param {Uuid[]} entityIDs - The IDs of the entities to get the properties of.
+ * @param {string[]|string} [desiredProperties=[]] - The name or names of the properties to get. For properties that are
+ * objects (e.g., the "keyLight" property), use the property and subproperty names in dot notation (e.g.,
+ * "keyLight.color").
+ * @returns {Entities.EntityProperties[]} The specified properties of each entity for each entity that can be found. If
+ * none of the entities can be found then an empty array. If no properties are specified, then all properties are
+ * returned.
+ * @example Retrieve the names of the nearby entities
+ * var SEARCH_RADIUS = 50; // meters
+ * var entityIDs = Entities.findEntities(MyAvatar.position, SEARCH_RADIUS);
+ * var propertySets = Entities.getMultipleEntityProperties(entityIDs, "name");
+ * print("Nearby entity names: " + JSON.stringify(propertySets));
*/
static QScriptValue getMultipleEntityProperties(QScriptContext* context, QScriptEngine* engine);
QScriptValue getMultipleEntityPropertiesInternal(QScriptEngine* engine, QVector entityIDs, const QScriptValue& extendedDesiredProperties);
@@ -170,13 +207,12 @@ public:
public slots:
/**jsdoc
- * Check whether or not you can change the locked property of entities. Locked entities have their
- * locked property set to true and cannot be edited or deleted. Whether or not you can change
- * entities' locked properties is configured in the domain server's permissions.
+ * Checks whether or not the script can change the locked property of entities. Locked entities have their
+ * locked property set to true and cannot be edited or deleted.
* @function Entities.canAdjustLocks
- * @returns {boolean} true if the client can change the locked property of entities,
- * otherwise false.
- * @example Set an entity's locked property to true if you can.
+ * @returns {boolean} true if the domain server will allow the script to change the locked
+ * property of entities, otherwise false.
+ * @example Lock an entity if you can.
* if (Entities.canAdjustLocks()) {
* Entities.editEntity(entityID, { locked: true });
* } else {
@@ -186,42 +222,43 @@ public slots:
Q_INVOKABLE bool canAdjustLocks();
/**jsdoc
- * Check whether or not you can rez (create) new entities in the domain.
+ * Checks whether or not the script can rez (create) new entities in the domain.
* @function Entities.canRez
- * @returns {boolean} true if the domain server will allow the script to rez (create) new entities,
- * otherwise false.
+ * @returns {boolean} true if the domain server will allow the script to rez (create) new entities, otherwise
+ * false.
*/
Q_INVOKABLE bool canRez();
/**jsdoc
- * Check whether or not you can rez (create) new temporary entities in the domain. Temporary entities are entities with a
- * finite lifetime property value set.
+ * Checks whether or not the script can rez (create) new temporary entities in the domain. Temporary entities are entities
+ * with a finite lifetime property value set.
* @function Entities.canRezTmp
- * @returns {boolean} true if the domain server will allow the script to rez (create) new temporary
- * entities, otherwise false.
+ * @returns {boolean} true if the domain server will allow the script to rez (create) new temporary entities,
+ * otherwise false.
*/
Q_INVOKABLE bool canRezTmp();
/**jsdoc
- * Check whether or not you can rez (create) new certified entities in the domain. Certified entities are entities that have
- * PoP certificates.
+ * Checks whether or not the script can rez (create) new certified entities in the domain. Certified entities are entities
+ * that have PoP certificates.
* @function Entities.canRezCertified
- * @returns {boolean} true if the domain server will allow the script to rez (create) new certified
- * entities, otherwise false.
+ * @returns {boolean} true if the domain server will allow the script to rez (create) new certified entities,
+ * otherwise false.
*/
Q_INVOKABLE bool canRezCertified();
/**jsdoc
- * Check whether or not you can rez (create) new temporary certified entities in the domain. Temporary entities are entities
- * with a finite lifetime property value set. Certified entities are entities that have PoP certificates.
+ * Checks whether or not the script can rez (create) new temporary certified entities in the domain. Temporary entities are
+ * entities with a finite lifetime property value set. Certified entities are entities that have PoP
+ * certificates.
* @function Entities.canRezTmpCertified
- * @returns {boolean} true if the domain server will allow the script to rez (create) new temporary
- * certified entities, otherwise false.
+ * @returns {boolean} true if the domain server will allow the script to rez (create) new temporary certified
+ * entities, otherwise false.
*/
Q_INVOKABLE bool canRezTmpCertified();
/**jsdoc
- * Check whether or not you can make changes to the asset server's assets.
+ * Checks whether or not the script can make changes to the asset server's assets.
* @function Entities.canWriteAssets
* @returns {boolean} true if the domain server will allow the script to make changes to the asset server's
* assets, otherwise false.
@@ -229,7 +266,7 @@ public slots:
Q_INVOKABLE bool canWriteAssets();
/**jsdoc
- * Check whether or not you can replace the domain's content set.
+ * Checks whether or not the script can replace the domain's content set.
* @function Entities.canReplaceContent
* @returns {boolean} true if the domain server will allow the script to replace the domain's content set,
* otherwise false.
@@ -237,43 +274,48 @@ public slots:
Q_INVOKABLE bool canReplaceContent();
/**jsdoc
- * Check whether or not you can get and set private user data.
+ * Checks whether or not the script can get and set the privateUserData property of entities.
* @function Entities.canGetAndSetPrivateUserData
- * @returns {boolean} true if the domain server will allow the user to get and set private user data,
- * otherwise false.
+ * @returns {boolean} true if the domain server will allow the script to get and set the
+ * privateUserData property of entities, otherwise false.
*/
Q_INVOKABLE bool canGetAndSetPrivateUserData();
/**jsdoc
- * How an entity is sent over the wire.
+ * How an entity is hosted and sent to others for display.
*
*
* Value Description domainDomain entities are sent over the entity server to everyone else avatarAvatar entities are sent over the avatar entity and are associated with one avatar localLocal entities are not sent over the wire and will only render for you, locally "domain"Domain entities are stored on the domain, are visible to everyone, and are
+ * sent to everyone by the entity server. "avatar"Avatar entities are stored on an Interface client, are visible to everyone,
+ * and are sent to everyone by the avatar mixer. They follow the client to each domain visited, displaying at the
+ * same domain coordinates unless parented to the client's avatar. "local"Local entities are ephemeral — they aren't stored anywhere — and
+ * are visible only to the client. They follow the client to each domain visited, displaying at the same domain
+ * coordinates unless parented to the client's avatar. Additionally, local entities are always
+ * collisionless.
- * @typedef {string} EntityHostType
+ * @typedef {string} Entities.EntityHostType
*/
/**jsdoc
- * Add a new entity with specified properties.
+ * Adds a new domain, avatar, or local entity.
* @function Entities.addEntity
* @param {Entities.EntityProperties} properties - The properties of the entity to create.
- * @param {EntityHostType} [entityHostType="domain"] - If "avatar" the entity is created as an avatar entity. An avatar entity
- * follows you to each domain you visit, rendering at the same world coordinates unless it's parented to your avatar.
- * If "local", the entity is created as a local entity, which will only render for you and isn't sent over the wire.
- * Otherwise it is created as a normal entity and sent over the entity server.
+ * @param {Entities.EntityHostType} [entityHostType="domain"] - The type of entity to create.
+
* @returns {Uuid} The ID of the entity if successfully created, otherwise {@link Uuid(0)|Uuid.NULL}.
- * @example Create a box entity in front of your avatar.
+ * @example Create a box domain entity in front of your avatar.
* var entityID = Entities.addEntity({
* type: "Box",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
- * dimensions: { x: 0.5, y: 0.5, z: 0.5 }
+ * dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+ * lifetime: 300 // Delete after 5 minutes.
* });
* print("Entity created: " + entityID);
*/
@@ -290,10 +332,13 @@ public slots:
}
/**jsdoc
- * Add a new entity with specified properties.
+ * Adds a new avatar entity ({@link Entities.EntityProperties|entityHostType} property is
+ * "avatar") or domain entity ({@link Entities.EntityProperties|entityHostType} property is
+ * "domain").
* @function Entities.addEntity
* @param {Entities.EntityProperties} properties - The properties of the entity to create.
- * @param {boolean} [avatarEntity=false] - Whether to create an avatar entity or a domain entity
+ * @param {boolean} [avatarEntity=false] - true to create an avatar entity, false to create a
+ * domain entity.
* @returns {Uuid} The ID of the entity if successfully created, otherwise {@link Uuid(0)|Uuid.NULL}.
*/
Q_INVOKABLE QUuid addEntity(const EntityItemProperties& properties, bool avatarEntity = false) {
@@ -303,13 +348,18 @@ public slots:
/// temporary method until addEntity can be used from QJSEngine
/// Deliberately not adding jsdoc, only used internally.
+ // FIXME: Deprecate and remove from the API.
Q_INVOKABLE QUuid addModelEntity(const QString& name, const QString& modelUrl, const QString& textures, const QString& shapeType, bool dynamic,
bool collisionless, bool grabbable, const glm::vec3& position, const glm::vec3& gravity);
/**jsdoc
- * Create a clone of an entity. A clone can be created by a client that doesn't have rez permissions in the current domain.
- * The entity must have its cloneable property set to true. The clone has a modified name, other
- * properties set per its clone related-properties, and its clone-related properties are set to defaults.
+ * Creates a clone of an entity. The clone has a modified name property, other properties set per the original
+ * entity's clone-related {@link Entities.EntityProperties|properties} (e.g., cloneLifetime), and
+ * clone-related properties set to defaults.
+ * Domain entities must have their cloneable property value be true in order to be cloned. A
+ * domain entity can be cloned by a client that doesn't have rez permissions in the domain.
+ * Avatar entities must have their cloneable and cloneAvatarEntity property values be
+ * true in order to be cloned.
* @function Entities.cloneEntity
* @param {Uuid} entityID - The ID of the entity to clone.
* @returns {Uuid} The ID of the new entity if successfully cloned, otherwise {@link Uuid(0)|Uuid.NULL}.
@@ -317,18 +367,21 @@ public slots:
Q_INVOKABLE QUuid cloneEntity(const QUuid& entityID);
/**jsdoc
- * Get the properties of an entity.
+ * Gets an entity's property values.
* @function Entities.getEntityProperties
* @param {Uuid} entityID - The ID of the entity to get the properties of.
- * @param {string[]} [desiredProperties=[]] - Array of the names of the properties to get. If the array is empty,
- * all properties are returned.
- * @returns {Entities.EntityProperties} The properties of the entity if the entity can be found, otherwise an empty object.
+ * @param {string|string[]} [desiredProperties=[]] - The name or names of the properties to get. For properties that are
+ * objects (e.g., the "keyLight" property), use the property and subproperty names in dot notation (e.g.,
+ * "keyLight.color").
+ * @returns {Entities.EntityProperties} The specified properties of the entity if the entity can be found, otherwise an
+ * empty object. If no properties are specified, then all properties are returned.
* @example Report the color of a new box entity.
* var entityID = Entities.addEntity({
* type: "Box",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
- * dimensions: { x: 0.5, y: 0.5, z: 0.5 }
+ * dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+ * lifetime: 300 // Delete after 5 minutes.
* });
* var properties = Entities.getEntityProperties(entityID, ["color"]);
* print("Entity color: " + JSON.stringify(properties.color));
@@ -337,31 +390,34 @@ public slots:
Q_INVOKABLE EntityItemProperties getEntityProperties(const QUuid& entityID, EntityPropertyFlags desiredProperties);
/**jsdoc
- * Update an entity with specified properties.
+ * Edits an entity, changing one or more of its property values.
* @function Entities.editEntity
* @param {Uuid} entityID - The ID of the entity to edit.
- * @param {Entities.EntityProperties} properties - The properties to update the entity with.
- * @returns {Uuid} The ID of the entity if the edit was successful, otherwise null.
+ * @param {Entities.EntityProperties} properties - The new property values.
+ * @returns {Uuid} The ID of the entity if the edit was successful, otherwise null or {@link Uuid|Uuid.NULL}.
* @example Change the color of an entity.
* var entityID = Entities.addEntity({
* type: "Box",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
- * dimensions: { x: 0.5, y: 0.5, z: 0.5 }
+ * dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+ * lifetime: 300 // Delete after 5 minutes.
* });
* var properties = Entities.getEntityProperties(entityID, ["color"]);
* print("Entity color: " + JSON.stringify(properties.color));
*
- * Entities.editEntity(entityID, {
- * color: { red: 255, green: 0, blue: 0 }
- * });
- * properties = Entities.getEntityProperties(entityID, ["color"]);
- * print("Entity color: " + JSON.stringify(properties.color));
+ * Script.setTimeout(function () { // Wait for the entity to be created before editing.
+ * Entities.editEntity(entityID, {
+ * color: { red: 255, green: 0, blue: 0 }
+ * });
+ * properties = Entities.getEntityProperties(entityID, ["color"]);
+ * print("Entity color: " + JSON.stringify(properties.color));
+ * }, 50);
*/
Q_INVOKABLE QUuid editEntity(const QUuid& entityID, const EntityItemProperties& properties);
/**jsdoc
- * Delete an entity.
+ * Deletes an entity.
* @function Entities.deleteEntity
* @param {Uuid} entityID - The ID of the entity to delete.
* @example Delete an entity a few seconds after creating it.
@@ -379,23 +435,79 @@ public slots:
Q_INVOKABLE void deleteEntity(const QUuid& entityID);
/**jsdoc
- * Get an entities type as a string.
- * @function Entities.deleteEntity
- * @param {Uuid} id - The id of the entity to get the type of.
+ * Gets an entity's type.
+ * @function Entities.getEntityType
+ * @param {Uuid} id - The ID of the entity to get the type of.
+ * @returns {Entities.EntityType} The type of the entity.
*/
Q_INVOKABLE QString getEntityType(const QUuid& entityID);
/**jsdoc
- * Get the entity script object. In particular, this is useful for accessing the event bridge for a Web
- * entity.
+ * Gets an entity's script object. In particular, this is useful for accessing a {@link Entities.EntityProperties-Web|Web}
+ * entity's HTML EventBridge script object to exchange messages with the web page script.
+ * Alternatively, you can use {@link Entities.emitScriptEvent} and {@link Entities.webEventReceived} to exchange
+ * messages with a Web entity over its event bridge.
* @function Entities.getEntityObject
- * @param {Uuid} id - The ID of the entity to get the script object of.
+ * @param {Uuid} id - The ID of the entity to get the script object for.
* @returns {object} The script object for the entity if found.
+ * @example Exchange messages with a Web entity.
+ * // HTML file, name: "webEntity.html".
+ *
+ *
+ *
+ * HELLO
+ *
+ *
+ * HELLO
+ *
+ *
+ *
+ *
+ * // Script file.
+ * var webEntity = Entities.addEntity({
+ * type: "Web",
+ * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -3 })),
+ * rotation: MyAvatar.orientation,
+ * sourceUrl: Script.resolvePath("webEntity.html"),
+ * alpha: 1.0,
+ * lifetime: 300 // 5 min
+ * });
+ *
+ * var webEntityObject;
+ *
+ * function onWebEventReceived(message) {
+ * // Message received.
+ * print("Message received: " + message);
+ *
+ * // Send a message back.
+ * webEntityObject.emitScriptEvent(message + " back");
+ * }
+ *
+ * Script.setTimeout(function () {
+ * webEntityObject = Entities.getEntityObject(webEntity);
+ * webEntityObject.webEventReceived.connect(onWebEventReceived);
+ * }, 500);
+ *
+ * Script.scriptEnding.connect(function () {
+ * Entities.deleteEntity(webEntity);
+ * });
*/
Q_INVOKABLE QObject* getEntityObject(const QUuid& id);
/**jsdoc
- * Check whether an entities's assets have been loaded. For example, for an Model entity the result indicates
+ * Checks whether an entities's assets have been loaded. For example, for an Model entity the result indicates
* whether its textures have been loaded.
* @function Entities.isLoaded
* @param {Uuid} id - The ID of the entity to check.
@@ -404,15 +516,15 @@ public slots:
Q_INVOKABLE bool isLoaded(const QUuid& id);
/**jsdoc
- * Check if there is an object of a given ID.
+ * Checks if there is an entity with a specified ID.
* @function Entities.isAddedEntity
* @param {Uuid} id - The ID to check.
- * @returns {boolean} true if an object with the given ID exists, false otherwise.
+ * @returns {boolean} true if an entity with the specified ID exists, false if it doesn't.
*/
Q_INVOKABLE bool isAddedEntity(const QUuid& id);
/**jsdoc
- * Calculates the size of the given text in the specified object if it is a text entity.
+ * Calculates the size of some text in a text entity.
* @function Entities.textSize
* @param {Uuid} id - The ID of the entity to use for calculation.
* @param {string} text - The string to calculate the size of.
@@ -422,47 +534,151 @@ public slots:
Q_INVOKABLE QSizeF textSize(const QUuid& id, const QString& text);
/**jsdoc
- * Call a method in a client entity script from a client script or client entity script, or call a method in a server
- * entity script from a server entity script. The entity script method must be exposed as a property in the target client
+ * Calls a method in a client entity script from an Interface, avatar, or client entity script, or calls a method in a
+ * server entity script from a server entity script. The entity script method must be exposed as a property in the target
* entity script. Additionally, if calling a server entity script, the server entity script must include the method's name
* in an exposed property called remotelyCallable that is an array of method names that can be called.
* @function Entities.callEntityMethod
* @param {Uuid} entityID - The ID of the entity to call the method in.
- * @param {string} method - The name of the method to call.
- * @param {string[]} [parameters=[]] - The parameters to call the specified method with.
+ * @param {string} method - The name of the method to call. The method is called with the entity ID as the first parameter
+ * and the parameters value as the second parameter.
+ * @param {string[]} [parameters=[]] - The additional parameters to call the specified method with.
+ * @example Call a method in a client entity script from an Interface script.
+ * // Client entity script.
+ * var entityScript = (function () {
+ * this.entityMethod = function (id, params) {
+ * print("Method at entity : " + id + " ; " + params[0] + ", " + params[1]);
+ * };
+ * });
+ *
+ * // Entity that hosts the client entity script.
+ * var entityID = Entities.addEntity({
+ * type: "Box",
+ * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
+ * dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+ * script: "(" + entityScript + ")", // Could host the script on a Web server instead.
+ * lifetime: 300 // Delete after 5 minutes.
+ * });
+ *
+ * // Interface script call to the client entity script.
+ * Script.setTimeout(function () {
+ * Entities.callEntityMethod(entityID, "entityMethod", ["hello", 12]);
+ * }, 1000); // Wait for the entity to be created.
*/
Q_INVOKABLE void callEntityMethod(const QUuid& entityID, const QString& method, const QStringList& params = QStringList());
/**jsdoc
- * Call a method in a server entity script from a client script or client entity script. The entity script method must be
- * exposed as a property in the target server entity script. Additionally, the target server entity script must include the
- * method's name in an exposed property called remotelyCallable that is an array of method names that can be
- * called.
+ * Calls a method in a server entity script from an Interface, avatar, or client entity script. The server entity script
+ * method must be exposed as a property in the target server entity script. Additionally, the server entity script must
+ * include the method's name in an exposed property called remotelyCallable that is an array of method names
+ * that can be called.
* @function Entities.callEntityServerMethod
* @param {Uuid} entityID - The ID of the entity to call the method in.
- * @param {string} method - The name of the method to call.
- * @param {string[]} [parameters=[]] - The parameters to call the specified method with.
+ * @param {string} method - The name of the method to call. The method is called with the entity ID as the first parameter
+ * and the parameters value as the second parameter.
+ * @param {string[]} [parameters=[]] - The additional parameters to call the specified method with.
+ * @example Call a method in a server entity script from an Interface script.
+ * // Server entity script.
+ * var entityScript = (function () {
+ * this.entityMethod = function (id, params) {
+ * print("Method at entity : " + id + " ; " + params[0] + ", " + params[1]); // In server log.
+ * };
+ * this.remotelyCallable = [
+ * "entityMethod"
+ * ];
+ * });
+ *
+ * // Entity that hosts the server entity script.
+ * var entityID = Entities.addEntity({
+ * type: "Box",
+ * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
+ * dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+ * serverScripts: "(" + entityScript + ")", // Could host the script on a Web server instead.
+ * lifetime: 300 // Delete after 5 minutes.
+ * });
+ *
+ * // Interface script call to the server entity script.
+ * Script.setTimeout(function () {
+ * Entities.callEntityServerMethod(entityID, "entityMethod", ["hello", 12]);
+ * }, 1000); // Wait for the entity to be created.
*/
Q_INVOKABLE void callEntityServerMethod(const QUuid& entityID, const QString& method, const QStringList& params = QStringList());
/**jsdoc
- * Call a method in a specific user's client entity script from a server entity script. The entity script method must be
- * exposed as a property in the target client entity script.
+ * Calls a method in a specific user's client entity script from a server entity script. The entity script method must be
+ * exposed as a property in the target client entity script. Additionally, the client entity script must
+ * include the method's name in an exposed property called remotelyCallable that is an array of method names
+ * that can be called.
* @function Entities.callEntityClientMethod
* @param {Uuid} clientSessionID - The session ID of the user to call the method in.
* @param {Uuid} entityID - The ID of the entity to call the method in.
- * @param {string} method - The name of the method to call.
- * @param {string[]} [parameters=[]] - The parameters to call the specified method with.
+ * @param {string} method - The name of the method to call. The method is called with the entity ID as the first parameter
+ * and the parameters value as the second parameter.
+ * @param {string[]} [parameters=[]] - The additional parameters to call the specified method with.
+ * @example Call a method in a client entity script from a server entity script.
+ * // Client entity script.
+ * var clientEntityScript = (function () {
+ * this.entityMethod = function (id, params) {
+ * print("Method at client entity : " + id + " ; " + params[0] + ", " + params[1]);
+ * };
+ * this.remotelyCallable = [
+ * "entityMethod"
+ * ];
+ * });
+ *
+ * // Server entity script.
+ * var serverEntityScript = (function () {
+ * var clientSessionID,
+ * clientEntityID;
+ *
+ * function callClientMethod() {
+ * // Server entity script call to client entity script.
+ * Entities.callEntityClientMethod(clientSessionID, clientEntityID, "entityMethod", ["hello", 12]);
+ * }
+ *
+ * // Obtain client entity details then call client entity method.
+ * this.entityMethod = function (id, params) {
+ * clientSessionID = params[0];
+ * clientEntityID = params[1];
+ * callClientMethod();
+ * };
+ * this.remotelyCallable = [
+ * "entityMethod"
+ * ];
+ * });
+ *
+ * // Entity that hosts the client entity script.
+ * var clientEntityID = Entities.addEntity({
+ * type: "Box",
+ * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: -1, y: 0, z: -5 })),
+ * dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+ * script: "(" + clientEntityScript + ")", // Could host the script on a Web server instead.
+ * lifetime: 300 // Delete after 5 minutes.
+ * });
+ *
+ * // Entity that hosts the server entity script.
+ * var serverEntityID = Entities.addEntity({
+ * type: "Box",
+ * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 1, y: 0, z: -5 })),
+ * dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+ * serverScripts: "(" + serverEntityScript + ")", // Could host the script on a Web server instead.
+ * lifetime: 300 // Delete after 5 minutes.
+ * });
+ *
+ * // Interface script call to the server entity script.
+ * Script.setTimeout(function () {
+ * Entities.callEntityServerMethod(serverEntityID, "entityMethod", [MyAvatar.sessionUUID, clientEntityID]);
+ * }, 1000); // Wait for the entities to be created.
*/
Q_INVOKABLE void callEntityClientMethod(const QUuid& clientSessionID, const QUuid& entityID, const QString& method,
const QStringList& params = QStringList());
/**jsdoc
- * Find the non-local entity with a position closest to a specified point and within a specified radius.
+ * Finds the domain or avatar entity with a position closest to a specified point and within a specified radius.
* @function Entities.findClosestEntity
* @param {Vec3} center - The point about which to search.
* @param {number} radius - The radius within which to search.
- * @returns {Uuid} The ID of the entity that is closest to the center and within the radius if
+ * @returns {Uuid} The ID of the entity that is closest to the center and within the radius, if
* there is one, otherwise null.
* @example Find the closest entity within 10m of your avatar.
* var entityID = Entities.findClosestEntity(MyAvatar.position, 10);
@@ -472,12 +688,12 @@ public slots:
Q_INVOKABLE QUuid findClosestEntity(const glm::vec3& center, float radius) const;
/**jsdoc
- * Find all non-local entities that intersect a sphere defined by a center point and radius.
+ * Finds all domain and avatar entities that intersect a sphere.
* @function Entities.findEntities
* @param {Vec3} center - The point about which to search.
* @param {number} radius - The radius within which to search.
- * @returns {Uuid[]} An array of entity IDs that were found that intersect the search sphere. The array is empty if no
- * entities could be found.
+ * @returns {Uuid[]} An array of entity IDs that intersect the search sphere. The array is empty if no entities could be
+ * found.
* @example Report how many entities are within 10m of your avatar.
* var entityIDs = Entities.findEntities(MyAvatar.position, 10);
* print("Number of entities within 10m: " + entityIDs.length);
@@ -486,8 +702,7 @@ public slots:
Q_INVOKABLE QVector findEntities(const glm::vec3& center, float radius) const;
/**jsdoc
- * Find all non-local entities whose axis-aligned boxes intersect a search axis-aligned box defined by its minimum coordinates corner
- * and dimensions.
+ * Finds all domain and avatar entities whose axis-aligned boxes intersect a search axis-aligned box.
* @function Entities.findEntitiesInBox
* @param {Vec3} corner - The corner of the search AA box with minimum co-ordinate values.
* @param {Vec3} dimensions - The dimensions of the search AA box.
@@ -498,12 +713,12 @@ public slots:
Q_INVOKABLE QVector findEntitiesInBox(const glm::vec3& corner, const glm::vec3& dimensions) const;
/**jsdoc
- * Find all non-local entities whose axis-aligned boxes intersect a search frustum.
+ * Finds all domain and avatar entities whose axis-aligned boxes intersect a search frustum.
* @function Entities.findEntitiesInFrustum
* @param {ViewFrustum} frustum - The frustum to search in. The position, orientation,
* projection, and centerRadius properties must be specified.
- * @returns {Uuid[]} An array of entity IDs axis-aligned boxes intersect the frustum. The array is empty if no entities
- * could be found.
+ * @returns {Uuid[]} An array of entity IDs whose axis-aligned boxes intersect the search frustum. The array is empty if no
+ * entities could be found.
* @example Report the number of entities in view.
* var entityIDs = Entities.findEntitiesInFrustum(Camera.frustum);
* print("Number of entities in view: " + entityIDs.length);
@@ -512,7 +727,7 @@ public slots:
Q_INVOKABLE QVector findEntitiesInFrustum(QVariantMap frustum) const;
/**jsdoc
- * Find all non-local entities of a particular type that intersect a sphere defined by a center point and radius.
+ * Finds all domain and avatar entities of a particular type that intersect a sphere.
* @function Entities.findEntitiesByType
* @param {Entities.EntityType} entityType - The type of entity to search for.
* @param {Vec3} center - The point about which to search.
@@ -527,33 +742,35 @@ public slots:
Q_INVOKABLE QVector findEntitiesByType(const QString entityType, const glm::vec3& center, float radius) const;
/**jsdoc
- * Find all non-local entities with a particular name that intersect a sphere defined by a center point and radius.
- * @function Entities.findEntitiesByName
- * @param {string} entityName - The name of the entity to search for.
- * @param {Vec3} center - The point about which to search.
- * @param {number} radius - The radius within which to search.
- * @param {boolean} [caseSensitive=false] - If true then the search is case-sensitive.
- * @returns {Uuid[]} An array of entity IDs that have the specified name and intersect the search sphere. The array is empty
- * if no entities could be found.
- * @example Report the number of entities with the name, "Light-Target".
- * var entityIDs = Entities.findEntitiesByName("Light-Target", MyAvatar.position, 10, false);
- * print("Number of entities with the name Light-Target: " + entityIDs.length);
- */
+ * Finds all domain and avatar entities with a particular name that intersect a sphere.
+ * @function Entities.findEntitiesByName
+ * @param {string} entityName - The name of the entity to search for.
+ * @param {Vec3} center - The point about which to search.
+ * @param {number} radius - The radius within which to search.
+ * @param {boolean} [caseSensitive=false] - If true then the search is case-sensitive.
+ * @returns {Uuid[]} An array of entity IDs that have the specified name and intersect the search sphere. The array is
+ * empty if no entities could be found.
+ * @example Report the number of entities with the name, "Light-Target".
+ * var entityIDs = Entities.findEntitiesByName("Light-Target", MyAvatar.position, 10, false);
+ * print("Number of entities with the name Light-Target: " + entityIDs.length);
+ */
Q_INVOKABLE QVector findEntitiesByName(const QString entityName, const glm::vec3& center, float radius,
bool caseSensitiveSearch = false) const;
/**jsdoc
- * Find the first non-local entity intersected by a {@link PickRay}. Light and Zone entities are not
- * intersected unless they've been configured as pickable using {@link Entities.setLightsArePickable|setLightsArePickable}
- * and {@link Entities.setZonesArePickable|setZonesArePickable}, respectively.
+ * Finds the first avatar or domain entity intersected by a {@link PickRay}. Light and Zone
+ * entities are not intersected unless they've been configured as pickable using
+ * {@link Entities.setLightsArePickable|setLightsArePickable} and {@link Entities.setZonesArePickable|setZonesArePickable},
+ * respectively.
* @function Entities.findRayIntersection
- * @param {PickRay} pickRay - The PickRay to use for finding entities.
- * @param {boolean} [precisionPicking=false] - If true and the intersected entity is a Model
- * entity, the result's extraInfo property includes more information than it otherwise would.
+ * @param {PickRay} pickRay - The pick ray to use for finding entities.
+ * @param {boolean} [precisionPicking=false] - true to pick against precise meshes, false to pick
+ * against coarse meshes. If true and the intersected entity is a Model entity, the result's
+ * extraInfo property includes more information than it otherwise would.
* @param {Uuid[]} [entitiesToInclude=[]] - If not empty then the search is restricted to these entities.
* @param {Uuid[]} [entitiesToDiscard=[]] - Entities to ignore during the search.
* @param {boolean} [visibleOnly=false] - If true then only entities that are
- * {@link Entities.EntityProperties|visible} are searched.
+ * {@link Entities.EntityProperties|visible} are searched.
* @param {boolean} [collideableOnly=false] - If true then only entities that are not
* {@link Entities.EntityProperties|collisionless} are searched.
* @returns {Entities.RayToEntityIntersectionResult} The result of the search for the first intersected entity.
@@ -587,14 +804,14 @@ public slots:
Q_INVOKABLE bool reloadServerScripts(const QUuid& entityID);
/**jsdoc
- * Gets the status of server entity script attached to an entity
+ * Gets the status of a server entity script attached to an entity.
* @function Entities.getServerScriptStatus
- * @param {Uuid} entityID - The ID of the entity to get the server entity script status for.
+ * @param {Uuid} entityID - The ID of the entity to get the server entity script status of.
* @param {Entities~getServerScriptStatusCallback} callback - The function to call upon completion.
* @returns {boolean} true always.
*/
/**jsdoc
- * Called when {@link Entities.getServerScriptStatus} is complete.
+ * Called when a {@link Entities.getServerScriptStatus} call is complete.
* @callback Entities~getServerScriptStatusCallback
* @param {boolean} success - true if the server entity script status could be obtained, otherwise
* false.
@@ -606,102 +823,104 @@ public slots:
Q_INVOKABLE bool getServerScriptStatus(const QUuid& entityID, QScriptValue callback);
/**jsdoc
- * Get metadata for certain entity properties such as script and serverScripts.
- * @function Entities.queryPropertyMetadata
- * @param {Uuid} entityID - The ID of the entity to get the metadata for.
- * @param {string} property - The property name to get the metadata for.
- * @param {Entities~queryPropertyMetadataCallback} callback - The function to call upon completion.
- * @returns {boolean} true if the request for metadata was successfully sent to the server, otherwise
- * false.
- * @throws Throws an error if property is not handled yet or callback is not a function.
- */
+ * Gets metadata for certain entity properties such as script and serverScripts.
+ * @function Entities.queryPropertyMetadata
+ * @param {Uuid} entityID - The ID of the entity to get the metadata for.
+ * @param {string} property - The property name to get the metadata for.
+ * @param {Entities~queryPropertyMetadataCallback} callback - The function to call upon completion.
+ * @returns {boolean} true if the request for metadata was successfully sent to the server, otherwise
+ * false.
+ * @throws Throws an error if property is not handled yet or callback is not a function.
+ */
/**jsdoc
- * Get metadata for certain entity properties such as script and serverScripts.
- * @function Entities.queryPropertyMetadata
- * @param {Uuid} entityID - The ID of the entity to get the metadata for.
- * @param {string} property - The property name to get the metadata for.
- * @param {object} scope - The "this" context that the callback will be executed within.
- * @param {Entities~queryPropertyMetadataCallback} callback - The function to call upon completion.
- * @returns {boolean} true if the request for metadata was successfully sent to the server, otherwise
- * false.
- * @throws Throws an error if property is not handled yet or callback is not a function.
- */
+ * Gets metadata for certain entity properties such as script and serverScripts.
+ * @function Entities.queryPropertyMetadata
+ * @param {Uuid} entityID - The ID of the entity to get the metadata for.
+ * @param {string} property - The property name to get the metadata for.
+ * @param {object} scope - The "this" context that the callback will be executed within.
+ * @param {Entities~queryPropertyMetadataCallback} callback - The function to call upon completion.
+ * @returns {boolean} true if the request for metadata was successfully sent to the server, otherwise
+ * false.
+ * @throws Throws an error if property is not handled yet or callback is not a function.
+ */
/**jsdoc
- * Called when {@link Entities.queryPropertyMetadata} is complete.
- * @callback Entities~queryPropertyMetadataCallback
- * @param {string} error - undefined if there was no error, otherwise an error message.
- * @param {object} result - The metadata for the requested entity property if there was no error, otherwise
- * undefined.
- */
+ * Called when a {@link Entities.queryPropertyMetadata} call is complete.
+ * @callback Entities~queryPropertyMetadataCallback
+ * @param {string} error - undefined if there was no error, otherwise an error message.
+ * @param {object} result - The metadata for the requested entity property if there was no error, otherwise
+ * undefined.
+ */
Q_INVOKABLE bool queryPropertyMetadata(const QUuid& entityID, QScriptValue property, QScriptValue scopeOrCallback,
QScriptValue methodOrName = QScriptValue());
/**jsdoc
- * Set whether or not ray picks intersect the bounding box of {@link Entities.EntityType|Light} entities. By default, Light
- * entities are not intersected. The setting lasts for the Interface session. Ray picks are done using
- * {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
+ * Sets whether or not ray picks intersect the bounding box of {@link Entities.EntityProperties-Light|Light} entities. By
+ * default, Light entities are not intersected. The setting lasts for the Interface session. Ray picks are done using
+ * {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
* @function Entities.setLightsArePickable
- * @param {boolean} value - Set true to make ray picks intersect the bounding box of
- * {@link Entities.EntityType|Light} entities, otherwise false.
+ * @param {boolean} value - true to make ray picks intersect the bounding box of
+ * {@link Entities.EntityProperties-Light|Light} entities, otherwise false.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE void setLightsArePickable(bool value);
/**jsdoc
- * Get whether or not ray picks intersect the bounding box of {@link Entities.EntityType|Light} entities. Ray picks are
- * done using {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
+ * Gets whether or not ray picks intersect the bounding box of {@link Entities.EntityProperties-Light|Light} entities. Ray
+ * picks are done using {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
* @function Entities.getLightsArePickable
- * @returns {boolean} true if ray picks intersect the bounding box of {@link Entities.EntityType|Light}
- * entities, otherwise false.
+ * @returns {boolean} true if ray picks intersect the bounding box of
+ * {@link Entities.EntityProperties-Light|Light} entities, otherwise false.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE bool getLightsArePickable() const;
/**jsdoc
- * Set whether or not ray picks intersect the bounding box of {@link Entities.EntityType|Zone} entities. By default, Light
- * entities are not intersected. The setting lasts for the Interface session. Ray picks are done using
- * {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
+ * Sets whether or not ray picks intersect the bounding box of {@link Entities.EntityProperties-Zone|Zone} entities. By
+ * default, Zone entities are not intersected. The setting lasts for the Interface session. Ray picks are done using
+ * {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
* @function Entities.setZonesArePickable
- * @param {boolean} value - Set true to make ray picks intersect the bounding box of
- * {@link Entities.EntityType|Zone} entities, otherwise false.
+ * @param {boolean} value - true to make ray picks intersect the bounding box of
+ * {@link Entities.EntityProperties-Zone|Zone} entities, otherwise false.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE void setZonesArePickable(bool value);
/**jsdoc
- * Get whether or not ray picks intersect the bounding box of {@link Entities.EntityType|Zone} entities. Ray picks are
- * done using {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
+ * Gets whether or not ray picks intersect the bounding box of {@link Entities.EntityProperties-Zone|Zone} entities. Ray
+ * picks are done using {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
* @function Entities.getZonesArePickable
- * @returns {boolean} true if ray picks intersect the bounding box of {@link Entities.EntityType|Zone}
- * entities, otherwise false.
+ * @returns {boolean} true if ray picks intersect the bounding box of
+ * {@link Entities.EntityProperties-Zone|Zone} entities, otherwise false.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE bool getZonesArePickable() const;
/**jsdoc
- * Set whether or not {@link Entities.EntityType|Zone} entities' boundaries should be drawn. Currently not used.
+ * Sets whether or not {@link Entities.EntityProperties-Zone|Zone} entities' boundaries should be drawn. Currently not
+ * used.
* @function Entities.setDrawZoneBoundaries
- * @param {boolean} value - Set to true if {@link Entities.EntityType|Zone} entities' boundaries should be
+ * @param {boolean} value - true if {@link Entities.EntityProperties-Zone|Zone} entities' boundaries should be
* drawn, otherwise false.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE void setDrawZoneBoundaries(bool value);
/**jsdoc
- * Get whether or not {@link Entities.EntityType|Zone} entities' boundaries should be drawn. Currently not used.
- * @function Entities.getDrawZoneBoundaries
- * @returns {boolean} true if {@link Entities.EntityType|Zone} entities' boundaries should be drawn,
- * otherwise false.
- */
+ * Gets whether or not {@link Entities.EntityProperties-Zone|Zone} entities' boundaries should be drawn. Currently
+ * not used.
+ * @function Entities.getDrawZoneBoundaries
+ * @returns {boolean} true if {@link Entities.EntityProperties-Zone|Zone} entities' boundaries should be
+ * drawn, otherwise false.
+ */
// FIXME move to a renderable entity interface
Q_INVOKABLE bool getDrawZoneBoundaries() const;
/**jsdoc
- * Set the values of all voxels in a spherical portion of a {@link Entities.EntityType|PolyVox} entity.
+ * Sets the values of all voxels in a spherical portion of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @function Entities.setVoxelSphere
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} center - The center of the sphere of voxels to set, in world coordinates.
* @param {number} radius - The radius of the sphere of voxels to set, in world coordinates.
* @param {number} value - If value % 256 == 0 then each voxel is cleared, otherwise each voxel is set.
@@ -720,9 +939,9 @@ public slots:
Q_INVOKABLE bool setVoxelSphere(const QUuid& entityID, const glm::vec3& center, float radius, int value);
/**jsdoc
- * Set the values of all voxels in a capsule-shaped portion of a {@link Entities.EntityType|PolyVox} entity.
+ * Sets the values of all voxels in a capsule-shaped portion of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @function Entities.setVoxelCapsule
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} start - The center of the sphere of voxels to set, in world coordinates.
* @param {Vec3} end - The center of the sphere of voxels to set, in world coordinates.
* @param {number} radius - The radius of the capsule cylinder and spherical ends, in world coordinates.
@@ -744,14 +963,14 @@ public slots:
Q_INVOKABLE bool setVoxelCapsule(const QUuid& entityID, const glm::vec3& start, const glm::vec3& end, float radius, int value);
/**jsdoc
- * Set the value of a particular voxels in a {@link Entities.EntityType|PolyVox} entity.
+ * Sets the value of a particular voxel in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @function Entities.setVoxel
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} position - The position relative to the minimum axes values corner of the entity. The
* position coordinates are rounded to the nearest integer to get the voxel coordinate. The minimum axes
* corner voxel is { x: 0, y: 0, z: 0 }.
* @param {number} value - If value % 256 == 0 then voxel is cleared, otherwise the voxel is set.
- * @example Create a cube PolyVox entity and clear the minimum axes corner voxel.
+ * @example Create a cube PolyVox entity and clear the minimum axes' corner voxel.
* var entity = Entities.addEntity({
* type: "PolyVox",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 })),
@@ -766,9 +985,9 @@ public slots:
Q_INVOKABLE bool setVoxel(const QUuid& entityID, const glm::vec3& position, int value);
/**jsdoc
- * Set the values of all voxels in a {@link Entities.EntityType|PolyVox} entity.
+ * Sets the values of all voxels in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @function Entities.setAllVoxels
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {number} value - If value % 256 == 0 then each voxel is cleared, otherwise each voxel is set.
* @example Create a PolyVox cube.
* var entity = Entities.addEntity({
@@ -784,9 +1003,9 @@ public slots:
Q_INVOKABLE bool setAllVoxels(const QUuid& entityID, int value);
/**jsdoc
- * Set the values of all voxels in a cubic portion of a {@link Entities.EntityType|PolyVox} entity.
+ * Sets the values of all voxels in a cubic portion of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @function Entities.setVoxelsInCuboid
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} lowPosition - The position of the minimum axes value corner of the cube of voxels to set, in voxel
* coordinates.
* @param {Vec3} cuboidSize - The size of the cube of voxels to set, in voxel coordinates.
@@ -809,14 +1028,14 @@ public slots:
Q_INVOKABLE bool setVoxelsInCuboid(const QUuid& entityID, const glm::vec3& lowPosition, const glm::vec3& cuboidSize, int value);
/**jsdoc
- * Convert voxel coordinates in a {@link Entities.EntityType|PolyVox} entity to world coordinates. Voxel coordinates are
- * relative to the minimum axes values corner of the entity with a scale of Vec3.ONE being the dimensions of
- * each voxel.
+ * Converts voxel coordinates in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity to world coordinates. Voxel
+ * coordinates are relative to the minimum axes values corner of the entity with a scale of Vec3.ONE being the
+ * dimensions of each voxel.
* @function Entities.voxelCoordsToWorldCoords
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} voxelCoords - The voxel coordinates. May be fractional and outside the entity's bounding box.
* @returns {Vec3} The world coordinates of the voxelCoords if the entityID is a
- * {@link Entities.EntityType|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}.
+ * {@link Entities.EntityProperties-PolyVox|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}.
* @example Create a PolyVox cube with the 0,0,0 voxel replaced by a sphere.
* // Cube PolyVox with 0,0,0 voxel missing.
* var polyVox = Entities.addEntity({
@@ -844,26 +1063,29 @@ public slots:
Q_INVOKABLE glm::vec3 voxelCoordsToWorldCoords(const QUuid& entityID, glm::vec3 voxelCoords);
/**jsdoc
- * Convert world coordinates to voxel coordinates in a {@link Entities.EntityType|PolyVox} entity. Voxel coordinates are
- * relative to the minimum axes values corner of the entity, with a scale of Vec3.ONE being the dimensions of
- * each voxel.
+ * Converts world coordinates to voxel coordinates in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity. Voxel
+ * coordinates are relative to the minimum axes values corner of the entity, with a scale of Vec3.ONE being
+ * the dimensions of each voxel.
* @function Entities.worldCoordsToVoxelCoords
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} worldCoords - The world coordinates. May be outside the entity's bounding box.
* @returns {Vec3} The voxel coordinates of the worldCoords if the entityID is a
- * {@link Entities.EntityType|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}. The value may be fractional.
+ * {@link Entities.EntityProperties-PolyVox|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}. The value may be
+ * fractional and outside the entity's bounding box.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE glm::vec3 worldCoordsToVoxelCoords(const QUuid& entityID, glm::vec3 worldCoords);
/**jsdoc
- * Convert voxel coordinates in a {@link Entities.EntityType|PolyVox} entity to local coordinates relative to the minimum
- * axes value corner of the entity, with the scale being the same as world coordinates.
+ * Converts voxel coordinates in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity to local coordinates. Local
+ * coordinates are relative to the minimum axes value corner of the entity, with the scale being the same as world
+ * coordinates. Voxel coordinates are relative to the minimum axes values corner of the entity, with a scale of
+ * Vec3.ONE being the dimensions of each voxel.
* @function Entities.voxelCoordsToLocalCoords
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} voxelCoords - The voxel coordinates. May be fractional and outside the entity's bounding box.
* @returns {Vec3} The local coordinates of the voxelCoords if the entityID is a
- * {@link Entities.EntityType|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}.
+ * {@link Entities.EntityProperties-PolyVox|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}.
* @example Get the world dimensions of a voxel in a PolyVox entity.
* var polyVox = Entities.addEntity({
* type: "PolyVox",
@@ -879,25 +1101,30 @@ public slots:
Q_INVOKABLE glm::vec3 voxelCoordsToLocalCoords(const QUuid& entityID, glm::vec3 voxelCoords);
/**jsdoc
- * Convert local coordinates to voxel coordinates in a {@link Entities.EntityType|PolyVox} entity. Local coordinates are
- * relative to the minimum axes value corner of the entity, with the scale being the same as world coordinates.
+ * Converts local coordinates to voxel coordinates in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity. Local
+ * coordinates are relative to the minimum axes value corner of the entity, with the scale being the same as world
+ * coordinates. Voxel coordinates are relative to the minimum axes values corner of the entity, with a scale of
+ * Vec3.ONE being the dimensions of each voxel.
* @function Entities.localCoordsToVoxelCoords
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} localCoords - The local coordinates. May be outside the entity's bounding box.
* @returns {Vec3} The voxel coordinates of the worldCoords if the entityID is a
- * {@link Entities.EntityType|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}. The value may be fractional.
+ * {@link Entities.EntityProperties-PolyVox|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}. The value may be
+ * fractional and outside the entity's bounding box.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE glm::vec3 localCoordsToVoxelCoords(const QUuid& entityID, glm::vec3 localCoords);
/**jsdoc
- * Set the linePoints property of a {@link Entities.EntityType|Line} entity.
+ * Sets all the points in a {@link Entities.EntityProperties-Line|Line} entity.
* @function Entities.setAllPoints
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|Line} entity.
- * @param {Vec3[]} points - The array of points to set the entity's linePoints property to.
- * @returns {boolean} true if the entity's property was updated, otherwise false. The property
- * may fail to be updated if the entity does not exist, the entity is not a {@link Entities.EntityType|Line} entity,
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-Line|Line} entity.
+ * @param {Vec3[]} points - The points that the entity should draw lines between.
+ * @returns {boolean} true if the entity was updated, otherwise false. The property may fail to
+ * be updated if the entity does not exist, the entity is not a {@link Entities.EntityProperties-Line|Line} entity,
* one of the points is outside the entity's dimensions, or the number of points is greater than the maximum allowed.
+ * @deprecated This function is deprecated and will be removed. Use {@link Entities.EntityProperties-PolyLine|PolyLine}
+ * entities instead.
* @example Change the shape of a Line entity.
* // Draw a horizontal line between two points.
* var entity = Entities.addEntity({
@@ -925,13 +1152,15 @@ public slots:
Q_INVOKABLE bool setAllPoints(const QUuid& entityID, const QVector& points);
/**jsdoc
- * Append a point to a {@link Entities.EntityType|Line} entity.
+ * Appends a point to a {@link Entities.EntityProperties-Line|Line} entity.
* @function Entities.appendPoint
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|Line} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-Line|Line} entity.
* @param {Vec3} point - The point to add to the line. The coordinates are relative to the entity's position.
* @returns {boolean} true if the point was added to the line, otherwise false. The point may
- * fail to be added if the entity does not exist, the entity is not a {@link Entities.EntityType|Line} entity, the
- * point is outside the entity's dimensions, or the maximum number of points has been reached.
+ * fail to be added if the entity does not exist, the entity is not a {@link Entities.EntityProperties-Line|Line}
+ * entity, the point is outside the entity's dimensions, or the maximum number of points has been reached.
+ * @deprecated This function is deprecated and will be removed. Use {@link Entities.EntityProperties-PolyLine|PolyLine}
+ * entities instead.
* @example Append a point to a Line entity.
* // Draw a line between two points.
* var entity = Entities.addEntity({
@@ -948,26 +1177,29 @@ public slots:
* });
*
* // Add a third point to create a "V".
- * Entities.appendPoint(entity, { x: 1, y: 1, z: 0 });
+ * Script.setTimeout(function () {
+ * Entities.appendPoint(entity, { x: 1, y: 1, z: 0 });
+ * }, 50); // Wait for the entity to be created.
*/
Q_INVOKABLE bool appendPoint(const QUuid& entityID, const glm::vec3& point);
/**jsdoc
- * Dumps debug information about all entities in Interface's local in-memory tree of entities it knows about to the program log.
+ * Dumps debug information about all entities in Interface's local in-memory tree of entities it knows about to the program
+ * log.
* @function Entities.dumpTree
*/
Q_INVOKABLE void dumpTree() const;
/**jsdoc
- * Add an action to an entity. An action is registered with the physics engine and is applied every physics simulation
+ * Adds an action to an entity. An action is registered with the physics engine and is applied every physics simulation
* step. Any entity may have more than one action associated with it, but only as many as will fit in an entity's
- * actionData property.
+ * {@link Entities.EntityProperties|actionData} property.
* @function Entities.addAction
* @param {Entities.ActionType} actionType - The type of action.
* @param {Uuid} entityID - The ID of the entity to add the action to.
- * @param {Entities.ActionArguments} arguments - Configure the action.
- * @returns {Uuid} The ID of the action added if successfully added, otherwise null.
+ * @param {Entities.ActionArguments} arguments - Configures the action.
+ * @returns {Uuid} The ID of the action if successfully added, otherwise null.
* @example Constrain a cube to move along a vertical line.
* var entityID = Entities.addEntity({
* type: "Box",
@@ -988,7 +1220,7 @@ public slots:
Q_INVOKABLE QUuid addAction(const QString& actionTypeString, const QUuid& entityID, const QVariantMap& arguments);
/**jsdoc
- * Update an entity action.
+ * Updates an entity action.
* @function Entities.updateAction
* @param {Uuid} entityID - The ID of the entity with the action to update.
* @param {Uuid} actionID - The ID of the action to update.
@@ -998,67 +1230,67 @@ public slots:
Q_INVOKABLE bool updateAction(const QUuid& entityID, const QUuid& actionID, const QVariantMap& arguments);
/**jsdoc
- * Delete an action from an entity.
+ * Deletes an action from an entity.
* @function Entities.deleteAction
* @param {Uuid} entityID - The ID of entity to delete the action from.
* @param {Uuid} actionID - The ID of the action to delete.
- * @returns {boolean} true if the update was successful, otherwise false.
+ * @returns {boolean} true if the delete was successful, otherwise false.
*/
Q_INVOKABLE bool deleteAction(const QUuid& entityID, const QUuid& actionID);
/**jsdoc
- * Get the IDs of the actions that are associated with an entity.
+ * Gets the IDs of the actions that are associated with an entity.
* @function Entities.getActionIDs
* @param {Uuid} entityID - The entity to get the action IDs for.
- * @returns {Uuid[]} An array of action IDs if any are found, otherwise an empty array.
+ * @returns {Uuid[]} The action IDs if any are found, otherwise an empty array.
*/
Q_INVOKABLE QVector getActionIDs(const QUuid& entityID);
/**jsdoc
- * Get the arguments of an action.
+ * Gets the arguments of an action.
* @function Entities.getActionArguments
* @param {Uuid} entityID - The ID of the entity with the action.
* @param {Uuid} actionID - The ID of the action to get the arguments of.
- * @returns {Entities.ActionArguments} The arguments of the requested action if found, otherwise an empty object.
+ * @returns {Entities.ActionArguments} The arguments of the action if found, otherwise an empty object.
*/
Q_INVOKABLE QVariantMap getActionArguments(const QUuid& entityID, const QUuid& actionID);
/**jsdoc
- * Get the translation of a joint in a {@link Entities.EntityType|Model} entity relative to the entity's position and
- * orientation.
+ * Gets the translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity relative to the entity's
+ * position and orientation.
* @function Entities.getAbsoluteJointTranslationInObjectFrame
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
* @returns {Vec3} The translation of the joint relative to the entity's position and orientation if the entity is a
- * {@link Entities.EntityType|Model} entity, the entity is loaded, and the joint index is valid; otherwise
+ * {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded, and the joint index is valid; otherwise
* {@link Vec3(0)|Vec3.ZERO}.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE glm::vec3 getAbsoluteJointTranslationInObjectFrame(const QUuid& entityID, int jointIndex);
/**jsdoc
- * Get the index of the parent joint.
+ * Gets the index of the parent joint of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.getJointParent
* @param {Uuid} entityID - The ID of the entity.
* @param {number} index - The integer index of the joint.
- * @returns {number} The index of the parent joint.
+ * @returns {number} The index of the parent joint if found, otherwise -1.
*/
Q_INVOKABLE int getJointParent(const QUuid& entityID, int index);
/**jsdoc
- * Get the translation of a joint in a {@link Entities.EntityType|Model} entity relative to the entity's position and
- * orientation.
+ * Gets the translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity relative to the entity's
+ * position and orientation.
* @function Entities.getAbsoluteJointRotationInObjectFrame
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
* @returns {Quat} The rotation of the joint relative to the entity's orientation if the entity is a
- * {@link Entities.EntityType|Model} entity, the entity is loaded, and the joint index is valid; otherwise
+ * {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded, and the joint index is valid; otherwise
* {@link Quat(0)|Quat.IDENTITY}.
* @example Compare the local and absolute rotations of an avatar model's left hand joint.
* entityID = Entities.addEntity({
* type: "Model",
- * modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
+ * modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* lifetime: 300 // Delete after 5 minutes.
@@ -1077,32 +1309,33 @@ public slots:
Q_INVOKABLE glm::quat getAbsoluteJointRotationInObjectFrame(const QUuid& entityID, int jointIndex);
/**jsdoc
- * Set the translation of a joint in a {@link Entities.EntityType|Model} entity relative to the entity's position and
- * orientation.
+ * Sets the translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity relative to the entity's
+ * position and orientation.
* @function Entities.setAbsoluteJointTranslationInObjectFrame
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
* @param {Vec3} translation - The translation to set the joint to relative to the entity's position and orientation.
- * @returns {boolean} trueif the entity is a {@link Entities.EntityType|Model} entity, the entity is loaded,
- * the joint index is valid, and the translation is different to the joint's current translation; otherwise
+ * @returns {boolean} trueif the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
+ * is loaded, the joint index is valid, and the translation is different to the joint's current translation; otherwise
* false.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE bool setAbsoluteJointTranslationInObjectFrame(const QUuid& entityID, int jointIndex, glm::vec3 translation);
/**jsdoc
- * Set the rotation of a joint in a {@link Entities.EntityType|Model} entity relative to the entity's position and
- * orientation.
+ * Sets the rotation of a joint in a {@link Entities.EntityProperties-Model|Model} entity relative to the entity's position
+ * and orientation.
* @function Entities.setAbsoluteJointRotationInObjectFrame
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
* @param {Quat} rotation - The rotation to set the joint to relative to the entity's orientation.
- * @returns {boolean} true if the entity is a {@link Entities.EntityType|Model} entity, the entity is loaded,
- * the joint index is valid, and the rotation is different to the joint's current rotation; otherwise false.
+ * @returns {boolean} true if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
+ * is loaded, the joint index is valid, and the rotation is different to the joint's current rotation; otherwise
+ * false.
* @example Raise an avatar model's left palm.
* entityID = Entities.addEntity({
* type: "Model",
- * modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
+ * modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* lifetime: 300 // Delete after 5 minutes.
@@ -1122,27 +1355,27 @@ public slots:
/**jsdoc
- * Get the local translation of a joint in a {@link Entities.EntityType|Model} entity.
+ * Gets the local translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.getLocalJointTranslation
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
- * @returns {Vec3} The local translation of the joint if the entity is a {@link Entities.EntityType|Model} entity, the
- * entity is loaded, and the joint index is valid; otherwise {@link Vec3(0)|Vec3.ZERO}.
+ * @returns {Vec3} The local translation of the joint if the entity is a {@link Entities.EntityProperties-Model|Model}
+ * entity, the entity is loaded, and the joint index is valid; otherwise {@link Vec3(0)|Vec3.ZERO}.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE glm::vec3 getLocalJointTranslation(const QUuid& entityID, int jointIndex);
/**jsdoc
- * Get the local rotation of a joint in a {@link Entities.EntityType|Model} entity.
+ * Gets the local rotation of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.getLocalJointRotation
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
- * @returns {Quat} The local rotation of the joint if the entity is a {@link Entities.EntityType|Model} entity, the entity
- * is loaded, and the joint index is valid; otherwise {@link Quat(0)|Quat.IDENTITY}.
+ * @returns {Quat} The local rotation of the joint if the entity is a {@link Entities.EntityProperties-Model|Model} entity,
+ * the entity is loaded, and the joint index is valid; otherwise {@link Quat(0)|Quat.IDENTITY}.
* @example Report the local rotation of an avatar model's head joint.
* entityID = Entities.addEntity({
* type: "Model",
- * modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
+ * modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* lifetime: 300 // Delete after 5 minutes.
@@ -1159,30 +1392,31 @@ public slots:
Q_INVOKABLE glm::quat getLocalJointRotation(const QUuid& entityID, int jointIndex);
/**jsdoc
- * Set the local translation of a joint in a {@link Entities.EntityType|Model} entity.
+ * Sets the local translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.setLocalJointTranslation
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
* @param {Vec3} translation - The local translation to set the joint to.
- * @returns {boolean} trueif the entity is a {@link Entities.EntityType|Model} entity, the entity is loaded,
- * the joint index is valid, and the translation is different to the joint's current translation; otherwise
+ * @returns {boolean} trueif the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
+ * is loaded, the joint index is valid, and the translation is different to the joint's current translation; otherwise
* false.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE bool setLocalJointTranslation(const QUuid& entityID, int jointIndex, glm::vec3 translation);
/**jsdoc
- * Set the local rotation of a joint in a {@link Entities.EntityType|Model} entity.
+ * Sets the local rotation of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.setLocalJointRotation
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
* @param {Quat} rotation - The local rotation to set the joint to.
- * @returns {boolean} true if the entity is a {@link Entities.EntityType|Model} entity, the entity is loaded,
- * the joint index is valid, and the rotation is different to the joint's current rotation; otherwise false.
+ * @returns {boolean} true if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
+ * is loaded, the joint index is valid, and the rotation is different to the joint's current rotation; otherwise
+ * false.
* @example Make an avatar model turn its head left.
* entityID = Entities.addEntity({
* type: "Model",
- * modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
+ * modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* lifetime: 300 // Delete after 5 minutes.
@@ -1201,29 +1435,29 @@ public slots:
/**jsdoc
- * Set the local translations of joints in a {@link Entities.EntityType|Model} entity.
+ * Sets the local translations of joints in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.setLocalJointTranslations
* @param {Uuid} entityID - The ID of the entity.
* @param {Vec3[]} translations - The local translations to set the joints to.
- * @returns {boolean} trueif the entity is a {@link Entities.EntityType|Model} entity, the entity is loaded,
- * the model has joints, and at least one of the translations is different to the model's current translations;
- * otherwise false.
+ * @returns {boolean} trueif the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
+ * is loaded, the model has joints, and at least one of the translations is different to the model's current
+ * translations; otherwise false.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE bool setLocalJointTranslations(const QUuid& entityID, const QVector& translations);
/**jsdoc
- * Set the local rotations of joints in a {@link Entities.EntityType|Model} entity.
+ * Sets the local rotations of joints in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.setLocalJointRotations
* @param {Uuid} entityID - The ID of the entity.
* @param {Quat[]} rotations - The local rotations to set the joints to.
- * @returns {boolean} true if the entity is a {@link Entities.EntityType|Model} entity, the entity is loaded,
- * the model has joints, and at least one of the rotations is different to the model's current rotations; otherwise
- * false.
+ * @returns {boolean} true if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
+ * is loaded, the model has joints, and at least one of the rotations is different to the model's current rotations;
+ * otherwise false.
* @example Raise both palms of an avatar model.
* entityID = Entities.addEntity({
* type: "Model",
- * modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
+ * modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* lifetime: 300 // Delete after 5 minutes.
@@ -1255,16 +1489,16 @@ public slots:
Q_INVOKABLE bool setLocalJointRotations(const QUuid& entityID, const QVector& rotations);
/**jsdoc
- * Set the local rotations and translations of joints in a {@link Entities.EntityType|Model} entity. This is the same as
- * calling both {@link Entities.setLocalJointRotations|setLocalJointRotations} and
+ * Sets the local rotations and translations of joints in a {@link Entities.EntityProperties-Model|Model} entity. This is
+ * the same as calling both {@link Entities.setLocalJointRotations|setLocalJointRotations} and
* {@link Entities.setLocalJointTranslations|setLocalJointTranslations} at the same time.
* @function Entities.setLocalJointsData
* @param {Uuid} entityID - The ID of the entity.
* @param {Quat[]} rotations - The local rotations to set the joints to.
* @param {Vec3[]} translations - The local translations to set the joints to.
- * @returns {boolean} true if the entity is a {@link Entities.EntityType|Model} entity, the entity is loaded,
- * the model has joints, and at least one of the rotations or translations is different to the model's current values;
- * otherwise false.
+ * @returns {boolean} true if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
+ * is loaded, the model has joints, and at least one of the rotations or translations is different to the model's
+ * current values; otherwise false.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE bool setLocalJointsData(const QUuid& entityID,
@@ -1273,17 +1507,17 @@ public slots:
/**jsdoc
- * Get the index of a named joint in a {@link Entities.EntityType|Model} entity.
+ * Gets the index of a named joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.getJointIndex
* @param {Uuid} entityID - The ID of the entity.
* @param {string} name - The name of the joint.
- * @returns {number} The integer index of the joint if the entity is a {@link Entities.EntityType|Model} entity, the entity
- * is loaded, and the joint is present; otherwise -1. The joint indexes are in order per
- * {@link Entities.getJointNames|getJointNames}.
+ * @returns {number} The integer index of the joint if the entity is a {@link Entities.EntityProperties-Model|Model}
+ * entity, the entity is loaded, and the joint is present; otherwise -1. The joint indexes are in order
+ * per {@link Entities.getJointNames|getJointNames}.
* @example Report the index of a model's head joint.
* entityID = Entities.addEntity({
* type: "Model",
- * modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
+ * modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* lifetime: 300 // Delete after 5 minutes.
@@ -1299,15 +1533,16 @@ public slots:
Q_INVOKABLE int getJointIndex(const QUuid& entityID, const QString& name);
/**jsdoc
- * Get the names of all the joints in a {@link Entities.EntityType|Model} entity.
+ * Gets the names of all the joints in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.getJointNames
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|Model} entity.
- * @returns {string[]} The names of all the joints in the entity if it is a {@link Entities.EntityType|Model} entity and
- * is loaded, otherwise an empty array. The joint names are in order per {@link Entities.getJointIndex|getJointIndex}.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-Model|Model} entity.
+ * @returns {string[]} The names of all the joints in the entity if it is a {@link Entities.EntityProperties-Model|Model}
+ * entity and is loaded, otherwise an empty array. The joint names are in order per
+ * {@link Entities.getJointIndex|getJointIndex}.
* @example Report a model's joint names.
* entityID = Entities.addEntity({
* type: "Model",
- * modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
+ * modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* lifetime: 300 // Delete after 5 minutes.
@@ -1324,7 +1559,8 @@ public slots:
/**jsdoc
- * Get the IDs of entities and avatars that are directly parented to an entity or avatar model. Recurse on the IDs returned by the function to get all descendants of an entity or avatar.
+ * Gets the IDs of entities and avatars that are directly parented to an entity or avatar model. To get all descendants,
+ * you can recurse on the IDs returned.
* @function Entities.getChildrenIDs
* @param {Uuid} parentID - The ID of the entity or avatar to get the children IDs of.
* @returns {Uuid[]} An array of entity and avatar IDs that are parented directly to the parentID
@@ -1354,7 +1590,8 @@ public slots:
Q_INVOKABLE QVector getChildrenIDs(const QUuid& parentID);
/**jsdoc
- * Get the IDs of entities and avatars that are directly parented to an entity or avatar model's joint.
+ * Gets the IDs of entities and avatars that are directly parented to an entity or avatar model's joint. To get all
+ * descendants, you can use {@link Entities.getChildrenIDs|getChildrenIDs} to recurse on the IDs returned.
* @function Entities.getChildrenIDsOfJoint
* @param {Uuid} parentID - The ID of the entity or avatar to get the children IDs of.
* @param {number} jointIndex - Integer number of the model joint to get the children IDs of.
@@ -1378,18 +1615,20 @@ public slots:
* var root = createEntity("Root", position, Uuid.NULL);
* var child = createEntity("Child", Vec3.sum(position, { x: 0, y: -1, z: 0 }), root);
*
- * Entities.editEntity(root, {
- * parentID: MyAvatar.sessionUUID,
- * parentJointIndex: MyAvatar.getJointIndex("RightHand")
- * });
- *
- * var children = Entities.getChildrenIDsOfJoint(MyAvatar.sessionUUID, MyAvatar.getJointIndex("RightHand"));
- * print("Children of hand: " + JSON.stringify(children)); // Only the root entity.
+ * Script.setTimeout(function () { // Wait for the entity to be created before editing.
+ * Entities.editEntity(root, {
+ * parentID: MyAvatar.sessionUUID,
+ * parentJointIndex: MyAvatar.getJointIndex("RightHand")
+ * });
+ *
+ * var children = Entities.getChildrenIDsOfJoint(MyAvatar.sessionUUID, MyAvatar.getJointIndex("RightHand"));
+ * print("Children of hand: " + JSON.stringify(children)); // Only the root entity.
+ * }, 50);
*/
Q_INVOKABLE QVector getChildrenIDsOfJoint(const QUuid& parentID, int jointIndex);
/**jsdoc
- * Check whether an entity has an entity as an ancestor (parent, parent's parent, etc.).
+ * Checks whether an entity has an entity as an ancestor (parent, parent's parent, etc.).
* @function Entities.isChildOfParent
* @param {Uuid} childID - The ID of the child entity to test for being a child, grandchild, etc.
* @param {Uuid} parentID - The ID of the parent entity to test for being a parent, grandparent, etc.
@@ -1418,12 +1657,11 @@ public slots:
Q_INVOKABLE bool isChildOfParent(const QUuid& childID, const QUuid& parentID);
/**jsdoc
- * Get the type — entity or avatar — of an in-world item.
+ * Gets the type — entity or avatar — of an in-world item.
* @function Entities.getNestableType
* @param {Uuid} id - The ID of the item to get the type of.
- * @returns {string} The type of the item: "entity" if the item is an entity, "avatar"
- * if the item is an avatar; otherwise "unknown" if the item cannot be found.
- * @example Print some nestable types.
+ * @returns {Entities.NestableType} The type of the item.
+ * @example Report some nestable types.
* var entity = Entities.addEntity({
* type: "Sphere",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 1, z: -2 })),
@@ -1436,22 +1674,22 @@ public slots:
Q_INVOKABLE QString getNestableType(const QUuid& id);
/**jsdoc
- * Get the ID of the {@link Entities.EntityType|Web} entity that has keyboard focus.
+ * Gets the ID of the {@link Entities.EntityProperties-Web|Web} entity that has keyboard focus.
* @function Entities.getKeyboardFocusEntity
- * @returns {Uuid} The ID of the {@link Entities.EntityType|Web} entity that has focus, if any, otherwise null.
+ * @returns {Uuid} The ID of the {@link Entities.EntityProperties-Web|Web} entity that has focus, if any, otherwise null.
*/
Q_INVOKABLE QUuid getKeyboardFocusEntity() const;
/**jsdoc
- * Set the {@link Entities.EntityType|Web} entity that has keyboard focus.
+ * Sets the {@link Entities.EntityProperties-Web|Web} entity that has keyboard focus.
* @function Entities.setKeyboardFocusEntity
- * @param {Uuid} id - The ID of the {@link Entities.EntityType|Web} entity to set keyboard focus to. Use
+ * @param {Uuid} id - The ID of the {@link Entities.EntityProperties-Web|Web} entity to set keyboard focus to. Use
* null or {@link Uuid(0)|Uuid.NULL} to unset keyboard focus from an entity.
*/
Q_INVOKABLE void setKeyboardFocusEntity(const QUuid& id);
/**jsdoc
- * Emit a {@link Entities.mousePressOnEntity|mousePressOnEntity} event.
+ * Emits a {@link Entities.mousePressOnEntity|mousePressOnEntity} event.
* @function Entities.sendMousePressOnEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1459,7 +1697,7 @@ public slots:
Q_INVOKABLE void sendMousePressOnEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Emit a {@link Entities.mouseMoveOnEntity|mouseMoveOnEntity} event.
+ * Emits a {@link Entities.mouseMoveOnEntity|mouseMoveOnEntity} event.
* @function Entities.sendMouseMoveOnEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1467,7 +1705,7 @@ public slots:
Q_INVOKABLE void sendMouseMoveOnEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Emit a {@link Entities.mouseReleaseOnEntity|mouseReleaseOnEntity} event.
+ * Emits a {@link Entities.mouseReleaseOnEntity|mouseReleaseOnEntity} event.
* @function Entities.sendMouseReleaseOnEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1475,7 +1713,7 @@ public slots:
Q_INVOKABLE void sendMouseReleaseOnEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Emit a {@link Entities.clickDownOnEntity|clickDownOnEntity} event.
+ * Emits a {@link Entities.clickDownOnEntity|clickDownOnEntity} event.
* @function Entities.sendClickDownOnEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1483,7 +1721,7 @@ public slots:
Q_INVOKABLE void sendClickDownOnEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Emit a {@link Entities.holdingClickOnEntity|holdingClickOnEntity} event.
+ * Emits a {@link Entities.holdingClickOnEntity|holdingClickOnEntity} event.
* @function Entities.sendHoldingClickOnEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1491,7 +1729,7 @@ public slots:
Q_INVOKABLE void sendHoldingClickOnEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Emit a {@link Entities.clickReleaseOnEntity|clickReleaseOnEntity} event.
+ * Emits a {@link Entities.clickReleaseOnEntity|clickReleaseOnEntity} event.
* @function Entities.sendClickReleaseOnEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1499,7 +1737,7 @@ public slots:
Q_INVOKABLE void sendClickReleaseOnEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Emit a {@link Entities.hoverEnterEntity|hoverEnterEntity} event.
+ * Emits a {@link Entities.hoverEnterEntity|hoverEnterEntity} event.
* @function Entities.sendHoverEnterEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1507,7 +1745,7 @@ public slots:
Q_INVOKABLE void sendHoverEnterEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Emit a {@link Entities.hoverOverEntity|hoverOverEntity} event.
+ * Emits a {@link Entities.hoverOverEntity|hoverOverEntity} event.
* @function Entities.sendHoverOverEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1515,7 +1753,7 @@ public slots:
Q_INVOKABLE void sendHoverOverEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Emit a {@link Entities.hoverLeaveEntity|hoverLeaveEntity} event.
+ * Emits a {@link Entities.hoverLeaveEntity|hoverLeaveEntity} event.
* @function Entities.sendHoverLeaveEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1523,8 +1761,8 @@ public slots:
Q_INVOKABLE void sendHoverLeaveEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Check whether an entity wants hand controller pointer events. For example, a {@link Entities.EntityType|Web} entity does
- * but a {@link Entities.EntityType|Shape} entity doesn't.
+ * Checks whether an entity wants hand controller pointer events. For example, a {@link Entities.EntityProperties-Web|Web}
+ * entity does but a {@link Entities.EntityProperties-Shape|Shape} entity doesn't.
* @function Entities.wantsHandControllerPointerEvents
* @param {Uuid} entityID - The ID of the entity.
* @returns {boolean} true if the entity can be found and it wants hand controller pointer events, otherwise
@@ -1533,35 +1771,89 @@ public slots:
Q_INVOKABLE bool wantsHandControllerPointerEvents(const QUuid& id);
/**jsdoc
- * Send a script event over a {@link Entities.EntityType|Web} entity's EventBridge to the Web page's scripts.
+ * Sends a message to a {@link Entities.EntityProperties-Web|Web} entity's HTML page. To receive the message, the web
+ * page's script must connect to the EventBridge that is automatically provided to the script:
+ * EventBridge.scriptEventReceived.connect(function(message) {
+ * ...
+ * });
+ * Use {@link Entities.webEventReceived} to receive messages from the Web entity's HTML page.
+ * Alternatively, you can use {@link Entities.getEntityObject} to exchange messages over a Web entity's HTML event
+ * bridge.
* @function Entities.emitScriptEvent
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|Web} entity.
+ * @param {Uuid} entityID - The ID of the Web entity to send the message to.
* @param {string} message - The message to send.
+ * @example Exchange messages with a Web entity.
+ * // HTML file, name: "webEntity.html".
+ *
+ *
+ *
+ * HELLO
+ *
+ *
+ * HELLO
+ *
+ *
+ *
+ *
+ * // Script file.
+ * var webEntity = Entities.addEntity({
+ * type: "Web",
+ * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -3 })),
+ * rotation: MyAvatar.orientation,
+ * sourceUrl: Script.resolvePath("webEntity.html"),
+ * alpha: 1.0,
+ * lifetime: 300 // 5 min
+ * });
+ *
+ * function onWebEventReceived(entityID, message) {
+ * if (entityID === webEntity) {
+ * // Message received.
+ * print("Message received: " + message);
+ *
+ * // Send a message back.
+ * Entities.emitScriptEvent(webEntity, message + " back");
+ * }
+ * }
+ *
+ * Entities.webEventReceived.connect(onWebEventReceived);
*/
Q_INVOKABLE void emitScriptEvent(const EntityItemID& entityID, const QVariant& message);
/**jsdoc
- * Check whether an axis-aligned box and a capsule intersect.
+ * Checks whether an axis-aligned box and a capsule intersect.
* @function Entities.AABoxIntersectsCapsule
* @param {Vec3} brn - The bottom right near (minimum axes values) corner of the AA box.
* @param {Vec3} dimensions - The dimensions of the AA box.
* @param {Vec3} start - One end of the capsule.
* @param {Vec3} end - The other end of the capsule.
- * @param {number} radius - The radiues of the capsule.
+ * @param {number} radius - The radius of the capsule.
* @returns {boolean} true if the AA box and capsule intersect, otherwise false.
*/
Q_INVOKABLE bool AABoxIntersectsCapsule(const glm::vec3& low, const glm::vec3& dimensions,
const glm::vec3& start, const glm::vec3& end, float radius);
/**jsdoc
- * Get the meshes in a {@link Entities.EntityType|Model} or {@link Entities.EntityType|PolyVox} entity.
+ * Gets the meshes in a {@link Entities.EntityProperties-Model|Model} or {@link Entities.EntityProperties-PolyVox|PolyVox}
+ * entity.
* @function Entities.getMeshes
* @param {Uuid} entityID - The ID of the Model or PolyVox entity to get the meshes of.
* @param {Entities~getMeshesCallback} callback - The function to call upon completion.
* @deprecated This function is deprecated and will be removed. Use the {@link Graphics} API instead.
*/
/**jsdoc
- * Called when {@link Entities.getMeshes} is complete.
+ * Called when a {@link Entities.getMeshes} call is complete.
* @callback Entities~getMeshesCallback
* @param {MeshProxy[]} meshes - If success< is true, a {@link MeshProxy} per mesh in the
* Model or PolyVox entity; otherwise undefined.
@@ -1573,7 +1865,7 @@ public slots:
Q_INVOKABLE void getMeshes(const QUuid& entityID, QScriptValue callback);
/**jsdoc
- * Get the object to world transform, excluding scale, of an entity.
+ * Gets the object to world transform, excluding scale, of an entity.
* @function Entities.getEntityTransform
* @param {Uuid} entityID - The ID of the entity.
* @returns {Mat4} The entity's object to world transform excluding scale (i.e., translation and rotation, with scale of 1)
@@ -1601,11 +1893,12 @@ public slots:
Q_INVOKABLE glm::mat4 getEntityTransform(const QUuid& entityID);
/**jsdoc
- * Get the object to parent transform, excluding scale, of an entity.
+ * Gets the object to parent transform, excluding scale, of an entity.
* @function Entities.getEntityLocalTransform
* @param {Uuid} entityID - The ID of the entity.
* @returns {Mat4} The entity's object to parent transform excluding scale (i.e., translation and rotation, with scale of
- * 1) if the entity can be found, otherwise a transform with zero translation and rotation and a scale of 1.
+ * 1) if the entity can be found, otherwise a transform with zero translation and rotation and a scale of 1. If the
+ * entity doesn't have a parent, its world transform is returned.
* @example Position and rotation in an entity's local transform.
* function createEntity(position, rotation, parent) {
* var entity = Entities.addEntity({
@@ -1636,141 +1929,193 @@ public slots:
/**jsdoc
+ * Converts a position in world coordinates to a position in an avatar, entity, or joint's local coordinates.
* @function Entities.worldToLocalPosition
- * @param {Vec3} worldPosition
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Vec3}
+ * @param {Vec3} worldPosition - The world position to convert.
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - The joint in the avatar or entity that the local coordinates are based on. If
+ * -1 then no joint is used and the local coordinates are based solely on the avatar or entity.
+ * @param {boolean} [scalesWithParent= false] - true to scale the local position per the parent's scale,
+ * false for the local position to be at world scale.
+ * @returns {Vec3} The position converted to local coordinates if successful, otherwise {@link Vec3(0)|Vec3.ZERO}.
+ * @example Report the local coordinates of an entity parented to another.
+ * var parentPosition = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 }));
+ * var childPosition = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 1, z: -5 }));
+ *
+ * var parentEntity = Entities.addEntity({
+ * type: "Box",
+ * position: parentPosition,
+ * rotation: MyAvatar.orientation,
+ * dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+ * lifetime: 300 // Delete after 5 minutes.
+ * });
+ * var childEntity = Entities.addEntity({
+ * type: "Sphere",
+ * position: childPosition,
+ * dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+ * parentID: parentEntity,
+ * lifetime: 300 // Delete after 5 minutes.
+ * });
+ *
+ * var localPosition = Entities.worldToLocalPosition(childPosition, parentEntity);
+ * print("Local position: " + JSON.stringify(localPosition)); // 0, 1, 0.
+ * localPosition = Entities.getEntityProperties(childEntity, "localPosition").localPosition;
+ * print("Local position: " + JSON.stringify(localPosition)); // The same.
*/
Q_INVOKABLE glm::vec3 worldToLocalPosition(glm::vec3 worldPosition, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts a rotation or orientation in world coordinates to rotation in an avatar, entity, or joint's local coordinates.
* @function Entities.worldToLocalRotation
- * @param {Quat} worldRotation
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Quat}
+ * @param {Quat} worldRotation - The world rotation to convert.
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - The joint in the avatar or entity that the local coordinates are based on. If
+ * -1 then no joint is used and the local coordinates are based solely on the avatar or entity.
+ * @param {boolean} [scalesWithParent=false] - Not used in the calculation.
+ * @returns {Quat} The rotation converted to local coordinates if successful, otherwise {@link Quat(0)|Quat.IDENTITY}.
*/
Q_INVOKABLE glm::quat worldToLocalRotation(glm::quat worldRotation, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts a velocity in world coordinates to a velocity in an avatar, entity, or joint's local coordinates.
* @function Entities.worldToLocalVelocity
- * @param {Vec3} worldVelocity
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Vec3}
+ * @param {Vec3} worldVelocity - The world velocity to convert.
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - The joint in the avatar or entity that the local coordinates are based on. If
+ * -1 then no joint is used and the local coordinates are based solely on the avatar or entity.
+ * @param {boolean} [scalesWithParent=false] - true to scale the local velocity per the parent's scale,
+ * false for the local velocity to be at world scale.
+ * @returns {Vec3} The velocity converted to local coordinates if successful, otherwise {@link Vec3(0)|Vec3.ZERO}.
*/
Q_INVOKABLE glm::vec3 worldToLocalVelocity(glm::vec3 worldVelocity, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts a Euler angular velocity in world coordinates to an angular velocity in an avatar, entity, or joint's local
+ * coordinates.
* @function Entities.worldToLocalAngularVelocity
- * @param {Vec3} worldAngularVelocity
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Vec3}
+ * @param {Vec3} worldAngularVelocity - The world Euler angular velocity to convert. (Can be in any unit, e.g., deg/s or
+ * rad/s.)
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - The joint in the avatar or entity that the local coordinates are based on. If
+ * -1 then no joint is used and the local coordinates are based solely on the avatar or entity.
+ * @param {boolean} [scalesWithParent=false] - Not used in the calculation.
+ * @returns {Vec3} The angular velocity converted to local coordinates if successful, otherwise {@link Vec3(0)|Vec3.ZERO}.
*/
Q_INVOKABLE glm::vec3 worldToLocalAngularVelocity(glm::vec3 worldAngularVelocity, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts dimensions in world coordinates to dimensions in an avatar or entity's local coordinates.
* @function Entities.worldToLocalDimensions
- * @param {Vec3} worldDimensions
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Vec3}
+ * @param {Vec3} worldDimensions - The world dimensions to convert.
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - Not used in the calculation.
+ * @param {boolean} [scalesWithParent=false] - true to scale the local dimensions per the parent's scale,
+ * false for the local dimensions to be at world scale.
+ * @returns {Vec3} The dimensions converted to local coordinates if successful, otherwise {@link Vec3(0)|Vec3.ZERO}.
*/
Q_INVOKABLE glm::vec3 worldToLocalDimensions(glm::vec3 worldDimensions, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts a position in an avatar, entity, or joint's local coordinate to a position in world coordinates.
* @function Entities.localToWorldPosition
- * @param {Vec3} localPosition
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Vec3}
+ * @param {Vec3} localPosition - The local position to convert.
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - The joint in the avatar or entity that the local coordinates are based on. If
+ * -1 then no joint is used and the local coordinates are based solely on the avatar or entity.
+ * @param {boolean} [scalesWithparent=false] - true if the local dimensions are scaled per the parent's scale,
+ * false if the local dimensions are at world scale.
+ * @returns {Vec3} The position converted to world coordinates if successful, otherwise {@link Vec3(0)|Vec3.ZERO}.
*/
Q_INVOKABLE glm::vec3 localToWorldPosition(glm::vec3 localPosition, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts a rotation or orientation in an avatar, entity, or joint's local coordinate to a rotation in world coordinates.
* @function Entities.localToWorldRotation
- * @param {Quat} localRotation
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Quat}
+ * @param {Quat} localRotation - The local rotation to convert.
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - The joint in the avatar or entity that the local coordinates are based on. If
+ * -1 then no joint is used and the local coordinates are based solely on the avatar or entity.
+ * @param {boolean} [scalesWithParent= false] - Not used in the calculation.
+ * @returns {Quat} The rotation converted to local coordinates if successful, otherwise {@link Quat(0)|Quat.IDENTITY}.
*/
Q_INVOKABLE glm::quat localToWorldRotation(glm::quat localRotation, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts a velocity in an avatar, entity, or joint's local coordinate to a velocity in world coordinates.
* @function Entities.localToWorldVelocity
- * @param {Vec3} localVelocity
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Vec3}
+ * @param {Vec3} localVelocity - The local velocity to convert.
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - The joint in the avatar or entity that the local coordinates are based on. If
+ * -1 then no joint is used and the local coordinates are based solely on the avatar or entity.
+ * @param {boolean} [scalesWithParent= false] - true if the local velocity is scaled per the parent's scale,
+ * false if the local velocity is at world scale.
+ * @returns {Vec3} The velocity converted to world coordinates it successful, otherwise {@link Vec3(0)|Vec3.ZERO}.
*/
Q_INVOKABLE glm::vec3 localToWorldVelocity(glm::vec3 localVelocity, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts a Euler angular velocity in an avatar, entity, or joint's local coordinate to an angular velocity in world
+ * coordinates.
* @function Entities.localToWorldAngularVelocity
- * @param {Vec3} localAngularVelocity
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Vec3}
+ * @param {Vec3} localAngularVelocity - The local Euler angular velocity to convert. (Can be in any unit, e.g., deg/s or
+ * rad/s.)
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - The joint in the avatar or entity that the local coordinates are based on. If
+ * -1 then no joint is used and the local coordinates are based solely on the avatar or entity.
+ * @param {boolean} [scalesWithParent= false] - Not used in the calculation.
+ * @returns {Vec3} The angular velocity converted to world coordinates if successful, otherwise {@link Vec3(0)|Vec3.ZERO}.
*/
Q_INVOKABLE glm::vec3 localToWorldAngularVelocity(glm::vec3 localAngularVelocity, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts dimensions in an avatar or entity's local coordinates to dimensions in world coordinates.
* @function Entities.localToWorldDimensions
- * @param {Vec3} localDimensions
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Vec3}
+ * @param {Vec3} localDimensions - The local dimensions to convert.
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - Not used in the calculation.
+ * @param {boolean} [scalesWithParent= false] - true if the local dimensions are scaled per the parent's
+ * scale, false if the local dimensions are at world scale.
+ * @returns {Vec3} The dimensions converted to world coordinates if successful, otherwise {@link Vec3(0)|Vec3.ZERO}.
*/
Q_INVOKABLE glm::vec3 localToWorldDimensions(glm::vec3 localDimensions, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
- * Get the static certificate for an entity. The static certificate contains static properties of the item which cannot
- * be altered.
- * @function Entities.getStaticCertificateJSON
- * @param {Uuid} entityID - The ID of the entity to get the static certificate for.
- * @returns {string} The entity's static certificate as a JSON string if the entity can be found, otherwise an empty string.
- */
+ * Gets the static certificate for an entity. The static certificate contains static properties of the item which cannot
+ * be altered.
+ * @function Entities.getStaticCertificateJSON
+ * @param {Uuid} entityID - The ID of the entity to get the static certificate for.
+ * @returns {string} The entity's static certificate as a JSON string if the entity can be found, otherwise "".
+ */
Q_INVOKABLE QString getStaticCertificateJSON(const QUuid& entityID);
/**jsdoc
- * Verify the entity's proof of provenance, i.e., that the entity's certificateID property was produced by
+ * Verifies the entity's proof of provenance, i.e., that the entity's certificateID property was produced by
* High Fidelity signing the entity's static certificate JSON.
* @function Entities.verifyStaticCertificateProperties
* @param {Uuid} entityID - The ID of the entity to verify.
- * @returns {boolean} true if the entity can be found an its certificateID property is present
- * and its value matches the entity's static certificate JSON; otherwise false.
+ * @returns {boolean} true if the entity can be found, its certificateID property is present, and
+ * its value matches the entity's static certificate JSON; otherwise false.
*/
Q_INVOKABLE bool verifyStaticCertificateProperties(const QUuid& entityID);
/**jsdoc
- * Get information about entity properties including a minimum to maximum range for numerical properties
- * as well as property enum value.
+ * Gets information about an entity property, including a minimum to maximum range for some numerical properties.
* @function Entities.getPropertyInfo
* @param {string} propertyName - The name of the property to get the information for.
- * @returns {Entities.EntityPropertyInfo} The information data including propertyEnum, minimum, and maximum
- * if the property can be found, otherwise an empty object.
+ * @returns {Entities.EntityPropertyInfo} The information about the property if it can be found, otherwise an empty object.
+ * @example Report property info. for some properties.
+ * print("alpha: " + JSON.stringify(Entities.getPropertyInfo("alpha")));
+ * print("script: " + JSON.stringify(Entities.getPropertyInfo("script")));
*/
Q_INVOKABLE const EntityPropertyInfo getPropertyInfo(const QString& propertyName) const;
signals:
/**jsdoc
- * Triggered on the client that is the physics simulation owner during the collision of two entities. Note: Isn't triggered
+ * Triggered on the client that is the physics simulation owner during the collision of two entities. Note: Isn't triggered
* for a collision with an avatar.
- * See also, {@link Script.addEventHandler}.
+ * See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.
* @function Entities.collisionWithEntity
* @param {Uuid} idA - The ID of one entity in the collision. For an entity script, this is the ID of the entity containing
* the script.
@@ -1813,7 +2158,7 @@ signals:
* Triggered when your ability to change the locked property of entities changes.
* @function Entities.canAdjustLocksChanged
* @param {boolean} canAdjustLocks - true if the script can change the locked property of an
- * entity, otherwise false.
+ * entity, false if it can't.
* @returns {Signal}
* @example Report when your ability to change locks changes.
* function onCanAdjustLocksChanged(canAdjustLocks) {
@@ -1826,7 +2171,7 @@ signals:
/**jsdoc
* Triggered when your ability to rez (create) entities changes.
* @function Entities.canRezChanged
- * @param {boolean} canRez - true if the script can rez (create) entities, otherwise false.
+ * @param {boolean} canRez - true if the script can rez (create) entities, false if it can't.
* @returns {Signal}
*/
void canRezChanged(bool canRez);
@@ -1835,8 +2180,8 @@ signals:
* Triggered when your ability to rez (create) temporary entities changes. Temporary entities are entities with a finite
* lifetime property value set.
* @function Entities.canRezTmpChanged
- * @param {boolean} canRezTmp - true if the script can rez (create) temporary entities, otherwise
- * false.
+ * @param {boolean} canRezTmp - true if the script can rez (create) temporary entities, false if
+ * it can't.
* @returns {Signal}
*/
void canRezTmpChanged(bool canRezTmp);
@@ -1845,8 +2190,8 @@ signals:
* Triggered when your ability to rez (create) certified entities changes. Certified entities are entities that have PoP
* certificates.
* @function Entities.canRezCertifiedChanged
- * @param {boolean} canRezCertified - true if the script can rez (create) certified entities, otherwise
- * false.
+ * @param {boolean} canRezCertified - true if the script can rez (create) certified entities,
+ * false if it can't.
* @returns {Signal}
*/
void canRezCertifiedChanged(bool canRezCertified);
@@ -1856,7 +2201,7 @@ signals:
* finite lifetime property value set. Certified entities are entities that have PoP certificates.
* @function Entities.canRezTmpCertifiedChanged
* @param {boolean} canRezTmpCertified - true if the script can rez (create) temporary certified entities,
- * otherwise false.
+ * false if it can't.
* @returns {Signal}
*/
void canRezTmpCertifiedChanged(bool canRezTmpCertified);
@@ -1865,7 +2210,7 @@ signals:
* Triggered when your ability to make changes to the asset server's assets changes.
* @function Entities.canWriteAssetsChanged
* @param {boolean} canWriteAssets - true if the script can change the ? property of an entity,
- * otherwise false.
+ * false if it can't.
* @returns {Signal}
*/
void canWriteAssetsChanged(bool canWriteAssets);
@@ -1873,8 +2218,8 @@ signals:
/**jsdoc
* Triggered when your ability to get and set private user data changes.
* @function Entities.canGetAndSetPrivateUserDataChanged
- * @param {boolean} canGetAndSetPrivateUserData - true if you can change the privateUserData property of an entity,
- * otherwise false.
+ * @param {boolean} canGetAndSetPrivateUserData - true if the script change the privateUserData
+ * property of an entity, false if it can't.
* @returns {Signal}
*/
void canGetAndSetPrivateUserDataChanged(bool canGetAndSetPrivateUserData);
@@ -1883,9 +2228,9 @@ signals:
/**jsdoc
* Triggered when a mouse button is clicked while the mouse cursor is on an entity, or a controller trigger is fully
* pressed while its laser is on an entity.
- * See also, {@link Script.addEventHandler}.
+ * See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.
* @function Entities.mousePressOnEntity
- * @param {Uuid} entityID - The ID of the entity that was pressed.
+ * @param {Uuid} entityID - The ID of the entity that was pressed on.
* @param {PointerEvent} event - Details of the event.
* @returns {Signal}
* @example Report when an entity is clicked with the mouse or laser.
@@ -1900,7 +2245,7 @@ signals:
/**jsdoc
* Triggered when a mouse button is double-clicked while the mouse cursor is on an entity.
* @function Entities.mouseDoublePressOnEntity
- * @param {Uuid} entityID - The ID of the entity that was double-pressed.
+ * @param {Uuid} entityID - The ID of the entity that was double-pressed on.
* @param {PointerEvent} event - Details of the event.
* @returns {Signal}
*/
@@ -1908,7 +2253,7 @@ signals:
/**jsdoc
* Repeatedly triggered while the mouse cursor or controller laser moves on an entity.
- * See also, {@link Script.addEventHandler}.
+ * See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.
* @function Entities.mouseMoveOnEntity
* @param {Uuid} entityID - The ID of the entity that was moved on.
* @param {PointerEvent} event - Details of the event.
@@ -1919,7 +2264,7 @@ signals:
/**jsdoc
* Triggered when a mouse button is released after clicking on an entity or the controller trigger is partly or fully
* released after pressing on an entity, even if the mouse pointer or controller laser has moved off the entity.
- * See also, {@link Script.addEventHandler}.
+ * See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.
* @function Entities.mouseReleaseOnEntity
* @param {Uuid} entityID - The ID of the entity that was originally pressed.
* @param {PointerEvent} event - Details of the event.
@@ -1945,19 +2290,42 @@ signals:
/**jsdoc
- * Triggered when a mouse button is clicked while the mouse cursor is on an entity. Note: Not triggered by controller.
- * See also, {@link Script.addEventHandler}.
+ * Triggered when a mouse button is clicked while the mouse cursor is on an entity. Note: Not triggered by controllers.
+ * See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.
* @function Entities.clickDownOnEntity
- * @param {Uuid} entityID - The ID of the entity that was clicked.
+ * @param {Uuid} entityID - The ID of the entity that was clicked on.
* @param {PointerEvent} event - Details of the event.
* @returns {Signal}
+ * @example Compare clickDownOnEntity signal and entity script method.
+ * var entityScript = (function () {
+ * // Method is called for only this entity.
+ * this.clickDownOnEntity = function (entityID, event) {
+ * print("Entity : Clicked sphere ; " + event.type);
+ * };
+ * });
+ *
+ * var sphereID = Entities.addEntity({
+ * type: "Sphere",
+ * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
+ * script: "(" + entityScript + ")", // Could host the script on a Web server instead.
+ * lifetime: 300 // Delete after 5 minutes.
+ * });
+ *
+ * Entities.clickDownOnEntity.connect(function (entityID, event) {
+ * // Signal is triggered for all entities.
+ * if (entityID === sphereID) {
+ * print("Interface : Clicked sphere ; " + event.type);
+ * } else {
+ * print("Interface : Clicked another entity ; " + event.type);
+ * }
+ * });
*/
void clickDownOnEntity(const EntityItemID& entityItemID, const PointerEvent& event);
/**jsdoc
* Repeatedly triggered while a mouse button continues to be held after clicking an entity, even if the mouse cursor has
- * moved off the entity. Note: Not triggered by controller.
- * See also, {@link Script.addEventHandler}.
+ * moved off the entity. Note: Not triggered by controllers.
+ * See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.
* @function Entities.holdingClickOnEntity
* @param {Uuid} entityID - The ID of the entity that was originally clicked.
* @param {PointerEvent} event - Details of the event.
@@ -1967,8 +2335,8 @@ signals:
/**jsdoc
* Triggered when a mouse button is released after clicking on an entity, even if the mouse cursor has moved off the
- * entity. Note: Not triggered by controller.
- * See also, {@link Script.addEventHandler}.
+ * entity. Note: Not triggered by controllers.
+ * See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.
* @function Entities.clickReleaseOnEntity
* @param {Uuid} entityID - The ID of the entity that was originally clicked.
* @param {PointerEvent} event - Details of the event.
@@ -1978,7 +2346,7 @@ signals:
/**jsdoc
* Triggered when the mouse cursor or controller laser starts hovering on an entity.
- * See also, {@link Script.addEventHandler}.
+ * See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.
* @function Entities.hoverEnterEntity
* @param {Uuid} entityID - The ID of the entity that is being hovered.
* @param {PointerEvent} event - Details of the event.
@@ -1988,7 +2356,7 @@ signals:
/**jsdoc
* Repeatedly triggered when the mouse cursor or controller laser moves while hovering over an entity.
- * See also, {@link Script.addEventHandler}.
+ * See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.
* @function Entities.hoverOverEntity
* @param {Uuid} entityID - The ID of the entity that is being hovered.
* @param {PointerEvent} event - Details of the event.
@@ -1998,7 +2366,7 @@ signals:
/**jsdoc
* Triggered when the mouse cursor or controller laser stops hovering over an entity.
- * See also, {@link Script.addEventHandler}.
+ * See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.
* @function Entities.hoverLeaveEntity
* @param {Uuid} entityID - The ID of the entity that was being hovered.
* @param {PointerEvent} event - Details of the event.
@@ -2008,42 +2376,17 @@ signals:
/**jsdoc
- * Triggered when an avatar enters an entity.
- * See also, {@link Script.addEventHandler}.
+ * Triggered when an avatar enters an entity, but only if the entity has an entity method exposed for this event.
+ * See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.
* @function Entities.enterEntity
* @param {Uuid} entityID - The ID of the entity that the avatar entered.
* @returns {Signal}
- * @example Change the color of an entity when an avatar enters or leaves.
- * var entityScript = (function () {
- * this.enterEntity = function (entityID) {
- * print("Enter entity");
- * Entities.editEntity(entityID, {
- * color: { red: 255, green: 64, blue: 64 },
- * });
- * };
- * this.leaveEntity = function (entityID) {
- * print("Leave entity");
- * Entities.editEntity(entityID, {
- * color: { red: 128, green: 128, blue: 128 },
- * });
- * };
- * });
- *
- * var entityID = Entities.addEntity({
- * type: "Sphere",
- * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
- * dimensions: { x: 3, y: 3, z: 3 },
- * color: { red: 128, green: 128, blue: 128 },
- * collisionless: true, // So that avatar can walk through entity.
- * script: "(" + entityScript + ")", // Could host the script on a Web server instead.
- * lifetime: 300 // Delete after 5 minutes.
- * });
- */
+ */
void enterEntity(const EntityItemID& entityItemID);
/**jsdoc
- * Triggered when an avatar leaves an entity.
- * See also, {@link Script.addEventHandler}.
+ * Triggered when an avatar leaves an entity, but only if the entity has an entity method exposed for this event.
+ * See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.
* @function Entities.leaveEntity
* @param {Uuid} entityID - The ID of the entity that the avatar left.
* @returns {Signal}
@@ -2064,9 +2407,9 @@ signals:
void deletingEntity(const EntityItemID& entityID);
/**jsdoc
- * Triggered when an entity is added to Interface's local in-memory tree of entities it knows about. This may occur when
+ * Triggered when an entity is added to Interface's local in-memory tree of entities it knows about. This may occur when
* entities are loaded upon visiting a domain, when the user rotates their view so that more entities become visible, and
- * when any type of entity is added (e.g., by {@Entities.addEntity|addEntity}).
+ * when any type of entity is created (e.g., by {@link Entities.addEntity|addEntity}).
* @function Entities.addingEntity
* @param {Uuid} entityID - The ID of the entity added.
* @returns {Signal}
@@ -2078,33 +2421,33 @@ signals:
void addingEntity(const EntityItemID& entityID);
/**jsdoc
- * Triggered when an 'wearable' entity is deleted.
- * @function Entities.deletingWearable
- * @param {Uuid} entityID - The ID of the 'wearable' entity deleted.
- * @returns {Signal}
- * @example Report when an 'wearable' entity is deleted.
- * Entities.deletingWearable.connect(function (entityID) {
- * print("Deleted wearable: " + entityID);
- * });
- */
+ * Triggered when a "wearable" entity is deleted, for example when removing a "wearable" from your avatar.
+ * @function Entities.deletingWearable
+ * @param {Uuid} entityID - The ID of the "wearable" entity deleted.
+ * @returns {Signal}
+ * @example Report when a "wearable" entity is deleted.
+ * Entities.deletingWearable.connect(function (entityID) {
+ * print("Deleted wearable: " + entityID);
+ * });
+ */
void deletingWearable(const EntityItemID& entityID);
/**jsdoc
- * Triggered when an 'wearable' entity is added to Interface's local in-memory tree of entities it knows about. This may occur when
- * 'wearable' entities are added to avatar
- * @function Entities.addingWearable
- * @param {Uuid} entityID - The ID of the 'wearable' entity added.
- * @returns {Signal}
- * @example Report when an 'wearable' entity is added.
- * Entities.addingWearable.connect(function (entityID) {
- * print("Added wearable: " + entityID);
- * });
- */
+ * Triggered when a "wearable" entity is added to Interface's local in-memory tree of entities it knows about, for example
+ * when adding a "wearable" to your avatar.
+ * @function Entities.addingWearable
+ * @param {Uuid} entityID - The ID of the "wearable" entity added.
+ * @returns {Signal}
+ * @example Report when a "wearable" entity is added.
+ * Entities.addingWearable.connect(function (entityID) {
+ * print("Added wearable: " + entityID);
+ * });
+ */
void addingWearable(const EntityItemID& entityID);
/**jsdoc
- * Triggered when you disconnect from a domain, at which time Interface's local in-memory tree of entities it knows about
- * is cleared.
+ * Triggered when you disconnect from a domain, at which time Interface's local in-memory tree of entities that it knows
+ * about is cleared.
* @function Entities.clearingEntities
* @returns {Signal}
* @example Report when Interfaces's entity tree is cleared.
@@ -2115,10 +2458,14 @@ signals:
void clearingEntities();
/**jsdoc
- * Triggered in when a script in a {@link Entities.EntityType|Web} entity's Web page script sends an event over the
- * script's EventBridge.
+ * Triggered when a script in a {@link Entities.EntityProperties-Web|Web} entity's HTML sends an event over the entity's
+ * HTML event bridge. The HTML web page can send a message by calling:
+ * EventBridge.emitWebEvent(message);
+ * Use {@link Entities.emitScriptEvent} to send messages to the Web entity's HTML page.
+ * Alternatively, you can use {@link Entities.getEntityObject} to exchange messages over a Web entity's HTML event
+ * bridge.
* @function Entities.webEventReceived
- * @param {Uuid} entityID - The ID of the entity that event was received from.
+ * @param {Uuid} entityID - The ID of the Web entity that the message was received from.
* @param {string} message - The message received.
* @returns {Signal}
*/
diff --git a/libraries/entities/src/EntityTypes.h b/libraries/entities/src/EntityTypes.h
index 91b71513dc..8fdc752cac 100644
--- a/libraries/entities/src/EntityTypes.h
+++ b/libraries/entities/src/EntityTypes.h
@@ -42,7 +42,10 @@ public:
* Value Description Properties "Box"A rectangular prism. This is a synonym of "Shape" for the case
+ * "Shape"A basic entity such as a cube.
+ * See also, the "Box" and "Sphere" entity types.
+ * {@link Entities.EntityProperties-Shape|EntityProperties-Shape} "Box"A rectangular prism. This is a synonym of "Shape" for the case
* where the entity's shape property value is "Cube".
* If an entity is created with its type
* set to "Box" it will always be created with a shape property value of
@@ -56,16 +59,13 @@ public:
* "Sphere". If an entity of type Box or Shape has its shape set
* to "Sphere" then its type will be reported as "Sphere".
* {@link Entities.EntityProperties-Sphere|EntityProperties-Sphere} "Shape"A basic entity such as a cube.
- * See also, the "Box" and "Sphere" entity types.
- * {@link Entities.EntityProperties-Shape|EntityProperties-Shape} "Model"A mesh model from an FBX or OBJ file.
+ * "Model"A mesh model from a glTf, FBX, or OBJ file.
* {@link Entities.EntityProperties-Model|EntityProperties-Model} "Text"A pane of text oriented in space.
* {@link Entities.EntityProperties-Text|EntityProperties-Text} "Image"An image oriented in space.
* {@link Entities.EntityProperties-Image|EntityProperties-Image} "Web"A browsable Web page.
+ * "Web"A browsable web page.
* {@link Entities.EntityProperties-Web|EntityProperties-Web} "ParticleEffect"A particle system that can be used to simulate things such as fire,
* smoke, snow, magic spells, etc.
@@ -78,7 +78,7 @@ public:
* {@link Entities.EntityProperties-PolyVox|EntityProperties-PolyVox} "Grid"A grid of lines in a plane.
* {@link Entities.EntityProperties-Grid|EntityProperties-Grid} "Gizmo"An entity with various UI-related properties.
+ * "Gizmo"A gizmo intended for UI.
* {@link Entities.EntityProperties-Gizmo|EntityProperties-Gizmo} "Light"A local lighting effect.
* {@link Entities.EntityProperties-Light|EntityProperties-Light} true the entity can be grabbed.
- * @property {boolean} grabKinematic=true - If true the entity is updated in a kinematic manner.
- * If false it will be grabbed using a tractor action. A kinematic grab will make the item appear more
- * tightly held, but will cause it to behave poorly when interacting with dynamic entities.
- * @property {boolean} grabFollowsController=true - If true the entity will follow the motions of the
- * hand-controller even if the avatar's hand can't get to the implied position. This should be true
- * for tools, pens, etc and false for things meant to decorate the hand.
- *
- * @property {boolean} triggerable=false - If true the entity will receive calls to trigger
+ * @property {boolean} grabbable=true - If true then the entity can be grabbed.
+ * @property {boolean} grabKinematic=true - If true then the entity will be updated in a kinematic manner when
+ * grabbed; if false it will be grabbed using a tractor action. A kinematic grab will make the item appear
+ * more tightly held but will cause it to behave poorly when interacting with dynamic entities.
+ * @property {boolean} grabFollowsController=true - If true then the entity will follow the motions of the hand
+ * controller even if the avatar's hand can't get to the implied position. This should be set true for tools,
+ * pens, etc. and false for things meant to decorate the hand.
+ * @property {boolean} triggerable=false - If true then the entity will receive calls to trigger
* {@link Controller|Controller entity methods}.
- *
- * @property {boolean} equippable=true - If true the entity can be equipped.
+ * @property {boolean} grabDelegateToParent=true - If true and the entity is grabbed, the grab will be transferred
+ * to its parent entity if there is one; if false, a child entity can be grabbed and moved relative to its
+ * parent.
+ * @property {boolean} equippable=true - If true then the entity can be equipped.
* @property {Vec3} equippableLeftPosition=0,0,0 - Positional offset from the left hand, when equipped.
* @property {Quat} equippableLeftRotation=0,0,0,1 - Rotational offset from the left hand, when equipped.
* @property {Vec3} equippableRightPosition=0,0,0 - Positional offset from the right hand, when equipped.
* @property {Quat} equippableRightRotation=0,0,0,1 - Rotational offset from the right hand, when equipped.
- *
* @property {string} equippableIndicatorURL="" - If non-empty, this model will be used to indicate that an
* entity is equippable, rather than the default.
- * @property {Vec3} equippableIndicatorScale=1,1,1 - If equippableIndicatorURL is non-empty, this controls the
+ * @property {Vec3} equippableIndicatorScale=1,1,1 - If equippableIndicatorURL is non-empty, this controls the
scale of the displayed indicator.
- * @property {Vec3} equippableIndicatorOffset=0,0,0 - If equippableIndicatorURL is non-empty, this controls the
+ * @property {Vec3} equippableIndicatorOffset=0,0,0 - If equippableIndicatorURL is non-empty, this controls the
relative offset of the displayed object from the equippable entity.
*/
-
-
class GrabPropertyGroup : public PropertyGroup {
public:
// EntityItemProperty related helpers
diff --git a/libraries/entities/src/HazePropertyGroup.h b/libraries/entities/src/HazePropertyGroup.h
index 595dbeaf51..116bfd9687 100644
--- a/libraries/entities/src/HazePropertyGroup.h
+++ b/libraries/entities/src/HazePropertyGroup.h
@@ -43,7 +43,7 @@ static const float INITIAL_KEY_LIGHT_ALTITUDE{ 200.0f };
// FIXME: Document hazeAttenuationKeyLight, hazeKeyLightRange, and hazeKeyLightAltitude once they're working and are provided
// in the Create app's UI.
/**jsdoc
- * Haze is defined by the following properties.
+ * Haze is defined by the following properties:
* @typedef {object} Entities.Haze
*
* @property {number} hazeRange=1000 - The horizontal distance at which visibility is reduced to 95%; i.e., 95% of each pixel's
@@ -56,7 +56,7 @@ static const float INITIAL_KEY_LIGHT_ALTITUDE{ 200.0f };
* haze color are blended 50/50.
*
* @property {boolean} hazeAltitudeEffect=false - If true then haze decreases with altitude as defined by the
- * entity's local coordinate system; hazeBaseRef and hazeCeiling are used.
+ * entity's local coordinate system; hazeBaseRef and hazeCeiling are used.
* @property {number} hazeBaseRef=0 - The y-axis value in the entity's local coordinate system at which the haze density starts
* reducing with altitude.
* @property {number} hazeCeiling=200 - The y-axis value in the entity's local coordinate system at which the haze density has
@@ -65,9 +65,11 @@ static const float INITIAL_KEY_LIGHT_ALTITUDE{ 200.0f };
* @property {number} hazeBackgroundBlend=0 - The proportion of the skybox image to show through the haze: 0.0
* displays no skybox image; 1.0 displays no haze.
*
- * @property {boolean} hazeAttenuateKeyLight=false - Currently not supported.
- * @property {number} hazeKeyLightRange=1000 - Currently not supported.
- * @property {number} hazeKeyLightAltitude=200 - Currently not supported.
+ * @property {boolean} hazeAttenuateKeyLight=false - If true then the haze attenuates the key light;
+ * hazeKeyLightRange and hazeKeyLightAltitude are used.
+ * @property {number} hazeKeyLightRange=1000 - The distance at which the haze attenuates the key light by 95%.
+ * @property {number} hazeKeyLightAltitude=200 - The altitude at which the haze starts attenuating the key light (i.e., the
+ * altitude at which the distance starts being calculated).
*/
class HazePropertyGroup : public PropertyGroup {
public:
diff --git a/libraries/entities/src/KeyLightPropertyGroup.h b/libraries/entities/src/KeyLightPropertyGroup.h
index d7fa75a32e..31e0cba1c6 100644
--- a/libraries/entities/src/KeyLightPropertyGroup.h
+++ b/libraries/entities/src/KeyLightPropertyGroup.h
@@ -28,13 +28,13 @@ class EntityTreeElementExtraEncodeData;
class ReadBitstreamToTreeParams;
/**jsdoc
- * A key light is defined by the following properties.
+ * A key light is defined by the following properties:
* @typedef {object} Entities.KeyLight
* @property {Color} color=255,255,255 - The color of the light.
* @property {number} intensity=1 - The intensity of the light.
* @property {Vec3} direction=0,-1,0 - The direction the light is shining.
* @property {boolean} castShadows=false - If true then shadows are cast. Shadows are cast by avatars, plus
- * {@link Entities.EntityType|Model} and {@link Entities.EntityType|Shape} entities that have their
+ * {@link Entities.EntityProperties-Model|Model} and {@link Entities.EntityProperties-Shape|Shape} entities that have their
* {@link Entities.EntityProperties|canCastShadow} property set to true.
*/
class KeyLightPropertyGroup : public PropertyGroup {
diff --git a/libraries/entities/src/PolyVoxEntityItem.h b/libraries/entities/src/PolyVoxEntityItem.h
index a6076dfda7..9d02cbcdad 100644
--- a/libraries/entities/src/PolyVoxEntityItem.h
+++ b/libraries/entities/src/PolyVoxEntityItem.h
@@ -63,7 +63,7 @@ class PolyVoxEntityItem : public EntityItem {
virtual int getOnCount() const { return 0; }
/**jsdoc
- * A PolyVoxSurfaceStyle may be one of the following:
+ * The surface of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity may be one of the following styles:
*
*
* Value Type Description min to max, then max to min in one period.
- * @property {PulseMode} colorMode="none" - If "in", the color is pulsed in phase with the pulse period; if "out"
+ * @property {Entities.PulseMode} colorMode="none" - If "in", the color is pulsed in phase with the pulse period; if "out"
* the color is pulsed out of phase with the pulse period.
- * @property {PulseMode} alphaMode="none" - If "in", the alpha is pulsed in phase with the pulse period; if "out"
+ * @property {Entities.PulseMode} alphaMode="none" - If "in", the alpha is pulsed in phase with the pulse period; if "out"
* the alpha is pulsed out of phase with the pulse period.
*/
-
class PulsePropertyGroup : public PropertyGroup {
public:
// EntityItemProperty related helpers
diff --git a/libraries/entities/src/RingGizmoPropertyGroup.h b/libraries/entities/src/RingGizmoPropertyGroup.h
index 42202eb509..1f23152fc7 100644
--- a/libraries/entities/src/RingGizmoPropertyGroup.h
+++ b/libraries/entities/src/RingGizmoPropertyGroup.h
@@ -25,31 +25,32 @@ class ReadBitstreamToTreeParams;
using u8vec3Color = glm::u8vec3;
/**jsdoc
- * A RingGizmo is defined by the following properties.
+ * A {@link Entities.EntityProperties-Gizmo|ring Gizmo} entity is defined by the following properties:
* @typedef {object} Entities.RingGizmo
*
- * @property {number} startAngle=0 - The angle at which the ring will start, in degrees.
- * @property {number} endAngle=360 - The angle at which the ring will end, in degrees.
- * @property {number} innerRadius=0 - The inner radius of the ring as a fraction of the total radius. 0-1.
+ * @property {number} startAngle=0 - The angle at which the ring starts, in degrees.
+ * @property {number} endAngle=360 - The angle at which the ring ends, in degrees.
+ * @property {number} innerRadius=0 - The inner radius of the ring as a fraction of the total radius, range 0.0
+ * — 1.0.
- * @property {Color} innerStartColor - The color at the inner start point of the ring.
- * @property {Color} innerEndColor - The color at the inner end point of the ring.
- * @property {Color} outerStartColor - The color at the outer start point of the ring.
- * @property {Color} outerEndColor - The color at the outer end point of the ring.
- * @property {number} innerStartAlpha=1 - The alpha at the inner start point of the ring.
- * @property {number} innerEndAlpha=1 - The alpha at the inner end point of the ring.
- * @property {number} outerStartAlpha=1 - The alpha at the outer start point of the ring.
- * @property {number} outerEndAlpha=1 - The alpha at the outer end point of the ring.
+ * @property {Color} innerStartColor=255,255,255 - The color at the inner start point of the ring.
+ * @property {Color} innerEndColor=255,255,255 - The color at the inner end point of the ring.
+ * @property {Color} outerStartColor=255,255,255 - The color at the outer start point of the ring.
+ * @property {Color} outerEndColor=255,255,255 - The color at the outer end point of the ring.
+ * @property {number} innerStartAlpha=1 - The opacity at the inner start point of the ring.
+ * @property {number} innerEndAlpha=1 - The opacity at the inner end point of the ring.
+ * @property {number} outerStartAlpha=1 - The opacity at the outer start point of the ring.
+ * @property {number} outerEndAlpha=1 - The opacity at the outer end point of the ring.
- * @property {boolean} hasTickMarks=false - Whether or not to render tick marks.
- * @property {number} majorTickMarksAngle - The angle between major tick marks, in degrees.
- * @property {number} minorTickMarksAngle - The angle between minor tick marks, in degrees.
- * @property {number} majorTickMarksLength - The length of the major tick marks, as a fraction of the radius. A positive value draws tick marks
- * outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.
- * @property {number} minorTickMarksLength - The length of the minor tick marks, as a fraction of the radius. A positive value draws tick marks
- * outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.
- * @property {Color} majorTickMarksColor - The color of the major tick marks.
- * @property {Color} minorTickMarksColor - The color of the minor tick marks.
+ * @property {boolean} hasTickMarks=false - true to render tick marks, otherwise false.
+ * @property {number} majorTickMarksAngle=0 - The angle between major tick marks, in degrees.
+ * @property {number} minorTickMarksAngle=0 - The angle between minor tick marks, in degrees.
+ * @property {number} majorTickMarksLength=0 - The length of the major tick marks as a fraction of the radius. A positive value
+ * draws tick marks outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.
+ * @property {number} minorTickMarksLength=0 - The length of the minor tick marks, as a fraction of the radius. A positive
+ * value draws tick marks outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.
+ * @property {Color} majorTickMarksColor=255,255,255 - The color of the major tick marks.
+ * @property {Color} minorTickMarksColor=255,255,255 - The color of the minor tick marks.
*/
class RingGizmoPropertyGroup : public PropertyGroup {
diff --git a/libraries/entities/src/ShapeEntityItem.cpp b/libraries/entities/src/ShapeEntityItem.cpp
index 869ae2985f..513daa0b09 100644
--- a/libraries/entities/src/ShapeEntityItem.cpp
+++ b/libraries/entities/src/ShapeEntityItem.cpp
@@ -22,8 +22,8 @@
namespace entity {
/**jsdoc
- * A Shape, Box, or Sphere {@link Entities.EntityType|EntityType} may display as
- * one of the following geometrical shapes:
+ * A "Shape", "Box", or "Sphere" {@link Entities.EntityType|EntityType} may
+ * display as one of the following geometrical shapes:
*
*
* Value Dimensions Notes url is "", otherwise modifies the
* color of the cube map image.
diff --git a/libraries/material-networking/src/material-networking/MaterialCache.cpp b/libraries/material-networking/src/material-networking/MaterialCache.cpp
index 5e86ea506a..4f6d149fbe 100644
--- a/libraries/material-networking/src/material-networking/MaterialCache.cpp
+++ b/libraries/material-networking/src/material-networking/MaterialCache.cpp
@@ -70,10 +70,10 @@ bool NetworkMaterialResource::parseJSONColor(const QJsonValue& array, glm::vec3&
}
/**jsdoc
- * A material or set of materials such as may be used by a {@link Entities.EntityType|Material} entity.
- * @typedef {object} MaterialResource
+ * A material or set of materials used by a {@link Entities.EntityType|Material entity}.
+ * @typedef {object} Entities.MaterialResource
* @property {number} materialVersion=1 - The version of the material. Currently not used.
- * @property {Material|Material[]} materials - The details of the material or materials.
+ * @property {Entities.Material|Entities.Material[]} materials - The details of the material or materials.
*/
NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMaterials(const QJsonDocument& materialJSON, const QUrl& baseUrl) {
ParsedMaterials toReturn;
@@ -109,60 +109,72 @@ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMater
}
/**jsdoc
- * A material such as may be used by a {@link Entities.EntityType|Material} entity.
- * @typedef {object} Material
+ * A material used in a {@link Entities.MaterialResource|MaterialResource}.
+ * @typedef {object} Entities.Material
* @property {string} model="hifi_pbr" - Different material models support different properties and rendering modes.
- * Supported models are: "hifi_pbr"
+ * Supported models are: "hifi_pbr".
* @property {string} name="" - A name for the material. Supported by all material models.
- * @property {Color|RGBS|string} emissive - The emissive color, i.e., the color that the material emits. A {@link Color} value
- * is treated as sRGB. A {@link RGBS} value can be either RGB or sRGB. Set to "fallthrough" to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {number|string} opacity=1.0 - The opacity, 0.0 – 1.0. Set to "fallthrough" to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {boolean|string} unlit=false - If true, the material is not lit. Set to "fallthrough" to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {Color|RGBS|string} albedo - The albedo color. A {@link Color} value is treated as sRGB. A {@link RGBS} value can
- * be either RGB or sRGB. Set to "fallthrough" to fallthrough to the material below. Set to "fallthrough" to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {number|string} roughness - The roughness, 0.0 – 1.0. Set to "fallthrough" to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {number|string} metallic - The metallicness, 0.0 – 1.0. Set to "fallthrough" to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {number|string} scattering - The scattering, 0.0 – 1.0. Set to "fallthrough" to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {string} emissiveMap - URL of emissive texture image. Set to "fallthrough" to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {string} albedoMap - URL of albedo texture image. Set to "fallthrough" to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {string} opacityMap - URL of opacity texture image. Set value the same as the albedoMap value for
- * transparency. "hifi_pbr" model only.
- * @property {string} roughnessMap - URL of roughness texture image. Can use this or glossMap, but not both. Set to "fallthrough"
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} glossMap - URL of gloss texture image. Can use this or roughnessMap, but not both. Set to "fallthrough"
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} metallicMap - URL of metallic texture image. Can use this or specularMap, but not both. Set to "fallthrough"
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} specularMap - URL of specular texture image. Can use this or metallicMap, but not both. Set to "fallthrough"
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} normalMap - URL of normal texture image. Can use this or bumpMap, but not both. Set to "fallthrough"
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} bumpMap - URL of bump texture image. Can use this or normalMap, but not both. Set to "fallthrough"
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} occlusionMap - URL of occlusion texture image. Set to "fallthrough" to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} scatteringMap - URL of scattering texture image. Only used if normalMap or
- * bumpMap is specified. Set to "fallthrough" to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} lightMap - URL of light map texture image. Currently not used.. Set to "fallthrough"
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} texCoordTransform0 - The transform to use for all of the maps besides occlusionMap and lightMap. Currently unused. Set to
- * "fallthrough" to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} texCoordTransform1 - The transform to use for occlusionMap and lightMap. Currently unused. Set to "fallthrough"
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} lightmapParams - Parameters for controlling how lightMap is used. Currently unused. Set to "fallthrough"
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} materialParams - Parameters for controlling the material projection and repition. Currently unused. Set to "fallthrough"
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {bool} defaultFallthrough=false - If true, all properties will fallthrough to the material below unless they are set. If
- * false, they will respect the individual properties' fallthrough state. "hifi_pbr" model only.
+ * @property {ColorFloat|RGBS|string} emissive - The emissive color, i.e., the color that the material emits. A
+ * {@link ColorFloat} value is treated as sRGB and must have component values in the range 0.0 —
+ * 1.0. A {@link RGBS} value can be either RGB or sRGB.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {number|string} opacity=1.0 - The opacity, range 0.0 – 1.0.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {boolean|string} unlit=false - If true, the material is not lit, otherwise it is.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {ColorFloat|RGBS|string} albedo - The albedo color. A {@link ColorFloat} value is treated as sRGB and must have
+ * component values in the range 0.0 — 1.0. A {@link RGBS} value can be either RGB or sRGB.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {number|string} roughness - The roughness, range 0.0 – 1.0.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {number|string} metallic - The metallicness, range 0.0 – 1.0.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {number|string} scattering - The scattering, range 0.0 – 1.0.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {string} emissiveMap - The URL of the emissive texture image.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {string} albedoMap - The URL of the albedo texture image.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {string} opacityMap - The URL of the opacity texture image. Set the value the same as the albedoMap
+ * value for transparency.
+ * "hifi_pbr" model only.
+ * @property {string} roughnessMap - The URL of the roughness texture image. You can use this or glossMap, but not
+ * both.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {string} glossMap - The URL of the gloss texture image. You can use this or roughnessMap, but not
+ * both.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {string} metallicMap - The URL of the metallic texture image. You can use this or specularMap, but
+ * not both.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {string} specularMap - The URL of the specular texture image. You can use this or metallicMap, but
+ * not both.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {string} normalMap - The URL of the normal texture image. You can use this or bumpMap, but not both.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {string} bumpMap - The URL of the bump texture image. You can use this or normalMap, but not both.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {string} occlusionMap - The URL of the occlusion texture image.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {string} scatteringMap - The URL of the scattering texture image. Only used if normalMap or
+ * bumpMap is specified.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {string} lightMap - The URL of the light map texture image.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {Mat4|string} texCoordTransform0 - The transform to use for all of the maps apart from occlusionMap
+ * and lightMap.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {Mat4|string} texCoordTransform1 - The transform to use for occlusionMap and lightMap.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * @property {string} lightmapParams - Parameters for controlling how lightMap is used.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * Currently not used.
+ * @property {string} materialParams - Parameters for controlling the material projection and repetition.
+ * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
+ * Currently not used.
+ * @property {boolean} defaultFallthrough=false - If true, all properties fall through to the material below
+ * unless they are set. If false, they respect their individual fall-through setting. "hifi_pbr"
+ * model only.
*/
// Note: See MaterialEntityItem.h for default values used in practice.
std::pair> NetworkMaterialResource::parseJSONMaterial(const QJsonObject& materialJSON, const QUrl& baseUrl) {
@@ -399,7 +411,7 @@ std::pair> NetworkMaterialResource
material->setPropertyDoesFallthrough(graphics::Material::ExtraFlagBit::LIGHTMAP_PARAMS);
}
}
- // TODO: implement lightmapParams
+ // TODO: implement lightmapParams and update JSDoc
} else if (key == "materialParams") {
auto value = materialJSON.value(key);
if (value.isString()) {
@@ -408,7 +420,7 @@ std::pair> NetworkMaterialResource
material->setPropertyDoesFallthrough(graphics::Material::ExtraFlagBit::MATERIAL_PARAMS);
}
}
- // TODO: implement materialParams
+ // TODO: implement materialParams and update JSDoc
} else if (key == "defaultFallthrough") {
auto value = materialJSON.value(key);
if (value.isBool()) {
diff --git a/libraries/octree/src/OctreeScriptingInterface.h b/libraries/octree/src/OctreeScriptingInterface.h
index e501dd166a..c7b0552511 100644
--- a/libraries/octree/src/OctreeScriptingInterface.h
+++ b/libraries/octree/src/OctreeScriptingInterface.h
@@ -37,7 +37,7 @@ private slots:
public slots:
/**jsdoc
- * Set the maximum number of entity packets that the client can send per second.
+ * Sets the maximum number of entity packets that the client can send per second.
* @function Entities.setPacketsPerSecond
* @param {number} packetsPerSecond - Integer maximum number of entity packets that the client can send per second.
*/
@@ -45,7 +45,7 @@ public slots:
void setPacketsPerSecond(int packetsPerSecond) { return _packetSender->setPacketsPerSecond(packetsPerSecond); }
/**jsdoc
- * Get the maximum number of entity packets that the client can send per second.
+ * Gets the maximum number of entity packets that the client can send per second.
* @function Entities.getPacketsPerSecond
* @returns {number} Integer maximum number of entity packets that the client can send per second.
*/
@@ -53,7 +53,7 @@ public slots:
int getPacketsPerSecond() const { return _packetSender->getPacketsPerSecond(); }
/**jsdoc
- * Check whether servers exist for the client to send entity packets to, i.e., whether you are connected to a domain and
+ * Checks whether servers exist for the client to send entity packets to, i.e., whether you are connected to a domain and
* its entity server is working.
* @function Entities.serversExist
* @returns {boolean} true if servers exist for the client to send entity packets to, otherwise
@@ -63,7 +63,7 @@ public slots:
bool serversExist() const { return _packetSender->serversExist(); }
/**jsdoc
- * Check whether the client has entity packets waiting to be sent.
+ * Checks whether the client has entity packets waiting to be sent.
* @function Entities.hasPacketsToSend
* @returns {boolean} true if the client has entity packets waiting to be sent, otherwise false.
*/
@@ -71,7 +71,7 @@ public slots:
bool hasPacketsToSend() const { return _packetSender->hasPacketsToSend(); }
/**jsdoc
- * Get the number of entity packets the client has waiting to be sent.
+ * Gets the number of entity packets the client has waiting to be sent.
* @function Entities.packetsToSendCount
* @returns {number} Integer number of entity packets the client has waiting to be sent.
*/
@@ -79,7 +79,7 @@ public slots:
int packetsToSendCount() const { return (int)_packetSender->packetsToSendCount(); }
/**jsdoc
- * Get the entity packets per second send rate of the client over its lifetime.
+ * Gets the entity packets per second send rate of the client over its lifetime.
* @function Entities.getLifetimePPS
* @returns {number} Entity packets per second send rate of the client over its lifetime.
*/
@@ -87,7 +87,7 @@ public slots:
float getLifetimePPS() const { return _packetSender->getLifetimePPS(); }
/**jsdoc
- * Get the entity bytes per second send rate of the client over its lifetime.
+ * Gets the entity bytes per second send rate of the client over its lifetime.
* @function Entities.getLifetimeBPS
* @returns {number} Entity bytes per second send rate of the client over its lifetime.
*/
@@ -95,7 +95,7 @@ public slots:
float getLifetimeBPS() const { return _packetSender->getLifetimeBPS(); }
/**jsdoc
- * Get the entity packets per second queued rate of the client over its lifetime.
+ * Gets the entity packets per second queued rate of the client over its lifetime.
* @function Entities.getLifetimePPSQueued
* @returns {number} Entity packets per second queued rate of the client over its lifetime.
*/
@@ -103,7 +103,7 @@ public slots:
float getLifetimePPSQueued() const { return _packetSender->getLifetimePPSQueued(); }
/**jsdoc
- * Get the entity bytes per second queued rate of the client over its lifetime.
+ * Gets the entity bytes per second queued rate of the client over its lifetime.
* @function Entities.getLifetimeBPSQueued
* @returns {number} Entity bytes per second queued rate of the client over its lifetime.
*/
@@ -111,7 +111,7 @@ public slots:
float getLifetimeBPSQueued() const { return _packetSender->getLifetimeBPSQueued(); }
/**jsdoc
- * Get the lifetime of the client from the first entity packet sent until now, in microseconds.
+ * Gets the lifetime of the client from the first entity packet sent until now, in microseconds.
* @function Entities.getLifetimeInUsecs
* @returns {number} Lifetime of the client from the first entity packet sent until now, in microseconds.
*/
@@ -119,7 +119,7 @@ public slots:
long long unsigned int getLifetimeInUsecs() const { return _packetSender->getLifetimeInUsecs(); }
/**jsdoc
- * Get the lifetime of the client from the first entity packet sent until now, in seconds.
+ * Gets the lifetime of the client from the first entity packet sent until now, in seconds.
* @function Entities.getLifetimeInSeconds
* @returns {number} Lifetime of the client from the first entity packet sent until now, in seconds.
*/
@@ -127,7 +127,7 @@ public slots:
float getLifetimeInSeconds() const { return _packetSender->getLifetimeInSeconds(); }
/**jsdoc
- * Get the total number of entity packets sent by the client over its lifetime.
+ * Gets the total number of entity packets sent by the client over its lifetime.
* @function Entities.getLifetimePacketsSent
* @returns {number} The total number of entity packets sent by the client over its lifetime.
*/
@@ -135,7 +135,7 @@ public slots:
long long unsigned int getLifetimePacketsSent() const { return _packetSender->getLifetimePacketsSent(); }
/**jsdoc
- * Get the total bytes of entity packets sent by the client over its lifetime.
+ * Gets the total bytes of entity packets sent by the client over its lifetime.
* @function Entities.getLifetimeBytesSent
* @returns {number} The total bytes of entity packets sent by the client over its lifetime.
*/
@@ -143,7 +143,7 @@ public slots:
long long unsigned int getLifetimeBytesSent() const { return _packetSender->getLifetimeBytesSent(); }
/**jsdoc
- * Get the total number of entity packets queued by the client over its lifetime.
+ * Gets the total number of entity packets queued by the client over its lifetime.
* @function Entities.getLifetimePacketsQueued
* @returns {number} The total number of entity packets queued by the client over its lifetime.
*/
@@ -151,7 +151,7 @@ public slots:
long long unsigned int getLifetimePacketsQueued() const { return _packetSender->getLifetimePacketsQueued(); }
/**jsdoc
- * Get the total bytes of entity packets queued by the client over its lifetime.
+ * Gets the total bytes of entity packets queued by the client over its lifetime.
* @function Entities.getLifetimeBytesQueued
* @returns {number} The total bytes of entity packets queued by the client over its lifetime.
*/
diff --git a/libraries/physics/src/ObjectActionOffset.cpp b/libraries/physics/src/ObjectActionOffset.cpp
index 24f8a1ba8f..a99c875106 100644
--- a/libraries/physics/src/ObjectActionOffset.cpp
+++ b/libraries/physics/src/ObjectActionOffset.cpp
@@ -145,7 +145,7 @@ bool ObjectActionOffset::updateArguments(QVariantMap arguments) {
/**jsdoc
* The "offset" {@link Entities.ActionType|ActionType} moves an entity so that it is a set distance away from a
* target point.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-Offset
* @property {Vec3} pointToOffsetFrom=0,0,0 - The target point to offset the entity from.
diff --git a/libraries/physics/src/ObjectActionTractor.cpp b/libraries/physics/src/ObjectActionTractor.cpp
index b53c2e137a..4925faaf2a 100644
--- a/libraries/physics/src/ObjectActionTractor.cpp
+++ b/libraries/physics/src/ObjectActionTractor.cpp
@@ -341,15 +341,15 @@ bool ObjectActionTractor::updateArguments(QVariantMap arguments) {
/**jsdoc
* The "tractor" {@link Entities.ActionType|ActionType} moves and rotates an entity to a target position and
* orientation, optionally relative to another entity.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-Tractor
+ * @property {Uuid} otherID=null - If an entity ID, the targetPosition and targetRotation are
+ * relative to the entity's position and rotation.
+ * @property {Uuid} otherJointIndex=null - If a joint index in the otherID entity, the targetPosition
+ * and targetRotation are relative to the entity joint's position and rotation.
* @property {Vec3} targetPosition=0,0,0 - The target position.
* @property {Quat} targetRotation=0,0,0,1 - The target rotation.
- * @property {Uuid} otherID=null - If an entity ID, the targetPosition and targetRotation are
- * relative to this entity's position and rotation.
- * @property {Uuid} otherJointIndex=null - If an entity JointIndex, the targetPosition and
- * targetRotation are relative to this entity's joint's position and rotation.
* @property {number} linearTimeScale=3.4e+38 - Controls how long it takes for the entity's position to catch up with the
* target position. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the action
* is applied using an exponential decay.
diff --git a/libraries/physics/src/ObjectActionTravelOriented.cpp b/libraries/physics/src/ObjectActionTravelOriented.cpp
index b27ec40ae4..025c74b96a 100644
--- a/libraries/physics/src/ObjectActionTravelOriented.cpp
+++ b/libraries/physics/src/ObjectActionTravelOriented.cpp
@@ -152,7 +152,7 @@ bool ObjectActionTravelOriented::updateArguments(QVariantMap arguments) {
/**jsdoc
* The "travel-oriented" {@link Entities.ActionType|ActionType} orients an entity to align with its direction of
* travel.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-TravelOriented
* @property {Vec3} forward=0,0,0 - The axis of the entity to align with the entity's direction of travel.
diff --git a/libraries/physics/src/ObjectConstraintBallSocket.cpp b/libraries/physics/src/ObjectConstraintBallSocket.cpp
index ddb0c75ac9..5b925c9e88 100644
--- a/libraries/physics/src/ObjectConstraintBallSocket.cpp
+++ b/libraries/physics/src/ObjectConstraintBallSocket.cpp
@@ -183,11 +183,11 @@ bool ObjectConstraintBallSocket::updateArguments(QVariantMap arguments) {
/**jsdoc
* The "ball-socket" {@link Entities.ActionType|ActionType} connects two entities with a ball and socket joint.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-BallSocket
- * @property {Vec3} pivot=0,0,0 - The local offset of the joint relative to the entity's position.
* @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint.
+ * @property {Vec3} pivot=0,0,0 - The local offset of the joint relative to the entity's position.
* @property {Vec3} otherPivot=0,0,0 - The local offset of the joint relative to the other entity's position.
*/
QVariantMap ObjectConstraintBallSocket::getArguments() {
diff --git a/libraries/physics/src/ObjectConstraintConeTwist.cpp b/libraries/physics/src/ObjectConstraintConeTwist.cpp
index 9551532182..6763f82773 100644
--- a/libraries/physics/src/ObjectConstraintConeTwist.cpp
+++ b/libraries/physics/src/ObjectConstraintConeTwist.cpp
@@ -264,17 +264,18 @@ bool ObjectConstraintConeTwist::updateArguments(QVariantMap arguments) {
/**jsdoc
* The "cone-twist" {@link Entities.ActionType|ActionType} connects two entities with a joint that can move
* through a cone and can twist.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-ConeTwist
+ * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint.
* @property {Vec3} pivot=0,0,0 - The local offset of the joint relative to the entity's position.
* @property {Vec3} axis=1,0,0 - The axis of the entity that moves through the cone. Must be a non-zero vector.
- * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint.
* @property {Vec3} otherPivot=0,0,0 - The local offset of the joint relative to the other entity's position.
* @property {Vec3} otherAxis=1,0,0 - The axis of the other entity that moves through the cone. Must be a non-zero vector.
- * @property {number} swingSpan1=6.238 - The angle through which the joint can move in one axis of the cone, in radians.
- * @property {number} swingSpan2=6.238 - The angle through which the joint can move in the other axis of the cone, in radians.
- * @property {number} twistSpan=6.238 - The angle through with the joint can twist, in radians.
+ * @property {number} swingSpan1=2*Math.PI - The angle through which the joint can move in one axis of the cone, in radians.
+ * @property {number} swingSpan2=2*Math.PI - The angle through which the joint can move in the other axis of the cone, in
+ * radians.
+ * @property {number} twistSpan=2*Math.PI - The angle through with the joint can twist, in radians.
*/
QVariantMap ObjectConstraintConeTwist::getArguments() {
QVariantMap arguments = ObjectDynamic::getArguments();
diff --git a/libraries/physics/src/ObjectConstraintHinge.cpp b/libraries/physics/src/ObjectConstraintHinge.cpp
index 67573918cb..3059d82bf3 100644
--- a/libraries/physics/src/ObjectConstraintHinge.cpp
+++ b/libraries/physics/src/ObjectConstraintHinge.cpp
@@ -248,18 +248,19 @@ bool ObjectConstraintHinge::updateArguments(QVariantMap arguments) {
/**jsdoc
* The "hinge" {@link Entities.ActionType|ActionType} lets an entity pivot about an axis or connects two entities
* with a hinge joint.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-Hinge
+ * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint, if any. If none is
+ * specified then the first entity simply pivots about its specified axis.
* @property {Vec3} pivot=0,0,0 - The local offset of the joint relative to the entity's position.
* @property {Vec3} axis=1,0,0 - The axis of the entity that it pivots about. Must be a non-zero vector.
- * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint, if any. If none is
- * specified then the first entity simply pivots about its specified axis.
* @property {Vec3} otherPivot=0,0,0 - The local offset of the joint relative to the other entity's position.
* @property {Vec3} otherAxis=1,0,0 - The axis of the other entity that it pivots about. Must be a non-zero vector.
- * @property {number} low=-6.283 - The most negative angle that the hinge can take, in radians.
- * @property {number} high=6.283 - The most positive angle that the hinge can take, in radians.
- * @property {number} angle=0 - The current angle of the hinge. Read-only.
+ * @property {number} low=-2*Math.PI - The most negative angle that the hinge can take, in radians.
+ * @property {number} high=2*Math.PI - The most positive angle that the hinge can take, in radians.
+ * @property {number} angle=0 - The current angle of the hinge, in radians, range -Math.PI –
+ * Math.PI. Read-only.
*/
QVariantMap ObjectConstraintHinge::getArguments() {
QVariantMap arguments = ObjectDynamic::getArguments();
diff --git a/libraries/physics/src/ObjectConstraintSlider.cpp b/libraries/physics/src/ObjectConstraintSlider.cpp
index 7865e871de..11374298cf 100644
--- a/libraries/physics/src/ObjectConstraintSlider.cpp
+++ b/libraries/physics/src/ObjectConstraintSlider.cpp
@@ -264,27 +264,27 @@ bool ObjectConstraintSlider::updateArguments(QVariantMap arguments) {
/**jsdoc
* The "slider" {@link Entities.ActionType|ActionType} lets an entity slide and rotate along an axis, or connects
* two entities that slide and rotate along a shared axis.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-Slider
+ * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint, if any. If none is
+ * specified then the first entity simply slides and rotates about its specified axis.
* @property {Vec3} point=0,0,0 - The local position of a point in the entity that slides along the axis.
* @property {Vec3} axis=1,0,0 - The axis of the entity that slides along the joint. Must be a non-zero vector.
- * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint, if any. If non is
- * specified then the first entity simply slides and rotates about its specified axis.
* @property {Vec3} otherPoint=0,0,0 - The local position of a point in the other entity that slides along the axis.
- * @property {Vec3} axis=1,0,0 - The axis of the other entity that slides along the joint. Must be a non-zero vector.
+ * @property {Vec3} otherAxis=1,0,0 - The axis of the other entity that slides along the joint. Must be a non-zero vector.
* @property {number} linearLow=1.17e-38 - The most negative linear offset from the entity's initial point that the entity can
* have along the slider.
* @property {number} linearHigh=3.40e+38 - The most positive linear offset from the entity's initial point that the entity can
* have along the slider.
- * @property {number} angularLow=-6.283 - The most negative angle that the entity can rotate about the axis if the action
+ * @property {number} angularLow=-2*Math.PI - The most negative angle that the entity can rotate about the axis if the action
* involves only one entity, otherwise the most negative angle the rotation can be between the two entities. In radians.
- * @property {number} angularHigh=6.283 - The most positive angle that the entity can rotate about the axis if the action
+ * @property {number} angularHigh=Math.PI - The most positive angle that the entity can rotate about the axis if the action
* involves only one entity, otherwise the most positive angle the rotation can be between the two entities. In radians.
* @property {number} linearPosition=0 - The current linear offset the entity is from its initial point if the action involves
* only one entity, otherwise the linear offset between the two entities' action points. Read-only.
* @property {number} angularPosition=0 - The current angular offset of the entity from its initial rotation if the action
- * involves only one entity, otherwise the angular offset between the two entities. Read-only.
+ * involves only one entity, otherwise the angular offset between the two entities. In radians. Read-only.
*/
QVariantMap ObjectConstraintSlider::getArguments() {
QVariantMap arguments = ObjectDynamic::getArguments();
diff --git a/libraries/physics/src/ObjectDynamic.cpp b/libraries/physics/src/ObjectDynamic.cpp
index 28323a8b92..f02b7b1c4c 100644
--- a/libraries/physics/src/ObjectDynamic.cpp
+++ b/libraries/physics/src/ObjectDynamic.cpp
@@ -94,36 +94,36 @@ bool ObjectDynamic::updateArguments(QVariantMap arguments) {
}
/**jsdoc
-* Different entity action types have different arguments: some common to all actions (listed below) and some specific to each
-* {@link Entities.ActionType|ActionType} (linked to below). The arguments are accessed as an object of property names and
-* values.
-*
-* @typedef {object} Entities.ActionArguments
-* @property {Entities.ActionType} type - The type of action.
-* @property {string} tag="" - A string that a script can use for its own purposes.
-* @property {number} ttl=0 - How long the action should exist, in seconds, before it is automatically deleted. A value of
-* 0 means that the action should not be deleted.
-* @property {boolean} isMine=true - Is true if you created the action during your current Interface session,
-* false otherwise. Read-only.
-* @property {boolean} ::no-motion-state - Is present when the entity hasn't been registered with the physics engine yet (e.g.,
-* if the action hasn't been properly configured), otherwise undefined. Read-only.
-* @property {boolean} ::active - Is true when the action is modifying the entity's motion, false
-* otherwise. Is present once the entity has been registered with the physics engine, otherwise undefined.
-* Read-only.
-* @property {Entities.PhysicsMotionType} ::motion-type - How the entity moves with the action. Is present once the entity has
-* been registered with the physics engine, otherwise undefined. Read-only.
-*
-* @see The different action types have additional arguments as follows:
-* @see {@link Entities.ActionArguments-FarGrab|ActionArguments-FarGrab}
-* @see {@link Entities.ActionArguments-Hold|ActionArguments-Hold}
-* @see {@link Entities.ActionArguments-Offset|ActionArguments-Offset}
-* @see {@link Entities.ActionArguments-Tractor|ActionArguments-Tractor}
-* @see {@link Entities.ActionArguments-TravelOriented|ActionArguments-TravelOriented}
-* @see {@link Entities.ActionArguments-Hinge|ActionArguments-Hinge}
-* @see {@link Entities.ActionArguments-Slider|ActionArguments-Slider}
-* @see {@link Entities.ActionArguments-ConeTwist|ActionArguments-ConeTwist}
-* @see {@link Entities.ActionArguments-BallSocket|ActionArguments-BallSocket}
-*/
+ * Different entity action types have different arguments: some common to all actions (listed in the table) and some specific
+ * to each {@link Entities.ActionType|ActionType} (linked to below). The arguments are accessed as an object of property names
+ * and values.
+ *
+ * @typedef {object} Entities.ActionArguments
+ * @property {Entities.ActionType} type - The type of action.
+ * @property {string} tag="" - A string that a script can use for its own purposes.
+ * @property {number} ttl=0 - How long the action should exist, in seconds, before it is automatically deleted. A value of
+ * 0 means that the action should not be deleted.
+ * @property {boolean} isMine=true - Is true if the action was created during the current client session,
+ * false otherwise. Read-only.
+ * @property {boolean} ::no-motion-state - Is present when the entity hasn't been registered with the physics engine yet (e.g.,
+ * if the action hasn't been properly configured), otherwise undefined. Read-only.
+ * @property {boolean} ::active - Is true when the action is modifying the entity's motion, false
+ * otherwise. Is present once the entity has been registered with the physics engine, otherwise undefined.
+ * Read-only.
+ * @property {Entities.PhysicsMotionType} ::motion-type - How the entity moves with the action. Is present once the entity has
+ * been registered with the physics engine, otherwise undefined. Read-only.
+ *
+ * @comment The different action types have additional arguments as follows:
+ * @see {@link Entities.ActionArguments-FarGrab|ActionArguments-FarGrab}
+ * @see {@link Entities.ActionArguments-Hold|ActionArguments-Hold}
+ * @see {@link Entities.ActionArguments-Offset|ActionArguments-Offset}
+ * @see {@link Entities.ActionArguments-Tractor|ActionArguments-Tractor}
+ * @see {@link Entities.ActionArguments-TravelOriented|ActionArguments-TravelOriented}
+ * @see {@link Entities.ActionArguments-Hinge|ActionArguments-Hinge}
+ * @see {@link Entities.ActionArguments-Slider|ActionArguments-Slider}
+ * @see {@link Entities.ActionArguments-ConeTwist|ActionArguments-ConeTwist}
+ * @see {@link Entities.ActionArguments-BallSocket|ActionArguments-BallSocket}
+ */
// Note: The "type" property is set in EntityItem::getActionArguments().
QVariantMap ObjectDynamic::getArguments() {
QVariantMap arguments;
diff --git a/libraries/script-engine/src/ScriptEngine.cpp b/libraries/script-engine/src/ScriptEngine.cpp
index 9ba8289b0c..02dcde3695 100644
--- a/libraries/script-engine/src/ScriptEngine.cpp
+++ b/libraries/script-engine/src/ScriptEngine.cpp
@@ -2205,6 +2205,7 @@ void ScriptEngine::loadEntityScript(const EntityItemID& entityID, const QString&
* lifetime: 300 // Delete after 5 minutes.
* });
*/
+// The JSDoc is for the callEntityScriptMethod() call in this method.
// since all of these operations can be asynch we will always do the actual work in the response handler
// for the download
void ScriptEngine::entityScriptContentAvailable(const EntityItemID& entityID, const QString& scriptOrURL, const QString& contents, bool isURL, bool success , const QString& status) {
@@ -2389,8 +2390,10 @@ void ScriptEngine::entityScriptContentAvailable(const EntityItemID& entityID, co
* Note: Can only be connected to via this.unoad = function () { ... } in the entity script.
* Available in: Client Entity Scripts Server Entity Scripts
* @function Entities.unload
+ * @param {Uuid} entityID - The ID of the entity that the script is running in.
* @returns {Signal}
*/
+// The JSDoc is for the callEntityScriptMethod() call in this method.
void ScriptEngine::unloadEntityScript(const EntityItemID& entityID, bool shouldRemoveFromMap) {
if (QThread::currentThread() != thread()) {
#ifdef THREAD_DEBUGGING
diff --git a/libraries/script-engine/src/ScriptEngine.h b/libraries/script-engine/src/ScriptEngine.h
index a2b16ed178..52ece63dc2 100644
--- a/libraries/script-engine/src/ScriptEngine.h
+++ b/libraries/script-engine/src/ScriptEngine.h
@@ -318,6 +318,7 @@ public:
/**jsdoc
* Adds a function to the list of functions called when an entity event occurs on a particular entity.
+ * See also, the {@link Entities} API.
* @function Script.addEventHandler
* @param {Uuid} entityID - The ID of the entity.
* @param {Script.EntityEvent} eventName - The name of the entity event.
@@ -341,6 +342,7 @@ public:
/**jsdoc
* Removes a function from the list of functions called when an entity event occurs on a particular entity.
+ * See also, the {@link Entities} API.
* @function Script.removeEventHandler
* @param {Uuid} entityID - The ID of the entity.
* @param {Script.EntityEvent} eventName - The name of the entity event.
diff --git a/libraries/shared/src/BillboardMode.h b/libraries/shared/src/BillboardMode.h
index 700127aff1..aa00ce34aa 100644
--- a/libraries/shared/src/BillboardMode.h
+++ b/libraries/shared/src/BillboardMode.h
@@ -21,7 +21,7 @@
* "none"The entity will not be billboarded. "yaw"The entity will yaw, but not pitch, to face the camera. Its actual rotation will be
* ignored. "full"The entity will be billboarded to face the camera. Its actual rotation will be
+ * "full"The entity will yaw and pitch to face the camera. Its actual rotation will be
* ignored.
diff --git a/libraries/shared/src/ComponentMode.cpp b/libraries/shared/src/ComponentMode.cpp
index 5b3a42e9ae..42ef820e2a 100644
--- a/libraries/shared/src/ComponentMode.cpp
+++ b/libraries/shared/src/ComponentMode.cpp
@@ -8,6 +8,22 @@
#include "ComponentMode.h"
+/**jsdoc
+ * How an effect is applied in a {@link Entities.EntityProperties-Zone|Zone} entity.
+ *
+ *
+ * Value Description "inherit"The effect from any enclosing zone continues into this zone. "disabled"The effect — from any enclosing zone and this zone — is disabled in
+ * this zone. "enabled"The effect from this zone is enabled, overriding the effect from any enclosing
+ * zone.
+ * @typedef {string} Entities.ComponentMode
+ */
const char* componentModeNames[] = {
"inherit",
"disabled",
@@ -22,6 +38,20 @@ QString ComponentModeHelpers::getNameForComponentMode(ComponentMode mode) {
return componentModeNames[(int)mode];
}
+/**jsdoc
+ * The priority of updates from avatars in a zone to other clients.
+ *
+ *
+ * Value Description "inherit"The update priority from any enclosing zone continues into this zone. "crowd"The update priority in this zone is the normal priority. "hero"Avatars in this zone have an increased update priority.
+ * @typedef {string} Entities.AvatarPriorityMode
+ */
const char* avatarPriorityModeNames[] = {
"inherit",
"crowd",
diff --git a/libraries/shared/src/GizmoType.h b/libraries/shared/src/GizmoType.h
index fc047b257d..20870158bc 100644
--- a/libraries/shared/src/GizmoType.h
+++ b/libraries/shared/src/GizmoType.h
@@ -12,16 +12,16 @@
#include "QString"
/**jsdoc
- * Controls how the Gizmo behaves and renders
+ * A {@link Entities.EntityProperties-Gizmo|Gizmo} entity may be one of the following types:
*
*
* Value Description ringA ring gizmo. "ring"A ring gizmo.
- * @typedef {string} GizmoType
+ * @typedef {string} Entities.GizmoType
*/
enum GizmoType {
diff --git a/libraries/shared/src/PointerEvent.cpp b/libraries/shared/src/PointerEvent.cpp
index 69d3f28d80..54374a934c 100644
--- a/libraries/shared/src/PointerEvent.cpp
+++ b/libraries/shared/src/PointerEvent.cpp
@@ -66,7 +66,7 @@ void PointerEvent::setButton(Button button) {
}
/**jsdoc
- * A PointerEvent defines a 2D or 3D mouse or similar pointer event.
+ * A 2D or 3D mouse or similar pointer event.
* @typedef {object} PointerEvent
* @property {string} type - The type of event: "Press", "DoublePress", "Release", or
* "Move".
diff --git a/libraries/shared/src/PrimitiveMode.h b/libraries/shared/src/PrimitiveMode.h
index 6072f24fb9..421b940aa1 100644
--- a/libraries/shared/src/PrimitiveMode.h
+++ b/libraries/shared/src/PrimitiveMode.h
@@ -12,17 +12,17 @@
#include "QString"
/**jsdoc
- * How the geometry of the entity is rendered.
+ * How the geometry of an entity is rendered.
*
*
* Value Description solidThe entity will be drawn as a solid shape. linesThe entity will be drawn as wireframe. "solid"The entity is drawn as a solid shape. "lines"The entity is drawn as wireframe.
- * @typedef {string} PrimitiveMode
+ * @typedef {string} Entities.PrimitiveMode
*/
enum class PrimitiveMode {
diff --git a/libraries/shared/src/PulseMode.h b/libraries/shared/src/PulseMode.h
index 7c823db68c..4e398cbbaa 100644
--- a/libraries/shared/src/PulseMode.h
+++ b/libraries/shared/src/PulseMode.h
@@ -18,12 +18,12 @@
* Value Description noneNo pulsing. inPulse in phase with the pulse period. outPulse out of phase with the pulse period. "none"No pulsing. "in"Pulse in phase with the pulse period. "out"Pulse out of phase with the pulse period.
- * @typedef {string} PulseMode
+ * @typedef {string} Entities.PulseMode
*/
enum class PulseMode {
diff --git a/libraries/shared/src/RegisteredMetaTypes.h b/libraries/shared/src/RegisteredMetaTypes.h
index 2ca7863ec6..5b8aa34fd9 100644
--- a/libraries/shared/src/RegisteredMetaTypes.h
+++ b/libraries/shared/src/RegisteredMetaTypes.h
@@ -122,43 +122,43 @@ glm::vec3 vec3FromVariant(const QVariant &object, bool& valid);
glm::vec3 vec3FromVariant(const QVariant &object);
/**jsdoc
-* A color vector. See also the {@link Vec3(0)|Vec3} object.
-*
-* @typedef {object} Color
-* @property {number} red - Red component value. Integer in the range 0 - 255. Synonyms: r, x.
-* @property {number} green - Green component value. Integer in the range 0 - 255. Synonyms: g, y.
-* @property {number} blue - Blue component value. Integer in the range 0 - 255. Synonyms: b, z.
-* @example Colors can be set in multiple ways and modified with their aliases, but still stringify in the same way
-* Entities.editEntity(, { color: { x: 1, y: 2, z: 3 }}); // { red: 1, green: 2, blue: 3 }
-* Entities.editEntity(, { color: { r: 4, g: 5, b: 6 }}); // { red: 4, green: 5, blue: 6 }
-* Entities.editEntity(, { color: { red: 7, green: 8, blue: 9 }}); // { red: 7, green: 8, blue: 9 }
-* Entities.editEntity(, { color: [10, 11, 12] }); // { red: 10, green: 11, blue: 12 }
-* Entities.editEntity(, { color: 13 }); // { red: 13, green: 13, blue: 13 }
-* var color = Entities.getEntityProperties().color; // { red: 13, green: 13, blue: 13 }
-* color.g = 14; // { red: 13, green: 14, blue: 13 }
-* color.blue = 15; // { red: 13, green: 14, blue: 15 }
-* Entities.editEntity(, { color: "red"}); // { red: 255, green: 0, blue: 0 }
-* Entities.editEntity(, { color: "#00FF00"}); // { red: 0, green: 255, blue: 0 }
-*/
+ * A color vector. See also the {@link Vec3(0)|Vec3} object.
+ *
+ * @typedef {object} Color
+ * @property {number} red - Red component value. Integer in the range 0 - 255. Synonyms: r, x.
+ * @property {number} green - Green component value. Integer in the range 0 - 255. Synonyms: g, y.
+ * @property {number} blue - Blue component value. Integer in the range 0 - 255. Synonyms: b, z.
+ * @example Colors can be set in multiple ways and modified with their aliases, but still stringify in the same way
+ * Entities.editEntity(, { color: { x: 1, y: 2, z: 3 }}); // { red: 1, green: 2, blue: 3 }
+ * Entities.editEntity(, { color: { r: 4, g: 5, b: 6 }}); // { red: 4, green: 5, blue: 6 }
+ * Entities.editEntity(, { color: { red: 7, green: 8, blue: 9 }}); // { red: 7, green: 8, blue: 9 }
+ * Entities.editEntity(, { color: [10, 11, 12] }); // { red: 10, green: 11, blue: 12 }
+ * Entities.editEntity(, { color: 13 }); // { red: 13, green: 13, blue: 13 }
+ * var color = Entities.getEntityProperties().color; // { red: 13, green: 13, blue: 13 }
+ * color.g = 14; // { red: 13, green: 14, blue: 13 }
+ * color.blue = 15; // { red: 13, green: 14, blue: 15 }
+ * Entities.editEntity(, { color: "red"}); // { red: 255, green: 0, blue: 0 }
+ * Entities.editEntity(, { color: "#00FF00"}); // { red: 0, green: 255, blue: 0 }
+ */
/**jsdoc
-* A color vector. See also the {@link Vec3(0)|Vec3} object.
-*
-* @typedef {object} ColorFloat
-* @property {number} red - Red component value. Real in the range 0 - 255. Synonyms: r, x.
-* @property {number} green - Green component value. Real in the range 0 - 255. Synonyms: g, y.
-* @property {number} blue - Blue component value. Real in the range 0 - 255. Synonyms: b, z.
-* @example ColorFloats can be set in multiple ways and modified with their aliases, but still stringify in the same way
-* Entities.editEntity(, { color: { x: 1, y: 2, z: 3 }}); // { red: 1, green: 2, blue: 3 }
-* Entities.editEntity(, { color: { r: 4, g: 5, b: 6 }}); // { red: 4, green: 5, blue: 6 }
-* Entities.editEntity(, { color: { red: 7, green: 8, blue: 9 }}); // { red: 7, green: 8, blue: 9 }
-* Entities.editEntity(, { color: [10, 11, 12] }); // { red: 10, green: 11, blue: 12 }
-* Entities.editEntity(, { color: 13 }); // { red: 13, green: 13, blue: 13 }
-* var color = Entities.getEntityProperties().color; // { red: 13, green: 13, blue: 13 }
-* color.g = 14; // { red: 13, green: 14, blue: 13 }
-* color.blue = 15; // { red: 13, green: 14, blue: 15 }
-* Entities.editEntity(, { color: "red"}); // { red: 255, green: 0, blue: 0 }
-* Entities.editEntity(, { color: "#00FF00"}); // { red: 0, green: 255, blue: 0 }
-*/
+ * A color vector with real values. Values may also be null. See also the {@link Vec3(0)|Vec3} object.
+ *
+ * @typedef {object} ColorFloat
+ * @property {number} red - Red component value. Real in the range 0 - 255. Synonyms: r, x.
+ * @property {number} green - Green component value. Real in the range 0 - 255. Synonyms: g, y.
+ * @property {number} blue - Blue component value. Real in the range 0 - 255. Synonyms: b, z.
+ * @example ColorFloats can be set in multiple ways and modified with their aliases, but still stringify in the same way
+ * Entities.editEntity(, { color: { x: 1, y: 2, z: 3 }}); // { red: 1, green: 2, blue: 3 }
+ * Entities.editEntity(, { color: { r: 4, g: 5, b: 6 }}); // { red: 4, green: 5, blue: 6 }
+ * Entities.editEntity(, { color: { red: 7, green: 8, blue: 9 }}); // { red: 7, green: 8, blue: 9 }
+ * Entities.editEntity(, { color: [10, 11, 12] }); // { red: 10, green: 11, blue: 12 }
+ * Entities.editEntity(, { color: 13 }); // { red: 13, green: 13, blue: 13 }
+ * var color = Entities.getEntityProperties().color; // { red: 13, green: 13, blue: 13 }
+ * color.g = 14; // { red: 13, green: 14, blue: 13 }
+ * color.blue = 15; // { red: 13, green: 14, blue: 15 }
+ * Entities.editEntity(, { color: "red"}); // { red: 255, green: 0, blue: 0 }
+ * Entities.editEntity(, { color: "#00FF00"}); // { red: 0, green: 255, blue: 0 }
+ */
QScriptValue u8vec3ToScriptValue(QScriptEngine* engine, const glm::u8vec3& vec3);
QScriptValue u8vec3ColorToScriptValue(QScriptEngine* engine, const glm::u8vec3& vec3);
void u8vec3FromScriptValue(const QScriptValue& object, glm::u8vec3& vec3);
diff --git a/libraries/shared/src/RenderLayer.h b/libraries/shared/src/RenderLayer.h
index b5bf885616..c95ceb192c 100644
--- a/libraries/shared/src/RenderLayer.h
+++ b/libraries/shared/src/RenderLayer.h
@@ -12,18 +12,18 @@
#include "QString"
/**jsdoc
- * In which layer an entity is rendered.
+ * A layer in which an entity may be rendered.
*
*
* Value Description worldThe entity will be drawn in the world with everything else. frontThe entity will be drawn on top of the world layer, but behind the HUD sphere. hudThe entity will be drawn on top of other layers and the HUD sphere. "world"The entity is drawn in the world with everything else. "front"The entity is drawn on top of the world layer but behind the HUD sphere. "hud"The entity is drawn on top of other layers and the HUD sphere.
- * @typedef {string} RenderLayer
+ * @typedef {string} Entities.RenderLayer
*/
enum class RenderLayer {
diff --git a/libraries/shared/src/ShapeInfo.cpp b/libraries/shared/src/ShapeInfo.cpp
index 00c9b883aa..c60d1c2574 100644
--- a/libraries/shared/src/ShapeInfo.cpp
+++ b/libraries/shared/src/ShapeInfo.cpp
@@ -17,7 +17,7 @@
#include "NumericalConstants.h" // for MILLIMETERS_PER_METER
/**jsdoc
- * A ShapeType defines the shape used for collisions or zones.
+ * Defines the shape used for collisions or zones.
*
*
* Value Description An in-world item may be one of the following types:
+ *
+ *
+ * Value Description "entity"The item is an entity. "avatar"The item is an avatar. "unknown"The item cannot be found.
+ * @typedef {string} Entities.NestableType
+ */
QString SpatiallyNestable::nestableTypeToString(NestableType nestableType) {
switch(nestableType) {
case NestableType::Entity:
diff --git a/libraries/shared/src/WebInputMode.h b/libraries/shared/src/WebInputMode.h
index d97ccef519..4f43691ac9 100644
--- a/libraries/shared/src/WebInputMode.h
+++ b/libraries/shared/src/WebInputMode.h
@@ -12,14 +12,14 @@
#include "QString"
/**jsdoc
- * Controls how the web surface processed PointerEvents
+ * Specifies how a web surface processes events.
*
*
* Value Description touchEvents are processed as touch events. mouseEvents are processed as mouse events. "touch"Events are processed as touch events. "mouse"Events are processed as mouse events.
* @typedef {string} WebInputMode