From eeb7f5ca8df3369dd7f34ab508dabfb64a101a04 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 7 Mar 2018 17:29:39 +1300 Subject: [PATCH] Doc review --- interface/src/avatar/AvatarActionFarGrab.h | 3 +- interface/src/avatar/AvatarActionHold.cpp | 4 +- .../entities/src/EntityDynamicInterface.cpp | 8 +- .../entities/src/EntityItemProperties.cpp | 133 ++++++++++-------- .../entities/src/EntityScriptingInterface.h | 53 +++---- libraries/entities/src/EntityTypes.h | 18 ++- libraries/entities/src/HazePropertyGroup.h | 2 +- .../src/model-networking/MaterialCache.cpp | 4 +- .../octree/src/OctreeScriptingInterface.h | 5 +- libraries/shared/src/PhysicsCollisionGroups.h | 3 +- 10 files changed, 133 insertions(+), 100 deletions(-) diff --git a/interface/src/avatar/AvatarActionFarGrab.h b/interface/src/avatar/AvatarActionFarGrab.h index c93f243551..97d4a6bb03 100644 --- a/interface/src/avatar/AvatarActionFarGrab.h +++ b/interface/src/avatar/AvatarActionFarGrab.h @@ -17,7 +17,8 @@ /**jsdoc * The "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"Avatar action -* 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. +* Moves and rotates an entity to a target position and orientation, optionally relative to another entity. Collisions +* between the entity and the user's avatar are disabled during the far-grab. * {@link Entities.ActionArguments-FarGrab} * "hold"Avatar action -* Positions and rotates an entity relative to an avatar's hand, without collisions between the entity and the holding -* avatar. +* Positions and rotates an entity relative to an avatar's hand. Collisions between the entity and the user's avatar +* are disabled during the hold. * {@link Entities.ActionArguments-Hold} * "offset"Object action * Moves an entity so that it is a set distance away from a target point. diff --git a/libraries/entities/src/EntityItemProperties.cpp b/libraries/entities/src/EntityItemProperties.cpp index a6f15c5fdd..324cf15a07 100644 --- a/libraries/entities/src/EntityItemProperties.cpp +++ b/libraries/entities/src/EntityItemProperties.cpp @@ -447,8 +447,9 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { * @typedef {object} Entities.EntityProperties * @property {Uuid} id - The ID of the entity. Read-only. * @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. - * Read-only. + * @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 "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 Create a spotlight pointing at the ground. @@ -724,15 +731,16 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { * @typedef {object} Entities.EntityProperties-Model * @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. When adding an entity, if no dimensions * value is specified then the model is automatically sized to its - * {@link 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".
* Note: If the name ends with "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 Crate an "Image" entity like the Create app. + * @example Create an "Image" entity like you can in the Create app. * var IMAGE_MODEL = "https://hifi-content.s3.amazonaws.com/DomainContent/production/default-image-model.fbx"; * var DEFAULT_IMAGE = "https://hifi-content.s3.amazonaws.com/DomainContent/production/no-image.jpg"; * var entity = Entities.addEntity({ @@ -807,7 +815,8 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { * @property {number} emitSpeed=5 - The speed, in m/s, that each particle is emitted at. * @property {number} speedSpread=1 - The spread in speeds at which particles are emitted at. If emitSpeed == 5 * and speedSpread == 1, particles will be emitted with speeds in the range 4m/s – 6m/s. - * @property {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: * ValueDescriptionProperties * * - * "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} @@ -62,10 +66,14 @@ public: * "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} diff --git a/libraries/entities/src/HazePropertyGroup.h b/libraries/entities/src/HazePropertyGroup.h index 1437a5fe12..e992aefbf3 100644 --- a/libraries/entities/src/HazePropertyGroup.h +++ b/libraries/entities/src/HazePropertyGroup.h @@ -57,7 +57,7 @@ static const float INITIAL_KEY_LIGHT_ALTITUDE{ 200.0f }; * * @property {boolean} hazeAltitudeEffect=false - If true then haze decreases with altitude as defined by the * entity's local coordinate system; hazeBaseRef and hazeCeiling are used. - * @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 */