From 351bb3b9349d15307c0d798d2e63015399b5934f Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Fri, 7 Jun 2019 14:58:35 +1200
Subject: [PATCH 01/13] Fix JSDoc naming of some Test API functions
---
interface/src/scripting/TestScriptingInterface.h | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/interface/src/scripting/TestScriptingInterface.h b/interface/src/scripting/TestScriptingInterface.h
index 897f955a74..dffda3ece0 100644
--- a/interface/src/scripting/TestScriptingInterface.h
+++ b/interface/src/scripting/TestScriptingInterface.h
@@ -165,14 +165,14 @@ public slots:
/**jsdoc
* Set number of cycles texture size is required to be stable
- * @function Entities.setMinimumGPUTextureMemStabilityCount
+ * @function Test.setMinimumGPUTextureMemStabilityCount
* @param {number} count - Number of cycles to wait
*/
Q_INVOKABLE void setMinimumGPUTextureMemStabilityCount(int count);
/**jsdoc
* Check whether all textures have been loaded.
- * @function Entities.isTextureLoadingComplete
+ * @function Test.isTextureLoadingComplete
* @returns {boolean} <code>true</code> texture memory usage is not increasing
*/
Q_INVOKABLE bool isTextureLoadingComplete();
From b16086de74eb92e9450bdf13bae9878837c29246 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Sat, 15 Jun 2019 10:22:14 +1200
Subject: [PATCH 02/13] Revise JSDoc for key Entities methods plus entity
properties
---
.../entities/src/AmbientLightPropertyGroup.h | 2 +-
.../entities/src/AnimationPropertyGroup.cpp | 8 +-
libraries/entities/src/BloomPropertyGroup.h | 3 +-
.../entities/src/EntityItemProperties.cpp | 572 ++++++++++--------
.../entities/src/EntityScriptingInterface.h | 94 +--
libraries/entities/src/EntityTypes.h | 10 +-
libraries/entities/src/GrabPropertyGroup.h | 31 +-
libraries/entities/src/HazePropertyGroup.h | 12 +-
.../entities/src/KeyLightPropertyGroup.h | 2 +-
libraries/entities/src/PolyVoxEntityItem.h | 2 +-
libraries/entities/src/PulsePropertyGroup.h | 8 +-
.../entities/src/RingGizmoPropertyGroup.h | 43 +-
libraries/entities/src/ShapeEntityItem.cpp | 4 +-
libraries/entities/src/SkyboxPropertyGroup.h | 2 +-
.../src/material-networking/MaterialCache.cpp | 121 ++--
libraries/shared/src/BillboardMode.h | 2 +-
libraries/shared/src/ComponentMode.cpp | 30 +
libraries/shared/src/GizmoType.h | 6 +-
libraries/shared/src/PrimitiveMode.h | 8 +-
libraries/shared/src/PulseMode.h | 8 +-
libraries/shared/src/RegisteredMetaTypes.h | 72 +--
libraries/shared/src/RenderLayer.h | 10 +-
libraries/shared/src/ShapeInfo.cpp | 2 +-
libraries/shared/src/WebInputMode.h | 6 +-
24 files changed, 580 insertions(+), 478 deletions(-)
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
From 9c752c9964c709a5b9b471cbe35e7fe8c03b3af5 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Sat, 15 Jun 2019 11:07:40 +1200
Subject: [PATCH 03/13] Fix up descriptions in EntityType table
---
libraries/entities/src/EntityTypes.h | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/libraries/entities/src/EntityTypes.h b/libraries/entities/src/EntityTypes.h
index 55ad2d9561..8fdc752cac 100644
--- a/libraries/entities/src/EntityTypes.h
+++ b/libraries/entities/src/EntityTypes.h
@@ -59,13 +59,13 @@ 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>"Model"</code></td><td>A mesh model from an FBX or OBJ file.</td>
+ * <tr><td><code>"Model"</code></td><td>A mesh model from a glTf, 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>
* <td>{@link Entities.EntityProperties-Text|EntityProperties-Text}</td></tr>
* <tr><td><code>"Image"</code></td><td>An image oriented in space.</td>
* <td>{@link Entities.EntityProperties-Image|EntityProperties-Image}</td></tr>
- * <tr><td><code>"Web"</code></td><td>A browsable Web page.</td>
+ * <tr><td><code>"Web"</code></td><td>A browsable web page.</td>
* <td>{@link Entities.EntityProperties-Web|EntityProperties-Web}</td></tr>
* <tr><td><code>"ParticleEffect"</code></td><td>A particle system that can be used to simulate things such as fire,
* smoke, snow, magic spells, etc.</td>
From 23785b5406428fa9ae6f54db48932cedeba5cf31 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Sat, 15 Jun 2019 14:06:49 +1200
Subject: [PATCH 04/13] Regularize links to individual entity types
---
.../entities/src/EntityItemProperties.cpp | 12 +-
.../entities/src/EntityScriptingInterface.h | 182 +++++++++---------
.../entities/src/KeyLightPropertyGroup.h | 2 +-
3 files changed, 99 insertions(+), 97 deletions(-)
diff --git a/libraries/entities/src/EntityItemProperties.cpp b/libraries/entities/src/EntityItemProperties.cpp
index a9ca5b8a9d..05072ac99e 100644
--- a/libraries/entities/src/EntityItemProperties.cpp
+++ b/libraries/entities/src/EntityItemProperties.cpp
@@ -608,9 +608,9 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
}
/**jsdoc
- * 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.
+ * Different entity types have different properties: some common to all entities (listed in the table) 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>
@@ -648,9 +648,9 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* entity's properties other than <code>locked</code> cannot be changed, and the entity cannot be deleted.
* @property {boolean} visible=true - Whether or not the entity is rendered. If <code>true</code> then the entity is rendered.
* @property {boolean} canCastShadow=true - Whether or not the entity can cast a shadow. Currently applicable only to
- * {@link Entities.EntityType|Model} and {@link Entities.EntityType|Shape} entities. Shadows are cast if inside a
- * {@link Entities.EntityType|Zone} entity with <code>castShadows</code> enabled in its
- * {@link Entities.EntityProperties-Zone|keyLight} property.
+ * {@link Entities.EntityProperties-Model|Model} and {@link Entities.EntityProperties-Shape|Shape} entities. Shadows are
+ * cast if inside a {@link Entities.EntityProperties-Zone|Zone} entity with <code>castShadows</code> enabled in its
+ * <code>keyLight</code> property.
* @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.
diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h
index a10c59e38b..bad619a5ad 100644
--- a/libraries/entities/src/EntityScriptingInterface.h
+++ b/libraries/entities/src/EntityScriptingInterface.h
@@ -117,9 +117,9 @@ public:
* @hifi-server-entity
* @hifi-assignment-client
*
- * @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.
+ * @property {Uuid} keyboardFocusEntity - The {@link Entities.EntityProperties-Web|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 {
@@ -658,70 +658,72 @@ public slots:
/**jsdoc
- * Set whether or not ray picks intersect the bounding box of {@link Entities.EntityType|Light} entities. By default, Light
- * entities are not intersected. The setting lasts for the Interface session. Ray picks are done using
+ * Set whether or not ray picks intersect the bounding box of {@link Entities.EntityProperties-Light|Light} entities. By
+ * default, Light entities are not intersected. The setting lasts for the Interface session. Ray picks are done using
* {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
* @function Entities.setLightsArePickable
* @param {boolean} value - Set <code>true</code> to make ray picks intersect the bounding box of
- * {@link Entities.EntityType|Light} entities, otherwise <code>false</code>.
+ * {@link Entities.EntityProperties-Light|Light} entities, otherwise <code>false</code>.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE void setLightsArePickable(bool value);
/**jsdoc
- * Get whether or not ray picks intersect the bounding box of {@link Entities.EntityType|Light} entities. Ray picks are
- * done using {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
+ * Get whether or not ray picks intersect the bounding box of {@link Entities.EntityProperties-Light|Light} entities. Ray
+ * picks are done using {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
* @function Entities.getLightsArePickable
- * @returns {boolean} <code>true</code> if ray picks intersect the bounding box of {@link Entities.EntityType|Light}
- * entities, otherwise <code>false</code>.
+ * @returns {boolean} <code>true</code> if ray picks intersect the bounding box of
+ * {@link Entities.EntityProperties-Light|Light} entities, otherwise <code>false</code>.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE bool getLightsArePickable() const;
/**jsdoc
- * Set whether or not ray picks intersect the bounding box of {@link Entities.EntityType|Zone} entities. By default, Light
- * entities are not intersected. The setting lasts for the Interface session. Ray picks are done using
- * {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
+ * Set whether or not ray picks intersect the bounding box of {@link Entities.EntityProperties-Zone|Zone} entities. By
+ * default, Light entities are not intersected. The setting lasts for the Interface session. Ray picks are done using
+ * {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
* @function Entities.setZonesArePickable
* @param {boolean} value - Set <code>true</code> to make ray picks intersect the bounding box of
- * {@link Entities.EntityType|Zone} entities, otherwise <code>false</code>.
+ * {@link Entities.EntityProperties-Zone|Zone} entities, otherwise <code>false</code>.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE void setZonesArePickable(bool value);
/**jsdoc
- * Get whether or not ray picks intersect the bounding box of {@link Entities.EntityType|Zone} entities. Ray picks are
- * done using {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
+ * Get whether or not ray picks intersect the bounding box of {@link Entities.EntityProperties-Zone|Zone} entities. Ray
+ * picks are done using {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
* @function Entities.getZonesArePickable
- * @returns {boolean} <code>true</code> if ray picks intersect the bounding box of {@link Entities.EntityType|Zone}
- * entities, otherwise <code>false</code>.
+ * @returns {boolean} <code>true</code> if ray picks intersect the bounding box of
+ * {@link Entities.EntityProperties-Zone|Zone} entities, otherwise <code>false</code>.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE bool getZonesArePickable() const;
/**jsdoc
- * Set whether or not {@link Entities.EntityType|Zone} entities' boundaries should be drawn. <em>Currently not used.</em>
+ * Set whether or not {@link Entities.EntityProperties-Zone|Zone} entities' boundaries should be drawn. <em>Currently not
+ * used.</em>
* @function Entities.setDrawZoneBoundaries
- * @param {boolean} value - Set to <code>true</code> if {@link Entities.EntityType|Zone} entities' boundaries should be
- * drawn, otherwise <code>false</code>.
+ * @param {boolean} value - Set to <code>true</code> if {@link Entities.EntityProperties-Zone|Zone} entities' boundaries
+ * should be drawn, otherwise <code>false</code>.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE void setDrawZoneBoundaries(bool value);
/**jsdoc
- * Get whether or not {@link Entities.EntityType|Zone} entities' boundaries should be drawn. <em>Currently not used.</em>
- * @function Entities.getDrawZoneBoundaries
- * @returns {boolean} <code>true</code> if {@link Entities.EntityType|Zone} entities' boundaries should be drawn,
- * otherwise <code>false</code>.
- */
+ * Get whether or not {@link Entities.EntityProperties-Zone|Zone} entities' boundaries should be drawn. <em>Currently
+ * not used.</em>
+ * @function Entities.getDrawZoneBoundaries
+ * @returns {boolean} <code>true</code> if {@link Entities.EntityProperties-Zone|Zone} entities' boundaries should be
+ * drawn, otherwise <code>false</code>.
+ */
// FIXME move to a renderable entity interface
Q_INVOKABLE bool getDrawZoneBoundaries() const;
/**jsdoc
- * Set the values of all voxels in a spherical portion of a {@link Entities.EntityType|PolyVox} entity.
+ * Set the values of all voxels in a spherical portion of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @function Entities.setVoxelSphere
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} center - The center of the sphere of voxels to set, in world coordinates.
* @param {number} radius - The radius of the sphere of voxels to set, in world coordinates.
* @param {number} value - If <code>value % 256 == 0</code> then each voxel is cleared, otherwise each voxel is set.
@@ -740,9 +742,9 @@ public slots:
Q_INVOKABLE bool setVoxelSphere(const QUuid& entityID, const glm::vec3& center, float radius, int value);
/**jsdoc
- * Set the values of all voxels in a capsule-shaped portion of a {@link Entities.EntityType|PolyVox} entity.
+ * Set the values of all voxels in a capsule-shaped portion of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @function Entities.setVoxelCapsule
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} start - The center of the sphere of voxels to set, in world coordinates.
* @param {Vec3} end - The center of the sphere of voxels to set, in world coordinates.
* @param {number} radius - The radius of the capsule cylinder and spherical ends, in world coordinates.
@@ -764,9 +766,9 @@ public slots:
Q_INVOKABLE bool setVoxelCapsule(const QUuid& entityID, const glm::vec3& start, const glm::vec3& end, float radius, int value);
/**jsdoc
- * Set the value of a particular voxels in a {@link Entities.EntityType|PolyVox} entity.
+ * Set the value of a particular voxels in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @function Entities.setVoxel
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} position - The position relative to the minimum axes values corner of the entity. The
* <code>position</code> coordinates are rounded to the nearest integer to get the voxel coordinate. The minimum axes
* corner voxel is <code>{ x: 0, y: 0, z: 0 }</code>.
@@ -786,9 +788,9 @@ public slots:
Q_INVOKABLE bool setVoxel(const QUuid& entityID, const glm::vec3& position, int value);
/**jsdoc
- * Set the values of all voxels in a {@link Entities.EntityType|PolyVox} entity.
+ * Set the values of all voxels in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @function Entities.setAllVoxels
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {number} value - If <code>value % 256 == 0</code> then each voxel is cleared, otherwise each voxel is set.
* @example <caption>Create a PolyVox cube.</caption>
* var entity = Entities.addEntity({
@@ -804,9 +806,9 @@ public slots:
Q_INVOKABLE bool setAllVoxels(const QUuid& entityID, int value);
/**jsdoc
- * Set the values of all voxels in a cubic portion of a {@link Entities.EntityType|PolyVox} entity.
+ * Set the values of all voxels in a cubic portion of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @function Entities.setVoxelsInCuboid
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} lowPosition - The position of the minimum axes value corner of the cube of voxels to set, in voxel
* coordinates.
* @param {Vec3} cuboidSize - The size of the cube of voxels to set, in voxel coordinates.
@@ -829,14 +831,14 @@ public slots:
Q_INVOKABLE bool setVoxelsInCuboid(const QUuid& entityID, const glm::vec3& lowPosition, const glm::vec3& cuboidSize, int value);
/**jsdoc
- * Convert voxel coordinates in a {@link Entities.EntityType|PolyVox} entity to world coordinates. Voxel coordinates are
+ * Convert voxel coordinates in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity to world coordinates. Voxel coordinates are
* relative to the minimum axes values corner of the entity with a scale of <code>Vec3.ONE</code> being the dimensions of
* each voxel.
* @function Entities.voxelCoordsToWorldCoords
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} voxelCoords - The voxel coordinates. May be fractional and outside the entity's bounding box.
* @returns {Vec3} The world coordinates of the <code>voxelCoords</code> if the <code>entityID</code> is a
- * {@link Entities.EntityType|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}.
+ * {@link Entities.EntityProperties-PolyVox|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}.
* @example <caption>Create a PolyVox cube with the 0,0,0 voxel replaced by a sphere.</caption>
* // Cube PolyVox with 0,0,0 voxel missing.
* var polyVox = Entities.addEntity({
@@ -864,26 +866,26 @@ public slots:
Q_INVOKABLE glm::vec3 voxelCoordsToWorldCoords(const QUuid& entityID, glm::vec3 voxelCoords);
/**jsdoc
- * Convert world coordinates to voxel coordinates in a {@link Entities.EntityType|PolyVox} entity. Voxel coordinates are
+ * Convert world coordinates to voxel coordinates in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity. Voxel coordinates are
* relative to the minimum axes values corner of the entity, with a scale of <code>Vec3.ONE</code> being the dimensions of
* each voxel.
* @function Entities.worldCoordsToVoxelCoords
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} worldCoords - The world coordinates. May be outside the entity's bounding box.
* @returns {Vec3} The voxel coordinates of the <code>worldCoords</code> if the <code>entityID</code> is a
- * {@link Entities.EntityType|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}. The value may be fractional.
+ * {@link Entities.EntityProperties-PolyVox|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}. The value may be fractional.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE glm::vec3 worldCoordsToVoxelCoords(const QUuid& entityID, glm::vec3 worldCoords);
/**jsdoc
- * Convert voxel coordinates in a {@link Entities.EntityType|PolyVox} entity to local coordinates relative to the minimum
+ * Convert voxel coordinates in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity to local coordinates relative to the minimum
* axes value corner of the entity, with the scale being the same as world coordinates.
* @function Entities.voxelCoordsToLocalCoords
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} voxelCoords - The voxel coordinates. May be fractional and outside the entity's bounding box.
* @returns {Vec3} The local coordinates of the <code>voxelCoords</code> if the <code>entityID</code> is a
- * {@link Entities.EntityType|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}.
+ * {@link Entities.EntityProperties-PolyVox|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}.
* @example <caption>Get the world dimensions of a voxel in a PolyVox entity.</caption>
* var polyVox = Entities.addEntity({
* type: "PolyVox",
@@ -899,24 +901,24 @@ public slots:
Q_INVOKABLE glm::vec3 voxelCoordsToLocalCoords(const QUuid& entityID, glm::vec3 voxelCoords);
/**jsdoc
- * Convert local coordinates to voxel coordinates in a {@link Entities.EntityType|PolyVox} entity. Local coordinates are
+ * Convert local coordinates to voxel coordinates in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity. Local coordinates are
* relative to the minimum axes value corner of the entity, with the scale being the same as world coordinates.
* @function Entities.localCoordsToVoxelCoords
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} localCoords - The local coordinates. May be outside the entity's bounding box.
* @returns {Vec3} The voxel coordinates of the <code>worldCoords</code> if the <code>entityID</code> is a
- * {@link Entities.EntityType|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}. The value may be fractional.
+ * {@link Entities.EntityProperties-PolyVox|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}. The value may be fractional.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE glm::vec3 localCoordsToVoxelCoords(const QUuid& entityID, glm::vec3 localCoords);
/**jsdoc
- * Set the <code>linePoints</code> property of a {@link Entities.EntityType|Line} entity.
+ * Set the <code>linePoints</code> property of a {@link Entities.EntityProperties-Line|Line} entity.
* @function Entities.setAllPoints
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|Line} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-Line|Line} entity.
* @param {Vec3[]} points - The array of points to set the entity's <code>linePoints</code> property to.
* @returns {boolean} <code>true</code> if the entity's property was updated, otherwise <code>false</code>. The property
- * may fail to be updated if the entity does not exist, the entity is not a {@link Entities.EntityType|Line} entity,
+ * may fail to be updated if the entity does not exist, the entity is not a {@link Entities.EntityProperties-Line|Line} entity,
* one of the points is outside the entity's dimensions, or the number of points is greater than the maximum allowed.
* @example <caption>Change the shape of a Line entity.</caption>
* // Draw a horizontal line between two points.
@@ -945,12 +947,12 @@ public slots:
Q_INVOKABLE bool setAllPoints(const QUuid& entityID, const QVector<glm::vec3>& points);
/**jsdoc
- * Append a point to a {@link Entities.EntityType|Line} entity.
+ * Append a point to a {@link Entities.EntityProperties-Line|Line} entity.
* @function Entities.appendPoint
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|Line} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-Line|Line} entity.
* @param {Vec3} point - The point to add to the line. The coordinates are relative to the entity's position.
* @returns {boolean} <code>true</code> if the point was added to the line, otherwise <code>false</code>. The point may
- * fail to be added if the entity does not exist, the entity is not a {@link Entities.EntityType|Line} entity, the
+ * fail to be added if the entity does not exist, the entity is not a {@link Entities.EntityProperties-Line|Line} entity, the
* point is outside the entity's dimensions, or the maximum number of points has been reached.
* @example <caption>Append a point to a Line entity.</caption>
* // Draw a line between two points.
@@ -1045,13 +1047,13 @@ public slots:
/**jsdoc
- * Get the translation of a joint in a {@link Entities.EntityType|Model} entity relative to the entity's position and
+ * Get the translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity relative to the entity's position and
* orientation.
* @function Entities.getAbsoluteJointTranslationInObjectFrame
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
* @returns {Vec3} The translation of the joint relative to the entity's position and orientation if the entity is a
- * {@link Entities.EntityType|Model} entity, the entity is loaded, and the joint index is valid; otherwise
+ * {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded, and the joint index is valid; otherwise
* <code>{@link Vec3(0)|Vec3.ZERO}</code>.
*/
// FIXME move to a renderable entity interface
@@ -1067,13 +1069,13 @@ public slots:
Q_INVOKABLE int getJointParent(const QUuid& entityID, int index);
/**jsdoc
- * Get the translation of a joint in a {@link Entities.EntityType|Model} entity relative to the entity's position and
+ * Get the translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity relative to the entity's position and
* orientation.
* @function Entities.getAbsoluteJointRotationInObjectFrame
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
* @returns {Quat} The rotation of the joint relative to the entity's orientation if the entity is a
- * {@link Entities.EntityType|Model} entity, the entity is loaded, and the joint index is valid; otherwise
+ * {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded, and the joint index is valid; otherwise
* <code>{@link Quat(0)|Quat.IDENTITY}</code>.
* @example <caption>Compare the local and absolute rotations of an avatar model's left hand joint.</caption>
* entityID = Entities.addEntity({
@@ -1097,13 +1099,13 @@ public slots:
Q_INVOKABLE glm::quat getAbsoluteJointRotationInObjectFrame(const QUuid& entityID, int jointIndex);
/**jsdoc
- * Set the translation of a joint in a {@link Entities.EntityType|Model} entity relative to the entity's position and
+ * Set the translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity relative to the entity's position and
* orientation.
* @function Entities.setAbsoluteJointTranslationInObjectFrame
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
* @param {Vec3} translation - The translation to set the joint to relative to the entity's position and orientation.
- * @returns {boolean} <code>true</code>if the entity is a {@link Entities.EntityType|Model} entity, the entity is loaded,
+ * @returns {boolean} <code>true</code>if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded,
* the joint index is valid, and the translation is different to the joint's current translation; otherwise
* <code>false</code>.
*/
@@ -1111,13 +1113,13 @@ public slots:
Q_INVOKABLE bool setAbsoluteJointTranslationInObjectFrame(const QUuid& entityID, int jointIndex, glm::vec3 translation);
/**jsdoc
- * Set the rotation of a joint in a {@link Entities.EntityType|Model} entity relative to the entity's position and
+ * Set the rotation of a joint in a {@link Entities.EntityProperties-Model|Model} entity relative to the entity's position and
* orientation.
* @function Entities.setAbsoluteJointRotationInObjectFrame
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
* @param {Quat} rotation - The rotation to set the joint to relative to the entity's orientation.
- * @returns {boolean} <code>true</code> if the entity is a {@link Entities.EntityType|Model} entity, the entity is loaded,
+ * @returns {boolean} <code>true</code> if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded,
* the joint index is valid, and the rotation is different to the joint's current rotation; otherwise <code>false</code>.
* @example <caption>Raise an avatar model's left palm.</caption>
* entityID = Entities.addEntity({
@@ -1142,22 +1144,22 @@ public slots:
/**jsdoc
- * Get the local translation of a joint in a {@link Entities.EntityType|Model} entity.
+ * Get the local translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.getLocalJointTranslation
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
- * @returns {Vec3} The local translation of the joint if the entity is a {@link Entities.EntityType|Model} entity, the
+ * @returns {Vec3} The local translation of the joint if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the
* entity is loaded, and the joint index is valid; otherwise <code>{@link Vec3(0)|Vec3.ZERO}</code>.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE glm::vec3 getLocalJointTranslation(const QUuid& entityID, int jointIndex);
/**jsdoc
- * Get the local rotation of a joint in a {@link Entities.EntityType|Model} entity.
+ * Get the local rotation of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.getLocalJointRotation
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
- * @returns {Quat} The local rotation of the joint if the entity is a {@link Entities.EntityType|Model} entity, the entity
+ * @returns {Quat} The local rotation of the joint if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
* is loaded, and the joint index is valid; otherwise <code>{@link Quat(0)|Quat.IDENTITY}</code>.
* @example <caption>Report the local rotation of an avatar model's head joint.</caption>
* entityID = Entities.addEntity({
@@ -1179,12 +1181,12 @@ public slots:
Q_INVOKABLE glm::quat getLocalJointRotation(const QUuid& entityID, int jointIndex);
/**jsdoc
- * Set the local translation of a joint in a {@link Entities.EntityType|Model} entity.
+ * Set the local translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.setLocalJointTranslation
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
* @param {Vec3} translation - The local translation to set the joint to.
- * @returns {boolean} <code>true</code>if the entity is a {@link Entities.EntityType|Model} entity, the entity is loaded,
+ * @returns {boolean} <code>true</code>if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded,
* the joint index is valid, and the translation is different to the joint's current translation; otherwise
* <code>false</code>.
*/
@@ -1192,12 +1194,12 @@ public slots:
Q_INVOKABLE bool setLocalJointTranslation(const QUuid& entityID, int jointIndex, glm::vec3 translation);
/**jsdoc
- * Set the local rotation of a joint in a {@link Entities.EntityType|Model} entity.
+ * Set the local rotation of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.setLocalJointRotation
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
* @param {Quat} rotation - The local rotation to set the joint to.
- * @returns {boolean} <code>true</code> if the entity is a {@link Entities.EntityType|Model} entity, the entity is loaded,
+ * @returns {boolean} <code>true</code> if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded,
* the joint index is valid, and the rotation is different to the joint's current rotation; otherwise <code>false</code>.
* @example <caption>Make an avatar model turn its head left.</caption>
* entityID = Entities.addEntity({
@@ -1221,11 +1223,11 @@ public slots:
/**jsdoc
- * Set the local translations of joints in a {@link Entities.EntityType|Model} entity.
+ * Set the local translations of joints in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.setLocalJointTranslations
* @param {Uuid} entityID - The ID of the entity.
* @param {Vec3[]} translations - The local translations to set the joints to.
- * @returns {boolean} <code>true</code>if the entity is a {@link Entities.EntityType|Model} entity, the entity is loaded,
+ * @returns {boolean} <code>true</code>if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded,
* the model has joints, and at least one of the translations is different to the model's current translations;
* otherwise <code>false</code>.
*/
@@ -1233,11 +1235,11 @@ public slots:
Q_INVOKABLE bool setLocalJointTranslations(const QUuid& entityID, const QVector<glm::vec3>& translations);
/**jsdoc
- * Set the local rotations of joints in a {@link Entities.EntityType|Model} entity.
+ * Set the local rotations of joints in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.setLocalJointRotations
* @param {Uuid} entityID - The ID of the entity.
* @param {Quat[]} rotations - The local rotations to set the joints to.
- * @returns {boolean} <code>true</code> if the entity is a {@link Entities.EntityType|Model} entity, the entity is loaded,
+ * @returns {boolean} <code>true</code> if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded,
* the model has joints, and at least one of the rotations is different to the model's current rotations; otherwise
* <code>false</code>.
* @example <caption>Raise both palms of an avatar model.</caption>
@@ -1275,14 +1277,14 @@ public slots:
Q_INVOKABLE bool setLocalJointRotations(const QUuid& entityID, const QVector<glm::quat>& rotations);
/**jsdoc
- * Set the local rotations and translations of joints in a {@link Entities.EntityType|Model} entity. This is the same as
+ * Set the local rotations and translations of joints in a {@link Entities.EntityProperties-Model|Model} entity. This is the same as
* calling both {@link Entities.setLocalJointRotations|setLocalJointRotations} and
* {@link Entities.setLocalJointTranslations|setLocalJointTranslations} at the same time.
* @function Entities.setLocalJointsData
* @param {Uuid} entityID - The ID of the entity.
* @param {Quat[]} rotations - The local rotations to set the joints to.
* @param {Vec3[]} translations - The local translations to set the joints to.
- * @returns {boolean} <code>true</code> if the entity is a {@link Entities.EntityType|Model} entity, the entity is loaded,
+ * @returns {boolean} <code>true</code> if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded,
* the model has joints, and at least one of the rotations or translations is different to the model's current values;
* otherwise <code>false</code>.
*/
@@ -1293,11 +1295,11 @@ public slots:
/**jsdoc
- * Get the index of a named joint in a {@link Entities.EntityType|Model} entity.
+ * Get the index of a named joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.getJointIndex
* @param {Uuid} entityID - The ID of the entity.
* @param {string} name - The name of the joint.
- * @returns {number} The integer index of the joint if the entity is a {@link Entities.EntityType|Model} entity, the entity
+ * @returns {number} The integer index of the joint if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
* is loaded, and the joint is present; otherwise <code>-1</code>. The joint indexes are in order per
* {@link Entities.getJointNames|getJointNames}.
* @example <caption>Report the index of a model's head joint.</caption>
@@ -1319,10 +1321,10 @@ public slots:
Q_INVOKABLE int getJointIndex(const QUuid& entityID, const QString& name);
/**jsdoc
- * Get the names of all the joints in a {@link Entities.EntityType|Model} entity.
+ * Get the names of all the joints in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.getJointNames
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|Model} entity.
- * @returns {string[]} The names of all the joints in the entity if it is a {@link Entities.EntityType|Model} entity and
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-Model|Model} entity.
+ * @returns {string[]} The names of all the joints in the entity if it is a {@link Entities.EntityProperties-Model|Model} entity and
* is loaded, otherwise an empty array. The joint names are in order per {@link Entities.getJointIndex|getJointIndex}.
* @example <caption>Report a model's joint names.</caption>
* entityID = Entities.addEntity({
@@ -1456,16 +1458,16 @@ public slots:
Q_INVOKABLE QString getNestableType(const QUuid& id);
/**jsdoc
- * Gets the ID of the {@link Entities.EntityType|Web} entity that has keyboard focus.
+ * Gets the ID of the {@link Entities.EntityProperties-Web|Web} entity that has keyboard focus.
* @function Entities.getKeyboardFocusEntity
- * @returns {Uuid} The ID of the {@link Entities.EntityType|Web} entity that has focus, if any, otherwise <code>null</code>.
+ * @returns {Uuid} The ID of the {@link Entities.EntityProperties-Web|Web} entity that has focus, if any, otherwise <code>null</code>.
*/
Q_INVOKABLE QUuid getKeyboardFocusEntity() const;
/**jsdoc
- * Sets the {@link Entities.EntityType|Web} entity that has keyboard focus.
+ * Sets the {@link Entities.EntityProperties-Web|Web} entity that has keyboard focus.
* @function Entities.setKeyboardFocusEntity
- * @param {Uuid} id - The ID of the {@link Entities.EntityType|Web} entity to set keyboard focus to. Use
+ * @param {Uuid} id - The ID of the {@link Entities.EntityProperties-Web|Web} entity to set keyboard focus to. Use
* <code>null</code> or {@link Uuid(0)|Uuid.NULL} to unset keyboard focus from an entity.
*/
Q_INVOKABLE void setKeyboardFocusEntity(const QUuid& id);
@@ -1543,8 +1545,8 @@ public slots:
Q_INVOKABLE void sendHoverLeaveEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Check whether an entity wants hand controller pointer events. For example, a {@link Entities.EntityType|Web} entity does
- * but a {@link Entities.EntityType|Shape} entity doesn't.
+ * Check whether an entity wants hand controller pointer events. For example, a {@link Entities.EntityProperties-Web|Web} entity does
+ * but a {@link Entities.EntityProperties-Shape|Shape} entity doesn't.
* @function Entities.wantsHandControllerPointerEvents
* @param {Uuid} entityID - The ID of the entity.
* @returns {boolean} <code>true</code> if the entity can be found and it wants hand controller pointer events, otherwise
@@ -1553,9 +1555,9 @@ public slots:
Q_INVOKABLE bool wantsHandControllerPointerEvents(const QUuid& id);
/**jsdoc
- * Send a script event over a {@link Entities.EntityType|Web} entity's <code>EventBridge</code> to the Web page's scripts.
+ * Send a script event over a {@link Entities.EntityProperties-Web|Web} entity's <code>EventBridge</code> to the Web page's scripts.
* @function Entities.emitScriptEvent
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityType|Web} entity.
+ * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-Web|Web} entity.
* @param {string} message - The message to send.
*/
Q_INVOKABLE void emitScriptEvent(const EntityItemID& entityID, const QVariant& message);
@@ -1574,7 +1576,7 @@ public slots:
const glm::vec3& start, const glm::vec3& end, float radius);
/**jsdoc
- * Get the meshes in a {@link Entities.EntityType|Model} or {@link Entities.EntityType|PolyVox} entity.
+ * Get the meshes in a {@link Entities.EntityProperties-Model|Model} or {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @function Entities.getMeshes
* @param {Uuid} entityID - The ID of the <code>Model</code> or <code>PolyVox</code> entity to get the meshes of.
* @param {Entities~getMeshesCallback} callback - The function to call upon completion.
diff --git a/libraries/entities/src/KeyLightPropertyGroup.h b/libraries/entities/src/KeyLightPropertyGroup.h
index d6246701a4..31e0cba1c6 100644
--- a/libraries/entities/src/KeyLightPropertyGroup.h
+++ b/libraries/entities/src/KeyLightPropertyGroup.h
@@ -34,7 +34,7 @@ class ReadBitstreamToTreeParams;
* @property {number} intensity=1 - The intensity of the light.
* @property {Vec3} direction=0,-1,0 - The direction the light is shining.
* @property {boolean} castShadows=false - If <code>true</code> then shadows are cast. Shadows are cast by avatars, plus
- * {@link Entities.EntityType|Model} and {@link Entities.EntityType|Shape} entities that have their
+ * {@link Entities.EntityProperties-Model|Model} and {@link Entities.EntityProperties-Shape|Shape} entities that have their
* <code>{@link Entities.EntityProperties|canCastShadow}</code> property set to <code>true</code>.
*/
class KeyLightPropertyGroup : public PropertyGroup {
From 72fdbc0aa81ecce4c1f9d947309009b779715f30 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Wed, 19 Jun 2019 10:18:48 +1200
Subject: [PATCH 05/13] Entity information and manipulation
---
interface/src/avatar/AvatarActionFarGrab.h | 9 +-
interface/src/avatar/AvatarActionHold.cpp | 4 +-
.../entities/src/EntityDynamicInterface.cpp | 82 ++--
.../entities/src/EntityItemProperties.cpp | 15 +-
.../entities/src/EntityScriptingInterface.h | 381 ++++++++++--------
libraries/physics/src/ObjectActionOffset.cpp | 2 +-
libraries/physics/src/ObjectActionTractor.cpp | 10 +-
.../src/ObjectActionTravelOriented.cpp | 2 +-
.../src/ObjectConstraintBallSocket.cpp | 4 +-
.../physics/src/ObjectConstraintConeTwist.cpp | 11 +-
.../physics/src/ObjectConstraintHinge.cpp | 13 +-
.../physics/src/ObjectConstraintSlider.cpp | 14 +-
libraries/physics/src/ObjectDynamic.cpp | 60 +--
libraries/shared/src/SpatiallyNestable.cpp | 15 +-
14 files changed, 350 insertions(+), 272 deletions(-)
diff --git a/interface/src/avatar/AvatarActionFarGrab.h b/interface/src/avatar/AvatarActionFarGrab.h
index 97d4a6bb03..c9b8f6ff3c 100644
--- a/interface/src/avatar/AvatarActionFarGrab.h
+++ b/interface/src/avatar/AvatarActionFarGrab.h
@@ -19,13 +19,15 @@
* The <code>"far-grab"</code> {@link Entities.ActionType|ActionType} moves and rotates an entity to a target position and
* orientation, optionally relative to another entity. Collisions between the entity and the user's avatar are disabled during
* the far-grab.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-FarGrab
+ * @property {Uuid} otherID=null - If an entity ID, the <code>targetPosition</code> and <code>targetRotation</code> are
+ * relative to the entity's position and rotation.
+ * @property {Uuid} otherJointIndex=null - If a joint index in the <code>otherID</code> entity, the <code>targetPosition</code>
+ * and <code>targetRotation</code> are relative to the entity joint's position and rotation.
* @property {Vec3} targetPosition=0,0,0 - The target position.
* @property {Quat} targetRotation=0,0,0,1 - The target rotation.
- * @property {Uuid} otherID=null - If an entity ID, the <code>targetPosition</code> and <code>targetRotation</code> are
- * relative to this entity's position and rotation.
* @property {number} linearTimeScale=3.4e+38 - Controls how long it takes for the entity's position to catch up with the
* target position. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the action
* is applied using an exponential decay.
@@ -33,6 +35,7 @@
* target orientation. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the
* action is applied using an exponential decay.
*/
+// The properties are per ObjectActionTractor.
class AvatarActionFarGrab : public ObjectActionTractor {
public:
AvatarActionFarGrab(const QUuid& id, EntityItemPointer ownerEntity);
diff --git a/interface/src/avatar/AvatarActionHold.cpp b/interface/src/avatar/AvatarActionHold.cpp
index 5fb9c9a0ee..3ac9f63649 100644
--- a/interface/src/avatar/AvatarActionHold.cpp
+++ b/interface/src/avatar/AvatarActionHold.cpp
@@ -447,16 +447,16 @@ bool AvatarActionHold::updateArguments(QVariantMap arguments) {
/**jsdoc
* The <code>"hold"</code> {@link Entities.ActionType|ActionType} positions and rotates an entity relative to an avatar's hand.
* Collisions between the entity and the user's avatar are disabled during the hold.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-Hold
* @property {Uuid} holderID=MyAvatar.sessionUUID - The ID of the avatar holding the entity.
+ * @property {string} hand=right - The hand holding the entity: <code>"left"</code> or <code>"right"</code>.
* @property {Vec3} relativePosition=0,0,0 - The target position relative to the avatar's hand.
* @property {Vec3} relativeRotation=0,0,0,1 - The target rotation relative to the avatar's hand.
* @property {number} timeScale=3.4e+38 - Controls how long it takes for the entity's position and rotation to catch up with
* the target. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the action is
* applied using an exponential decay.
- * @property {string} hand=right - The hand holding the entity: <code>"left"</code> or <code>"right"</code>.
* @property {boolean} kinematic=false - If <code>true</code>, the entity is made kinematic during the action; the entity won't
* lag behind the hand but constraint actions such as <code>"hinge"</code> won't act properly.
* @property {boolean} kinematicSetVelocity=false - If <code>true</code> and <code>kinematic</code> is <code>true</code>, the
diff --git a/libraries/entities/src/EntityDynamicInterface.cpp b/libraries/entities/src/EntityDynamicInterface.cpp
index 1115559342..84ceefa6b9 100644
--- a/libraries/entities/src/EntityDynamicInterface.cpp
+++ b/libraries/entities/src/EntityDynamicInterface.cpp
@@ -94,47 +94,47 @@ variables. These argument variables are used by the code which is run when bull
#include "EntityItem.h"
/**jsdoc
-* <p>An entity action may be one of the following types:</p>
-* <table>
-* <thead>
-* <tr><th>Value</th><th>Type</th><th>Description</th><th>Arguments</th></tr>
-* </thead>
-* <tbody>
-* <tr><td><code>"far-grab"</code></td><td>Avatar action</td>
-* <td>Moves and rotates an entity to a target position and orientation, optionally relative to another entity. Collisions
-* between the entity and the user's avatar are disabled during the far-grab.</td>
-* <td>{@link Entities.ActionArguments-FarGrab}</td></tr>
-* <tr><td><code>"hold"</code></td><td>Avatar action</td>
-* <td>Positions and rotates an entity relative to an avatar's hand. Collisions between the entity and the user's avatar
-* are disabled during the hold.</td>
-* <td>{@link Entities.ActionArguments-Hold}</td></tr>
-* <tr><td><code>"offset"</code></td><td>Object action</td>
-* <td>Moves an entity so that it is a set distance away from a target point.</td>
-* <td>{@link Entities.ActionArguments-Offset}</td></tr>
-* <tr><td><code>"tractor"</code></td><td>Object action</td>
-* <td>Moves and rotates an entity to a target position and orientation, optionally relative to another entity.</td>
-* <td>{@link Entities.ActionArguments-Tractor}</td></tr>
-* <tr><td><code>"travel-oriented"</code></td><td>Object action</td>
-* <td>Orients an entity to align with its direction of travel.</td>
-* <td>{@link Entities.ActionArguments-TravelOriented}</td></tr>
-* <tr><td><code>"hinge"</code></td><td>Object constraint</td>
-* <td>Lets an entity pivot about an axis or connects two entities with a hinge joint.</td>
-* <td>{@link Entities.ActionArguments-Hinge}</td></tr>
-* <tr><td><code>"slider"</code></td><td>Object constraint</td>
-* <td>Lets an entity slide and rotate along an axis, or connects two entities that slide and rotate along a shared
-* axis.</td>
-* <td>{@link Entities.ActionArguments-Slider|ActionArguments-Slider}</td></tr>
-* <tr><td><code>"cone-twist"</code></td><td>Object constraint</td>
-* <td>Connects two entities with a joint that can move through a cone and can twist.</td>
-* <td>{@link Entities.ActionArguments-ConeTwist}</td></tr>
-* <tr><td><code>"ball-socket"</code></td><td>Object constraint</td>
-* <td>Connects two entities with a ball and socket joint.</td>
-* <td>{@link Entities.ActionArguments-BallSocket}</td></tr>
-* <tr><td><code>"spring"</code></td><td colspan="3">Synonym for <code>"tractor"</code>. <em>Legacy value.</em></td></tr>
-* </tbody>
-* </table>
-* @typedef {string} Entities.ActionType
-*/
+ * <p>An entity action may be one of the following types:</p>
+ * <table>
+ * <thead>
+ * <tr><th>Value</th><th>Type</th><th>Description</th><th>Arguments</th></tr>
+ * </thead>
+ * <tbody>
+ * <tr><td><code>"far-grab"</code></td><td>Avatar action</td>
+ * <td>Moves and rotates an entity to a target position and orientation, optionally relative to another entity. Collisions
+ * between the entity and the user's avatar are disabled during the far-grab.</td>
+ * <td>{@link Entities.ActionArguments-FarGrab}</td></tr>
+ * <tr><td><code>"hold"</code></td><td>Avatar action</td>
+ * <td>Positions and rotates an entity relative to an avatar's hand. Collisions between the entity and the user's avatar
+ * are disabled during the hold.</td>
+ * <td>{@link Entities.ActionArguments-Hold}</td></tr>
+ * <tr><td><code>"offset"</code></td><td>Object action</td>
+ * <td>Moves an entity so that it is a set distance away from a target point.</td>
+ * <td>{@link Entities.ActionArguments-Offset}</td></tr>
+ * <tr><td><code>"tractor"</code></td><td>Object action</td>
+ * <td>Moves and rotates an entity to a target position and orientation, optionally relative to another entity.</td>
+ * <td>{@link Entities.ActionArguments-Tractor}</td></tr>
+ * <tr><td><code>"travel-oriented"</code></td><td>Object action</td>
+ * <td>Orients an entity to align with its direction of travel.</td>
+ * <td>{@link Entities.ActionArguments-TravelOriented}</td></tr>
+ * <tr><td><code>"hinge"</code></td><td>Object constraint</td>
+ * <td>Lets an entity pivot about an axis or connects two entities with a hinge joint.</td>
+ * <td>{@link Entities.ActionArguments-Hinge}</td></tr>
+ * <tr><td><code>"slider"</code></td><td>Object constraint</td>
+ * <td>Lets an entity slide and rotate along an axis, or connects two entities that slide and rotate along a shared
+ * axis.</td>
+ * <td>{@link Entities.ActionArguments-Slider|ActionArguments-Slider}</td></tr>
+ * <tr><td><code>"cone-twist"</code></td><td>Object constraint</td>
+ * <td>Connects two entities with a joint that can move through a cone and can twist.</td>
+ * <td>{@link Entities.ActionArguments-ConeTwist}</td></tr>
+ * <tr><td><code>"ball-socket"</code></td><td>Object constraint</td>
+ * <td>Connects two entities with a ball and socket joint.</td>
+ * <td>{@link Entities.ActionArguments-BallSocket}</td></tr>
+ * <tr><td><code>"spring"</code></td><td colspan="3">Synonym for <code>"tractor"</code>. <em>Legacy value.</em></td></tr>
+ * </tbody>
+ * </table>
+ * @typedef {string} Entities.ActionType
+ */
// Note: The "none" action type is not listed because it's an internal "uninitialized" value and not useful for scripts.
EntityDynamicType EntityDynamicInterface::dynamicTypeFromString(QString dynamicTypeString) {
QString normalizedDynamicTypeString = dynamicTypeString.toLower().remove('-').remove('_');
diff --git a/libraries/entities/src/EntityItemProperties.cpp b/libraries/entities/src/EntityItemProperties.cpp
index 05072ac99e..a2e1d5560a 100644
--- a/libraries/entities/src/EntityItemProperties.cpp
+++ b/libraries/entities/src/EntityItemProperties.cpp
@@ -757,10 +757,10 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* unnecessary entity server updates. Scripts should not change this property's value.
*
* @property {string} actionData="" - Base-64 encoded compressed dump of the actions associated with the entity. This property
- * is typically not used in scripts directly; rather, functions that manipulate an entity's actions update it.
- * The size of this property increases with the number of actions. Because this property value has to fit within a High
- * Fidelity datagram packet there is a limit to the number of actions that an entity can have, and edits which would result
- * in overflow are rejected. <em>Read-only.</em>
+ * is typically not used in scripts directly; rather, functions that manipulate an entity's actions update it, e.g.,
+ * {@link Entities.addAction}. The size of this property increases with the number of actions. Because this property value
+ * has to fit within a High Fidelity datagram packet there is a limit to the number of actions that an entity can have, and
+ * edits which would result in overflow are rejected. <em>Read-only.</em>
* @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>
*
@@ -2876,6 +2876,13 @@ bool EntityItemProperties::getPropertyInfo(const QString& propertyName, EntityPr
return false;
}
+/**jsdoc
+ * Information about an entity property.
+ * @typedef {object} Entities.EntityPropertyInfo
+ * @property {number} propertyEnum - The internal number of the property.
+ * @property {string} minimum - The minimum numerical value the property may have, if available, otherwise <code>""</code>.
+ * @property {string} maximum - The maximum numerical value the property may have, if available, otherwise <code>""</code>.
+ */
QScriptValue EntityPropertyInfoToScriptValue(QScriptEngine* engine, const EntityPropertyInfo& propertyInfo) {
QScriptValue obj = engine->newObject();
obj.setProperty("propertyEnum", propertyInfo.propertyEnum);
diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h
index bad619a5ad..1a34fd2139 100644
--- a/libraries/entities/src/EntityScriptingInterface.h
+++ b/libraries/entities/src/EntityScriptingInterface.h
@@ -57,7 +57,7 @@ private:
};
/**jsdoc
- * The result of a {@link PickRay} search using {@link Entities.findRayIntersection|findRayIntersection}.
+ * The result of a {@link Entities.findRayIntersection|findRayIntersection} search using a {@link PickRay}.
* @typedef {object} Entities.RayToEntityIntersectionResult
* @property {boolean} intersects - <code>true</code> if the {@link PickRay} intersected an entity, otherwise
* <code>false</code>.
@@ -154,17 +154,20 @@ public:
const QVector<EntityItemID>& entityIdsToInclude, const QVector<EntityItemID>& entityIdsToDiscard);
/**jsdoc
- * Get the properties of multiple entities.
- * @function Entities.getMultipleEntityProperties
- * @param {Uuid[]} entityIDs - The IDs of the entities to get the properties of.
- * @param {string[]|string} [desiredProperties=[]] - Either string with property name or array of the names of the properties
- * to get. If the array is empty, all properties are returned.
- * @returns {Entities.EntityProperties[]} The properties of the entity if the entity can be found, otherwise an empty object.
- * @example <caption>Retrieve the names of the nearby entities</caption>
- * var SEARCH_RADIUS = 50; // meters
- * var entityIds = Entities.findEntities(MyAvatar.position, SEARCH_RADIUS);
- * var propertySets = Entities.getMultipleEntityProperties(entityIds, "name");
- * print("Nearby entity names: " + JSON.stringify(propertySets));
+ * Gets the properties of multiple entities.
+ * @function Entities.getMultipleEntityProperties
+ * @param {Uuid[]} entityIDs - The IDs of the entities to get the properties of.
+ * @param {string[]|string} [desiredProperties=[]] - The name or names of the properties to get. For properties that are
+ * objects (e.g., the <code>"keyLight"</code> property), use the property and subproperty names in dot notation (e.g.,
+ * <code>"keyLight.color"</code>).
+ * @returns {Entities.EntityProperties[]} The specified properties of each entity for each entity that can be found. If
+ * none of the entities can be found then an empty array. If no properties are specified, then all properties are
+ * returned.
+ * @example <caption>Retrieve the names of the nearby entities</caption>
+ * var SEARCH_RADIUS = 50; // meters
+ * var entityIDs = Entities.findEntities(MyAvatar.position, SEARCH_RADIUS);
+ * var propertySets = Entities.getMultipleEntityProperties(entityIDs, "name");
+ * print("Nearby entity names: " + JSON.stringify(propertySets));
*/
static QScriptValue getMultipleEntityProperties(QScriptContext* context, QScriptEngine* engine);
QScriptValue getMultipleEntityPropertiesInternal(QScriptEngine* engine, QVector<QUuid> entityIDs, const QScriptValue& extendedDesiredProperties);
@@ -314,6 +317,7 @@ public slots:
/// temporary method until addEntity can be used from QJSEngine
/// Deliberately not adding jsdoc, only used internally.
+ // FIXME: Deprecate and remove from the API.
Q_INVOKABLE QUuid addModelEntity(const QString& name, const QString& modelUrl, const QString& textures, const QString& shapeType, bool dynamic,
bool collisionless, bool grabbable, const glm::vec3& position, const glm::vec3& gravity);
@@ -332,14 +336,14 @@ public slots:
Q_INVOKABLE QUuid cloneEntity(const QUuid& entityID);
/**jsdoc
- * Gets the properties of an entity.
+ * Gets an entity's property values.
* @function Entities.getEntityProperties
* @param {Uuid} entityID - The ID of the entity to get the properties of.
- * @param {string|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.,
+ * @param {string|string[]} [desiredProperties=[]] - The name or 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.
+ * @returns {Entities.EntityProperties} The specified properties of the entity if the entity can be found, otherwise an
+ * empty object. If no properties are specified, then all properties are returned.
* @example <caption>Report the color of a new box entity.</caption>
* var entityID = Entities.addEntity({
* type: "Box",
@@ -355,7 +359,7 @@ public slots:
Q_INVOKABLE EntityItemProperties getEntityProperties(const QUuid& entityID, EntityPropertyFlags desiredProperties);
/**jsdoc
- * Edits an entity, changing one or more of its properties.
+ * Edits an entity, changing one or more of its property values.
* @function Entities.editEntity
* @param {Uuid} entityID - The ID of the entity to edit.
* @param {Entities.EntityProperties} properties - The new property values.
@@ -406,16 +410,56 @@ public slots:
Q_INVOKABLE QString getEntityType(const QUuid& entityID);
/**jsdoc
- * Get the entity script object. In particular, this is useful for accessing the event bridge for a <code>Web</code>
- * entity.
+ * Gets an entity's script object. In particular, this is useful for accessing a {@link Entities.EntityProperties-Web|Web}
+ * entity's event bridge.
* @function Entities.getEntityObject
- * @param {Uuid} id - The ID of the entity to get the script object of.
+ * @param {Uuid} id - The ID of the entity to get the script object for.
* @returns {object} The script object for the entity if found.
+ * @example <caption>Receive "hello" messages from a Web entity.</caption>
+ * // HTML file, name: "webEntity.html".
+ * <!DOCTYPE html>
+ * <html>
+ * <head>
+ * <title>HELLO</title>
+ * </head>
+ * <body>
+ * <h1>HELLO</h1></h1>
+ * <script>
+ * setInterval(function () {
+ * console.log("$$$$$$$ send");
+ * EventBridge.emitWebEvent("hello");
+ * }, 2000);
+ * </script>
+ * </body>
+ * </html>
+ *
+ * // Script file.
+ * var webEntity = Entities.addEntity({
+ * type: "Web",
+ * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -3 })),
+ * rotation: MyAvatar.orientation,
+ * sourceUrl: Script.resolvePath("webEntity.html"),
+ * alpha: 1.0
+ * });
+ *
+ * function onWebEventReceived(event) {
+ * print("onWebEventReceived() : " + JSON.stringify(event));
+ * }
+ *
+ * Script.setTimeout(function () {
+ * var entityObject = Entities.getEntityObject(webEntity);
+ * print("$$$$ entityObject: " + entityObject);
+ * entityObject.webEventReceived.connect(onWebEventReceived);
+ * }, 500);
+ *
+ * Script.scriptEnding.connect(function () {
+ * Entities.deleteEntity(webEntity);
+ * });
*/
Q_INVOKABLE QObject* getEntityObject(const QUuid& id);
/**jsdoc
- * Check whether an entities's assets have been loaded. For example, for an <code>Model</code> entity the result indicates
+ * Checks whether an entities's assets have been loaded. For example, for an <code>Model</code> entity the result indicates
* whether its textures have been loaded.
* @function Entities.isLoaded
* @param {Uuid} id - The ID of the entity to check.
@@ -432,7 +476,7 @@ public slots:
Q_INVOKABLE bool isAddedEntity(const QUuid& id);
/**jsdoc
- * Calculates the size of the given text in the specified object if it is a text entity.
+ * Calculates the size of some text in a text entity.
* @function Entities.textSize
* @param {Uuid} id - The ID of the entity to use for calculation.
* @param {string} text - The string to calculate the size of.
@@ -478,11 +522,11 @@ public slots:
const QStringList& params = QStringList());
/**jsdoc
- * Find the non-local entity with a position closest to a specified point and within a specified radius.
+ * Finds the domain or avatar entity with a position closest to a specified point and within a specified radius.
* @function Entities.findClosestEntity
* @param {Vec3} center - The point about which to search.
* @param {number} radius - The radius within which to search.
- * @returns {Uuid} The ID of the entity that is closest to the <code>center</code> and within the <code>radius</code> if
+ * @returns {Uuid} The ID of the entity that is closest to the <code>center</code> and within the <code>radius</code>, if
* there is one, otherwise <code>null</code>.
* @example <caption>Find the closest entity within 10m of your avatar.</caption>
* var entityID = Entities.findClosestEntity(MyAvatar.position, 10);
@@ -492,12 +536,12 @@ public slots:
Q_INVOKABLE QUuid findClosestEntity(const glm::vec3& center, float radius) const;
/**jsdoc
- * Find all non-local entities that intersect a sphere defined by a center point and radius.
+ * Finds all domain and avatar entities that intersect a sphere.
* @function Entities.findEntities
* @param {Vec3} center - The point about which to search.
* @param {number} radius - The radius within which to search.
- * @returns {Uuid[]} An array of entity IDs that were found that intersect the search sphere. The array is empty if no
- * entities could be found.
+ * @returns {Uuid[]} An array of entity IDs that intersect the search sphere. The array is empty if no entities could be
+ * found.
* @example <caption>Report how many entities are within 10m of your avatar.</caption>
* var entityIDs = Entities.findEntities(MyAvatar.position, 10);
* print("Number of entities within 10m: " + entityIDs.length);
@@ -506,8 +550,7 @@ public slots:
Q_INVOKABLE QVector<QUuid> findEntities(const glm::vec3& center, float radius) const;
/**jsdoc
- * Find all non-local entities whose axis-aligned boxes intersect a search axis-aligned box defined by its minimum coordinates corner
- * and dimensions.
+ * Finds all domain and avatar entities whose axis-aligned boxes intersect a search axis-aligned box.
* @function Entities.findEntitiesInBox
* @param {Vec3} corner - The corner of the search AA box with minimum co-ordinate values.
* @param {Vec3} dimensions - The dimensions of the search AA box.
@@ -518,12 +561,12 @@ public slots:
Q_INVOKABLE QVector<QUuid> findEntitiesInBox(const glm::vec3& corner, const glm::vec3& dimensions) const;
/**jsdoc
- * Find all non-local entities whose axis-aligned boxes intersect a search frustum.
+ * Finds all domain and avatar entities whose axis-aligned boxes intersect a search frustum.
* @function Entities.findEntitiesInFrustum
* @param {ViewFrustum} frustum - The frustum to search in. The <code>position</code>, <code>orientation</code>,
* <code>projection</code>, and <code>centerRadius</code> properties must be specified.
- * @returns {Uuid[]} An array of entity IDs axis-aligned boxes intersect the frustum. The array is empty if no entities
- * could be found.
+ * @returns {Uuid[]} An array of entity IDs whose axis-aligned boxes intersect the search frustum. The array is empty if no
+ * entities could be found.
* @example <caption>Report the number of entities in view.</caption>
* var entityIDs = Entities.findEntitiesInFrustum(Camera.frustum);
* print("Number of entities in view: " + entityIDs.length);
@@ -532,7 +575,7 @@ public slots:
Q_INVOKABLE QVector<QUuid> findEntitiesInFrustum(QVariantMap frustum) const;
/**jsdoc
- * Find all non-local entities of a particular type that intersect a sphere defined by a center point and radius.
+ * Finds all domain and avatar entities of a particular type that intersect a sphere.
* @function Entities.findEntitiesByType
* @param {Entities.EntityType} entityType - The type of entity to search for.
* @param {Vec3} center - The point about which to search.
@@ -547,33 +590,35 @@ public slots:
Q_INVOKABLE QVector<QUuid> findEntitiesByType(const QString entityType, const glm::vec3& center, float radius) const;
/**jsdoc
- * Find all non-local entities with a particular name that intersect a sphere defined by a center point and radius.
- * @function Entities.findEntitiesByName
- * @param {string} entityName - The name of the entity to search for.
- * @param {Vec3} center - The point about which to search.
- * @param {number} radius - The radius within which to search.
- * @param {boolean} [caseSensitive=false] - If <code>true</code> then the search is case-sensitive.
- * @returns {Uuid[]} An array of entity IDs that have the specified name and intersect the search sphere. The array is empty
- * if no entities could be found.
- * @example <caption>Report the number of entities with the name, "Light-Target".</caption>
- * var entityIDs = Entities.findEntitiesByName("Light-Target", MyAvatar.position, 10, false);
- * print("Number of entities with the name Light-Target: " + entityIDs.length);
- */
+ * Finds all domain and avatar entities with a particular name that intersect a sphere.
+ * @function Entities.findEntitiesByName
+ * @param {string} entityName - The name of the entity to search for.
+ * @param {Vec3} center - The point about which to search.
+ * @param {number} radius - The radius within which to search.
+ * @param {boolean} [caseSensitive=false] - If <code>true</code> then the search is case-sensitive.
+ * @returns {Uuid[]} An array of entity IDs that have the specified name and intersect the search sphere. The array is
+ * empty if no entities could be found.
+ * @example <caption>Report the number of entities with the name, "Light-Target".</caption>
+ * var entityIDs = Entities.findEntitiesByName("Light-Target", MyAvatar.position, 10, false);
+ * print("Number of entities with the name Light-Target: " + entityIDs.length);
+ */
Q_INVOKABLE QVector<QUuid> findEntitiesByName(const QString entityName, const glm::vec3& center, float radius,
bool caseSensitiveSearch = false) const;
/**jsdoc
- * Find the first non-local entity intersected by a {@link PickRay}. <code>Light</code> and <code>Zone</code> entities are not
- * intersected unless they've been configured as pickable using {@link Entities.setLightsArePickable|setLightsArePickable}
- * and {@link Entities.setZonesArePickable|setZonesArePickable}, respectively.<br />
+ * Finds the first avatar or domain entity intersected by a {@link PickRay}. <code>Light</code> and <code>Zone</code>
+ * entities are not intersected unless they've been configured as pickable using
+ * {@link Entities.setLightsArePickable|setLightsArePickable} and {@link Entities.setZonesArePickable|setZonesArePickable},
+ * respectively.
* @function Entities.findRayIntersection
- * @param {PickRay} pickRay - The PickRay to use for finding entities.
- * @param {boolean} [precisionPicking=false] - If <code>true</code> and the intersected entity is a <code>Model</code>
- * entity, the result's <code>extraInfo</code> property includes more information than it otherwise would.
+ * @param {PickRay} pickRay - The pick ray to use for finding entities.
+ * @param {boolean} [precisionPicking=false] - <code>true</code> to pick against precise meshes, <code>false</code> to pick
+ * against coarse meshes. If <code>true</code> and the intersected entity is a <code>Model</code> entity, the result's
+ * <code>extraInfo</code> property includes more information than it otherwise would.
* @param {Uuid[]} [entitiesToInclude=[]] - If not empty then the search is restricted to these entities.
* @param {Uuid[]} [entitiesToDiscard=[]] - Entities to ignore during the search.
* @param {boolean} [visibleOnly=false] - If <code>true</code> then only entities that are
- * <code>{@link Entities.EntityProperties|visible}<code> are searched.
+ * <code>{@link Entities.EntityProperties|visible}</code> are searched.
* @param {boolean} [collideableOnly=false] - If <code>true</code> then only entities that are not
* <code>{@link Entities.EntityProperties|collisionless}</code> are searched.
* @returns {Entities.RayToEntityIntersectionResult} The result of the search for the first intersected entity.
@@ -626,33 +671,33 @@ public slots:
Q_INVOKABLE bool getServerScriptStatus(const QUuid& entityID, QScriptValue callback);
/**jsdoc
- * Get metadata for certain entity properties such as <code>script</code> and <code>serverScripts</code>.
- * @function Entities.queryPropertyMetadata
- * @param {Uuid} entityID - The ID of the entity to get the metadata for.
- * @param {string} property - The property name to get the metadata for.
- * @param {Entities~queryPropertyMetadataCallback} callback - The function to call upon completion.
- * @returns {boolean} <code>true</code> if the request for metadata was successfully sent to the server, otherwise
- * <code>false</code>.
- * @throws Throws an error if <code>property</code> is not handled yet or <code>callback</code> is not a function.
- */
+ * Gets metadata for certain entity properties such as <code>script</code> and <code>serverScripts</code>.
+ * @function Entities.queryPropertyMetadata
+ * @param {Uuid} entityID - The ID of the entity to get the metadata for.
+ * @param {string} property - The property name to get the metadata for.
+ * @param {Entities~queryPropertyMetadataCallback} callback - The function to call upon completion.
+ * @returns {boolean} <code>true</code> if the request for metadata was successfully sent to the server, otherwise
+ * <code>false</code>.
+ * @throws Throws an error if <code>property</code> is not handled yet or <code>callback</code> is not a function.
+ */
/**jsdoc
- * Get metadata for certain entity properties such as <code>script</code> and <code>serverScripts</code>.
- * @function Entities.queryPropertyMetadata
- * @param {Uuid} entityID - The ID of the entity to get the metadata for.
- * @param {string} property - The property name to get the metadata for.
- * @param {object} scope - The "<code>this</code>" context that the callback will be executed within.
- * @param {Entities~queryPropertyMetadataCallback} callback - The function to call upon completion.
- * @returns {boolean} <code>true</code> if the request for metadata was successfully sent to the server, otherwise
- * <code>false</code>.
- * @throws Throws an error if <code>property</code> is not handled yet or <code>callback</code> is not a function.
- */
+ * Gets metadata for certain entity properties such as <code>script</code> and <code>serverScripts</code>.
+ * @function Entities.queryPropertyMetadata
+ * @param {Uuid} entityID - The ID of the entity to get the metadata for.
+ * @param {string} property - The property name to get the metadata for.
+ * @param {object} scope - The "<code>this</code>" context that the callback will be executed within.
+ * @param {Entities~queryPropertyMetadataCallback} callback - The function to call upon completion.
+ * @returns {boolean} <code>true</code> if the request for metadata was successfully sent to the server, otherwise
+ * <code>false</code>.
+ * @throws Throws an error if <code>property</code> is not handled yet or <code>callback</code> is not a function.
+ */
/**jsdoc
- * Called when {@link Entities.queryPropertyMetadata} is complete.
- * @callback Entities~queryPropertyMetadataCallback
- * @param {string} error - <code>undefined</code> if there was no error, otherwise an error message.
- * @param {object} result - The metadata for the requested entity property if there was no error, otherwise
- * <code>undefined</code>.
- */
+ * Called when a {@link Entities.queryPropertyMetadata} call is complete.
+ * @callback Entities~queryPropertyMetadataCallback
+ * @param {string} error - <code>undefined</code> if there was no error, otherwise an error message.
+ * @param {object} result - The metadata for the requested entity property if there was no error, otherwise
+ * <code>undefined</code>.
+ */
Q_INVOKABLE bool queryPropertyMetadata(const QUuid& entityID, QScriptValue property, QScriptValue scopeOrCallback,
QScriptValue methodOrName = QScriptValue());
@@ -721,7 +766,7 @@ public slots:
/**jsdoc
- * Set the values of all voxels in a spherical portion of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
+ * Sets the values of all voxels in a spherical portion of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @function Entities.setVoxelSphere
* @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} center - The center of the sphere of voxels to set, in world coordinates.
@@ -742,7 +787,7 @@ public slots:
Q_INVOKABLE bool setVoxelSphere(const QUuid& entityID, const glm::vec3& center, float radius, int value);
/**jsdoc
- * Set the values of all voxels in a capsule-shaped portion of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
+ * Sets the values of all voxels in a capsule-shaped portion of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @function Entities.setVoxelCapsule
* @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} start - The center of the sphere of voxels to set, in world coordinates.
@@ -766,7 +811,7 @@ public slots:
Q_INVOKABLE bool setVoxelCapsule(const QUuid& entityID, const glm::vec3& start, const glm::vec3& end, float radius, int value);
/**jsdoc
- * Set the value of a particular voxels in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
+ * Sets the value of a particular voxel in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @function Entities.setVoxel
* @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} position - The position relative to the minimum axes values corner of the entity. The
@@ -788,7 +833,7 @@ public slots:
Q_INVOKABLE bool setVoxel(const QUuid& entityID, const glm::vec3& position, int value);
/**jsdoc
- * Set the values of all voxels in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
+ * Sets the values of all voxels in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @function Entities.setAllVoxels
* @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {number} value - If <code>value % 256 == 0</code> then each voxel is cleared, otherwise each voxel is set.
@@ -806,7 +851,7 @@ public slots:
Q_INVOKABLE bool setAllVoxels(const QUuid& entityID, int value);
/**jsdoc
- * Set the values of all voxels in a cubic portion of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
+ * Sets the values of all voxels in a cubic portion of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @function Entities.setVoxelsInCuboid
* @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} lowPosition - The position of the minimum axes value corner of the cube of voxels to set, in voxel
@@ -913,12 +958,12 @@ public slots:
Q_INVOKABLE glm::vec3 localCoordsToVoxelCoords(const QUuid& entityID, glm::vec3 localCoords);
/**jsdoc
- * Set the <code>linePoints</code> property of a {@link Entities.EntityProperties-Line|Line} entity.
+ * Sets all the points in a {@link Entities.EntityProperties-Line|Line} entity.
* @function Entities.setAllPoints
* @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-Line|Line} entity.
- * @param {Vec3[]} points - The array of points to set the entity's <code>linePoints</code> property to.
- * @returns {boolean} <code>true</code> if the entity's property was updated, otherwise <code>false</code>. The property
- * may fail to be updated if the entity does not exist, the entity is not a {@link Entities.EntityProperties-Line|Line} entity,
+ * @param {Vec3[]} points - The points that the entity should draw lines between.
+ * @returns {boolean} <code>true</code> if the entity was updated, otherwise <code>false</code>. The property may fail to
+ * be updated if the entity does not exist, the entity is not a {@link Entities.EntityProperties-Line|Line} entity,
* one of the points is outside the entity's dimensions, or the number of points is greater than the maximum allowed.
* @example <caption>Change the shape of a Line entity.</caption>
* // Draw a horizontal line between two points.
@@ -947,7 +992,7 @@ public slots:
Q_INVOKABLE bool setAllPoints(const QUuid& entityID, const QVector<glm::vec3>& points);
/**jsdoc
- * Append a point to a {@link Entities.EntityProperties-Line|Line} entity.
+ * Appends a point to a {@link Entities.EntityProperties-Line|Line} entity.
* @function Entities.appendPoint
* @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-Line|Line} entity.
* @param {Vec3} point - The point to add to the line. The coordinates are relative to the entity's position.
@@ -982,14 +1027,14 @@ public slots:
/**jsdoc
- * Add an action to an entity. An action is registered with the physics engine and is applied every physics simulation
+ * Adds an action to an entity. An action is registered with the physics engine and is applied every physics simulation
* step. Any entity may have more than one action associated with it, but only as many as will fit in an entity's
- * <code>actionData</code> property.
+ * <code>{@link Entities.EntityProperties|actionData}</code> property.
* @function Entities.addAction
* @param {Entities.ActionType} actionType - The type of action.
* @param {Uuid} entityID - The ID of the entity to add the action to.
- * @param {Entities.ActionArguments} arguments - Configure the action.
- * @returns {Uuid} The ID of the action added if successfully added, otherwise <code>null</code>.
+ * @param {Entities.ActionArguments} arguments - Configures the action.
+ * @returns {Uuid} The ID of the action if successfully added, otherwise <code>null</code>.
* @example <caption>Constrain a cube to move along a vertical line.</caption>
* var entityID = Entities.addEntity({
* type: "Box",
@@ -1010,7 +1055,7 @@ public slots:
Q_INVOKABLE QUuid addAction(const QString& actionTypeString, const QUuid& entityID, const QVariantMap& arguments);
/**jsdoc
- * Update an entity action.
+ * Updates an entity action.
* @function Entities.updateAction
* @param {Uuid} entityID - The ID of the entity with the action to update.
* @param {Uuid} actionID - The ID of the action to update.
@@ -1020,35 +1065,35 @@ public slots:
Q_INVOKABLE bool updateAction(const QUuid& entityID, const QUuid& actionID, const QVariantMap& arguments);
/**jsdoc
- * Delete an action from an entity.
+ * Deletes an action from an entity.
* @function Entities.deleteAction
* @param {Uuid} entityID - The ID of entity to delete the action from.
* @param {Uuid} actionID - The ID of the action to delete.
- * @returns {boolean} <code>true</code> if the update was successful, otherwise <code>false</code>.
+ * @returns {boolean} <code>true</code> if the delete was successful, otherwise <code>false</code>.
*/
Q_INVOKABLE bool deleteAction(const QUuid& entityID, const QUuid& actionID);
/**jsdoc
- * Get the IDs of the actions that are associated with an entity.
+ * Gets the IDs of the actions that are associated with an entity.
* @function Entities.getActionIDs
* @param {Uuid} entityID - The entity to get the action IDs for.
- * @returns {Uuid[]} An array of action IDs if any are found, otherwise an empty array.
+ * @returns {Uuid[]} The action IDs if any are found, otherwise an empty array.
*/
Q_INVOKABLE QVector<QUuid> getActionIDs(const QUuid& entityID);
/**jsdoc
- * Get the arguments of an action.
+ * Gets the arguments of an action.
* @function Entities.getActionArguments
* @param {Uuid} entityID - The ID of the entity with the action.
* @param {Uuid} actionID - The ID of the action to get the arguments of.
- * @returns {Entities.ActionArguments} The arguments of the requested action if found, otherwise an empty object.
+ * @returns {Entities.ActionArguments} The arguments of the action if found, otherwise an empty object.
*/
Q_INVOKABLE QVariantMap getActionArguments(const QUuid& entityID, const QUuid& actionID);
/**jsdoc
- * Get the translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity relative to the entity's position and
- * orientation.
+ * Gets the translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity relative to the entity's
+ * position and orientation.
* @function Entities.getAbsoluteJointTranslationInObjectFrame
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
@@ -1060,17 +1105,17 @@ public slots:
Q_INVOKABLE glm::vec3 getAbsoluteJointTranslationInObjectFrame(const QUuid& entityID, int jointIndex);
/**jsdoc
- * Get the index of the parent joint.
+ * Gets the index of the parent joint of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.getJointParent
* @param {Uuid} entityID - The ID of the entity.
* @param {number} index - The integer index of the joint.
- * @returns {number} The index of the parent joint.
+ * @returns {number} The index of the parent joint if found, otherwise <code>-1</code>.
*/
Q_INVOKABLE int getJointParent(const QUuid& entityID, int index);
/**jsdoc
- * Get the translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity relative to the entity's position and
- * orientation.
+ * Gets the translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity relative to the entity's
+ * position and orientation.
* @function Entities.getAbsoluteJointRotationInObjectFrame
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
@@ -1099,28 +1144,29 @@ public slots:
Q_INVOKABLE glm::quat getAbsoluteJointRotationInObjectFrame(const QUuid& entityID, int jointIndex);
/**jsdoc
- * Set the translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity relative to the entity's position and
- * orientation.
+ * Sets the translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity relative to the entity's
+ * position and orientation.
* @function Entities.setAbsoluteJointTranslationInObjectFrame
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
* @param {Vec3} translation - The translation to set the joint to relative to the entity's position and orientation.
- * @returns {boolean} <code>true</code>if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded,
- * the joint index is valid, and the translation is different to the joint's current translation; otherwise
+ * @returns {boolean} <code>true</code>if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
+ * is loaded, the joint index is valid, and the translation is different to the joint's current translation; otherwise
* <code>false</code>.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE bool setAbsoluteJointTranslationInObjectFrame(const QUuid& entityID, int jointIndex, glm::vec3 translation);
/**jsdoc
- * Set the rotation of a joint in a {@link Entities.EntityProperties-Model|Model} entity relative to the entity's position and
- * orientation.
+ * Sets the rotation of a joint in a {@link Entities.EntityProperties-Model|Model} entity relative to the entity's position
+ * and orientation.
* @function Entities.setAbsoluteJointRotationInObjectFrame
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
* @param {Quat} rotation - The rotation to set the joint to relative to the entity's orientation.
- * @returns {boolean} <code>true</code> if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded,
- * the joint index is valid, and the rotation is different to the joint's current rotation; otherwise <code>false</code>.
+ * @returns {boolean} <code>true</code> if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
+ * is loaded, the joint index is valid, and the rotation is different to the joint's current rotation; otherwise
+ * <code>false</code>.
* @example <caption>Raise an avatar model's left palm.</caption>
* entityID = Entities.addEntity({
* type: "Model",
@@ -1144,23 +1190,23 @@ public slots:
/**jsdoc
- * Get the local translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
+ * Gets the local translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.getLocalJointTranslation
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
- * @returns {Vec3} The local translation of the joint if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the
- * entity is loaded, and the joint index is valid; otherwise <code>{@link Vec3(0)|Vec3.ZERO}</code>.
+ * @returns {Vec3} The local translation of the joint if the entity is a {@link Entities.EntityProperties-Model|Model}
+ * entity, the entity is loaded, and the joint index is valid; otherwise <code>{@link Vec3(0)|Vec3.ZERO}</code>.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE glm::vec3 getLocalJointTranslation(const QUuid& entityID, int jointIndex);
/**jsdoc
- * Get the local rotation of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
+ * Gets the local rotation of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.getLocalJointRotation
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
- * @returns {Quat} The local rotation of the joint if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
- * is loaded, and the joint index is valid; otherwise <code>{@link Quat(0)|Quat.IDENTITY}</code>.
+ * @returns {Quat} The local rotation of the joint if the entity is a {@link Entities.EntityProperties-Model|Model} entity,
+ * the entity is loaded, and the joint index is valid; otherwise <code>{@link Quat(0)|Quat.IDENTITY}</code>.
* @example <caption>Report the local rotation of an avatar model's head joint.</caption>
* entityID = Entities.addEntity({
* type: "Model",
@@ -1181,26 +1227,27 @@ public slots:
Q_INVOKABLE glm::quat getLocalJointRotation(const QUuid& entityID, int jointIndex);
/**jsdoc
- * Set the local translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
+ * Sets the local translation of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.setLocalJointTranslation
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
* @param {Vec3} translation - The local translation to set the joint to.
- * @returns {boolean} <code>true</code>if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded,
- * the joint index is valid, and the translation is different to the joint's current translation; otherwise
+ * @returns {boolean} <code>true</code>if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
+ * is loaded, the joint index is valid, and the translation is different to the joint's current translation; otherwise
* <code>false</code>.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE bool setLocalJointTranslation(const QUuid& entityID, int jointIndex, glm::vec3 translation);
/**jsdoc
- * Set the local rotation of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
+ * Sets the local rotation of a joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.setLocalJointRotation
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
* @param {Quat} rotation - The local rotation to set the joint to.
- * @returns {boolean} <code>true</code> if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded,
- * the joint index is valid, and the rotation is different to the joint's current rotation; otherwise <code>false</code>.
+ * @returns {boolean} <code>true</code> if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
+ * is loaded, the joint index is valid, and the rotation is different to the joint's current rotation; otherwise
+ * <code>false</code>.
* @example <caption>Make an avatar model turn its head left.</caption>
* entityID = Entities.addEntity({
* type: "Model",
@@ -1223,25 +1270,25 @@ public slots:
/**jsdoc
- * Set the local translations of joints in a {@link Entities.EntityProperties-Model|Model} entity.
+ * Sets the local translations of joints in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.setLocalJointTranslations
* @param {Uuid} entityID - The ID of the entity.
* @param {Vec3[]} translations - The local translations to set the joints to.
- * @returns {boolean} <code>true</code>if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded,
- * the model has joints, and at least one of the translations is different to the model's current translations;
- * otherwise <code>false</code>.
+ * @returns {boolean} <code>true</code>if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
+ * is loaded, the model has joints, and at least one of the translations is different to the model's current
+ * translations; otherwise <code>false</code>.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE bool setLocalJointTranslations(const QUuid& entityID, const QVector<glm::vec3>& translations);
/**jsdoc
- * Set the local rotations of joints in a {@link Entities.EntityProperties-Model|Model} entity.
+ * Sets the local rotations of joints in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.setLocalJointRotations
* @param {Uuid} entityID - The ID of the entity.
* @param {Quat[]} rotations - The local rotations to set the joints to.
- * @returns {boolean} <code>true</code> if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded,
- * the model has joints, and at least one of the rotations is different to the model's current rotations; otherwise
- * <code>false</code>.
+ * @returns {boolean} <code>true</code> if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
+ * is loaded, the model has joints, and at least one of the rotations is different to the model's current rotations;
+ * otherwise <code>false</code>.
* @example <caption>Raise both palms of an avatar model.</caption>
* entityID = Entities.addEntity({
* type: "Model",
@@ -1277,16 +1324,16 @@ public slots:
Q_INVOKABLE bool setLocalJointRotations(const QUuid& entityID, const QVector<glm::quat>& rotations);
/**jsdoc
- * Set the local rotations and translations of joints in a {@link Entities.EntityProperties-Model|Model} entity. This is the same as
- * calling both {@link Entities.setLocalJointRotations|setLocalJointRotations} and
+ * Sets the local rotations and translations of joints in a {@link Entities.EntityProperties-Model|Model} entity. This is
+ * the same as calling both {@link Entities.setLocalJointRotations|setLocalJointRotations} and
* {@link Entities.setLocalJointTranslations|setLocalJointTranslations} at the same time.
* @function Entities.setLocalJointsData
* @param {Uuid} entityID - The ID of the entity.
* @param {Quat[]} rotations - The local rotations to set the joints to.
* @param {Vec3[]} translations - The local translations to set the joints to.
- * @returns {boolean} <code>true</code> if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity is loaded,
- * the model has joints, and at least one of the rotations or translations is different to the model's current values;
- * otherwise <code>false</code>.
+ * @returns {boolean} <code>true</code> if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
+ * is loaded, the model has joints, and at least one of the rotations or translations is different to the model's
+ * current values; otherwise <code>false</code>.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE bool setLocalJointsData(const QUuid& entityID,
@@ -1295,13 +1342,13 @@ public slots:
/**jsdoc
- * Get the index of a named joint in a {@link Entities.EntityProperties-Model|Model} entity.
+ * Gets the index of a named joint in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.getJointIndex
* @param {Uuid} entityID - The ID of the entity.
* @param {string} name - The name of the joint.
- * @returns {number} The integer index of the joint if the entity is a {@link Entities.EntityProperties-Model|Model} entity, the entity
- * is loaded, and the joint is present; otherwise <code>-1</code>. The joint indexes are in order per
- * {@link Entities.getJointNames|getJointNames}.
+ * @returns {number} The integer index of the joint if the entity is a {@link Entities.EntityProperties-Model|Model}
+ * entity, the entity is loaded, and the joint is present; otherwise <code>-1</code>. The joint indexes are in order
+ * per {@link Entities.getJointNames|getJointNames}.
* @example <caption>Report the index of a model's head joint.</caption>
* entityID = Entities.addEntity({
* type: "Model",
@@ -1321,11 +1368,12 @@ public slots:
Q_INVOKABLE int getJointIndex(const QUuid& entityID, const QString& name);
/**jsdoc
- * Get the names of all the joints in a {@link Entities.EntityProperties-Model|Model} entity.
+ * Gets the names of all the joints in a {@link Entities.EntityProperties-Model|Model} entity.
* @function Entities.getJointNames
* @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-Model|Model} entity.
- * @returns {string[]} The names of all the joints in the entity if it is a {@link Entities.EntityProperties-Model|Model} entity and
- * is loaded, otherwise an empty array. The joint names are in order per {@link Entities.getJointIndex|getJointIndex}.
+ * @returns {string[]} The names of all the joints in the entity if it is a {@link Entities.EntityProperties-Model|Model}
+ * entity and is loaded, otherwise an empty array. The joint names are in order per
+ * {@link Entities.getJointIndex|getJointIndex}.
* @example <caption>Report a model's joint names.</caption>
* entityID = Entities.addEntity({
* type: "Model",
@@ -1346,7 +1394,8 @@ public slots:
/**jsdoc
- * Get the IDs of entities and avatars that are directly parented to an entity or avatar model. Recurse on the IDs returned by the function to get all descendants of an entity or avatar.
+ * Gets the IDs of entities and avatars that are directly parented to an entity or avatar model. To get all descendants,
+ * you can recurse on the IDs returned.
* @function Entities.getChildrenIDs
* @param {Uuid} parentID - The ID of the entity or avatar to get the children IDs of.
* @returns {Uuid[]} An array of entity and avatar IDs that are parented directly to the <code>parentID</code>
@@ -1376,7 +1425,8 @@ public slots:
Q_INVOKABLE QVector<QUuid> getChildrenIDs(const QUuid& parentID);
/**jsdoc
- * Get the IDs of entities and avatars that are directly parented to an entity or avatar model's joint.
+ * Gets the IDs of entities and avatars that are directly parented to an entity or avatar model's joint. To get all
+ * descendants, you can use {@link Entities.getChildrenIDs|getChildrenIDs} to recurse on the IDs returned.
* @function Entities.getChildrenIDsOfJoint
* @param {Uuid} parentID - The ID of the entity or avatar to get the children IDs of.
* @param {number} jointIndex - Integer number of the model joint to get the children IDs of.
@@ -1411,7 +1461,7 @@ public slots:
Q_INVOKABLE QVector<QUuid> getChildrenIDsOfJoint(const QUuid& parentID, int jointIndex);
/**jsdoc
- * Check whether an entity has an entity as an ancestor (parent, parent's parent, etc.).
+ * Checks whether an entity has an entity as an ancestor (parent, parent's parent, etc.).
* @function Entities.isChildOfParent
* @param {Uuid} childID - The ID of the child entity to test for being a child, grandchild, etc.
* @param {Uuid} parentID - The ID of the parent entity to test for being a parent, grandparent, etc.
@@ -1440,12 +1490,11 @@ public slots:
Q_INVOKABLE bool isChildOfParent(const QUuid& childID, const QUuid& parentID);
/**jsdoc
- * Get the type — entity or avatar — of an in-world item.
+ * Gets the type — entity or avatar — of an in-world item.
* @function Entities.getNestableType
* @param {Uuid} id - The ID of the item to get the type of.
- * @returns {string} The type of the item: <code>"entity"</code> if the item is an entity, <code>"avatar"</code>
- * if the item is an avatar; otherwise <code>"unknown"</code> if the item cannot be found.
- * @example <caption>Print some nestable types.</caption>
+ * @returns {Entities.NestableType} The type of the item.
+ * @example <caption>Report some nestable types.</caption>
* var entity = Entities.addEntity({
* type: "Sphere",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 1, z: -2 })),
@@ -1545,8 +1594,8 @@ public slots:
Q_INVOKABLE void sendHoverLeaveEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Check whether an entity wants hand controller pointer events. For example, a {@link Entities.EntityProperties-Web|Web} entity does
- * but a {@link Entities.EntityProperties-Shape|Shape} entity doesn't.
+ * Checks whether an entity wants hand controller pointer events. For example, a {@link Entities.EntityProperties-Web|Web}
+ * entity does but a {@link Entities.EntityProperties-Shape|Shape} entity doesn't.
* @function Entities.wantsHandControllerPointerEvents
* @param {Uuid} entityID - The ID of the entity.
* @returns {boolean} <code>true</code> if the entity can be found and it wants hand controller pointer events, otherwise
@@ -1576,14 +1625,15 @@ public slots:
const glm::vec3& start, const glm::vec3& end, float radius);
/**jsdoc
- * Get the meshes in a {@link Entities.EntityProperties-Model|Model} or {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
+ * Gets the meshes in a {@link Entities.EntityProperties-Model|Model} or {@link Entities.EntityProperties-PolyVox|PolyVox}
+ * entity.
* @function Entities.getMeshes
* @param {Uuid} entityID - The ID of the <code>Model</code> or <code>PolyVox</code> entity to get the meshes of.
* @param {Entities~getMeshesCallback} callback - The function to call upon completion.
* @deprecated This function is deprecated and will be removed. Use the {@link Graphics} API instead.
*/
/**jsdoc
- * Called when {@link Entities.getMeshes} is complete.
+ * Called when a {@link Entities.getMeshes} call is complete.
* @callback Entities~getMeshesCallback
* @param {MeshProxy[]} meshes - If <code>success<</code> is <code>true</code>, a {@link MeshProxy} per mesh in the
* <code>Model</code> or <code>PolyVox</code> entity; otherwise <code>undefined</code>.
@@ -1595,7 +1645,7 @@ public slots:
Q_INVOKABLE void getMeshes(const QUuid& entityID, QScriptValue callback);
/**jsdoc
- * Get the object to world transform, excluding scale, of an entity.
+ * Gets the object to world transform, excluding scale, of an entity.
* @function Entities.getEntityTransform
* @param {Uuid} entityID - The ID of the entity.
* @returns {Mat4} The entity's object to world transform excluding scale (i.e., translation and rotation, with scale of 1)
@@ -1623,11 +1673,12 @@ public slots:
Q_INVOKABLE glm::mat4 getEntityTransform(const QUuid& entityID);
/**jsdoc
- * Get the object to parent transform, excluding scale, of an entity.
+ * Gets the object to parent transform, excluding scale, of an entity.
* @function Entities.getEntityLocalTransform
* @param {Uuid} entityID - The ID of the entity.
* @returns {Mat4} The entity's object to parent transform excluding scale (i.e., translation and rotation, with scale of
- * 1) if the entity can be found, otherwise a transform with zero translation and rotation and a scale of 1.
+ * 1) if the entity can be found, otherwise a transform with zero translation and rotation and a scale of 1. If the
+ * entity doesn't have a parent, its world transform is returned.
* @example <caption>Position and rotation in an entity's local transform.</caption>
* function createEntity(position, rotation, parent) {
* var entity = Entities.addEntity({
@@ -1779,18 +1830,20 @@ public slots:
Q_INVOKABLE bool verifyStaticCertificateProperties(const QUuid& entityID);
/**jsdoc
- * Get information about entity properties including a minimum to maximum range for numerical properties
- * as well as property enum value.
+ * Gets information about an entity property, including a minimum to maximum range for some numerical properties.
* @function Entities.getPropertyInfo
* @param {string} propertyName - The name of the property to get the information for.
- * @returns {Entities.EntityPropertyInfo} The information data including propertyEnum, minimum, and maximum
- * if the property can be found, otherwise an empty object.
+ * @returns {Entities.EntityPropertyInfo} The information about the property if it can be found, otherwise an empty object.
+ * @example <caption>Report property info. for some properties.</caption>
+ * print("alpha: " + JSON.stringify(Entities.getPropertyInfo("alpha")));
+ * print("script: " + JSON.stringify(Entities.getPropertyInfo("script")));
*/
Q_INVOKABLE const EntityPropertyInfo getPropertyInfo(const QString& propertyName) const;
signals:
/**jsdoc
- * Triggered on the client that is the physics simulation owner during the collision of two entities. Note: Isn't triggered
+ * #######<br />
+ * Triggered on the client that is the physics simulation owner during the collision of two entities. Note: Isn't triggered
* for a collision with an avatar.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.collisionWithEntity
diff --git a/libraries/physics/src/ObjectActionOffset.cpp b/libraries/physics/src/ObjectActionOffset.cpp
index 24f8a1ba8f..a99c875106 100644
--- a/libraries/physics/src/ObjectActionOffset.cpp
+++ b/libraries/physics/src/ObjectActionOffset.cpp
@@ -145,7 +145,7 @@ bool ObjectActionOffset::updateArguments(QVariantMap arguments) {
/**jsdoc
* The <code>"offset"</code> {@link Entities.ActionType|ActionType} moves an entity so that it is a set distance away from a
* target point.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-Offset
* @property {Vec3} pointToOffsetFrom=0,0,0 - The target point to offset the entity from.
diff --git a/libraries/physics/src/ObjectActionTractor.cpp b/libraries/physics/src/ObjectActionTractor.cpp
index b53c2e137a..4925faaf2a 100644
--- a/libraries/physics/src/ObjectActionTractor.cpp
+++ b/libraries/physics/src/ObjectActionTractor.cpp
@@ -341,15 +341,15 @@ bool ObjectActionTractor::updateArguments(QVariantMap arguments) {
/**jsdoc
* The <code>"tractor"</code> {@link Entities.ActionType|ActionType} moves and rotates an entity to a target position and
* orientation, optionally relative to another entity.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-Tractor
+ * @property {Uuid} otherID=null - If an entity ID, the <code>targetPosition</code> and <code>targetRotation</code> are
+ * relative to the entity's position and rotation.
+ * @property {Uuid} otherJointIndex=null - If a joint index in the <code>otherID</code> entity, the <code>targetPosition</code>
+ * and <code>targetRotation</code> are relative to the entity joint's position and rotation.
* @property {Vec3} targetPosition=0,0,0 - The target position.
* @property {Quat} targetRotation=0,0,0,1 - The target rotation.
- * @property {Uuid} otherID=null - If an entity ID, the <code>targetPosition</code> and <code>targetRotation</code> are
- * relative to this entity's position and rotation.
- * @property {Uuid} otherJointIndex=null - If an entity JointIndex, the <code>targetPosition</code> and
- * <code>targetRotation</code> are relative to this entity's joint's position and rotation.
* @property {number} linearTimeScale=3.4e+38 - Controls how long it takes for the entity's position to catch up with the
* target position. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the action
* is applied using an exponential decay.
diff --git a/libraries/physics/src/ObjectActionTravelOriented.cpp b/libraries/physics/src/ObjectActionTravelOriented.cpp
index b27ec40ae4..025c74b96a 100644
--- a/libraries/physics/src/ObjectActionTravelOriented.cpp
+++ b/libraries/physics/src/ObjectActionTravelOriented.cpp
@@ -152,7 +152,7 @@ bool ObjectActionTravelOriented::updateArguments(QVariantMap arguments) {
/**jsdoc
* The <code>"travel-oriented"</code> {@link Entities.ActionType|ActionType} orients an entity to align with its direction of
* travel.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-TravelOriented
* @property {Vec3} forward=0,0,0 - The axis of the entity to align with the entity's direction of travel.
diff --git a/libraries/physics/src/ObjectConstraintBallSocket.cpp b/libraries/physics/src/ObjectConstraintBallSocket.cpp
index ddb0c75ac9..5b925c9e88 100644
--- a/libraries/physics/src/ObjectConstraintBallSocket.cpp
+++ b/libraries/physics/src/ObjectConstraintBallSocket.cpp
@@ -183,11 +183,11 @@ bool ObjectConstraintBallSocket::updateArguments(QVariantMap arguments) {
/**jsdoc
* The <code>"ball-socket"</code> {@link Entities.ActionType|ActionType} connects two entities with a ball and socket joint.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-BallSocket
- * @property {Vec3} pivot=0,0,0 - The local offset of the joint relative to the entity's position.
* @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint.
+ * @property {Vec3} pivot=0,0,0 - The local offset of the joint relative to the entity's position.
* @property {Vec3} otherPivot=0,0,0 - The local offset of the joint relative to the other entity's position.
*/
QVariantMap ObjectConstraintBallSocket::getArguments() {
diff --git a/libraries/physics/src/ObjectConstraintConeTwist.cpp b/libraries/physics/src/ObjectConstraintConeTwist.cpp
index 9551532182..6763f82773 100644
--- a/libraries/physics/src/ObjectConstraintConeTwist.cpp
+++ b/libraries/physics/src/ObjectConstraintConeTwist.cpp
@@ -264,17 +264,18 @@ bool ObjectConstraintConeTwist::updateArguments(QVariantMap arguments) {
/**jsdoc
* The <code>"cone-twist"</code> {@link Entities.ActionType|ActionType} connects two entities with a joint that can move
* through a cone and can twist.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-ConeTwist
+ * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint.
* @property {Vec3} pivot=0,0,0 - The local offset of the joint relative to the entity's position.
* @property {Vec3} axis=1,0,0 - The axis of the entity that moves through the cone. Must be a non-zero vector.
- * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint.
* @property {Vec3} otherPivot=0,0,0 - The local offset of the joint relative to the other entity's position.
* @property {Vec3} otherAxis=1,0,0 - The axis of the other entity that moves through the cone. Must be a non-zero vector.
- * @property {number} swingSpan1=6.238 - The angle through which the joint can move in one axis of the cone, in radians.
- * @property {number} swingSpan2=6.238 - The angle through which the joint can move in the other axis of the cone, in radians.
- * @property {number} twistSpan=6.238 - The angle through with the joint can twist, in radians.
+ * @property {number} swingSpan1=2*Math.PI - The angle through which the joint can move in one axis of the cone, in radians.
+ * @property {number} swingSpan2=2*Math.PI - The angle through which the joint can move in the other axis of the cone, in
+ * radians.
+ * @property {number} twistSpan=2*Math.PI - The angle through with the joint can twist, in radians.
*/
QVariantMap ObjectConstraintConeTwist::getArguments() {
QVariantMap arguments = ObjectDynamic::getArguments();
diff --git a/libraries/physics/src/ObjectConstraintHinge.cpp b/libraries/physics/src/ObjectConstraintHinge.cpp
index 67573918cb..3059d82bf3 100644
--- a/libraries/physics/src/ObjectConstraintHinge.cpp
+++ b/libraries/physics/src/ObjectConstraintHinge.cpp
@@ -248,18 +248,19 @@ bool ObjectConstraintHinge::updateArguments(QVariantMap arguments) {
/**jsdoc
* The <code>"hinge"</code> {@link Entities.ActionType|ActionType} lets an entity pivot about an axis or connects two entities
* with a hinge joint.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-Hinge
+ * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint, if any. If none is
+ * specified then the first entity simply pivots about its specified <code>axis</code>.
* @property {Vec3} pivot=0,0,0 - The local offset of the joint relative to the entity's position.
* @property {Vec3} axis=1,0,0 - The axis of the entity that it pivots about. Must be a non-zero vector.
- * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint, if any. If none is
- * specified then the first entity simply pivots about its specified <code>axis</code>.
* @property {Vec3} otherPivot=0,0,0 - The local offset of the joint relative to the other entity's position.
* @property {Vec3} otherAxis=1,0,0 - The axis of the other entity that it pivots about. Must be a non-zero vector.
- * @property {number} low=-6.283 - The most negative angle that the hinge can take, in radians.
- * @property {number} high=6.283 - The most positive angle that the hinge can take, in radians.
- * @property {number} angle=0 - The current angle of the hinge. <em>Read-only.</em>
+ * @property {number} low=-2*Math.PI - The most negative angle that the hinge can take, in radians.
+ * @property {number} high=2*Math.PI - The most positive angle that the hinge can take, in radians.
+ * @property {number} angle=0 - The current angle of the hinge, in radians, range <code>-Math.PI</code> –
+ * <code>Math.PI</code>. <em>Read-only.</em>
*/
QVariantMap ObjectConstraintHinge::getArguments() {
QVariantMap arguments = ObjectDynamic::getArguments();
diff --git a/libraries/physics/src/ObjectConstraintSlider.cpp b/libraries/physics/src/ObjectConstraintSlider.cpp
index 7865e871de..11374298cf 100644
--- a/libraries/physics/src/ObjectConstraintSlider.cpp
+++ b/libraries/physics/src/ObjectConstraintSlider.cpp
@@ -264,27 +264,27 @@ bool ObjectConstraintSlider::updateArguments(QVariantMap arguments) {
/**jsdoc
* The <code>"slider"</code> {@link Entities.ActionType|ActionType} lets an entity slide and rotate along an axis, or connects
* two entities that slide and rotate along a shared axis.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
*
* @typedef {object} Entities.ActionArguments-Slider
+ * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint, if any. If none is
+ * specified then the first entity simply slides and rotates about its specified <code>axis</code>.
* @property {Vec3} point=0,0,0 - The local position of a point in the entity that slides along the axis.
* @property {Vec3} axis=1,0,0 - The axis of the entity that slides along the joint. Must be a non-zero vector.
- * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint, if any. If non is
- * specified then the first entity simply slides and rotates about its specified <code>axis</code>.
* @property {Vec3} otherPoint=0,0,0 - The local position of a point in the other entity that slides along the axis.
- * @property {Vec3} axis=1,0,0 - The axis of the other entity that slides along the joint. Must be a non-zero vector.
+ * @property {Vec3} otherAxis=1,0,0 - The axis of the other entity that slides along the joint. Must be a non-zero vector.
* @property {number} linearLow=1.17e-38 - The most negative linear offset from the entity's initial point that the entity can
* have along the slider.
* @property {number} linearHigh=3.40e+38 - The most positive linear offset from the entity's initial point that the entity can
* have along the slider.
- * @property {number} angularLow=-6.283 - The most negative angle that the entity can rotate about the axis if the action
+ * @property {number} angularLow=-2*Math.PI - The most negative angle that the entity can rotate about the axis if the action
* involves only one entity, otherwise the most negative angle the rotation can be between the two entities. In radians.
- * @property {number} angularHigh=6.283 - The most positive angle that the entity can rotate about the axis if the action
+ * @property {number} angularHigh=Math.PI - The most positive angle that the entity can rotate about the axis if the action
* involves only one entity, otherwise the most positive angle the rotation can be between the two entities. In radians.
* @property {number} linearPosition=0 - The current linear offset the entity is from its initial point if the action involves
* only one entity, otherwise the linear offset between the two entities' action points. <em>Read-only.</em>
* @property {number} angularPosition=0 - The current angular offset of the entity from its initial rotation if the action
- * involves only one entity, otherwise the angular offset between the two entities. <em>Read-only.</em>
+ * involves only one entity, otherwise the angular offset between the two entities. In radians. <em>Read-only.</em>
*/
QVariantMap ObjectConstraintSlider::getArguments() {
QVariantMap arguments = ObjectDynamic::getArguments();
diff --git a/libraries/physics/src/ObjectDynamic.cpp b/libraries/physics/src/ObjectDynamic.cpp
index 28323a8b92..ad070e296c 100644
--- a/libraries/physics/src/ObjectDynamic.cpp
+++ b/libraries/physics/src/ObjectDynamic.cpp
@@ -94,36 +94,36 @@ bool ObjectDynamic::updateArguments(QVariantMap arguments) {
}
/**jsdoc
-* Different entity action types have different arguments: some common to all actions (listed below) and some specific to each
-* {@link Entities.ActionType|ActionType} (linked to below). The arguments are accessed as an object of property names and
-* values.
-*
-* @typedef {object} Entities.ActionArguments
-* @property {Entities.ActionType} type - The type of action.
-* @property {string} tag="" - A string that a script can use for its own purposes.
-* @property {number} ttl=0 - How long the action should exist, in seconds, before it is automatically deleted. A value of
-* <code>0</code> means that the action should not be deleted.
-* @property {boolean} isMine=true - Is <code>true</code> if you created the action during your current Interface session,
-* <code>false</code> otherwise. <em>Read-only.</em>
-* @property {boolean} ::no-motion-state - Is present when the entity hasn't been registered with the physics engine yet (e.g.,
-* if the action hasn't been properly configured), otherwise <code>undefined</code>. <em>Read-only.</em>
-* @property {boolean} ::active - Is <code>true</code> when the action is modifying the entity's motion, <code>false</code>
-* otherwise. Is present once the entity has been registered with the physics engine, otherwise <code>undefined</code>.
-* <em>Read-only.</em>
-* @property {Entities.PhysicsMotionType} ::motion-type - How the entity moves with the action. Is present once the entity has
-* been registered with the physics engine, otherwise <code>undefined</code>. <em>Read-only.</em>
-*
-* @see The different action types have additional arguments as follows:
-* @see {@link Entities.ActionArguments-FarGrab|ActionArguments-FarGrab}
-* @see {@link Entities.ActionArguments-Hold|ActionArguments-Hold}
-* @see {@link Entities.ActionArguments-Offset|ActionArguments-Offset}
-* @see {@link Entities.ActionArguments-Tractor|ActionArguments-Tractor}
-* @see {@link Entities.ActionArguments-TravelOriented|ActionArguments-TravelOriented}
-* @see {@link Entities.ActionArguments-Hinge|ActionArguments-Hinge}
-* @see {@link Entities.ActionArguments-Slider|ActionArguments-Slider}
-* @see {@link Entities.ActionArguments-ConeTwist|ActionArguments-ConeTwist}
-* @see {@link Entities.ActionArguments-BallSocket|ActionArguments-BallSocket}
-*/
+ * Different entity action types have different arguments: some common to all actions (listed in the table) and some specific
+ * to each {@link Entities.ActionType|ActionType} (linked to below). The arguments are accessed as an object of property names
+ * and values.
+ *
+ * @typedef {object} Entities.ActionArguments
+ * @property {Entities.ActionType} type - The type of action.
+ * @property {string} tag="" - A string that a script can use for its own purposes.
+ * @property {number} ttl=0 - How long the action should exist, in seconds, before it is automatically deleted. A value of
+ * <code>0</code> means that the action should not be deleted.
+ * @property {boolean} isMine=true - Is <code>true</code> if you created the action during your current Interface session,
+ * <code>false</code> otherwise. <em>Read-only.</em>
+ * @property {boolean} ::no-motion-state - Is present when the entity hasn't been registered with the physics engine yet (e.g.,
+ * if the action hasn't been properly configured), otherwise <code>undefined</code>. <em>Read-only.</em>
+ * @property {boolean} ::active - Is <code>true</code> when the action is modifying the entity's motion, <code>false</code>
+ * otherwise. Is present once the entity has been registered with the physics engine, otherwise <code>undefined</code>.
+ * <em>Read-only.</em>
+ * @property {Entities.PhysicsMotionType} ::motion-type - How the entity moves with the action. Is present once the entity has
+ * been registered with the physics engine, otherwise <code>undefined</code>. <em>Read-only.</em>
+ *
+ * @comment The different action types have additional arguments as follows:
+ * @see {@link Entities.ActionArguments-FarGrab|ActionArguments-FarGrab}
+ * @see {@link Entities.ActionArguments-Hold|ActionArguments-Hold}
+ * @see {@link Entities.ActionArguments-Offset|ActionArguments-Offset}
+ * @see {@link Entities.ActionArguments-Tractor|ActionArguments-Tractor}
+ * @see {@link Entities.ActionArguments-TravelOriented|ActionArguments-TravelOriented}
+ * @see {@link Entities.ActionArguments-Hinge|ActionArguments-Hinge}
+ * @see {@link Entities.ActionArguments-Slider|ActionArguments-Slider}
+ * @see {@link Entities.ActionArguments-ConeTwist|ActionArguments-ConeTwist}
+ * @see {@link Entities.ActionArguments-BallSocket|ActionArguments-BallSocket}
+ */
// Note: The "type" property is set in EntityItem::getActionArguments().
QVariantMap ObjectDynamic::getArguments() {
QVariantMap arguments;
diff --git a/libraries/shared/src/SpatiallyNestable.cpp b/libraries/shared/src/SpatiallyNestable.cpp
index f49921f272..8387270905 100644
--- a/libraries/shared/src/SpatiallyNestable.cpp
+++ b/libraries/shared/src/SpatiallyNestable.cpp
@@ -1348,7 +1348,20 @@ SpatiallyNestablePointer SpatiallyNestable::findByID(QUuid id, bool& success) {
return parentWP.lock();
}
-
+/**jsdoc
+ * <p>An in-world item may be one of the following types:</p>
+ * <table>
+ * <thead>
+ * <tr><th>Value</th><th>Description</th></tr>
+ * </thead>
+ * <tbody>
+ * <tr><td><code>"entity"</code></td><td>The item is an entity.</td></tr>
+ * <tr><td><code>"avatar"</code></td><td>The item is an avatar.</td></tr>
+ * <tr><td><code>"unknown"</code></td><td>The item cannot be found.</td></tr>
+ * </tbody>
+ * </table>
+ * @typedef {string} Entities.NestableType
+ */
QString SpatiallyNestable::nestableTypeToString(NestableType nestableType) {
switch(nestableType) {
case NestableType::Entity:
From 0945bdaac7c30406b11bb418b0744f7cef4f5f8e Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Thu, 20 Jun 2019 15:11:01 +1200
Subject: [PATCH 06/13] Remainder of Entities methods' JSDoc
---
.../entities/src/EntityScriptingInterface.h | 430 +++++++++++-------
.../octree/src/OctreeScriptingInterface.h | 30 +-
libraries/script-engine/src/ScriptEngine.cpp | 3 +
libraries/shared/src/PointerEvent.cpp | 2 +-
4 files changed, 297 insertions(+), 168 deletions(-)
diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h
index 1a34fd2139..d38f2917a7 100644
--- a/libraries/entities/src/EntityScriptingInterface.h
+++ b/libraries/entities/src/EntityScriptingInterface.h
@@ -177,13 +177,12 @@ public:
public slots:
/**jsdoc
- * Check whether or not you can change the <code>locked</code> property of entities. Locked entities have their
- * <code>locked</code> property set to <code>true</code> and cannot be edited or deleted. Whether or not you can change
- * entities' <code>locked</code> properties is configured in the domain server's permissions.
+ * Checks whether or not the script can change the <code>locked</code> property of entities. Locked entities have their
+ * <code>locked</code> property set to <code>true</code> and cannot be edited or deleted.
* @function Entities.canAdjustLocks
- * @returns {boolean} <code>true</code> if the client can change the <code>locked</code> property of entities,
- * otherwise <code>false</code>.
- * @example <caption>Set an entity's <code>locked</code> property to true if you can.</caption>
+ * @returns {boolean} <code>true</code> if the domain server will allow the script to change the <code>locked</code>
+ * property of entities, otherwise <code>false</code>.
+ * @example <caption>Lock an entity if you can.</caption>
* if (Entities.canAdjustLocks()) {
* Entities.editEntity(entityID, { locked: true });
* } else {
@@ -193,42 +192,43 @@ public slots:
Q_INVOKABLE bool canAdjustLocks();
/**jsdoc
- * Check whether or not you can rez (create) new entities in the domain.
+ * Checks whether or not the script can rez (create) new entities in the domain.
* @function Entities.canRez
- * @returns {boolean} <code>true</code> if the domain server will allow the script to rez (create) new entities,
- * otherwise <code>false</code>.
+ * @returns {boolean} <code>true</code> if the domain server will allow the script to rez (create) new entities, otherwise
+ * <code>false</code>.
*/
Q_INVOKABLE bool canRez();
/**jsdoc
- * Check whether or not you can rez (create) new temporary entities in the domain. Temporary entities are entities with a
- * finite <code>lifetime</code> property value set.
+ * Checks whether or not the script can rez (create) new temporary entities in the domain. Temporary entities are entities
+ * with a finite <code>lifetime</code> property value set.
* @function Entities.canRezTmp
- * @returns {boolean} <code>true</code> if the domain server will allow the script to rez (create) new temporary
- * entities, otherwise <code>false</code>.
+ * @returns {boolean} <code>true</code> if the domain server will allow the script to rez (create) new temporary entities,
+ * otherwise <code>false</code>.
*/
Q_INVOKABLE bool canRezTmp();
/**jsdoc
- * Check whether or not you can rez (create) new certified entities in the domain. Certified entities are entities that have
- * PoP certificates.
+ * Checks whether or not the script can rez (create) new certified entities in the domain. Certified entities are entities
+ * that have PoP certificates.
* @function Entities.canRezCertified
- * @returns {boolean} <code>true</code> if the domain server will allow the script to rez (create) new certified
- * entities, otherwise <code>false</code>.
+ * @returns {boolean} <code>true</code> if the domain server will allow the script to rez (create) new certified entities,
+ * otherwise <code>false</code>.
*/
Q_INVOKABLE bool canRezCertified();
/**jsdoc
- * Check whether or not you can rez (create) new temporary certified entities in the domain. Temporary entities are entities
- * with a finite <code>lifetime</code> property value set. Certified entities are entities that have PoP certificates.
+ * Checks whether or not the script can rez (create) new temporary certified entities in the domain. Temporary entities are
+ * entities with a finite <code>lifetime</code> property value set. Certified entities are entities that have PoP
+ * certificates.
* @function Entities.canRezTmpCertified
- * @returns {boolean} <code>true</code> if the domain server will allow the script to rez (create) new temporary
- * certified entities, otherwise <code>false</code>.
+ * @returns {boolean} <code>true</code> if the domain server will allow the script to rez (create) new temporary certified
+ * entities, otherwise <code>false</code>.
*/
Q_INVOKABLE bool canRezTmpCertified();
/**jsdoc
- * Check whether or not you can make changes to the asset server's assets.
+ * Checks whether or not the script can make changes to the asset server's assets.
* @function Entities.canWriteAssets
* @returns {boolean} <code>true</code> if the domain server will allow the script to make changes to the asset server's
* assets, otherwise <code>false</code>.
@@ -236,7 +236,7 @@ public slots:
Q_INVOKABLE bool canWriteAssets();
/**jsdoc
- * Check whether or not you can replace the domain's content set.
+ * Checks whether or not the script can replace the domain's content set.
* @function Entities.canReplaceContent
* @returns {boolean} <code>true</code> if the domain server will allow the script to replace the domain's content set,
* otherwise <code>false</code>.
@@ -244,10 +244,10 @@ public slots:
Q_INVOKABLE bool canReplaceContent();
/**jsdoc
- * Check whether or not you can get and set private user data.
+ * Checks whether or not the script can get and set the <code>privateUserData</code> property of entities.
* @function Entities.canGetAndSetPrivateUserData
- * @returns {boolean} <code>true</code> if the domain server will allow the user to get and set private user data,
- * otherwise <code>false</code>.
+ * @returns {boolean} <code>true</code> if the domain server will allow the script to get and set the
+ * <code>privateUserData</code> property of entities, otherwise <code>false</code>.
*/
Q_INVOKABLE bool canGetAndSetPrivateUserData();
@@ -411,11 +411,13 @@ public slots:
/**jsdoc
* Gets an entity's script object. In particular, this is useful for accessing a {@link Entities.EntityProperties-Web|Web}
- * entity's event bridge.
+ * entity's HTML <code>EventBridge</code> script object to exchange messages with the web page script.
+ * <p>Alternatively, you can use {@link Entities.emitScriptEvent} and {@link Entities.webEventReceived} to exchange
+ * messages with a Web entity over its event bridge.</p>
* @function Entities.getEntityObject
* @param {Uuid} id - The ID of the entity to get the script object for.
* @returns {object} The script object for the entity if found.
- * @example <caption>Receive "hello" messages from a Web entity.</caption>
+ * @example <caption>Exchange messages with a Web entity.</caption>
* // HTML file, name: "webEntity.html".
* <!DOCTYPE html>
* <html>
@@ -425,10 +427,17 @@ public slots:
* <body>
* <h1>HELLO</h1></h1>
* <script>
- * setInterval(function () {
- * console.log("$$$$$$$ send");
+ * function onScriptEventReceived(message) {
+ * // Message received from the script.
+ * console.log("Message received: " + message);
+ * }
+ *
+ * EventBridge.scriptEventReceived.connect(onScriptEventReceived);
+ *
+ * setTimeout(function () {
+ * // Send a message to the script.
* EventBridge.emitWebEvent("hello");
- * }, 2000);
+ * }, 5000);
* </script>
* </body>
* </html>
@@ -439,17 +448,23 @@ public slots:
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -3 })),
* rotation: MyAvatar.orientation,
* sourceUrl: Script.resolvePath("webEntity.html"),
- * alpha: 1.0
+ * alpha: 1.0,
+ * lifetime: 300 // 5 min
* });
+ *
+ * var webEntityObject;
*
- * function onWebEventReceived(event) {
- * print("onWebEventReceived() : " + JSON.stringify(event));
+ * function onWebEventReceived(message) {
+ * // Message received.
+ * print("Message received: " + message);
+ *
+ * // Send a message back.
+ * webEntityObject.emitScriptEvent(message + " back");
* }
*
* Script.setTimeout(function () {
- * var entityObject = Entities.getEntityObject(webEntity);
- * print("$$$$ entityObject: " + entityObject);
- * entityObject.webEventReceived.connect(onWebEventReceived);
+ * webEntityObject = Entities.getEntityObject(webEntity);
+ * webEntityObject.webEventReceived.connect(onWebEventReceived);
* }, 500);
*
* Script.scriptEnding.connect(function () {
@@ -468,10 +483,10 @@ public slots:
Q_INVOKABLE bool isLoaded(const QUuid& id);
/**jsdoc
- * Check if there is an object of a given ID.
+ * Checks if there is an entity with a specified ID.
* @function Entities.isAddedEntity
* @param {Uuid} id - The ID to check.
- * @returns {boolean} <code>true</code> if an object with the given ID exists, <code>false</code> otherwise.
+ * @returns {boolean} <code>true</code> if an entity with the specified ID exists, <code>false</code> if it doesn't.
*/
Q_INVOKABLE bool isAddedEntity(const QUuid& id);
@@ -486,7 +501,7 @@ public slots:
Q_INVOKABLE QSizeF textSize(const QUuid& id, const QString& text);
/**jsdoc
- * Call a method in a client entity script from a client script or client entity script, or call a method in a server
+ * Calls a method in a client entity script from a client script or client entity script, or calls a method in a server
* entity script from a server entity script. The entity script method must be exposed as a property in the target client
* entity script. Additionally, if calling a server entity script, the server entity script must include the method's name
* in an exposed property called <code>remotelyCallable</code> that is an array of method names that can be called.
@@ -498,7 +513,7 @@ public slots:
Q_INVOKABLE void callEntityMethod(const QUuid& entityID, const QString& method, const QStringList& params = QStringList());
/**jsdoc
- * Call a method in a server entity script from a client script or client entity script. The entity script method must be
+ * Calls a method in a server entity script from a client script or client entity script. The entity script method must be
* exposed as a property in the target server entity script. Additionally, the target server entity script must include the
* method's name in an exposed property called <code>remotelyCallable</code> that is an array of method names that can be
* called.
@@ -510,7 +525,7 @@ public slots:
Q_INVOKABLE void callEntityServerMethod(const QUuid& entityID, const QString& method, const QStringList& params = QStringList());
/**jsdoc
- * Call a method in a specific user's client entity script from a server entity script. The entity script method must be
+ * Calls a method in a specific user's client entity script from a server entity script. The entity script method must be
* exposed as a property in the target client entity script.
* @function Entities.callEntityClientMethod
* @param {Uuid} clientSessionID - The session ID of the user to call the method in.
@@ -652,14 +667,14 @@ public slots:
Q_INVOKABLE bool reloadServerScripts(const QUuid& entityID);
/**jsdoc
- * Gets the status of server entity script attached to an entity
+ * Gets the status of a server entity script attached to an entity.
* @function Entities.getServerScriptStatus
- * @param {Uuid} entityID - The ID of the entity to get the server entity script status for.
+ * @param {Uuid} entityID - The ID of the entity to get the server entity script status of.
* @param {Entities~getServerScriptStatusCallback} callback - The function to call upon completion.
* @returns {boolean} <code>true</code> always.
*/
/**jsdoc
- * Called when {@link Entities.getServerScriptStatus} is complete.
+ * Called when a {@link Entities.getServerScriptStatus} call is complete.
* @callback Entities~getServerScriptStatusCallback
* @param {boolean} success - <code>true</code> if the server entity script status could be obtained, otherwise
* <code>false</code>.
@@ -703,18 +718,18 @@ public slots:
/**jsdoc
- * Set whether or not ray picks intersect the bounding box of {@link Entities.EntityProperties-Light|Light} entities. By
+ * Sets whether or not ray picks intersect the bounding box of {@link Entities.EntityProperties-Light|Light} entities. By
* default, Light entities are not intersected. The setting lasts for the Interface session. Ray picks are done using
- * {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
+ * {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
* @function Entities.setLightsArePickable
- * @param {boolean} value - Set <code>true</code> to make ray picks intersect the bounding box of
+ * @param {boolean} value - <code>true</code> to make ray picks intersect the bounding box of
* {@link Entities.EntityProperties-Light|Light} entities, otherwise <code>false</code>.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE void setLightsArePickable(bool value);
/**jsdoc
- * Get whether or not ray picks intersect the bounding box of {@link Entities.EntityProperties-Light|Light} entities. Ray
+ * Gets whether or not ray picks intersect the bounding box of {@link Entities.EntityProperties-Light|Light} entities. Ray
* picks are done using {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
* @function Entities.getLightsArePickable
* @returns {boolean} <code>true</code> if ray picks intersect the bounding box of
@@ -724,18 +739,18 @@ public slots:
Q_INVOKABLE bool getLightsArePickable() const;
/**jsdoc
- * Set whether or not ray picks intersect the bounding box of {@link Entities.EntityProperties-Zone|Zone} entities. By
- * default, Light entities are not intersected. The setting lasts for the Interface session. Ray picks are done using
+ * Sets whether or not ray picks intersect the bounding box of {@link Entities.EntityProperties-Zone|Zone} entities. By
+ * default, Zone entities are not intersected. The setting lasts for the Interface session. Ray picks are done using
* {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
* @function Entities.setZonesArePickable
- * @param {boolean} value - Set <code>true</code> to make ray picks intersect the bounding box of
+ * @param {boolean} value - <code>true</code> to make ray picks intersect the bounding box of
* {@link Entities.EntityProperties-Zone|Zone} entities, otherwise <code>false</code>.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE void setZonesArePickable(bool value);
/**jsdoc
- * Get whether or not ray picks intersect the bounding box of {@link Entities.EntityProperties-Zone|Zone} entities. Ray
+ * Gets whether or not ray picks intersect the bounding box of {@link Entities.EntityProperties-Zone|Zone} entities. Ray
* picks are done using {@link Entities.findRayIntersection|findRayIntersection}, or the {@link Picks} API.
* @function Entities.getZonesArePickable
* @returns {boolean} <code>true</code> if ray picks intersect the bounding box of
@@ -745,17 +760,17 @@ public slots:
Q_INVOKABLE bool getZonesArePickable() const;
/**jsdoc
- * Set whether or not {@link Entities.EntityProperties-Zone|Zone} entities' boundaries should be drawn. <em>Currently not
+ * Sets whether or not {@link Entities.EntityProperties-Zone|Zone} entities' boundaries should be drawn. <em>Currently not
* used.</em>
* @function Entities.setDrawZoneBoundaries
- * @param {boolean} value - Set to <code>true</code> if {@link Entities.EntityProperties-Zone|Zone} entities' boundaries
- * should be drawn, otherwise <code>false</code>.
+ * @param {boolean} value - <code>true</code> if {@link Entities.EntityProperties-Zone|Zone} entities' boundaries should be
+ * drawn, otherwise <code>false</code>.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE void setDrawZoneBoundaries(bool value);
/**jsdoc
- * Get whether or not {@link Entities.EntityProperties-Zone|Zone} entities' boundaries should be drawn. <em>Currently
+ * Gets whether or not {@link Entities.EntityProperties-Zone|Zone} entities' boundaries should be drawn. <em>Currently
* not used.</em>
* @function Entities.getDrawZoneBoundaries
* @returns {boolean} <code>true</code> if {@link Entities.EntityProperties-Zone|Zone} entities' boundaries should be
@@ -876,9 +891,9 @@ public slots:
Q_INVOKABLE bool setVoxelsInCuboid(const QUuid& entityID, const glm::vec3& lowPosition, const glm::vec3& cuboidSize, int value);
/**jsdoc
- * Convert voxel coordinates in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity to world coordinates. Voxel coordinates are
- * relative to the minimum axes values corner of the entity with a scale of <code>Vec3.ONE</code> being the dimensions of
- * each voxel.
+ * Converts voxel coordinates in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity to world coordinates. Voxel
+ * coordinates are relative to the minimum axes values corner of the entity with a scale of <code>Vec3.ONE</code> being the
+ * dimensions of each voxel.
* @function Entities.voxelCoordsToWorldCoords
* @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} voxelCoords - The voxel coordinates. May be fractional and outside the entity's bounding box.
@@ -911,21 +926,24 @@ public slots:
Q_INVOKABLE glm::vec3 voxelCoordsToWorldCoords(const QUuid& entityID, glm::vec3 voxelCoords);
/**jsdoc
- * Convert world coordinates to voxel coordinates in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity. Voxel coordinates are
- * relative to the minimum axes values corner of the entity, with a scale of <code>Vec3.ONE</code> being the dimensions of
- * each voxel.
+ * Converts world coordinates to voxel coordinates in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity. Voxel
+ * coordinates are relative to the minimum axes values corner of the entity, with a scale of <code>Vec3.ONE</code> being
+ * the dimensions of each voxel.
* @function Entities.worldCoordsToVoxelCoords
* @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} worldCoords - The world coordinates. May be outside the entity's bounding box.
* @returns {Vec3} The voxel coordinates of the <code>worldCoords</code> if the <code>entityID</code> is a
- * {@link Entities.EntityProperties-PolyVox|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}. The value may be fractional.
+ * {@link Entities.EntityProperties-PolyVox|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}. The value may be
+ * fractional and outside the entity's bounding box.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE glm::vec3 worldCoordsToVoxelCoords(const QUuid& entityID, glm::vec3 worldCoords);
/**jsdoc
- * Convert voxel coordinates in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity to local coordinates relative to the minimum
- * axes value corner of the entity, with the scale being the same as world coordinates.
+ * Converts voxel coordinates in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity to local coordinates. Local
+ * coordinates are relative to the minimum axes value corner of the entity, with the scale being the same as world
+ * coordinates. Voxel coordinates are relative to the minimum axes values corner of the entity, with a scale of
+ * <code>Vec3.ONE</code> being the dimensions of each voxel.
* @function Entities.voxelCoordsToLocalCoords
* @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} voxelCoords - The voxel coordinates. May be fractional and outside the entity's bounding box.
@@ -946,13 +964,16 @@ public slots:
Q_INVOKABLE glm::vec3 voxelCoordsToLocalCoords(const QUuid& entityID, glm::vec3 voxelCoords);
/**jsdoc
- * Convert local coordinates to voxel coordinates in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity. Local coordinates are
- * relative to the minimum axes value corner of the entity, with the scale being the same as world coordinates.
+ * Converts local coordinates to voxel coordinates in a {@link Entities.EntityProperties-PolyVox|PolyVox} entity. Local
+ * coordinates are relative to the minimum axes value corner of the entity, with the scale being the same as world
+ * coordinates. Voxel coordinates are relative to the minimum axes values corner of the entity, with a scale of
+ * <code>Vec3.ONE</code> being the dimensions of each voxel.
* @function Entities.localCoordsToVoxelCoords
* @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-PolyVox|PolyVox} entity.
* @param {Vec3} localCoords - The local coordinates. May be outside the entity's bounding box.
* @returns {Vec3} The voxel coordinates of the <code>worldCoords</code> if the <code>entityID</code> is a
- * {@link Entities.EntityProperties-PolyVox|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}. The value may be fractional.
+ * {@link Entities.EntityProperties-PolyVox|PolyVox} entity, otherwise {@link Vec3(0)|Vec3.ZERO}. The value may be
+ * fractional and outside the entity's bounding box.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE glm::vec3 localCoordsToVoxelCoords(const QUuid& entityID, glm::vec3 localCoords);
@@ -1020,7 +1041,8 @@ public slots:
Q_INVOKABLE bool appendPoint(const QUuid& entityID, const glm::vec3& point);
/**jsdoc
- * Dumps debug information about all entities in Interface's local in-memory tree of entities it knows about to the program log.
+ * Dumps debug information about all entities in Interface's local in-memory tree of entities it knows about to the program
+ * log.
* @function Entities.dumpTree
*/
Q_INVOKABLE void dumpTree() const;
@@ -1125,7 +1147,7 @@ public slots:
* @example <caption>Compare the local and absolute rotations of an avatar model's left hand joint.</caption>
* entityID = Entities.addEntity({
* type: "Model",
- * modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
+ * modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* lifetime: 300 // Delete after 5 minutes.
@@ -1170,7 +1192,7 @@ public slots:
* @example <caption>Raise an avatar model's left palm.</caption>
* entityID = Entities.addEntity({
* type: "Model",
- * modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
+ * modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* lifetime: 300 // Delete after 5 minutes.
@@ -1210,7 +1232,7 @@ public slots:
* @example <caption>Report the local rotation of an avatar model's head joint.</caption>
* entityID = Entities.addEntity({
* type: "Model",
- * modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
+ * modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* lifetime: 300 // Delete after 5 minutes.
@@ -1251,7 +1273,7 @@ public slots:
* @example <caption>Make an avatar model turn its head left.</caption>
* entityID = Entities.addEntity({
* type: "Model",
- * modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
+ * modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* lifetime: 300 // Delete after 5 minutes.
@@ -1292,7 +1314,7 @@ public slots:
* @example <caption>Raise both palms of an avatar model.</caption>
* entityID = Entities.addEntity({
* type: "Model",
- * modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
+ * modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* lifetime: 300 // Delete after 5 minutes.
@@ -1352,7 +1374,7 @@ public slots:
* @example <caption>Report the index of a model's head joint.</caption>
* entityID = Entities.addEntity({
* type: "Model",
- * modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
+ * modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* lifetime: 300 // Delete after 5 minutes.
@@ -1377,7 +1399,7 @@ public slots:
* @example <caption>Report a model's joint names.</caption>
* entityID = Entities.addEntity({
* type: "Model",
- * modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
+ * modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* lifetime: 300 // Delete after 5 minutes.
@@ -1522,7 +1544,7 @@ public slots:
Q_INVOKABLE void setKeyboardFocusEntity(const QUuid& id);
/**jsdoc
- * Emit a {@link Entities.mousePressOnEntity|mousePressOnEntity} event.
+ * Emits a {@link Entities.mousePressOnEntity|mousePressOnEntity} event.
* @function Entities.sendMousePressOnEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1530,7 +1552,7 @@ public slots:
Q_INVOKABLE void sendMousePressOnEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Emit a {@link Entities.mouseMoveOnEntity|mouseMoveOnEntity} event.
+ * Emits a {@link Entities.mouseMoveOnEntity|mouseMoveOnEntity} event.
* @function Entities.sendMouseMoveOnEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1538,7 +1560,7 @@ public slots:
Q_INVOKABLE void sendMouseMoveOnEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Emit a {@link Entities.mouseReleaseOnEntity|mouseReleaseOnEntity} event.
+ * Emits a {@link Entities.mouseReleaseOnEntity|mouseReleaseOnEntity} event.
* @function Entities.sendMouseReleaseOnEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1546,7 +1568,7 @@ public slots:
Q_INVOKABLE void sendMouseReleaseOnEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Emit a {@link Entities.clickDownOnEntity|clickDownOnEntity} event.
+ * Emits a {@link Entities.clickDownOnEntity|clickDownOnEntity} event.
* @function Entities.sendClickDownOnEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1554,7 +1576,7 @@ public slots:
Q_INVOKABLE void sendClickDownOnEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Emit a {@link Entities.holdingClickOnEntity|holdingClickOnEntity} event.
+ * Emits a {@link Entities.holdingClickOnEntity|holdingClickOnEntity} event.
* @function Entities.sendHoldingClickOnEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1562,7 +1584,7 @@ public slots:
Q_INVOKABLE void sendHoldingClickOnEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Emit a {@link Entities.clickReleaseOnEntity|clickReleaseOnEntity} event.
+ * Emits a {@link Entities.clickReleaseOnEntity|clickReleaseOnEntity} event.
* @function Entities.sendClickReleaseOnEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1570,7 +1592,7 @@ public slots:
Q_INVOKABLE void sendClickReleaseOnEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Emit a {@link Entities.hoverEnterEntity|hoverEnterEntity} event.
+ * Emits a {@link Entities.hoverEnterEntity|hoverEnterEntity} event.
* @function Entities.sendHoverEnterEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1578,7 +1600,7 @@ public slots:
Q_INVOKABLE void sendHoverEnterEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Emit a {@link Entities.hoverOverEntity|hoverOverEntity} event.
+ * Emits a {@link Entities.hoverOverEntity|hoverOverEntity} event.
* @function Entities.sendHoverOverEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1586,7 +1608,7 @@ public slots:
Q_INVOKABLE void sendHoverOverEntity(const EntityItemID& id, const PointerEvent& event);
/**jsdoc
- * Emit a {@link Entities.hoverLeaveEntity|hoverLeaveEntity} event.
+ * Emits a {@link Entities.hoverLeaveEntity|hoverLeaveEntity} event.
* @function Entities.sendHoverLeaveEntity
* @param {Uuid} entityID - The ID of the entity to emit the event for.
* @param {PointerEvent} event - The event details.
@@ -1604,21 +1626,74 @@ public slots:
Q_INVOKABLE bool wantsHandControllerPointerEvents(const QUuid& id);
/**jsdoc
- * Send a script event over a {@link Entities.EntityProperties-Web|Web} entity's <code>EventBridge</code> to the Web page's scripts.
+ * Sends a message to a {@link Entities.EntityProperties-Web|Web} entity's HTML page. To receive the message, the web
+ * page's script must connect to the <code>EventBridge</code> that is automatically provided to the script:
+ * <pre class="prettyprint"><code>EventBridge.scriptEventReceived.connect(function(message) {
+ * ...
+ * });</code></pre>
+ * <p>Use {@link Entities.webEventReceived} to receive messages from the Web entity's HTML page.</p>
+ * <p>Alternatively, you can use {@link Entities.getEntityObject} to exchange messages over a Web entity's HTML event
+ * bridge.</p>
* @function Entities.emitScriptEvent
- * @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-Web|Web} entity.
+ * @param {Uuid} entityID - The ID of the Web entity to send the message to.
* @param {string} message - The message to send.
+ * @example <caption>Exchange messages with a Web entity.</caption>
+ * // HTML file, name: "webEntity.html".
+ * <!DOCTYPE html>
+ * <html>
+ * <head>
+ * <title>HELLO</title>
+ * </head>
+ * <body>
+ * <h1>HELLO</h1></h1>
+ * <script>
+ * function onScriptEventReceived(message) {
+ * // Message received from the script.
+ * console.log("Message received: " + message);
+ * }
+ *
+ * EventBridge.scriptEventReceived.connect(onScriptEventReceived);
+ *
+ * setTimeout(function () {
+ * // Send a message to the script.
+ * EventBridge.emitWebEvent("hello");
+ * }, 5000);
+ * </script>
+ * </body>
+ * </html>
+ *
+ * // Script file.
+ * var webEntity = Entities.addEntity({
+ * type: "Web",
+ * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -3 })),
+ * rotation: MyAvatar.orientation,
+ * sourceUrl: Script.resolvePath("webEntity.html"),
+ * alpha: 1.0,
+ * lifetime: 300 // 5 min
+ * });
+ *
+ * function onWebEventReceived(entityID, message) {
+ * if (entityID === webEntity) {
+ * // Message received.
+ * print("Message received: " + message);
+ *
+ * // Send a message back.
+ * Entities.emitScriptEvent(webEntity, message + " back");
+ * }
+ * }
+ *
+ * Entities.webEventReceived.connect(onWebEventReceived);
*/
Q_INVOKABLE void emitScriptEvent(const EntityItemID& entityID, const QVariant& message);
/**jsdoc
- * Check whether an axis-aligned box and a capsule intersect.
+ * Checks whether an axis-aligned box and a capsule intersect.
* @function Entities.AABoxIntersectsCapsule
* @param {Vec3} brn - The bottom right near (minimum axes values) corner of the AA box.
* @param {Vec3} dimensions - The dimensions of the AA box.
* @param {Vec3} start - One end of the capsule.
* @param {Vec3} end - The other end of the capsule.
- * @param {number} radius - The radiues of the capsule.
+ * @param {number} radius - The radius of the capsule.
* @returns {boolean} <code>true</code> if the AA box and capsule intersect, otherwise <code>false</code>.
*/
Q_INVOKABLE bool AABoxIntersectsCapsule(const glm::vec3& low, const glm::vec3& dimensions,
@@ -1709,123 +1784,174 @@ public slots:
/**jsdoc
+ * Converts a position in world coordinates to a position in an avatar, entity, or joint's local coordinates.
* @function Entities.worldToLocalPosition
- * @param {Vec3} worldPosition
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Vec3}
+ * @param {Vec3} worldPosition - The world position to convert.
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - The joint in the avatar or entity that the local coordinates are based on. If
+ * <code>-1</code> then no joint is used and the local coordinates are based solely on the avatar or entity.
+ * @param {boolean} [scalesWithParent= false] - <code>true</code> to scale the local position per the parent's scale,
+ * <code>false</code> for the local position to be at world scale.
+ * @returns {Vec3} The position converted to local coordinates if successful, otherwise {@link Vec3(0)|Vec3.ZERO}.
+ * @example <caption>Report the local coordinates of an entity parented to another.</caption>
+ * var parentPosition = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 }));
+ * var childPosition = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 1, z: -5 }));
+ *
+ * var parentEntity = Entities.addEntity({
+ * type: "Box",
+ * position: parentPosition,
+ * rotation: MyAvatar.orientation,
+ * dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+ * lifetime: 300 // Delete after 5 minutes.
+ * });
+ * var childEntity = Entities.addEntity({
+ * type: "Sphere",
+ * position: childPosition,
+ * dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+ * parentID: parentEntity,
+ * lifetime: 300 // Delete after 5 minutes.
+ * });
+ *
+ * var localPosition = Entities.worldToLocalPosition(childPosition, parentEntity);
+ * print("Local position: " + JSON.stringify(localPosition)); // 0, 1, 0.
+ * localPosition = Entities.getEntityProperties(childEntity, "localPosition").localPosition;
+ * print("Local position: " + JSON.stringify(localPosition)); // The same.
*/
Q_INVOKABLE glm::vec3 worldToLocalPosition(glm::vec3 worldPosition, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts a rotation or orientation in world coordinates to rotation in an avatar, entity, or joint's local coordinates.
* @function Entities.worldToLocalRotation
- * @param {Quat} worldRotation
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Quat}
+ * @param {Quat} worldRotation - The world rotation to convert.
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - The joint in the avatar or entity that the local coordinates are based on. If
+ * <code>-1</code> then no joint is used and the local coordinates are based solely on the avatar or entity.
+ * @param {boolean} [scalesWithParent=false] - <em>Not used in the calculation.</em>
+ * @returns {Quat} The rotation converted to local coordinates if successful, otherwise {@link Quat(0)|Quat.IDENTITY}.
*/
Q_INVOKABLE glm::quat worldToLocalRotation(glm::quat worldRotation, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts a velocity in world coordinates to a velocity in an avatar, entity, or joint's local coordinates.
* @function Entities.worldToLocalVelocity
- * @param {Vec3} worldVelocity
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Vec3}
+ * @param {Vec3} worldVelocity - The world velocity to convert.
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - The joint in the avatar or entity that the local coordinates are based on. If
+ * <code>-1</code> then no joint is used and the local coordinates are based solely on the avatar or entity.
+ * @param {boolean} [scalesWithParent=false] - <code>true</code> to scale the local velocity per the parent's scale,
+ * <code>false</code> for the local velocity to be at world scale.
+ * @returns {Vec3} The velocity converted to local coordinates if successful, otherwise {@link Vec3(0)|Vec3.ZERO}.
*/
Q_INVOKABLE glm::vec3 worldToLocalVelocity(glm::vec3 worldVelocity, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts a Euler angular velocity in world coordinates to an angular velocity in an avatar, entity, or joint's local
+ * coordinates.
* @function Entities.worldToLocalAngularVelocity
- * @param {Vec3} worldAngularVelocity
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Vec3}
+ * @param {Vec3} worldAngularVelocity - The world Euler angular velocity to convert. (Can be in any unit, e.g., deg/s or
+ * rad/s.)
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - The joint in the avatar or entity that the local coordinates are based on. If
+ * <code>-1</code> then no joint is used and the local coordinates are based solely on the avatar or entity.
+ * @param {boolean} [scalesWithParent=false] - <em>Not used in the calculation.</em>
+ * @returns {Vec3} The angular velocity converted to local coordinates if successful, otherwise {@link Vec3(0)|Vec3.ZERO}.
*/
Q_INVOKABLE glm::vec3 worldToLocalAngularVelocity(glm::vec3 worldAngularVelocity, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts dimensions in world coordinates to dimensions in an avatar or entity's local coordinates.
* @function Entities.worldToLocalDimensions
- * @param {Vec3} worldDimensions
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Vec3}
+ * @param {Vec3} worldDimensions - The world dimensions to convert.
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - <em>Not used in the calculation.</em>
+ * @param {boolean} [scalesWithParent=false] - <code>true</code> to scale the local dimensions per the parent's scale,
+ * <code>false</code> for the local dimensions to be at world scale.
+ * @returns {Vec3} The dimensions converted to local coordinates if successful, otherwise {@link Vec3(0)|Vec3.ZERO}.
*/
Q_INVOKABLE glm::vec3 worldToLocalDimensions(glm::vec3 worldDimensions, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts a position in an avatar, entity, or joint's local coordinate to a position in world coordinates.
* @function Entities.localToWorldPosition
- * @param {Vec3} localPosition
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Vec3}
+ * @param {Vec3} localPosition - The local position to convert.
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - The joint in the avatar or entity that the local coordinates are based on. If
+ * <code>-1</code> then no joint is used and the local coordinates are based solely on the avatar or entity.
+ * @param {boolean} [scalesWithparent=false] - <code>true</code> if the local dimensions are scaled per the parent's scale,
+ * <code>false</code> if the local dimensions are at world scale.
+ * @returns {Vec3} The position converted to world coordinates if successful, otherwise {@link Vec3(0)|Vec3.ZERO}.
*/
Q_INVOKABLE glm::vec3 localToWorldPosition(glm::vec3 localPosition, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts a rotation or orientation in an avatar, entity, or joint's local coordinate to a rotation in world coordinates.
* @function Entities.localToWorldRotation
- * @param {Quat} localRotation
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Quat}
+ * @param {Quat} localRotation - The local rotation to convert.
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - The joint in the avatar or entity that the local coordinates are based on. If
+ * <code>-1</code> then no joint is used and the local coordinates are based solely on the avatar or entity.
+ * @param {boolean} [scalesWithParent= false] - <em>Not used in the calculation.</em>
+ * @returns {Quat} The rotation converted to local coordinates if successful, otherwise {@link Quat(0)|Quat.IDENTITY}.
*/
Q_INVOKABLE glm::quat localToWorldRotation(glm::quat localRotation, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts a velocity in an avatar, entity, or joint's local coordinate to a velocity in world coordinates.
* @function Entities.localToWorldVelocity
- * @param {Vec3} localVelocity
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Vec3}
+ * @param {Vec3} localVelocity - The local velocity to convert.
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - The joint in the avatar or entity that the local coordinates are based on. If
+ * <code>-1</code> then no joint is used and the local coordinates are based solely on the avatar or entity.
+ * @param {boolean} [scalesWithParent= false] - <code>true</code> if the local velocity is scaled per the parent's scale,
+ * <code>false</code> if the local velocity is at world scale.
+ * @returns {Vec3} The velocity converted to world coordinates it successful, otherwise {@link Vec3(0)|Vec3.ZERO}.
*/
Q_INVOKABLE glm::vec3 localToWorldVelocity(glm::vec3 localVelocity, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts a Euler angular velocity in an avatar, entity, or joint's local coordinate to an angular velocity in world
+ * coordinates.
* @function Entities.localToWorldAngularVelocity
- * @param {Vec3} localAngularVelocity
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Vec3}
+ * @param {Vec3} localAngularVelocity - The local Euler angular velocity to convert. (Can be in any unit, e.g., deg/s or
+ * rad/s.)
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - The joint in the avatar or entity that the local coordinates are based on. If
+ * <code>-1</code> then no joint is used and the local coordinates are based solely on the avatar or entity.
+ * @param {boolean} [scalesWithParent= false] - <em>Not used in the calculation.</em>
+ * @returns {Vec3} The angular velocity converted to world coordinates if successful, otherwise {@link Vec3(0)|Vec3.ZERO}.
*/
Q_INVOKABLE glm::vec3 localToWorldAngularVelocity(glm::vec3 localAngularVelocity, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
+ * Converts dimensions in an avatar or entity's local coordinates to dimensions in world coordinates.
* @function Entities.localToWorldDimensions
- * @param {Vec3} localDimensions
- * @param {Uuid} parentID
- * @param {number} parentJointIndex
- * @param {boolean} scalesWithparent
- * @returns {Vec3}
+ * @param {Vec3} localDimensions - The local dimensions to convert.
+ * @param {Uuid} parentID - The avatar or entity that the local coordinates are based on.
+ * @param {number} [parentJointIndex=-1] - <em>Not used in the calculation.</em>
+ * @param {boolean} [scalesWithParent= false] - <code>true</code> if the local dimensions are scaled per the parent's
+ * scale, <code>false</code> if the local dimensions are at world scale.
+ * @returns {Vec3} The dimensions converted to world coordinates if successful, otherwise {@link Vec3(0)|Vec3.ZERO}.
*/
Q_INVOKABLE glm::vec3 localToWorldDimensions(glm::vec3 localDimensions, const QUuid& parentID,
int parentJointIndex = -1, bool scalesWithParent = false);
/**jsdoc
- * Get the static certificate for an entity. The static certificate contains static properties of the item which cannot
- * be altered.
- * @function Entities.getStaticCertificateJSON
- * @param {Uuid} entityID - The ID of the entity to get the static certificate for.
- * @returns {string} The entity's static certificate as a JSON string if the entity can be found, otherwise an empty string.
- */
+ * Gets the static certificate for an entity. The static certificate contains static properties of the item which cannot
+ * be altered.
+ * @function Entities.getStaticCertificateJSON
+ * @param {Uuid} entityID - The ID of the entity to get the static certificate for.
+ * @returns {string} The entity's static certificate as a JSON string if the entity can be found, otherwise <code>""</code>.
+ */
Q_INVOKABLE QString getStaticCertificateJSON(const QUuid& entityID);
/**jsdoc
- * Verify the entity's proof of provenance, i.e., that the entity's <code>certificateID</code> property was produced by
+ * Verifies the entity's proof of provenance, i.e., that the entity's <code>certificateID</code> property was produced by
* High Fidelity signing the entity's static certificate JSON.
* @function Entities.verifyStaticCertificateProperties
* @param {Uuid} entityID - The ID of the entity to verify.
- * @returns {boolean} <code>true</code> if the entity can be found an its <code>certificateID</code> property is present
- * and its value matches the entity's static certificate JSON; otherwise <code>false</code>.
+ * @returns {boolean} <code>true</code> if the entity can be found, its <code>certificateID</code> property is present, and
+ * its value matches the entity's static certificate JSON; otherwise <code>false</code>.
*/
Q_INVOKABLE bool verifyStaticCertificateProperties(const QUuid& entityID);
@@ -1960,7 +2086,7 @@ signals:
* pressed while its laser is on an entity.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.mousePressOnEntity
- * @param {Uuid} entityID - The ID of the entity that was pressed.
+ * @param {Uuid} entityID - The ID of the entity that was pressed on.
* @param {PointerEvent} event - Details of the event.
* @returns {Signal}
* @example <caption>Report when an entity is clicked with the mouse or laser.</caption>
@@ -1975,7 +2101,7 @@ signals:
/**jsdoc
* Triggered when a mouse button is double-clicked while the mouse cursor is on an entity.
* @function Entities.mouseDoublePressOnEntity
- * @param {Uuid} entityID - The ID of the entity that was double-pressed.
+ * @param {Uuid} entityID - The ID of the entity that was double-pressed on.
* @param {PointerEvent} event - Details of the event.
* @returns {Signal}
*/
@@ -2023,7 +2149,7 @@ signals:
* Triggered when a mouse button is clicked while the mouse cursor is on an entity. Note: Not triggered by controller.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.clickDownOnEntity
- * @param {Uuid} entityID - The ID of the entity that was clicked.
+ * @param {Uuid} entityID - The ID of the entity that was clicked on.
* @param {PointerEvent} event - Details of the event.
* @returns {Signal}
*/
diff --git a/libraries/octree/src/OctreeScriptingInterface.h b/libraries/octree/src/OctreeScriptingInterface.h
index e501dd166a..c7b0552511 100644
--- a/libraries/octree/src/OctreeScriptingInterface.h
+++ b/libraries/octree/src/OctreeScriptingInterface.h
@@ -37,7 +37,7 @@ private slots:
public slots:
/**jsdoc
- * Set the maximum number of entity packets that the client can send per second.
+ * Sets the maximum number of entity packets that the client can send per second.
* @function Entities.setPacketsPerSecond
* @param {number} packetsPerSecond - Integer maximum number of entity packets that the client can send per second.
*/
@@ -45,7 +45,7 @@ public slots:
void setPacketsPerSecond(int packetsPerSecond) { return _packetSender->setPacketsPerSecond(packetsPerSecond); }
/**jsdoc
- * Get the maximum number of entity packets that the client can send per second.
+ * Gets the maximum number of entity packets that the client can send per second.
* @function Entities.getPacketsPerSecond
* @returns {number} Integer maximum number of entity packets that the client can send per second.
*/
@@ -53,7 +53,7 @@ public slots:
int getPacketsPerSecond() const { return _packetSender->getPacketsPerSecond(); }
/**jsdoc
- * Check whether servers exist for the client to send entity packets to, i.e., whether you are connected to a domain and
+ * Checks whether servers exist for the client to send entity packets to, i.e., whether you are connected to a domain and
* its entity server is working.
* @function Entities.serversExist
* @returns {boolean} <code>true</code> if servers exist for the client to send entity packets to, otherwise
@@ -63,7 +63,7 @@ public slots:
bool serversExist() const { return _packetSender->serversExist(); }
/**jsdoc
- * Check whether the client has entity packets waiting to be sent.
+ * Checks whether the client has entity packets waiting to be sent.
* @function Entities.hasPacketsToSend
* @returns {boolean} <code>true</code> if the client has entity packets waiting to be sent, otherwise <code>false</code>.
*/
@@ -71,7 +71,7 @@ public slots:
bool hasPacketsToSend() const { return _packetSender->hasPacketsToSend(); }
/**jsdoc
- * Get the number of entity packets the client has waiting to be sent.
+ * Gets the number of entity packets the client has waiting to be sent.
* @function Entities.packetsToSendCount
* @returns {number} Integer number of entity packets the client has waiting to be sent.
*/
@@ -79,7 +79,7 @@ public slots:
int packetsToSendCount() const { return (int)_packetSender->packetsToSendCount(); }
/**jsdoc
- * Get the entity packets per second send rate of the client over its lifetime.
+ * Gets the entity packets per second send rate of the client over its lifetime.
* @function Entities.getLifetimePPS
* @returns {number} Entity packets per second send rate of the client over its lifetime.
*/
@@ -87,7 +87,7 @@ public slots:
float getLifetimePPS() const { return _packetSender->getLifetimePPS(); }
/**jsdoc
- * Get the entity bytes per second send rate of the client over its lifetime.
+ * Gets the entity bytes per second send rate of the client over its lifetime.
* @function Entities.getLifetimeBPS
* @returns {number} Entity bytes per second send rate of the client over its lifetime.
*/
@@ -95,7 +95,7 @@ public slots:
float getLifetimeBPS() const { return _packetSender->getLifetimeBPS(); }
/**jsdoc
- * Get the entity packets per second queued rate of the client over its lifetime.
+ * Gets the entity packets per second queued rate of the client over its lifetime.
* @function Entities.getLifetimePPSQueued
* @returns {number} Entity packets per second queued rate of the client over its lifetime.
*/
@@ -103,7 +103,7 @@ public slots:
float getLifetimePPSQueued() const { return _packetSender->getLifetimePPSQueued(); }
/**jsdoc
- * Get the entity bytes per second queued rate of the client over its lifetime.
+ * Gets the entity bytes per second queued rate of the client over its lifetime.
* @function Entities.getLifetimeBPSQueued
* @returns {number} Entity bytes per second queued rate of the client over its lifetime.
*/
@@ -111,7 +111,7 @@ public slots:
float getLifetimeBPSQueued() const { return _packetSender->getLifetimeBPSQueued(); }
/**jsdoc
- * Get the lifetime of the client from the first entity packet sent until now, in microseconds.
+ * Gets the lifetime of the client from the first entity packet sent until now, in microseconds.
* @function Entities.getLifetimeInUsecs
* @returns {number} Lifetime of the client from the first entity packet sent until now, in microseconds.
*/
@@ -119,7 +119,7 @@ public slots:
long long unsigned int getLifetimeInUsecs() const { return _packetSender->getLifetimeInUsecs(); }
/**jsdoc
- * Get the lifetime of the client from the first entity packet sent until now, in seconds.
+ * Gets the lifetime of the client from the first entity packet sent until now, in seconds.
* @function Entities.getLifetimeInSeconds
* @returns {number} Lifetime of the client from the first entity packet sent until now, in seconds.
*/
@@ -127,7 +127,7 @@ public slots:
float getLifetimeInSeconds() const { return _packetSender->getLifetimeInSeconds(); }
/**jsdoc
- * Get the total number of entity packets sent by the client over its lifetime.
+ * Gets the total number of entity packets sent by the client over its lifetime.
* @function Entities.getLifetimePacketsSent
* @returns {number} The total number of entity packets sent by the client over its lifetime.
*/
@@ -135,7 +135,7 @@ public slots:
long long unsigned int getLifetimePacketsSent() const { return _packetSender->getLifetimePacketsSent(); }
/**jsdoc
- * Get the total bytes of entity packets sent by the client over its lifetime.
+ * Gets the total bytes of entity packets sent by the client over its lifetime.
* @function Entities.getLifetimeBytesSent
* @returns {number} The total bytes of entity packets sent by the client over its lifetime.
*/
@@ -143,7 +143,7 @@ public slots:
long long unsigned int getLifetimeBytesSent() const { return _packetSender->getLifetimeBytesSent(); }
/**jsdoc
- * Get the total number of entity packets queued by the client over its lifetime.
+ * Gets the total number of entity packets queued by the client over its lifetime.
* @function Entities.getLifetimePacketsQueued
* @returns {number} The total number of entity packets queued by the client over its lifetime.
*/
@@ -151,7 +151,7 @@ public slots:
long long unsigned int getLifetimePacketsQueued() const { return _packetSender->getLifetimePacketsQueued(); }
/**jsdoc
- * Get the total bytes of entity packets queued by the client over its lifetime.
+ * Gets the total bytes of entity packets queued by the client over its lifetime.
* @function Entities.getLifetimeBytesQueued
* @returns {number} The total bytes of entity packets queued by the client over its lifetime.
*/
diff --git a/libraries/script-engine/src/ScriptEngine.cpp b/libraries/script-engine/src/ScriptEngine.cpp
index 9d29f32931..d820f0cb0f 100644
--- a/libraries/script-engine/src/ScriptEngine.cpp
+++ b/libraries/script-engine/src/ScriptEngine.cpp
@@ -2200,6 +2200,7 @@ void ScriptEngine::loadEntityScript(const EntityItemID& entityID, const QString&
* lifetime: 300 // Delete after 5 minutes.
* });
*/
+// The JSDoc is for the callEntityScriptMethod() call in this method.
// since all of these operations can be asynch we will always do the actual work in the response handler
// for the download
void ScriptEngine::entityScriptContentAvailable(const EntityItemID& entityID, const QString& scriptOrURL, const QString& contents, bool isURL, bool success , const QString& status) {
@@ -2384,8 +2385,10 @@ void ScriptEngine::entityScriptContentAvailable(const EntityItemID& entityID, co
* <p>Note: Can only be connected to via <code>this.unoad = function () { ... }</code> in the entity script.</p>
* <table><tr><th>Available in:</th><td>Client Entity Scripts</td><td>Server Entity Scripts</td></tr></table>
* @function Entities.unload
+ * @param {Uuid} entityID - The ID of the entity that the script is running in.
* @returns {Signal}
*/
+// The JSDoc is for the callEntityScriptMethod() call in this method.
void ScriptEngine::unloadEntityScript(const EntityItemID& entityID, bool shouldRemoveFromMap) {
if (QThread::currentThread() != thread()) {
#ifdef THREAD_DEBUGGING
diff --git a/libraries/shared/src/PointerEvent.cpp b/libraries/shared/src/PointerEvent.cpp
index 69d3f28d80..54374a934c 100644
--- a/libraries/shared/src/PointerEvent.cpp
+++ b/libraries/shared/src/PointerEvent.cpp
@@ -66,7 +66,7 @@ void PointerEvent::setButton(Button button) {
}
/**jsdoc
- * A PointerEvent defines a 2D or 3D mouse or similar pointer event.
+ * A 2D or 3D mouse or similar pointer event.
* @typedef {object} PointerEvent
* @property {string} type - The type of event: <code>"Press"</code>, <code>"DoublePress"</code>, <code>"Release"</code>, or
* <code>"Move"</code>.
From a858314898b3a5a12fb53775d122694b0019d566 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Fri, 21 Jun 2019 11:25:10 +1200
Subject: [PATCH 07/13] Remainder of Entities signals' JSDoc
---
.../entities/src/EntityScriptingInterface.h | 133 ++++++++++--------
1 file changed, 77 insertions(+), 56 deletions(-)
diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h
index d38f2917a7..dc0039f0f5 100644
--- a/libraries/entities/src/EntityScriptingInterface.h
+++ b/libraries/entities/src/EntityScriptingInterface.h
@@ -1968,7 +1968,6 @@ public slots:
signals:
/**jsdoc
- * #######<br />
* Triggered on the client that is the physics simulation owner during the collision of two entities. Note: Isn't triggered
* for a collision with an avatar.
* <p>See also, {@link Script.addEventHandler}.</p>
@@ -2014,7 +2013,7 @@ signals:
* Triggered when your ability to change the <code>locked</code> property of entities changes.
* @function Entities.canAdjustLocksChanged
* @param {boolean} canAdjustLocks - <code>true</code> if the script can change the <code>locked</code> property of an
- * entity, otherwise <code>false</code>.
+ * entity, <code>false</code> if it can't.
* @returns {Signal}
* @example <caption>Report when your ability to change locks changes.</caption>
* function onCanAdjustLocksChanged(canAdjustLocks) {
@@ -2027,7 +2026,7 @@ signals:
/**jsdoc
* Triggered when your ability to rez (create) entities changes.
* @function Entities.canRezChanged
- * @param {boolean} canRez - <code>true</code> if the script can rez (create) entities, otherwise <code>false</code>.
+ * @param {boolean} canRez - <code>true</code> if the script can rez (create) entities, <code>false</code> if it can't.
* @returns {Signal}
*/
void canRezChanged(bool canRez);
@@ -2036,8 +2035,8 @@ signals:
* Triggered when your ability to rez (create) temporary entities changes. Temporary entities are entities with a finite
* <code>lifetime</code> property value set.
* @function Entities.canRezTmpChanged
- * @param {boolean} canRezTmp - <code>true</code> if the script can rez (create) temporary entities, otherwise
- * <code>false</code>.
+ * @param {boolean} canRezTmp - <code>true</code> if the script can rez (create) temporary entities, <code>false</code> if
+ * it can't.
* @returns {Signal}
*/
void canRezTmpChanged(bool canRezTmp);
@@ -2046,8 +2045,8 @@ signals:
* Triggered when your ability to rez (create) certified entities changes. Certified entities are entities that have PoP
* certificates.
* @function Entities.canRezCertifiedChanged
- * @param {boolean} canRezCertified - <code>true</code> if the script can rez (create) certified entities, otherwise
- * <code>false</code>.
+ * @param {boolean} canRezCertified - <code>true</code> if the script can rez (create) certified entities,
+ * <code>false</code> if it can't.
* @returns {Signal}
*/
void canRezCertifiedChanged(bool canRezCertified);
@@ -2057,7 +2056,7 @@ signals:
* finite <code>lifetime</code> property value set. Certified entities are entities that have PoP certificates.
* @function Entities.canRezTmpCertifiedChanged
* @param {boolean} canRezTmpCertified - <code>true</code> if the script can rez (create) temporary certified entities,
- * otherwise <code>false</code>.
+ * <code>false</code> if it can't.
* @returns {Signal}
*/
void canRezTmpCertifiedChanged(bool canRezTmpCertified);
@@ -2066,7 +2065,7 @@ signals:
* Triggered when your ability to make changes to the asset server's assets changes.
* @function Entities.canWriteAssetsChanged
* @param {boolean} canWriteAssets - <code>true</code> if the script can change the <code>?</code> property of an entity,
- * otherwise <code>false</code>.
+ * <code>false</code> if it can't.
* @returns {Signal}
*/
void canWriteAssetsChanged(bool canWriteAssets);
@@ -2074,8 +2073,8 @@ signals:
/**jsdoc
* Triggered when your ability to get and set private user data changes.
* @function Entities.canGetAndSetPrivateUserDataChanged
- * @param {boolean} canGetAndSetPrivateUserData - <code>true</code> if you can change the <code>privateUserData</code> property of an entity,
- * otherwise <code>false</code>.
+ * @param {boolean} canGetAndSetPrivateUserData - <code>true</code> if the script change the <code>privateUserData</code>
+ * property of an entity, <code>false</code> if it can't.
* @returns {Signal}
*/
void canGetAndSetPrivateUserDataChanged(bool canGetAndSetPrivateUserData);
@@ -2146,7 +2145,7 @@ signals:
/**jsdoc
- * Triggered when a mouse button is clicked while the mouse cursor is on an entity. Note: Not triggered by controller.
+ * Triggered when a mouse button is clicked while the mouse cursor is on an entity. Note: Not triggered by controllers.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.clickDownOnEntity
* @param {Uuid} entityID - The ID of the entity that was clicked on.
@@ -2157,7 +2156,7 @@ signals:
/**jsdoc
* Repeatedly triggered while a mouse button continues to be held after clicking an entity, even if the mouse cursor has
- * moved off the entity. Note: Not triggered by controller.
+ * moved off the entity. Note: Not triggered by controllers.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.holdingClickOnEntity
* @param {Uuid} entityID - The ID of the entity that was originally clicked.
@@ -2168,7 +2167,8 @@ signals:
/**jsdoc
* Triggered when a mouse button is released after clicking on an entity, even if the mouse cursor has moved off the
- * entity. Note: Not triggered by controller.
+ * entity. Note: Not triggered by controllers.
+ * <p>See also, {@link Script.addEventHandler}.</p>
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.clickReleaseOnEntity
* @param {Uuid} entityID - The ID of the entity that was originally clicked.
@@ -2209,41 +2209,58 @@ signals:
/**jsdoc
- * Triggered when an avatar enters an entity.
+ * Triggered when an avatar enters an entity if the entity has a function connected to this event. If used in an entity
+ * script then the function is called only for enter events on that entity.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.enterEntity
* @param {Uuid} entityID - The ID of the entity that the avatar entered.
* @returns {Signal}
- * @example <caption>Change the color of an entity when an avatar enters or leaves.</caption>
+ * @example <caption>Change the color of entities when an avatar enters or leaves.</caption>
+ * // Change the color of entities when an avatar enters or leaves.
* var entityScript = (function () {
* this.enterEntity = function (entityID) {
- * print("Enter entity");
+ * print("Entity : Enter entity: " + entityID); // Only this entity.
* Entities.editEntity(entityID, {
- * color: { red: 255, green: 64, blue: 64 },
+ * color: { red: 255, green: 64, blue: 64 }
* });
* };
* this.leaveEntity = function (entityID) {
- * print("Leave entity");
+ * print("Entity : Leave entity: " + entityID); // Only this entity.
* Entities.editEntity(entityID, {
- * color: { red: 128, green: 128, blue: 128 },
+ * color: { red: 128, green: 128, blue: 128 }
* });
* };
* });
- *
- * var entityID = Entities.addEntity({
- * type: "Sphere",
- * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
- * dimensions: { x: 3, y: 3, z: 3 },
- * color: { red: 128, green: 128, blue: 128 },
- * collisionless: true, // So that avatar can walk through entity.
- * script: "(" + entityScript + ")", // Could host the script on a Web server instead.
- * lifetime: 300 // Delete after 5 minutes.
+ *
+ * function addSphere(deltaPosition) {
+ * Entities.addEntity({
+ * type: "Sphere",
+ * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, deltaPosition)),
+ * dimensions: { x: 3, y: 3, z: 3 },
+ * color: { red: 128, green: 128, blue: 128 },
+ * collisionless: true, // So that avatar can walk through entity.
+ * script: "(" + entityScript + ")", // Could host the script on a Web server instead.
+ * lifetime: 300 // Delete after 5 minutes.
+ * });
+ * }
+ *
+ * // Create two spheres that change color whan an avatar enters.
+ * addSphere({ x: -2, y: 0, z: -5 });
+ * addSphere({ x: 2, y: 0, z: -5 });
+ *
+ * Entities.enterEntity.connect(function (entityID) {
+ * print("Interface : Enter entity : " + entityID); // Both entities.
+ * });
+ *
+ * Entities.leaveEntity.connect(function (entityID) {
+ * print("Interface : Enter entity : " + entityID); // Both entities.
* });
*/
void enterEntity(const EntityItemID& entityItemID);
/**jsdoc
- * Triggered when an avatar leaves an entity.
+ * Triggered when an avatar leaves an entity if the entity has a function connected to this event. If used in an entity
+ * script then the function is called only for leave events on that entity.
* <p>See also, {@link Script.addEventHandler}.</p>
* @function Entities.leaveEntity
* @param {Uuid} entityID - The ID of the entity that the avatar left.
@@ -2265,9 +2282,9 @@ signals:
void deletingEntity(const EntityItemID& entityID);
/**jsdoc
- * Triggered when an entity is added to Interface's local in-memory tree of entities it knows about. This may occur when
+ * Triggered when an entity is added to Interface's local in-memory tree of entities it knows about. This may occur when
* entities are loaded upon visiting a domain, when the user rotates their view so that more entities become visible, and
- * when any type of entity is added (e.g., by {@Entities.addEntity|addEntity}).
+ * when any type of entity is created (e.g., by {@link Entities.addEntity|addEntity}).
* @function Entities.addingEntity
* @param {Uuid} entityID - The ID of the entity added.
* @returns {Signal}
@@ -2279,33 +2296,33 @@ signals:
void addingEntity(const EntityItemID& entityID);
/**jsdoc
- * Triggered when an 'wearable' entity is deleted.
- * @function Entities.deletingWearable
- * @param {Uuid} entityID - The ID of the 'wearable' entity deleted.
- * @returns {Signal}
- * @example <caption>Report when an 'wearable' entity is deleted.</caption>
- * Entities.deletingWearable.connect(function (entityID) {
- * print("Deleted wearable: " + entityID);
- * });
- */
+ * Triggered when an "wearable" entity is deleted, for example when removing a "wearable" from your avatar.
+ * @function Entities.deletingWearable
+ * @param {Uuid} entityID - The ID of the "wearable" entity deleted.
+ * @returns {Signal}
+ * @example <caption>Report when a "wearable" entity is deleted.</caption>
+ * Entities.deletingWearable.connect(function (entityID) {
+ * print("Deleted wearable: " + entityID);
+ * });
+ */
void deletingWearable(const EntityItemID& entityID);
/**jsdoc
- * Triggered when an 'wearable' entity is added to Interface's local in-memory tree of entities it knows about. This may occur when
- * 'wearable' entities are added to avatar
- * @function Entities.addingWearable
- * @param {Uuid} entityID - The ID of the 'wearable' entity added.
- * @returns {Signal}
- * @example <caption>Report when an 'wearable' entity is added.</caption>
- * Entities.addingWearable.connect(function (entityID) {
- * print("Added wearable: " + entityID);
- * });
- */
+ * Triggered when an "wearable" entity is added to Interface's local in-memory tree of entities it knows about, for example
+ * when adding a "wearable" to your avatar.
+ * @function Entities.addingWearable
+ * @param {Uuid} entityID - The ID of the "wearable" entity added.
+ * @returns {Signal}
+ * @example <caption>Report when a "wearable" entity is added.</caption>
+ * Entities.addingWearable.connect(function (entityID) {
+ * print("Added wearable: " + entityID);
+ * });
+ */
void addingWearable(const EntityItemID& entityID);
/**jsdoc
- * Triggered when you disconnect from a domain, at which time Interface's local in-memory tree of entities it knows about
- * is cleared.
+ * Triggered when you disconnect from a domain, at which time Interface's local in-memory tree of entities that it knows
+ * about is cleared.
* @function Entities.clearingEntities
* @returns {Signal}
* @example <caption>Report when Interfaces's entity tree is cleared.</caption>
@@ -2316,10 +2333,14 @@ signals:
void clearingEntities();
/**jsdoc
- * Triggered in when a script in a {@link Entities.EntityType|Web} entity's Web page script sends an event over the
- * script's <code>EventBridge</code>.
+ * Triggered when a script in a {@link Entities.EntityProperties-Web|Web} entity's HTML sends an event over the entity's
+ * HTML event bridge. The HTML web page can send a message by calling:
+ * <pre class="prettyprint"><code>EventBridge.emitWebEvent(message);</code></pre>
+ * <p>Use {@link Entities.emitScriptEvent} to send messages to the Web entity's HTML page.</p>
+ * <p>Alternatively, you can use {@link Entities.getEntityObject} to exchange messages over a Web entity's HTML event
+ * bridge.</p>
* @function Entities.webEventReceived
- * @param {Uuid} entityID - The ID of the entity that event was received from.
+ * @param {Uuid} entityID - The ID of the Web entity that the message was received from.
* @param {string} message - The message received.
* @returns {Signal}
*/
From 52860adc1caf05f320bf53b9f26b15b5d4030689 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Fri, 21 Jun 2019 14:27:51 +1200
Subject: [PATCH 08/13] Add callEntityMethod() and similar examples
---
.../entities/src/EntityScriptingInterface.h | 130 ++++++++++++++++--
1 file changed, 117 insertions(+), 13 deletions(-)
diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h
index dc0039f0f5..3ffc94af5e 100644
--- a/libraries/entities/src/EntityScriptingInterface.h
+++ b/libraries/entities/src/EntityScriptingInterface.h
@@ -501,37 +501,141 @@ public slots:
Q_INVOKABLE QSizeF textSize(const QUuid& id, const QString& text);
/**jsdoc
- * Calls a method in a client entity script from a client script or client entity script, or calls a method in a server
- * entity script from a server entity script. The entity script method must be exposed as a property in the target client
+ * Calls a method in a client entity script from an Interface, avatar, or client entity script, or calls a method in a
+ * server entity script from a server entity script. The entity script method must be exposed as a property in the target
* entity script. Additionally, if calling a server entity script, the server entity script must include the method's name
* in an exposed property called <code>remotelyCallable</code> that is an array of method names that can be called.
* @function Entities.callEntityMethod
* @param {Uuid} entityID - The ID of the entity to call the method in.
- * @param {string} method - The name of the method to call.
- * @param {string[]} [parameters=[]] - The parameters to call the specified method with.
+ * @param {string} method - The name of the method to call. The method is called with the entity ID as the first parameter
+ * and the <code>parameters</code> value as the second parameter.
+ * @param {string[]} [parameters=[]] - The additional parameters to call the specified method with.
+ * @example <caption>Call a method in a client entity script from an Interface script.</caption>
+ * // Client entity script.
+ * var entityScript = (function () {
+ * this.entityMethod = function (id, params) {
+ * print("Method at entity : " + id + " ; " + params[0] + ", " + params[1]);
+ * };
+ * });
+ *
+ * // Entity that hosts the client entity script.
+ * var entityID = Entities.addEntity({
+ * type: "Box",
+ * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
+ * dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+ * script: "(" + entityScript + ")", // Could host the script on a Web server instead.
+ * lifetime: 300 // Delete after 5 minutes.
+ * });
+ *
+ * // Interface script call to the client entity script.
+ * Script.setTimeout(function () {
+ * Entities.callEntityMethod(entityID, "entityMethod", ["hello", 12]);
+ * }, 1000); // Wait for the entity to be created.
*/
Q_INVOKABLE void callEntityMethod(const QUuid& entityID, const QString& method, const QStringList& params = QStringList());
/**jsdoc
- * Calls a method in a server entity script from a client script or client entity script. The entity script method must be
- * exposed as a property in the target server entity script. Additionally, the target server entity script must include the
- * method's name in an exposed property called <code>remotelyCallable</code> that is an array of method names that can be
- * called.
+ * Calls a method in a server entity script from an Interface, avatar, or client entity script. The server entity script
+ * method must be exposed as a property in the target server entity script. Additionally, the server entity script must
+ * include the method's name in an exposed property called <code>remotelyCallable</code> that is an array of method names
+ * that can be called.
* @function Entities.callEntityServerMethod
* @param {Uuid} entityID - The ID of the entity to call the method in.
- * @param {string} method - The name of the method to call.
- * @param {string[]} [parameters=[]] - The parameters to call the specified method with.
+ * @param {string} method - The name of the method to call. The method is called with the entity ID as the first parameter
+ * and the <code>parameters</code> value as the second parameter.
+ * @param {string[]} [parameters=[]] - The additional parameters to call the specified method with.
+ * @example <caption>Call a method in a server entity script from an Interface script.</caption>
+ * // Server entity script.
+ * var entityScript = (function () {
+ * this.entityMethod = function (id, params) {
+ * print("Method at entity : " + id + " ; " + params[0] + ", " + params[1]); // In server log.
+ * };
+ * this.remotelyCallable = [
+ * "entityMethod"
+ * ];
+ * });
+ *
+ * // Entity that hosts the server entity script.
+ * var entityID = Entities.addEntity({
+ * type: "Box",
+ * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
+ * dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+ * serverScripts: "(" + entityScript + ")", // Could host the script on a Web server instead.
+ * lifetime: 300 // Delete after 5 minutes.
+ * });
+ *
+ * // Interface script call to the server entity script.
+ * Script.setTimeout(function () {
+ * Entities.callEntityServerMethod(entityID, "entityMethod", ["hello", 12]);
+ * }, 1000); // Wait for the entity to be created.
*/
Q_INVOKABLE void callEntityServerMethod(const QUuid& entityID, const QString& method, const QStringList& params = QStringList());
/**jsdoc
* Calls a method in a specific user's client entity script from a server entity script. The entity script method must be
- * exposed as a property in the target client entity script.
+ * exposed as a property in the target client entity script. Additionally, the client entity script must
+ * include the method's name in an exposed property called <code>remotelyCallable</code> that is an array of method names
+ * that can be called.
* @function Entities.callEntityClientMethod
* @param {Uuid} clientSessionID - The session ID of the user to call the method in.
* @param {Uuid} entityID - The ID of the entity to call the method in.
- * @param {string} method - The name of the method to call.
- * @param {string[]} [parameters=[]] - The parameters to call the specified method with.
+ * @param {string} method - The name of the method to call. The method is called with the entity ID as the first parameter
+ * and the <code>parameters</code> value as the second parameter.
+ * @param {string[]} [parameters=[]] - The additional parameters to call the specified method with.
+ * @example <caption>Call a method in a client entity script from a server entity script.</caption>
+ * // Client entity script.
+ * var clientEntityScript = (function () {
+ * this.entityMethod = function (id, params) {
+ * print("Method at client entity : " + id + " ; " + params[0] + ", " + params[1]);
+ * };
+ * this.remotelyCallable = [
+ * "entityMethod"
+ * ];
+ * });
+ *
+ * // Server entity script.
+ * var serverEntityScript = (function () {
+ * var clientSessionID,
+ * clientEntityID;
+ *
+ * function callClientMethod() {
+ * // Server entity script call to client entity script.
+ * Entities.callEntityClientMethod(clientSessionID, clientEntityID, "entityMethod", ["hello", 12]);
+ * }
+ *
+ * // Obtain client entity details then call client entity method.
+ * this.entityMethod = function (id, params) {
+ * clientSessionID = params[0];
+ * clientEntityID = params[1];
+ * callClientMethod();
+ * };
+ * this.remotelyCallable = [
+ * "entityMethod"
+ * ];
+ * });
+ *
+ * // Entity that hosts the client entity script.
+ * var clientEntityID = Entities.addEntity({
+ * type: "Box",
+ * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: -1, y: 0, z: -5 })),
+ * dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+ * script: "(" + clientEntityScript + ")", // Could host the script on a Web server instead.
+ * lifetime: 300 // Delete after 5 minutes.
+ * });
+ *
+ * // Entity that hosts the server entity script.
+ * var serverEntityID = Entities.addEntity({
+ * type: "Box",
+ * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 1, y: 0, z: -5 })),
+ * dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+ * serverScripts: "(" + serverEntityScript + ")", // Could host the script on a Web server instead.
+ * lifetime: 300 // Delete after 5 minutes.
+ * });
+ *
+ * // Interface script call to the server entity script.
+ * Script.setTimeout(function () {
+ * Entities.callEntityServerMethod(serverEntityID, "entityMethod", [MyAvatar.sessionUUID, clientEntityID]);
+ * }, 1000); // Wait for the entities to be created.
*/
Q_INVOKABLE void callEntityClientMethod(const QUuid& clientSessionID, const QUuid& entityID, const QString& method,
const QStringList& params = QStringList());
From 3c53cb2e90ca95d1e332a176192f8f71f9c23137 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Fri, 21 Jun 2019 15:21:16 +1200
Subject: [PATCH 09/13] Add missing grabDelegetToParent property to JSDoc
---
libraries/entities/src/GrabPropertyGroup.h | 3 +++
1 file changed, 3 insertions(+)
diff --git a/libraries/entities/src/GrabPropertyGroup.h b/libraries/entities/src/GrabPropertyGroup.h
index 99b8100075..75804378aa 100644
--- a/libraries/entities/src/GrabPropertyGroup.h
+++ b/libraries/entities/src/GrabPropertyGroup.h
@@ -53,6 +53,9 @@ static const glm::vec3 INITIAL_EQUIPPABLE_INDICATOR_OFFSET { glm::vec3(0.0f) };
* 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} grabDelegateToParent=true - If <code>true</code> and the entity is grabbed, the grab will be transferred
+ * to its parent entity if there is one; if <code>false</code>, a child entity can be grabbed and moved relative to its
+ * parent.
* @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.
From 0bee5edc47c6e7eb0c58a321c5aeddf78b6a3d07 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Sat, 22 Jun 2019 08:41:30 +1200
Subject: [PATCH 10/13] Fix documentation of Material's albedo and emissive
property values
---
.../src/material-networking/MaterialCache.cpp | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
diff --git a/libraries/material-networking/src/material-networking/MaterialCache.cpp b/libraries/material-networking/src/material-networking/MaterialCache.cpp
index af1a868647..4f6d149fbe 100644
--- a/libraries/material-networking/src/material-networking/MaterialCache.cpp
+++ b/libraries/material-networking/src/material-networking/MaterialCache.cpp
@@ -114,15 +114,16 @@ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMater
* @property {string} model="hifi_pbr" - Different material models support different properties and rendering modes.
* 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.
+ * @property {ColorFloat|RGBS|string} emissive - The emissive color, i.e., the color that the material emits. A
+ * {@link ColorFloat} value is treated as sRGB and must have component values in the range <code>0.0</code> —
+ * <code>1.0</code>. 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.
+ * @property {ColorFloat|RGBS|string} albedo - The albedo color. A {@link ColorFloat} value is treated as sRGB and must have
+ * component values in the range <code>0.0</code> — <code>1.0</code>. 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} 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.
From e3f971a30465a98d24c53604c182af1240c83bc8 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Sat, 22 Jun 2019 09:23:07 +1200
Subject: [PATCH 11/13] Update Entities examples to have a delay after creation
before editing
---
.../entities/src/EntityScriptingInterface.h | 32 +++++++++++--------
1 file changed, 19 insertions(+), 13 deletions(-)
diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h
index 3ffc94af5e..45f44f00ac 100644
--- a/libraries/entities/src/EntityScriptingInterface.h
+++ b/libraries/entities/src/EntityScriptingInterface.h
@@ -375,11 +375,13 @@ public slots:
* var properties = Entities.getEntityProperties(entityID, ["color"]);
* print("Entity color: " + JSON.stringify(properties.color));
*
- * Entities.editEntity(entityID, {
- * color: { red: 255, green: 0, blue: 0 }
- * });
- * properties = Entities.getEntityProperties(entityID, ["color"]);
- * print("Entity color: " + JSON.stringify(properties.color));
+ * Script.setTimeout(function () { // Wait for entity to finish creation before editing.
+ * Entities.editEntity(entityID, {
+ * color: { red: 255, green: 0, blue: 0 }
+ * });
+ * properties = Entities.getEntityProperties(entityID, ["color"]);
+ * print("Entity color: " + JSON.stringify(properties.color));
+ * }, 50);
*/
Q_INVOKABLE QUuid editEntity(const QUuid& entityID, const EntityItemProperties& properties);
@@ -1140,7 +1142,9 @@ public slots:
* });
*
* // Add a third point to create a "V".
- * Entities.appendPoint(entity, { x: 1, y: 1, z: 0 });
+ * Script.setTimeout(function () { // Wait for entity to finish creation before editing.
+ * Entities.appendPoint(entity, { x: 1, y: 1, z: 0 });
+ * }, 50);
*/
Q_INVOKABLE bool appendPoint(const QUuid& entityID, const glm::vec3& point);
@@ -1576,13 +1580,15 @@ public slots:
* var root = createEntity("Root", position, Uuid.NULL);
* var child = createEntity("Child", Vec3.sum(position, { x: 0, y: -1, z: 0 }), root);
*
- * Entities.editEntity(root, {
- * parentID: MyAvatar.sessionUUID,
- * parentJointIndex: MyAvatar.getJointIndex("RightHand")
- * });
- *
- * var children = Entities.getChildrenIDsOfJoint(MyAvatar.sessionUUID, MyAvatar.getJointIndex("RightHand"));
- * print("Children of hand: " + JSON.stringify(children)); // Only the root entity.
+ * Script.setTimeout(function () { // Wait for entity to finish creation before editing.
+ * Entities.editEntity(root, {
+ * parentID: MyAvatar.sessionUUID,
+ * parentJointIndex: MyAvatar.getJointIndex("RightHand")
+ * });
+ *
+ * var children = Entities.getChildrenIDsOfJoint(MyAvatar.sessionUUID, MyAvatar.getJointIndex("RightHand"));
+ * print("Children of hand: " + JSON.stringify(children)); // Only the root entity.
+ * }, 50);
*/
Q_INVOKABLE QVector<QUuid> getChildrenIDsOfJoint(const QUuid& parentID, int jointIndex);
From eb227c6b9af27e2b51d79549a02c70b961063adc Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Sat, 22 Jun 2019 11:59:07 +1200
Subject: [PATCH 12/13] Document Entities entity methods
---
.../entities/src/EntityScriptingInterface.h | 126 ++++++++++--------
libraries/script-engine/src/ScriptEngine.h | 2 +
2 files changed, 70 insertions(+), 58 deletions(-)
diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h
index 45f44f00ac..605fcf6943 100644
--- a/libraries/entities/src/EntityScriptingInterface.h
+++ b/libraries/entities/src/EntityScriptingInterface.h
@@ -109,6 +109,36 @@ public:
* <p>Note: For Interface scripts, the entities available to scripts are those that Interface has displayed and so knows
* about.</p>
*
+ * <h3>Entity Methods</h3>
+ *
+ * <p>Some of the API's signals correspond to entity methods that are called if, if present, in the entity being interacted
+ * with. The client or server entity script must expose them as a property. However, unlike {@link Entities.callEntityMethod},
+ * server entity scripts do not need to list them in an <code>remotelyCallable</code> property. The entity methods are called
+ * with parameters per their corresponding signal.</p>
+ * <table>
+ * <thead>
+ * <tr><th>Method Name</th><th>Corresponding Signal</th></tr>
+ * </thead>
+ * <tbody>
+ * <tr><td><code>clickDownOnEntity</code></td><td>{@link Entities.clickDownOnEntity}</td></tr>
+ * <tr><td><code>clickReleaseOnEntity</code></td><td>{@link Entities.clickReleaseOnEntity}</td></tr>
+ * <tr><td><code>collisionWithEntity</code></td><td>{@link Entities.collisionWithEntity}</td></tr>
+ * <tr><td><code>enterEntity</code></td><td>{@link Entities.enterEntity}</td></tr>
+ * <tr><td><code>holdingClickOnEntity</code></td><td>{@link Entities.holdingClickOnEntity}</td></tr>
+ * <tr><td><code>hoverEnterEntity</code></td><td>{@link Entities.hoverEnterEntity}</td></tr>
+ * <tr><td><code>hoverLeaveEntity</code></td><td>{@link Entities.hoverLeaveEntity}</td></tr>
+ * <tr><td><code>hoverOverEntity</code></td><td>{@link Entities.hoverOverEntity}</td></tr>
+ * <tr><td><code>leaveEntity</code></td><td>{@link Entities.leaveEntity}</td></tr>
+ * <tr><td><code>mouseDoublePressOnEntity</code></td><td>{@link Entities.mouseDoublePressOnEntity}</td></tr>
+ * <tr><td><code>mouseMoveOnEntity</code></td><td>{@link Entities.mouseMoveOnEntity}</td></tr>
+ * <tr><td><code>mouseMoveEvent</code></td><td><span class="important">Deprecated: This is a synonym for
+ * <code>mouseMoveOnEntity</code>.</span></td></tr>
+ * <tr><td><code>mousePressOnEntity</code></td><td>{@link Entities.mousePressOnEntity}</td></tr>
+ * <tr><td><code>mouseReleaseOnEntity</code></td><td>{@link Entities.mouseReleaseOnEntity}</td></tr>
+ * </tbody>
+ * </table>
+ * <p>See {@link Entities.clickDownOnEntity} for an example.</p>
+ *
* @namespace Entities
*
* @hifi-interface
@@ -2080,7 +2110,7 @@ signals:
/**jsdoc
* Triggered on the client that is the physics simulation owner during the collision of two entities. Note: Isn't triggered
* for a collision with an avatar.
- * <p>See also, {@link Script.addEventHandler}.</p>
+ * <p>See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.</p>
* @function Entities.collisionWithEntity
* @param {Uuid} idA - The ID of one entity in the collision. For an entity script, this is the ID of the entity containing
* the script.
@@ -2193,7 +2223,7 @@ signals:
/**jsdoc
* Triggered when a mouse button is clicked while the mouse cursor is on an entity, or a controller trigger is fully
* pressed while its laser is on an entity.
- * <p>See also, {@link Script.addEventHandler}.</p>
+ * <p>See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.</p>
* @function Entities.mousePressOnEntity
* @param {Uuid} entityID - The ID of the entity that was pressed on.
* @param {PointerEvent} event - Details of the event.
@@ -2218,7 +2248,7 @@ signals:
/**jsdoc
* Repeatedly triggered while the mouse cursor or controller laser moves on an entity.
- * <p>See also, {@link Script.addEventHandler}.</p>
+ * <p>See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.</p>
* @function Entities.mouseMoveOnEntity
* @param {Uuid} entityID - The ID of the entity that was moved on.
* @param {PointerEvent} event - Details of the event.
@@ -2229,7 +2259,7 @@ signals:
/**jsdoc
* Triggered when a mouse button is released after clicking on an entity or the controller trigger is partly or fully
* released after pressing on an entity, even if the mouse pointer or controller laser has moved off the entity.
- * <p>See also, {@link Script.addEventHandler}.</p>
+ * <p>See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.</p>
* @function Entities.mouseReleaseOnEntity
* @param {Uuid} entityID - The ID of the entity that was originally pressed.
* @param {PointerEvent} event - Details of the event.
@@ -2256,18 +2286,41 @@ signals:
/**jsdoc
* Triggered when a mouse button is clicked while the mouse cursor is on an entity. Note: Not triggered by controllers.
- * <p>See also, {@link Script.addEventHandler}.</p>
+ * <p>See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.</p>
* @function Entities.clickDownOnEntity
* @param {Uuid} entityID - The ID of the entity that was clicked on.
* @param {PointerEvent} event - Details of the event.
* @returns {Signal}
+ * @example <caption>Compare clickDownOnEntity signal and entity script method.</caption>
+ * var entityScript = (function () {
+ * // Method is called for only this entity.
+ * this.clickDownOnEntity = function (entityID, event) {
+ * print("Entity : Clicked sphere ; " + event.type);
+ * };
+ * });
+ *
+ * var sphereID = Entities.addEntity({
+ * type: "Sphere",
+ * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
+ * script: "(" + entityScript + ")", // Could host the script on a Web server instead.
+ * lifetime: 300 // Delete after 5 minutes.
+ * });
+ *
+ * Entities.clickDownOnEntity.connect(function (entityID, event) {
+ * // Signal is triggered for all entities.
+ * if (entityID === sphereID) {
+ * print("Interface : Clicked sphere ; " + event.type);
+ * } else {
+ * print("Interface : Clicked another entity ; " + event.type);
+ * }
+ * });
*/
void clickDownOnEntity(const EntityItemID& entityItemID, const PointerEvent& event);
/**jsdoc
* Repeatedly triggered while a mouse button continues to be held after clicking an entity, even if the mouse cursor has
* moved off the entity. Note: Not triggered by controllers.
- * <p>See also, {@link Script.addEventHandler}.</p>
+ * <p>See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.</p>
* @function Entities.holdingClickOnEntity
* @param {Uuid} entityID - The ID of the entity that was originally clicked.
* @param {PointerEvent} event - Details of the event.
@@ -2278,8 +2331,7 @@ signals:
/**jsdoc
* Triggered when a mouse button is released after clicking on an entity, even if the mouse cursor has moved off the
* entity. Note: Not triggered by controllers.
- * <p>See also, {@link Script.addEventHandler}.</p>
- * <p>See also, {@link Script.addEventHandler}.</p>
+ * <p>See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.</p>
* @function Entities.clickReleaseOnEntity
* @param {Uuid} entityID - The ID of the entity that was originally clicked.
* @param {PointerEvent} event - Details of the event.
@@ -2289,7 +2341,7 @@ signals:
/**jsdoc
* Triggered when the mouse cursor or controller laser starts hovering on an entity.
- * <p>See also, {@link Script.addEventHandler}.</p>
+ * <p>See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.</p>
* @function Entities.hoverEnterEntity
* @param {Uuid} entityID - The ID of the entity that is being hovered.
* @param {PointerEvent} event - Details of the event.
@@ -2299,7 +2351,7 @@ signals:
/**jsdoc
* Repeatedly triggered when the mouse cursor or controller laser moves while hovering over an entity.
- * <p>See also, {@link Script.addEventHandler}.</p>
+ * <p>See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.</p>
* @function Entities.hoverOverEntity
* @param {Uuid} entityID - The ID of the entity that is being hovered.
* @param {PointerEvent} event - Details of the event.
@@ -2309,7 +2361,7 @@ signals:
/**jsdoc
* Triggered when the mouse cursor or controller laser stops hovering over an entity.
- * <p>See also, {@link Script.addEventHandler}.</p>
+ * <p>See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.</p>
* @function Entities.hoverLeaveEntity
* @param {Uuid} entityID - The ID of the entity that was being hovered.
* @param {PointerEvent} event - Details of the event.
@@ -2319,59 +2371,17 @@ signals:
/**jsdoc
- * Triggered when an avatar enters an entity if the entity has a function connected to this event. If used in an entity
- * script then the function is called only for enter events on that entity.
- * <p>See also, {@link Script.addEventHandler}.</p>
+ * Triggered when an avatar enters an entity, but only if the entity has an entity method exposed for this event.
+ * <p>See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.</p>
* @function Entities.enterEntity
* @param {Uuid} entityID - The ID of the entity that the avatar entered.
* @returns {Signal}
- * @example <caption>Change the color of entities when an avatar enters or leaves.</caption>
- * // Change the color of entities when an avatar enters or leaves.
- * var entityScript = (function () {
- * this.enterEntity = function (entityID) {
- * print("Entity : Enter entity: " + entityID); // Only this entity.
- * Entities.editEntity(entityID, {
- * color: { red: 255, green: 64, blue: 64 }
- * });
- * };
- * this.leaveEntity = function (entityID) {
- * print("Entity : Leave entity: " + entityID); // Only this entity.
- * Entities.editEntity(entityID, {
- * color: { red: 128, green: 128, blue: 128 }
- * });
- * };
- * });
- *
- * function addSphere(deltaPosition) {
- * Entities.addEntity({
- * type: "Sphere",
- * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, deltaPosition)),
- * dimensions: { x: 3, y: 3, z: 3 },
- * color: { red: 128, green: 128, blue: 128 },
- * collisionless: true, // So that avatar can walk through entity.
- * script: "(" + entityScript + ")", // Could host the script on a Web server instead.
- * lifetime: 300 // Delete after 5 minutes.
- * });
- * }
- *
- * // Create two spheres that change color whan an avatar enters.
- * addSphere({ x: -2, y: 0, z: -5 });
- * addSphere({ x: 2, y: 0, z: -5 });
- *
- * Entities.enterEntity.connect(function (entityID) {
- * print("Interface : Enter entity : " + entityID); // Both entities.
- * });
- *
- * Entities.leaveEntity.connect(function (entityID) {
- * print("Interface : Enter entity : " + entityID); // Both entities.
- * });
- */
+ */
void enterEntity(const EntityItemID& entityItemID);
/**jsdoc
- * Triggered when an avatar leaves an entity if the entity has a function connected to this event. If used in an entity
- * script then the function is called only for leave events on that entity.
- * <p>See also, {@link Script.addEventHandler}.</p>
+ * Triggered when an avatar leaves an entity, but only if the entity has an entity method exposed for this event.
+ * <p>See also, {@link Entities|Entity Methods} and {@link Script.addEventHandler}.</p>
* @function Entities.leaveEntity
* @param {Uuid} entityID - The ID of the entity that the avatar left.
* @returns {Signal}
diff --git a/libraries/script-engine/src/ScriptEngine.h b/libraries/script-engine/src/ScriptEngine.h
index a2b16ed178..52ece63dc2 100644
--- a/libraries/script-engine/src/ScriptEngine.h
+++ b/libraries/script-engine/src/ScriptEngine.h
@@ -318,6 +318,7 @@ public:
/**jsdoc
* Adds a function to the list of functions called when an entity event occurs on a particular entity.
+ * <p>See also, the {@link Entities} API.</p>
* @function Script.addEventHandler
* @param {Uuid} entityID - The ID of the entity.
* @param {Script.EntityEvent} eventName - The name of the entity event.
@@ -341,6 +342,7 @@ public:
/**jsdoc
* Removes a function from the list of functions called when an entity event occurs on a particular entity.
+ * <p>See also, the {@link Entities} API.</p>
* @function Script.removeEventHandler
* @param {Uuid} entityID - The ID of the entity.
* @param {Script.EntityEvent} eventName - The name of the entity event.
From 4c8f281383e1ae317ee1007a79c091fc63c47ba9 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Sat, 22 Jun 2019 14:16:17 +1200
Subject: [PATCH 13/13] Typos etc.
---
.../entities/src/EntityDynamicInterface.cpp | 3 +-
.../entities/src/EntityItemProperties.cpp | 52 +++++++++----------
.../entities/src/EntityScriptingInterface.h | 33 +++++++-----
libraries/physics/src/ObjectDynamic.cpp | 2 +-
4 files changed, 48 insertions(+), 42 deletions(-)
diff --git a/libraries/entities/src/EntityDynamicInterface.cpp b/libraries/entities/src/EntityDynamicInterface.cpp
index 84ceefa6b9..4586b665ee 100644
--- a/libraries/entities/src/EntityDynamicInterface.cpp
+++ b/libraries/entities/src/EntityDynamicInterface.cpp
@@ -130,7 +130,8 @@ variables. These argument variables are used by the code which is run when bull
* <tr><td><code>"ball-socket"</code></td><td>Object constraint</td>
* <td>Connects two entities with a ball and socket joint.</td>
* <td>{@link Entities.ActionArguments-BallSocket}</td></tr>
- * <tr><td><code>"spring"</code></td><td colspan="3">Synonym for <code>"tractor"</code>. <em>Legacy value.</em></td></tr>
+ * <tr><td><code>"spring"</code></td><td colspan="3">Synonym for <code>"tractor"</code>.
+ * <span class="important">Deprecated.</span></td></tr>
* </tbody>
* </table>
* @typedef {string} Entities.ActionType
diff --git a/libraries/entities/src/EntityItemProperties.cpp b/libraries/entities/src/EntityItemProperties.cpp
index a2e1d5560a..5b3bbb88ee 100644
--- a/libraries/entities/src/EntityItemProperties.cpp
+++ b/libraries/entities/src/EntityItemProperties.cpp
@@ -656,10 +656,10 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* @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.
+ * <code>false</code> if they don't.
*
- * @property {Vec3} position=0,0,0 - The position of the entity.
- * @property {Quat} rotation=0,0,0,1 - The orientation of the entity with respect to world coordinates.
+ * @property {Vec3} position=0,0,0 - The position of the entity in world coordinates.
+ * @property {Quat} rotation=0,0,0,1 - The orientation of the entity in world coordinates.
* @property {Vec3} registrationPoint=0.5,0.5,0.5 - The point in the entity that is set to the entity's position and is rotated
* about, 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.
@@ -670,13 +670,13 @@ 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, range
+ * @property {number} damping=0.39347 - How much the linear velocity of an entity slows down 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, range
+ * @property {number} angularDamping=0.39347 - How much the angular velocity of an entity slows down 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.
@@ -694,7 +694,7 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* <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, range <code>0.0</code>
+ * @property {number} friction=0.5 - How much an entity slows down 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>, range <code>100</code> for balsa wood
@@ -744,7 +744,7 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* @property {Vec3} localVelocity=0,0,0 - The velocity of the entity relative to its parent if the entity is parented,
* otherwise the same value as <code>velocity</code>.
* @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>.
+ * parented, otherwise the same value as <code>angularVelocity</code>.
* @property {Vec3} localDimensions - The dimensions of the entity. 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 dimensions value while the
* avatar scale changes.
@@ -1197,24 +1197,24 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* rejected.
* @property {Entities.PolyVoxSurfaceStyle} voxelSurfaceStyle=2 - The style of rendering the voxels' surface and how
* neighboring PolyVox entities are joined.
- * @property {string} xTextureURL="" - URL of the texture to map to surfaces perpendicular to the entity's local x-axis. JPG or
- * PNG format. If no texture is specified the surfaces display white.
- * @property {string} yTextureURL="" - URL of the texture to map to surfaces perpendicular to the entity's local y-axis. JPG or
- * PNG format. If no texture is specified the surfaces display white.
- * @property {string} zTextureURL="" - URL of the texture to map to surfaces perpendicular to the entity's local z-axis. JPG or
- * PNG format. If no texture is specified the surfaces display white.
- * @property {Uuid} xNNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's -ve local x-axis direction,
- * if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
- * @property {Uuid} yNNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's -ve local y-axis direction,
- * if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
- * @property {Uuid} zNNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's -ve local z-axis direction,
- * if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
- * @property {Uuid} xPNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's +ve local x-axis direction,
- * if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
- * @property {Uuid} yPNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's +ve local y-axis direction,
- * if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
- * @property {Uuid} zPNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's +ve local z-axis direction,
- * if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
+ * @property {string} xTextureURL="" - The URL of the texture to map to surfaces perpendicular to the entity's local x-axis.
+ * JPG or PNG format. If no texture is specified the surfaces display white.
+ * @property {string} yTextureURL="" - The URL of the texture to map to surfaces perpendicular to the entity's local y-axis.
+ * JPG or PNG format. If no texture is specified the surfaces display white.
+ * @property {string} zTextureURL="" - The URL of the texture to map to surfaces perpendicular to the entity's local z-axis.
+ * JPG or PNG format. If no texture is specified the surfaces display white.
+ * @property {Uuid} xNNeighborID=Uuid.NULL - The ID of the neighboring PolyVox entity in the entity's -ve local x-axis
+ * direction, if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
+ * @property {Uuid} yNNeighborID=Uuid.NULL - The ID of the neighboring PolyVox entity in the entity's -ve local y-axis
+ * direction, if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
+ * @property {Uuid} zNNeighborID=Uuid.NULL - The ID of the neighboring PolyVox entity in the entity's -ve local z-axis
+ * direction, if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
+ * @property {Uuid} xPNeighborID=Uuid.NULL - The ID of the neighboring PolyVox entity in the entity's +ve local x-axis
+ * direction, if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
+ * @property {Uuid} yPNeighborID=Uuid.NULL - The ID of the neighboring PolyVox entity in the entity's +ve local y-axis
+ * direction, if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
+ * @property {Uuid} zPNeighborID=Uuid.NULL - The ID of the neighboring PolyVox entity in the entity's +ve local z-axis
+ * direction, if you want them joined. Set to {@link Uuid(0)|Uuid.NULL} if there is none or you don't want to join them.
* @example <caption>Create a textured PolyVox sphere.</caption>
* var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 }));
* var texture = "http://public.highfidelity.com/cozza13/tuscany/Concrete2.jpg";
@@ -1440,7 +1440,7 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* <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>
+ * @example <caption>Create an image entity.</caption>
* var image = Entities.addEntity({
* type: "Image",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h
index 605fcf6943..0666bb98df 100644
--- a/libraries/entities/src/EntityScriptingInterface.h
+++ b/libraries/entities/src/EntityScriptingInterface.h
@@ -111,10 +111,10 @@ public:
*
* <h3>Entity Methods</h3>
*
- * <p>Some of the API's signals correspond to entity methods that are called if, if present, in the entity being interacted
- * with. The client or server entity script must expose them as a property. However, unlike {@link Entities.callEntityMethod},
- * server entity scripts do not need to list them in an <code>remotelyCallable</code> property. The entity methods are called
- * with parameters per their corresponding signal.</p>
+ * <p>Some of the API's signals correspond to entity methods that are called, if present, in the entity being interacted with.
+ * The client or server entity script must expose them as a property. However, unlike {@link Entities.callEntityMethod}, server
+ * entity scripts do not need to list them in an <code>remotelyCallable</code> property. The entity methods are called with
+ * parameters per their corresponding signal.</p>
* <table>
* <thead>
* <tr><th>Method Name</th><th>Corresponding Signal</th></tr>
@@ -295,7 +295,8 @@ public slots:
* 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>
+ * coordinates unless parented to the client's avatar. Additionally, local entities are always
+ * collisionless.</td></tr>
* </tbody>
* </table>
* @typedef {string} Entities.EntityHostType
@@ -405,7 +406,7 @@ public slots:
* var properties = Entities.getEntityProperties(entityID, ["color"]);
* print("Entity color: " + JSON.stringify(properties.color));
*
- * Script.setTimeout(function () { // Wait for entity to finish creation before editing.
+ * Script.setTimeout(function () { // Wait for the entity to be created before editing.
* Entities.editEntity(entityID, {
* color: { red: 255, green: 0, blue: 0 }
* });
@@ -969,7 +970,7 @@ public slots:
* <code>position</code> coordinates are rounded to the nearest integer to get the voxel coordinate. The minimum axes
* corner voxel is <code>{ x: 0, y: 0, z: 0 }</code>.
* @param {number} value - If <code>value % 256 == 0</code> then voxel is cleared, otherwise the voxel is set.
- * @example <caption>Create a cube PolyVox entity and clear the minimum axes corner voxel.</caption>
+ * @example <caption>Create a cube PolyVox entity and clear the minimum axes' corner voxel.</caption>
* var entity = Entities.addEntity({
* type: "PolyVox",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 })),
@@ -1122,6 +1123,8 @@ public slots:
* @returns {boolean} <code>true</code> if the entity was updated, otherwise <code>false</code>. The property may fail to
* be updated if the entity does not exist, the entity is not a {@link Entities.EntityProperties-Line|Line} entity,
* one of the points is outside the entity's dimensions, or the number of points is greater than the maximum allowed.
+ * @deprecated This function is deprecated and will be removed. Use {@link Entities.EntityProperties-PolyLine|PolyLine}
+ * entities instead.
* @example <caption>Change the shape of a Line entity.</caption>
* // Draw a horizontal line between two points.
* var entity = Entities.addEntity({
@@ -1154,8 +1157,10 @@ public slots:
* @param {Uuid} entityID - The ID of the {@link Entities.EntityProperties-Line|Line} entity.
* @param {Vec3} point - The point to add to the line. The coordinates are relative to the entity's position.
* @returns {boolean} <code>true</code> if the point was added to the line, otherwise <code>false</code>. The point may
- * fail to be added if the entity does not exist, the entity is not a {@link Entities.EntityProperties-Line|Line} entity, the
- * point is outside the entity's dimensions, or the maximum number of points has been reached.
+ * fail to be added if the entity does not exist, the entity is not a {@link Entities.EntityProperties-Line|Line}
+ * entity, the point is outside the entity's dimensions, or the maximum number of points has been reached.
+ * @deprecated This function is deprecated and will be removed. Use {@link Entities.EntityProperties-PolyLine|PolyLine}
+ * entities instead.
* @example <caption>Append a point to a Line entity.</caption>
* // Draw a line between two points.
* var entity = Entities.addEntity({
@@ -1172,9 +1177,9 @@ public slots:
* });
*
* // Add a third point to create a "V".
- * Script.setTimeout(function () { // Wait for entity to finish creation before editing.
+ * Script.setTimeout(function () {
* Entities.appendPoint(entity, { x: 1, y: 1, z: 0 });
- * }, 50);
+ * }, 50); // Wait for the entity to be created.
*/
Q_INVOKABLE bool appendPoint(const QUuid& entityID, const glm::vec3& point);
@@ -1610,7 +1615,7 @@ public slots:
* var root = createEntity("Root", position, Uuid.NULL);
* var child = createEntity("Child", Vec3.sum(position, { x: 0, y: -1, z: 0 }), root);
*
- * Script.setTimeout(function () { // Wait for entity to finish creation before editing.
+ * Script.setTimeout(function () { // Wait for the entity to be created before editing.
* Entities.editEntity(root, {
* parentID: MyAvatar.sessionUUID,
* parentJointIndex: MyAvatar.getJointIndex("RightHand")
@@ -2416,7 +2421,7 @@ signals:
void addingEntity(const EntityItemID& entityID);
/**jsdoc
- * Triggered when an "wearable" entity is deleted, for example when removing a "wearable" from your avatar.
+ * Triggered when a "wearable" entity is deleted, for example when removing a "wearable" from your avatar.
* @function Entities.deletingWearable
* @param {Uuid} entityID - The ID of the "wearable" entity deleted.
* @returns {Signal}
@@ -2428,7 +2433,7 @@ signals:
void deletingWearable(const EntityItemID& entityID);
/**jsdoc
- * Triggered when an "wearable" entity is added to Interface's local in-memory tree of entities it knows about, for example
+ * Triggered when a "wearable" entity is added to Interface's local in-memory tree of entities it knows about, for example
* when adding a "wearable" to your avatar.
* @function Entities.addingWearable
* @param {Uuid} entityID - The ID of the "wearable" entity added.
diff --git a/libraries/physics/src/ObjectDynamic.cpp b/libraries/physics/src/ObjectDynamic.cpp
index ad070e296c..f02b7b1c4c 100644
--- a/libraries/physics/src/ObjectDynamic.cpp
+++ b/libraries/physics/src/ObjectDynamic.cpp
@@ -103,7 +103,7 @@ bool ObjectDynamic::updateArguments(QVariantMap arguments) {
* @property {string} tag="" - A string that a script can use for its own purposes.
* @property {number} ttl=0 - How long the action should exist, in seconds, before it is automatically deleted. A value of
* <code>0</code> means that the action should not be deleted.
- * @property {boolean} isMine=true - Is <code>true</code> if you created the action during your current Interface session,
+ * @property {boolean} isMine=true - Is <code>true</code> if the action was created during the current client session,
* <code>false</code> otherwise. <em>Read-only.</em>
* @property {boolean} ::no-motion-state - Is present when the entity hasn't been registered with the physics engine yet (e.g.,
* if the action hasn't been properly configured), otherwise <code>undefined</code>. <em>Read-only.</em>