//// EntityItemPropertiesDocs.cpp// libraries/entities/src//// Created by HifiExperiments on 7/24/24.// Copyright 2024 Overte e.V.//// Distributed under the Apache License, Version 2.0.// See the accompanying file LICENSE or http://www.apache.org/licenses/LICENSE-2.0.html// SPDX-License-Identifier: Apache-2.0// /*@jsdoc * Different entity types have different properties: some common to all entities (listed in the table) and some specific to * each {@link Entities.EntityType|EntityType} (linked to below). * * @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'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.NONE - The session ID of the owning avatar if <code>avatarEntity</code> is * <code>true</code>, otherwise {@link Uuid(0)|Uuid.NONE}. <em>Read-only.</em> * * @property {number} created - When the entity was created, expressed as the number of microseconds since * 1970-01-01T00:00:00 UTC. <em>Read-only.</em> * @property {number} age - The age of the entity in seconds since it was created. <em>Read-only.</em> * @property {string} ageAsText - The age of the entity since it was created, formatted as <code>h hours m minutes s * seconds</code>. * @property {number} lifetime=-1 - How long an entity lives for, in seconds, before being automatically deleted. A value of * <code>-1</code> means that the entity lives for ever. * @property {number} lastEdited - When the entity was last edited, expressed as the number of microseconds since * 1970-01-01T00:00:00 UTC. <em>Read-only.</em> * @property {Uuid} lastEditedBy - The session ID of the avatar or agent that most recently created or edited the entity. * <em>Read-only.</em> * * @property {boolean} locked=false - <code>true</code> if properties other than <code>locked</code> cannot be changed and the * entity cannot be deleted, <code>false</code> if all properties can be changed and the entity can be deleted. * @property {boolean} visible=true - <code>true</code> if the entity is rendered, <code>false</code> if it isn't. * @property {boolean} canCastShadow=true - <code>true</code> if the entity can cast a shadow, <code>false</code> if it can't. * Currently applicable only to {@link Entities.EntityProperties-Model|Model} and * {@link Entities.EntityProperties-Shape|Shape} entities. Shadows are cast if inside a * {@link Entities.EntityProperties-Zone|Zone} entity with <code>castShadows</code> enabled in its <code>keyLight</code> * property. * @property {boolean} isVisibleInSecondaryCamera=true - <code>true</code> if the entity is rendered in the secondary camera, * <code>false</code> if it isn't. * @property {Entities.RenderLayer} renderLayer="world" - The layer that 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. * * @property {Vec3} position=0,0,0 - The position of the entity in world coordinates. * @property {Quat} rotation=0,0,0,1 - The orientation of the entity in world coordinates. * @property {Vec3} registrationPoint=0.5,0.5,0.5 - The point in the entity that is set to the entity's position and is rotated * about, range {@link Vec3(0)|Vec3.ZERO} – {@link Vec3(0)|Vec3.ONE}. A value of {@link Vec3(0)|Vec3.ZERO} is the * entity's minimum x, y, z corner; a value of {@link Vec3(0)|Vec3.ONE} is the entity's maximum x, y, z corner. * * @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> * @property {Vec3} naturalDimensions - The dimensions of the entity's unscaled mesh model or image if it has one, otherwise * {@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 the linear velocity of an entity slows down over time, range * <code>0.0</code> – <code>1.0</code>. A higher damping value slows down the entity more quickly. The default value * is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to <code>1/e = 0.368</code> * of its initial value. * @property {Vec3} angularVelocity=0,0,0 - The angular velocity of the entity in rad/s with respect to its axes, about its * registration point. * @property {number} angularDamping=0.39347 - How much the angular velocity of an entity slows down over time, range * <code>0.0</code> – <code>1.0</code>. A higher damping value slows down the entity more quickly. The default value * is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to <code>1/e = 0.368</code> * of its initial value. * * @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. 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>. * <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 - The current, measured acceleration of the entity, in m/s<sup>2</sup>. * <p class="important">Deprecated: This property is deprecated and will be removed.</p> * @property {number} restitution=0.5 - The "bounciness" of an entity when it collides, range <code>0.0</code> – * <code>0.99</code>. The higher the value, the more bouncy. * @property {number} friction=0.5 - How much an entity slows down when it's moving against another, range <code>0.0</code> * – <code>10.0</code>. The higher the value, the more quickly it slows down. Examples: <code>0.1</code> for ice, * <code>0.9</code> for sandpaper. * @property {number} density=1000 - The density of the entity in kg/m<sup>3</sup>, range <code>100</code> – * <code>10000</code>. Examples: <code>100</code> for balsa wood, <code>10000</code> for silver. The density is used in * conjunction with the entity's bounding box volume to work out its mass in the application of physics. * * @property {boolean} collisionless=false - <code>true</code> if the entity shouldn't collide, <code>false</code> if it * collides with items per its <code>collisionMask</code> property. * @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 that's played when the entity experiences a collision. Valid file * formats are per {@link SoundObject}. * @property {boolean} dynamic=false - <code>true</code> if the entity's movement is affected by collisions, <code>false</code> * if it isn't. * @property {boolean} collisionsWillMove - A synonym for <code>dynamic</code>. * * @property {string} href="" - A "hifi://" directory services 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. * <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 <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 - 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.NONE - The ID of the entity or avatar that the entity is parented to. A value of * {@link Uuid(0)|Uuid.NONE} is used 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 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>. * @property {Vec3} localVelocity=0,0,0 - The velocity of the entity relative to its parent if the entity is parented, * otherwise the same value as <code>velocity</code>. * @property {Vec3} localAngularVelocity=0,0,0 - The angular velocity of the entity relative to its parent if the entity is * parented, otherwise the same value as <code>angularVelocity</code>. * @property {Vec3} localDimensions - The dimensions of the entity. If the entity is parented to an avatar and is an * avatar entity so that it scales with the avatar, this value remains the original dimensions value while the * avatar scale changes. * * @property {Entities.BoundingBox} boundingBox - The axis-aligned bounding box that tightly encloses the entity. * <em>Read-only.</em> * @property {AACube} queryAACube - The axis-aligned cube that determines where the entity lives in the entity server's octree. * The cube may be considerably larger than the entity in some situations, e.g., when the entity is grabbed by an avatar: * the position of the entity is determined through avatar mixer updates and so the AA cube is expanded in order to reduce * unnecessary entity server updates. Scripts should not change this property's value. * * @property {string} actionData="" - Base-64 encoded compressed dump of the actions associated with the entity. This property * is typically not used in scripts directly; rather, functions that manipulate an entity's actions update it, e.g., * {@link Entities.addAction}. The size of this property increases with the number of actions. Because this property value * has to fit within a Overte datagram packet, there is a limit to the number of actions that an entity can have; * edits which would result in overflow are rejected. <em>Read-only.</em> * @property {Entities.RenderInfo} renderInfo - Information on the cost of rendering the entity. Currently information is only * provided for <code>Model</code> entities. <em>Read-only.</em> * * @property {boolean} cloneable=false - <code>true</code> if the domain or avatar entity can be cloned via * {@link Entities.cloneEntity}, <code>false</code> if it can't be. * @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 - <code>true</code> if clones created from this entity will have their * <code>dynamic</code> property set to <code>true</code>, <code>false</code> if they won't. * @property {boolean} cloneAvatarEntity=false - <code>true</code> if clones created from this entity will be created as * avatar entities, <code>false</code> if they won't be. * @property {Uuid} cloneOriginID - The ID of the entity that this entity was cloned from. * * @property {Uuid[]} renderWithZones=[]] - A list of entity IDs representing with which zones this entity should render. * If it is empty, this entity will render normally. Otherwise, this entity will only render if your avatar is within * one of the zones in this list. * @property {BillboardMode} billboardMode="none" - Whether the entity is billboarded to face the camera. Use the rotation * property to control which axis is facing you. * @property {string[]} tags=[]] - A set of tags describing this entity. * * @property {Entities.Grab} grab - The entity's grab-related properties. * * @property {MirrorMode} mirrorMode="none" - If this entity should render as a mirror (reflecting the view of the camera), * a portal (reflecting the view through its <code>portalExitID</code>), or normally. * @property {Uuid} portalExitID=Uuid.NONE - The ID of the entity that should act as the portal exit if the <code>mirrorMode</code> * is set to <code>portal</code>. * * @property {Entities.Fade} fadeIn - The entity's fade in properties. For zones, this defines the default fade in properties for entities * while you are in this zone. * @property {Entities.Fade} fadeOut - The entity's fade out properties. For zones, this defines the default fade out properties for entities * while you are in this zone. * @property {Entities.ComponentMode} fadeInMode="inherit" - Configures the fade in for this entity. * @property {Entities.ComponentMode} fadeOutMode="inherit" - Configures the fade out for this entity. * * @comment The different entity types have additional properties as follows: * @see {@link Entities.EntityProperties-Box|EntityProperties-Box} * @see {@link Entities.EntityProperties-Canvas|EntityProperties-Canvas} * @see {@link Entities.EntityProperties-Empty|EntityProperties-Empty} * @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-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-ProceduralParticleEffect|EntityProperties-ProceduralParticleEffect} * @see {@link Entities.EntityProperties-Script|EntityProperties-Script} * @see {@link Entities.EntityProperties-Shape|EntityProperties-Shape} * @see {@link Entities.EntityProperties-Sound|EntityProperties-Sound} * @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} */ /*@jsdoc * The <code>"Box"</code> {@link Entities.EntityType|EntityType} is the same as the <code>"Shape"</code> * {@link Entities.EntityType|EntityType} except that its <code>shape</code> value is always set to <code>"Cube"</code> * 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}. * * @typedef {object} Entities.EntityProperties-Light * @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 - <code>true</code> if the light is directional, emitting along the entity's * local negative z-axis; <code>false</code> if 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> * Entities.addEntity({ * type: "Light", * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -4 })), * rotation: Quat.fromPitchYawRollDegrees(-75, 0, 0), * dimensions: { x: 5, y: 5, z: 5 }, * intensity: 100, * falloffRadius: 0.3, * isSpotlight: true, * exponent: 20, * cutoff: 30, * lifetime: 300 // Delete after 5 minutes. * }); */ /*@jsdoc * The <code>"Line"</code> {@link Entities.EntityType|EntityType} draws thin, straight lines between a sequence of two or more * points. It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. * <p class=important>Deprecated: Use {@link Entities.EntityProperties-PolyLine|PolyLine} entities 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>. * @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. The property's value is set only if all the <code>linePoints</code> * lie within the entity's <code>dimensions</code>. * @property {Color} color=255,255,255 - The color of the line. * @example <caption>Draw lines in a "V".</caption> * var entity = Entities.addEntity({ * type: "Line", * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -5 })), * rotation: MyAvatar.orientation, * dimensions: { x: 2, y: 2, z: 1 }, * linePoints: [ * { x: -1, y: 1, z: 0 }, * { x: 0, y: -1, z: 0 }, * { x: 1, y: 1, z: 0 }, * ], * color: { red: 255, green: 0, blue: 0 }, * lifetime: 300 // Delete after 5 minutes. * }); */ /*@jsdoc * 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> 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 {Vec3} dimensions=0.1,0.1,0.1 - Used when <code>materialMappingMode == "projected"</code>. * @property {string} materialURL="" - URL to a {@link Entities.MaterialResource|MaterialResource}. Alternatively, set the * property value to <code>"materialData"</code> to use the <code>materialData</code> property for the * {@link Entities.MaterialResource|MaterialResource} values. If you append <code>"#name"</code> to the URL, the material * with that name will be applied to the entity. You can also use the ID of another Material entity as the URL, in which * case this material will act as a copy of that material, with its own unique material transform, priority, etc. * @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. * 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>, * <code>"projected"</code>, or <code>"triplanar"</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. <code>"triplanar"</code> * mode is like <code>"uv"</code> mode but the UV coordinates are evaluated based on a triplanar mapping instead of the * coordinates from the model. * @property {Vec2} materialMappingPos=0,0 - Offset position in UV-space of the top left of the material, range * <code>{ x: 0, y: 0 }</code> – <code>{ x: 1, y: 1 }</code>. * @property {Vec2} materialMappingScale=1,1 - How much to scale the material within the parent's UV-space. * @property {number} materialMappingRot=0 - How much to rotate the material within the parent's UV-space, in degrees. * @property {boolean} materialRepeat=true - <code>true</code> if the material repeats, <code>false</code> if it doesn't. If * <code>false</code>, fragments outside of texCoord 0 – 1 will be discarded. Works in both <code>"uv"</code> and * <code>"projected"</code> modes. * @example <caption>Color a sphere using a Material entity.</caption> * var entityID = Entities.addEntity({ * type: "Sphere", * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })), * dimensions: { x: 1, y: 1, z: 1 }, * color: { red: 128, green: 128, blue: 128 }, * lifetime: 300 // Delete after 5 minutes. * }); * * var materialID = Entities.addEntity({ * type: "Material", * parentID: entityID, * materialURL: "materialData", * priority: 1, * materialData: JSON.stringify({ * materialVersion: 1, * materials: { * // Value overrides entity's "color" property. * albedo: [1.0, 1.0, 0] // Yellow * } * }) * }); */ /*@jsdoc * The <code>"Model"</code> {@link Entities.EntityType|EntityType} displays a glTF, VRM, 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 {string} modelURL="" - The URL of the glTF, VRM, FBX, or OBJ model. glTF models may be in JSON or binary format * (".gltf" or ".glb" URLs respectively). Baked models' URLs have ".baked" before the file type. 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} blendshapeCoefficients - A JSON string of a map of blendshape names to values. Only stores set values. * When editing this property, only coefficients that you are editing will change; it will not explicitly reset other * coefficients. * @property {boolean} useOriginalPivot=false - If <code>false</code>, the model will be centered based on its content, * ignoring any offset in the model itself. If <code>true</code>, the model will respect its original offset. Currently, * only pivots relative to <code>{x: 0, y: 0, z: 0}</code> are supported. * @property {number} loadPriority=0.0 - If <code>0</code>, the model download will be prioritized based on distance, size, and * other factors, and assigned a priority automatically between <code>0</code> and <code>PI / 2</code>. Otherwise, the * download will be ordered based on the set <code>loadPriority</code>. * @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 * overrides. You can use <code>JSON.stringify()</code> to convert a JavaScript object of name, URL pairs into a JSON * string. * @property {string} originalTextures="{}" - A JSON string of texture name, URL pairs used in the model. The property value is * filled in after the entity has finished rezzing (i.e., textures have loaded). You can use <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 * <code>"compound"</code>. * * @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 * model hasn't loaded. The array indexes are per {@link Entities.getJointIndex|getJointIndex}. Rotations are relative to * 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 * the model hasn't loaded. The array indexes are per {@link Entities.getJointIndex|getJointIndex}. Translations are * relative 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>.</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 - <code>true</code> if when the entity is parented to an avatar, the avatar's * joint rotations are applied to the entity's joints; <code>false</code> if a parent avatar's joint rotations are not * applied to the entity's joints. * @property {boolean} groupCulled=false - <code>true</code> if the mesh parts of the model are LOD culled as a group, * <code>false</code> if separate mesh parts are LOD culled individually. * * @example <caption>Rez a cowboy hat.</caption> * var entity = Entities.addEntity({ * type: "Model", * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -2 })), * rotation: MyAvatar.orientation, * modelURL: "https://apidocs.overte.org/examples/cowboy-hat.fbx", * dimensions: { x: 0.8569, y: 0.3960, z: 1.0744 }, * lifetime: 300 // Delete after 5 minutes. * }); */ /*@jsdoc * 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 - <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. For example, if * <code>emitSpeed == 5</code> and <code>speedSpread == 1</code>, particles will be emitted with speeds in the range * <code>4</code> – <code>6</code>m/s. * @property {Vec3} emitAcceleration=0,-9.8,0 - The acceleration that is applied to each particle during its lifetime. The * default is Earth's gravity value. * @property {Vec3} accelerationSpread=0,0,0 - The spread in accelerations that each particle is given. For example, if * <code>emitAccelerations == {x: 0, y: -9.8, z: 0}</code> and <code>accelerationSpread == * {x: 0, y: 1, z: 0}</code>, each particle will have an acceleration in the range <code>{x: 0, y: -10.8, z: 0}</code> * – <code>{x: 0, y: -8.8, z: 0}</code>. * @property {Vec3} dimensions - The dimensions of the particle effect, i.e., a bounding box containing all the particles * during their lifetimes, assuming that <code>emitterShouldTrail == false</code>. <em>Read-only.</em> * @property {boolean} emitterShouldTrail=false - <code>true</code> if particles are "left behind" as the emitter moves, * <code>false</code> if 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 {ShapeType} shapeType="ellipsoid" - The shape from which particles are emitted. * @property {string} compoundShapeURL="" - The model file to use for the compound shape if <code>shapeType == * "compound"</code>. * @property {Vec3} emitDimensions=0,0,0 - The dimensions of the shape from which particles are emitted. * @property {number} emitRadiusStart=1 - The starting radius within the shape at which particles start being emitted; * range <code>0.0</code> – <code>1.0</code> for the center to the surface, respectively. * Particles are emitted from the portion of the shape that lies between <code>emitRadiusStart</code> and the * shape's surface. * @property {number} polarStart=0 - The angle in radians from the entity's local z-axis at which particles start being emitted * within the shape; range <code>0</code> – <code>Math.PI</code>. Particles are emitted from the portion of the * shape that lies between <code>polarStart</code> and <code>polarFinish</code>. Only used if <code>shapeType</code> is * <code>"ellipsoid"</code> or <code>"sphere"</code>. * @property {number} polarFinish=0 - The angle in radians from the entity's local z-axis at which particles stop being emitted * within the shape; range <code>0</code> – <code>Math.PI</code>. Particles are emitted from the portion of the * shape that lies between <code>polarStart</code> and <code>polarFinish</code>. Only used if <code>shapeType</code> is * <code>"ellipsoid"</code> or <code>"sphere"</code>. * @property {number} azimuthStart=-Math.PI - The angle in radians from the entity's local x-axis about the entity's local * z-axis at which particles start being emitted; range <code>-Math.PI</code> – <code>Math.PI</code>. Particles are * emitted from the portion of the shape that lies between <code>azimuthStart</code> and <code>azimuthFinish</code>. * Only used if <code>shapeType</code> is <code>"ellipsoid"</code>, <code>"sphere"</code>, or <code>"circle"</code>. * @property {number} azimuthFinish=Math.PI - The angle in radians from the entity's local x-axis about the entity's local * z-axis at which particles stop being emitted; range <code>-Math.PI</code> – <code>Math.PI</code>. Particles are * emitted from the portion of the shape that lies between <code>azimuthStart</code> and <code>azimuthFinish</code>. * Only used if <code>shapeType</code> is <code>"ellipsoid"</code>, <code>"sphere"</code>, or <code>"circle"</code>. * * @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=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=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. For example, if * <code>particleRadius == 0.5</code> and <code>radiusSpread == 0.25</code>, each particle will have a radius in the range * <code>0.25</code> – <code>0.75</code>. * @property {Color} color=255,255,255 - The color of each particle at the middle of its life. * @property {ColorFloat} colorStart=null,null,null - The color of each particle at the start of its life. If any of theLines 1–500 of 1098. Load more
// // EntityItemPropertiesDocs.cpp // libraries/entities/src // // Created by HifiExperiments on 7/24/24. // Copyright 2024 Overte e.V. // // Distributed under the Apache License, Version 2.0. // See the accompanying file LICENSE or http://www.apache.org/licenses/LICENSE-2.0.html // SPDX-License-Identifier: Apache-2.0 // /*@jsdoc * Different entity types have different properties: some common to all entities (listed in the table) and some specific to * each {@link Entities.EntityType|EntityType} (linked to below). * * @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'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.NONE - The session ID of the owning avatar if <code>avatarEntity</code> is * <code>true</code>, otherwise {@link Uuid(0)|Uuid.NONE}. <em>Read-only.</em> * * @property {number} created - When the entity was created, expressed as the number of microseconds since * 1970-01-01T00:00:00 UTC. <em>Read-only.</em> * @property {number} age - The age of the entity in seconds since it was created. <em>Read-only.</em> * @property {string} ageAsText - The age of the entity since it was created, formatted as <code>h hours m minutes s * seconds</code>. * @property {number} lifetime=-1 - How long an entity lives for, in seconds, before being automatically deleted. A value of * <code>-1</code> means that the entity lives for ever. * @property {number} lastEdited - When the entity was last edited, expressed as the number of microseconds since * 1970-01-01T00:00:00 UTC. <em>Read-only.</em> * @property {Uuid} lastEditedBy - The session ID of the avatar or agent that most recently created or edited the entity. * <em>Read-only.</em> * * @property {boolean} locked=false - <code>true</code> if properties other than <code>locked</code> cannot be changed and the * entity cannot be deleted, <code>false</code> if all properties can be changed and the entity can be deleted. * @property {boolean} visible=true - <code>true</code> if the entity is rendered, <code>false</code> if it isn't. * @property {boolean} canCastShadow=true - <code>true</code> if the entity can cast a shadow, <code>false</code> if it can't. * Currently applicable only to {@link Entities.EntityProperties-Model|Model} and * {@link Entities.EntityProperties-Shape|Shape} entities. Shadows are cast if inside a * {@link Entities.EntityProperties-Zone|Zone} entity with <code>castShadows</code> enabled in its <code>keyLight</code> * property. * @property {boolean} isVisibleInSecondaryCamera=true - <code>true</code> if the entity is rendered in the secondary camera, * <code>false</code> if it isn't. * @property {Entities.RenderLayer} renderLayer="world" - The layer that 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. * * @property {Vec3} position=0,0,0 - The position of the entity in world coordinates. * @property {Quat} rotation=0,0,0,1 - The orientation of the entity in world coordinates. * @property {Vec3} registrationPoint=0.5,0.5,0.5 - The point in the entity that is set to the entity's position and is rotated * about, range {@link Vec3(0)|Vec3.ZERO} – {@link Vec3(0)|Vec3.ONE}. A value of {@link Vec3(0)|Vec3.ZERO} is the * entity's minimum x, y, z corner; a value of {@link Vec3(0)|Vec3.ONE} is the entity's maximum x, y, z corner. * * @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> * @property {Vec3} naturalDimensions - The dimensions of the entity's unscaled mesh model or image if it has one, otherwise * {@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 the linear velocity of an entity slows down over time, range * <code>0.0</code> – <code>1.0</code>. A higher damping value slows down the entity more quickly. The default value * is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to <code>1/e = 0.368</code> * of its initial value. * @property {Vec3} angularVelocity=0,0,0 - The angular velocity of the entity in rad/s with respect to its axes, about its * registration point. * @property {number} angularDamping=0.39347 - How much the angular velocity of an entity slows down over time, range * <code>0.0</code> – <code>1.0</code>. A higher damping value slows down the entity more quickly. The default value * is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to <code>1/e = 0.368</code> * of its initial value. * * @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. 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>. * <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 - The current, measured acceleration of the entity, in m/s<sup>2</sup>. * <p class="important">Deprecated: This property is deprecated and will be removed.</p> * @property {number} restitution=0.5 - The "bounciness" of an entity when it collides, range <code>0.0</code> – * <code>0.99</code>. The higher the value, the more bouncy. * @property {number} friction=0.5 - How much an entity slows down when it's moving against another, range <code>0.0</code> * – <code>10.0</code>. The higher the value, the more quickly it slows down. Examples: <code>0.1</code> for ice, * <code>0.9</code> for sandpaper. * @property {number} density=1000 - The density of the entity in kg/m<sup>3</sup>, range <code>100</code> – * <code>10000</code>. Examples: <code>100</code> for balsa wood, <code>10000</code> for silver. The density is used in * conjunction with the entity's bounding box volume to work out its mass in the application of physics. * * @property {boolean} collisionless=false - <code>true</code> if the entity shouldn't collide, <code>false</code> if it * collides with items per its <code>collisionMask</code> property. * @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 that's played when the entity experiences a collision. Valid file * formats are per {@link SoundObject}. * @property {boolean} dynamic=false - <code>true</code> if the entity's movement is affected by collisions, <code>false</code> * if it isn't. * @property {boolean} collisionsWillMove - A synonym for <code>dynamic</code>. * * @property {string} href="" - A "hifi://" directory services 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. * <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 <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 - 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.NONE - The ID of the entity or avatar that the entity is parented to. A value of * {@link Uuid(0)|Uuid.NONE} is used 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 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>. * @property {Vec3} localVelocity=0,0,0 - The velocity of the entity relative to its parent if the entity is parented, * otherwise the same value as <code>velocity</code>. * @property {Vec3} localAngularVelocity=0,0,0 - The angular velocity of the entity relative to its parent if the entity is * parented, otherwise the same value as <code>angularVelocity</code>. * @property {Vec3} localDimensions - The dimensions of the entity. If the entity is parented to an avatar and is an * avatar entity so that it scales with the avatar, this value remains the original dimensions value while the * avatar scale changes. * * @property {Entities.BoundingBox} boundingBox - The axis-aligned bounding box that tightly encloses the entity. * <em>Read-only.</em> * @property {AACube} queryAACube - The axis-aligned cube that determines where the entity lives in the entity server's octree. * The cube may be considerably larger than the entity in some situations, e.g., when the entity is grabbed by an avatar: * the position of the entity is determined through avatar mixer updates and so the AA cube is expanded in order to reduce * unnecessary entity server updates. Scripts should not change this property's value. * * @property {string} actionData="" - Base-64 encoded compressed dump of the actions associated with the entity. This property * is typically not used in scripts directly; rather, functions that manipulate an entity's actions update it, e.g., * {@link Entities.addAction}. The size of this property increases with the number of actions. Because this property value * has to fit within a Overte datagram packet, there is a limit to the number of actions that an entity can have; * edits which would result in overflow are rejected. <em>Read-only.</em> * @property {Entities.RenderInfo} renderInfo - Information on the cost of rendering the entity. Currently information is only * provided for <code>Model</code> entities. <em>Read-only.</em> * * @property {boolean} cloneable=false - <code>true</code> if the domain or avatar entity can be cloned via * {@link Entities.cloneEntity}, <code>false</code> if it can't be. * @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 - <code>true</code> if clones created from this entity will have their * <code>dynamic</code> property set to <code>true</code>, <code>false</code> if they won't. * @property {boolean} cloneAvatarEntity=false - <code>true</code> if clones created from this entity will be created as * avatar entities, <code>false</code> if they won't be. * @property {Uuid} cloneOriginID - The ID of the entity that this entity was cloned from. * * @property {Uuid[]} renderWithZones=[]] - A list of entity IDs representing with which zones this entity should render. * If it is empty, this entity will render normally. Otherwise, this entity will only render if your avatar is within * one of the zones in this list. * @property {BillboardMode} billboardMode="none" - Whether the entity is billboarded to face the camera. Use the rotation * property to control which axis is facing you. * @property {string[]} tags=[]] - A set of tags describing this entity. * * @property {Entities.Grab} grab - The entity's grab-related properties. * * @property {MirrorMode} mirrorMode="none" - If this entity should render as a mirror (reflecting the view of the camera), * a portal (reflecting the view through its <code>portalExitID</code>), or normally. * @property {Uuid} portalExitID=Uuid.NONE - The ID of the entity that should act as the portal exit if the <code>mirrorMode</code> * is set to <code>portal</code>. * * @property {Entities.Fade} fadeIn - The entity's fade in properties. For zones, this defines the default fade in properties for entities * while you are in this zone. * @property {Entities.Fade} fadeOut - The entity's fade out properties. For zones, this defines the default fade out properties for entities * while you are in this zone. * @property {Entities.ComponentMode} fadeInMode="inherit" - Configures the fade in for this entity. * @property {Entities.ComponentMode} fadeOutMode="inherit" - Configures the fade out for this entity. * * @comment The different entity types have additional properties as follows: * @see {@link Entities.EntityProperties-Box|EntityProperties-Box} * @see {@link Entities.EntityProperties-Canvas|EntityProperties-Canvas} * @see {@link Entities.EntityProperties-Empty|EntityProperties-Empty} * @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-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-ProceduralParticleEffect|EntityProperties-ProceduralParticleEffect} * @see {@link Entities.EntityProperties-Script|EntityProperties-Script} * @see {@link Entities.EntityProperties-Shape|EntityProperties-Shape} * @see {@link Entities.EntityProperties-Sound|EntityProperties-Sound} * @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} */ /*@jsdoc * The <code>"Box"</code> {@link Entities.EntityType|EntityType} is the same as the <code>"Shape"</code> * {@link Entities.EntityType|EntityType} except that its <code>shape</code> value is always set to <code>"Cube"</code> * 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}. * * @typedef {object} Entities.EntityProperties-Light * @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 - <code>true</code> if the light is directional, emitting along the entity's * local negative z-axis; <code>false</code> if 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> * Entities.addEntity({ * type: "Light", * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -4 })), * rotation: Quat.fromPitchYawRollDegrees(-75, 0, 0), * dimensions: { x: 5, y: 5, z: 5 }, * intensity: 100, * falloffRadius: 0.3, * isSpotlight: true, * exponent: 20, * cutoff: 30, * lifetime: 300 // Delete after 5 minutes. * }); */ /*@jsdoc * The <code>"Line"</code> {@link Entities.EntityType|EntityType} draws thin, straight lines between a sequence of two or more * points. It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. * <p class=important>Deprecated: Use {@link Entities.EntityProperties-PolyLine|PolyLine} entities 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>. * @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. The property's value is set only if all the <code>linePoints</code> * lie within the entity's <code>dimensions</code>. * @property {Color} color=255,255,255 - The color of the line. * @example <caption>Draw lines in a "V".</caption> * var entity = Entities.addEntity({ * type: "Line", * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -5 })), * rotation: MyAvatar.orientation, * dimensions: { x: 2, y: 2, z: 1 }, * linePoints: [ * { x: -1, y: 1, z: 0 }, * { x: 0, y: -1, z: 0 }, * { x: 1, y: 1, z: 0 }, * ], * color: { red: 255, green: 0, blue: 0 }, * lifetime: 300 // Delete after 5 minutes. * }); */ /*@jsdoc * 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> 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 {Vec3} dimensions=0.1,0.1,0.1 - Used when <code>materialMappingMode == "projected"</code>. * @property {string} materialURL="" - URL to a {@link Entities.MaterialResource|MaterialResource}. Alternatively, set the * property value to <code>"materialData"</code> to use the <code>materialData</code> property for the * {@link Entities.MaterialResource|MaterialResource} values. If you append <code>"#name"</code> to the URL, the material * with that name will be applied to the entity. You can also use the ID of another Material entity as the URL, in which * case this material will act as a copy of that material, with its own unique material transform, priority, etc. * @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. * 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>, * <code>"projected"</code>, or <code>"triplanar"</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. <code>"triplanar"</code> * mode is like <code>"uv"</code> mode but the UV coordinates are evaluated based on a triplanar mapping instead of the * coordinates from the model. * @property {Vec2} materialMappingPos=0,0 - Offset position in UV-space of the top left of the material, range * <code>{ x: 0, y: 0 }</code> – <code>{ x: 1, y: 1 }</code>. * @property {Vec2} materialMappingScale=1,1 - How much to scale the material within the parent's UV-space. * @property {number} materialMappingRot=0 - How much to rotate the material within the parent's UV-space, in degrees. * @property {boolean} materialRepeat=true - <code>true</code> if the material repeats, <code>false</code> if it doesn't. If * <code>false</code>, fragments outside of texCoord 0 – 1 will be discarded. Works in both <code>"uv"</code> and * <code>"projected"</code> modes. * @example <caption>Color a sphere using a Material entity.</caption> * var entityID = Entities.addEntity({ * type: "Sphere", * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })), * dimensions: { x: 1, y: 1, z: 1 }, * color: { red: 128, green: 128, blue: 128 }, * lifetime: 300 // Delete after 5 minutes. * }); * * var materialID = Entities.addEntity({ * type: "Material", * parentID: entityID, * materialURL: "materialData", * priority: 1, * materialData: JSON.stringify({ * materialVersion: 1, * materials: { * // Value overrides entity's "color" property. * albedo: [1.0, 1.0, 0] // Yellow * } * }) * }); */ /*@jsdoc * The <code>"Model"</code> {@link Entities.EntityType|EntityType} displays a glTF, VRM, 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 {string} modelURL="" - The URL of the glTF, VRM, FBX, or OBJ model. glTF models may be in JSON or binary format * (".gltf" or ".glb" URLs respectively). Baked models' URLs have ".baked" before the file type. 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} blendshapeCoefficients - A JSON string of a map of blendshape names to values. Only stores set values. * When editing this property, only coefficients that you are editing will change; it will not explicitly reset other * coefficients. * @property {boolean} useOriginalPivot=false - If <code>false</code>, the model will be centered based on its content, * ignoring any offset in the model itself. If <code>true</code>, the model will respect its original offset. Currently, * only pivots relative to <code>{x: 0, y: 0, z: 0}</code> are supported. * @property {number} loadPriority=0.0 - If <code>0</code>, the model download will be prioritized based on distance, size, and * other factors, and assigned a priority automatically between <code>0</code> and <code>PI / 2</code>. Otherwise, the * download will be ordered based on the set <code>loadPriority</code>. * @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 * overrides. You can use <code>JSON.stringify()</code> to convert a JavaScript object of name, URL pairs into a JSON * string. * @property {string} originalTextures="{}" - A JSON string of texture name, URL pairs used in the model. The property value is * filled in after the entity has finished rezzing (i.e., textures have loaded). You can use <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 * <code>"compound"</code>. * * @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 * model hasn't loaded. The array indexes are per {@link Entities.getJointIndex|getJointIndex}. Rotations are relative to * 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 * the model hasn't loaded. The array indexes are per {@link Entities.getJointIndex|getJointIndex}. Translations are * relative 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>.</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 - <code>true</code> if when the entity is parented to an avatar, the avatar's * joint rotations are applied to the entity's joints; <code>false</code> if a parent avatar's joint rotations are not * applied to the entity's joints. * @property {boolean} groupCulled=false - <code>true</code> if the mesh parts of the model are LOD culled as a group, * <code>false</code> if separate mesh parts are LOD culled individually. * * @example <caption>Rez a cowboy hat.</caption> * var entity = Entities.addEntity({ * type: "Model", * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -2 })), * rotation: MyAvatar.orientation, * modelURL: "https://apidocs.overte.org/examples/cowboy-hat.fbx", * dimensions: { x: 0.8569, y: 0.3960, z: 1.0744 }, * lifetime: 300 // Delete after 5 minutes. * }); */ /*@jsdoc * 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 - <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. For example, if * <code>emitSpeed == 5</code> and <code>speedSpread == 1</code>, particles will be emitted with speeds in the range * <code>4</code> – <code>6</code>m/s. * @property {Vec3} emitAcceleration=0,-9.8,0 - The acceleration that is applied to each particle during its lifetime. The * default is Earth's gravity value. * @property {Vec3} accelerationSpread=0,0,0 - The spread in accelerations that each particle is given. For example, if * <code>emitAccelerations == {x: 0, y: -9.8, z: 0}</code> and <code>accelerationSpread == * {x: 0, y: 1, z: 0}</code>, each particle will have an acceleration in the range <code>{x: 0, y: -10.8, z: 0}</code> * – <code>{x: 0, y: -8.8, z: 0}</code>. * @property {Vec3} dimensions - The dimensions of the particle effect, i.e., a bounding box containing all the particles * during their lifetimes, assuming that <code>emitterShouldTrail == false</code>. <em>Read-only.</em> * @property {boolean} emitterShouldTrail=false - <code>true</code> if particles are "left behind" as the emitter moves, * <code>false</code> if 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 {ShapeType} shapeType="ellipsoid" - The shape from which particles are emitted. * @property {string} compoundShapeURL="" - The model file to use for the compound shape if <code>shapeType == * "compound"</code>. * @property {Vec3} emitDimensions=0,0,0 - The dimensions of the shape from which particles are emitted. * @property {number} emitRadiusStart=1 - The starting radius within the shape at which particles start being emitted; * range <code>0.0</code> – <code>1.0</code> for the center to the surface, respectively. * Particles are emitted from the portion of the shape that lies between <code>emitRadiusStart</code> and the * shape's surface. * @property {number} polarStart=0 - The angle in radians from the entity's local z-axis at which particles start being emitted * within the shape; range <code>0</code> – <code>Math.PI</code>. Particles are emitted from the portion of the * shape that lies between <code>polarStart</code> and <code>polarFinish</code>. Only used if <code>shapeType</code> is * <code>"ellipsoid"</code> or <code>"sphere"</code>. * @property {number} polarFinish=0 - The angle in radians from the entity's local z-axis at which particles stop being emitted * within the shape; range <code>0</code> – <code>Math.PI</code>. Particles are emitted from the portion of the * shape that lies between <code>polarStart</code> and <code>polarFinish</code>. Only used if <code>shapeType</code> is * <code>"ellipsoid"</code> or <code>"sphere"</code>. * @property {number} azimuthStart=-Math.PI - The angle in radians from the entity's local x-axis about the entity's local * z-axis at which particles start being emitted; range <code>-Math.PI</code> – <code>Math.PI</code>. Particles are * emitted from the portion of the shape that lies between <code>azimuthStart</code> and <code>azimuthFinish</code>. * Only used if <code>shapeType</code> is <code>"ellipsoid"</code>, <code>"sphere"</code>, or <code>"circle"</code>. * @property {number} azimuthFinish=Math.PI - The angle in radians from the entity's local x-axis about the entity's local * z-axis at which particles stop being emitted; range <code>-Math.PI</code> – <code>Math.PI</code>. Particles are * emitted from the portion of the shape that lies between <code>azimuthStart</code> and <code>azimuthFinish</code>. * Only used if <code>shapeType</code> is <code>"ellipsoid"</code>, <code>"sphere"</code>, or <code>"circle"</code>. * * @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=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=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. For example, if * <code>particleRadius == 0.5</code> and <code>radiusSpread == 0.25</code>, each particle will have a radius in the range * <code>0.25</code> – <code>0.75</code>. * @property {Color} color=255,255,255 - The color of each particle at the middle of its life. * @property {ColorFloat} colorStart=null,null,null - The color of each particle at the start of its life. If any of the