"far-grab" {@link Entities.ActionType|ActionType} moves and rotates an entity to a target position and
- * orientation, optionally relative to another entity, such that the entity doesn't collide with the user's avatar.
+ * 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}.
*
* @typedef {object} Entities.ActionArguments-FarGrab
diff --git a/interface/src/avatar/AvatarActionHold.cpp b/interface/src/avatar/AvatarActionHold.cpp
index 0d7129181b..9d568e6d73 100644
--- a/interface/src/avatar/AvatarActionHold.cpp
+++ b/interface/src/avatar/AvatarActionHold.cpp
@@ -417,8 +417,8 @@ bool AvatarActionHold::updateArguments(QVariantMap arguments) {
}
/**jsdoc
- * The "hold" {@link Entities.ActionType|ActionType} positions and rotates an entity relative to an avatar's hand,
- * without collisions between the entity and the holding avatar.
+ * The "hold" {@link Entities.ActionType|ActionType} positions and rotates an entity relative to an avatar's hand.
+ * Collisions between the entity and the user's avatar are disabled during the hold.
* It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
*
* @typedef {object} Entities.ActionArguments-Hold
diff --git a/libraries/entities/src/EntityDynamicInterface.cpp b/libraries/entities/src/EntityDynamicInterface.cpp
index 9ff39fe5b4..d43bdd7b51 100644
--- a/libraries/entities/src/EntityDynamicInterface.cpp
+++ b/libraries/entities/src/EntityDynamicInterface.cpp
@@ -102,12 +102,12 @@ variables. These argument variables are used by the code which is run when bull
*
*
* "far-grab""hold""offset""Box", "Shape", and "Sphere" depending on changes to
+ * the shape property set for entities of these types.) Read-only.
* @property {boolean} clientOnly=false - If true then the entity is an avatar entity, otherwise it is a server
* entity. Read-only.
* @property {Uuid} owningAvatarID=Uuid.NULL - The session ID of the owning avatar if clientOnly is
@@ -510,7 +511,7 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* 10.0. The higher the value, the more quickly it slows down. Examples: 0.1 for ice,
* 0.9 for sandpaper.
* @property {number} density=1000 - The density of the entity in kg/m3, 100 for balsa wood –
- * 10000 for silver. The density is used in conjunction with the entity's collision volume to work out its
+ * 10000 for silver. The density is used in conjunction with the entity's bounding box volume to work out its
* mass in the application of physics.
*
* @property {boolean} collisionless=false - Whether or not the entity should collide with items per its
@@ -528,13 +529,17 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* @property {string} href="" - A "hifi://" metaverse address that a user is taken to when they click on the entity.
* @property {string} description="" - A description of the href property value.
*
- * @property {string} userData="" - Intended to be 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.
+ * @property {string} userData="" - Used to store extra data about the entity in JSON format. WARNING: Other apps such as the
+ * Create app can also use this property, so make sure you handle data stored by other apps — edit only your bit and
+ * leave the rest of the data intact. You can use JSON.parse() to parse the string into a JavaScript object
+ * which you can manipulate the properties of, and use JSON.stringify() to convert the object into a string to
+ * put in the property.
*
* @property {string} 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
* an integer number of milliseconds since midnight GMT on January 1, 1970 (e.g., as supplied by Date.now().
- * If you update the property's value, the script is re-downloaded and reloaded.
+ * If you update the property's value, the script is re-downloaded and reloaded. This is how the "reload"
+ * button beside the "script URL" field in properties tab of the Create app works.
* @property {string} serverScripts="" - The URL of the server entity script, if any, that is attached to the entity.
*
* @property {Uuid} parentID=Uuid.NULL - The ID of the entity or avatar that this entity is parented to. {@link Uuid|Uuid.NULL}
@@ -564,7 +569,8 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* @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.
+ * Fidelity datagram packet there is a limit to the number of actions that an entity can have, and edits which would result
+ * in overflow are rejected.
* Read-only.
* @property {Entities.RenderInfo} renderInfo - Information on the cost of rendering the entity. Currently information is only
* provided for Model entities. Read-only.
@@ -603,9 +609,10 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The "Box" {@link Entities.EntityType|EntityType} is the same as the "Shape"
- * {@link Entities.EntityType|EntityType} except that its initial shape value is always set to "Cube"
- * when the entity is created. This property value can subsequently be changed (i.e. so that the entity is no longer displayed
- * as a cube).
+ * {@link Entities.EntityType|EntityType} except that its shape value is always set to "Cube"
+ * when the entity is created. If its shape property value is subsequently changed then the entity's
+ * type will be reported as "Sphere" if the shape is set to "Sphere",
+ * otherwise it will be reported as "Shape".
* @typedef {object} Entities.EntityProperties-Box
*/
@@ -619,7 +626,7 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* @property {number} intensity=1 - The brightness of the light.
* @property {number} falloffRadius=0.1 - The distance from the light's center at which intensity is reduced by 25%.
* @property {boolean} isSpotlight=false - If true then the light is directional, emitting along the entity's
- * 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 dimensions
* value is specified then the model is automatically sized to its
- * {@link Entityes.EntityProperties|naturalDimensions}.
+ * {@link Entities.EntityProperties|naturalDimensions}.
* @property {Color} color=255,255,255 - Currently not used.
* @property {string} modelURL="" - The URL of the FBX of OBJ model. Baked FBX models' URLs end in ".baked.fbx"."default-image-model.fbx" then the entity is considered to be an "Image"
* entity, in which case the textures property should be set per the example.
* @property {string} textures="" - A JSON string of texture name, URL pairs used when rendering the model in place of the
- * model's original textures. Only the texture names and URLs to be overridden need be specified; original textures are
- * used where there are no overrides. You can use JSON.stringify() to convert a JavaScript object of name, URL
- * pairs into a JSON string.
+ * model's original textures. Use a texture name from the originanlTextures 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
+ * overrides. You can use JSON.stringify() to convert a JavaScript object of name, URL pairs into a JSON
+ * string.
* @property {string} originalTextures="{}" - A JSON string of texture name, URL pairs used in the model. The property value is
* filled in after the entity has finished rezzing (i.e., textures have loaded). You can use JSON.parse() to
* parse the JSON string into a JavaScript object of name, URL pairs. Read-only.
@@ -773,7 +781,7 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* dimensions: { x: 0.0945, y: 0.0921, z: 0.0423 },
* lifetime: 300 // Delete after 5 minutes.
* });
- * @example emitSpeed == 5
* and speedSpread == 1, particles will be emitted with speeds in the range 4m/s – 6m/s.
- * @property {vec3} emitAcceleration=0,-9.8,0 - The acceleration that is applied to each particle during its lifetime.
+ * @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
* emitAccelerations == {x: 0, y: -9.8, z: 0} and accelerationSpread ==
* {x: 0, y: 1, z: 0}, each particle will have an acceleration in the range, {x: 0, y: -10.8, z: 0}
@@ -818,40 +827,46 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* otherwise they stay with 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 z-axis, and azimuthStart and azimuthFinish are
- * relative to the entity's x-axis. The default value is a rotation of -90 degrees about the x-axis, i.e., the particles
- * emit vertically.
+ * default, particles emit along the entity's local z-axis, and azimuthStart and azimuthFinish
+ * are relative to the entity's local x-axis. The default value is a rotation of -90 degrees about the local x-axis, i.e.,
+ * the particles emit vertically.
* @property {vec3} emitDimensions=0,0,0 - The dimensions of the ellipsoid from which particles are emitted.
* @property {number} emitRadiusStart=1 - The starting radius within the ellipsoid at which particles start being emitted;
* range 0.0 – 1.0 for the ellipsoid center to the ellipsoid surface, respectively.
* Particles are emitted from the portion of the ellipsoid that lies between emitRadiusStart and the
* ellipsoid's surface.
- * @property {number} polarStart=0 - The angle in radians from the entity's z-axis at which particles start being emitted
+ * @property {number} polarStart=0 - The angle in radians from the entity's local z-axis at which particles start being emitted
* within the ellipsoid; range 0 – Math.PI. Particles are emitted from the portion of the
* ellipsoid that lies between polarStart and polarFinish.
- * @property {number} polarFinish=0 - The angle in radians from the entity's z-axis at which particles stop being emitted
+ * @property {number} polarFinish=0 - The angle in radians from the entity's local z-axis at which particles stop being emitted
* within the ellipsoid; range 0 – Math.PI. Particles are emitted from the portion of the
* ellipsoid that lies between polarStart and polarFinish.
- * @property {number} azimuthStart=-Math.PI - The angle in radians from the entity's x-axis about the entity's z-axis at which
- * particles start being emitted; range -Math.PI – Math.PI. Particles are emitted from the
- * portion of the ellipsoid that lies between azimuthStart and azimuthFinish.
- * @property {number} azimuthFinish=Math.PI - The angle in radians from the entity's x-axis about the entity's z-axis at which
- * particles stop being emitted; range -Math.PI – Math.PI. Particles are emitted from the
- * portion of the ellipsoid that lies between azimuthStart and azimuthFinish.
+ * @property {number} azimuthStart=-Math.PI - The angle in radians from the entity's local x-axis about the entity's local
+ * z-axis at which particles start being emitted; range -Math.PI – Math.PI. Particles are
+ * emitted from the portion of the ellipsoid that lies between azimuthStart and azimuthFinish.
+ * @property {number} azimuthFinish=Math.PI - The angle in radians from the entity's local x-axis about the entity's local
+ * z-axis at which particles stop being emitted; range -Math.PI – Math.PI. Particles are
+ * emitted from the portion of the ellipsoid that lies between azimuthStart and azimuthFinish.
*
* @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=0.025 - The radius of each particle at the start of its life.
- * @property {number} radiusFinish=0.025 - The radius of each particle at the end of its life.
+ * @property {number} radiusStart=0.025 - The radius of each particle at the start of its life. If not explicitly set, the
+ * particleRadius value is used.
+ * @property {number} radiusFinish=0.025 - The radius of each particle at the end of its life. If not explicitly set, the
+ * particleRadius value is used.
* @property {number} radiusSpread=0 - Currently not used.
* @property {Color} color=255,255,255 - The color of each particle at the middle of its life.
- * @property {Color} colorStart=255,255,255 - The color of each particle at the start of its life.
- * @property {color} colorFinish=255,255,255 - The color of each particle at the end of its life.
+ * @property {Color} colorStart=255,255,255 - The color of each particle at the start of its life. If not explicitly set, the
+ * color value is used.
+ * @property {Color} colorFinish=255,255,255 - The color of each particle at the end of its life. If not explicitly set, the
+ * color value is used.
* @property {Color} colorSpread=0,0,0 - Currently not used.
* @property {number} alpha=1 - The alpha of each particle at the middle of its life.
- * @property {number} alphaStart=1 - The alpha of each particle at the start of its life.
- * @property {number} alphaFinish=1 - The alpha of each particle at the end of its life.
+ * @property {number} alphaStart=1 - The alpha of each particle at the start of its life. If not explicitly set, the
+ * alpha value is used.
+ * @property {number} alphaFinish=1 - The alpha of each particle at the end of its life. If not explicitly set, the
+ * alpha value is used.
* @property {number} alphaSpread=0 - Currently not used.
*
* @property {ShapeType} shapeType="none" - Currently not used. Read-only.
@@ -939,24 +954,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 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 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 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 x-axis direction, if you
- * want them joined. Set to {@link Uuid|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 y-axis direction, if you
- * want them joined. Set to {@link Uuid|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 z-axis direction, if you
- * want them joined. Set to {@link Uuid|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 x-axis direction, if you
- * want them joined. Set to {@link Uuid|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 y-axis direction, if you
- * want them joined. Set to {@link Uuid|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 z-axis direction, if you
- * want them joined. Set to {@link Uuid|Uuid.NULL} if there is none or you don't want to join them.
+ * @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|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|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|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|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|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|Uuid.NULL} if there is none or you don't want to join them.
* @example Create a textured PolyVox sphere.
* var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 }));
* var texture = "http://public.highfidelity.com/cozza13/tuscany/Concrete2.jpg";
@@ -991,9 +1006,10 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The "Sphere" {@link Entities.EntityType|EntityType} is the same as the "Shape"
- * {@link Entities.EntityType|EntityType} except that its initial shape value is always set to
- * "Sphere" when the entity is created. This property value can subsequently be changed (i.e. so that the entity
- * is no longer displayed as a sphere).
+ * {@link Entities.EntityType|EntityType} except that its shape value is always set to "Sphere"
+ * when the entity is created. If its shape property value is subsequently changed then the entity's
+ * type will be reported as "Box" if the shape is set to "Cube",
+ * otherwise it will be reported as "Shape".
* @typedef {object} Entities.EntityProperties-Sphere
*/
@@ -1030,7 +1046,9 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* @property {Vec3} dimensions=0.1,0.1,0.01 - The dimensions of the entity.
* @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 {number} dpi=30 - The resolution to display the page at, in dots per inch
+ * @property {number} dpi=30 - The resolution to display the page at, in dots per inch. If you convert this to dots per meter
+ * (multiply by 1 / 0.0254 = 39.3701) then multiply dimensions.x and dimensions.y by that value
+ * you get the resolution in pixels.
* @example Create a Web entity displaying at 1920 x 1080 resolution.
* var METERS_TO_INCHES = 39.3701;
* var entity = Entities.addEntity({
@@ -1050,6 +1068,7 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The "Zone" {@link Entities.EntityType|EntityType} is a volume of lighting effects and avatar permissions.
+ * Avatar interaction events such as {@link Entities.enterEntity} are also often used with a Zone entity.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
* @typedef {object} Entities.EntityProperties-Zone
* @property {Vec3} dimensions=0.1,0.1,0.1 - The size of the volume in which the zone's lighting effects and avatar permissions
@@ -1247,7 +1266,7 @@ QScriptValue EntityItemProperties::copyToScriptValue(QScriptEngine* engine, bool
COPY_PROPERTY_TO_QSCRIPTVALUE_GETTER(PROP_SHAPE_TYPE, shapeType, getShapeTypeAsString());
}
- // FIXME: Shouldn't provide a shapeType property for Box and Sphere entities?
+ // FIXME: Shouldn't provide a shapeType property for Box and Sphere entities.
if (_type == EntityTypes::Box) {
COPY_PROPERTY_TO_QSCRIPTVALUE_GETTER(PROP_SHAPE_TYPE, shapeType, QString("Box"));
}
diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h
index 166b2130ef..3a5f6e18ab 100644
--- a/libraries/entities/src/EntityScriptingInterface.h
+++ b/libraries/entities/src/EntityScriptingInterface.h
@@ -186,8 +186,8 @@ public slots:
/**jsdoc
* Check whether or not you can make changes to the asset server's assets.
* @function Entities.canWriteAssets
- * @returns {boolean} true if the domain server will allow the script to make changes to the to the asset
- * server's assets, otherwise false.
+ * @returns {boolean} true if the domain server will allow the script to make changes to the asset server's
+ * assets, otherwise false.
*/
Q_INVOKABLE bool canWriteAssets();
@@ -481,7 +481,7 @@ public slots:
Q_INVOKABLE bool getServerScriptStatus(QUuid entityID, QScriptValue callback);
/**jsdoc
- * Get metadata for "magic" entity properties such as script and serverScripts.
+ * Get metadata for certain entity properties such as script and serverScripts.
* @function Entities.queryPropertyMetadata
* @param {Uuid} entityID - The ID of the entity to get the metadata for.
* @param {string} property - The property name to get the metadata for.
@@ -491,7 +491,7 @@ public slots:
* @throws Throws an error if property is not handled yet or callback is not a function.
*/
/**jsdoc
- * Get metadata for "magic" entity properties such as script and serverScripts.
+ * Get metadata for certain entity properties such as script and serverScripts.
* @function Entities.queryPropertyMetadata
* @param {Uuid} entityID - The ID of the entity to get the metadata for.
* @param {string} property - The property name to get the metadata for.
@@ -513,8 +513,9 @@ public slots:
/**jsdoc
- * Set 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
+ * Set whether or not ray picks intersect the bounding box of {@link Entities.EntityType|Light} entities. By default, Light
+ * entities are not intersected. The setting lasts for the Interface session. Ray picks are done using
+ * {@link Entities.findRayIntersection|findRayIntersection} or
* {@link Entities.findRayIntersectionBlocking|findRayIntersectionBlocking}, or the {@link Picks} and {@link RayPick}
* APIs.
* @function Entities.setLightsArePickable
@@ -526,7 +527,7 @@ public slots:
/**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
+ * done using {@link Entities.findRayIntersection|findRayIntersection} or
* {@link Entities.findRayIntersectionBlocking|findRayIntersectionBlocking}, or the {@link Picks} and {@link RayPick}
* APIs.
* @function Entities.getLightsArePickable
@@ -537,8 +538,9 @@ public slots:
Q_INVOKABLE bool getLightsArePickable() const;
/**jsdoc
- * Set 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
+ * 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
* {@link Entities.findRayIntersectionBlocking|findRayIntersectionBlocking}, or the {@link Picks} and {@link RayPick}
* APIs.
* @function Entities.setZonesArePickable
@@ -550,7 +552,7 @@ public slots:
/**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
+ * done using {@link Entities.findRayIntersection|findRayIntersection} or
* {@link Entities.findRayIntersectionBlocking|findRayIntersectionBlocking}, or the {@link Picks} and {@link RayPick}
* APIs.
* @function Entities.getZonesArePickable
@@ -584,8 +586,8 @@ public slots:
* @function Entities.setVoxelSphere
* @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
* @param {Vec3} center - The center of the sphere of voxels to set, in world coordinates.
- * @param {number} radius - If radius of the sphere of voxels to set, in world coordinates.
- * @param {number} value - If value % 256 == 0 then the each voxel is cleared, otherwise each voxel is set.
+ * @param {number} radius - The radius of the sphere of voxels to set, in world coordinates.
+ * @param {number} value - If value % 256 == 0 then each voxel is cleared, otherwise each voxel is set.
* @example Create a PolyVox sphere.
* var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 }));
* var polyVox = Entities.addEntity({
@@ -607,7 +609,7 @@ public slots:
* @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.
- * @param {number} value - If value % 256 == 0 then the each voxel is cleared, otherwise each voxel is set.
+ * @param {number} value - If value % 256 == 0 then each voxel is cleared, otherwise each voxel is set.
* @example Create a PolyVox capsule shape.
* var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 }));
* var polyVox = Entities.addEntity({
@@ -631,7 +633,7 @@ public slots:
* @param {Vec3} position - The position relative to the minimum axes values corner of the entity. The
* position coordinates are rounded to the nearest integer to get the voxel coordinate. The minimum axes
* corner voxel is { x: 0, y: 0, z: 0 }.
- * @param {number} value - If value % 256 == 0 then the voxel is cleared, otherwise the voxel is set.
+ * @param {number} value - If value % 256 == 0 then voxel is cleared, otherwise the voxel is set.
* @example Create a cube PolyVox entity and clear the minimum axes corner voxel.
* var entity = Entities.addEntity({
* type: "PolyVox",
@@ -650,7 +652,7 @@ public slots:
* Set the values of all voxels in a {@link Entities.EntityType|PolyVox} entity.
* @function Entities.setAllVoxels
* @param {Uuid} entityID - The ID of the {@link Entities.EntityType|PolyVox} entity.
- * @param {number} value - If value % 256 == 0 then the each voxel is cleared, otherwise each voxel is set.
+ * @param {number} value - If value % 256 == 0 then each voxel is cleared, otherwise each voxel is set.
* @example Create a PolyVox cube.
* var entity = Entities.addEntity({
* type: "PolyVox",
@@ -671,7 +673,7 @@ public slots:
* @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.
- * @param {number} value - If value % 256 == 0 then the each voxel is cleared, otherwise each voxel is set.
+ * @param {number} value - If value % 256 == 0 then each voxel is cleared, otherwise each voxel is set.
* @example Create a PolyVox cube and clear the voxels in one corner.
* var polyVox = Entities.addEntity({
* type: "PolyVox",
@@ -745,7 +747,7 @@ public slots:
* @param {Vec3} voxelCoords - The voxel coordinates. May be fractional and outside the entity's bounding box.
* @returns {Vec3} The local coordinates of the voxelCoords if the entityID is a
* {@link Entities.EntityType|PolyVox} entity, otherwise {@link Vec3|Vec3.ZERO}.
- * @example Get the world dimensions of a voxel in a PolyVox entity.
+ * @example Get the world dimensions of a voxel in a PolyVox entity.
* var polyVox = Entities.addEntity({
* type: "PolyVox",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 })),
@@ -849,7 +851,7 @@ public slots:
* @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 successful, otherwise null.
+ * @returns {Uuid} The ID of the action added if successfully added, otherwise null.
* @example Constrain a cube to move along a vertical line.
* var entityID = Entities.addEntity({
* type: "Box",
@@ -919,7 +921,7 @@ public slots:
Q_INVOKABLE glm::vec3 getAbsoluteJointTranslationInObjectFrame(const QUuid& entityID, int jointIndex);
/**jsdoc
- * Get the trannslation of a joint in a {@link Entities.EntityType|Model} entity relative to the entity's coordinate frame.
+ * Get the translation of a joint in a {@link Entities.EntityType|Model} entity relative to the entity's coordinate frame.
* @function Entities.getAbsoluteJointRotationInObjectFrame
* @param {Uuid} entityID - The ID of the entity.
* @param {number} jointIndex - The integer index of the joint.
@@ -1068,7 +1070,8 @@ public slots:
/**jsdoc
- * Get the IDs of entities, overlays, and avatars that are directly parented to an entity.
+ * Get the IDs of entities, overlays, and avatars that are directly parented to an entity. To get all descendants of an
+ * entity, recurse on the IDs returned by the function.
* @function Entities.getChildrenIDs
* @param {Uuid} parentID - The ID of the entity to get the children IDs of.
* @returns {Uuid[]} An array of entity, overlay, and avatar IDs that are parented directly to the parentID
@@ -1133,11 +1136,11 @@ public slots:
Q_INVOKABLE QVector getChildrenIDsOfJoint(const QUuid& parentID, int jointIndex);
/**jsdoc
- * Check whether an entity or overlay has a an entity as an ancestor (parent, parent's parent, etc.).
+ * Check whether an entity or overlay has an entity as an ancestor (parent, parent's parent, etc.).
* @function Entities.isChildOfParent
* @param {Uuid} childID - The ID of the child entity or overlay 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.
- * @returns {boolean} true if the childID> entity or overlay has the parentID entity
+ * @returns {boolean} true if the childID entity or overlay has the parentID entity
* as a parent or grandparent etc., otherwise false.
* @example Check that a grandchild entity is a child of its grandparent.
* function createEntity(description, position, parent) {
@@ -1273,8 +1276,8 @@ public slots:
* but a {@link Entities.EntityType|Shape} entity doesn't.
* @function Entities.wantsHandControllerPointerEvents
* @param {Uuid} entityID - The ID of the entity.
- * @returns {boolean} true if the entity entity can be found and it wants hand controller pointer events,
- * otherwise false.
+ * @returns {boolean} true if the entity can be found and it wants hand controller pointer events, otherwise
+ * false.
*/
Q_INVOKABLE bool wantsHandControllerPointerEvents(QUuid id);
@@ -1657,7 +1660,7 @@ signals:
/**jsdoc
* Triggered when an avatar leaves an entity.
- * @function Entities.enterEntity
+ * @function Entities.leaveEntity
* @param {Uuid} entityID - The ID of the entity that the avatar left.
* @returns {Signal}
*/
diff --git a/libraries/entities/src/EntityTypes.h b/libraries/entities/src/EntityTypes.h
index bcde8893c4..0e2fca8180 100644
--- a/libraries/entities/src/EntityTypes.h
+++ b/libraries/entities/src/EntityTypes.h
@@ -42,8 +42,12 @@ public:
* Value Description Properties "Box"A rectangular prism. This is identical to the Shape EntityType except
- * that it is always created with an initial shape property value of "Cube".
+ * "Box"A rectangular prism. This is a synonym of "Shape" for the case
+ * where the entity's shape property value is "Cube".
+ * If an entity is created with its type
+ * set to "Box" it will always be created with a shape property value of
+ * "Cube". If an entity of type Shape or Sphere has its shape set
+ * to "Cube" then its type will be reported as "Box".
* {@link Entities.EntityProperties-Box|EntityProperties-Box} "Light"A local lighting effect.
* {@link Entities.EntityProperties-Light|EntityProperties-Light} "PolyVox"A set of textured voxels.
* {@link Entities.EntityProperties-PolyVox|EntityProperties-PolyVox} "Shape"A basic entity such as a cube.
- * See also, the Box and Sphere entity types.
+ * See also, the "Box" and "Sphere" entity types.
* {@link Entities.EntityProperties-Shape|EntityProperties-Shape} "Sphere"A sphere. This is identical to the Shape EntityType except that it is
- * always created with an initial shape property value of "Sphere".
+ * "Sphere"A sphere. This is a synonym of "Shape" for the case
+ * where the entity's shape property value is "Sphere".
+ * If an entity is created with its type
+ * set to "Sphere" it will always be created with a shape property value of
+ * "Sphere". If an entity of type Box or Shape has its shape set
+ * to "Sphere" then its type will be reported as "Sphere".
* {@link Entities.EntityProperties-Sphere|EntityProperties-Sphere} "Text"A pane of text oriented in space.
* {@link Entities.EntityProperties-Text|EntityProperties-Text} true then haze decreases with altitude as defined by the
* entity's local coordinate system; hazeBaseRef and hazeCeiling are used.
- * @property {number} hazeBaseRef=0 - The y-azis value in the entity's local coordinate system at which the haze density starts
+ * @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
* reduced to 5%.
diff --git a/libraries/model-networking/src/model-networking/MaterialCache.cpp b/libraries/model-networking/src/model-networking/MaterialCache.cpp
index de5b3023ae..01bb43759c 100644
--- a/libraries/model-networking/src/model-networking/MaterialCache.cpp
+++ b/libraries/model-networking/src/model-networking/MaterialCache.cpp
@@ -106,8 +106,8 @@ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMater
* @typedef {object} Material
* @property {string} name="" - A name for the material.
* @property {string} model="hifi_pbr" - Currently not used.
- * @property {Vec3Color|RGBS} emissive - The emissive color. A {@link Vec3Color} value is treated as sRGB. A {@link RGBS} value
- * can be either RGB or sRGB.
+ * @property {Vec3Color|RGBS} emissive - The emissive color, i.e., the color that the material emits. A {@link Vec3Color} value
+ * is treated as sRGB. A {@link RGBS} value can be either RGB or sRGB.
* @property {number} opacity=1.0 - The opacity, 0.0 – 1.0.
* @property {boolean} unlit=false - If true, the material is not lit.
* @property {Vec3Color|RGBS} albedo - The albedo color. A {@link Vec3Color} value is treated as sRGB. A {@link RGBS} value can
diff --git a/libraries/octree/src/OctreeScriptingInterface.h b/libraries/octree/src/OctreeScriptingInterface.h
index 4154911d08..e501dd166a 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 send per second.
+ * Set 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.
*/
@@ -53,7 +53,8 @@ public slots:
int getPacketsPerSecond() const { return _packetSender->getPacketsPerSecond(); }
/**jsdoc
- * Check whether servers exist for the client to send entity packets to.
+ * Check whether servers exist for the client to send entity packets to, i.e., whether you are connected to a domain and
+ * its entity server is working.
* @function Entities.serversExist
* @returns {boolean} true if servers exist for the client to send entity packets to, otherwise
* false.
diff --git a/libraries/shared/src/PhysicsCollisionGroups.h b/libraries/shared/src/PhysicsCollisionGroups.h
index 0eb1d2021f..edec61dc67 100644
--- a/libraries/shared/src/PhysicsCollisionGroups.h
+++ b/libraries/shared/src/PhysicsCollisionGroups.h
@@ -79,7 +79,8 @@ const int16_t BULLET_COLLISION_MASK_COLLISIONLESS = 0;
* 16Other avatars. The values for the collision types that are enabled are added together to give the CollisionMask value.
+ * The values for the collision types that are enabled are added together to give the CollisionMask value. For example, a
+ * value of 31 means that an entity will collide with all item types.
* @typedef {number} Entities.CollisionMask
*/