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 - <code>true</code> to enable translations contained in the animation to be
+ * played, <code>false</code> 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 <code>true</code> then the animation should play.
- * @property {boolean} loop=true - If <code>true</code> then the animation should be continuously repeated in a loop.
- * @property {boolean} hold=false - If <code>true</code> then the rotations and translations of the last frame played should be
+ * @property {boolean} loop=true - If <code>true</code> then the animation is continuously repeated in a loop.
+ * @property {boolean} hold=false - If <code>true</code> 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/EntityItemProperties.cpp b/libraries/entities/src/EntityItemProperties.cpp
index 805eabc877..a9ca5b8a9d 100644
--- a/libraries/entities/src/EntityItemProperties.cpp
+++ b/libraries/entities/src/EntityItemProperties.cpp
@@ -608,27 +608,27 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
}
/**jsdoc
- * Different entity types have different properties: some common to all entities (listed below) and some specific to each
+ * Different entity types have different properties: some common to all entities (listed below) and some specific to each
* {@link Entities.EntityType|EntityType} (linked to below). The properties are accessed as an object of property names and
* values.
*
* @typedef {object} Entities.EntityProperties
* @property {Uuid} id - The ID of the entity. <em>Read-only.</em>
* @property {string} name="" - A name for the entity. Need not be unique.
- * @property {Entities.EntityType} type - The entity type. You cannot change the type of an entity after it's created. (Though
- * its value may switch among <code>"Box"</code>, <code>"Shape"</code>, and <code>"Sphere"</code> depending on changes to
- * the <code>shape</code> property set for entities of these types.) <em>Read-only.</em>
- * @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 <code>entityHostType</code> parameter in
- * {@link Entities.addEntity}. Read-only.
- * @property {boolean} avatarEntity=false - If <code>true</code> 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. <em>Value cannot be changed after the entity is created.</em><br />
- * The value can only be set at entity creation by using the <code>entityHostType</code> parameter in
- * {@link Entities.addEntity}. <code>clientOnly</code> is an alias. Read-only.
- * @property {boolean} localEntity=false - If <code>true</code> then the entity is a local entity; Local entities only render for you and are not sent over the wire.
- * <em>Value cannot be changed after the entity is created.</em><br />
- * The value can only be set at entity creation by using the <code>entityHostType</code> 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 <code>"Box"</code>, <code>"Shape"</code>, and <code>"Sphere"</code> depending on
+ * changes to the <code>shape</code> property set for entities of these types. <em>Read-only.</em>
+ *
+ * @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. <em>Read-only.</em>
+ * @property {boolean} avatarEntity=false - <code>true</code> if the entity is an {@link Entities.EntityHostType|avatar entity},
+ * <code>false</code> if it isn't. The value is per the <code>entityHostType</code> property value, set at entity creation
+ * by one of the {@link Entities.addEntity} methods. <em>Read-only.</em>
+ * @property {boolean} clientOnly=false - A synonym for <code>avatarEntity</code>. <em>Read-only.</em>
+ * @property {boolean} localEntity=false - <code>true</code> if the entity is a {@link Entities.EntityHostType|local entity},
+ * <code>false</code> if it isn't. The value is per the <code>entityHostType</code> property value, set at entity creation
+ * by one of the {@link Entities.addEntity} methods. <em>Read-only.</em>
+ *
* @property {Uuid} owningAvatarID=Uuid.NULL - The session ID of the owning avatar if <code>avatarEntity</code> is
* <code>true</code>, otherwise {@link Uuid(0)|Uuid.NULL}. <em>Read-only.</em>
*
@@ -651,16 +651,18 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* {@link Entities.EntityType|Model} and {@link Entities.EntityType|Shape} entities. Shadows are cast if inside a
* {@link Entities.EntityType|Zone} entity with <code>castShadows</code> 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 <code>true</code> 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 <code>true</code>, picks ignore the entity.
+ * @property {boolean} isVisibleInSecondaryCamera=true - <code>true</code> if the entity is rendered in the secondary camera,
+ * <code>false</code> 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 - <code>true</code> if {@link Picks} and {@link RayPick} ignore the entity,
+ * <code>false</code> if they don't ignore it.
*
* @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} 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}. <em>Read-only.</em>
@@ -668,72 +670,74 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* {@link Vec3(0)|Vec3.ONE}. <em>Read-only.</em>
*
* @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, <code>0.0</code>
- * – <code>1.0</code>. 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 <code>1/e = 0.368</code> of its
- * initial value.
+ * @property {number} damping=0.39347 - How much to slow down the linear velocity of an entity over time, range
+ * <code>0.0</code> – <code>1.0</code>. 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 <code>1/e = 0.368</code>
+ * 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 to slow down the angular velocity of an entity over time, range
* <code>0.0</code> – <code>1.0</code>. 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 <code>1/e = 0.368</code>
* of its initial value.
*
* @property {Vec3} gravity=0,0,0 - The acceleration due to gravity in m/s<sup>2</sup> that the entity should move with, in
- * world coordinates. Set to <code>{ x: 0, y: -9.8, z: 0 }</code> to simulate Earth's gravity. Gravity is applied to an
- * entity's motion only if its <code>dynamic</code> property is <code>true</code>. If changing an entity's
- * <code>gravity</code> from {@link Vec3(0)|Vec3.ZERO}, you need to give it a small <code>velocity</code> in order to kick
- * off physics simulation.
- * The <code>gravity</code> value is applied in addition to the <code>acceleration</code> value.
+ * world coordinates. Use a value of <code>{ x: 0, y: -9.8, z: 0 }</code> to simulate Earth's gravity. Gravity is applied
+ * to an entity's motion only if its <code>dynamic</code> property is <code>true</code>. The <code>gravity</code> value is
+ * applied in addition to the <code>acceleration</code> value.
+ * <p>If changing an entity's <code>gravity</code> from {@link Vec3(0)|Vec3.ZERO}, you need to give it a small
+ * <code>velocity</code> in order to kick off physics simulation.</p>
* @property {Vec3} acceleration=0,0,0 - A general acceleration in m/s<sup>2</sup> that the entity should move with, in world
* coordinates. The acceleration is applied to an entity's motion only if its <code>dynamic</code> property is
- * <code>true</code>. If changing an entity's <code>acceleration</code> from {@link Vec3(0)|Vec3.ZERO}, you need to give it
- * a small <code>velocity</code> in order to kick off physics simulation.
- * The <code>acceleration</code> value is applied in addition to the <code>gravity</code> value.
- * @property {number} restitution=0.5 - The "bounciness" of an entity when it collides, <code>0.0</code> –
+ * <code>true</code>. The <code>acceleration</code> value is applied in addition to the <code>gravity</code> value.
+ * <p>If changing an entity's <code>acceleration</code> from {@link Vec3(0)|Vec3.ZERO}, you need to give it a small
+ * <code>velocity</code> in order to kick off physics simulation.<p>
+ * @property {number} restitution=0.5 - The "bounciness" of an entity when it collides, range <code>0.0</code> –
* <code>0.99</code>. 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, <code>0.0</code> –
- * <code>10.0</code>. The higher the value, the more quickly it slows down. Examples: <code>0.1</code> for ice,
+ * @property {number} friction=0.5 - How much to slow down an entity when it's moving against another, range <code>0.0</code>
+ * – <code>10.0</code>. The higher the value, the more quickly it slows down. Examples: <code>0.1</code> for ice,
* <code>0.9</code> for sandpaper.
- * @property {number} density=1000 - The density of the entity in kg/m<sup>3</sup>, <code>100</code> for balsa wood –
- * <code>10000</code> 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/m<sup>3</sup>, range <code>100</code> for balsa wood
+ * – <code>10000</code> 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
- * <code>collisionMask<code> property. If <code>true</code> then the entity does not collide. A synonym is <code>ignoreForCollisions</code>.
+ * <code>collisionMask</code> property. If <code>true</code> then the entity does not collide.
+ * @property {boolean} ignoreForCollisions - Synonym for <code>collisionless</code>.
* @property {CollisionMask} collisionMask=31 - What types of items the entity should collide with.
* @property {string} collidesWith="static,dynamic,kinematic,myAvatar,otherAvatar," - Synonym for <code>collisionMask</code>,
* 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 <code>true</code> then
- * the entity's movement is affected by collisions. A synonym is <code>collisionsWillMove</code>.
+ * the entity's movement is affected by collisions.
+ * @property {boolean} collisionsWillMove - A synonym for <code>dynamic</code>.
*
- * @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 <code>href</code> 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 <code>JSON.parse()</code> to parse the string into a JavaScript object
- * which you can manipulate the properties of, and use <code>JSON.stringify()</code> 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.
+ * <p><strong>Warning:</strong> 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 <code>JSON.parse()</code> to parse the string into
+ * a JavaScript object which you can manipulate the properties of, and use <code>JSON.stringify()</code> to convert the
+ * object into a string to put back in the property.</p>
*
- * @property {string} privateUserData="" - Like userData, but only accessible by Entity Server Scripts, AC scripts, and users
- * who are given "Can Get and Set Private User Data" permissions from the ACL matrix on the Domain Settings page.
+ * @property {string} privateUserData="" - Like <code>userData</code>, 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 <code>Date.now()</code>.
* If you update the property's value, the <code>script</code> 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
* <code>65535</code> or <code>-1</code> 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 <code>position</code>. If the entity is parented to an avatar and is an <code>avatarEntity</code>
+ * otherwise the same value as <code>position</code>. 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 <code>rotation</code>.
@@ -742,7 +746,7 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* @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 <code>position</code>.
* @property {Vec3} localDimensions - The dimensions of the entity. If the entity is parented to an avatar and is an
- * <code>avatarEntity</code> 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.
@@ -760,50 +764,52 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* @property {Entities.RenderInfo} renderInfo - Information on the cost of rendering the entity. Currently information is only
* provided for <code>Model</code> entities. <em>Read-only.</em>
*
- * @property {boolean} cloneable=false - If <code>true</code> then the entity can be cloned via {@link Entities.cloneEntity}.
+ * @property {boolean} cloneable=false - If <code>true</code> 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 <code>true</code> then clones created from this entity will have their
* <code>dynamic</code> property set to <code>true</code>.
* @property {boolean} cloneAvatarEntity=false - If <code>true</code> then clones created from this entity will be created as
- * avatar entities: their <code>avatarEntity</code> property will be set to <code>true</code>.
+ * 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 <code>certificateID</code>.
*
- * @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 <code>shape</code> property value is subsequently changed then the entity's
* <code>type</code> will be reported as <code>"Sphere"</code> if the <code>shape</code> is set to <code>"Sphere"</code>,
* otherwise it will be reported as <code>"Shape"</code>.
+ *
* @typedef {object} Entities.EntityProperties-Box
+ * @see {@link Entities.EntityProperties-Shape|EntityProperties-Shape}
*/
/**jsdoc
- * The <code>"Light"</code> {@link Entities.EntityType|EntityType} adds local lighting effects.
- * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ * The <code>"Light"</code> {@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 <code>true</code> 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 <caption>Create a spotlight pointing at the ground.</caption>
@@ -845,8 +854,9 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The <code>"Line"</code> {@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}.
+ * <p class=important>Deprecated: Use PolyLines instead.</p>
+ *
* @typedef {object} Entities.EntityProperties-Line
* @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. Must be sufficient to contain all the
* <code>linePoints</code>.
@@ -871,41 +881,46 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
*/
/**jsdoc
- * The <code>"Material"</code> {@link Entities.EntityType|EntityType} modifies the existing materials on entities and avatars.
- * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.<br />
- * To apply a material to an entity, set the material entity's <code>parentID</code> property to the entity ID.
+ * The <code>"Material"</code> {@link Entities.EntityType|EntityType} modifies existing materials on entities and avatars. It
+ * has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ * <p>To apply a material to an entity, set the material entity's <code>parentID</code> property to the entity ID.
* To apply a material to an avatar, set the material entity's <code>parentID</code> 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 <code>entityHostType</code> parameter in {@link Entities.addEntity} to <code>"avatar"</code>.
- * Material entities render as non-scalable spheres if they don't have their parent set.
+ * by setting the <code>entityHostType</code> parameter in {@link Entities.addEntity} to <code>"avatar"</code> and set the
+ * entity's <code>parentID</code> property to <code>MyAvatar.SELF_ID</code>.
+ * Material entities render as non-scalable spheres if they don't have their parent set.</p>
+ *
* @typedef {object} Entities.EntityProperties-Material
- * @property {string} materialURL="" - URL to a {@link MaterialResource}. If you append <code>#name</code> to the URL, the
- * material with that name in the {@link MaterialResource} will be applied to the entity. <br />
- * Alternatively, set the property value to <code>"materialData"</code> to use the <code>materialData</code> 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 <code>materialMappingMode == "projected"</code>.
+ * @property {string} materialURL="" - URL to a {@link Entities.MaterialResource|MaterialResource}. If you append
+ * <code>"#name"</code> 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 <code>"materialData"</code> to use the
+ * <code>materialData</code> 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 <code>JSON.parse()</code> to parse the string into a JavaScript object which you can manipulate the
+ * properties of, and use <code>JSON.stringify()</code> 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
* <code>0</code>.
* @property {string} parentMaterialName="0" - Selects the mesh part or parts within the parent to which to apply the material.
* If in the format <code>"mat::string"</code>, all mesh parts with material name <code>"string"</code> are replaced.
- * Otherwise the property value is parsed as an unsigned integer, specifying the mesh part index to modify. If <code>"all"</code>,
- * all mesh parts will be replaced. If an array (starts with <code>"["</code> and ends with <code>"]"</code>), the string will be
- * split at each <code>","</code> and each element will be parsed as either a number or a string if it starts with
- * <code>"mat::"</code>. In other words, <code>"[0,1,mat::string,mat::string2]"</code> will replace mesh parts 0 and 1, and any
- * mesh parts with material <code>"string"</code> or <code>"string2"</code>. Do not put spaces around the commas. Invalid values
- * are parsed to <code>0</code>.
+ * If <code>"all"</code> then all mesh parts are replaced.
+ * Otherwise the property value is parsed as an unsigned integer, specifying the mesh part index to modify.
+ * <p>If the string represents an array (starts with <code>"["</code> and ends with <code>"]"</code>), the string is split
+ * at each <code>","</code> and each element parsed as either a number or a string if it starts with <code>"mat::"</code>.
+ * For example, <code>"[0,1,mat::string,mat::string2]"</code> will replace mesh parts 0 and 1, and any mesh parts with
+ * material <code>"string"</code> or <code>"string2"</code>. Do not put spaces around the commas. Invalid values are parsed
+ * to <code>0</code>.</p>
* @property {string} materialMappingMode="uv" - How the material is mapped to the entity. Either <code>"uv"</code> or
- * <code>"projected"</code>. 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.
+ * <code>"projected"</code>. In <code>"uv"</code> mode, the material is evaluated within the UV space of the mesh it is
+ * applied to. In <code>"projected"</code> 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
* <code>{ x: 0, y: 0 }</code> – <code>{ x: 1, y: 1 }</code>.
* @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
- * <code>JSON.parse()</code> to parse the string into a JavaScript object which you can manipulate the properties of, and
- * use <code>JSON.stringify()</code> 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 <code>true</code>, the material repeats. If <code>false</code>, fragments
+ * outside of texCoord 0 – 1 will be discarded. Works in both <code>"uv"</code> and </code>"projected"</code> modes.
* @example <caption>Color a sphere using a Material entity.</caption>
* var entityID = Entities.addEntity({
* type: "Sphere",
@@ -931,15 +946,20 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
*/
/**jsdoc
- * The <code>"Model"</code> {@link Entities.EntityType|EntityType} displays an FBX or OBJ model.
- * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ * The <code>"Model"</code> {@link Entities.EntityType|EntityType} displays a glTF, FBX, or OBJ model. When adding an entity,
+ * if no <code>dimensions</code> value is specified then the model is automatically sized to its
+ * <code>{@link Entities.EntityProperties|naturalDimensions}</code>. 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 <code>dimensions</code>
* value is specified then the model is automatically sized to its
* <code>{@link Entities.EntityProperties|naturalDimensions}</code>.
- * @property {Vec3} modelScale - The scale factor applied to the model's dimensions. Deprecated.
- * @property {Color} color=255,255,255 - <em>Currently not used.</em>
- * @property {string} modelURL="" - The URL of the FBX of OBJ model. Baked FBX models' URLs end in ".baked.fbx".<br />
+ * @property {string} modelURL="" - The URL of the glTF, FBX, or OBJ model. glTF models may be in JSON or binary format
+ * (".gltf" or ".glb" URLs respectively). Baked FBX models' URLs end in ".baked.fbx". Model files may also be compressed in GZ
+ * format, in which case the URL ends in ".gz".
+ * @property {Vec3} modelScale - The scale factor applied to the model's dimensions.
+ * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @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 the <code>originalTextures</code> 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 <code>JSON.parse()</code> to
* parse the JSON string into a JavaScript object of name, URL pairs. <em>Read-only.</em>
+ * @property {Color} color=255,255,255 - <em>Currently not used.</em>
*
* @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 <code>shapeType</code> 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; <code>[]</code> if none are applied or the
+ * @property {Quat[]} jointRotations=[]] - Joint rotations applied to the model; <code>[]</code> 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.<br />
- * 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 <code>jointRotationsSet</code> value to <code>true</code>.
- * @property {boolean[]} jointRotationsSet=[] - <code>true</code> values for joints that have had rotations applied,
+ * each joint's parent.
+ * <p>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 <code>jointRotationsSet</code> value to <code>true</code>.</p>
+ * @property {boolean[]} jointRotationsSet=[]] - <code>true</code> values for joints that have had rotations applied,
* <code>false</code> otherwise; <code>[]</code> 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; <code>[]</code> if none are applied or
+ * @property {Vec3[]} jointTranslations=[]] - Joint translations applied to the model; <code>[]</code> 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.<br />
- * Joint translations can be set by {@link Entities.setLocalJointTranslation|setLocalJointTranslation} and similar
+ * to each joint's parent.
+ * <p>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 <code>jointTranslationsSet</code> value to <code>true</code>.
- * @property {boolean[]} jointTranslationsSet=[] - <code>true</code> values for joints that have had translations applied,
+ * set the corresponding <code>jointTranslationsSet</code> value to <code>true</code>.</p>
+ * @property {boolean[]} jointTranslationsSet=[]] - <code>true</code> values for joints that have had translations applied,
* <code>false</code> otherwise; <code>[]</code> if none are applied or the model hasn't loaded. The array indexes are per
* {@link Entities.getJointIndex|getJointIndex}.
* @property {boolean} relayParentJoints=false - If <code>true</code> and the entity is parented to an avatar, then the
@@ -990,98 +1011,103 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
*/
/**jsdoc
- * The <code>"ParticleEffect"</code> {@link Entities.EntityType|EntityType} displays a particle system that can be used to
+ * The <code>"ParticleEffect"</code> {@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 <code>true</code> then particles are emitted.
+ * @property {boolean} isEmitting=true - <code>true</code> if particles are being emitted, <code>false</code> 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 <code>emitSpeed == 5</code>
- * and <code>speedSpread == 1</code>, 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
+ * <code>emitSpeed == 5</code> and <code>speedSpread == 1</code>, particles will be emitted with speeds in the range
+ * <code>4</code> – <code>6</code>m/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
* <code>emitAccelerations == {x: 0, y: -9.8, z: 0}</code> and <code>accelerationSpread ==
* {x: 0, y: 1, z: 0}</code>, each particle will have an acceleration in the range <code>{x: 0, y: -10.8, z: 0}</code>
* – <code>{x: 0, y: -8.8, z: 0}</code>.
* @property {Vec3} dimensions - The dimensions of the particle effect, i.e., a bounding box containing all the particles
- * during their lifetimes, assuming that <code>emitterShouldTrail</code> is <code>false</code>. <em>Read-only.</em>
+ * during their lifetimes, assuming that <code>emitterShouldTrail == false</code>. <em>Read-only.</em>
* @property {boolean} emitterShouldTrail=false - If <code>true</code> 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 <code>azimuthStart</code> and <code>azimuthFinish</code>
* 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
- * <code>shapeType</code>.
+ *
+ * @property {ShapeType} shapeType="ellipsoid" - The shape from which particles are emitted.
+ * @property {string} compoundShapeURL="" - The model file to use for the compound shape if <code>shapeType ==
+ * "compound"</code>.
+ * @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 <code>0.0</code> – <code>1.0</code> for the center to the surface, respectively.
* Particles are emitted from the portion of the shape that lies between <code>emitRadiusStart</code> 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 <code>0</code> – <code>Math.PI</code>. Particles are emitted from the portion of the
- * shape that lies between <code>polarStart<code> and <code>polarFinish</code>. Only used if <code>shapeType</code> is
- * <code>ellipsoid</code> or <code>sphere</code>.
+ * shape that lies between <code>polarStart</code> and <code>polarFinish</code>. Only used if <code>shapeType</code> is
+ * <code>"ellipsoid"</code> or <code>"sphere"</code>.
* @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 <code>0</code> – <code>Math.PI</code>. Particles are emitted from the portion of the
- * shape that lies between <code>polarStart<code> and <code>polarFinish</code>. Only used if <code>shapeType</code> is
- * <code>ellipsoid</code> or <code>sphere</code>.
+ * shape that lies between <code>polarStart</code> and <code>polarFinish</code>. Only used if <code>shapeType</code> is
+ * <code>"ellipsoid"</code> or <code>"sphere"</code>.
* @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 <code>-Math.PI</code> – <code>Math.PI</code>. Particles are
- * emitted from the portion of the shape that lies between <code>azimuthStart<code> and <code>azimuthFinish</code>.
- * Only used if <code>shapeType</code> is <code>ellipsoid</code>, <code>sphere</code>, or <code>circle</code>.
+ * emitted from the portion of the shape that lies between <code>azimuthStart</code> and <code>azimuthFinish</code>.
+ * Only used if <code>shapeType</code> is <code>"ellipsoid"</code>, <code>"sphere"</code>, or <code>"circle"</code>.
* @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 <code>-Math.PI</code> – <code>Math.PI</code>. Particles are
- * emitted from the portion of the shape that lies between <code>azimuthStart<code> and <code>azimuthFinish</code>.
- * Only used if <code>shapeType</code> is <code>ellipsoid</code>, <code>sphere</code>, or <code>circle</code>..
+ * emitted from the portion of the shape that lies between <code>azimuthStart</code> and <code>azimuthFinish</code>.
+ * Only used if <code>shapeType</code> is <code>"ellipsoid"</code>, <code>"sphere"</code>, or <code>"circle"</code>.
*
* @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 <code>NaN</code>, the
+ * @property {number} radiusStart=null - The radius of each particle at the start of its life. If <code>null</code>, the
* <code>particleRadius</code> value is used.
- * @property {number} radiusFinish=NaN - The radius of each particle at the end of its life. If <code>NaN</code>, the
+ * @property {number} radiusFinish=null - The radius of each particle at the end of its life. If <code>null</code>, the
* <code>particleRadius</code> value is used.
- * @property {number} radiusSpread=0 - The spread in radius that each particle is given. If <code>particleRadius == 0.5</code>
- * and <code>radiusSpread == 0.25</code>, each particle will have a radius in the range <code>0.25</code> –
- * <code>0.75</code>.
+ * @property {number} radiusSpread=0 - The spread in radius that each particle is given. For example, if
+ * <code>particleRadius == 0.5</code> and <code>radiusSpread == 0.25</code>, each particle will have a radius in the range
+ * <code>0.25</code> – <code>0.75</code>.
* @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 <code>color</code> 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 <code>color</code> 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 <code>color</code> 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 <code>color</code> value is used.
+ * @property {Color} colorSpread=0,0,0 - The spread in color that each particle is given. For example, if
* <code>color == {red: 100, green: 100, blue: 100}</code> and <code>colorSpread ==
* {red: 10, green: 25, blue: 50}</code>, each particle will have a color in the range
* <code>{red: 90, green: 75, blue: 50}</code> – <code>{red: 110, green: 125, blue: 150}</code>.
- * @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 <code>NaN</code>, 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 <code>null</code>, the
* <code>alpha</code> value is used.
- * @property {number} alphaFinish=NaN - The alpha of each particle at the end of its life. If <code>NaN</code>, the
+ * @property {number} alphaFinish=null - The opacity of each particle at the end of its life. If <code>null</code>, the
* <code>alpha</code> value is used.
- * @property {number} alphaSpread=0 - The spread in alpha that each particle is given. If <code>alpha == 0.5</code>
- * and <code>alphaSpread == 0.25</code>, each particle will have an alpha in the range <code>0.25</code> –
- * <code>0.75</code>.
- * @property {number} particleSpin=0 - The spin of each particle at the middle of its life. In the range <code>-2*PI</code> – <code>2*PI</code>.
- * @property {number} spinStart=NaN - The spin of each particle at the start of its life. In the range <code>-2*PI</code> – <code>2*PI</code>.
- * If <code>NaN</code>, the <code>particleSpin</code> value is used.
- * @property {number} spinFinish=NaN - The spin of each particle at the end of its life. In the range <code>-2*PI</code> – <code>2*PI</code>.
- * If <code>NaN</code>, the <code>particleSpin</code> value is used.
- * @property {number} spinSpread=0 - The spread in spin that each particle is given. In the range <code>0</code> – <code>2*PI</code>. If <code>particleSpin == PI</code>
- * and <code>spinSpread == PI/2</code>, each particle will have a spin in the range <code>PI/2</code> – <code>3*PI/2</code>.
- * @property {boolean} rotateWithEntity=false - Whether or not the particles' spin will rotate with the entity. If false, when <code>particleSpin == 0</code>, 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 <code>shapeType</code> is
- * <code>"compound"</code>.
+ * @property {number} alphaSpread=0 - The spread in alpha that each particle is given. For example, if
+ * <code>alpha == 0.5</code> and <code>alphaSpread == 0.25</code>, each particle will have an alpha in the range
+ * <code>0.25</code> – <code>0.75</code>.
+ * @property {Entities.Pulse} pulse - Color and alpha pulse.
+ * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
+ * @property {number} particleSpin=0 - The rotation of each particle at the middle of its life, range <code>-2 * Math.PI</code>
+ * – <code>2 * Math.PI</code> radians.
+ * @property {number} spinStart=null - The rotation of each particle at the start of its life, range <code>-2 * Math.PI</code>
+ * – <code>2 * Math.PI</code> radians. If <code>null</code>, the <code>particleSpin</code> value is used.
+ * @property {number} spinFinish=null - The rotation of each particle at the end of its life, range <code>-2 * Math.PI</code>
+ * – <code>2 * Math.PI</code> radians. If <code>null</code>, the <code>particleSpin</code> value is used.
+ * @property {number} spinSpread=0 - The spread in spin that each particle is given, range <code>0</code> –
+ * <code>2 * Math.PI</code> radians. For example, if <code>particleSpin == Math.PI</code> and
+ * <code>spinSpread == Math.PI / 2</code>, each particle will have a rotation in the range <code>Math.PI / 2</code> –
+ * <code>3 * Math.PI / 2</code>.
+ * @property {boolean} rotateWithEntity=false - <code>true</code> to make the particles' rotations relative to the entity's
+ * instantaneous rotation, <code>false</code> to make them relative to world coordinates. If <code>true</code> with
+ * <code>particleSpin == 0</code>, the particles keep oriented per the entity's orientation.
*
* @example <caption>Create a ball of green smoke.</caption>
* particles = Entities.addEntity({
@@ -1102,27 +1128,30 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
*/
/**jsdoc
- * The <code>"PolyLine"</code> {@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 <code>"PolyLine"</code> {@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 <code>linePoints</code>. 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. <em>Read-only.</em>
+ * @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 <code>linePoints</code>. 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 <code>linePoints</code>. Must be specified in
+ * @property {number[]} strokeWidths=[]] - The widths, in m, of the line at the <code>linePoints</code>. 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, <code>color</code> is used for the remaining points.
- * @property {Color} color=255,255,255 - Used as the color for each point if <code>strokeColors</code> is too short.
+ * @property {Vec3[]} strokeColors=[]] - The base colors of each point, with values in the range <code>0.0,0.0,0.0</code>
+ * — <code>1.0,1.0,1.0</code>. These colors are multiplied with the color of the texture. If there are more line
+ * points than stroke colors, the <code>color</code> property value is used for the remaining points.
+ * <p><strong>Warning:</strong> The ordinate values are in the range <code>0.0</code> — <code>1.0</code>.</p>
+ * @property {Color} color=255,255,255 - Used as the color for each point if <code>strokeColors</code> 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 <code>true</code>, the texture is stretched to fill the whole line, otherwise
* the texture repeats along the line.
- * @property {bool} glow=false - If <code>true</code>, the alpha of the strokes will drop off farther from the center.
- * @property {bool} faceCamera=false - If <code>true</code>, each line segment will rotate to face the camera.
+ * @property {boolean} glow=false - If <code>true</code>, the opacity of the strokes drops off away from the line center.
+ * @property {boolean} faceCamera=false - If <code>true</code>, each line segment rotates to face the camera.
* @example <caption>Draw a textured "V".</caption>
* var entity = Entities.addEntity({
* type: "PolyLine",
@@ -1147,12 +1176,13 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
*/
/**jsdoc
- * The <code>"PolyVox"</code> {@link Entities.EntityType|EntityType} displays a set of textured voxels.
+ * The <code>"PolyVox"</code> {@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 <code>voxelSurfaceStyle</code> and neighbor ID properties.<br />
- * PolyVox entities uses a library from <a href="http://www.volumesoffun.com/">Volumes of Fun</a>. Their
- * <a href="http://www.volumesoffun.com/polyvox-documentation/">library documentation</a> may be useful to read.
+ * configuring their <code>voxelSurfaceStyle</code> and various neighbor ID properties.
+ * <p>PolyVox entities uses a library from <a href="http://www.volumesoffun.com/">Volumes of Fun</a>. Their
+ * <a href="http://www.volumesoffun.com/polyvox-documentation/">library documentation</a> may be useful to read.</p>
+ *
* @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
@@ -1203,12 +1233,14 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The <code>"Shape"</code> {@link Entities.EntityType|EntityType} displays an entity of a specified <code>shape</code>.
* 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 <code>0.0</code> – <code>1.0</code>.
+ * @property {Entities.Pulse} pulse - Color and alpha pulse.
+ * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @example <caption>Create a cylinder.</caption>
* var shape = Entities.addEntity({
* type: "Shape",
@@ -1225,30 +1257,39 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* when the entity is created. If its <code>shape</code> property value is subsequently changed then the entity's
* <code>type</code> will be reported as <code>"Box"</code> if the <code>shape</code> is set to <code>"Cube"</code>,
* otherwise it will be reported as <code>"Shape"</code>.
+ *
* @typedef {object} Entities.EntityProperties-Sphere
+ * @see {@link Entities.EntityProperties-Shape|EntityProperties-Shape}
*/
/**jsdoc
* The <code>"Text"</code> {@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 <code>\n</code>. 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 <code>"none"</code>, the entity is not billboarded. If <code>"yaw"</code>, the entity will be
- * oriented to follow your camera around the y-axis. If <code>"full"</code> the entity will be oriented to face your camera. The following deprecated
- * behavior is also supported: you can also set <code>"faceCamera"</code> to <code>true</code> to set <code>billboardMode</code> to "yaw", and you can set
- * <code>"isFacingAvatar"</code> to <code>true</code> to set <code>billboardMode</code> to "full". Setting either to <code>false</code> sets the mode to "none"
+ * @property {number} backgroundAlpha=1.0 - The opacity of the background.
+ * @property {Entities.Pulse} pulse - Color and alpha pulse.
+ * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @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 - <code>true</code> if <code>billboardMode</code> is <code>"yaw"</code>, otherwise
+ * <code>false</code>. Setting this property to <code>false</code> sets the <code>billboardMode</code> to
+ * <code>"none"</code>.
+ * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
+ * @property {boolean} isFacingAvatar - <code>true</code> if <code>billboardMode</code> is <code>"full"</code>, otherwise
+ * <code>false</code>. Setting this property to <code>false</code> sets the <code>billboardMode</code> to
+ * <code>"none"</code>.
+ * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @example <caption>Create a text entity.</caption>
* var text = Entities.addEntity({
* type: "Text",
@@ -1262,28 +1303,36 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
*/
/**jsdoc
- * The <code>"Web"</code> {@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 <code>"Web"</code> {@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 <code>"none"</code>, the entity is not billboarded. If <code>"yaw"</code>, the entity will be
- * oriented to follow your camera around the y-axis. If <code>"full"</code> the entity will be oriented to face your camera. The following deprecated
- * behavior is also supported: you can also set <code>"faceCamera"</code> to <code>true</code> to set <code>billboardMode</code> to "yaw", and you can set
- * <code>"isFacingAvatar"</code> to <code>true</code> to set <code>billboardMode</code> to "full". Setting either to <code>false</code> 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.
+ * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
+ * @property {BillboardMode} billboardMode="none" - Whether the entity is billboarded to face the camera.
+ * @property {boolean} faceCamera - <code>true</code> if <code>billboardMode</code> is <code>"yaw"</code>, otherwise
+ * <code>false</code>. Setting this property to <code>false</code> sets the <code>billboardMode</code> to
+ * <code>"none"</code>.
+ * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
+ * @property {boolean} isFacingAvatar - <code>true</code> if <code>billboardMode</code> is <code>"full"</code>, otherwise
+ * <code>false</code>. Setting this property to <code>false</code> sets the <code>billboardMode</code> to
+ * <code>"none"</code>.
+ * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @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 <code>dimensions.x</code> and <code>dimensions.y</code> 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 - <code>true</code> to highlight the entity when it has keyboard focus,
+ * <code>false</code> to not display the highlight.
* @example <caption>Create a Web entity displaying at 1920 x 1080 resolution.</caption>
* var METERS_TO_INCHES = 39.3701;
* var entity = Entities.addEntity({
@@ -1303,74 +1352,54 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The <code>"Zone"</code> {@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 <code>"none"</code>, or set to <code>"compound"</code>
* and <code>compoundShapeURL</code> is <code>""</code>.
* @property {string} compoundShapeURL="" - The model file to use for the compound shape if <code>shapeType</code> is
* <code>"compound"</code>.
*
- * @property {string} keyLightMode="inherit" - Configures the key light in the zone. Possible values:<br />
- * <code>"inherit"</code>: The key light from any enclosing zone continues into this zone.<br />
- * <code>"disabled"</code>: The key light from any enclosing zone and the key light of this zone are disabled in this
- * zone.<br />
- * <code>"enabled"</code>: 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:<br />
- * <code>"inherit"</code>: The ambient light from any enclosing zone continues into this zone.<br />
- * <code>"disabled"</code>: The ambient light from any enclosing zone and the ambient light of this zone are disabled in
- * this zone.<br />
- * <code>"enabled"</code>: 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:<br />
- * <code>"inherit"</code>: The skybox from any enclosing zone is dislayed in this zone.<br />
- * <code>"disabled"</code>: The skybox from any enclosing zone and the skybox of this zone are disabled in this zone.<br />
- * <code>"enabled"</code>: 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:<br />
- * <code>"inherit"</code>: The haze from any enclosing zone continues into this zone.<br />
- * <code>"disabled"</code>: The haze from any enclosing zone and the haze of this zone are disabled in this zone.<br />
- * <code>"enabled"</code>: 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:<br />
- * <code>"inherit"</code>: The bloom from any enclosing zone continues into this zone.<br />
- * <code>"disabled"</code>: The bloom from any enclosing zone and the bloom of this zone are disabled in this zone.<br />
- * <code>"enabled"</code>: 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 <code>true</code> then visitors can fly in the zone; otherwise they cannot.
- * Only works on domain entities.
+ * @property {boolean} flyingAllowed=true - If <code>true</code> then visitors can fly in the zone; otherwise, they cannot.
+ * Only works for domain entities.
* @property {boolean} ghostingAllowed=true - If <code>true</code> 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.<br />
- *
- * @property {string} avatarPriority="inherit" - Configures the update priority of contained avatars to other clients.<br />
- * <code>"inherit"</code>: Priority from enclosing zones is unchanged.<br />
- * <code>"crowd"</code>: Priority in this zone is the normal priority.<br />
- * <code>"hero"</code>: Avatars in this zone will have an increased update priority
+ * certain properties:
* <pre>
- *
* function filter(properties) {
- * // Test and edit properties object values,
+ * // Check and edit properties object values,
* // e.g., properties.modelURL, as required.
* return properties;
* }
* </pre>
*
+ * @property {Entities.AvatarPriorityMode} avatarPriority="inherit" - Configures the priority of updates from avatars in the
+ * zone to other clients.
+ *
* @example <caption>Create a zone that casts a red key light along the x-axis.</caption>
* var zone = Entities.addEntity({
* type: "Zone",
@@ -1388,19 +1417,29 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The <code>"Image"</code> {@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 <code>"none"</code>, the entity is not billboarded. If <code>"yaw"</code>, the entity will be
- * oriented to follow your camera around the y-axis. If <code>"full"</code> the entity will be oriented to face your camera. The following deprecated
- * behavior is also supported: you can also set <code>"faceCamera"</code> to <code>true</code> to set <code>billboardMode</code> to "yaw", and you can set
- * <code>"isFacingAvatar"</code> to <code>true</code> to set <code>billboardMode</code> to "full". Setting either to <code>false</code> 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 - <code>true</code> fi the the image should be emissive (unlit), <code>false</code> if it
+ * shouldn't.
+ * @property {boolean} keepAspectRatio=true - <code>true</code> if the image should maintain its aspect ratio,
+ * <code>false</code> if it shouldn't.
+ * @property {Rect} subImage=0,0,0,0 - The portion of the image to display. If width or height are <code>0</code>, 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.
+ * @property {number} alpha=1 - The opacity of the image.
+ * @property {Entities.Pulse} pulse - Color and alpha pulse.
+ * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
+ * @property {BillboardMode} billboardMode="none" - Whether the entity is billboarded to face the camera.
+ * @property {boolean} faceCamera - <code>true</code> if <code>billboardMode</code> is <code>"yaw"</code>, otherwise
+ * <code>false</code>. Setting this property to <code>false</code> sets the <code>billboardMode</code> to
+ * <code>"none"</code>.
+ * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
+ * @property {boolean} isFacingAvatar - <code>true</code> if <code>billboardMode</code> is <code>"full"</code>, otherwise
+ * <code>false</code>. Setting this property to <code>false</code> sets the <code>billboardMode</code> to
+ * <code>"none"</code>.
+ * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @example <caption>Create a image entity.</caption>
* var image = Entities.addEntity({
* type: "Image",
@@ -1415,16 +1454,19 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The <code>"Grid"</code> {@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.
+ * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @property {boolean} followCamera=true - If <code>true</code>, the grid is always visible even as the camera moves to another
* position.
* @property {number} majorGridEvery=5 - Integer number of <code>minorGridEvery</code> intervals at which to draw a thick grid
* line. Minimum value = <code>1</code>.
* @property {number} minorGridEvery=1 - Real number of meters at which to draw thin grid lines. Minimum value =
* <code>0.001</code>.
- * @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated.
* @example <caption>Create a grid entity.</caption>
* var grid = Entities.addEntity({
* type: "Grid",
@@ -1440,8 +1482,10 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The <code>"Gizmo"</code> {@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 <code>true</code> if any of the textures has transparency.
* @property {number} drawCalls - The number of draw calls required to render the entity.
*/
diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h
index c3b0371029..a10c59e38b 100644
--- a/libraries/entities/src/EntityScriptingInterface.h
+++ b/libraries/entities/src/EntityScriptingInterface.h
@@ -101,9 +101,13 @@ 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 <code>Entities</code> 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").
+ *
+ * <p>Note: For Interface scripts, the entities available to scripts are those that Interface has displayed and so knows
+ * about.</p>
*
* @namespace Entities
*
@@ -113,9 +117,9 @@ 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 <code>null</code>; set to <code>null</code> or {@link Uuid(0)|Uuid.NULL} to
- * clear keyboard focus.
+ * @property {Uuid} keyboardFocusEntity - The {@link Entities.EntityType|Web} entity that has keyboard focus. If no Web entity
+ * has keyboard focus, get returns <code>null</code>; set to <code>null</code> or {@link Uuid(0)|Uuid.NULL} to clear
+ * keyboard focus.
*/
/// handles scripting of Entity commands from JS passed to assigned clients
class EntityScriptingInterface : public OctreeScriptingInterface, public Dependency {
@@ -245,35 +249,39 @@ public slots:
Q_INVOKABLE bool canGetAndSetPrivateUserData();
/**jsdoc
- * <p>How an entity is sent over the wire.</p>
+ * <p>How an entity is hosted and sent to others for display.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
- * <tr><td><code>domain</code></td><td>Domain entities are sent over the entity server to everyone else</td></tr>
- * <tr><td><code>avatar</code></td><td>Avatar entities are sent over the avatar entity and are associated with one avatar</td></tr>
- * <tr><td><code>local</code></td><td>Local entities are not sent over the wire and will only render for you, locally</td></tr>
+ * <tr><td><code>"domain"</code></td><td>Domain entities are stored on the domain, are visible to everyone, and are
+ * sent to everyone by the entity server.</td></tr>
+ * <tr><td><code>"avatar"</code></td><td>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.</td></tr>
+ * <tr><td><code>"local"</code></td><td>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 collisionless.</td></tr>
* </tbody>
* </table>
- * @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 <code>"avatar"</code> 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 <code>"local"</code>, 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 <caption>Create a box entity in front of your avatar.</caption>
+ * @example <caption>Create a box domain entity in front of your avatar.</caption>
* 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 +298,13 @@ public slots:
}
/**jsdoc
- * Add a new entity with specified properties.
+ * Adds a new avatar entity (<code>{@link Entities.EntityProperties|entityHostType}</code> property is
+ * <code>"avatar"</code>) or domain entity (<code>{@link Entities.EntityProperties|entityHostType}</code> property is
+ * <code>"domain"</code>).
* @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] - <code>true</code> to create an avatar entity, <code>false</code> 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) {
@@ -307,9 +318,13 @@ public slots:
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 <code>cloneable</code> property set to <code>true</code>. 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 <code>name</code> property, other properties set per the original
+ * entity's clone-related {@link Entities.EntityProperties|properties} (e.g., <code>cloneLifetime</code>), and
+ * clone-related properties set to defaults.
+ * <p>Domain entities must have their <code>cloneable</code> property value be <code>true</code> in order to be cloned. A
+ * domain entity can be cloned by a client that doesn't have rez permissions in the domain.</p>
+ * <p>Avatar entities must have their <code>cloneable</code> and <code>cloneAvatarEntity</code> property values be
+ * <code>true</code> in order to be cloned.</p>
* @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 +332,21 @@ public slots:
Q_INVOKABLE QUuid cloneEntity(const QUuid& entityID);
/**jsdoc
- * Get the properties of an entity.
+ * Gets the properties of an entity.
* @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.
+ * @param {string|string[]} [desiredProperties=[]] - The names of the properties to get. For properties that are objects
+ * (e.g., the <code>"keyLight"</code> property), use the property and subproperty names in dot notation (e.g.,
+ * <code>"keyLight.color"</code>).
* @returns {Entities.EntityProperties} The 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 <caption>Report the color of a new box entity.</caption>
* 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,17 +355,18 @@ 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 properties.
* @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 <code>null</code>.
+ * @param {Entities.EntityProperties} properties - The new property values.
+ * @returns {Uuid} The ID of the entity if the edit was successful, otherwise <code>null</code> or {@link Uuid|Uuid.NULL}.
* @example <caption>Change the color of an entity.</caption>
* 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));
@@ -361,7 +380,7 @@ public slots:
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 <caption>Delete an entity a few seconds after creating it.</caption>
@@ -379,9 +398,10 @@ 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);
@@ -1436,14 +1456,14 @@ 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.EntityType|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 <code>null</code>.
*/
Q_INVOKABLE QUuid getKeyboardFocusEntity() const;
/**jsdoc
- * Set the {@link Entities.EntityType|Web} entity that has keyboard focus.
+ * Sets the {@link Entities.EntityType|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
* <code>null</code> or {@link Uuid(0)|Uuid.NULL} to unset keyboard focus from an entity.
diff --git a/libraries/entities/src/EntityTypes.h b/libraries/entities/src/EntityTypes.h
index 91b71513dc..55ad2d9561 100644
--- a/libraries/entities/src/EntityTypes.h
+++ b/libraries/entities/src/EntityTypes.h
@@ -42,7 +42,10 @@ public:
* <tr><th>Value</th><th>Description</th><th>Properties</th></tr>
* </thead>
* <tbody>
- * <tr><td><code>"Box"</code></td><td>A rectangular prism. This is a synonym of <code>"Shape"</code> for the case
+ * <tr><td><code>"Shape"</code></td><td>A basic entity such as a cube.
+ * See also, the <code>"Box"</code> and <code>"Sphere"</code> entity types.</td>
+ * <td>{@link Entities.EntityProperties-Shape|EntityProperties-Shape}</td></tr>
+ * <tr><td><code>"Box"</code></td><td>A rectangular prism. This is a synonym of <code>"Shape"</code> for the case
* where the entity's <code>shape</code> property value is <code>"Cube"</code>.<br />
* If an entity is created with its <code>type</code>
* set to <code>"Box"</code> it will always be created with a <code>shape</code> property value of
@@ -56,9 +59,6 @@ public:
* <code>"Sphere"</code>. If an entity of type <code>Box</code> or <code>Shape</code> has its <code>shape</code> set
* to <code>"Sphere"</code> then its <code>type</code> will be reported as <code>"Sphere"</code>.
* <td>{@link Entities.EntityProperties-Sphere|EntityProperties-Sphere}</td></tr>
- * <tr><td><code>"Shape"</code></td><td>A basic entity such as a cube.
- * See also, the <code>"Box"</code> and <code>"Sphere"</code> entity types.</td>
- * <td>{@link Entities.EntityProperties-Shape|EntityProperties-Shape}</td></tr>
* <tr><td><code>"Model"</code></td><td>A mesh model from an FBX or OBJ file.</td>
* <td>{@link Entities.EntityProperties-Model|EntityProperties-Model}</td></tr>
* <tr><td><code>"Text"</code></td><td>A pane of text oriented in space.</td>
@@ -78,7 +78,7 @@ public:
* <td>{@link Entities.EntityProperties-PolyVox|EntityProperties-PolyVox}</td></tr>
* <tr><td><code>"Grid"</code></td><td>A grid of lines in a plane.</td>
* <td>{@link Entities.EntityProperties-Grid|EntityProperties-Grid}</td></tr>
- * <tr><td><code>"Gizmo"</code></td><td>An entity with various UI-related properties.</td>
+ * <tr><td><code>"Gizmo"</code></td><td>A gizmo intended for UI.</td>
* <td>{@link Entities.EntityProperties-Gizmo|EntityProperties-Gizmo}</td></tr>
* <tr><td><code>"Light"</code></td><td>A local lighting effect.</td>
* <td>{@link Entities.EntityProperties-Light|EntityProperties-Light}</td></tr>
diff --git a/libraries/entities/src/GrabPropertyGroup.h b/libraries/entities/src/GrabPropertyGroup.h
index d76ac46a81..99b8100075 100644
--- a/libraries/entities/src/GrabPropertyGroup.h
+++ b/libraries/entities/src/GrabPropertyGroup.h
@@ -41,35 +41,30 @@ static const glm::vec3 INITIAL_EQUIPPABLE_INDICATOR_OFFSET { glm::vec3(0.0f) };
/**jsdoc
- * Grab is defined by the following properties.
+ * Grabbing behavior is defined by the following properties:
+ *
* @typedef {object} Entities.Grab
- *
- * @property {boolean} grabbable=true - If <code>true</code> the entity can be grabbed.
- * @property {boolean} grabKinematic=true - If <code>true</code> the entity is updated in a kinematic manner.
- * If <code>false</code> 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 <code>true</code> 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 <code>true</code>
- * for tools, pens, etc and false for things meant to decorate the hand.
- *
- * @property {boolean} triggerable=false - If <code>true</code> the entity will receive calls to trigger
+ * @property {boolean} grabbable=true - If <code>true</code> then the entity can be grabbed.
+ * @property {boolean} grabKinematic=true - If <code>true</code> then the entity will be updated in a kinematic manner when
+ * grabbed; if <code>false</code> 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 <code>true</code> 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 <code>true</code> for tools,
+ * pens, etc. and <code>false</code> for things meant to decorate the hand.
+ * @property {boolean} triggerable=false - If <code>true</code> then the entity will receive calls to trigger
* {@link Controller|Controller entity methods}.
- *
- * @property {boolean} equippable=true - If <code>true</code> the entity can be equipped.
+ * @property {boolean} equippable=true - If <code>true</code> 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 <code>equippableIndicatorURL</code> 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 <code>equippableIndicatorURL</code> 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 <code>true</code> then haze decreases with altitude as defined by the
- * entity's local coordinate system; <code>hazeBaseRef</code> and </code>hazeCeiling</code> are used.
+ * entity's local coordinate system; <code>hazeBaseRef</code> and <code>hazeCeiling</code> 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: <code>0.0</code>
* displays no skybox image; <code>1.0</code> displays no haze.
*
- * @property {boolean} hazeAttenuateKeyLight=false - <em>Currently not supported.</em>
- * @property {number} hazeKeyLightRange=1000 - <em>Currently not supported.</em>
- * @property {number} hazeKeyLightAltitude=200 - <em>Currently not supported.</em>
+ * @property {boolean} hazeAttenuateKeyLight=false - If <code>true</code> then the haze attenuates the key light;
+ * <code>hazeKeyLightRange</code> and <code>hazeKeyLightAltitude</code> 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..d6246701a4 100644
--- a/libraries/entities/src/KeyLightPropertyGroup.h
+++ b/libraries/entities/src/KeyLightPropertyGroup.h
@@ -28,7 +28,7 @@ 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.
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
- * <p>A <code>PolyVoxSurfaceStyle</code> may be one of the following:</p>
+ * <p>The surface of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity may be one of the following styles:</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Type</th><th>Description</th></tr>
diff --git a/libraries/entities/src/PulsePropertyGroup.h b/libraries/entities/src/PulsePropertyGroup.h
index f54db39149..634ab654a7 100644
--- a/libraries/entities/src/PulsePropertyGroup.h
+++ b/libraries/entities/src/PulsePropertyGroup.h
@@ -26,19 +26,17 @@ class OctreePacketData;
class ReadBitstreamToTreeParams;
/**jsdoc
- * Pulse is defined by the following properties.
+ * A color and alpha pulse that an entity may have.
* @typedef {object} Entities.Pulse
- *
* @property {number} min=0 - The minimum value of the pulse multiplier.
* @property {number} max=1 - The maximum value of the pulse multiplier.
* @property {number} period=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from
* <code>min</code> to <code>max</code>, then <code>max</code> to <code>min</code> 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 <code>0.0</code>
+ * — <code>1.0</code>.
- * @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 - <code>true</code> to render tick marks, otherwise <code>false</code>.
+ * @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
- * <p>A <code>Shape</code>, <code>Box</code>, or <code>Sphere</code> {@link Entities.EntityType|EntityType} may display as
- * one of the following geometrical shapes:</p>
+ * <p>A <code>"Shape"</code>, <code>"Box"</code>, or <code>"Sphere"</code> {@link Entities.EntityType|EntityType} may
+ * display as one of the following geometrical shapes:</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Dimensions</th><th>Notes</th></tr>
diff --git a/libraries/entities/src/SkyboxPropertyGroup.h b/libraries/entities/src/SkyboxPropertyGroup.h
index c3f9b421f4..0c128aa730 100644
--- a/libraries/entities/src/SkyboxPropertyGroup.h
+++ b/libraries/entities/src/SkyboxPropertyGroup.h
@@ -30,7 +30,7 @@ class EntityTreeElementExtraEncodeData;
class ReadBitstreamToTreeParams;
/**jsdoc
- * A skybox is defined by the following properties.
+ * A skybox is defined by the following properties:
* @typedef {object} Entities.Skybox
* @property {Color} color=0,0,0 - Sets the color of the sky if <code>url</code> is <code>""</code>, 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..af1a868647 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. <em>Currently not used.</em>
- * @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,71 @@ 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: <code>"hifi_pbr"</code>.
* @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 <code>"fallthrough"</code> to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {number|string} opacity=1.0 - The opacity, <code>0.0</code> – <code>1.0</code>. Set to <code>"fallthrough"</code> to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {boolean|string} unlit=false - If <code>true</code>, the material is not lit. Set to <code>"fallthrough"</code> to fallthrough to
- * the material below. "hifi_pbr" model only.
+ * is treated as sRGB. A {@link RGBS} value can be either RGB or sRGB.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {number|string} opacity=1.0 - The opacity, range <code>0.0</code> – <code>1.0</code>.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {boolean|string} unlit=false - If <code>true</code>, the material is not lit, otherwise it is.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> 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 <code>"fallthrough"</code> to fallthrough to the material below. Set to <code>"fallthrough"</code> to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {number|string} roughness - The roughness, <code>0.0</code> – <code>1.0</code>. Set to <code>"fallthrough"</code> to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {number|string} metallic - The metallicness, <code>0.0</code> – <code>1.0</code>. Set to <code>"fallthrough"</code> to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {number|string} scattering - The scattering, <code>0.0</code> – <code>1.0</code>. Set to <code>"fallthrough"</code> to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {string} emissiveMap - URL of emissive texture image. Set to <code>"fallthrough"</code> to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {string} albedoMap - URL of albedo texture image. Set to <code>"fallthrough"</code> to fallthrough to
- * the material below. "hifi_pbr" model only.
- * @property {string} opacityMap - URL of opacity texture image. Set value the same as the <code>albedoMap</code> value for
- * transparency. "hifi_pbr" model only.
- * @property {string} roughnessMap - URL of roughness texture image. Can use this or <code>glossMap</code>, but not both. Set to <code>"fallthrough"</code>
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} glossMap - URL of gloss texture image. Can use this or <code>roughnessMap</code>, but not both. Set to <code>"fallthrough"</code>
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} metallicMap - URL of metallic texture image. Can use this or <code>specularMap</code>, but not both. Set to <code>"fallthrough"</code>
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} specularMap - URL of specular texture image. Can use this or <code>metallicMap</code>, but not both. Set to <code>"fallthrough"</code>
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} normalMap - URL of normal texture image. Can use this or <code>bumpMap</code>, but not both. Set to <code>"fallthrough"</code>
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} bumpMap - URL of bump texture image. Can use this or <code>normalMap</code>, but not both. Set to <code>"fallthrough"</code>
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} occlusionMap - URL of occlusion texture image. Set to <code>"fallthrough"</code> to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} scatteringMap - URL of scattering texture image. Only used if <code>normalMap</code> or
- * <code>bumpMap</code> is specified. Set to <code>"fallthrough"</code> to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} lightMap - URL of light map texture image. <em>Currently not used.</em>. Set to <code>"fallthrough"</code>
- * 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
- * <code>"fallthrough"</code> 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 <code>"fallthrough"</code>
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {string} lightmapParams - Parameters for controlling how lightMap is used. Currently unused. Set to <code>"fallthrough"</code>
- * 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 <code>"fallthrough"</code>
- * to fallthrough to the material below. "hifi_pbr" model only.
- * @property {bool} defaultFallthrough=false - If <code>true</code>, all properties will fallthrough to the material below unless they are set. If
- * <code>false</code>, they will respect the individual properties' fallthrough state. "hifi_pbr" model only.
+ * be either RGB or sRGB.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {number|string} roughness - The roughness, range <code>0.0</code> – <code>1.0</code>.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {number|string} metallic - The metallicness, range <code>0.0</code> – <code>1.0</code>.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {number|string} scattering - The scattering, range <code>0.0</code> – <code>1.0</code>.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {string} emissiveMap - The URL of the emissive texture image.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {string} albedoMap - The URL of the albedo texture image.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {string} opacityMap - The URL of the opacity texture image. Set the value the same as the <code>albedoMap</code>
+ * value for transparency.
+ * <code>"hifi_pbr"</code> model only.
+ * @property {string} roughnessMap - The URL of the roughness texture image. You can use this or <code>glossMap</code>, but not
+ * both.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {string} glossMap - The URL of the gloss texture image. You can use this or <code>roughnessMap</code>, but not
+ * both.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {string} metallicMap - The URL of the metallic texture image. You can use this or <code>specularMap</code>, but
+ * not both.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {string} specularMap - The URL of the specular texture image. You can use this or <code>metallicMap</code>, but
+ * not both.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {string} normalMap - The URL of the normal texture image. You can use this or <code>bumpMap</code>, but not both.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {string} bumpMap - The URL of the bump texture image. You can use this or <code>normalMap</code>, but not both.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {string} occlusionMap - The URL of the occlusion texture image.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {string} scatteringMap - The URL of the scattering texture image. Only used if <code>normalMap</code> or
+ * <code>bumpMap</code> is specified.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {string} lightMap - The URL of the light map texture image.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {Mat4|string} texCoordTransform0 - The transform to use for all of the maps apart from <code>occlusionMap</code>
+ * and <code>lightMap</code>.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {Mat4|string} texCoordTransform1 - The transform to use for <code>occlusionMap</code> and <code>lightMap</code>.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {string} lightmapParams - Parameters for controlling how lightMap is used.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * <p><em>Currently not used.</em></p>
+ * @property {string} materialParams - Parameters for controlling the material projection and repetition.
+ * Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * <p><em>Currently not used.</em></p>
+ * @property {boolean} defaultFallthrough=false - If <code>true</code>, all properties fall through to the material below
+ * unless they are set. If <code>false</code>, they respect their individual fall-through setting. <code>"hifi_pbr"</code>
+ * model only.
*/
// Note: See MaterialEntityItem.h for default values used in practice.
std::pair<std::string, std::shared_ptr<NetworkMaterial>> NetworkMaterialResource::parseJSONMaterial(const QJsonObject& materialJSON, const QUrl& baseUrl) {
@@ -399,7 +410,7 @@ std::pair<std::string, std::shared_ptr<NetworkMaterial>> 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 +419,7 @@ std::pair<std::string, std::shared_ptr<NetworkMaterial>> 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/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 @@
* <tr><td><code>"none"</code></td><td>The entity will not be billboarded.</td></tr>
* <tr><td><code>"yaw"</code></td><td>The entity will yaw, but not pitch, to face the camera. Its actual rotation will be
* ignored.</td></tr>
- * <tr><td><code>"full"</code></td><td>The entity will be billboarded to face the camera. Its actual rotation will be
+ * <tr><td><code>"full"</code></td><td>The entity will yaw and pitch to face the camera. Its actual rotation will be
* ignored.</td></tr>
* </tbody>
* </table>
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
+ * <p>How an effect is applied in a {@link Entities.EntityProperties-Zone|Zone} entity.</p>
+ * <table>
+ * <thead>
+ * <tr><th>Value</th><th>Description</th></tr>
+ * </thead>
+ * <tbody>
+ * <tr><td><code>"inherit"</code></td><td>The effect from any enclosing zone continues into this zone.</td></tr>
+ * <tr><td><code>"disabled"</code></td><td>The effect — from any enclosing zone and this zone — is disabled in
+ * this zone.</td></tr>
+ * <tr><td><code>"enabled"</code></td><td>The effect from this zone is enabled, overriding the effect from any enclosing
+ * zone.</td></tr>
+ * </tbody>
+ * </table>
+ * @typedef {string} Entities.ComponentMode
+ */
const char* componentModeNames[] = {
"inherit",
"disabled",
@@ -22,6 +38,20 @@ QString ComponentModeHelpers::getNameForComponentMode(ComponentMode mode) {
return componentModeNames[(int)mode];
}
+/**jsdoc
+ * <p>The priority of updates from avatars in a zone to other clients.</p>
+ * <table>
+ * <thead>
+ * <tr><th>Value</th><th>Description</th></tr>
+ * </thead>
+ * <tbody>
+ * <tr><td><code>"inherit"</code></td><td>The update priority from any enclosing zone continues into this zone.</td></tr>
+ * <tr><td><code>"crowd"</code></td><td>The update priority in this zone is the normal priority.</td></tr>
+ * <tr><td><code>"hero"</code></td><td>Avatars in this zone have an increased update priority.</td></tr>
+ * </tbody>
+ * </table>
+ * @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
- * <p>Controls how the Gizmo behaves and renders</p>
+ * <p>A {@link Entities.EntityProperties-Gizmo|Gizmo} entity may be one of the following types:</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
- * <tr><td><code>ring</code></td><td>A ring gizmo.</td></tr>
+ * <tr><td><code>"ring"</code></td><td>A ring gizmo.</td></tr>
* </tbody>
* </table>
- * @typedef {string} GizmoType
+ * @typedef {string} Entities.GizmoType
*/
enum GizmoType {
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
- * <p>How the geometry of the entity is rendered.</p>
+ * <p>How the geometry of an entity is rendered.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
- * <tr><td><code>solid</code></td><td>The entity will be drawn as a solid shape.</td></tr>
- * <tr><td><code>lines</code></td><td>The entity will be drawn as wireframe.</td></tr>
+ * <tr><td><code>"solid"</code></td><td>The entity is drawn as a solid shape.</td></tr>
+ * <tr><td><code>"lines"</code></td><td>The entity is drawn as wireframe.</td></tr>
* </tbody>
* </table>
- * @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 @@
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
- * <tr><td><code>none</code></td><td>No pulsing.</td></tr>
- * <tr><td><code>in</code></td><td>Pulse in phase with the pulse period.</td></tr>
- * <tr><td><code>out</code></td><td>Pulse out of phase with the pulse period.</td></tr>
+ * <tr><td><code>"none"</code></td><td>No pulsing.</td></tr>
+ * <tr><td><code>"in"</code></td><td>Pulse in phase with the pulse period.</td></tr>
+ * <tr><td><code>"out"</code></td><td>Pulse out of phase with the pulse period.</td></tr>
* </tbody>
* </table>
- * @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 <code>0</code> - <code>255</code>. Synonyms: <code>r</code>, <code>x</code>.
-* @property {number} green - Green component value. Integer in the range <code>0</code> - <code>255</code>. Synonyms: <code>g</code>, <code>y</code>.
-* @property {number} blue - Blue component value. Integer in the range <code>0</code> - <code>255</code>. Synonyms: <code>b</code>, <code>z</code>.
-* @example <caption>Colors can be set in multiple ways and modified with their aliases, but still stringify in the same way</caption>
-* Entities.editEntity(<id>, { color: { x: 1, y: 2, z: 3 }}); // { red: 1, green: 2, blue: 3 }
-* Entities.editEntity(<id>, { color: { r: 4, g: 5, b: 6 }}); // { red: 4, green: 5, blue: 6 }
-* Entities.editEntity(<id>, { color: { red: 7, green: 8, blue: 9 }}); // { red: 7, green: 8, blue: 9 }
-* Entities.editEntity(<id>, { color: [10, 11, 12] }); // { red: 10, green: 11, blue: 12 }
-* Entities.editEntity(<id>, { color: 13 }); // { red: 13, green: 13, blue: 13 }
-* var color = Entities.getEntityProperties(<id>).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(<id>, { color: "red"}); // { red: 255, green: 0, blue: 0 }
-* Entities.editEntity(<id>, { 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 <code>0</code> - <code>255</code>. Synonyms: <code>r</code>, <code>x</code>.
+ * @property {number} green - Green component value. Integer in the range <code>0</code> - <code>255</code>. Synonyms: <code>g</code>, <code>y</code>.
+ * @property {number} blue - Blue component value. Integer in the range <code>0</code> - <code>255</code>. Synonyms: <code>b</code>, <code>z</code>.
+ * @example <caption>Colors can be set in multiple ways and modified with their aliases, but still stringify in the same way</caption>
+ * Entities.editEntity(<id>, { color: { x: 1, y: 2, z: 3 }}); // { red: 1, green: 2, blue: 3 }
+ * Entities.editEntity(<id>, { color: { r: 4, g: 5, b: 6 }}); // { red: 4, green: 5, blue: 6 }
+ * Entities.editEntity(<id>, { color: { red: 7, green: 8, blue: 9 }}); // { red: 7, green: 8, blue: 9 }
+ * Entities.editEntity(<id>, { color: [10, 11, 12] }); // { red: 10, green: 11, blue: 12 }
+ * Entities.editEntity(<id>, { color: 13 }); // { red: 13, green: 13, blue: 13 }
+ * var color = Entities.getEntityProperties(<id>).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(<id>, { color: "red"}); // { red: 255, green: 0, blue: 0 }
+ * Entities.editEntity(<id>, { 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 <code>0</code> - <code>255</code>. Synonyms: <code>r</code>, <code>x</code>.
-* @property {number} green - Green component value. Real in the range <code>0</code> - <code>255</code>. Synonyms: <code>g</code>, <code>y</code>.
-* @property {number} blue - Blue component value. Real in the range <code>0</code> - <code>255</code>. Synonyms: <code>b</code>, <code>z</code>.
-* @example <caption>ColorFloats can be set in multiple ways and modified with their aliases, but still stringify in the same way</caption>
-* Entities.editEntity(<id>, { color: { x: 1, y: 2, z: 3 }}); // { red: 1, green: 2, blue: 3 }
-* Entities.editEntity(<id>, { color: { r: 4, g: 5, b: 6 }}); // { red: 4, green: 5, blue: 6 }
-* Entities.editEntity(<id>, { color: { red: 7, green: 8, blue: 9 }}); // { red: 7, green: 8, blue: 9 }
-* Entities.editEntity(<id>, { color: [10, 11, 12] }); // { red: 10, green: 11, blue: 12 }
-* Entities.editEntity(<id>, { color: 13 }); // { red: 13, green: 13, blue: 13 }
-* var color = Entities.getEntityProperties(<id>).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(<id>, { color: "red"}); // { red: 255, green: 0, blue: 0 }
-* Entities.editEntity(<id>, { color: "#00FF00"}); // { red: 0, green: 255, blue: 0 }
-*/
+ * A color vector with real values. Values may also be <code>null</code>. See also the {@link Vec3(0)|Vec3} object.
+ *
+ * @typedef {object} ColorFloat
+ * @property {number} red - Red component value. Real in the range <code>0</code> - <code>255</code>. Synonyms: <code>r</code>, <code>x</code>.
+ * @property {number} green - Green component value. Real in the range <code>0</code> - <code>255</code>. Synonyms: <code>g</code>, <code>y</code>.
+ * @property {number} blue - Blue component value. Real in the range <code>0</code> - <code>255</code>. Synonyms: <code>b</code>, <code>z</code>.
+ * @example <caption>ColorFloats can be set in multiple ways and modified with their aliases, but still stringify in the same way</caption>
+ * Entities.editEntity(<id>, { color: { x: 1, y: 2, z: 3 }}); // { red: 1, green: 2, blue: 3 }
+ * Entities.editEntity(<id>, { color: { r: 4, g: 5, b: 6 }}); // { red: 4, green: 5, blue: 6 }
+ * Entities.editEntity(<id>, { color: { red: 7, green: 8, blue: 9 }}); // { red: 7, green: 8, blue: 9 }
+ * Entities.editEntity(<id>, { color: [10, 11, 12] }); // { red: 10, green: 11, blue: 12 }
+ * Entities.editEntity(<id>, { color: 13 }); // { red: 13, green: 13, blue: 13 }
+ * var color = Entities.getEntityProperties(<id>).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(<id>, { color: "red"}); // { red: 255, green: 0, blue: 0 }
+ * Entities.editEntity(<id>, { 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
- * <p>In which layer an entity is rendered.</p>
+ * <p>A layer in which an entity may be rendered.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
- * <tr><td><code>world</code></td><td>The entity will be drawn in the world with everything else.</td></tr>
- * <tr><td><code>front</code></td><td>The entity will be drawn on top of the world layer, but behind the HUD sphere.</td></tr>
- * <tr><td><code>hud</code></td><td>The entity will be drawn on top of other layers and the HUD sphere.</td></tr>
+ * <tr><td><code>"world"</code></td><td>The entity is drawn in the world with everything else.</td></tr>
+ * <tr><td><code>"front"</code></td><td>The entity is drawn on top of the world layer but behind the HUD sphere.</td></tr>
+ * <tr><td><code>"hud"</code></td><td>The entity is drawn on top of other layers and the HUD sphere.</td></tr>
* </tbody>
* </table>
- * @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
- * <p>A ShapeType defines the shape used for collisions or zones.</p>
+ * <p>Defines the shape used for collisions or zones.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
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
- * <p>Controls how the web surface processed PointerEvents</p>
+ * <p>Specifies how a web surface processes events.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
- * <tr><td><code>touch</code></td><td>Events are processed as touch events.</td></tr>
- * <tr><td><code>mouse</code></td><td>Events are processed as mouse events.</td></tr>
+ * <tr><td><code>"touch"</code></td><td>Events are processed as touch events.</td></tr>
+ * <tr><td><code>"mouse"</code></td><td>Events are processed as mouse events.</td></tr>
* </tbody>
* </table>
* @typedef {string} WebInputMode