From b16086de74eb92e9450bdf13bae9878837c29246 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sat, 15 Jun 2019 10:22:14 +1200 Subject: [PATCH] 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 - true to enable translations contained in the animation to be + * played, false to disable translations. * @property {number} fps=30 - The speed in frames/s that the animation is played at. * @property {number} firstFrame=0 - The first frame to play in the animation. * @property {number} lastFrame=100000 - The last frame to play in the animation. * @property {number} currentFrame=0 - The current frame being played in the animation. * @property {boolean} running=false - If true then the animation should play. - * @property {boolean} loop=true - If true then the animation should be continuously repeated in a loop. - * @property {boolean} hold=false - If true then the rotations and translations of the last frame played should be + * @property {boolean} loop=true - If true then the animation is continuously repeated in a loop. + * @property {boolean} hold=false - If true then the rotations and translations of the last frame played are * maintained when the animation stops playing. */ void AnimationPropertyGroup::copyToScriptValue(const EntityPropertyFlags& desiredProperties, QScriptValue& properties, QScriptEngine* engine, bool skipDefaults, EntityItemProperties& defaultEntityProperties) const { diff --git a/libraries/entities/src/BloomPropertyGroup.h b/libraries/entities/src/BloomPropertyGroup.h index a1f9b6d748..12743c9298 100644 --- a/libraries/entities/src/BloomPropertyGroup.h +++ b/libraries/entities/src/BloomPropertyGroup.h @@ -31,9 +31,8 @@ static const float INITIAL_BLOOM_THRESHOLD { 0.7f }; static const float INITIAL_BLOOM_SIZE { 0.9f }; /**jsdoc - * Bloom is defined by the following properties. + * Bloom is defined by the following properties: * @typedef {object} Entities.Bloom - * * @property {number} bloomIntensity=0.25 - The intensity of the bloom effect. * @property {number} bloomThreshold=0.7 - The threshold for the bloom effect. * @property {number} bloomSize=0.9 - The size of the bloom effect. diff --git a/libraries/entities/src/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. 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. (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 {EntityHostType} entityHostType="domain" - How this entity will behave, including if and how it is sent to other people. - * The value can only be set at entity creation by using the entityHostType parameter in - * {@link Entities.addEntity}. Read-only. - * @property {boolean} avatarEntity=false - If true then the entity is an avatar entity; An avatar entity follows you to each domain you visit, - * rendering at the same world coordinates unless it's parented to your avatar. Value cannot be changed after the entity is created.
- * The value can only be set at entity creation by using the entityHostType parameter in - * {@link Entities.addEntity}. clientOnly is an alias. Read-only. - * @property {boolean} localEntity=false - If true then the entity is a local entity; Local entities only render for you and are not sent over the wire. - * Value cannot be changed after the entity is created.
- * The value can only be set at entity creation by using the entityHostType parameter in - * {@link Entities.addEntity}. Read-only. + * @property {Entities.EntityType} type - The entity's type. You cannot change the type of an entity after it's created. + * However, its value may switch among "Box", "Shape", and "Sphere" depending on + * changes to the shape property set for entities of these types. Read-only. + * + * @property {Entities.EntityHostType} entityHostType="domain" - How the entity is hosted and sent to others for display. + * The value can only be set at entity creation by one of the {@link Entities.addEntity} methods. Read-only. + * @property {boolean} avatarEntity=false - true if the entity is an {@link Entities.EntityHostType|avatar entity}, + * false if it isn't. The value is per the entityHostType property value, set at entity creation + * by one of the {@link Entities.addEntity} methods. Read-only. + * @property {boolean} clientOnly=false - A synonym for avatarEntity. Read-only. + * @property {boolean} localEntity=false - true if the entity is a {@link Entities.EntityHostType|local entity}, + * false if it isn't. The value is per the entityHostType property value, set at entity creation + * by one of the {@link Entities.addEntity} methods. Read-only. + * * @property {Uuid} owningAvatarID=Uuid.NULL - The session ID of the owning avatar if avatarEntity is * true, otherwise {@link Uuid(0)|Uuid.NULL}. Read-only. * @@ -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 castShadows enabled in its * {@link Entities.EntityProperties-Zone|keyLight} property. - * @property {boolean} isVisibleInSecondaryCamera=true - Whether or not the entity is rendered in the secondary camera. If true then the entity is rendered. - * @property {RenderLayer} renderLayer="world" - In which layer this entity renders. - * @property {PrimitiveMode} primitiveMode="solid" - How this entity's geometry is rendered. - * @property {boolean} ignorePickIntersection=false - If true, picks ignore the entity. + * @property {boolean} isVisibleInSecondaryCamera=true - true if the entity is rendered in the secondary camera, + * false if it isn't. + * @property {Entities.RenderLayer} renderLayer="world" - Which layer the entity renders in. + * @property {Entities.PrimitiveMode} primitiveMode="solid" - How the entity's geometry is rendered. + * @property {boolean} ignorePickIntersection=false - true if {@link Picks} and {@link RayPick} ignore the entity, + * false if they don't 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}. Read-only. @@ -668,72 +670,74 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { * {@link Vec3(0)|Vec3.ONE}. Read-only. * * @property {Vec3} velocity=0,0,0 - The linear velocity of the entity in m/s with respect to world coordinates. - * @property {number} damping=0.39347 - How much to slow down the linear velocity of an entity over time, 0.0 - * – 1.0. A higher damping value slows down the entity more quickly. The default value is for an - * exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to 1/e = 0.368 of its - * initial value. + * @property {number} damping=0.39347 - How much to slow down the linear velocity of an entity over time, range + * 0.0 – 1.0. A higher damping value slows down the entity more quickly. The default value + * is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to 1/e = 0.368 + * of its initial value. * @property {Vec3} angularVelocity=0,0,0 - The angular velocity of the entity in rad/s with respect to its axes, about its * registration point. - * @property {number} angularDamping=0.39347 - How much to slow down the angular velocity of an entity over time, + * @property {number} angularDamping=0.39347 - How much to slow down the angular velocity of an entity over time, range * 0.0 – 1.0. A higher damping value slows down the entity more quickly. The default value * is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to 1/e = 0.368 * of its initial value. * * @property {Vec3} gravity=0,0,0 - The acceleration due to gravity in m/s2 that the entity should move with, in - * world coordinates. Set to { x: 0, y: -9.8, z: 0 } to simulate Earth's gravity. Gravity is applied to an - * entity's motion only if its dynamic property is true. If changing an entity's - * gravity from {@link Vec3(0)|Vec3.ZERO}, you need to give it a small velocity in order to kick - * off physics simulation. - * The gravity value is applied in addition to the acceleration value. + * world coordinates. Use a value of { x: 0, y: -9.8, z: 0 } to simulate Earth's gravity. Gravity is applied + * to an entity's motion only if its dynamic property is true. The gravity value is + * applied in addition to the acceleration value. + *

If changing an entity's gravity from {@link Vec3(0)|Vec3.ZERO}, you need to give it a small + * velocity in order to kick off physics simulation.

* @property {Vec3} acceleration=0,0,0 - A general acceleration in m/s2 that the entity should move with, in world * coordinates. The acceleration is applied to an entity's motion only if its dynamic property is - * true. If changing an entity's acceleration from {@link Vec3(0)|Vec3.ZERO}, you need to give it - * a small velocity in order to kick off physics simulation. - * The acceleration value is applied in addition to the gravity value. - * @property {number} restitution=0.5 - The "bounciness" of an entity when it collides, 0.0 – + * true. The acceleration value is applied in addition to the gravity value. + *

If changing an entity's acceleration from {@link Vec3(0)|Vec3.ZERO}, you need to give it a small + * velocity in order to kick off physics simulation.

+ * @property {number} restitution=0.5 - The "bounciness" of an entity when it collides, range 0.0 – * 0.99. The higher the value, the more bouncy. - * @property {number} friction=0.5 - How much to slow down an entity when it's moving against another, 0.0 – - * 10.0. The higher the value, the more quickly it slows down. Examples: 0.1 for ice, + * @property {number} friction=0.5 - How much to slow down an entity when it's moving against another, range 0.0 + * – 10.0. The higher the value, the more quickly it slows down. Examples: 0.1 for ice, * 0.9 for sandpaper. - * @property {number} density=1000 - The density of the entity in kg/m3, 100 for balsa wood – - * 10000 for silver. The density is used in conjunction with the entity's bounding box volume to work out its - * mass in the application of physics. + * @property {number} density=1000 - The density of the entity in kg/m3, range 100 for balsa wood + * – 10000 for silver. The density is used in conjunction with the entity's bounding box volume to work + * out its mass in the application of physics. * * @property {boolean} collisionless=false - Whether or not the entity should collide with items per its - * collisionMask property. If true then the entity does not collide. A synonym is ignoreForCollisions. + * collisionMask property. If true then the entity does not collide. + * @property {boolean} ignoreForCollisions - Synonym for collisionless. * @property {CollisionMask} collisionMask=31 - What types of items the entity should collide with. * @property {string} collidesWith="static,dynamic,kinematic,myAvatar,otherAvatar," - Synonym for collisionMask, * in text format. - * @property {string} collisionSoundURL="" - The sound to play when the entity experiences a collision. Valid file formats are - * as per the {@link SoundCache} object. + * @property {string} collisionSoundURL="" - The sound that's played when the entity experiences a collision. Valid file + * formats are per {@link SoundObject}. * @property {boolean} dynamic=false - Whether or not the entity should be affected by collisions. If true then - * the entity's movement is affected by collisions. A synonym is collisionsWillMove. + * the entity's movement is affected by collisions. + * @property {boolean} collisionsWillMove - A synonym for dynamic. * - * @property {string} href="" - A "hifi://" metaverse address that a user is taken to when they click on the entity. + * @property {string} href="" - A "hifi://" metaverse address that a user is teleported to when they click on the entity. * @property {string} description="" - A description of the href property value. * - * @property {string} userData="" - Used to store extra data about the entity in JSON format. WARNING: Other apps such as the - * Create app can also use this property, so make sure you handle data stored by other apps — edit only your bit and - * leave the rest of the data intact. You can use JSON.parse() to parse the string into a JavaScript object - * which you can manipulate the properties of, and use JSON.stringify() to convert the object into a string to - * put in the property. + * @property {string} userData="" - Used to store extra data about the entity in JSON format. + *

Warning: Other apps may also use this property, so make sure you handle data stored by other apps: + * edit only your bit and leave the rest of the data intact. You can use JSON.parse() to parse the string into + * a JavaScript object which you can manipulate the properties of, and use JSON.stringify() to convert the + * object into a string to put back in the property.

* - * @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 userData, but only accessible by server entity scripts, assignment + * client scripts, and users who have "Can Get and Set Private User Data" permissions in the domain. * * @property {string} script="" - The URL of the client entity script, if any, that is attached to the entity. - * @property {number} scriptTimestamp=0 - Intended to be used to indicate when the client entity script was loaded. Should be + * @property {number} scriptTimestamp=0 - Used to indicate when the client entity script was loaded. Should be * an integer number of milliseconds since midnight GMT on January 1, 1970 (e.g., as supplied by Date.now(). * If you update the property's value, the script is re-downloaded and reloaded. This is how the "reload" * button beside the "script URL" field in properties tab of the Create app works. * @property {string} serverScripts="" - The URL of the server entity script, if any, that is attached to the entity. * - * @property {Uuid} parentID=Uuid.NULL - The ID of the entity or avatar that this entity is parented to. {@link Uuid(0)|Uuid.NULL} - * if the entity is not parented. - * @property {number} parentJointIndex=65535 - The joint of the entity or avatar that this entity is parented to. Use + * @property {Uuid} parentID=Uuid.NULL - The ID of the entity or avatar that the entity is parented to. + * {@link Uuid(0)|Uuid.NULL} if the entity is not parented. + * @property {number} parentJointIndex=65535 - The joint of the entity or avatar that the entity is parented to. Use * 65535 or -1 to parent to the entity or avatar's position and orientation rather than a joint. * @property {Vec3} localPosition=0,0,0 - The position of the entity relative to its parent if the entity is parented, - * otherwise the same value as position. If the entity is parented to an avatar and is an avatarEntity + * otherwise the same value as position. If the entity is parented to an avatar and is an avatar entity * so that it scales with the avatar, this value remains the original local position value while the avatar scale changes. * @property {Quat} localRotation=0,0,0,1 - The rotation of the entity relative to its parent if the entity is parented, * otherwise the same value as rotation. @@ -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 position. * @property {Vec3} localDimensions - The dimensions of the entity. If the entity is parented to an avatar and is an - * avatarEntity so that it scales with the avatar, this value remains the original dimensions value while the + * avatar entity so that it scales with the avatar, this value remains the original dimensions value while the * avatar scale changes. * * @property {Entities.BoundingBox} boundingBox - The axis-aligned bounding box that tightly encloses the entity. @@ -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 Model entities. Read-only. * - * @property {boolean} cloneable=false - If true then the entity can be cloned via {@link Entities.cloneEntity}. + * @property {boolean} cloneable=false - If true then the domain or avatar entity can be cloned via + * {@link Entities.cloneEntity}. * @property {number} cloneLifetime=300 - The entity lifetime for clones created from this entity. * @property {number} cloneLimit=0 - The total number of clones of this entity that can exist in the domain at any given time. * @property {boolean} cloneDynamic=false - If true then clones created from this entity will have their * dynamic property set to true. * @property {boolean} cloneAvatarEntity=false - If true then clones created from this entity will be created as - * avatar entities: their avatarEntity property will be set to true. + * avatar entities. * @property {Uuid} cloneOriginID - The ID of the entity that this entity was cloned from. * - * @property {Entities.Grab} grab - The grab-related properties. + * @property {Entities.Grab} grab - The entity's grab-related properties. * * @property {string} itemName="" - Certifiable name of the Marketplace item. * @property {string} itemDescription="" - Certifiable description of the Marketplace item. * @property {string} itemCategories="" - Certifiable category of the Marketplace item. - * @property {string} itemArtist="" - Certifiable artist that created the Marketplace item. + * @property {string} itemArtist="" - Certifiable artist that created the Marketplace item. * @property {string} itemLicense="" - Certifiable license URL for the Marketplace item. * @property {number} limitedRun=4294967295 - Certifiable maximum integer number of editions (copies) of the Marketplace item * allowed to be sold. * @property {number} editionNumber=0 - Certifiable integer edition (copy) number or the Marketplace item. Each copy sold in * the Marketplace is numbered sequentially, starting at 1. * @property {number} entityInstanceNumber=0 - Certifiable integer instance number for identical entities in a Marketplace - * item. A Marketplace item may have identical parts. If so, then each is numbered sequentially with an instance number. + * item. A Marketplace item may have multiple, identical parts. If so, then each is numbered sequentially with an instance + * number. * @property {string} marketplaceID="" - Certifiable UUID for the Marketplace item, as used in the URL of the item's download * and its Marketplace Web page. * @property {string} certificateID="" - Hash of the entity's static certificate JSON, signed by the artist's private key. * @property {number} staticCertificateVersion=0 - The version of the method used to generate the certificateID. * - * @see The different entity types have additional properties as follows: + * @comment The different entity types have additional properties as follows: * @see {@link Entities.EntityProperties-Box|EntityProperties-Box} - * @see {@link Entities.EntityProperties-Sphere|EntityProperties-Sphere} - * @see {@link Entities.EntityProperties-Shape|EntityProperties-Shape} - * @see {@link Entities.EntityProperties-Model|EntityProperties-Model} - * @see {@link Entities.EntityProperties-Text|EntityProperties-Text} + * @see {@link Entities.EntityProperties-Gizmo|EntityProperties-Gizmo} + * @see {@link Entities.EntityProperties-Grid|EntityProperties-Grid} * @see {@link Entities.EntityProperties-Image|EntityProperties-Image} - * @see {@link Entities.EntityProperties-Web|EntityProperties-Web} - * @see {@link Entities.EntityProperties-ParticleEffect|EntityProperties-ParticleEffect} + * @see {@link Entities.EntityProperties-Light|EntityProperties-Light} * @see {@link Entities.EntityProperties-Line|EntityProperties-Line} + * @see {@link Entities.EntityProperties-Material|EntityProperties-Material} + * @see {@link Entities.EntityProperties-Model|EntityProperties-Model} + * @see {@link Entities.EntityProperties-ParticleEffect|EntityProperties-ParticleEffect} * @see {@link Entities.EntityProperties-PolyLine|EntityProperties-PolyLine} * @see {@link Entities.EntityProperties-PolyVox|EntityProperties-PolyVox} - * @see {@link Entities.EntityProperties-Grid|EntityProperties-Grid} - * @see {@link Entities.EntityProperties-Gizmo|EntityProperties-Gizmo} - * @see {@link Entities.EntityProperties-Light|EntityProperties-Light} + * @see {@link Entities.EntityProperties-Shape|EntityProperties-Shape} + * @see {@link Entities.EntityProperties-Sphere|EntityProperties-Sphere} + * @see {@link Entities.EntityProperties-Text|EntityProperties-Text} + * @see {@link Entities.EntityProperties-Web|EntityProperties-Web} * @see {@link Entities.EntityProperties-Zone|EntityProperties-Zone} - * @see {@link Entities.EntityProperties-Material|EntityProperties-Material} */ /**jsdoc @@ -812,20 +818,23 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { * when the entity is created. If its shape property value is subsequently changed then the entity's * type will be reported as "Sphere" if the shape is set to "Sphere", * otherwise it will be reported as "Shape". + * * @typedef {object} Entities.EntityProperties-Box + * @see {@link Entities.EntityProperties-Shape|EntityProperties-Shape} */ /**jsdoc - * The "Light" {@link Entities.EntityType|EntityType} adds local lighting effects. - * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * The "Light" {@link Entities.EntityType|EntityType} adds local lighting effects. It has properties in addition + * to the common {@link Entities.EntityProperties|EntityProperties}. + * * @typedef {object} Entities.EntityProperties-Light - * @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. Entity surface outside these dimensions are not lit + * @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. Surfaces outside these dimensions are not lit * by the light. * @property {Color} color=255,255,255 - The color of the light emitted. * @property {number} intensity=1 - The brightness of the light. * @property {number} falloffRadius=0.1 - The distance from the light's center at which intensity is reduced by 25%. * @property {boolean} isSpotlight=false - If true then the light is directional, emitting along the entity's - * local negative z-axis; otherwise the light is a point light which emanates in all directions. + * local negative z-axis; otherwise, the light is a point light which emanates in all directions. * @property {number} exponent=0 - Affects the softness of the spotlight beam: the higher the value the softer the beam. * @property {number} cutoff=1.57 - Affects the size of the spotlight beam: the higher the value the larger the beam. * @example Create a spotlight pointing at the ground. @@ -845,8 +854,9 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { /**jsdoc * The "Line" {@link Entities.EntityType|EntityType} draws thin, straight lines between a sequence of two or more - * points. Deprecated: Use PolyLines instead. - * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * points. It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + *

Deprecated: Use PolyLines instead.

+ * * @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 * linePoints. @@ -871,41 +881,46 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { */ /**jsdoc - * The "Material" {@link Entities.EntityType|EntityType} modifies the existing materials on entities and avatars. - * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
- * To apply a material to an entity, set the material entity's parentID property to the entity ID. + * The "Material" {@link Entities.EntityType|EntityType} modifies existing materials on entities and avatars. It + * has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + *

To apply a material to an entity, set the material entity's parentID property to the entity ID. * To apply a material to an avatar, set the material entity's parentID property to the avatar's session UUID. * To apply a material to your avatar such that it persists across domains and log-ins, create the material as an avatar entity - * by setting the entityHostType parameter in {@link Entities.addEntity} to "avatar". - * Material entities render as non-scalable spheres if they don't have their parent set. + * by setting the entityHostType parameter in {@link Entities.addEntity} to "avatar" and set the + * entity's parentID property to MyAvatar.SELF_ID. + * Material entities render as non-scalable spheres if they don't have their parent set.

+ * * @typedef {object} Entities.EntityProperties-Material - * @property {string} materialURL="" - URL to a {@link MaterialResource}. If you append #name to the URL, the - * material with that name in the {@link MaterialResource} will be applied to the entity.
- * Alternatively, set the property value to "materialData" to use the materialData property - * for the {@link MaterialResource} values. - * @property {number} priority=0 - The priority for applying the material to its parent. Only the highest priority material is + * @property {Vec3} dimensions=0.1,0.1,0.1 - Used when materialMappingMode == "projected". + * @property {string} materialURL="" - URL to a {@link Entities.MaterialResource|MaterialResource}. If you append + * "#name" to the URL, the material with that name in the {@link Entities.MaterialResource|MaterialResource} + * will be applied to the entity. Alternatively, set the property value to "materialData" to use the + * materialData property for the {@link Entities.MaterialResource|MaterialResource} values. + * @property {string} materialData="" - Used to store {@link Entities.MaterialResource|MaterialResource} data as a JSON string. + * You can use JSON.parse() to parse the string into a JavaScript object which you can manipulate the + * properties of, and use JSON.stringify() to convert the object into a string to put in the property. + * @property {number} priority=0 - The priority for applying the material to its parent. Only the highest priority material is * applied, with materials of the same priority randomly assigned. Materials that come with the model have a priority of * 0. * @property {string} parentMaterialName="0" - Selects the mesh part or parts within the parent to which to apply the material. * If in the format "mat::string", all mesh parts with material name "string" are replaced. - * Otherwise the property value is parsed as an unsigned integer, specifying the mesh part index to modify. If "all", - * all mesh parts will be replaced. If an array (starts with "[" and ends with "]"), the string will be - * split at each "," and each element will be parsed as either a number or a string if it starts with - * "mat::". In other words, "[0,1,mat::string,mat::string2]" will replace mesh parts 0 and 1, and any - * mesh parts with material "string" or "string2". Do not put spaces around the commas. Invalid values - * are parsed to 0. + * If "all" then all mesh parts are replaced. + * Otherwise the property value is parsed as an unsigned integer, specifying the mesh part index to modify. + *

If the string represents an array (starts with "[" and ends with "]"), the string is split + * at each "," and each element parsed as either a number or a string if it starts with "mat::". + * For example, "[0,1,mat::string,mat::string2]" will replace mesh parts 0 and 1, and any mesh parts with + * material "string" or "string2". Do not put spaces around the commas. Invalid values are parsed + * to 0.

* @property {string} materialMappingMode="uv" - How the material is mapped to the entity. Either "uv" or - * "projected". In "uv" mode, the material will be evaluated within the UV space of the mesh it is applied to. In - * "projected" mode, the 3D transform of the Material Entity will be used to evaluate the texture coordinates for the material. + * "projected". In "uv" mode, the material is evaluated within the UV space of the mesh it is + * applied to. In "projected" mode, the 3D transform (position, rotation, and dimensions) of the Material + * entity is used to evaluate the texture coordinates for the material. * @property {Vec2} materialMappingPos=0,0 - Offset position in UV-space of the top left of the material, range * { x: 0, y: 0 } – { x: 1, y: 1 }. * @property {Vec2} materialMappingScale=1,1 - How much to scale the material within the parent's UV-space. * @property {number} materialMappingRot=0 - How much to rotate the material within the parent's UV-space, in degrees. - * @property {string} materialData="" - Used to store {@link MaterialResource} data as a JSON string. You can use - * JSON.parse() to parse the string into a JavaScript object which you can manipulate the properties of, and - * use JSON.stringify() to convert the object into a string to put in the property. - * @property {boolean} materialRepeat=true - If true, the material will repeat. If false, fragments outside of texCoord 0 - 1 will be discarded. - * Works in both "uv" and "projected" modes. + * @property {boolean} materialRepeat=true - If true, the material repeats. If false, fragments + * outside of texCoord 0 – 1 will be discarded. Works in both "uv" and "projected" modes. * @example Color a sphere using a Material entity. * var entityID = Entities.addEntity({ * type: "Sphere", @@ -931,15 +946,20 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { */ /**jsdoc - * The "Model" {@link Entities.EntityType|EntityType} displays an FBX or OBJ model. - * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * The "Model" {@link Entities.EntityType|EntityType} displays a glTF, FBX, or OBJ model. When adding an entity, + * if no dimensions value is specified then the model is automatically sized to its + * {@link Entities.EntityProperties|naturalDimensions}. It has properties in addition to the common + * {@link Entities.EntityProperties|EntityProperties}. + * * @typedef {object} Entities.EntityProperties-Model * @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. When adding an entity, if no dimensions * value is specified then the model is automatically sized to its * {@link Entities.EntityProperties|naturalDimensions}. - * @property {Vec3} modelScale - The scale factor applied to the model's dimensions. Deprecated. - * @property {Color} color=255,255,255 - Currently not used. - * @property {string} modelURL="" - The URL of the FBX of OBJ model. Baked FBX models' URLs end in ".baked.fbx".
+ * @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. + *

Deprecated: This property is deprecated and will be removed.

* @property {string} textures="" - A JSON string of texture name, URL pairs used when rendering the model in place of the * model's original textures. Use a texture name from the originalTextures property to override that texture. * Only the texture names and URLs to be overridden need be specified; original textures are used where there are no @@ -948,6 +968,7 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { * @property {string} originalTextures="{}" - A JSON string of texture name, URL pairs used in the model. The property value is * filled in after the entity has finished rezzing (i.e., textures have loaded). You can use JSON.parse() to * parse the JSON string into a JavaScript object of name, URL pairs. Read-only. + * @property {Color} color=255,255,255 - Currently not used. * * @property {ShapeType} shapeType="none" - The shape of the collision hull used if collisions are enabled. * @property {string} compoundShapeURL="" - The model file to use for the compound shape if shapeType is @@ -955,22 +976,22 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { * * @property {Entities.AnimationProperties} animation - An animation to play on the model. * - * @property {Quat[]} jointRotations=[] - Joint rotations applied to the model; [] if none are applied or the + * @property {Quat[]} jointRotations=[]] - Joint rotations applied to the model; [] if none are applied or the * model hasn't loaded. The array indexes are per {@link Entities.getJointIndex|getJointIndex}. Rotations are relative to - * each joint's parent.
- * Joint rotations can be set by {@link Entities.setLocalJointRotation|setLocalJointRotation} and similar functions, or by - * setting the value of this property. If you set a joint rotation using this property you also need to set the - * corresponding jointRotationsSet value to true. - * @property {boolean[]} jointRotationsSet=[] - true values for joints that have had rotations applied, + * each joint's parent. + *

Joint rotations can be set by {@link Entities.setLocalJointRotation|setLocalJointRotation} and similar functions, or + * by setting the value of this property. If you set a joint rotation using this property you also need to set the + * corresponding jointRotationsSet value to true.

+ * @property {boolean[]} jointRotationsSet=[]] - true values for joints that have had rotations applied, * false otherwise; [] if none are applied or the model hasn't loaded. The array indexes are per * {@link Entities.getJointIndex|getJointIndex}. - * @property {Vec3[]} jointTranslations=[] - Joint translations applied to the model; [] if none are applied or + * @property {Vec3[]} jointTranslations=[]] - Joint translations applied to the model; [] if none are applied or * the model hasn't loaded. The array indexes are per {@link Entities.getJointIndex|getJointIndex}. Rotations are relative - * to each joint's parent.
- * Joint translations can be set by {@link Entities.setLocalJointTranslation|setLocalJointTranslation} and similar + * to each joint's parent. + *

Joint translations can be set by {@link Entities.setLocalJointTranslation|setLocalJointTranslation} and similar * functions, or by setting the value of this property. If you set a joint translation using this property you also need to - * set the corresponding jointTranslationsSet value to true. - * @property {boolean[]} jointTranslationsSet=[] - true values for joints that have had translations applied, + * set the corresponding jointTranslationsSet value to true.

+ * @property {boolean[]} jointTranslationsSet=[]] - true values for joints that have had translations applied, * false otherwise; [] if none are applied or the model hasn't loaded. The array indexes are per * {@link Entities.getJointIndex|getJointIndex}. * @property {boolean} relayParentJoints=false - If true and the entity is parented to an avatar, then the @@ -990,98 +1011,103 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { */ /**jsdoc - * The "ParticleEffect" {@link Entities.EntityType|EntityType} displays a particle system that can be used to + * The "ParticleEffect" {@link Entities.EntityType|EntityType} displays a particle system that can be used to * simulate things such as fire, smoke, snow, magic spells, etc. The particles emanate from an ellipsoid or part thereof. * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * * @typedef {object} Entities.EntityProperties-ParticleEffect - - * @property {boolean} isEmitting=true - If true then particles are emitted. + * @property {boolean} isEmitting=true - true if particles are being emitted, false if they aren't. * @property {number} maxParticles=1000 - The maximum number of particles to render at one time. Older particles are deleted if * necessary when new ones are created. * @property {number} lifespan=3s - How long, in seconds, each particle lives. * @property {number} emitRate=15 - The number of particles per second to emit. * @property {number} emitSpeed=5 - The speed, in m/s, that each particle is emitted at. - * @property {number} speedSpread=1 - The spread in speeds at which particles are emitted at. If emitSpeed == 5 - * and speedSpread == 1, particles will be emitted with speeds in the range 4m/s – 6m/s. + * @property {number} speedSpread=1 - The spread in speeds at which particles are emitted at. For example, if + * emitSpeed == 5 and speedSpread == 1, particles will be emitted with speeds in the range + * 4 – 6m/s. * @property {Vec3} emitAcceleration=0,-9.8,0 - The acceleration that is applied to each particle during its lifetime. The * default is Earth's gravity value. - * @property {Vec3} accelerationSpread=0,0,0 - The spread in accelerations that each particle is given. If + * @property {Vec3} accelerationSpread=0,0,0 - The spread in accelerations that each particle is given. For example, if * emitAccelerations == {x: 0, y: -9.8, z: 0} and accelerationSpread == * {x: 0, y: 1, z: 0}, each particle will have an acceleration in the range {x: 0, y: -10.8, z: 0} * – {x: 0, y: -8.8, z: 0}. * @property {Vec3} dimensions - The dimensions of the particle effect, i.e., a bounding box containing all the particles - * during their lifetimes, assuming that emitterShouldTrail is false. Read-only. + * during their lifetimes, assuming that emitterShouldTrail == false. Read-only. * @property {boolean} emitterShouldTrail=false - If true then particles are "left behind" as the emitter moves, - * otherwise they stay with the entity's dimensions. + * otherwise they stay within the entity's dimensions. * * @property {Quat} emitOrientation=-0.707,0,0,0.707 - The orientation of particle emission relative to the entity's axes. By * default, particles emit along the entity's local z-axis, and azimuthStart and azimuthFinish * are relative to the entity's local x-axis. The default value is a rotation of -90 degrees about the local x-axis, i.e., * the particles emit vertically. - * @property {Vec3} emitDimensions=0,0,0 - The dimensions of the shape from which particles are emitted. The shape is specified with - * shapeType. + * + * @property {ShapeType} shapeType="ellipsoid" - The shape from which particles are emitted. + * @property {string} compoundShapeURL="" - The model file to use for the compound shape if shapeType == + * "compound". + * @property {Vec3} emitDimensions=0,0,0 - The dimensions of the shape from which particles are emitted. * @property {number} emitRadiusStart=1 - The starting radius within the shape at which particles start being emitted; * range 0.0 – 1.0 for the center to the surface, respectively. * Particles are emitted from the portion of the shape that lies between emitRadiusStart and the * shape's surface. * @property {number} polarStart=0 - The angle in radians from the entity's local z-axis at which particles start being emitted * within the shape; range 0 – Math.PI. Particles are emitted from the portion of the - * shape that lies between polarStart and polarFinish. Only used if shapeType is - * ellipsoid or sphere. + * shape that lies between polarStart and polarFinish. Only used if shapeType is + * "ellipsoid" or "sphere". * @property {number} polarFinish=0 - The angle in radians from the entity's local z-axis at which particles stop being emitted * within the shape; range 0 – Math.PI. Particles are emitted from the portion of the - * shape that lies between polarStart and polarFinish. Only used if shapeType is - * ellipsoid or sphere. + * shape that lies between polarStart and polarFinish. Only used if shapeType is + * "ellipsoid" or "sphere". * @property {number} azimuthStart=-Math.PI - The angle in radians from the entity's local x-axis about the entity's local * z-axis at which particles start being emitted; range -Math.PI – Math.PI. Particles are - * emitted from the portion of the shape that lies between azimuthStart and azimuthFinish. - * Only used if shapeType is ellipsoid, sphere, or circle. + * emitted from the portion of the shape that lies between azimuthStart and azimuthFinish. + * Only used if shapeType is "ellipsoid", "sphere", or "circle". * @property {number} azimuthFinish=Math.PI - The angle in radians from the entity's local x-axis about the entity's local * z-axis at which particles stop being emitted; range -Math.PI – Math.PI. Particles are - * emitted from the portion of the shape that lies between azimuthStart and azimuthFinish. - * Only used if shapeType is ellipsoid, sphere, or circle.. + * emitted from the portion of the shape that lies between azimuthStart and azimuthFinish. + * Only used if shapeType is "ellipsoid", "sphere", or "circle". * * @property {string} textures="" - The URL of a JPG or PNG image file to display for each particle. If you want transparency, * use PNG format. * @property {number} particleRadius=0.025 - The radius of each particle at the middle of its life. - * @property {number} radiusStart=NaN - The radius of each particle at the start of its life. If NaN, the + * @property {number} radiusStart=null - The radius of each particle at the start of its life. If null, the * particleRadius value is used. - * @property {number} radiusFinish=NaN - The radius of each particle at the end of its life. If NaN, the + * @property {number} radiusFinish=null - The radius of each particle at the end of its life. If null, the * particleRadius value is used. - * @property {number} radiusSpread=0 - The spread in radius that each particle is given. If particleRadius == 0.5 - * and radiusSpread == 0.25, each particle will have a radius in the range 0.25 – - * 0.75. + * @property {number} radiusSpread=0 - The spread in radius that each particle is given. For example, if + * particleRadius == 0.5 and radiusSpread == 0.25, each particle will have a radius in the range + * 0.25 – 0.75. * @property {Color} color=255,255,255 - The color of each particle at the middle of its life. - * @property {ColorFloat} colorStart={} - The color of each particle at the start of its life. If any of the component values are - * undefined, the color value is used. - * @property {ColorFloat} colorFinish={} - The color of each particle at the end of its life. If any of the component values are - * undefined, the color value is used. - * @property {Color} colorSpread=0,0,0 - The spread in color that each particle is given. If + * @property {ColorFloat} colorStart=null,null,null - The color of each particle at the start of its life. If any of the + * component values are undefined, the color value is used. + * @property {ColorFloat} colorFinish=null,null,null - The color of each particle at the end of its life. If any of the + * component values are undefined, the color value is used. + * @property {Color} colorSpread=0,0,0 - The spread in color that each particle is given. For example, if * color == {red: 100, green: 100, blue: 100} and colorSpread == * {red: 10, green: 25, blue: 50}, each particle will have a color in the range * {red: 90, green: 75, blue: 50} – {red: 110, green: 125, blue: 150}. - * @property {number} alpha=1 - The alpha of each particle at the middle of its life. - * @property {number} alphaStart=NaN - The alpha of each particle at the start of its life. If NaN, the + * @property {number} alpha=1 - The opacity of each particle at the middle of its life. + * @property {number} alphaStart=null - The opacity of each particle at the start of its life. If null, the * alpha value is used. - * @property {number} alphaFinish=NaN - The alpha of each particle at the end of its life. If NaN, the + * @property {number} alphaFinish=null - The opacity of each particle at the end of its life. If null, the * alpha value is used. - * @property {number} alphaSpread=0 - The spread in alpha that each particle is given. If alpha == 0.5 - * and alphaSpread == 0.25, each particle will have an alpha in the range 0.25 – - * 0.75. - * @property {number} particleSpin=0 - The spin of each particle at the middle of its life. In the range -2*PI – 2*PI. - * @property {number} spinStart=NaN - The spin of each particle at the start of its life. In the range -2*PI – 2*PI. - * If NaN, the particleSpin value is used. - * @property {number} spinFinish=NaN - The spin of each particle at the end of its life. In the range -2*PI – 2*PI. - * If NaN, the particleSpin value is used. - * @property {number} spinSpread=0 - The spread in spin that each particle is given. In the range 0 – 2*PI. If particleSpin == PI - * and spinSpread == PI/2, each particle will have a spin in the range PI/2 – 3*PI/2. - * @property {boolean} rotateWithEntity=false - Whether or not the particles' spin will rotate with the entity. If false, when particleSpin == 0, the particles will point - * up in the world. If true, they will point towards the entity's up vector, based on its orientation. - * @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated. - * - * @property {ShapeType} shapeType="ellipsoid" - The shape of the collision hull used if collisions are enabled. - * @property {string} compoundShapeURL="" - The model file to use for the compound shape if shapeType is - * "compound". + * @property {number} alphaSpread=0 - The spread in alpha that each particle is given. For example, if + * alpha == 0.5 and alphaSpread == 0.25, each particle will have an alpha in the range + * 0.25 – 0.75. + * @property {Entities.Pulse} pulse - Color and alpha pulse. + *

Deprecated: This property is deprecated and will be removed.

+ * @property {number} particleSpin=0 - The rotation of each particle at the middle of its life, range -2 * Math.PI + * – 2 * Math.PI radians. + * @property {number} spinStart=null - The rotation of each particle at the start of its life, range -2 * Math.PI + * – 2 * Math.PI radians. If null, the particleSpin value is used. + * @property {number} spinFinish=null - The rotation of each particle at the end of its life, range -2 * Math.PI + * – 2 * Math.PI radians. If null, the particleSpin value is used. + * @property {number} spinSpread=0 - The spread in spin that each particle is given, range 0 – + * 2 * Math.PI radians. For example, if particleSpin == Math.PI and + * spinSpread == Math.PI / 2, each particle will have a rotation in the range Math.PI / 2 – + * 3 * Math.PI / 2. + * @property {boolean} rotateWithEntity=false - true to make the particles' rotations relative to the entity's + * instantaneous rotation, false to make them relative to world coordinates. If true with + * particleSpin == 0, the particles keep oriented per the entity's orientation. * * @example Create a ball of green smoke. * particles = Entities.addEntity({ @@ -1102,27 +1128,30 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { */ /**jsdoc - * The "PolyLine" {@link Entities.EntityType|EntityType} draws textured, straight lines between a sequence of - * points. - * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * The "PolyLine" {@link Entities.EntityType|EntityType} draws textured, straight lines between a sequence of + * points. It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * * @typedef {object} Entities.EntityProperties-PolyLine - * @property {Vec3} dimensions=1,1,1 - The dimensions of the entity, i.e., the size of the bounding box that contains the - * lines drawn. - * @property {Vec3[]} linePoints=[] - The sequence of points to draw lines between. The values are relative to the entity's - * position. A maximum of 70 points can be specified. Must be specified in order for the entity to render. - * @property {Vec3[]} normals=[] - The normal vectors for the line's surface at the linePoints. The values are + * @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity, i.e., the size of the bounding box that contains the + * lines drawn. Read-only. + * @property {Vec3[]} linePoints=[]] - The sequence of points to draw lines between. The values are relative to the entity's + * position. A maximum of 70 points can be specified. + * @property {Vec3[]} normals=[]] - The normal vectors for the line's surface at the linePoints. The values are * relative to the entity's orientation. Must be specified in order for the entity to render. - * @property {number[]} strokeWidths=[] - The widths, in m, of the line at the linePoints. Must be specified in + * @property {number[]} strokeWidths=[]] - The widths, in m, of the line at the linePoints. Must be specified in * order for the entity to render. - * @property {Vec3[]} strokeColors=[] - The base colors of each point, which are multiplied with the color of the texture, going from 0-1. - * If strokeColors.length < the number of points, color is used for the remaining points. - * @property {Color} color=255,255,255 - Used as the color for each point if strokeColors is too short. + * @property {Vec3[]} strokeColors=[]] - The base colors of each point, with values in the range 0.0,0.0,0.0 + * — 1.0,1.0,1.0. These colors are multiplied with the color of the texture. If there are more line + * points than stroke colors, the color property value is used for the remaining points. + *

Warning: The ordinate values are in the range 0.0 — 1.0.

+ * @property {Color} color=255,255,255 - Used as the color for each point if strokeColors doesn't have a value for + * the point. * @property {string} textures="" - The URL of a JPG or PNG texture to use for the lines. If you want transparency, use PNG * format. * @property {boolean} isUVModeStretch=true - If true, the texture is stretched to fill the whole line, otherwise * the texture repeats along the line. - * @property {bool} glow=false - If true, the alpha of the strokes will drop off farther from the center. - * @property {bool} faceCamera=false - If true, each line segment will rotate to face the camera. + * @property {boolean} glow=false - If true, the opacity of the strokes drops off away from the line center. + * @property {boolean} faceCamera=false - If true, each line segment rotates to face the camera. * @example Draw a textured "V". * var entity = Entities.addEntity({ * type: "PolyLine", @@ -1147,12 +1176,13 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { */ /**jsdoc - * The "PolyVox" {@link Entities.EntityType|EntityType} displays a set of textured voxels. + * The "PolyVox" {@link Entities.EntityType|EntityType} displays a set of textured voxels. * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. * If you have two or more neighboring PolyVox entities of the same size abutting each other, you can display them as joined by - * configuring their voxelSurfaceStyle and neighbor ID properties.
- * PolyVox entities uses a library from Volumes of Fun. Their - * library documentation may be useful to read. + * configuring their voxelSurfaceStyle and various neighbor ID properties. + *

PolyVox entities uses a library from Volumes of Fun. Their + * library documentation may be useful to read.

+ * * @typedef {object} Entities.EntityProperties-PolyVox * @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. * @property {Vec3} voxelVolumeSize=32,32,32 - Integer number of voxels along each axis of the entity, in the range @@ -1203,12 +1233,14 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { /**jsdoc * The "Shape" {@link Entities.EntityType|EntityType} displays an entity of a specified shape. * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * * @typedef {object} Entities.EntityProperties-Shape * @property {Entities.Shape} shape="Sphere" - The shape of the entity. * @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. * @property {Color} color=255,255,255 - The color of the entity. - * @property {number} alpha=1 - The alpha of the shape. - * @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated. + * @property {number} alpha=1 - The opacity of the entity, range 0.0 – 1.0. + * @property {Entities.Pulse} pulse - Color and alpha pulse. + *

Deprecated: This property is deprecated and will be removed.

* @example Create a cylinder. * var shape = Entities.addEntity({ * type: "Shape", @@ -1225,30 +1257,39 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { * when the entity is created. If its shape property value is subsequently changed then the entity's * type will be reported as "Box" if the shape is set to "Cube", * otherwise it will be reported as "Shape". + * * @typedef {object} Entities.EntityProperties-Sphere + * @see {@link Entities.EntityProperties-Shape|EntityProperties-Shape} */ /**jsdoc * The "Text" {@link Entities.EntityType|EntityType} displays a 2D rectangle of text in the domain. * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * * @typedef {object} Entities.EntityProperties-Text * @property {Vec3} dimensions=0.1,0.1,0.01 - The dimensions of the entity. * @property {string} text="" - The text to display on the face of the entity. Text wraps if necessary to fit. New lines can be * created using \n. Overflowing lines are not displayed. * @property {number} lineHeight=0.1 - The height of each line of text (thus determining the font size). * @property {Color} textColor=255,255,255 - The color of the text. - * @property {number} textAlpha=1.0 - The text alpha. + * @property {number} textAlpha=1.0 - The opacity of the text. * @property {Color} backgroundColor=0,0,0 - The color of the background rectangle. - * @property {number} backgroundAlpha=1.0 - The background alpha. - * @property {BillboardMode} billboardMode="none" - If "none", the entity is not billboarded. If "yaw", the entity will be - * oriented to follow your camera around the y-axis. If "full" the entity will be oriented to face your camera. The following deprecated - * behavior is also supported: you can also set "faceCamera" to true to set billboardMode to "yaw", and you can set - * "isFacingAvatar" to true to set billboardMode to "full". Setting either to false sets the mode to "none" + * @property {number} backgroundAlpha=1.0 - The opacity of the background. + * @property {Entities.Pulse} pulse - Color and alpha pulse. + *

Deprecated: This property is deprecated and will be removed.

* @property {number} leftMargin=0.0 - The left margin, in meters. * @property {number} rightMargin=0.0 - The right margin, in meters. * @property {number} topMargin=0.0 - The top margin, in meters. * @property {number} bottomMargin=0.0 - The bottom margin, in meters. - * @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated. + * @property {BillboardMode} billboardMode="none" - Whether the entity is billboarded to face the camera. + * @property {boolean} faceCamera - true if billboardMode is "yaw", otherwise + * false. Setting this property to false sets the billboardMode to + * "none". + *

Deprecated: This property is deprecated and will be removed.

+ * @property {boolean} isFacingAvatar - true if billboardMode is "full", otherwise + * false. Setting this property to false sets the billboardMode to + * "none". + *

Deprecated: This property is deprecated and will be removed.

* @example Create a text entity. * var text = Entities.addEntity({ * type: "Text", @@ -1262,28 +1303,36 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { */ /**jsdoc - * The "Web" {@link Entities.EntityType|EntityType} displays a browsable Web page. Each user views their own copy - * of the Web page: if one user navigates to another page on the entity, other users do not see the change; if a video is being - * played, users don't see it in sync. - * The entity has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * The "Web" {@link Entities.EntityType|EntityType} displays a browsable web page. Each user views their own copy + * of the web page: if one user navigates to another page on the entity, other users do not see the change; if a video is being + * played, users don't see it in sync. It has properties in addition to the common + * {@link Entities.EntityProperties|EntityProperties}. + * * @typedef {object} Entities.EntityProperties-Web * @property {Vec3} dimensions=0.1,0.1,0.01 - The dimensions of the entity. - * @property {Color} color=255,255,255 - The color of the web surface. - * @property {number} alpha=1 - The alpha of the web surface. - * @property {BillboardMode} billboardMode="none" - If "none", the entity is not billboarded. If "yaw", the entity will be - * oriented to follow your camera around the y-axis. If "full" the entity will be oriented to face your camera. The following deprecated - * behavior is also supported: you can also set "faceCamera" to true to set billboardMode to "yaw", and you can set - * "isFacingAvatar" to true to set billboardMode to "full". Setting either to false sets the mode to "none" - * @property {string} sourceUrl="" - The URL of the Web page to display. This value does not change as you or others navigate + * @property {string} sourceUrl="" - The URL of the web page to display. This value does not change as you or others navigate * on the Web entity. + * @property {Color} color=255,255,255 - The color of the web surface. + * @property {number} alpha=1 - The opacity of the web surface. + * @property {Entities.Pulse} pulse - Color and alpha pulse. + *

Deprecated: This property is deprecated and will be removed.

+ * @property {BillboardMode} billboardMode="none" - Whether the entity is billboarded to face the camera. + * @property {boolean} faceCamera - true if billboardMode is "yaw", otherwise + * false. Setting this property to false sets the billboardMode to + * "none". + *

Deprecated: This property is deprecated and will be removed.

+ * @property {boolean} isFacingAvatar - true if billboardMode is "full", otherwise + * false. Setting this property to false sets the billboardMode to + * "none". + *

Deprecated: This property is deprecated and will be removed.

* @property {number} dpi=30 - The resolution to display the page at, in dots per inch. If you convert this to dots per meter * (multiply by 1 / 0.0254 = 39.3701) then multiply dimensions.x and dimensions.y by that value * you get the resolution in pixels. - * @property {string} scriptURL="" - The URL of a JavaScript file to inject into the Web page. - * @property {number} maxFPS=10 - The maximum update rate for the Web content, in frames/second. + * @property {string} scriptURL="" - The URL of a JavaScript file to inject into the web page. + * @property {number} maxFPS=10 - The maximum update rate for the web content, in frames/second. * @property {WebInputMode} inputMode="touch" - The user input mode to use. - * @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated. - * @property {boolean} showKeyboardFocusHighlight - Whether or not to show the keyboard focus highlight when this entity has focus. + * @property {boolean} showKeyboardFocusHighlight=true - true to highlight the entity when it has keyboard focus, + * false to not display the highlight. * @example Create a Web entity displaying at 1920 x 1080 resolution. * var METERS_TO_INCHES = 39.3701; * var entity = Entities.addEntity({ @@ -1303,74 +1352,54 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { /**jsdoc * The "Zone" {@link Entities.EntityType|EntityType} is a volume of lighting effects and avatar permissions. - * Avatar interaction events such as {@link Entities.enterEntity} are also often used with a Zone entity. - * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. - * @typedef {object} Entities.EntityProperties-Zone - * @property {Vec3} dimensions=0.1,0.1,0.1 - The size of the volume in which the zone's lighting effects and avatar permissions - * have effect. + * Avatar interaction events such as {@link Entities.enterEntity} are also often used with a Zone entity. It has properties in + * addition to the common {@link Entities.EntityProperties|EntityProperties}. * - * @property {ShapeType} shapeType="box" - The shape of the volume in which the zone's lighting effects and avatar + * @typedef {object} Entities.EntityProperties-Zone + * @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the volume in which the zone's lighting effects and avatar + * permissions have effect. + * + * @property {ShapeType} shapeType="box" - The shape of the volume in which the zone's lighting effects and avatar * permissions have effect. Reverts to the default value if set to "none", or set to "compound" * and compoundShapeURL is "". * @property {string} compoundShapeURL="" - The model file to use for the compound shape if shapeType is * "compound". * - * @property {string} keyLightMode="inherit" - Configures the key light in the zone. Possible values:
- * "inherit": The key light from any enclosing zone continues into this zone.
- * "disabled": The key light from any enclosing zone and the key light of this zone are disabled in this - * zone.
- * "enabled": The key light properties of this zone are enabled, overriding the key light of from any - * enclosing zone. + * @property {Entities.ComponentMode} keyLightMode="inherit" - Configures the key light in the zone. * @property {Entities.KeyLight} keyLight - The key light properties of the zone. * - * @property {string} ambientLightMode="inherit" - Configures the ambient light in the zone. Possible values:
- * "inherit": The ambient light from any enclosing zone continues into this zone.
- * "disabled": The ambient light from any enclosing zone and the ambient light of this zone are disabled in - * this zone.
- * "enabled": The ambient light properties of this zone are enabled, overriding the ambient light from any - * enclosing zone. + * @property {Entities.ComponentMode} ambientLightMode="inherit" - Configures the ambient light in the zone. * @property {Entities.AmbientLight} ambientLight - The ambient light properties of the zone. * - * @property {string} skyboxMode="inherit" - Configures the skybox displayed in the zone. Possible values:
- * "inherit": The skybox from any enclosing zone is dislayed in this zone.
- * "disabled": The skybox from any enclosing zone and the skybox of this zone are disabled in this zone.
- * "enabled": The skybox properties of this zone are enabled, overriding the skybox from any enclosing zone. + * @property {Entities.ComponentMode} skyboxMode="inherit" - Configures the skybox displayed in the zone. * @property {Entities.Skybox} skybox - The skybox properties of the zone. * - * @property {string} hazeMode="inherit" - Configures the haze in the zone. Possible values:
- * "inherit": The haze from any enclosing zone continues into this zone.
- * "disabled": The haze from any enclosing zone and the haze of this zone are disabled in this zone.
- * "enabled": The haze properties of this zone are enabled, overriding the haze from any enclosing zone. + * @property {Entities.ComponentMode} hazeMode="inherit" - Configures the haze in the zone. * @property {Entities.Haze} haze - The haze properties of the zone. * - * @property {string} bloomMode="inherit" - Configures the bloom in the zone. Possible values:
- * "inherit": The bloom from any enclosing zone continues into this zone.
- * "disabled": The bloom from any enclosing zone and the bloom of this zone are disabled in this zone.
- * "enabled": The bloom properties of this zone are enabled, overriding the bloom from any enclosing zone. + * @property {Entities.ComponentMode} bloomMode="inherit" - Configures the bloom in the zone. * @property {Entities.Bloom} bloom - The bloom properties of the zone. * - * @property {boolean} flyingAllowed=true - If true then visitors can fly in the zone; otherwise they cannot. - * Only works on domain entities. + * @property {boolean} flyingAllowed=true - If true then visitors can fly in the zone; otherwise, they cannot. + * Only works for domain entities. * @property {boolean} ghostingAllowed=true - If true then visitors with avatar collisions turned off will not - * collide with content in the zone; otherwise visitors will always collide with content in the zone. Only works on domain entities. + * collide with content in the zone; otherwise, visitors will always collide with content in the zone. Only works for domain + * entities. * @property {string} filterURL="" - The URL of a JavaScript file that filters changes to properties of entities within the * zone. It is periodically executed for each entity in the zone. It can, for example, be used to not allow changes to - * certain properties.
- * - * @property {string} avatarPriority="inherit" - Configures the update priority of contained avatars to other clients.
- * "inherit": Priority from enclosing zones is unchanged.
- * "crowd": Priority in this zone is the normal priority.
- * "hero": Avatars in this zone will have an increased update priority + * certain properties: * 
- *
  * function filter(properties) {
- *     // Test and edit properties object values,
+ *     // Check and edit properties object values,
  *     // e.g., properties.modelURL, as required.
  *     return properties;
  * }
  *
* + * @property {Entities.AvatarPriorityMode} avatarPriority="inherit" - Configures the priority of updates from avatars in the + * zone to other clients. + * * @example Create a zone that casts a red key light along the x-axis. * var zone = Entities.addEntity({ * type: "Zone", @@ -1388,19 +1417,29 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { /**jsdoc * The "Image" {@link Entities.EntityType|EntityType} displays an image on a 2D rectangle in the domain. * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * * @typedef {object} Entities.EntityProperties-Image + * @property {Vec3} dimensions=0.1,0.1,0.01 - The dimensions of the entity. * @property {string} imageURL="" - The URL of the image to use. - * @property {boolean} emissive=false - Whether or not the image should be emissive (unlit). - * @property {boolean} keepAspectRatio=true - Whether or not the image should maintain its aspect ratio. - * @property {BillboardMode} billboardMode="none" - If "none", the entity is not billboarded. If "yaw", the entity will be - * oriented to follow your camera around the y-axis. If "full" the entity will be oriented to face your camera. The following deprecated - * behavior is also supported: you can also set "faceCamera" to true to set billboardMode to "yaw", and you can set - * "isFacingAvatar" to true to set billboardMode to "full". Setting either to false sets the mode to "none" - * @property {Rect} subImage={ x: 0, y: 0, width: -1, height: -1 } - The portion of the image to display. If width or height are -1, defaults to - * the full image in that dimension. + * @property {boolean} emissive=false - true fi the the image should be emissive (unlit), false if it + * shouldn't. + * @property {boolean} keepAspectRatio=true - true if the image should maintain its aspect ratio, + * false if it shouldn't. + * @property {Rect} subImage=0,0,0,0 - The portion of the image to display. If width or height are 0, it defaults + * to the full image in that dimension. * @property {Color} color=255,255,255 - The color of the image. - * @property {number} alpha=1 - The alpha of the image. - * @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated. + * @property {number} alpha=1 - The opacity of the image. + * @property {Entities.Pulse} pulse - Color and alpha pulse. + *

Deprecated: This property is deprecated and will be removed.

+ * @property {BillboardMode} billboardMode="none" - Whether the entity is billboarded to face the camera. + * @property {boolean} faceCamera - true if billboardMode is "yaw", otherwise + * false. Setting this property to false sets the billboardMode to + * "none". + *

Deprecated: This property is deprecated and will be removed.

+ * @property {boolean} isFacingAvatar - true if billboardMode is "full", otherwise + * false. Setting this property to false sets the billboardMode to + * "none". + *

Deprecated: This property is deprecated and will be removed.

* @example Create a image entity. * var image = Entities.addEntity({ * type: "Image", @@ -1415,16 +1454,19 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { /**jsdoc * The "Grid" {@link Entities.EntityType|EntityType} displays a grid on a 2D plane. * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * * @typedef {object} Entities.EntityProperties-Grid + * @property {Vec3} dimensions - 0.1,0.1,0.01 - The dimensions of the entity. * @property {Color} color=255,255,255 - The color of the grid. - * @property {number} alpha=1 - The alpha of the grid. + * @property {number} alpha=1 - The opacity of the grid. + * @property {Entities.Pulse} pulse - Color and alpha pulse. + *

Deprecated: This property is deprecated and will be removed.

* @property {boolean} followCamera=true - If true, the grid is always visible even as the camera moves to another * position. * @property {number} majorGridEvery=5 - Integer number of minorGridEvery intervals at which to draw a thick grid * line. Minimum value = 1. * @property {number} minorGridEvery=1 - Real number of meters at which to draw thin grid lines. Minimum value = * 0.001. - * @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated. * @example Create a grid entity. * var grid = Entities.addEntity({ * type: "Grid", @@ -1440,8 +1482,10 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { /**jsdoc * The "Gizmo" {@link Entities.EntityType|EntityType} displays an entity that could be used as UI. * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * * @typedef {object} Entities.EntityProperties-Gizmo - * @property {GizmoType} gizmoType="ring" - The gizmo type of the entity. + * @property {Vec3} dimensions=0.1,0.001,0.1 - The dimensions of the entity. + * @property {Entities.GizmoType} gizmoType="ring" - The gizmo type of the entity. * @property {Entities.RingGizmo} ring - The ring gizmo properties. */ @@ -1850,7 +1894,7 @@ QScriptValue EntityItemProperties::copyToScriptValue(QScriptEngine* engine, bool * @typedef {object} Entities.RenderInfo * @property {number} verticesCount - The number of vertices in the entity. * @property {number} texturesCount - The number of textures in the entity. - * @property {number} textureSize - The total size of the textures in the entity, in bytes. + * @property {number} texturesSize - The total size of the textures in the entity, in bytes. * @property {boolean} hasTransparent - Is true if any of the textures has transparency. * @property {number} drawCalls - The number of draw calls required to render the entity. */ 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 Entities API provides facilities to create and interact with entities. Entities are 2D or 3D objects + * displayed in-world. Depending on their {@link Entities.EntityHostType|EntityHostType}, they may persist in the domain as + * "domain" entities, travel to different domains with a user as "avatar" entities, or be visible only to an individual user as + * "local" entities (a.k.a. "overlays"). + * + *

Note: For Interface scripts, the entities available to scripts are those that Interface has displayed and so knows + * about.

* * @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 null; set to null 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 null; set to null or {@link Uuid(0)|Uuid.NULL} to clear + * keyboard focus. */ /// handles scripting of Entity commands from JS passed to assigned clients class EntityScriptingInterface : public OctreeScriptingInterface, public Dependency { @@ -245,35 +249,39 @@ public slots: Q_INVOKABLE bool canGetAndSetPrivateUserData(); /**jsdoc - *

How an entity is sent over the wire.

+ *

How an entity is hosted and sent to others for display.

* * * * * - * - * - * + * + * + * * *
ValueDescription
domainDomain entities are sent over the entity server to everyone else
avatarAvatar entities are sent over the avatar entity and are associated with one avatar
localLocal entities are not sent over the wire and will only render for you, locally
"domain"Domain entities are stored on the domain, are visible to everyone, and are + * sent to everyone by the entity server.
"avatar"Avatar entities are stored on an Interface client, are visible to everyone, + * and are sent to everyone by the avatar mixer. They follow the client to each domain visited, displaying at the + * same domain coordinates unless parented to the client's avatar.
"local"Local entities are ephemeral — they aren't stored anywhere — and + * are visible only to the client. They follow the client to each domain visited, displaying at the same domain + * coordinates unless parented to the client's avatar. Additionally, local entities are collisionless.
- * @typedef {string} EntityHostType + * @typedef {string} Entities.EntityHostType */ /**jsdoc - * Add a new entity with specified properties. + * Adds a new domain, avatar, or local entity. * @function Entities.addEntity * @param {Entities.EntityProperties} properties - The properties of the entity to create. - * @param {EntityHostType} [entityHostType="domain"] - If "avatar" the entity is created as an avatar entity. An avatar entity - * follows you to each domain you visit, rendering at the same world coordinates unless it's parented to your avatar. - * If "local", the entity is created as a local entity, which will only render for you and isn't sent over the wire. - * Otherwise it is created as a normal entity and sent over the entity server. + * @param {Entities.EntityHostType} [entityHostType="domain"] - The type of entity to create. + * @returns {Uuid} The ID of the entity if successfully created, otherwise {@link Uuid(0)|Uuid.NULL}. - * @example Create a box entity in front of your avatar. + * @example Create a box domain entity in front of your avatar. * var entityID = Entities.addEntity({ * type: "Box", * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })), * rotation: MyAvatar.orientation, - * dimensions: { x: 0.5, y: 0.5, z: 0.5 } + * dimensions: { x: 0.5, y: 0.5, z: 0.5 }, + * lifetime: 300 // Delete after 5 minutes. * }); * print("Entity created: " + entityID); */ @@ -290,10 +298,13 @@ public slots: } /**jsdoc - * Add a new entity with specified properties. + * Adds a new avatar entity ({@link Entities.EntityProperties|entityHostType} property is + * "avatar") or domain entity ({@link Entities.EntityProperties|entityHostType} property is + * "domain"). * @function Entities.addEntity * @param {Entities.EntityProperties} properties - The properties of the entity to create. - * @param {boolean} [avatarEntity=false] - Whether to create an avatar entity or a domain entity + * @param {boolean} [avatarEntity=false] - true to create an avatar entity, false to create a + * domain entity. * @returns {Uuid} The ID of the entity if successfully created, otherwise {@link Uuid(0)|Uuid.NULL}. */ Q_INVOKABLE QUuid addEntity(const EntityItemProperties& properties, bool avatarEntity = false) { @@ -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 cloneable property set to true. The clone has a modified name, other - * properties set per its clone related-properties, and its clone-related properties are set to defaults. + * Creates a clone of an entity. The clone has a modified name property, other properties set per the original + * entity's clone-related {@link Entities.EntityProperties|properties} (e.g., cloneLifetime), and + * clone-related properties set to defaults. + *

Domain entities must have their cloneable property value be true in order to be cloned. A + * domain entity can be cloned by a client that doesn't have rez permissions in the domain.

+ *

Avatar entities must have their cloneable and cloneAvatarEntity property values be + * true in order to be cloned.

* @function Entities.cloneEntity * @param {Uuid} entityID - The ID of the entity to clone. * @returns {Uuid} The ID of the new entity if successfully cloned, otherwise {@link Uuid(0)|Uuid.NULL}. @@ -317,18 +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 "keyLight" property), use the property and subproperty names in dot notation (e.g., + * "keyLight.color"). * @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 Report the color of a new box entity. * var entityID = Entities.addEntity({ * type: "Box", * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })), * rotation: MyAvatar.orientation, - * dimensions: { x: 0.5, y: 0.5, z: 0.5 } + * dimensions: { x: 0.5, y: 0.5, z: 0.5 }, + * lifetime: 300 // Delete after 5 minutes. * }); * var properties = Entities.getEntityProperties(entityID, ["color"]); * print("Entity color: " + JSON.stringify(properties.color)); @@ -337,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 null. + * @param {Entities.EntityProperties} properties - The new property values. + * @returns {Uuid} The ID of the entity if the edit was successful, otherwise null or {@link Uuid|Uuid.NULL}. * @example Change the color of an entity. * var entityID = Entities.addEntity({ * type: "Box", * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })), * rotation: MyAvatar.orientation, - * dimensions: { x: 0.5, y: 0.5, z: 0.5 } + * dimensions: { x: 0.5, y: 0.5, z: 0.5 }, + * lifetime: 300 // Delete after 5 minutes. * }); * var properties = Entities.getEntityProperties(entityID, ["color"]); * print("Entity color: " + JSON.stringify(properties.color)); @@ -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 Delete an entity a few seconds after creating it. @@ -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 null. */ 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 * null 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: * ValueDescriptionProperties * * - * "Box"A rectangular prism. This is a synonym of "Shape" for the case + * "Shape"A basic entity such as a cube. + * See also, the "Box" and "Sphere" entity types. + * {@link Entities.EntityProperties-Shape|EntityProperties-Shape} + * "Box"A rectangular prism. This is a synonym of "Shape" for the case * where the entity's shape property value is "Cube".
* If an entity is created with its type * set to "Box" it will always be created with a shape property value of @@ -56,9 +59,6 @@ public: * "Sphere". If an entity of type Box or Shape has its shape set * to "Sphere" then its type will be reported as "Sphere". * {@link Entities.EntityProperties-Sphere|EntityProperties-Sphere} - * "Shape"A basic entity such as a cube. - * See also, the "Box" and "Sphere" entity types. - * {@link Entities.EntityProperties-Shape|EntityProperties-Shape} * "Model"A mesh model from an FBX or OBJ file. * {@link Entities.EntityProperties-Model|EntityProperties-Model} * "Text"A pane of text oriented in space. @@ -78,7 +78,7 @@ public: * {@link Entities.EntityProperties-PolyVox|EntityProperties-PolyVox} * "Grid"A grid of lines in a plane. * {@link Entities.EntityProperties-Grid|EntityProperties-Grid} - * "Gizmo"An entity with various UI-related properties. + * "Gizmo"A gizmo intended for UI. * {@link Entities.EntityProperties-Gizmo|EntityProperties-Gizmo} * "Light"A local lighting effect. * {@link Entities.EntityProperties-Light|EntityProperties-Light} 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 true the entity can be grabbed. - * @property {boolean} grabKinematic=true - If true the entity is updated in a kinematic manner. - * If false it will be grabbed using a tractor action. A kinematic grab will make the item appear more - * tightly held, but will cause it to behave poorly when interacting with dynamic entities. - * @property {boolean} grabFollowsController=true - If true the entity will follow the motions of the - * hand-controller even if the avatar's hand can't get to the implied position. This should be true - * for tools, pens, etc and false for things meant to decorate the hand. - * - * @property {boolean} triggerable=false - If true the entity will receive calls to trigger + * @property {boolean} grabbable=true - If true then the entity can be grabbed. + * @property {boolean} grabKinematic=true - If true then the entity will be updated in a kinematic manner when + * grabbed; if false it will be grabbed using a tractor action. A kinematic grab will make the item appear + * more tightly held but will cause it to behave poorly when interacting with dynamic entities. + * @property {boolean} grabFollowsController=true - If true then the entity will follow the motions of the hand + * controller even if the avatar's hand can't get to the implied position. This should be set true for tools, + * pens, etc. and false for things meant to decorate the hand. + * @property {boolean} triggerable=false - If true then the entity will receive calls to trigger * {@link Controller|Controller entity methods}. - * - * @property {boolean} equippable=true - If true the entity can be equipped. + * @property {boolean} equippable=true - If true then the entity can be equipped. * @property {Vec3} equippableLeftPosition=0,0,0 - Positional offset from the left hand, when equipped. * @property {Quat} equippableLeftRotation=0,0,0,1 - Rotational offset from the left hand, when equipped. * @property {Vec3} equippableRightPosition=0,0,0 - Positional offset from the right hand, when equipped. * @property {Quat} equippableRightRotation=0,0,0,1 - Rotational offset from the right hand, when equipped. - * * @property {string} equippableIndicatorURL="" - If non-empty, this model will be used to indicate that an * entity is equippable, rather than the default. - * @property {Vec3} equippableIndicatorScale=1,1,1 - If equippableIndicatorURL is non-empty, this controls the + * @property {Vec3} equippableIndicatorScale=1,1,1 - If equippableIndicatorURL is non-empty, this controls the scale of the displayed indicator. - * @property {Vec3} equippableIndicatorOffset=0,0,0 - If equippableIndicatorURL is non-empty, this controls the + * @property {Vec3} equippableIndicatorOffset=0,0,0 - If equippableIndicatorURL is non-empty, this controls the relative offset of the displayed object from the equippable entity. */ - - class GrabPropertyGroup : public PropertyGroup { public: // EntityItemProperty related helpers diff --git a/libraries/entities/src/HazePropertyGroup.h b/libraries/entities/src/HazePropertyGroup.h index 595dbeaf51..116bfd9687 100644 --- a/libraries/entities/src/HazePropertyGroup.h +++ b/libraries/entities/src/HazePropertyGroup.h @@ -43,7 +43,7 @@ static const float INITIAL_KEY_LIGHT_ALTITUDE{ 200.0f }; // FIXME: Document hazeAttenuationKeyLight, hazeKeyLightRange, and hazeKeyLightAltitude once they're working and are provided // in the Create app's UI. /**jsdoc - * Haze is defined by the following properties. + * Haze is defined by the following properties: * @typedef {object} Entities.Haze * * @property {number} hazeRange=1000 - The horizontal distance at which visibility is reduced to 95%; i.e., 95% of each pixel's @@ -56,7 +56,7 @@ static const float INITIAL_KEY_LIGHT_ALTITUDE{ 200.0f }; * haze color are blended 50/50. * * @property {boolean} hazeAltitudeEffect=false - If true then haze decreases with altitude as defined by the - * entity's local coordinate system; hazeBaseRef and hazeCeiling are used. + * entity's local coordinate system; hazeBaseRef and hazeCeiling are used. * @property {number} hazeBaseRef=0 - The y-axis value in the entity's local coordinate system at which the haze density starts * reducing with altitude. * @property {number} hazeCeiling=200 - The y-axis value in the entity's local coordinate system at which the haze density has @@ -65,9 +65,11 @@ static const float INITIAL_KEY_LIGHT_ALTITUDE{ 200.0f }; * @property {number} hazeBackgroundBlend=0 - The proportion of the skybox image to show through the haze: 0.0 * displays no skybox image; 1.0 displays no haze. * - * @property {boolean} hazeAttenuateKeyLight=false - Currently not supported. - * @property {number} hazeKeyLightRange=1000 - Currently not supported. - * @property {number} hazeKeyLightAltitude=200 - Currently not supported. + * @property {boolean} hazeAttenuateKeyLight=false - If true then the haze attenuates the key light; + * hazeKeyLightRange and hazeKeyLightAltitude are used. + * @property {number} hazeKeyLightRange=1000 - The distance at which the haze attenuates the key light by 95%. + * @property {number} hazeKeyLightAltitude=200 - The altitude at which the haze starts attenuating the key light (i.e., the + * altitude at which the distance starts being calculated). */ class HazePropertyGroup : public PropertyGroup { public: diff --git a/libraries/entities/src/KeyLightPropertyGroup.h b/libraries/entities/src/KeyLightPropertyGroup.h index d7fa75a32e..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 - *

A PolyVoxSurfaceStyle may be one of the following:

+ *

The surface of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity may be one of the following styles:

* * * 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 * min to max, then max to min in one period. - * @property {PulseMode} colorMode="none" - If "in", the color is pulsed in phase with the pulse period; if "out" + * @property {Entities.PulseMode} colorMode="none" - If "in", the color is pulsed in phase with the pulse period; if "out" * the color is pulsed out of phase with the pulse period. - * @property {PulseMode} alphaMode="none" - If "in", the alpha is pulsed in phase with the pulse period; if "out" + * @property {Entities.PulseMode} alphaMode="none" - If "in", the alpha is pulsed in phase with the pulse period; if "out" * the alpha is pulsed out of phase with the pulse period. */ - class PulsePropertyGroup : public PropertyGroup { public: // EntityItemProperty related helpers diff --git a/libraries/entities/src/RingGizmoPropertyGroup.h b/libraries/entities/src/RingGizmoPropertyGroup.h index 42202eb509..1f23152fc7 100644 --- a/libraries/entities/src/RingGizmoPropertyGroup.h +++ b/libraries/entities/src/RingGizmoPropertyGroup.h @@ -25,31 +25,32 @@ class ReadBitstreamToTreeParams; using u8vec3Color = glm::u8vec3; /**jsdoc - * A RingGizmo is defined by the following properties. + * A {@link Entities.EntityProperties-Gizmo|ring Gizmo} entity is defined by the following properties: * @typedef {object} Entities.RingGizmo * - * @property {number} startAngle=0 - The angle at which the ring will start, in degrees. - * @property {number} endAngle=360 - The angle at which the ring will end, in degrees. - * @property {number} innerRadius=0 - The inner radius of the ring as a fraction of the total radius. 0-1. + * @property {number} startAngle=0 - The angle at which the ring starts, in degrees. + * @property {number} endAngle=360 - The angle at which the ring ends, in degrees. + * @property {number} innerRadius=0 - The inner radius of the ring as a fraction of the total radius, range 0.0 + * — 1.0. - * @property {Color} innerStartColor - The color at the inner start point of the ring. - * @property {Color} innerEndColor - The color at the inner end point of the ring. - * @property {Color} outerStartColor - The color at the outer start point of the ring. - * @property {Color} outerEndColor - The color at the outer end point of the ring. - * @property {number} innerStartAlpha=1 - The alpha at the inner start point of the ring. - * @property {number} innerEndAlpha=1 - The alpha at the inner end point of the ring. - * @property {number} outerStartAlpha=1 - The alpha at the outer start point of the ring. - * @property {number} outerEndAlpha=1 - The alpha at the outer end point of the ring. + * @property {Color} innerStartColor=255,255,255 - The color at the inner start point of the ring. + * @property {Color} innerEndColor=255,255,255 - The color at the inner end point of the ring. + * @property {Color} outerStartColor=255,255,255 - The color at the outer start point of the ring. + * @property {Color} outerEndColor=255,255,255 - The color at the outer end point of the ring. + * @property {number} innerStartAlpha=1 - The opacity at the inner start point of the ring. + * @property {number} innerEndAlpha=1 - The opacity at the inner end point of the ring. + * @property {number} outerStartAlpha=1 - The opacity at the outer start point of the ring. + * @property {number} outerEndAlpha=1 - The opacity at the outer end point of the ring. - * @property {boolean} hasTickMarks=false - Whether or not to render tick marks. - * @property {number} majorTickMarksAngle - The angle between major tick marks, in degrees. - * @property {number} minorTickMarksAngle - The angle between minor tick marks, in degrees. - * @property {number} majorTickMarksLength - The length of the major tick marks, as a fraction of the radius. A positive value draws tick marks - * outwards from the inner radius; a negative value draws tick marks inwards from the outer radius. - * @property {number} minorTickMarksLength - The length of the minor tick marks, as a fraction of the radius. A positive value draws tick marks - * outwards from the inner radius; a negative value draws tick marks inwards from the outer radius. - * @property {Color} majorTickMarksColor - The color of the major tick marks. - * @property {Color} minorTickMarksColor - The color of the minor tick marks. + * @property {boolean} hasTickMarks=false - true to render tick marks, otherwise false. + * @property {number} majorTickMarksAngle=0 - The angle between major tick marks, in degrees. + * @property {number} minorTickMarksAngle=0 - The angle between minor tick marks, in degrees. + * @property {number} majorTickMarksLength=0 - The length of the major tick marks as a fraction of the radius. A positive value + * draws tick marks outwards from the inner radius; a negative value draws tick marks inwards from the outer radius. + * @property {number} minorTickMarksLength=0 - The length of the minor tick marks, as a fraction of the radius. A positive + * value draws tick marks outwards from the inner radius; a negative value draws tick marks inwards from the outer radius. + * @property {Color} majorTickMarksColor=255,255,255 - The color of the major tick marks. + * @property {Color} minorTickMarksColor=255,255,255 - The color of the minor tick marks. */ class RingGizmoPropertyGroup : public PropertyGroup { diff --git a/libraries/entities/src/ShapeEntityItem.cpp b/libraries/entities/src/ShapeEntityItem.cpp index 869ae2985f..513daa0b09 100644 --- a/libraries/entities/src/ShapeEntityItem.cpp +++ b/libraries/entities/src/ShapeEntityItem.cpp @@ -22,8 +22,8 @@ namespace entity { /**jsdoc - *

A Shape, Box, or Sphere {@link Entities.EntityType|EntityType} may display as - * one of the following geometrical shapes:

+ *

A "Shape", "Box", or "Sphere" {@link Entities.EntityType|EntityType} may + * display as one of the following geometrical shapes:

*
ValueTypeDescription
* * 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 url is "", otherwise modifies the * color of the cube map image. diff --git a/libraries/material-networking/src/material-networking/MaterialCache.cpp b/libraries/material-networking/src/material-networking/MaterialCache.cpp index 5e86ea506a..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. Currently not used. - * @property {Material|Material[]} materials - The details of the material or materials. + * @property {Entities.Material|Entities.Material[]} materials - The details of the material or materials. */ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMaterials(const QJsonDocument& materialJSON, const QUrl& baseUrl) { ParsedMaterials toReturn; @@ -109,60 +109,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: "hifi_pbr". * @property {string} name="" - A name for the material. Supported by all material models. * @property {Color|RGBS|string} emissive - The emissive color, i.e., the color that the material emits. A {@link Color} value - * is treated as sRGB. A {@link RGBS} value can be either RGB or sRGB. Set to "fallthrough" to fallthrough to - * the material below. "hifi_pbr" model only. - * @property {number|string} opacity=1.0 - The opacity, 0.0 – 1.0. Set to "fallthrough" to fallthrough to - * the material below. "hifi_pbr" model only. - * @property {boolean|string} unlit=false - If true, the material is not lit. Set to "fallthrough" to fallthrough to - * the material below. "hifi_pbr" model only. + * is treated as sRGB. A {@link RGBS} value can be either RGB or sRGB. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {number|string} opacity=1.0 - The opacity, range 0.0 – 1.0. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {boolean|string} unlit=false - If true, the material is not lit, otherwise it is. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. * @property {Color|RGBS|string} albedo - The albedo color. A {@link Color} value is treated as sRGB. A {@link RGBS} value can - * be either RGB or sRGB. Set to "fallthrough" to fallthrough to the material below. Set to "fallthrough" to fallthrough to - * the material below. "hifi_pbr" model only. - * @property {number|string} roughness - The roughness, 0.0 – 1.0. Set to "fallthrough" to fallthrough to - * the material below. "hifi_pbr" model only. - * @property {number|string} metallic - The metallicness, 0.0 – 1.0. Set to "fallthrough" to fallthrough to - * the material below. "hifi_pbr" model only. - * @property {number|string} scattering - The scattering, 0.0 – 1.0. Set to "fallthrough" to fallthrough to - * the material below. "hifi_pbr" model only. - * @property {string} emissiveMap - URL of emissive texture image. Set to "fallthrough" to fallthrough to - * the material below. "hifi_pbr" model only. - * @property {string} albedoMap - URL of albedo texture image. Set to "fallthrough" to fallthrough to - * the material below. "hifi_pbr" model only. - * @property {string} opacityMap - URL of opacity texture image. Set value the same as the albedoMap value for - * transparency. "hifi_pbr" model only. - * @property {string} roughnessMap - URL of roughness texture image. Can use this or glossMap, but not both. Set to "fallthrough" - * to fallthrough to the material below. "hifi_pbr" model only. - * @property {string} glossMap - URL of gloss texture image. Can use this or roughnessMap, but not both. Set to "fallthrough" - * to fallthrough to the material below. "hifi_pbr" model only. - * @property {string} metallicMap - URL of metallic texture image. Can use this or specularMap, but not both. Set to "fallthrough" - * to fallthrough to the material below. "hifi_pbr" model only. - * @property {string} specularMap - URL of specular texture image. Can use this or metallicMap, but not both. Set to "fallthrough" - * to fallthrough to the material below. "hifi_pbr" model only. - * @property {string} normalMap - URL of normal texture image. Can use this or bumpMap, but not both. Set to "fallthrough" - * to fallthrough to the material below. "hifi_pbr" model only. - * @property {string} bumpMap - URL of bump texture image. Can use this or normalMap, but not both. Set to "fallthrough" - * to fallthrough to the material below. "hifi_pbr" model only. - * @property {string} occlusionMap - URL of occlusion texture image. Set to "fallthrough" to fallthrough to the material below. "hifi_pbr" model only. - * @property {string} scatteringMap - URL of scattering texture image. Only used if normalMap or - * bumpMap is specified. Set to "fallthrough" to fallthrough to the material below. "hifi_pbr" model only. - * @property {string} lightMap - URL of light map texture image. Currently not used.. Set to "fallthrough" - * to fallthrough to the material below. "hifi_pbr" model only. - * @property {string} texCoordTransform0 - The transform to use for all of the maps besides occlusionMap and lightMap. Currently unused. Set to - * "fallthrough" to fallthrough to the material below. "hifi_pbr" model only. - * @property {string} texCoordTransform1 - The transform to use for occlusionMap and lightMap. Currently unused. Set to "fallthrough" - * to fallthrough to the material below. "hifi_pbr" model only. - * @property {string} lightmapParams - Parameters for controlling how lightMap is used. Currently unused. Set to "fallthrough" - * to fallthrough to the material below. "hifi_pbr" model only. - * @property {string} materialParams - Parameters for controlling the material projection and repition. Currently unused. Set to "fallthrough" - * to fallthrough to the material below. "hifi_pbr" model only. - * @property {bool} defaultFallthrough=false - If true, all properties will fallthrough to the material below unless they are set. If - * false, they will respect the individual properties' fallthrough state. "hifi_pbr" model only. + * be either RGB or sRGB. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {number|string} roughness - The roughness, range 0.0 – 1.0. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {number|string} metallic - The metallicness, range 0.0 – 1.0. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {number|string} scattering - The scattering, range 0.0 – 1.0. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {string} emissiveMap - The URL of the emissive texture image. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {string} albedoMap - The URL of the albedo texture image. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {string} opacityMap - The URL of the opacity texture image. Set the value the same as the albedoMap + * value for transparency. + * "hifi_pbr" model only. + * @property {string} roughnessMap - The URL of the roughness texture image. You can use this or glossMap, but not + * both. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {string} glossMap - The URL of the gloss texture image. You can use this or roughnessMap, but not + * both. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {string} metallicMap - The URL of the metallic texture image. You can use this or specularMap, but + * not both. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {string} specularMap - The URL of the specular texture image. You can use this or metallicMap, but + * not both. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {string} normalMap - The URL of the normal texture image. You can use this or bumpMap, but not both. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {string} bumpMap - The URL of the bump texture image. You can use this or normalMap, but not both. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {string} occlusionMap - The URL of the occlusion texture image. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {string} scatteringMap - The URL of the scattering texture image. Only used if normalMap or + * bumpMap is specified. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {string} lightMap - The URL of the light map texture image. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {Mat4|string} texCoordTransform0 - The transform to use for all of the maps apart from occlusionMap + * and lightMap. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {Mat4|string} texCoordTransform1 - The transform to use for occlusionMap and lightMap. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {string} lightmapParams - Parameters for controlling how lightMap is used. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + *

Currently not used.

+ * @property {string} materialParams - Parameters for controlling the material projection and repetition. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + *

Currently not used.

+ * @property {boolean} defaultFallthrough=false - If true, all properties fall through to the material below + * unless they are set. If false, they respect their individual fall-through setting. "hifi_pbr" + * model only. */ // Note: See MaterialEntityItem.h for default values used in practice. std::pair> NetworkMaterialResource::parseJSONMaterial(const QJsonObject& materialJSON, const QUrl& baseUrl) { @@ -399,7 +410,7 @@ std::pair> NetworkMaterialResource material->setPropertyDoesFallthrough(graphics::Material::ExtraFlagBit::LIGHTMAP_PARAMS); } } - // TODO: implement lightmapParams + // TODO: implement lightmapParams and update JSDoc } else if (key == "materialParams") { auto value = materialJSON.value(key); if (value.isString()) { @@ -408,7 +419,7 @@ std::pair> NetworkMaterialResource material->setPropertyDoesFallthrough(graphics::Material::ExtraFlagBit::MATERIAL_PARAMS); } } - // TODO: implement materialParams + // TODO: implement materialParams and update JSDoc } else if (key == "defaultFallthrough") { auto value = materialJSON.value(key); if (value.isBool()) { diff --git a/libraries/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 @@ * * - * * *
ValueDimensionsNotes
"none"The entity will not be billboarded.
"yaw"The entity will yaw, but not pitch, to face the camera. Its actual rotation will be * ignored.
"full"The entity will be billboarded to face the camera. Its actual rotation will be + *
"full"The entity will yaw and pitch to face the camera. Its actual rotation will be * ignored.
diff --git a/libraries/shared/src/ComponentMode.cpp b/libraries/shared/src/ComponentMode.cpp index 5b3a42e9ae..42ef820e2a 100644 --- a/libraries/shared/src/ComponentMode.cpp +++ b/libraries/shared/src/ComponentMode.cpp @@ -8,6 +8,22 @@ #include "ComponentMode.h" +/**jsdoc + *

How an effect is applied in a {@link Entities.EntityProperties-Zone|Zone} entity.

+ * + * + * + * + * + * + * + * + * + *
ValueDescription
"inherit"The effect from any enclosing zone continues into this zone.
"disabled"The effect — from any enclosing zone and this zone — is disabled in + * this zone.
"enabled"The effect from this zone is enabled, overriding the effect from any enclosing + * zone.
+ * @typedef {string} Entities.ComponentMode + */ const char* componentModeNames[] = { "inherit", "disabled", @@ -22,6 +38,20 @@ QString ComponentModeHelpers::getNameForComponentMode(ComponentMode mode) { return componentModeNames[(int)mode]; } +/**jsdoc + *

The priority of updates from avatars in a zone to other clients.

+ * + * + * + * + * + * + * + * + * + *
ValueDescription
"inherit"The update priority from any enclosing zone continues into this zone.
"crowd"The update priority in this zone is the normal priority.
"hero"Avatars in this zone have an increased update priority.
+ * @typedef {string} Entities.AvatarPriorityMode + */ const char* avatarPriorityModeNames[] = { "inherit", "crowd", diff --git a/libraries/shared/src/GizmoType.h b/libraries/shared/src/GizmoType.h index fc047b257d..20870158bc 100644 --- a/libraries/shared/src/GizmoType.h +++ b/libraries/shared/src/GizmoType.h @@ -12,16 +12,16 @@ #include "QString" /**jsdoc - *

Controls how the Gizmo behaves and renders

+ *

A {@link Entities.EntityProperties-Gizmo|Gizmo} entity may be one of the following types:

* * * * * - * + * * *
ValueDescription
ringA ring gizmo.
"ring"A ring gizmo.
- * @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 - *

How the geometry of the entity is rendered.

+ *

How the geometry of an entity is rendered.

* * * * * - * - * + * + * * *
ValueDescription
solidThe entity will be drawn as a solid shape.
linesThe entity will be drawn as wireframe.
"solid"The entity is drawn as a solid shape.
"lines"The entity is drawn as wireframe.
- * @typedef {string} PrimitiveMode + * @typedef {string} Entities.PrimitiveMode */ enum class PrimitiveMode { diff --git a/libraries/shared/src/PulseMode.h b/libraries/shared/src/PulseMode.h index 7c823db68c..4e398cbbaa 100644 --- a/libraries/shared/src/PulseMode.h +++ b/libraries/shared/src/PulseMode.h @@ -18,12 +18,12 @@ * ValueDescription * * - * noneNo pulsing. - * inPulse in phase with the pulse period. - * outPulse out of phase with the pulse period. + * "none"No pulsing. + * "in"Pulse in phase with the pulse period. + * "out"Pulse out of phase with the pulse period. * * - * @typedef {string} PulseMode + * @typedef {string} Entities.PulseMode */ enum class PulseMode { diff --git a/libraries/shared/src/RegisteredMetaTypes.h b/libraries/shared/src/RegisteredMetaTypes.h index 2ca7863ec6..5b8aa34fd9 100644 --- a/libraries/shared/src/RegisteredMetaTypes.h +++ b/libraries/shared/src/RegisteredMetaTypes.h @@ -122,43 +122,43 @@ glm::vec3 vec3FromVariant(const QVariant &object, bool& valid); glm::vec3 vec3FromVariant(const QVariant &object); /**jsdoc -* A color vector. See also the {@link Vec3(0)|Vec3} object. -* -* @typedef {object} Color -* @property {number} red - Red component value. Integer in the range 0 - 255. Synonyms: r, x. -* @property {number} green - Green component value. Integer in the range 0 - 255. Synonyms: g, y. -* @property {number} blue - Blue component value. Integer in the range 0 - 255. Synonyms: b, z. -* @example Colors can be set in multiple ways and modified with their aliases, but still stringify in the same way -* Entities.editEntity(, { color: { x: 1, y: 2, z: 3 }}); // { red: 1, green: 2, blue: 3 } -* Entities.editEntity(, { color: { r: 4, g: 5, b: 6 }}); // { red: 4, green: 5, blue: 6 } -* Entities.editEntity(, { color: { red: 7, green: 8, blue: 9 }}); // { red: 7, green: 8, blue: 9 } -* Entities.editEntity(, { color: [10, 11, 12] }); // { red: 10, green: 11, blue: 12 } -* Entities.editEntity(, { color: 13 }); // { red: 13, green: 13, blue: 13 } -* var color = Entities.getEntityProperties().color; // { red: 13, green: 13, blue: 13 } -* color.g = 14; // { red: 13, green: 14, blue: 13 } -* color.blue = 15; // { red: 13, green: 14, blue: 15 } -* Entities.editEntity(, { color: "red"}); // { red: 255, green: 0, blue: 0 } -* Entities.editEntity(, { color: "#00FF00"}); // { red: 0, green: 255, blue: 0 } -*/ + * A color vector. See also the {@link Vec3(0)|Vec3} object. + * + * @typedef {object} Color + * @property {number} red - Red component value. Integer in the range 0 - 255. Synonyms: r, x. + * @property {number} green - Green component value. Integer in the range 0 - 255. Synonyms: g, y. + * @property {number} blue - Blue component value. Integer in the range 0 - 255. Synonyms: b, z. + * @example Colors can be set in multiple ways and modified with their aliases, but still stringify in the same way + * Entities.editEntity(, { color: { x: 1, y: 2, z: 3 }}); // { red: 1, green: 2, blue: 3 } + * Entities.editEntity(, { color: { r: 4, g: 5, b: 6 }}); // { red: 4, green: 5, blue: 6 } + * Entities.editEntity(, { color: { red: 7, green: 8, blue: 9 }}); // { red: 7, green: 8, blue: 9 } + * Entities.editEntity(, { color: [10, 11, 12] }); // { red: 10, green: 11, blue: 12 } + * Entities.editEntity(, { color: 13 }); // { red: 13, green: 13, blue: 13 } + * var color = Entities.getEntityProperties().color; // { red: 13, green: 13, blue: 13 } + * color.g = 14; // { red: 13, green: 14, blue: 13 } + * color.blue = 15; // { red: 13, green: 14, blue: 15 } + * Entities.editEntity(, { color: "red"}); // { red: 255, green: 0, blue: 0 } + * Entities.editEntity(, { color: "#00FF00"}); // { red: 0, green: 255, blue: 0 } + */ /**jsdoc -* A color vector. See also the {@link Vec3(0)|Vec3} object. -* -* @typedef {object} ColorFloat -* @property {number} red - Red component value. Real in the range 0 - 255. Synonyms: r, x. -* @property {number} green - Green component value. Real in the range 0 - 255. Synonyms: g, y. -* @property {number} blue - Blue component value. Real in the range 0 - 255. Synonyms: b, z. -* @example ColorFloats can be set in multiple ways and modified with their aliases, but still stringify in the same way -* Entities.editEntity(, { color: { x: 1, y: 2, z: 3 }}); // { red: 1, green: 2, blue: 3 } -* Entities.editEntity(, { color: { r: 4, g: 5, b: 6 }}); // { red: 4, green: 5, blue: 6 } -* Entities.editEntity(, { color: { red: 7, green: 8, blue: 9 }}); // { red: 7, green: 8, blue: 9 } -* Entities.editEntity(, { color: [10, 11, 12] }); // { red: 10, green: 11, blue: 12 } -* Entities.editEntity(, { color: 13 }); // { red: 13, green: 13, blue: 13 } -* var color = Entities.getEntityProperties().color; // { red: 13, green: 13, blue: 13 } -* color.g = 14; // { red: 13, green: 14, blue: 13 } -* color.blue = 15; // { red: 13, green: 14, blue: 15 } -* Entities.editEntity(, { color: "red"}); // { red: 255, green: 0, blue: 0 } -* Entities.editEntity(, { color: "#00FF00"}); // { red: 0, green: 255, blue: 0 } -*/ + * A color vector with real values. Values may also be null. See also the {@link Vec3(0)|Vec3} object. + * + * @typedef {object} ColorFloat + * @property {number} red - Red component value. Real in the range 0 - 255. Synonyms: r, x. + * @property {number} green - Green component value. Real in the range 0 - 255. Synonyms: g, y. + * @property {number} blue - Blue component value. Real in the range 0 - 255. Synonyms: b, z. + * @example ColorFloats can be set in multiple ways and modified with their aliases, but still stringify in the same way + * Entities.editEntity(, { color: { x: 1, y: 2, z: 3 }}); // { red: 1, green: 2, blue: 3 } + * Entities.editEntity(, { color: { r: 4, g: 5, b: 6 }}); // { red: 4, green: 5, blue: 6 } + * Entities.editEntity(, { color: { red: 7, green: 8, blue: 9 }}); // { red: 7, green: 8, blue: 9 } + * Entities.editEntity(, { color: [10, 11, 12] }); // { red: 10, green: 11, blue: 12 } + * Entities.editEntity(, { color: 13 }); // { red: 13, green: 13, blue: 13 } + * var color = Entities.getEntityProperties().color; // { red: 13, green: 13, blue: 13 } + * color.g = 14; // { red: 13, green: 14, blue: 13 } + * color.blue = 15; // { red: 13, green: 14, blue: 15 } + * Entities.editEntity(, { color: "red"}); // { red: 255, green: 0, blue: 0 } + * Entities.editEntity(, { color: "#00FF00"}); // { red: 0, green: 255, blue: 0 } + */ QScriptValue u8vec3ToScriptValue(QScriptEngine* engine, const glm::u8vec3& vec3); QScriptValue u8vec3ColorToScriptValue(QScriptEngine* engine, const glm::u8vec3& vec3); void u8vec3FromScriptValue(const QScriptValue& object, glm::u8vec3& vec3); diff --git a/libraries/shared/src/RenderLayer.h b/libraries/shared/src/RenderLayer.h index b5bf885616..c95ceb192c 100644 --- a/libraries/shared/src/RenderLayer.h +++ b/libraries/shared/src/RenderLayer.h @@ -12,18 +12,18 @@ #include "QString" /**jsdoc - *

In which layer an entity is rendered.

+ *

A layer in which an entity may be rendered.

* * * * * - * - * - * + * + * + * * *
ValueDescription
worldThe entity will be drawn in the world with everything else.
frontThe entity will be drawn on top of the world layer, but behind the HUD sphere.
hudThe entity will be drawn on top of other layers and the HUD sphere.
"world"The entity is drawn in the world with everything else.
"front"The entity is drawn on top of the world layer but behind the HUD sphere.
"hud"The entity is drawn on top of other layers and the HUD sphere.
- * @typedef {string} RenderLayer + * @typedef {string} Entities.RenderLayer */ enum class RenderLayer { diff --git a/libraries/shared/src/ShapeInfo.cpp b/libraries/shared/src/ShapeInfo.cpp index 00c9b883aa..c60d1c2574 100644 --- a/libraries/shared/src/ShapeInfo.cpp +++ b/libraries/shared/src/ShapeInfo.cpp @@ -17,7 +17,7 @@ #include "NumericalConstants.h" // for MILLIMETERS_PER_METER /**jsdoc - *

A ShapeType defines the shape used for collisions or zones.

+ *

Defines the shape used for collisions or zones.

* * * diff --git a/libraries/shared/src/WebInputMode.h b/libraries/shared/src/WebInputMode.h index d97ccef519..4f43691ac9 100644 --- a/libraries/shared/src/WebInputMode.h +++ b/libraries/shared/src/WebInputMode.h @@ -12,14 +12,14 @@ #include "QString" /**jsdoc - *

Controls how the web surface processed PointerEvents

+ *

Specifies how a web surface processes events.

*
ValueDescription
* * * * - * - * + * + * * *
ValueDescription
touchEvents are processed as touch events.
mouseEvents are processed as mouse events.
"touch"Events are processed as touch events.
"mouse"Events are processed as mouse events.
* @typedef {string} WebInputMode