Mirrors/overte
3
0
Fork 0
mirror of https://github.com/overte-org/overte.git synced 2025-08-07 05:59:24 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Revise JSDoc for key Entities methods plus entity properties

Browse source
This commit is contained in:
David Rowe 2019-06-15 10:22:14 +12:00
parent 351bb3b934
commit b16086de74
24 changed files with 580 additions and 478 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
libraries/entities/src/AmbientLightPropertyGroup.h
View file

@ -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

8
libraries/entities/src/AnimationPropertyGroup.cpp
View file

@ -48,16 +48,18 @@ bool operator!=(const AnimationPropertyGroup& a, const AnimationPropertyGroup& b
/**jsdoc
* The AnimationProperties are used to configure an animation.
* An animation is configured by the following properties:
* @typedef {object} Entities.AnimationProperties
* @property {string} url="" - The URL of the FBX file that has the animation.
* @property {boolean} allowTranslation=true - <code>true</code> to enable translations contained in the animation to be
* played, <code>false</code> to disable translations.
* @property {number} fps=30 - The speed in frames/s that the animation is played at.
* @property {number} firstFrame=0 - The first frame to play in the animation.
* @property {number} lastFrame=100000 - The last frame to play in the animation.
* @property {number} currentFrame=0 - The current frame being played in the animation.
* @property {boolean} running=false - If <code>true</code> then the animation should play.
* @property {boolean} loop=true - If <code>true</code> then the animation should be continuously repeated in a loop.
* @property {boolean} hold=false - If <code>true</code> then the rotations and translations of the last frame played should be
* @property {boolean} loop=true - If <code>true</code> then the animation is continuously repeated in a loop.
* @property {boolean} hold=false - If <code>true</code> then the rotations and translations of the last frame played are
* maintained when the animation stops playing.
*/
void AnimationPropertyGroup::copyToScriptValue(const EntityPropertyFlags& desiredProperties, QScriptValue& properties, QScriptEngine* engine, bool skipDefaults, EntityItemProperties& defaultEntityProperties) const {

3
libraries/entities/src/BloomPropertyGroup.h
View file

@ -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.

556
libraries/entities/src/EntityItemProperties.cpp
View file

@ -615,20 +615,20 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* @typedef {object} Entities.EntityProperties
* @property {Uuid} id - The ID of the entity. <em>Read-only.</em>
* @property {string} name="" - A name for the entity. Need not be unique.
* @property {Entities.EntityType} type - The entity type. You cannot change the type of an entity after it's created. (Though
* its value may switch among <code>"Box"</code>, <code>"Shape"</code>, and <code>"Sphere"</code> depending on changes to
* the <code>shape</code> property set for entities of these types.) <em>Read-only.</em>
* @property {EntityHostType} entityHostType="domain" - How this entity will behave, including if and how it is sent to other people.
* The value can only be set at entity creation by using the <code>entityHostType</code> parameter in
* {@link Entities.addEntity}. Read-only.
* @property {boolean} avatarEntity=false - If <code>true</code> then the entity is an avatar entity; An avatar entity follows you to each domain you visit,
* rendering at the same world coordinates unless it's parented to your avatar. <em>Value cannot be changed after the entity is created.</em><br />
* The value can only be set at entity creation by using the <code>entityHostType</code> parameter in
* {@link Entities.addEntity}. <code>clientOnly</code> is an alias. Read-only.
* @property {boolean} localEntity=false - If <code>true</code> then the entity is a local entity; Local entities only render for you and are not sent over the wire.
* <em>Value cannot be changed after the entity is created.</em><br />
* The value can only be set at entity creation by using the <code>entityHostType</code> parameter in
* {@link Entities.addEntity}. Read-only.
* @property {Entities.EntityType} type - The entity's type. You cannot change the type of an entity after it's created.
* However, its value may switch among <code>"Box"</code>, <code>"Shape"</code>, and <code>"Sphere"</code> depending on
* changes to the <code>shape</code> property set for entities of these types. <em>Read-only.</em>
*
* @property {Entities.EntityHostType} entityHostType="domain" - How the entity is hosted and sent to others for display.
* The value can only be set at entity creation by one of the {@link Entities.addEntity} methods. <em>Read-only.</em>
* @property {boolean} avatarEntity=false - <code>true</code> if the entity is an {@link Entities.EntityHostType|avatar entity},
* <code>false</code> if it isn't. The value is per the <code>entityHostType</code> property value, set at entity creation
* by one of the {@link Entities.addEntity} methods. <em>Read-only.</em>
* @property {boolean} clientOnly=false - A synonym for <code>avatarEntity</code>. <em>Read-only.</em>
* @property {boolean} localEntity=false - <code>true</code> if the entity is a {@link Entities.EntityHostType|local entity},
* <code>false</code> if it isn't. The value is per the <code>entityHostType</code> property value, set at entity creation
* by one of the {@link Entities.addEntity} methods. <em>Read-only.</em>
*
* @property {Uuid} owningAvatarID=Uuid.NULL - The session ID of the owning avatar if <code>avatarEntity</code> is
* <code>true</code>, otherwise {@link Uuid(0)|Uuid.NULL}. <em>Read-only.</em>
*
@ -651,16 +651,18 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* {@link Entities.EntityType|Model} and {@link Entities.EntityType|Shape} entities. Shadows are cast if inside a
* {@link Entities.EntityType|Zone} entity with <code>castShadows</code> enabled in its
* {@link Entities.EntityProperties-Zone|keyLight} property.
* @property {boolean} isVisibleInSecondaryCamera=true - Whether or not the entity is rendered in the secondary camera. If <code>true</code> then the entity is rendered.
* @property {RenderLayer} renderLayer="world" - In which layer this entity renders.
* @property {PrimitiveMode} primitiveMode="solid" - How this entity's geometry is rendered.
* @property {boolean} ignorePickIntersection=false - If <code>true</code>, picks ignore the entity.
* @property {boolean} isVisibleInSecondaryCamera=true - <code>true</code> if the entity is rendered in the secondary camera,
* <code>false</code> if it isn't.
* @property {Entities.RenderLayer} renderLayer="world" - Which layer the entity renders in.
* @property {Entities.PrimitiveMode} primitiveMode="solid" - How the entity's geometry is rendered.
* @property {boolean} ignorePickIntersection=false - <code>true</code> if {@link Picks} and {@link RayPick} ignore the entity,
* <code>false</code> if they don't ignore it.
*
* @property {Vec3} position=0,0,0 - The position of the entity.
* @property {Quat} rotation=0,0,0,1 - The orientation of the entity with respect to world coordinates.
* @property {Vec3} registrationPoint=0.5,0.5,0.5 - The point in the entity that is set to the entity's position and is rotated
* about, {@link Vec3(0)|Vec3.ZERO} &ndash; {@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} &ndash; {@link Vec3(0)|Vec3.ONE}. A value of {@link Vec3(0)|Vec3.ZERO} is the
* entity's minimum x, y, z corner; a value of {@link Vec3(0)|Vec3.ONE} is the entity's maximum x, y, z corner.
*
* @property {Vec3} naturalPosition=0,0,0 - The center of the entity's unscaled mesh model if it has one, otherwise
* {@link Vec3(0)|Vec3.ZERO}. <em>Read-only.</em>
@ -668,72 +670,74 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* {@link Vec3(0)|Vec3.ONE}. <em>Read-only.</em>
*
* @property {Vec3} velocity=0,0,0 - The linear velocity of the entity in m/s with respect to world coordinates.
* @property {number} damping=0.39347 - How much to slow down the linear velocity of an entity over time, <code>0.0</code>
* &ndash; <code>1.0</code>. A higher damping value slows down the entity more quickly. The default value is for an
* exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to <code>1/e = 0.368</code> of its
* initial value.
* @property {number} damping=0.39347 - How much to slow down the linear velocity of an entity over time, range
* <code>0.0</code> &ndash; <code>1.0</code>. A higher damping value slows down the entity more quickly. The default value
* is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to <code>1/e = 0.368</code>
* of its initial value.
* @property {Vec3} angularVelocity=0,0,0 - The angular velocity of the entity in rad/s with respect to its axes, about its
* registration point.
* @property {number} angularDamping=0.39347 - How much to slow down the angular velocity of an entity over time,
* @property {number} angularDamping=0.39347 - How much to slow down the angular velocity of an entity over time, range
* <code>0.0</code> &ndash; <code>1.0</code>. A higher damping value slows down the entity more quickly. The default value
* is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to <code>1/e = 0.368</code>
* of its initial value.
*
* @property {Vec3} gravity=0,0,0 - The acceleration due to gravity in m/s<sup>2</sup> that the entity should move with, in
* world coordinates. Set to <code>{ x: 0, y: -9.8, z: 0 }</code> to simulate Earth's gravity. Gravity is applied to an
* entity's motion only if its <code>dynamic</code> property is <code>true</code>. If changing an entity's
* <code>gravity</code> from {@link Vec3(0)|Vec3.ZERO}, you need to give it a small <code>velocity</code> in order to kick
* off physics simulation.
* The <code>gravity</code> value is applied in addition to the <code>acceleration</code> value.
* world coordinates. Use a value of <code>{ x: 0, y: -9.8, z: 0 }</code> to simulate Earth's gravity. Gravity is applied
* to an entity's motion only if its <code>dynamic</code> property is <code>true</code>. The <code>gravity</code> value is
* applied in addition to the <code>acceleration</code> value.
* <p>If changing an entity's <code>gravity</code> from {@link Vec3(0)|Vec3.ZERO}, you need to give it a small
* <code>velocity</code> in order to kick off physics simulation.</p>
* @property {Vec3} acceleration=0,0,0 - A general acceleration in m/s<sup>2</sup> that the entity should move with, in world
* coordinates. The acceleration is applied to an entity's motion only if its <code>dynamic</code> property is
* <code>true</code>. If changing an entity's <code>acceleration</code> from {@link Vec3(0)|Vec3.ZERO}, you need to give it
* a small <code>velocity</code> in order to kick off physics simulation.
* The <code>acceleration</code> value is applied in addition to the <code>gravity</code> value.
* @property {number} restitution=0.5 - The "bounciness" of an entity when it collides, <code>0.0</code> &ndash;
* <code>true</code>. The <code>acceleration</code> value is applied in addition to the <code>gravity</code> value.
* <p>If changing an entity's <code>acceleration</code> from {@link Vec3(0)|Vec3.ZERO}, you need to give it a small
* <code>velocity</code> in order to kick off physics simulation.<p>
* @property {number} restitution=0.5 - The "bounciness" of an entity when it collides, range <code>0.0</code> &ndash;
* <code>0.99</code>. The higher the value, the more bouncy.
* @property {number} friction=0.5 - How much to slow down an entity when it's moving against another, <code>0.0</code> &ndash;
* <code>10.0</code>. The higher the value, the more quickly it slows down. Examples: <code>0.1</code> for ice,
* @property {number} friction=0.5 - How much to slow down an entity when it's moving against another, range <code>0.0</code>
* &ndash; <code>10.0</code>. The higher the value, the more quickly it slows down. Examples: <code>0.1</code> for ice,
* <code>0.9</code> for sandpaper.
* @property {number} density=1000 - The density of the entity in kg/m<sup>3</sup>, <code>100</code> for balsa wood &ndash;
* <code>10000</code> for silver. The density is used in conjunction with the entity's bounding box volume to work out its
* mass in the application of physics.
* @property {number} density=1000 - The density of the entity in kg/m<sup>3</sup>, range <code>100</code> for balsa wood
* &ndash; <code>10000</code> for silver. The density is used in conjunction with the entity's bounding box volume to work
* out its mass in the application of physics.
*
* @property {boolean} collisionless=false - Whether or not the entity should collide with items per its
* <code>collisionMask<code> property. If <code>true</code> then the entity does not collide. A synonym is <code>ignoreForCollisions</code>.
* <code>collisionMask</code> property. If <code>true</code> then the entity does not collide.
* @property {boolean} ignoreForCollisions - Synonym for <code>collisionless</code>.
* @property {CollisionMask} collisionMask=31 - What types of items the entity should collide with.
* @property {string} collidesWith="static,dynamic,kinematic,myAvatar,otherAvatar," - Synonym for <code>collisionMask</code>,
* in text format.
* @property {string} collisionSoundURL="" - The sound to play when the entity experiences a collision. Valid file formats are
* as per the {@link SoundCache} object.
* @property {string} collisionSoundURL="" - The sound that's played when the entity experiences a collision. Valid file
* formats are per {@link SoundObject}.
* @property {boolean} dynamic=false - Whether or not the entity should be affected by collisions. If <code>true</code> then
* the entity's movement is affected by collisions. A synonym is <code>collisionsWillMove</code>.
* the entity's movement is affected by collisions.
* @property {boolean} collisionsWillMove - A synonym for <code>dynamic</code>.
*
* @property {string} href="" - A "hifi://" metaverse address that a user is taken to when they click on the entity.
* @property {string} href="" - A "hifi://" metaverse address that a user is teleported to when they click on the entity.
* @property {string} description="" - A description of the <code>href</code> property value.
*
* @property {string} userData="" - Used to store extra data about the entity in JSON format. WARNING: Other apps such as the
* Create app can also use this property, so make sure you handle data stored by other apps &mdash; edit only your bit and
* leave the rest of the data intact. You can use <code>JSON.parse()</code> to parse the string into a JavaScript object
* which you can manipulate the properties of, and use <code>JSON.stringify()</code> to convert the object into a string to
* put in the property.
* @property {string} userData="" - Used to store extra data about the entity in JSON format.
* <p><strong>Warning:</strong> Other apps may also use this property, so make sure you handle data stored by other apps:
* edit only your bit and leave the rest of the data intact. You can use <code>JSON.parse()</code> to parse the string into
* a JavaScript object which you can manipulate the properties of, and use <code>JSON.stringify()</code> to convert the
* object into a string to put back in the property.</p>
*
* @property {string} privateUserData="" - Like userData, but only accessible by Entity Server Scripts, AC scripts, and users
* who are given "Can Get and Set Private User Data" permissions from the ACL matrix on the Domain Settings page.
* @property {string} privateUserData="" - Like <code>userData</code>, but only accessible by server entity scripts, assignment
* client scripts, and users who have "Can Get and Set Private User Data" permissions in the domain.
*
* @property {string} script="" - The URL of the client entity script, if any, that is attached to the entity.
* @property {number} scriptTimestamp=0 - Intended to be used to indicate when the client entity script was loaded. Should be
* @property {number} scriptTimestamp=0 - Used to indicate when the client entity script was loaded. Should be
* an integer number of milliseconds since midnight GMT on January 1, 1970 (e.g., as supplied by <code>Date.now()</code>.
* If you update the property's value, the <code>script</code> is re-downloaded and reloaded. This is how the "reload"
* button beside the "script URL" field in properties tab of the Create app works.
* @property {string} serverScripts="" - The URL of the server entity script, if any, that is attached to the entity.
*
* @property {Uuid} parentID=Uuid.NULL - The ID of the entity or avatar that this entity is parented to. {@link Uuid(0)|Uuid.NULL}
* if the entity is not parented.
* @property {number} parentJointIndex=65535 - The joint of the entity or avatar that this entity is parented to. Use
* @property {Uuid} parentID=Uuid.NULL - The ID of the entity or avatar that the entity is parented to.
* {@link Uuid(0)|Uuid.NULL} if the entity is not parented.
* @property {number} parentJointIndex=65535 - The joint of the entity or avatar that the entity is parented to. Use
* <code>65535</code> or <code>-1</code> to parent to the entity or avatar's position and orientation rather than a joint.
* @property {Vec3} localPosition=0,0,0 - The position of the entity relative to its parent if the entity is parented,
* otherwise the same value as <code>position</code>. If the entity is parented to an avatar and is an <code>avatarEntity</code>
* otherwise the same value as <code>position</code>. If the entity is parented to an avatar and is an avatar entity
* so that it scales with the avatar, this value remains the original local position value while the avatar scale changes.
* @property {Quat} localRotation=0,0,0,1 - The rotation of the entity relative to its parent if the entity is parented,
* otherwise the same value as <code>rotation</code>.
@ -742,7 +746,7 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* @property {Vec3} localAngularVelocity=0,0,0 - The angular velocity of the entity relative to its parent if the entity is
* parented, otherwise the same value as <code>position</code>.
* @property {Vec3} localDimensions - The dimensions of the entity. If the entity is parented to an avatar and is an
* <code>avatarEntity</code> so that it scales with the avatar, this value remains the original dimensions value while the
* avatar entity so that it scales with the avatar, this value remains the original dimensions value while the
* avatar scale changes.
*
* @property {Entities.BoundingBox} boundingBox - The axis-aligned bounding box that tightly encloses the entity.
@ -760,16 +764,17 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* @property {Entities.RenderInfo} renderInfo - Information on the cost of rendering the entity. Currently information is only
* provided for <code>Model</code> entities. <em>Read-only.</em>
*
* @property {boolean} cloneable=false - If <code>true</code> then the entity can be cloned via {@link Entities.cloneEntity}.
* @property {boolean} cloneable=false - If <code>true</code> then the domain or avatar entity can be cloned via
* {@link Entities.cloneEntity}.
* @property {number} cloneLifetime=300 - The entity lifetime for clones created from this entity.
* @property {number} cloneLimit=0 - The total number of clones of this entity that can exist in the domain at any given time.
* @property {boolean} cloneDynamic=false - If <code>true</code> then clones created from this entity will have their
* <code>dynamic</code> property set to <code>true</code>.
* @property {boolean} cloneAvatarEntity=false - If <code>true</code> then clones created from this entity will be created as
* avatar entities: their <code>avatarEntity</code> property will be set to <code>true</code>.
* avatar entities.
* @property {Uuid} cloneOriginID - The ID of the entity that this entity was cloned from.
*
* @property {Entities.Grab} grab - The grab-related properties.
* @property {Entities.Grab} grab - The entity's grab-related properties.
*
* @property {string} itemName="" - Certifiable name of the Marketplace item.
* @property {string} itemDescription="" - Certifiable description of the Marketplace item.
@ -781,29 +786,30 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* @property {number} editionNumber=0 - Certifiable integer edition (copy) number or the Marketplace item. Each copy sold in
* the Marketplace is numbered sequentially, starting at 1.
* @property {number} entityInstanceNumber=0 - Certifiable integer instance number for identical entities in a Marketplace
* item. A Marketplace item may have identical parts. If so, then each is numbered sequentially with an instance number.
* item. A Marketplace item may have multiple, identical parts. If so, then each is numbered sequentially with an instance
* number.
* @property {string} marketplaceID="" - Certifiable UUID for the Marketplace item, as used in the URL of the item's download
* and its Marketplace Web page.
* @property {string} certificateID="" - Hash of the entity's static certificate JSON, signed by the artist's private key.
* @property {number} staticCertificateVersion=0 - The version of the method used to generate the <code>certificateID</code>.
*
* @see The different entity types have additional properties as follows:
* @comment The different entity types have additional properties as follows:
* @see {@link Entities.EntityProperties-Box|EntityProperties-Box}
* @see {@link Entities.EntityProperties-Sphere|EntityProperties-Sphere}
* @see {@link Entities.EntityProperties-Shape|EntityProperties-Shape}
* @see {@link Entities.EntityProperties-Model|EntityProperties-Model}
* @see {@link Entities.EntityProperties-Text|EntityProperties-Text}
* @see {@link Entities.EntityProperties-Gizmo|EntityProperties-Gizmo}
* @see {@link Entities.EntityProperties-Grid|EntityProperties-Grid}
* @see {@link Entities.EntityProperties-Image|EntityProperties-Image}
* @see {@link Entities.EntityProperties-Web|EntityProperties-Web}
* @see {@link Entities.EntityProperties-ParticleEffect|EntityProperties-ParticleEffect}
* @see {@link Entities.EntityProperties-Light|EntityProperties-Light}
* @see {@link Entities.EntityProperties-Line|EntityProperties-Line}
* @see {@link Entities.EntityProperties-Material|EntityProperties-Material}
* @see {@link Entities.EntityProperties-Model|EntityProperties-Model}
* @see {@link Entities.EntityProperties-ParticleEffect|EntityProperties-ParticleEffect}
* @see {@link Entities.EntityProperties-PolyLine|EntityProperties-PolyLine}
* @see {@link Entities.EntityProperties-PolyVox|EntityProperties-PolyVox}
* @see {@link Entities.EntityProperties-Grid|EntityProperties-Grid}
* @see {@link Entities.EntityProperties-Gizmo|EntityProperties-Gizmo}
* @see {@link Entities.EntityProperties-Light|EntityProperties-Light}
* @see {@link Entities.EntityProperties-Shape|EntityProperties-Shape}
* @see {@link Entities.EntityProperties-Sphere|EntityProperties-Sphere}
* @see {@link Entities.EntityProperties-Text|EntityProperties-Text}
* @see {@link Entities.EntityProperties-Web|EntityProperties-Web}
* @see {@link Entities.EntityProperties-Zone|EntityProperties-Zone}
* @see {@link Entities.EntityProperties-Material|EntityProperties-Material}
*/
/**jsdoc
@ -812,20 +818,23 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* when the entity is created. If its <code>shape</code> property value is subsequently changed then the entity's
* <code>type</code> will be reported as <code>"Sphere"</code> if the <code>shape</code> is set to <code>"Sphere"</code>,
* otherwise it will be reported as <code>"Shape"</code>.
*
* @typedef {object} Entities.EntityProperties-Box
* @see {@link Entities.EntityProperties-Shape|EntityProperties-Shape}
*/
/**jsdoc
* The <code>"Light"</code> {@link Entities.EntityType|EntityType} adds local lighting effects.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
* The <code>"Light"</code> {@link Entities.EntityType|EntityType} adds local lighting effects. It has properties in addition
* to the common {@link Entities.EntityProperties|EntityProperties}.
*
* @typedef {object} Entities.EntityProperties-Light
* @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. Entity surface outside these dimensions are not lit
* @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. Surfaces outside these dimensions are not lit
* by the light.
* @property {Color} color=255,255,255 - The color of the light emitted.
* @property {number} intensity=1 - The brightness of the light.
* @property {number} falloffRadius=0.1 - The distance from the light's center at which intensity is reduced by 25%.
* @property {boolean} isSpotlight=false - If <code>true</code> then the light is directional, emitting along the entity's
* local negative z-axis; otherwise the light is a point light which emanates in all directions.
* local negative z-axis; otherwise, the light is a point light which emanates in all directions.
* @property {number} exponent=0 - Affects the softness of the spotlight beam: the higher the value the softer the beam.
* @property {number} cutoff=1.57 - Affects the size of the spotlight beam: the higher the value the larger the beam.
* @example <caption>Create a spotlight pointing at the ground.</caption>
@ -845,8 +854,9 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The <code>"Line"</code> {@link Entities.EntityType|EntityType} draws thin, straight lines between a sequence of two or more
* points. Deprecated: Use PolyLines instead.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
* points. It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
* <p class=important>Deprecated: Use PolyLines instead.</p>
*
* @typedef {object} Entities.EntityProperties-Line
* @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. Must be sufficient to contain all the
* <code>linePoints</code>.
@ -871,41 +881,46 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
*/
/**jsdoc
* The <code>"Material"</code> {@link Entities.EntityType|EntityType} modifies the existing materials on entities and avatars.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.<br />
* To apply a material to an entity, set the material entity's <code>parentID</code> property to the entity ID.
* The <code>"Material"</code> {@link Entities.EntityType|EntityType} modifies existing materials on entities and avatars. It
* has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
* <p>To apply a material to an entity, set the material entity's <code>parentID</code> property to the entity ID.
* To apply a material to an avatar, set the material entity's <code>parentID</code> property to the avatar's session UUID.
* To apply a material to your avatar such that it persists across domains and log-ins, create the material as an avatar entity
* by setting the <code>entityHostType</code> parameter in {@link Entities.addEntity} to <code>"avatar"</code>.
* Material entities render as non-scalable spheres if they don't have their parent set.
* by setting the <code>entityHostType</code> parameter in {@link Entities.addEntity} to <code>"avatar"</code> and set the
* entity's <code>parentID</code> property to <code>MyAvatar.SELF_ID</code>.
* Material entities render as non-scalable spheres if they don't have their parent set.</p>
*
* @typedef {object} Entities.EntityProperties-Material
* @property {string} materialURL="" - URL to a {@link MaterialResource}. If you append <code>#name</code> to the URL, the
* material with that name in the {@link MaterialResource} will be applied to the entity. <br />
* Alternatively, set the property value to <code>"materialData"</code> to use the <code>materialData</code> property
* for the {@link MaterialResource} values.
* @property {Vec3} dimensions=0.1,0.1,0.1 - Used when <code>materialMappingMode == "projected"</code>.
* @property {string} materialURL="" - URL to a {@link Entities.MaterialResource|MaterialResource}. If you append
* <code>"#name"</code> to the URL, the material with that name in the {@link Entities.MaterialResource|MaterialResource}
* will be applied to the entity. Alternatively, set the property value to <code>"materialData"</code> to use the
* <code>materialData</code> property for the {@link Entities.MaterialResource|MaterialResource} values.
* @property {string} materialData="" - Used to store {@link Entities.MaterialResource|MaterialResource} data as a JSON string.
* You can use <code>JSON.parse()</code> to parse the string into a JavaScript object which you can manipulate the
* properties of, and use <code>JSON.stringify()</code> to convert the object into a string to put in the property.
* @property {number} priority=0 - The priority for applying the material to its parent. Only the highest priority material is
* applied, with materials of the same priority randomly assigned. Materials that come with the model have a priority of
* <code>0</code>.
* @property {string} parentMaterialName="0" - Selects the mesh part or parts within the parent to which to apply the material.
* If in the format <code>"mat::string"</code>, all mesh parts with material name <code>"string"</code> are replaced.
* Otherwise the property value is parsed as an unsigned integer, specifying the mesh part index to modify. If <code>"all"</code>,
* all mesh parts will be replaced. If an array (starts with <code>"["</code> and ends with <code>"]"</code>), the string will be
* split at each <code>","</code> and each element will be parsed as either a number or a string if it starts with
* <code>"mat::"</code>. In other words, <code>"[0,1,mat::string,mat::string2]"</code> will replace mesh parts 0 and 1, and any
* mesh parts with material <code>"string"</code> or <code>"string2"</code>. Do not put spaces around the commas. Invalid values
* are parsed to <code>0</code>.
* If <code>"all"</code> then all mesh parts are replaced.
* Otherwise the property value is parsed as an unsigned integer, specifying the mesh part index to modify.
* <p>If the string represents an array (starts with <code>"["</code> and ends with <code>"]"</code>), the string is split
* at each <code>","</code> and each element parsed as either a number or a string if it starts with <code>"mat::"</code>.
* For example, <code>"[0,1,mat::string,mat::string2]"</code> will replace mesh parts 0 and 1, and any mesh parts with
* material <code>"string"</code> or <code>"string2"</code>. Do not put spaces around the commas. Invalid values are parsed
* to <code>0</code>.</p>
* @property {string} materialMappingMode="uv" - How the material is mapped to the entity. Either <code>"uv"</code> or
* <code>"projected"</code>. In "uv" mode, the material will be evaluated within the UV space of the mesh it is applied to. In
* "projected" mode, the 3D transform of the Material Entity will be used to evaluate the texture coordinates for the material.
* <code>"projected"</code>. In <code>"uv"</code> mode, the material is evaluated within the UV space of the mesh it is
* applied to. In <code>"projected"</code> mode, the 3D transform (position, rotation, and dimensions) of the Material
* entity is used to evaluate the texture coordinates for the material.
* @property {Vec2} materialMappingPos=0,0 - Offset position in UV-space of the top left of the material, range
* <code>{ x: 0, y: 0 }</code> &ndash; <code>{ x: 1, y: 1 }</code>.
* @property {Vec2} materialMappingScale=1,1 - How much to scale the material within the parent's UV-space.
* @property {number} materialMappingRot=0 - How much to rotate the material within the parent's UV-space, in degrees.
* @property {string} materialData="" - Used to store {@link MaterialResource} data as a JSON string. You can use
* <code>JSON.parse()</code> to parse the string into a JavaScript object which you can manipulate the properties of, and
* use <code>JSON.stringify()</code> to convert the object into a string to put in the property.
* @property {boolean} materialRepeat=true - If true, the material will repeat. If false, fragments outside of texCoord 0 - 1 will be discarded.
* Works in both "uv" and "projected" modes.
* @property {boolean} materialRepeat=true - If <code>true</code>, the material repeats. If <code>false</code>, fragments
* outside of texCoord 0 &ndash; 1 will be discarded. Works in both <code>"uv"</code> and </code>"projected"</code> modes.
* @example <caption>Color a sphere using a Material entity.</caption>
* var entityID = Entities.addEntity({
* type: "Sphere",
@ -931,15 +946,20 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
*/
/**jsdoc
* The <code>"Model"</code> {@link Entities.EntityType|EntityType} displays an FBX or OBJ model.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
* The <code>"Model"</code> {@link Entities.EntityType|EntityType} displays a glTF, FBX, or OBJ model. When adding an entity,
* if no <code>dimensions</code> value is specified then the model is automatically sized to its
* <code>{@link Entities.EntityProperties|naturalDimensions}</code>. It has properties in addition to the common
* {@link Entities.EntityProperties|EntityProperties}.
*
* @typedef {object} Entities.EntityProperties-Model
* @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. When adding an entity, if no <code>dimensions</code>
* value is specified then the model is automatically sized to its
* <code>{@link Entities.EntityProperties|naturalDimensions}</code>.
* @property {Vec3} modelScale - The scale factor applied to the model's dimensions. Deprecated.
* @property {Color} color=255,255,255 - <em>Currently not used.</em>
* @property {string} modelURL="" - The URL of the FBX of OBJ model. Baked FBX models' URLs end in ".baked.fbx".<br />
* @property {string} modelURL="" - The URL of the glTF, FBX, or OBJ model. glTF models may be in JSON or binary format
* (".gltf" or ".glb" URLs respectively). Baked FBX models' URLs end in ".baked.fbx". Model files may also be compressed in GZ
* format, in which case the URL ends in ".gz".
* @property {Vec3} modelScale - The scale factor applied to the model's dimensions.
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @property {string} textures="" - A JSON string of texture name, URL pairs used when rendering the model in place of the
* model's original textures. Use a texture name from the <code>originalTextures</code> property to override that texture.
* Only the texture names and URLs to be overridden need be specified; original textures are used where there are no
@ -948,6 +968,7 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* @property {string} originalTextures="{}" - A JSON string of texture name, URL pairs used in the model. The property value is
* filled in after the entity has finished rezzing (i.e., textures have loaded). You can use <code>JSON.parse()</code> to
* parse the JSON string into a JavaScript object of name, URL pairs. <em>Read-only.</em>
* @property {Color} color=255,255,255 - <em>Currently not used.</em>
*
* @property {ShapeType} shapeType="none" - The shape of the collision hull used if collisions are enabled.
* @property {string} compoundShapeURL="" - The model file to use for the compound shape if <code>shapeType</code> is
@ -955,22 +976,22 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
*
* @property {Entities.AnimationProperties} animation - An animation to play on the model.
*
* @property {Quat[]} jointRotations=[] - Joint rotations applied to the model; <code>[]</code> if none are applied or the
* @property {Quat[]} jointRotations=[]] - Joint rotations applied to the model; <code>[]</code> if none are applied or the
* model hasn't loaded. The array indexes are per {@link Entities.getJointIndex|getJointIndex}. Rotations are relative to
* each joint's parent.<br />
* Joint rotations can be set by {@link Entities.setLocalJointRotation|setLocalJointRotation} and similar functions, or by
* setting the value of this property. If you set a joint rotation using this property you also need to set the
* corresponding <code>jointRotationsSet</code> value to <code>true</code>.
* @property {boolean[]} jointRotationsSet=[] - <code>true</code> values for joints that have had rotations applied,
* each joint's parent.
* <p>Joint rotations can be set by {@link Entities.setLocalJointRotation|setLocalJointRotation} and similar functions, or
* by setting the value of this property. If you set a joint rotation using this property you also need to set the
* corresponding <code>jointRotationsSet</code> value to <code>true</code>.</p>
* @property {boolean[]} jointRotationsSet=[]] - <code>true</code> values for joints that have had rotations applied,
* <code>false</code> otherwise; <code>[]</code> if none are applied or the model hasn't loaded. The array indexes are per
* {@link Entities.getJointIndex|getJointIndex}.
* @property {Vec3[]} jointTranslations=[] - Joint translations applied to the model; <code>[]</code> if none are applied or
* @property {Vec3[]} jointTranslations=[]] - Joint translations applied to the model; <code>[]</code> if none are applied or
* the model hasn't loaded. The array indexes are per {@link Entities.getJointIndex|getJointIndex}. Rotations are relative
* to each joint's parent.<br />
* Joint translations can be set by {@link Entities.setLocalJointTranslation|setLocalJointTranslation} and similar
* to each joint's parent.
* <p>Joint translations can be set by {@link Entities.setLocalJointTranslation|setLocalJointTranslation} and similar
* functions, or by setting the value of this property. If you set a joint translation using this property you also need to
* set the corresponding <code>jointTranslationsSet</code> value to <code>true</code>.
* @property {boolean[]} jointTranslationsSet=[] - <code>true</code> values for joints that have had translations applied,
* set the corresponding <code>jointTranslationsSet</code> value to <code>true</code>.</p>
* @property {boolean[]} jointTranslationsSet=[]] - <code>true</code> values for joints that have had translations applied,
* <code>false</code> otherwise; <code>[]</code> if none are applied or the model hasn't loaded. The array indexes are per
* {@link Entities.getJointIndex|getJointIndex}.
* @property {boolean} relayParentJoints=false - If <code>true</code> and the entity is parented to an avatar, then the
@ -993,95 +1014,100 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* The <code>"ParticleEffect"</code> {@link Entities.EntityType|EntityType} displays a particle system that can be used to
* simulate things such as fire, smoke, snow, magic spells, etc. The particles emanate from an ellipsoid or part thereof.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
*
* @typedef {object} Entities.EntityProperties-ParticleEffect
* @property {boolean} isEmitting=true - If <code>true</code> then particles are emitted.
* @property {boolean} isEmitting=true - <code>true</code> if particles are being emitted, <code>false</code> if they aren't.
* @property {number} maxParticles=1000 - The maximum number of particles to render at one time. Older particles are deleted if
* necessary when new ones are created.
* @property {number} lifespan=3s - How long, in seconds, each particle lives.
* @property {number} emitRate=15 - The number of particles per second to emit.
* @property {number} emitSpeed=5 - The speed, in m/s, that each particle is emitted at.
* @property {number} speedSpread=1 - The spread in speeds at which particles are emitted at. If <code>emitSpeed == 5</code>
* and <code>speedSpread == 1</code>, particles will be emitted with speeds in the range 4m/s &ndash; 6m/s.
* @property {number} speedSpread=1 - The spread in speeds at which particles are emitted at. For example, if
* <code>emitSpeed == 5</code> and <code>speedSpread == 1</code>, particles will be emitted with speeds in the range
* <code>4</code> &ndash; <code>6</code>m/s.
* @property {Vec3} emitAcceleration=0,-9.8,0 - The acceleration that is applied to each particle during its lifetime. The
* default is Earth's gravity value.
* @property {Vec3} accelerationSpread=0,0,0 - The spread in accelerations that each particle is given. If
* @property {Vec3} accelerationSpread=0,0,0 - The spread in accelerations that each particle is given. For example, if
* <code>emitAccelerations == {x: 0, y: -9.8, z: 0}</code> and <code>accelerationSpread ==
* {x: 0, y: 1, z: 0}</code>, each particle will have an acceleration in the range <code>{x: 0, y: -10.8, z: 0}</code>
* &ndash; <code>{x: 0, y: -8.8, z: 0}</code>.
* @property {Vec3} dimensions - The dimensions of the particle effect, i.e., a bounding box containing all the particles
* during their lifetimes, assuming that <code>emitterShouldTrail</code> is <code>false</code>. <em>Read-only.</em>
* during their lifetimes, assuming that <code>emitterShouldTrail == false</code>. <em>Read-only.</em>
* @property {boolean} emitterShouldTrail=false - If <code>true</code> then particles are "left behind" as the emitter moves,
* otherwise they stay with the entity's dimensions.
* otherwise they stay within the entity's dimensions.
*
* @property {Quat} emitOrientation=-0.707,0,0,0.707 - The orientation of particle emission relative to the entity's axes. By
* default, particles emit along the entity's local z-axis, and <code>azimuthStart</code> and <code>azimuthFinish</code>
* are relative to the entity's local x-axis. The default value is a rotation of -90 degrees about the local x-axis, i.e.,
* the particles emit vertically.
* @property {Vec3} emitDimensions=0,0,0 - The dimensions of the shape from which particles are emitted. The shape is specified with
* <code>shapeType</code>.
*
* @property {ShapeType} shapeType="ellipsoid" - The shape from which particles are emitted.
* @property {string} compoundShapeURL="" - The model file to use for the compound shape if <code>shapeType ==
* "compound"</code>.
* @property {Vec3} emitDimensions=0,0,0 - The dimensions of the shape from which particles are emitted.
* @property {number} emitRadiusStart=1 - The starting radius within the shape at which particles start being emitted;
* range <code>0.0</code> &ndash; <code>1.0</code> for the center to the surface, respectively.
* Particles are emitted from the portion of the shape that lies between <code>emitRadiusStart</code> and the
* shape's surface.
* @property {number} polarStart=0 - The angle in radians from the entity's local z-axis at which particles start being emitted
* within the shape; range <code>0</code> &ndash; <code>Math.PI</code>. Particles are emitted from the portion of the
* shape that lies between <code>polarStart<code> and <code>polarFinish</code>. Only used if <code>shapeType</code> is
* <code>ellipsoid</code> or <code>sphere</code>.
* shape that lies between <code>polarStart</code> and <code>polarFinish</code>. Only used if <code>shapeType</code> is
* <code>"ellipsoid"</code> or <code>"sphere"</code>.
* @property {number} polarFinish=0 - The angle in radians from the entity's local z-axis at which particles stop being emitted
* within the shape; range <code>0</code> &ndash; <code>Math.PI</code>. Particles are emitted from the portion of the
* shape that lies between <code>polarStart<code> and <code>polarFinish</code>. Only used if <code>shapeType</code> is
* <code>ellipsoid</code> or <code>sphere</code>.
* shape that lies between <code>polarStart</code> and <code>polarFinish</code>. Only used if <code>shapeType</code> is
* <code>"ellipsoid"</code> or <code>"sphere"</code>.
* @property {number} azimuthStart=-Math.PI - The angle in radians from the entity's local x-axis about the entity's local
* z-axis at which particles start being emitted; range <code>-Math.PI</code> &ndash; <code>Math.PI</code>. Particles are
* emitted from the portion of the shape that lies between <code>azimuthStart<code> and <code>azimuthFinish</code>.
* Only used if <code>shapeType</code> is <code>ellipsoid</code>, <code>sphere</code>, or <code>circle</code>.
* emitted from the portion of the shape that lies between <code>azimuthStart</code> and <code>azimuthFinish</code>.
* Only used if <code>shapeType</code> is <code>"ellipsoid"</code>, <code>"sphere"</code>, or <code>"circle"</code>.
* @property {number} azimuthFinish=Math.PI - The angle in radians from the entity's local x-axis about the entity's local
* z-axis at which particles stop being emitted; range <code>-Math.PI</code> &ndash; <code>Math.PI</code>. Particles are
* emitted from the portion of the shape that lies between <code>azimuthStart<code> and <code>azimuthFinish</code>.
* Only used if <code>shapeType</code> is <code>ellipsoid</code>, <code>sphere</code>, or <code>circle</code>..
* emitted from the portion of the shape that lies between <code>azimuthStart</code> and <code>azimuthFinish</code>.
* Only used if <code>shapeType</code> is <code>"ellipsoid"</code>, <code>"sphere"</code>, or <code>"circle"</code>.
*
* @property {string} textures="" - The URL of a JPG or PNG image file to display for each particle. If you want transparency,
* use PNG format.
* @property {number} particleRadius=0.025 - The radius of each particle at the middle of its life.
* @property {number} radiusStart=NaN - The radius of each particle at the start of its life. If <code>NaN</code>, the
* @property {number} radiusStart=null - The radius of each particle at the start of its life. If <code>null</code>, the
* <code>particleRadius</code> value is used.
* @property {number} radiusFinish=NaN - The radius of each particle at the end of its life. If <code>NaN</code>, the
* @property {number} radiusFinish=null - The radius of each particle at the end of its life. If <code>null</code>, the
* <code>particleRadius</code> value is used.
* @property {number} radiusSpread=0 - The spread in radius that each particle is given. If <code>particleRadius == 0.5</code>
* and <code>radiusSpread == 0.25</code>, each particle will have a radius in the range <code>0.25</code> &ndash;
* <code>0.75</code>.
* @property {number} radiusSpread=0 - The spread in radius that each particle is given. For example, if
* <code>particleRadius == 0.5</code> and <code>radiusSpread == 0.25</code>, each particle will have a radius in the range
* <code>0.25</code> &ndash; <code>0.75</code>.
* @property {Color} color=255,255,255 - The color of each particle at the middle of its life.
* @property {ColorFloat} colorStart={} - The color of each particle at the start of its life. If any of the component values are
* undefined, the <code>color</code> value is used.
* @property {ColorFloat} colorFinish={} - The color of each particle at the end of its life. If any of the component values are
* undefined, the <code>color</code> value is used.
* @property {Color} colorSpread=0,0,0 - The spread in color that each particle is given. If
* @property {ColorFloat} colorStart=null,null,null - The color of each particle at the start of its life. If any of the
* component values are undefined, the <code>color</code> value is used.
* @property {ColorFloat} colorFinish=null,null,null - The color of each particle at the end of its life. If any of the
* component values are undefined, the <code>color</code> value is used.
* @property {Color} colorSpread=0,0,0 - The spread in color that each particle is given. For example, if
* <code>color == {red: 100, green: 100, blue: 100}</code> and <code>colorSpread ==
* {red: 10, green: 25, blue: 50}</code>, each particle will have a color in the range
* <code>{red: 90, green: 75, blue: 50}</code> &ndash; <code>{red: 110, green: 125, blue: 150}</code>.
* @property {number} alpha=1 - The alpha of each particle at the middle of its life.
* @property {number} alphaStart=NaN - The alpha of each particle at the start of its life. If <code>NaN</code>, the
* @property {number} alpha=1 - The opacity of each particle at the middle of its life.
* @property {number} alphaStart=null - The opacity of each particle at the start of its life. If <code>null</code>, the
* <code>alpha</code> value is used.
* @property {number} alphaFinish=NaN - The alpha of each particle at the end of its life. If <code>NaN</code>, the
* @property {number} alphaFinish=null - The opacity of each particle at the end of its life. If <code>null</code>, the
* <code>alpha</code> value is used.
* @property {number} alphaSpread=0 - The spread in alpha that each particle is given. If <code>alpha == 0.5</code>
* and <code>alphaSpread == 0.25</code>, each particle will have an alpha in the range <code>0.25</code> &ndash;
* <code>0.75</code>.
* @property {number} particleSpin=0 - The spin of each particle at the middle of its life. In the range <code>-2*PI</code> &ndash; <code>2*PI</code>.
* @property {number} spinStart=NaN - The spin of each particle at the start of its life. In the range <code>-2*PI</code> &ndash; <code>2*PI</code>.
* If <code>NaN</code>, the <code>particleSpin</code> value is used.
* @property {number} spinFinish=NaN - The spin of each particle at the end of its life. In the range <code>-2*PI</code> &ndash; <code>2*PI</code>.
* If <code>NaN</code>, the <code>particleSpin</code> value is used.
* @property {number} spinSpread=0 - The spread in spin that each particle is given. In the range <code>0</code> &ndash; <code>2*PI</code>. If <code>particleSpin == PI</code>
* and <code>spinSpread == PI/2</code>, each particle will have a spin in the range <code>PI/2</code> &ndash; <code>3*PI/2</code>.
* @property {boolean} rotateWithEntity=false - Whether or not the particles' spin will rotate with the entity. If false, when <code>particleSpin == 0</code>, the particles will point
* up in the world. If true, they will point towards the entity's up vector, based on its orientation.
* @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated.
*
* @property {ShapeType} shapeType="ellipsoid" - The shape of the collision hull used if collisions are enabled.
* @property {string} compoundShapeURL="" - The model file to use for the compound shape if <code>shapeType</code> is
* <code>"compound"</code>.
* @property {number} alphaSpread=0 - The spread in alpha that each particle is given. For example, if
* <code>alpha == 0.5</code> and <code>alphaSpread == 0.25</code>, each particle will have an alpha in the range
* <code>0.25</code> &ndash; <code>0.75</code>.
* @property {Entities.Pulse} pulse - Color and alpha pulse.
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @property {number} particleSpin=0 - The rotation of each particle at the middle of its life, range <code>-2 * Math.PI</code>
* &ndash; <code>2 * Math.PI</code> radians.
* @property {number} spinStart=null - The rotation of each particle at the start of its life, range <code>-2 * Math.PI</code>
* &ndash; <code>2 * Math.PI</code> radians. If <code>null</code>, the <code>particleSpin</code> value is used.
* @property {number} spinFinish=null - The rotation of each particle at the end of its life, range <code>-2 * Math.PI</code>
* &ndash; <code>2 * Math.PI</code> radians. If <code>null</code>, the <code>particleSpin</code> value is used.
* @property {number} spinSpread=0 - The spread in spin that each particle is given, range <code>0</code> &ndash;
* <code>2 * Math.PI</code> radians. For example, if <code>particleSpin == Math.PI</code> and
* <code>spinSpread == Math.PI / 2</code>, each particle will have a rotation in the range <code>Math.PI / 2</code> &ndash;
* <code>3 * Math.PI / 2</code>.
* @property {boolean} rotateWithEntity=false - <code>true</code> to make the particles' rotations relative to the entity's
* instantaneous rotation, <code>false</code> to make them relative to world coordinates. If <code>true</code> with
* <code>particleSpin == 0</code>, the particles keep oriented per the entity's orientation.
*
* @example <caption>Create a ball of green smoke.</caption>
* particles = Entities.addEntity({
@ -1103,26 +1129,29 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The <code>"PolyLine"</code> {@link Entities.EntityType|EntityType} draws textured, straight lines between a sequence of
* points.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
* points. It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
*
* @typedef {object} Entities.EntityProperties-PolyLine
* @property {Vec3} dimensions=1,1,1 - The dimensions of the entity, i.e., the size of the bounding box that contains the
* lines drawn.
* @property {Vec3[]} linePoints=[] - The sequence of points to draw lines between. The values are relative to the entity's
* position. A maximum of 70 points can be specified. Must be specified in order for the entity to render.
* @property {Vec3[]} normals=[] - The normal vectors for the line's surface at the <code>linePoints</code>. The values are
* @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity, i.e., the size of the bounding box that contains the
* lines drawn. <em>Read-only.</em>
* @property {Vec3[]} linePoints=[]] - The sequence of points to draw lines between. The values are relative to the entity's
* position. A maximum of 70 points can be specified.
* @property {Vec3[]} normals=[]] - The normal vectors for the line's surface at the <code>linePoints</code>. The values are
* relative to the entity's orientation. Must be specified in order for the entity to render.
* @property {number[]} strokeWidths=[] - The widths, in m, of the line at the <code>linePoints</code>. Must be specified in
* @property {number[]} strokeWidths=[]] - The widths, in m, of the line at the <code>linePoints</code>. Must be specified in
* order for the entity to render.
* @property {Vec3[]} strokeColors=[] - The base colors of each point, which are multiplied with the color of the texture, going from 0-1.
* If strokeColors.length < the number of points, <code>color</code> is used for the remaining points.
* @property {Color} color=255,255,255 - Used as the color for each point if <code>strokeColors</code> is too short.
* @property {Vec3[]} strokeColors=[]] - The base colors of each point, with values in the range <code>0.0,0.0,0.0</code>
* &mdash; <code>1.0,1.0,1.0</code>. These colors are multiplied with the color of the texture. If there are more line
* points than stroke colors, the <code>color</code> property value is used for the remaining points.
* <p><strong>Warning:</strong> The ordinate values are in the range <code>0.0</code> &mdash; <code>1.0</code>.</p>
* @property {Color} color=255,255,255 - Used as the color for each point if <code>strokeColors</code> doesn't have a value for
* the point.
* @property {string} textures="" - The URL of a JPG or PNG texture to use for the lines. If you want transparency, use PNG
* format.
* @property {boolean} isUVModeStretch=true - If <code>true</code>, the texture is stretched to fill the whole line, otherwise
* the texture repeats along the line.
* @property {bool} glow=false - If <code>true</code>, the alpha of the strokes will drop off farther from the center.
* @property {bool} faceCamera=false - If <code>true</code>, each line segment will rotate to face the camera.
* @property {boolean} glow=false - If <code>true</code>, the opacity of the strokes drops off away from the line center.
* @property {boolean} faceCamera=false - If <code>true</code>, each line segment rotates to face the camera.
* @example <caption>Draw a textured "V".</caption>
* var entity = Entities.addEntity({
* type: "PolyLine",
@ -1150,9 +1179,10 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* The <code>"PolyVox"</code> {@link Entities.EntityType|EntityType} displays a set of textured voxels.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
* If you have two or more neighboring PolyVox entities of the same size abutting each other, you can display them as joined by
* configuring their <code>voxelSurfaceStyle</code> and neighbor ID properties.<br />
* PolyVox entities uses a library from <a href="http://www.volumesoffun.com/">Volumes of Fun</a>. Their
* <a href="http://www.volumesoffun.com/polyvox-documentation/">library documentation</a> may be useful to read.
* configuring their <code>voxelSurfaceStyle</code> and various neighbor ID properties.
* <p>PolyVox entities uses a library from <a href="http://www.volumesoffun.com/">Volumes of Fun</a>. Their
* <a href="http://www.volumesoffun.com/polyvox-documentation/">library documentation</a> may be useful to read.</p>
*
* @typedef {object} Entities.EntityProperties-PolyVox
* @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity.
* @property {Vec3} voxelVolumeSize=32,32,32 - Integer number of voxels along each axis of the entity, in the range
@ -1203,12 +1233,14 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The <code>"Shape"</code> {@link Entities.EntityType|EntityType} displays an entity of a specified <code>shape</code>.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
*
* @typedef {object} Entities.EntityProperties-Shape
* @property {Entities.Shape} shape="Sphere" - The shape of the entity.
* @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity.
* @property {Color} color=255,255,255 - The color of the entity.
* @property {number} alpha=1 - The alpha of the shape.
* @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated.
* @property {number} alpha=1 - The opacity of the entity, range <code>0.0</code> &ndash; <code>1.0</code>.
* @property {Entities.Pulse} pulse - Color and alpha pulse.
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @example <caption>Create a cylinder.</caption>
* var shape = Entities.addEntity({
* type: "Shape",
@ -1225,30 +1257,39 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* when the entity is created. If its <code>shape</code> property value is subsequently changed then the entity's
* <code>type</code> will be reported as <code>"Box"</code> if the <code>shape</code> is set to <code>"Cube"</code>,
* otherwise it will be reported as <code>"Shape"</code>.
*
* @typedef {object} Entities.EntityProperties-Sphere
* @see {@link Entities.EntityProperties-Shape|EntityProperties-Shape}
*/
/**jsdoc
* The <code>"Text"</code> {@link Entities.EntityType|EntityType} displays a 2D rectangle of text in the domain.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
*
* @typedef {object} Entities.EntityProperties-Text
* @property {Vec3} dimensions=0.1,0.1,0.01 - The dimensions of the entity.
* @property {string} text="" - The text to display on the face of the entity. Text wraps if necessary to fit. New lines can be
* created using <code>\n</code>. Overflowing lines are not displayed.
* @property {number} lineHeight=0.1 - The height of each line of text (thus determining the font size).
* @property {Color} textColor=255,255,255 - The color of the text.
* @property {number} textAlpha=1.0 - The text alpha.
* @property {number} textAlpha=1.0 - The opacity of the text.
* @property {Color} backgroundColor=0,0,0 - The color of the background rectangle.
* @property {number} backgroundAlpha=1.0 - The background alpha.
* @property {BillboardMode} billboardMode="none" - If <code>"none"</code>, the entity is not billboarded. If <code>"yaw"</code>, the entity will be
* oriented to follow your camera around the y-axis. If <code>"full"</code> the entity will be oriented to face your camera. The following deprecated
* behavior is also supported: you can also set <code>"faceCamera"</code> to <code>true</code> to set <code>billboardMode</code> to "yaw", and you can set
* <code>"isFacingAvatar"</code> to <code>true</code> to set <code>billboardMode</code> to "full". Setting either to <code>false</code> sets the mode to "none"
* @property {number} backgroundAlpha=1.0 - The opacity of the background.
* @property {Entities.Pulse} pulse - Color and alpha pulse.
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @property {number} leftMargin=0.0 - The left margin, in meters.
* @property {number} rightMargin=0.0 - The right margin, in meters.
* @property {number} topMargin=0.0 - The top margin, in meters.
* @property {number} bottomMargin=0.0 - The bottom margin, in meters.
* @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated.
* @property {BillboardMode} billboardMode="none" - Whether the entity is billboarded to face the camera.
* @property {boolean} faceCamera - <code>true</code> if <code>billboardMode</code> is <code>"yaw"</code>, otherwise
* <code>false</code>. Setting this property to <code>false</code> sets the <code>billboardMode</code> to
* <code>"none"</code>.
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @property {boolean} isFacingAvatar - <code>true</code> if <code>billboardMode</code> is <code>"full"</code>, otherwise
* <code>false</code>. Setting this property to <code>false</code> sets the <code>billboardMode</code> to
* <code>"none"</code>.
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @example <caption>Create a text entity.</caption>
* var text = Entities.addEntity({
* type: "Text",
@ -1262,28 +1303,36 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
*/
/**jsdoc
* The <code>"Web"</code> {@link Entities.EntityType|EntityType} displays a browsable Web page. Each user views their own copy
* of the Web page: if one user navigates to another page on the entity, other users do not see the change; if a video is being
* played, users don't see it in sync.
* The entity has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
* The <code>"Web"</code> {@link Entities.EntityType|EntityType} displays a browsable web page. Each user views their own copy
* of the web page: if one user navigates to another page on the entity, other users do not see the change; if a video is being
* played, users don't see it in sync. It has properties in addition to the common
* {@link Entities.EntityProperties|EntityProperties}.
*
* @typedef {object} Entities.EntityProperties-Web
* @property {Vec3} dimensions=0.1,0.1,0.01 - The dimensions of the entity.
* @property {Color} color=255,255,255 - The color of the web surface.
* @property {number} alpha=1 - The alpha of the web surface.
* @property {BillboardMode} billboardMode="none" - If <code>"none"</code>, the entity is not billboarded. If <code>"yaw"</code>, the entity will be
* oriented to follow your camera around the y-axis. If <code>"full"</code> the entity will be oriented to face your camera. The following deprecated
* behavior is also supported: you can also set <code>"faceCamera"</code> to <code>true</code> to set <code>billboardMode</code> to "yaw", and you can set
* <code>"isFacingAvatar"</code> to <code>true</code> to set <code>billboardMode</code> to "full". Setting either to <code>false</code> sets the mode to "none"
* @property {string} sourceUrl="" - The URL of the Web page to display. This value does not change as you or others navigate
* @property {string} sourceUrl="" - The URL of the web page to display. This value does not change as you or others navigate
* on the Web entity.
* @property {Color} color=255,255,255 - The color of the web surface.
* @property {number} alpha=1 - The opacity of the web surface.
* @property {Entities.Pulse} pulse - Color and alpha pulse.
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @property {BillboardMode} billboardMode="none" - Whether the entity is billboarded to face the camera.
* @property {boolean} faceCamera - <code>true</code> if <code>billboardMode</code> is <code>"yaw"</code>, otherwise
* <code>false</code>. Setting this property to <code>false</code> sets the <code>billboardMode</code> to
* <code>"none"</code>.
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @property {boolean} isFacingAvatar - <code>true</code> if <code>billboardMode</code> is <code>"full"</code>, otherwise
* <code>false</code>. Setting this property to <code>false</code> sets the <code>billboardMode</code> to
* <code>"none"</code>.
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @property {number} dpi=30 - The resolution to display the page at, in dots per inch. If you convert this to dots per meter
* (multiply by 1 / 0.0254 = 39.3701) then multiply <code>dimensions.x</code> and <code>dimensions.y</code> by that value
* you get the resolution in pixels.
* @property {string} scriptURL="" - The URL of a JavaScript file to inject into the Web page.
* @property {number} maxFPS=10 - The maximum update rate for the Web content, in frames/second.
* @property {string} scriptURL="" - The URL of a JavaScript file to inject into the web page.
* @property {number} maxFPS=10 - The maximum update rate for the web content, in frames/second.
* @property {WebInputMode} inputMode="touch" - The user input mode to use.
* @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated.
* @property {boolean} showKeyboardFocusHighlight - Whether or not to show the keyboard focus highlight when this entity has focus.
* @property {boolean} showKeyboardFocusHighlight=true - <code>true</code> to highlight the entity when it has keyboard focus,
* <code>false</code> to not display the highlight.
* @example <caption>Create a Web entity displaying at 1920 x 1080 resolution.</caption>
* var METERS_TO_INCHES = 39.3701;
* var entity = Entities.addEntity({
@ -1303,11 +1352,12 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The <code>"Zone"</code> {@link Entities.EntityType|EntityType} is a volume of lighting effects and avatar permissions.
* Avatar interaction events such as {@link Entities.enterEntity} are also often used with a Zone entity.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
* 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.
* @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the volume in which the zone's lighting effects and avatar
* permissions have effect.
*
* @property {ShapeType} shapeType="box" - The shape of the volume in which the zone's lighting effects and avatar
* permissions have effect. Reverts to the default value if set to <code>"none"</code>, or set to <code>"compound"</code>
@ -1315,62 +1365,41 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* @property {string} compoundShapeURL="" - The model file to use for the compound shape if <code>shapeType</code> is
* <code>"compound"</code>.
*
* @property {string} keyLightMode="inherit" - Configures the key light in the zone. Possible values:<br />
* <code>"inherit"</code>: The key light from any enclosing zone continues into this zone.<br />
* <code>"disabled"</code>: The key light from any enclosing zone and the key light of this zone are disabled in this
* zone.<br />
* <code>"enabled"</code>: The key light properties of this zone are enabled, overriding the key light of from any
* enclosing zone.
* @property {Entities.ComponentMode} keyLightMode="inherit" - Configures the key light in the zone.
* @property {Entities.KeyLight} keyLight - The key light properties of the zone.
*
* @property {string} ambientLightMode="inherit" - Configures the ambient light in the zone. Possible values:<br />
* <code>"inherit"</code>: The ambient light from any enclosing zone continues into this zone.<br />
* <code>"disabled"</code>: The ambient light from any enclosing zone and the ambient light of this zone are disabled in
* this zone.<br />
* <code>"enabled"</code>: The ambient light properties of this zone are enabled, overriding the ambient light from any
* enclosing zone.
* @property {Entities.ComponentMode} ambientLightMode="inherit" - Configures the ambient light in the zone.
* @property {Entities.AmbientLight} ambientLight - The ambient light properties of the zone.
*
* @property {string} skyboxMode="inherit" - Configures the skybox displayed in the zone. Possible values:<br />
* <code>"inherit"</code>: The skybox from any enclosing zone is dislayed in this zone.<br />
* <code>"disabled"</code>: The skybox from any enclosing zone and the skybox of this zone are disabled in this zone.<br />
* <code>"enabled"</code>: The skybox properties of this zone are enabled, overriding the skybox from any enclosing zone.
* @property {Entities.ComponentMode} skyboxMode="inherit" - Configures the skybox displayed in the zone.
* @property {Entities.Skybox} skybox - The skybox properties of the zone.
*
* @property {string} hazeMode="inherit" - Configures the haze in the zone. Possible values:<br />
* <code>"inherit"</code>: The haze from any enclosing zone continues into this zone.<br />
* <code>"disabled"</code>: The haze from any enclosing zone and the haze of this zone are disabled in this zone.<br />
* <code>"enabled"</code>: The haze properties of this zone are enabled, overriding the haze from any enclosing zone.
* @property {Entities.ComponentMode} hazeMode="inherit" - Configures the haze in the zone.
* @property {Entities.Haze} haze - The haze properties of the zone.
*
* @property {string} bloomMode="inherit" - Configures the bloom in the zone. Possible values:<br />
* <code>"inherit"</code>: The bloom from any enclosing zone continues into this zone.<br />
* <code>"disabled"</code>: The bloom from any enclosing zone and the bloom of this zone are disabled in this zone.<br />
* <code>"enabled"</code>: The bloom properties of this zone are enabled, overriding the bloom from any enclosing zone.
* @property {Entities.ComponentMode} bloomMode="inherit" - Configures the bloom in the zone.
* @property {Entities.Bloom} bloom - The bloom properties of the zone.
*
* @property {boolean} flyingAllowed=true - If <code>true</code> then visitors can fly in the zone; otherwise they cannot.
* Only works on domain entities.
* @property {boolean} flyingAllowed=true - If <code>true</code> then visitors can fly in the zone; otherwise, they cannot.
* Only works for domain entities.
* @property {boolean} ghostingAllowed=true - If <code>true</code> then visitors with avatar collisions turned off will not
* collide with content in the zone; otherwise visitors will always collide with content in the zone. Only works on domain entities.
* collide with content in the zone; otherwise, visitors will always collide with content in the zone. Only works for domain
* entities.
* @property {string} filterURL="" - The URL of a JavaScript file that filters changes to properties of entities within the
* zone. It is periodically executed for each entity in the zone. It can, for example, be used to not allow changes to
* certain properties.<br />
*
* @property {string} avatarPriority="inherit" - Configures the update priority of contained avatars to other clients.<br />
* <code>"inherit"</code>: Priority from enclosing zones is unchanged.<br />
* <code>"crowd"</code>: Priority in this zone is the normal priority.<br />
* <code>"hero"</code>: Avatars in this zone will have an increased update priority
* certain properties:
* <pre>
*
* function filter(properties) {
* // Test and edit properties object values,
* // Check and edit properties object values,
* // e.g., properties.modelURL, as required.
* return properties;
* }
* </pre>
*
* @property {Entities.AvatarPriorityMode} avatarPriority="inherit" - Configures the priority of updates from avatars in the
* zone to other clients.
*
* @example <caption>Create a zone that casts a red key light along the x-axis.</caption>
* var zone = Entities.addEntity({
* type: "Zone",
@ -1388,19 +1417,29 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The <code>"Image"</code> {@link Entities.EntityType|EntityType} displays an image on a 2D rectangle in the domain.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
*
* @typedef {object} Entities.EntityProperties-Image
* @property {Vec3} dimensions=0.1,0.1,0.01 - The dimensions of the entity.
* @property {string} imageURL="" - The URL of the image to use.
* @property {boolean} emissive=false - Whether or not the image should be emissive (unlit).
* @property {boolean} keepAspectRatio=true - Whether or not the image should maintain its aspect ratio.
* @property {BillboardMode} billboardMode="none" - If <code>"none"</code>, the entity is not billboarded. If <code>"yaw"</code>, the entity will be
* oriented to follow your camera around the y-axis. If <code>"full"</code> the entity will be oriented to face your camera. The following deprecated
* behavior is also supported: you can also set <code>"faceCamera"</code> to <code>true</code> to set <code>billboardMode</code> to "yaw", and you can set
* <code>"isFacingAvatar"</code> to <code>true</code> to set <code>billboardMode</code> to "full". Setting either to <code>false</code> sets the mode to "none"
* @property {Rect} subImage={ x: 0, y: 0, width: -1, height: -1 } - The portion of the image to display. If width or height are -1, defaults to
* the full image in that dimension.
* @property {boolean} emissive=false - <code>true</code> fi the the image should be emissive (unlit), <code>false</code> if it
* shouldn't.
* @property {boolean} keepAspectRatio=true - <code>true</code> if the image should maintain its aspect ratio,
* <code>false</code> if it shouldn't.
* @property {Rect} subImage=0,0,0,0 - The portion of the image to display. If width or height are <code>0</code>, it defaults
* to the full image in that dimension.
* @property {Color} color=255,255,255 - The color of the image.
* @property {number} alpha=1 - The alpha of the image.
* @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated.
* @property {number} alpha=1 - The opacity of the image.
* @property {Entities.Pulse} pulse - Color and alpha pulse.
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @property {BillboardMode} billboardMode="none" - Whether the entity is billboarded to face the camera.
* @property {boolean} faceCamera - <code>true</code> if <code>billboardMode</code> is <code>"yaw"</code>, otherwise
* <code>false</code>. Setting this property to <code>false</code> sets the <code>billboardMode</code> to
* <code>"none"</code>.
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @property {boolean} isFacingAvatar - <code>true</code> if <code>billboardMode</code> is <code>"full"</code>, otherwise
* <code>false</code>. Setting this property to <code>false</code> sets the <code>billboardMode</code> to
* <code>"none"</code>.
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @example <caption>Create a image entity.</caption>
* var image = Entities.addEntity({
* type: "Image",
@ -1415,16 +1454,19 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The <code>"Grid"</code> {@link Entities.EntityType|EntityType} displays a grid on a 2D plane.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
*
* @typedef {object} Entities.EntityProperties-Grid
* @property {Vec3} dimensions - 0.1,0.1,0.01 - The dimensions of the entity.
* @property {Color} color=255,255,255 - The color of the grid.
* @property {number} alpha=1 - The alpha of the grid.
* @property {number} alpha=1 - The opacity of the grid.
* @property {Entities.Pulse} pulse - Color and alpha pulse.
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @property {boolean} followCamera=true - If <code>true</code>, the grid is always visible even as the camera moves to another
* position.
* @property {number} majorGridEvery=5 - Integer number of <code>minorGridEvery</code> intervals at which to draw a thick grid
* line. Minimum value = <code>1</code>.
* @property {number} minorGridEvery=1 - Real number of meters at which to draw thin grid lines. Minimum value =
* <code>0.001</code>.
* @property {Entities.Pulse} pulse - The pulse-related properties. Deprecated.
* @example <caption>Create a grid entity.</caption>
* var grid = Entities.addEntity({
* type: "Grid",
@ -1440,8 +1482,10 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
/**jsdoc
* The <code>"Gizmo"</code> {@link Entities.EntityType|EntityType} displays an entity that could be used as UI.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
*
* @typedef {object} Entities.EntityProperties-Gizmo
* @property {GizmoType} gizmoType="ring" - The gizmo type of the entity.
* @property {Vec3} dimensions=0.1,0.001,0.1 - The dimensions of the entity.
* @property {Entities.GizmoType} gizmoType="ring" - The gizmo type of the entity.
* @property {Entities.RingGizmo} ring - The ring gizmo properties.
*/
@ -1850,7 +1894,7 @@ QScriptValue EntityItemProperties::copyToScriptValue(QScriptEngine* engine, bool
* @typedef {object} Entities.RenderInfo
* @property {number} verticesCount - The number of vertices in the entity.
* @property {number} texturesCount - The number of textures in the entity.
* @property {number} textureSize - The total size of the textures in the entity, in bytes.
* @property {number} texturesSize - The total size of the textures in the entity, in bytes.
* @property {boolean} hasTransparent - Is <code>true</code> if any of the textures has transparency.
* @property {number} drawCalls - The number of draw calls required to render the entity.
*/

94
libraries/entities/src/EntityScriptingInterface.h
View file

@ -101,9 +101,13 @@ public:
};
/**jsdoc
* The Entities API provides facilities to create and interact with entities. Entities are 2D and 3D objects that are visible
* to everyone and typically are persisted to the domain. For Interface scripts, the entities available are those that
* Interface has displayed and so knows about.
* The <code>Entities</code> API provides facilities to create and interact with entities. Entities are 2D or 3D objects
* displayed in-world. Depending on their {@link Entities.EntityHostType|EntityHostType}, they may persist in the domain as
* "domain" entities, travel to different domains with a user as "avatar" entities, or be visible only to an individual user as
* "local" entities (a.k.a. "overlays").
*
* <p>Note: For Interface scripts, the entities available to scripts are those that Interface has displayed and so knows
* about.</p>
*
* @namespace Entities
*
@ -113,9 +117,9 @@ public:
* @hifi-server-entity
* @hifi-assignment-client
*
* @property {Uuid} keyboardFocusEntity - Get or set the {@link Entities.EntityType|Web} entity that has keyboard focus.
* If no entity has keyboard focus, get returns <code>null</code>; set to <code>null</code> or {@link Uuid(0)|Uuid.NULL} to
* clear keyboard focus.
* @property {Uuid} keyboardFocusEntity - The {@link Entities.EntityType|Web} entity that has keyboard focus. If no Web entity
* has keyboard focus, get returns <code>null</code>; set to <code>null</code> or {@link Uuid(0)|Uuid.NULL} to clear
* keyboard focus.
*/
/// handles scripting of Entity commands from JS passed to assigned clients
class EntityScriptingInterface : public OctreeScriptingInterface, public Dependency {
@ -245,35 +249,39 @@ public slots:
Q_INVOKABLE bool canGetAndSetPrivateUserData();
/**jsdoc
* <p>How an entity is sent over the wire.</p>
* <p>How an entity is hosted and sent to others for display.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>domain</code></td><td>Domain entities are sent over the entity server to everyone else</td></tr>
* <tr><td><code>avatar</code></td><td>Avatar entities are sent over the avatar entity and are associated with one avatar</td></tr>
* <tr><td><code>local</code></td><td>Local entities are not sent over the wire and will only render for you, locally</td></tr>
* <tr><td><code>"domain"</code></td><td>Domain entities are stored on the domain, are visible to everyone, and are
* sent to everyone by the entity server.</td></tr>
* <tr><td><code>"avatar"</code></td><td>Avatar entities are stored on an Interface client, are visible to everyone,
* and are sent to everyone by the avatar mixer. They follow the client to each domain visited, displaying at the
* same domain coordinates unless parented to the client's avatar.</td></tr>
* <tr><td><code>"local"</code></td><td>Local entities are ephemeral &mdash; they aren't stored anywhere &mdash; and
* are visible only to the client. They follow the client to each domain visited, displaying at the same domain
* coordinates unless parented to the client's avatar. Additionally, local entities are collisionless.</td></tr>
* </tbody>
* </table>
* @typedef {string} EntityHostType
* @typedef {string} Entities.EntityHostType
*/
/**jsdoc
* Add a new entity with specified properties.
* Adds a new domain, avatar, or local entity.
* @function Entities.addEntity
* @param {Entities.EntityProperties} properties - The properties of the entity to create.
* @param {EntityHostType} [entityHostType="domain"] - If <code>"avatar"</code> the entity is created as an avatar entity. An avatar entity
* follows you to each domain you visit, rendering at the same world coordinates unless it's parented to your avatar.
* If <code>"local"</code>, the entity is created as a local entity, which will only render for you and isn't sent over the wire.
* Otherwise it is created as a normal entity and sent over the entity server.
* @param {Entities.EntityHostType} [entityHostType="domain"] - The type of entity to create.
* @returns {Uuid} The ID of the entity if successfully created, otherwise {@link Uuid(0)|Uuid.NULL}.
* @example <caption>Create a box entity in front of your avatar.</caption>
* @example <caption>Create a box domain entity in front of your avatar.</caption>
* var entityID = Entities.addEntity({
* type: "Box",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* dimensions: { x: 0.5, y: 0.5, z: 0.5 }
* dimensions: { x: 0.5, y: 0.5, z: 0.5 },
* lifetime: 300 // Delete after 5 minutes.
* });
* print("Entity created: " + entityID);
*/
@ -290,10 +298,13 @@ public slots:
}
/**jsdoc
* Add a new entity with specified properties.
* Adds a new avatar entity (<code>{@link Entities.EntityProperties|entityHostType}</code> property is
* <code>"avatar"</code>) or domain entity (<code>{@link Entities.EntityProperties|entityHostType}</code> property is
* <code>"domain"</code>).
* @function Entities.addEntity
* @param {Entities.EntityProperties} properties - The properties of the entity to create.
* @param {boolean} [avatarEntity=false] - Whether to create an avatar entity or a domain entity
* @param {boolean} [avatarEntity=false] - <code>true</code> to create an avatar entity, <code>false</code> to create a
* domain entity.
* @returns {Uuid} The ID of the entity if successfully created, otherwise {@link Uuid(0)|Uuid.NULL}.
*/
Q_INVOKABLE QUuid addEntity(const EntityItemProperties& properties, bool avatarEntity = false) {
@ -307,9 +318,13 @@ public slots:
bool collisionless, bool grabbable, const glm::vec3& position, const glm::vec3& gravity);
/**jsdoc
* Create a clone of an entity. A clone can be created by a client that doesn't have rez permissions in the current domain.
* The entity must have its <code>cloneable</code> property set to <code>true</code>. The clone has a modified name, other
* properties set per its clone related-properties, and its clone-related properties are set to defaults.
* Creates a clone of an entity. The clone has a modified <code>name</code> property, other properties set per the original
* entity's clone-related {@link Entities.EntityProperties|properties} (e.g., <code>cloneLifetime</code>), and
* clone-related properties set to defaults.
* <p>Domain entities must have their <code>cloneable</code> property value be <code>true</code> in order to be cloned. A
* domain entity can be cloned by a client that doesn't have rez permissions in the domain.</p>
* <p>Avatar entities must have their <code>cloneable</code> and <code>cloneAvatarEntity</code> property values be
* <code>true</code> in order to be cloned.</p>
* @function Entities.cloneEntity
* @param {Uuid} entityID - The ID of the entity to clone.
* @returns {Uuid} The ID of the new entity if successfully cloned, otherwise {@link Uuid(0)|Uuid.NULL}.
@ -317,18 +332,21 @@ public slots:
Q_INVOKABLE QUuid cloneEntity(const QUuid& entityID);
/**jsdoc
* Get the properties of an entity.
* Gets the properties of an entity.
* @function Entities.getEntityProperties
* @param {Uuid} entityID - The ID of the entity to get the properties of.
* @param {string[]} [desiredProperties=[]] - Array of the names of the properties to get. If the array is empty,
* all properties are returned.
* @param {string|string[]} [desiredProperties=[]] - The names of the properties to get. For properties that are objects
* (e.g., the <code>"keyLight"</code> property), use the property and subproperty names in dot notation (e.g.,
* <code>"keyLight.color"</code>).
* @returns {Entities.EntityProperties} The properties of the entity if the entity can be found, otherwise an empty object.
* If no properties are specified, then all properties are returned.
* @example <caption>Report the color of a new box entity.</caption>
* var entityID = Entities.addEntity({
* type: "Box",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* dimensions: { x: 0.5, y: 0.5, z: 0.5 }
* dimensions: { x: 0.5, y: 0.5, z: 0.5 },
* lifetime: 300 // Delete after 5 minutes.
* });
* var properties = Entities.getEntityProperties(entityID, ["color"]);
* print("Entity color: " + JSON.stringify(properties.color));
@ -337,17 +355,18 @@ public slots:
Q_INVOKABLE EntityItemProperties getEntityProperties(const QUuid& entityID, EntityPropertyFlags desiredProperties);
/**jsdoc
* Update an entity with specified properties.
* Edits an entity, changing one or more of its properties.
* @function Entities.editEntity
* @param {Uuid} entityID - The ID of the entity to edit.
* @param {Entities.EntityProperties} properties - The properties to update the entity with.
* @returns {Uuid} The ID of the entity if the edit was successful, otherwise <code>null</code>.
* @param {Entities.EntityProperties} properties - The new property values.
* @returns {Uuid} The ID of the entity if the edit was successful, otherwise <code>null</code> or {@link Uuid|Uuid.NULL}.
* @example <caption>Change the color of an entity.</caption>
* var entityID = Entities.addEntity({
* type: "Box",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* rotation: MyAvatar.orientation,
* dimensions: { x: 0.5, y: 0.5, z: 0.5 }
* dimensions: { x: 0.5, y: 0.5, z: 0.5 },
* lifetime: 300 // Delete after 5 minutes.
* });
* var properties = Entities.getEntityProperties(entityID, ["color"]);
* print("Entity color: " + JSON.stringify(properties.color));
@ -361,7 +380,7 @@ public slots:
Q_INVOKABLE QUuid editEntity(const QUuid& entityID, const EntityItemProperties& properties);
/**jsdoc
* Delete an entity.
* Deletes an entity.
* @function Entities.deleteEntity
* @param {Uuid} entityID - The ID of the entity to delete.
* @example <caption>Delete an entity a few seconds after creating it.</caption>
@ -379,9 +398,10 @@ public slots:
Q_INVOKABLE void deleteEntity(const QUuid& entityID);
/**jsdoc
* Get an entities type as a string.
* @function Entities.deleteEntity
* @param {Uuid} id - The id of the entity to get the type of.
* Gets an entity's type.
* @function Entities.getEntityType
* @param {Uuid} id - The ID of the entity to get the type of.
* @returns {Entities.EntityType} The type of the entity.
*/
Q_INVOKABLE QString getEntityType(const QUuid& entityID);
@ -1436,14 +1456,14 @@ public slots:
Q_INVOKABLE QString getNestableType(const QUuid& id);
/**jsdoc
* Get the ID of the {@link Entities.EntityType|Web} entity that has keyboard focus.
* Gets the ID of the {@link Entities.EntityType|Web} entity that has keyboard focus.
* @function Entities.getKeyboardFocusEntity
* @returns {Uuid} The ID of the {@link Entities.EntityType|Web} entity that has focus, if any, otherwise <code>null</code>.
*/
Q_INVOKABLE QUuid getKeyboardFocusEntity() const;
/**jsdoc
* Set the {@link Entities.EntityType|Web} entity that has keyboard focus.
* Sets the {@link Entities.EntityType|Web} entity that has keyboard focus.
* @function Entities.setKeyboardFocusEntity
* @param {Uuid} id - The ID of the {@link Entities.EntityType|Web} entity to set keyboard focus to. Use
* <code>null</code> or {@link Uuid(0)|Uuid.NULL} to unset keyboard focus from an entity.

8
libraries/entities/src/EntityTypes.h
View file

@ -42,6 +42,9 @@ public:
* <tr><th>Value</th><th>Description</th><th>Properties</th></tr>
* </thead>
* <tbody>
* <tr><td><code>"Shape"</code></td><td>A basic entity such as a cube.
* See also, the <code>"Box"</code> and <code>"Sphere"</code> entity types.</td>
* <td>{@link Entities.EntityProperties-Shape|EntityProperties-Shape}</td></tr>
* <tr><td><code>"Box"</code></td><td>A rectangular prism. This is a synonym of <code>"Shape"</code> for the case
* where the entity's <code>shape</code> property value is <code>"Cube"</code>.<br />
* If an entity is created with its <code>type</code>
@ -56,9 +59,6 @@ public:
* <code>"Sphere"</code>. If an entity of type <code>Box</code> or <code>Shape</code> has its <code>shape</code> set
* to <code>"Sphere"</code> then its <code>type</code> will be reported as <code>"Sphere"</code>.
* <td>{@link Entities.EntityProperties-Sphere|EntityProperties-Sphere}</td></tr>
* <tr><td><code>"Shape"</code></td><td>A basic entity such as a cube.
* See also, the <code>"Box"</code> and <code>"Sphere"</code> entity types.</td>
* <td>{@link Entities.EntityProperties-Shape|EntityProperties-Shape}</td></tr>
* <tr><td><code>"Model"</code></td><td>A mesh model from an FBX or OBJ file.</td>
* <td>{@link Entities.EntityProperties-Model|EntityProperties-Model}</td></tr>
* <tr><td><code>"Text"</code></td><td>A pane of text oriented in space.</td>
@ -78,7 +78,7 @@ public:
* <td>{@link Entities.EntityProperties-PolyVox|EntityProperties-PolyVox}</td></tr>
* <tr><td><code>"Grid"</code></td><td>A grid of lines in a plane.</td>
* <td>{@link Entities.EntityProperties-Grid|EntityProperties-Grid}</td></tr>
* <tr><td><code>"Gizmo"</code></td><td>An entity with various UI-related properties.</td>
* <tr><td><code>"Gizmo"</code></td><td>A gizmo intended for UI.</td>
* <td>{@link Entities.EntityProperties-Gizmo|EntityProperties-Gizmo}</td></tr>
* <tr><td><code>"Light"</code></td><td>A local lighting effect.</td>
* <td>{@link Entities.EntityProperties-Light|EntityProperties-Light}</td></tr>

31
libraries/entities/src/GrabPropertyGroup.h
View file

@ -41,35 +41,30 @@ static const glm::vec3 INITIAL_EQUIPPABLE_INDICATOR_OFFSET { glm::vec3(0.0f) };
/**jsdoc
* Grab is defined by the following properties.
* Grabbing behavior is defined by the following properties:
*
* @typedef {object} Entities.Grab
*
* @property {boolean} grabbable=true - If <code>true</code> the entity can be grabbed.
* @property {boolean} grabKinematic=true - If <code>true</code> the entity is updated in a kinematic manner.
* If <code>false</code> it will be grabbed using a tractor action. A kinematic grab will make the item appear more
* tightly held, but will cause it to behave poorly when interacting with dynamic entities.
* @property {boolean} grabFollowsController=true - If <code>true</code> the entity will follow the motions of the
* hand-controller even if the avatar's hand can't get to the implied position. This should be <code>true</code>
* for tools, pens, etc and false for things meant to decorate the hand.
*
* @property {boolean} triggerable=false - If <code>true</code> the entity will receive calls to trigger
* @property {boolean} grabbable=true - If <code>true</code> then the entity can be grabbed.
* @property {boolean} grabKinematic=true - If <code>true</code> then the entity will be updated in a kinematic manner when
* grabbed; if <code>false</code> it will be grabbed using a tractor action. A kinematic grab will make the item appear
* more tightly held but will cause it to behave poorly when interacting with dynamic entities.
* @property {boolean} grabFollowsController=true - If <code>true</code> then the entity will follow the motions of the hand
* controller even if the avatar's hand can't get to the implied position. This should be set <code>true</code> for tools,
* pens, etc. and <code>false</code> for things meant to decorate the hand.
* @property {boolean} triggerable=false - If <code>true</code> then the entity will receive calls to trigger
* {@link Controller|Controller entity methods}.
*
* @property {boolean} equippable=true - If <code>true</code> the entity can be equipped.
* @property {boolean} equippable=true - If <code>true</code> then the entity can be equipped.
* @property {Vec3} equippableLeftPosition=0,0,0 - Positional offset from the left hand, when equipped.
* @property {Quat} equippableLeftRotation=0,0,0,1 - Rotational offset from the left hand, when equipped.
* @property {Vec3} equippableRightPosition=0,0,0 - Positional offset from the right hand, when equipped.
* @property {Quat} equippableRightRotation=0,0,0,1 - Rotational offset from the right hand, when equipped.
*
* @property {string} equippableIndicatorURL="" - If non-empty, this model will be used to indicate that an
* entity is equippable, rather than the default.
* @property {Vec3} equippableIndicatorScale=1,1,1 - If equippableIndicatorURL is non-empty, this controls the
* @property {Vec3} equippableIndicatorScale=1,1,1 - If <code>equippableIndicatorURL</code> is non-empty, this controls the
scale of the displayed indicator.
* @property {Vec3} equippableIndicatorOffset=0,0,0 - If equippableIndicatorURL is non-empty, this controls the
* @property {Vec3} equippableIndicatorOffset=0,0,0 - If <code>equippableIndicatorURL</code> is non-empty, this controls the
relative offset of the displayed object from the equippable entity.
*/
class GrabPropertyGroup : public PropertyGroup {
public:
// EntityItemProperty related helpers

12
libraries/entities/src/HazePropertyGroup.h
View file

@ -43,7 +43,7 @@ static const float INITIAL_KEY_LIGHT_ALTITUDE{ 200.0f };
// FIXME: Document hazeAttenuationKeyLight, hazeKeyLightRange, and hazeKeyLightAltitude once they're working and are provided
// in the Create app's UI.
/**jsdoc
* Haze is defined by the following properties.
* Haze is defined by the following properties:
* @typedef {object} Entities.Haze
*
* @property {number} hazeRange=1000 - The horizontal distance at which visibility is reduced to 95%; i.e., 95% of each pixel's
@ -56,7 +56,7 @@ static const float INITIAL_KEY_LIGHT_ALTITUDE{ 200.0f };
* haze color are blended 50/50.
*
* @property {boolean} hazeAltitudeEffect=false - If <code>true</code> then haze decreases with altitude as defined by the
* entity's local coordinate system; <code>hazeBaseRef</code> and </code>hazeCeiling</code> are used.
* entity's local coordinate system; <code>hazeBaseRef</code> and <code>hazeCeiling</code> are used.
* @property {number} hazeBaseRef=0 - The y-axis value in the entity's local coordinate system at which the haze density starts
* reducing with altitude.
* @property {number} hazeCeiling=200 - The y-axis value in the entity's local coordinate system at which the haze density has
@ -65,9 +65,11 @@ static const float INITIAL_KEY_LIGHT_ALTITUDE{ 200.0f };
* @property {number} hazeBackgroundBlend=0 - The proportion of the skybox image to show through the haze: <code>0.0</code>
* displays no skybox image; <code>1.0</code> displays no haze.
*
* @property {boolean} hazeAttenuateKeyLight=false - <em>Currently not supported.</em>
* @property {number} hazeKeyLightRange=1000 - <em>Currently not supported.</em>
* @property {number} hazeKeyLightAltitude=200 - <em>Currently not supported.</em>
* @property {boolean} hazeAttenuateKeyLight=false - If <code>true</code> then the haze attenuates the key light;
* <code>hazeKeyLightRange</code> and <code>hazeKeyLightAltitude</code> are used.
* @property {number} hazeKeyLightRange=1000 - The distance at which the haze attenuates the key light by 95%.
* @property {number} hazeKeyLightAltitude=200 - The altitude at which the haze starts attenuating the key light (i.e., the
* altitude at which the distance starts being calculated).
*/
class HazePropertyGroup : public PropertyGroup {
public:

2
libraries/entities/src/KeyLightPropertyGroup.h
View file

@ -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.

2
libraries/entities/src/PolyVoxEntityItem.h
View file

@ -63,7 +63,7 @@ class PolyVoxEntityItem : public EntityItem {
virtual int getOnCount() const { return 0; }
/**jsdoc
* <p>A <code>PolyVoxSurfaceStyle</code> may be one of the following:</p>
* <p>The surface of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity may be one of the following styles:</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Type</th><th>Description</th></tr>

8
libraries/entities/src/PulsePropertyGroup.h
View file

@ -26,19 +26,17 @@ class OctreePacketData;
class ReadBitstreamToTreeParams;
/**jsdoc
* Pulse is defined by the following properties.
* A color and alpha pulse that an entity may have.
* @typedef {object} Entities.Pulse
*
* @property {number} min=0 - The minimum value of the pulse multiplier.
* @property {number} max=1 - The maximum value of the pulse multiplier.
* @property {number} period=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from
* <code>min</code> to <code>max</code>, then <code>max</code> to <code>min</code> in one period.
* @property {PulseMode} colorMode="none" - If "in", the color is pulsed in phase with the pulse period; if "out"
* @property {Entities.PulseMode} colorMode="none" - If "in", the color is pulsed in phase with the pulse period; if "out"
* the color is pulsed out of phase with the pulse period.
* @property {PulseMode} alphaMode="none" - If "in", the alpha is pulsed in phase with the pulse period; if "out"
* @property {Entities.PulseMode} alphaMode="none" - If "in", the alpha is pulsed in phase with the pulse period; if "out"
* the alpha is pulsed out of phase with the pulse period.
*/
class PulsePropertyGroup : public PropertyGroup {
public:
// EntityItemProperty related helpers

43
libraries/entities/src/RingGizmoPropertyGroup.h
View file

@ -25,31 +25,32 @@ class ReadBitstreamToTreeParams;
using u8vec3Color = glm::u8vec3;
/**jsdoc
* A RingGizmo is defined by the following properties.
* A {@link Entities.EntityProperties-Gizmo|ring Gizmo} entity is defined by the following properties:
* @typedef {object} Entities.RingGizmo
*
* @property {number} startAngle=0 - The angle at which the ring will start, in degrees.
* @property {number} endAngle=360 - The angle at which the ring will end, in degrees.
* @property {number} innerRadius=0 - The inner radius of the ring as a fraction of the total radius. 0-1.
* @property {number} startAngle=0 - The angle at which the ring starts, in degrees.
* @property {number} endAngle=360 - The angle at which the ring ends, in degrees.
* @property {number} innerRadius=0 - The inner radius of the ring as a fraction of the total radius, range <code>0.0</code>
* &mdash; <code>1.0</code>.
* @property {Color} innerStartColor - The color at the inner start point of the ring.
* @property {Color} innerEndColor - The color at the inner end point of the ring.
* @property {Color} outerStartColor - The color at the outer start point of the ring.
* @property {Color} outerEndColor - The color at the outer end point of the ring.
* @property {number} innerStartAlpha=1 - The alpha at the inner start point of the ring.
* @property {number} innerEndAlpha=1 - The alpha at the inner end point of the ring.
* @property {number} outerStartAlpha=1 - The alpha at the outer start point of the ring.
* @property {number} outerEndAlpha=1 - The alpha at the outer end point of the ring.
* @property {Color} innerStartColor=255,255,255 - The color at the inner start point of the ring.
* @property {Color} innerEndColor=255,255,255 - The color at the inner end point of the ring.
* @property {Color} outerStartColor=255,255,255 - The color at the outer start point of the ring.
* @property {Color} outerEndColor=255,255,255 - The color at the outer end point of the ring.
* @property {number} innerStartAlpha=1 - The opacity at the inner start point of the ring.
* @property {number} innerEndAlpha=1 - The opacity at the inner end point of the ring.
* @property {number} outerStartAlpha=1 - The opacity at the outer start point of the ring.
* @property {number} outerEndAlpha=1 - The opacity at the outer end point of the ring.
* @property {boolean} hasTickMarks=false - Whether or not to render tick marks.
* @property {number} majorTickMarksAngle - The angle between major tick marks, in degrees.
* @property {number} minorTickMarksAngle - The angle between minor tick marks, in degrees.
* @property {number} majorTickMarksLength - The length of the major tick marks, as a fraction of the radius. A positive value draws tick marks
* outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.
* @property {number} minorTickMarksLength - The length of the minor tick marks, as a fraction of the radius. A positive value draws tick marks
* outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.
* @property {Color} majorTickMarksColor - The color of the major tick marks.
* @property {Color} minorTickMarksColor - The color of the minor tick marks.
* @property {boolean} hasTickMarks=false - <code>true</code> to render tick marks, otherwise <code>false</code>.
* @property {number} majorTickMarksAngle=0 - The angle between major tick marks, in degrees.
* @property {number} minorTickMarksAngle=0 - The angle between minor tick marks, in degrees.
* @property {number} majorTickMarksLength=0 - The length of the major tick marks as a fraction of the radius. A positive value
* draws tick marks outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.
* @property {number} minorTickMarksLength=0 - The length of the minor tick marks, as a fraction of the radius. A positive
* value draws tick marks outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.
* @property {Color} majorTickMarksColor=255,255,255 - The color of the major tick marks.
* @property {Color} minorTickMarksColor=255,255,255 - The color of the minor tick marks.
*/
class RingGizmoPropertyGroup : public PropertyGroup {

4
libraries/entities/src/ShapeEntityItem.cpp
View file

@ -22,8 +22,8 @@
namespace entity {
/**jsdoc
* <p>A <code>Shape</code>, <code>Box</code>, or <code>Sphere</code> {@link Entities.EntityType|EntityType} may display as
* one of the following geometrical shapes:</p>
* <p>A <code>"Shape"</code>, <code>"Box"</code>, or <code>"Sphere"</code> {@link Entities.EntityType|EntityType} may
* display as one of the following geometrical shapes:</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Dimensions</th><th>Notes</th></tr>

2
libraries/entities/src/SkyboxPropertyGroup.h
View file

@ -30,7 +30,7 @@ class EntityTreeElementExtraEncodeData;
class ReadBitstreamToTreeParams;
/**jsdoc
* A skybox is defined by the following properties.
* A skybox is defined by the following properties:
* @typedef {object} Entities.Skybox
* @property {Color} color=0,0,0 - Sets the color of the sky if <code>url</code> is <code>""</code>, otherwise modifies the
* color of the cube map image.

121
libraries/material-networking/src/material-networking/MaterialCache.cpp
View file

@ -70,10 +70,10 @@ bool NetworkMaterialResource::parseJSONColor(const QJsonValue& array, glm::vec3&
}
/**jsdoc
* A material or set of materials such as may be used by a {@link Entities.EntityType|Material} entity.
* @typedef {object} MaterialResource
* A material or set of materials used by a {@link Entities.EntityType|Material entity}.
* @typedef {object} Entities.MaterialResource
* @property {number} materialVersion=1 - The version of the material. <em>Currently not used.</em>
* @property {Material|Material[]} materials - The details of the material or materials.
* @property {Entities.Material|Entities.Material[]} materials - The details of the material or materials.
*/
NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMaterials(const QJsonDocument& materialJSON, const QUrl& baseUrl) {
ParsedMaterials toReturn;
@ -109,60 +109,71 @@ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMater
}
/**jsdoc
* A material such as may be used by a {@link Entities.EntityType|Material} entity.
* @typedef {object} Material
* A material used in a {@link Entities.MaterialResource|MaterialResource}.
* @typedef {object} Entities.Material
* @property {string} model="hifi_pbr" - Different material models support different properties and rendering modes.
* Supported models are: "hifi_pbr"
* Supported models are: <code>"hifi_pbr"</code>.
* @property {string} name="" - A name for the material. Supported by all material models.
* @property {Color|RGBS|string} emissive - The emissive color, i.e., the color that the material emits. A {@link Color} value
* is treated as sRGB. A {@link RGBS} value can be either RGB or sRGB. Set to <code>"fallthrough"</code> to fallthrough to
* the material below. "hifi_pbr" model only.
* @property {number|string} opacity=1.0 - The opacity, <code>0.0</code> &ndash; <code>1.0</code>. Set to <code>"fallthrough"</code> to fallthrough to
* the material below. "hifi_pbr" model only.
* @property {boolean|string} unlit=false - If <code>true</code>, the material is not lit. Set to <code>"fallthrough"</code> to fallthrough to
* the material below. "hifi_pbr" model only.
* is treated as sRGB. A {@link RGBS} value can be either RGB or sRGB.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {number|string} opacity=1.0 - The opacity, range <code>0.0</code> &ndash; <code>1.0</code>.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {boolean|string} unlit=false - If <code>true</code>, the material is not lit, otherwise it is.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {Color|RGBS|string} albedo - The albedo color. A {@link Color} value is treated as sRGB. A {@link RGBS} value can
* be either RGB or sRGB. Set to <code>"fallthrough"</code> to fallthrough to the material below. Set to <code>"fallthrough"</code> to fallthrough to
* the material below. "hifi_pbr" model only.
* @property {number|string} roughness - The roughness, <code>0.0</code> &ndash; <code>1.0</code>. Set to <code>"fallthrough"</code> to fallthrough to
* the material below. "hifi_pbr" model only.
* @property {number|string} metallic - The metallicness, <code>0.0</code> &ndash; <code>1.0</code>. Set to <code>"fallthrough"</code> to fallthrough to
* the material below. "hifi_pbr" model only.
* @property {number|string} scattering - The scattering, <code>0.0</code> &ndash; <code>1.0</code>. Set to <code>"fallthrough"</code> to fallthrough to
* the material below. "hifi_pbr" model only.
* @property {string} emissiveMap - URL of emissive texture image. Set to <code>"fallthrough"</code> to fallthrough to
* the material below. "hifi_pbr" model only.
* @property {string} albedoMap - URL of albedo texture image. Set to <code>"fallthrough"</code> to fallthrough to
* the material below. "hifi_pbr" model only.
* @property {string} opacityMap - URL of opacity texture image. Set value the same as the <code>albedoMap</code> value for
* transparency. "hifi_pbr" model only.
* @property {string} roughnessMap - URL of roughness texture image. Can use this or <code>glossMap</code>, but not both. Set to <code>"fallthrough"</code>
* to fallthrough to the material below. "hifi_pbr" model only.
* @property {string} glossMap - URL of gloss texture image. Can use this or <code>roughnessMap</code>, but not both. Set to <code>"fallthrough"</code>
* to fallthrough to the material below. "hifi_pbr" model only.
* @property {string} metallicMap - URL of metallic texture image. Can use this or <code>specularMap</code>, but not both. Set to <code>"fallthrough"</code>
* to fallthrough to the material below. "hifi_pbr" model only.
* @property {string} specularMap - URL of specular texture image. Can use this or <code>metallicMap</code>, but not both. Set to <code>"fallthrough"</code>
* to fallthrough to the material below. "hifi_pbr" model only.
* @property {string} normalMap - URL of normal texture image. Can use this or <code>bumpMap</code>, but not both. Set to <code>"fallthrough"</code>
* to fallthrough to the material below. "hifi_pbr" model only.
* @property {string} bumpMap - URL of bump texture image. Can use this or <code>normalMap</code>, but not both. Set to <code>"fallthrough"</code>
* to fallthrough to the material below. "hifi_pbr" model only.
* @property {string} occlusionMap - URL of occlusion texture image. Set to <code>"fallthrough"</code> to fallthrough to the material below. "hifi_pbr" model only.
* @property {string} scatteringMap - URL of scattering texture image. Only used if <code>normalMap</code> or
* <code>bumpMap</code> is specified. Set to <code>"fallthrough"</code> to fallthrough to the material below. "hifi_pbr" model only.
* @property {string} lightMap - URL of light map texture image. <em>Currently not used.</em>. Set to <code>"fallthrough"</code>
* to fallthrough to the material below. "hifi_pbr" model only.
* @property {string} texCoordTransform0 - The transform to use for all of the maps besides occlusionMap and lightMap. Currently unused. Set to
* <code>"fallthrough"</code> to fallthrough to the material below. "hifi_pbr" model only.
* @property {string} texCoordTransform1 - The transform to use for occlusionMap and lightMap. Currently unused. Set to <code>"fallthrough"</code>
* to fallthrough to the material below. "hifi_pbr" model only.
* @property {string} lightmapParams - Parameters for controlling how lightMap is used. Currently unused. Set to <code>"fallthrough"</code>
* to fallthrough to the material below. "hifi_pbr" model only.
* @property {string} materialParams - Parameters for controlling the material projection and repition. Currently unused. Set to <code>"fallthrough"</code>
* to fallthrough to the material below. "hifi_pbr" model only.
* @property {bool} defaultFallthrough=false - If <code>true</code>, all properties will fallthrough to the material below unless they are set. If
* <code>false</code>, they will respect the individual properties' fallthrough state. "hifi_pbr" model only.
* be either RGB or sRGB.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {number|string} roughness - The roughness, range <code>0.0</code> &ndash; <code>1.0</code>.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {number|string} metallic - The metallicness, range <code>0.0</code> &ndash; <code>1.0</code>.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {number|string} scattering - The scattering, range <code>0.0</code> &ndash; <code>1.0</code>.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {string} emissiveMap - The URL of the emissive texture image.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {string} albedoMap - The URL of the albedo texture image.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {string} opacityMap - The URL of the opacity texture image. Set the value the same as the <code>albedoMap</code>
* value for transparency.
* <code>"hifi_pbr"</code> model only.
* @property {string} roughnessMap - The URL of the roughness texture image. You can use this or <code>glossMap</code>, but not
* both.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {string} glossMap - The URL of the gloss texture image. You can use this or <code>roughnessMap</code>, but not
* both.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {string} metallicMap - The URL of the metallic texture image. You can use this or <code>specularMap</code>, but
* not both.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {string} specularMap - The URL of the specular texture image. You can use this or <code>metallicMap</code>, but
* not both.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {string} normalMap - The URL of the normal texture image. You can use this or <code>bumpMap</code>, but not both.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {string} bumpMap - The URL of the bump texture image. You can use this or <code>normalMap</code>, but not both.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {string} occlusionMap - The URL of the occlusion texture image.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {string} scatteringMap - The URL of the scattering texture image. Only used if <code>normalMap</code> or
* <code>bumpMap</code> is specified.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {string} lightMap - The URL of the light map texture image.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {Mat4|string} texCoordTransform0 - The transform to use for all of the maps apart from <code>occlusionMap</code>
* and <code>lightMap</code>.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {Mat4|string} texCoordTransform1 - The transform to use for <code>occlusionMap</code> and <code>lightMap</code>.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {string} lightmapParams - Parameters for controlling how lightMap is used.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* <p><em>Currently not used.</em></p>
* @property {string} materialParams - Parameters for controlling the material projection and repetition.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* <p><em>Currently not used.</em></p>
* @property {boolean} defaultFallthrough=false - If <code>true</code>, all properties fall through to the material below
* unless they are set. If <code>false</code>, they respect their individual fall-through setting. <code>"hifi_pbr"</code>
* model only.
*/
// Note: See MaterialEntityItem.h for default values used in practice.
std::pair<std::string, std::shared_ptr<NetworkMaterial>> NetworkMaterialResource::parseJSONMaterial(const QJsonObject& materialJSON, const QUrl& baseUrl) {
@ -399,7 +410,7 @@ std::pair<std::string, std::shared_ptr<NetworkMaterial>> NetworkMaterialResource
material->setPropertyDoesFallthrough(graphics::Material::ExtraFlagBit::LIGHTMAP_PARAMS);
}
}
// TODO: implement lightmapParams
// TODO: implement lightmapParams and update JSDoc
} else if (key == "materialParams") {
auto value = materialJSON.value(key);
if (value.isString()) {
@ -408,7 +419,7 @@ std::pair<std::string, std::shared_ptr<NetworkMaterial>> NetworkMaterialResource
material->setPropertyDoesFallthrough(graphics::Material::ExtraFlagBit::MATERIAL_PARAMS);
}
}
// TODO: implement materialParams
// TODO: implement materialParams and update JSDoc
} else if (key == "defaultFallthrough") {
auto value = materialJSON.value(key);
if (value.isBool()) {

2
libraries/shared/src/BillboardMode.h
View file

@ -21,7 +21,7 @@
* <tr><td><code>"none"</code></td><td>The entity will not be billboarded.</td></tr>
* <tr><td><code>"yaw"</code></td><td>The entity will yaw, but not pitch, to face the camera. Its actual rotation will be
* ignored.</td></tr>
* <tr><td><code>"full"</code></td><td>The entity will be billboarded to face the camera. Its actual rotation will be
* <tr><td><code>"full"</code></td><td>The entity will yaw and pitch to face the camera. Its actual rotation will be
* ignored.</td></tr>
* </tbody>
* </table>

30
libraries/shared/src/ComponentMode.cpp
View file

@ -8,6 +8,22 @@
#include "ComponentMode.h"
/**jsdoc
* <p>How an effect is applied in a {@link Entities.EntityProperties-Zone|Zone} entity.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>"inherit"</code></td><td>The effect from any enclosing zone continues into this zone.</td></tr>
* <tr><td><code>"disabled"</code></td><td>The effect &mdash; from any enclosing zone and this zone &mdash; is disabled in
* this zone.</td></tr>
* <tr><td><code>"enabled"</code></td><td>The effect from this zone is enabled, overriding the effect from any enclosing
* zone.</td></tr>
* </tbody>
* </table>
* @typedef {string} Entities.ComponentMode
*/
const char* componentModeNames[] = {
"inherit",
"disabled",
@ -22,6 +38,20 @@ QString ComponentModeHelpers::getNameForComponentMode(ComponentMode mode) {
return componentModeNames[(int)mode];
}
/**jsdoc
* <p>The priority of updates from avatars in a zone to other clients.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>"inherit"</code></td><td>The update priority from any enclosing zone continues into this zone.</td></tr>
* <tr><td><code>"crowd"</code></td><td>The update priority in this zone is the normal priority.</td></tr>
* <tr><td><code>"hero"</code></td><td>Avatars in this zone have an increased update priority.</td></tr>
* </tbody>
* </table>
* @typedef {string} Entities.AvatarPriorityMode
*/
const char* avatarPriorityModeNames[] = {
"inherit",
"crowd",

6
libraries/shared/src/GizmoType.h
View file

@ -12,16 +12,16 @@
#include "QString"
/**jsdoc
* <p>Controls how the Gizmo behaves and renders</p>
* <p>A {@link Entities.EntityProperties-Gizmo|Gizmo} entity may be one of the following types:</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>ring</code></td><td>A ring gizmo.</td></tr>
* <tr><td><code>"ring"</code></td><td>A ring gizmo.</td></tr>
* </tbody>
* </table>
* @typedef {string} GizmoType
* @typedef {string} Entities.GizmoType
*/
enum GizmoType {

8
libraries/shared/src/PrimitiveMode.h
View file

@ -12,17 +12,17 @@
#include "QString"
/**jsdoc
* <p>How the geometry of the entity is rendered.</p>
* <p>How the geometry of an entity is rendered.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>solid</code></td><td>The entity will be drawn as a solid shape.</td></tr>
* <tr><td><code>lines</code></td><td>The entity will be drawn as wireframe.</td></tr>
* <tr><td><code>"solid"</code></td><td>The entity is drawn as a solid shape.</td></tr>
* <tr><td><code>"lines"</code></td><td>The entity is drawn as wireframe.</td></tr>
* </tbody>
* </table>
* @typedef {string} PrimitiveMode
* @typedef {string} Entities.PrimitiveMode
*/
enum class PrimitiveMode {

8
libraries/shared/src/PulseMode.h
View file

@ -18,12 +18,12 @@
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>none</code></td><td>No pulsing.</td></tr>
* <tr><td><code>in</code></td><td>Pulse in phase with the pulse period.</td></tr>
* <tr><td><code>out</code></td><td>Pulse out of phase with the pulse period.</td></tr>
* <tr><td><code>"none"</code></td><td>No pulsing.</td></tr>
* <tr><td><code>"in"</code></td><td>Pulse in phase with the pulse period.</td></tr>
* <tr><td><code>"out"</code></td><td>Pulse out of phase with the pulse period.</td></tr>
* </tbody>
* </table>
* @typedef {string} PulseMode
* @typedef {string} Entities.PulseMode
*/
enum class PulseMode {

2
libraries/shared/src/RegisteredMetaTypes.h
View file

@ -141,7 +141,7 @@ glm::vec3 vec3FromVariant(const QVariant &object);
* Entities.editEntity(<id>, { color: "#00FF00"}); // { red: 0, green: 255, blue: 0 }
*/
/**jsdoc
* A color vector. See also the {@link Vec3(0)|Vec3} object.
* A color vector with real values. Values may also be <code>null</code>. See also the {@link Vec3(0)|Vec3} object.
*
* @typedef {object} ColorFloat
* @property {number} red - Red component value. Real in the range <code>0</code> - <code>255</code>. Synonyms: <code>r</code>, <code>x</code>.

10
libraries/shared/src/RenderLayer.h
View file

@ -12,18 +12,18 @@
#include "QString"
/**jsdoc
* <p>In which layer an entity is rendered.</p>
* <p>A layer in which an entity may be rendered.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>world</code></td><td>The entity will be drawn in the world with everything else.</td></tr>
* <tr><td><code>front</code></td><td>The entity will be drawn on top of the world layer, but behind the HUD sphere.</td></tr>
* <tr><td><code>hud</code></td><td>The entity will be drawn on top of other layers and the HUD sphere.</td></tr>
* <tr><td><code>"world"</code></td><td>The entity is drawn in the world with everything else.</td></tr>
* <tr><td><code>"front"</code></td><td>The entity is drawn on top of the world layer but behind the HUD sphere.</td></tr>
* <tr><td><code>"hud"</code></td><td>The entity is drawn on top of other layers and the HUD sphere.</td></tr>
* </tbody>
* </table>
* @typedef {string} RenderLayer
* @typedef {string} Entities.RenderLayer
*/
enum class RenderLayer {

2
libraries/shared/src/ShapeInfo.cpp
View file

@ -17,7 +17,7 @@
#include "NumericalConstants.h" // for MILLIMETERS_PER_METER
/**jsdoc
* <p>A ShapeType defines the shape used for collisions or zones.</p>
* <p>Defines the shape used for collisions or zones.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>

6
libraries/shared/src/WebInputMode.h
View file

@ -12,14 +12,14 @@
#include "QString"
/**jsdoc
* <p>Controls how the web surface processed PointerEvents</p>
* <p>Specifies how a web surface processes events.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>touch</code></td><td>Events are processed as touch events.</td></tr>
* <tr><td><code>mouse</code></td><td>Events are processed as mouse events.</td></tr>
* <tr><td><code>"touch"</code></td><td>Events are processed as touch events.</td></tr>
* <tr><td><code>"mouse"</code></td><td>Events are processed as mouse events.</td></tr>
* </tbody>
* </table>
* @typedef {string} WebInputMode