From 67cfe783be90634200dbcb5f3d701e4b630cd0e6 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Mon, 19 Feb 2018 12:17:31 +1300 Subject: [PATCH] Entity properties JSDoc --- .../entities/src/AmbientLightPropertyGroup.h | 8 + .../entities/src/AnimationPropertyGroup.cpp | 13 + .../entities/src/EntityItemProperties.cpp | 642 +++++++++++++++++- .../entities/src/EntityScriptingInterface.h | 8 + libraries/entities/src/EntityTypes.h | 39 ++ libraries/entities/src/HazePropertyGroup.h | 29 + .../entities/src/KeyLightPropertyGroup.h | 7 + libraries/entities/src/PolyVoxEntityItem.h | 19 + libraries/entities/src/ShapeEntityItem.cpp | 29 +- libraries/entities/src/ShapeEntityItem.h | 2 +- libraries/entities/src/SkyboxPropertyGroup.h | 7 + libraries/render-utils/src/GeometryCache.cpp | 26 - libraries/shared/src/PhysicsCollisionGroups.h | 18 + libraries/shared/src/RegisteredMetaTypes.cpp | 9 + libraries/shared/src/ShapeInfo.cpp | 29 +- tools/jsdoc/plugins/hifi.js | 1 - 16 files changed, 847 insertions(+), 39 deletions(-) diff --git a/libraries/entities/src/AmbientLightPropertyGroup.h b/libraries/entities/src/AmbientLightPropertyGroup.h index fbbc7c9900..591ea6a6fa 100644 --- a/libraries/entities/src/AmbientLightPropertyGroup.h +++ b/libraries/entities/src/AmbientLightPropertyGroup.h @@ -27,6 +27,14 @@ class OctreePacketData; class EntityTreeElementExtraEncodeData; class ReadBitstreamToTreeParams; +/**jsdoc + * 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 + * "" then the entity's {@link Entities.Skybox|Skybox} url property value is used, unless that also is "" in which + * case the entity's ambientLightMode property is set to "inherit". + */ class AmbientLightPropertyGroup : public PropertyGroup { public: // EntityItemProperty related helpers diff --git a/libraries/entities/src/AnimationPropertyGroup.cpp b/libraries/entities/src/AnimationPropertyGroup.cpp index 2af56fb6b2..82af60ed1a 100644 --- a/libraries/entities/src/AnimationPropertyGroup.cpp +++ b/libraries/entities/src/AnimationPropertyGroup.cpp @@ -44,6 +44,19 @@ bool operator!=(const AnimationPropertyGroup& a, const AnimationPropertyGroup& b } +/**jsdoc + * The AnimationProperties are used to configure an animation. + * @typedef Entities.AnimationProperties + * @property {string} url="" - The URL of the FBX file that has the animation. + * @property {number} fps=30 - The speed in frames/s that the animation is played at. + * @property {number} firstFrame=0 - The first frame to play in the animation. + * @property {number} lastFrame=100000 - The last frame to play in the animation. + * @property {number} currentFrame=0 - The current frame being played in the animation. + * @property {boolean} running=false - If true then the animation should play. + * @property {boolean} loop=true - If true then the animation should be continuously repeated in a loop. + * @property {boolean} hold=false - If true then the rotations and translations of the last frame played should be + * maintained when the animation stops playing. + */ void AnimationPropertyGroup::copyToScriptValue(const EntityPropertyFlags& desiredProperties, QScriptValue& properties, QScriptEngine* engine, bool skipDefaults, EntityItemProperties& defaultEntityProperties) const { COPY_GROUP_PROPERTY_TO_QSCRIPTVALUE(PROP_ANIMATION_URL, Animation, animation, URL, url); COPY_GROUP_PROPERTY_TO_QSCRIPTVALUE(PROP_ANIMATION_ALLOW_TRANSLATION, Animation, animation, AllowTranslation, allowTranslation); diff --git a/libraries/entities/src/EntityItemProperties.cpp b/libraries/entities/src/EntityItemProperties.cpp index e2a5ddf8b5..fed3204245 100644 --- a/libraries/entities/src/EntityItemProperties.cpp +++ b/libraries/entities/src/EntityItemProperties.cpp @@ -406,6 +406,607 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { return changedProperties; } +/**jsdoc + * Different entity types have different properties: some common to all entities (listed below) and some specific to the type + * of entity (listed separately). The properties are accessed as an object of property names and values. + * + * @typedef {object} Entities.EntityProperties + * @property {Uuid} id - The ID of the entity. Read-only. + * @property {string} name="" - A name for the entity. Need not be unique. + * @property {Entities.EntityType} type - The entity type. You cannot change the type of an entity after it's created. + * Read-only. + * @property {boolean} clientOnly=false - If true then the entity is an avatar entity, otherwise it is a server + * entity. Read-only. + * @property {Uuid} owningAvatarID=Uuid.NULL - The session ID of the owning avatar if clientOnly is + * true, otherwise {@link Uuid|Uuid.NULL}. Read-only. + * + * @property {string} created - The UTC date and time that the entity was created, in ISO 8601 format as + * yyyy-MM-ddTHH:mm:ssZ. Read-only. + * @property {number} age - The age of the entity in seconds since it was created. Read-only. + * @property {string} ageAsText - The age of the entity since it was created, formatted as h hours m minutes s + * seconds. + * @property {number} lifetime=-1 - How long an entity lives for, in seconds, before being automatically deleted. A value of + * -1 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. Read-only. + * @property {Uuid} lastEditedBy - The session ID of the avatar or agent that most recently created or edited the entity. + * Read-only. + * + * @property {boolean} locked=false - Whether or not the entity can be edited or deleted. If true then the + * entity's properties other than locked cannot be changed, and the entity cannot be deleted. + * @property {boolean} visible=true - Whether or not the entity is rendered. If true then the entity is rendered. + * + * @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|Vec3.ZERO} – {@link Vec3|Vec3.ONE}. A value of {@link Vec3|Vec3.ZERO} is the entity's + * minimum x, y, z corner; a value of {@link Vec3|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|Vec3.ZERO}. Read-only. + * @property {Vec3} naturalDimensions - The dimensions of the entity's unscaled mesh model if it has one, otherwise + * {@link Vec3|Vec3.ONE}. Read-only. + * + * @property {Vec3} velocity=0,0,0 - The linear velocity of the entity in m/s with respect to world coordinates. + * @property {number} damping=0.39347 - How much to slow down the linear velocity of an entity over time, 0.0 + * – 1.0. A higher damping value slows down the entity more quickly. The default value is for an + * exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to 1/e = 0.368 of its + * initial value. + * @property {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, + * 0.0 – 1.0. A higher damping value slows down the entity more quickly. The default value + * is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to 1/e = 0.368 + * of its initial value. + * + * @property {Vec3} gravity=0,0,0 - The acceleration due to gravity in m/s2 that the entity should move with, in + * world coordinates. Set to { x: 0, y: -9.8, z: 0 } to simulate Earth's gravity. Gravity is applied to an + * entity's motion only if its dynamic property is true. If changing an entity's + * gravity from {@link Vec3|Vec3.ZERO}, you need to give it a small velocity in order to kick off + * physics simulation. + * The gravity value is applied in addition to the acceleration value. + * @property {Vec3} acceleration=0,0,0 - A general acceleration in m/s2 that the entity should move with, in world + * coordinates. The acceleration is applied to an entity's motion only if its dynamic property is + * true. If changing an entity's acceleration from {@link Vec3|Vec3.ZERO}, you need to give it a + * small velocity in order to kick off physics simulation. + * The acceleration value is applied in addition to the gravity value. + * @property {number} restitution=0.5 - The "bounciness" of an entity when it collides, 0.0 – + * 0.99. The higher the value, the more bouncy. + * @property {number} friction=0.5 - How much to slow down an entity when it's moving against another, 0.0 – + * 10.0. The higher the value, the more quickly it slows down. Examples: 0.1 for ice, + * 0.9 for sandpaper. + * @property {number} density=1000 - The density of the entity in kg/m3, 100 for balsa wood – + * 10000 for silver. The density is used in conjunction with the entity's collision volume to work out its + * mass in the application of physics. + * + * @property {boolean} collisionless=false - Whether or not the entity should collide with items per its + * collisionMask property. If true then the entity does not collide. + * @property {boolean} ignoreForCollisions=false - Synonym for collisionless. + * @property {Entities.CollisionMask} collisionMask=31 - What types of items the entity should collide with. + * @property {string} collidesWith="static,dynamic,kinematic,myAvatar,otherAvatar," - Synonym for collisionMask, + * in text format. + * @property {string} collisionSoundURL="" - The sound to play when the entity experiences a collision. Valid file formats are + * as per the {@link SoundCache} object. + * @property {boolean} dynamic=false - Whether or not the entity should be affected by collisions. If true then + * the entity's movement is affected by collisions. + * @property {boolean} collisionsWillMove=false - Synonym for dynamic. + * + * @property {string} href="" - A "hifi://" metaverse address that a user is taken to when they click on the entity. + * @property {string} description="" - A description of the href property value. + * + * @property {string} userData="" - Intended to be used to store extra data about the entity in JSON format. WARNING: Other + * apps such as the Create app can also use this property, so make sure you handle data stored by other apps. + * + * @property {string} script="" - The URL of the client entity script, if any, that is attached to the entity. + * @property {number} scriptTimestamp=0 - Intended to be used to indicate when the client entity script was loaded. Should be + * an integer number of milliseconds since midnight GMT on January 1, 1970. + * @property {string} serverScripts="" - The URL of the server entity script, if any, that is attached to the entity. + * + * @property {Uuid} parentID=Uuid.NULL - The ID of the entity or avatar that this entity is parented to. {@link Uuid|Uuid.NULL} + * if the entity is not parented. + * @property {number} parentJointIndex=65535 - The joint of the entity or avatar that this entity is parented to. Use + * 65535 or -1 to parent to the entity or avatar's position and orientation rather than a joint. + * @property {Vec3} localPosition=0,0,0 - The position of the entity relative to its parent if the entity is parented, + * otherwise the same value as position. If the entity is parented to an avatar and is clientOnly + * so that it scales with the avatar, this value remains the original local position value while the avatar scale changes. + * @property {Quat} localRotation=0,0,0,1 - The rotation of the entity relative to its parent if the entity is parented, + * otherwise the same value as rotation. + * @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 velocity. + * @property {Vec3} localAngularVelocity=0,0,0 - The angular velocity of the entity relative to its parent if the entity is + * parented, otherwise the same value as position. + * @property {Vec3} localDimensions - The dimensions of the entity. If the entity is parented to an avatar and is + * clientOnly 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. + * Read-only. + * @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. + * Read-only. + * @property {Entities.RenderInfo} renderInfo - Information on the cost of rendering the entity. Currently information is only + * provided for Model entities. Read-only. + * + * @property {string} itemName="" - Certifiable name of the Marketplace item. + * @property {string} itemDescription="" - Certifiable description of the Marketplace item. + * @property {string} itemCategories="" - Certifiable category of the Marketplace item. + * @property {string} itemArtist="" - Certifiable artist that created the Marketplace item. + * @property {string} itemLicense="" - Certifiable license URL for the Marketplace item. + * @property {number} limitedRun=4294967295 - Certifiable maximum integer number of editions (copies) of the Marketplace item + * allowed to be sold. + * @property {number} editionNumber=0 - Certifiable integer edition (copy) number or the Marketplace item. Each copy sold in + * the Marketplace is numbered sequentially, starting at 1. + * @property {number} entityInstanceNumber=0 - Certifiable integer instance number for identical entities in a Marketplace + * item. A Marketplace item may have identical parts. If so, then each is numbered sequentially with an instance number. + * @property {string} marketplaceID="" - Certifiable UUID for the Marketplace item, as used in the URL of the item's download + * and its Marketplace Web page. + * @property {string} certificateID="" - Hash of the entity's static certificate JSON, signed by the artist's private key. + * @property {number} staticCertificateVersion=0 - The version of the method used to generate the certificateID. + * + * @see The different entity types have additional properties as follows: + * @see Entities.EntityProperties-Box + * @see Entities.EntityProperties-Light + * @see Entities.EntityProperties-Line + * @see Entities.EntityProperties-Model + * @see Entities.EntityProperties-ParticleEffect + * @see Entities.EntityProperties-PolyLine + * @see Entities.EntityProperties-PolyVox + * @see Entities.EntityProperties-Shape + * @see Entities.EntityProperties-Sphere + * @see Entities.EntityProperties-Text + * @see Entities.EntityProperties-Web + * @see Entities.EntityProperties-Zone + */ + +/**jsdoc + * The "Box" {@link Entities.EntityType|EntityType} is the same as the "Shape" + * {@link Entities.EntityType|EntityType} except that its initial shape value is always set to "Cube" + * when the entity is created. This property value can subsequently be changed (i.e. so that the entity is no longer displayed + * as a cube). + * @typedef {object} Entities.EntityProperties-Box + */ + +/**jsdoc + * The "Light" {@link Entities.EntityType|EntityType} adds local lighting effects. + * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * @typedef {object} Entities.EntityProperties-Light + * @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. Entity surface outside these dimensions are not lit + * by the light. + * @property {Color} color=255,255,255 - The color of the light emitted. + * @property {number} intensity=1 - The brightness of the light. + * @property {number} falloffRadius=0.1 - The distance from the light's center at which intensity is reduced by 25%. + * @property {boolean} isSpotlight=false - If true then the light is directional, emitting along the entity's + * negative z-axis; otherwise the light is a point light which emanates in all directions. + * @property {number} exponent=0 - Affects the softness of the spotlight beam: the higher the value the softer the beam. + * @property {number} cutoff=1.57 - Affects the size of the spotlight beam: the higher the value the larger the beam. + * @example Create a spotlight pointing at the ground. + * 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 "Line" {@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}. + * @typedef {object} Entities.EntityProperties-Line + * @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. Must be sufficient to contain all the + * linePoints. + * @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 linePoints + * lie within the entity's dimensions. + * @property {number} lineWidth=2 - Currently not used. + * @property {Color} color=255,255,255 - The color of the line. + * @example Draw lines in a "V". + * 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 "Model" {@link Entities.EntityType|EntityType} displays an FBX or OBJ model. + * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * @typedef {object} Entities.EntityProperties-Model + * @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. When adding an entity, if no dimensions + * value is specified then the model is automatically sized to its + * {@link Entityes.EntityProperties|naturalDimensions}. + * @property {Color} color=255,255,255 - Currently not used. + * @property {string} modelURL="" - The URL of the FBX of OBJ model. Baked FBX models' URLs end in ".baked.fbx". + * @property {string} textures="" - A JSON string of texture name, URL pairs used when rendering the model in place of the + * model's original textures. Only the texture names and URLs to be overridden need be specified; original textures are + * used where there are no overrides. You can use JSON.stringify() to convert a JavaScript object of name, URL + * pairs into a JSON string. + * @property {string} originalTextures="{}" - A JSON string of texture name, URL pairs used in the model. The property value is + * filled in after the entity has finished rezzing (i.e., textures have loaded). You can use JSON.parse() to + * parse the JSON string into a JavaScript object of name, URL pairs. Read-only. + * + * @property {ShapeType} shapeType="none" - The shape of the collision hull used if collisions are enabled. + * @property {string} compoundShapeURL="" - The OBJ file to use for the compound shape if shapeType is + * "compound". + * + * @property {Entities.AnimationProperties} animation - An animation to play on the model. + * + * @property {Quat[]} jointRotations=[]] - Joint rotations applied to the model; [] if none are applied or the + * model hasn't loaded. The array indexes are per {@link Entities.getJointIndex|getJointIndex}. Rotations are relative to + * each joint's parent.
+ * Joint rotations can be set by {@link Entities.setLocalJointRotation|setLocalJointRotation} and similar functions, or by + * setting the value of this property. If you set a joint rotation using this property you also need to set the + * corresponding jointRotationsSet value to true. + * @property {boolean[]} jointRotationsSet=[]] - true values for joints that have had rotations applied, + * false otherwise; [] if none are applied or the model hasn't loaded. The array indexes are per + * {@link Entities.getJointIndex|getJointIndex}. + * @property {Vec3[]} jointTranslations=[]] - Joint translations applied to the model; [] if none are applied or + * the model hasn't loaded. The array indexes are per {@link Entities.getJointIndex|getJointIndex}. Rotations are relative + * to each joint's parent.
+ * Joint translations can be set by {@link Entities.setLocalJointTranslation|setLocalJointTranslation} and similar + * functions, or by setting the value of this property. If you set a joint translation using this property you also need to + * set the corresponding jointTranslationsSet value to true. + * @property {boolean[]} jointTranslationsSet=[]] - true values for joints that have had translations applied, + * false otherwise; [] if none are applied or the model hasn't loaded. The array indexes are per + * {@link Entities.getJointIndex|getJointIndex}. + * @property {boolean} relayParentJoints=false - If true and the entity is parented to an avatar, then the + * avatar's joint rotations are applied to the entity's joints. + * + * @example Rez a Vive tracker puck. + * 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: "http://content.highfidelity.com/seefo/production/puck-attach/vive_tracker_puck.obj", + * dimensions: { x: 0.0945, y: 0.0921, z: 0.0423 }, + * lifetime: 300 // Delete after 5 minutes. + * }); + */ + +/**jsdoc + * The "ParticleEffect" {@link Entities.EntityType|EntityType} displays a particle system that can be used to + * simulate things such as fire, smoke, snow, magic spells, etc. The particles emanate from an ellipsoid or part thereof. + * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * @typedef {object} Entities.EntityProperties-ParticleEffect + + * @property {boolean} isEmitting=true - If true then particles are emitted. + * @property {number} maxParticles=1000 - The maximum number of particles to render at one time. Older particles are deleted if + * necessary when new ones are created. + * @property {number} lifespan=3s - How long, in seconds, each particle lives. + * @property {number} emitRate=15 - The number of particles per second to emit. + * @property {number} emitSpeed=5 - The speed, in m/s, that each particle is emitted at. + * @property {number} speedSpread=1 - The spread in speeds at which particles are emitted at. If emitSpeed == 5 + * and speedSpread == 1, particles will be emitted with speeds in the range 4m/s – 6m/s. + * @property {vec3} emitAcceleration=0,-9.8,0 - The acceleration that is applied to each particle during its lifetime. + * @property {vec3} accelerationSpread=0,0,0 - The spread in accelerations that each particle is given. If + * emitAccelerations == {x: 0, y: -9.8, z: 0} and accelerationSpread == + * {x: 0, y: 1, z: 0}, each particle will have an acceleration in the range, {x: 0, y: -10.8, z: 0} + * – {x: 0, y: -8.8, z: 0}. + * @property {Vec3} dimensions - The dimensions of the particle effect, i.e., a bounding box containing all the particles + * during their lifetimes, assuming that emitterShouldTrail is false. Read-only. + * @property {boolean} emitterShouldTrail=false - If true then particles are "left behind" as the emitter moves, + * otherwise they stay with the entity's dimensions. + * + * @property {Quat} emitOrientation=-0.707,0,0,0.707 - The orientation of particle emission relative to the entity's axes. By + * default, particles emit along the entity's z-axis, and azimuthStart and azimuthFinish are + * relative to the entity's x-axis. The default value is a rotation of -90 degrees about the x-axis, i.e., the particles + * emit vertically. + * @property {vec3} emitDimensions=0,0,0 - The dimensions of the ellipsoid from which particles are emitted. + * @property {number} emitRadiusStart=1 - The starting radius within the ellipsoid at which particles start being emitted; + * range 0.0 – 1.0 for the ellipsoid center to the ellipsoid surface, respectively. + * Particles are emitted from the portion of the ellipsoid that lies between emitRadiusStart and the + * ellipsoid's surface. + * @property {number} polarStart=0 - The angle in radians from the entity's z-axis at which particles start being emitted + * within the ellipsoid; range 0 – Math.PI. Particles are emitted from the portion of the + * ellipsoid that lies between polarStart and polarFinish. + * @property {number} polarFinish=0 - The angle in radians from the entity's z-axis at which particles stop being emitted + * within the ellipsoid; range 0 – Math.PI. Particles are emitted from the portion of the + * ellipsoid that lies between polarStart and polarFinish. + * @property {number} azimuthStart=-Math.PI - The angle in radians from the entity's x-axis about the entity's z-axis at which + * particles start being emitted; range -Math.PI – Math.PI. Particles are emitted from the + * portion of the ellipsoid that lies between azimuthStart and azimuthFinish. + * @property {number} azimuthFinish=Math.PI - The angle in radians from the entity's x-axis about the entity's z-axis at which + * particles stop being emitted; range -Math.PI – Math.PI. Particles are emitted from the + * portion of the ellipsoid that lies between azimuthStart and azimuthFinish. + * + * @property {string} textures="" - The URL of a JPG or PNG image file to display for each particle. If you want transparency, + * use PNG format. + * @property {number} particleRadius=0.025 - The radius of each particle at the middle of its life. + * @property {number} radiusStart=0.025 - The radius of each particle at the start of its life. + * @property {number} radiusFinish=0.025 - The radius of each particle at the end of its life. + * @property {number} radiusSpread=0 - Currently not used. + * @property {Color} color=255,255,255 - The color of each particle at the middle of its life. + * @property {Color} colorStart=255,255,255 - The color of each particle at the start of its life. + * @property {color} colorFinish=255,255,255 - The color of each particle at the end of its life. + * @property {Color} colorSpread=0,0,0 - Currently not used. + * @property {number} alpha=1 - The alpha of each particle at the middle of its life. + * @property {number} alphaStart=1 - The alpha of each particle at the start of its life. + * @property {number} alphaFinish=1 - The alpha of each particle at the end of its life. + * @property {number} alphaSpread=0 - Currently not used. + * + * @property {ShapeType} shapeType="none" - Currently not used. Read-only. + * + * @example Create a ball of green smoke. + * particles = Entities.addEntity({ + * type: "ParticleEffect", + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -4 })), + * lifespan: 5, + * emitRate: 10, + * emitSpeed: 0.02, + * speedSpread: 0.01, + * emitAcceleration: { x: 0, y: 0.02, z: 0 }, + * polarFinish: Math.PI, + * textures: "https://content.highfidelity.com/DomainContent/production/Particles/wispy-smoke.png", + * particleRadius: 0.1, + * color: { red: 0, green: 255, blue: 0 }, + * alphaFinish: 0, + * lifetime: 300 // Delete after 5 minutes. + * }); + */ + +/**jsdoc + * The "PolyLine" {@link Entities.EntityType|EntityType} draws textured, straight lines between a sequence of + * points. + * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * @typedef {object} Entities.EntityProperties-PolyLine + * @property {Vec3} dimensions=1,1,1 - The dimensions of the entity, i.e., the size of the bounding box that contains the + * lines drawn. + * @property {Vec3[]} linePoints=[]] - The sequence of points to draw lines between. The values are relative to the entity's + * position. A maximum of 70 points can be specified. Must be specified in order for the entity to render. + * @property {Vec3[]} normals=[]] - The normal vectors for the line's surface at the linePoints. The values are + * relative to the entity's orientation. Must be specified in order for the entity to render. + * @property {number[]} strokeWidths=[]] - The widths, in m, of the line at the linePoints. Must be specified in + * order for the entity to render. + * @property {number} lineWidth=2 - Currently not used. + * @property {Vec3[]} strokeColors=[]] - Currently not used. + * @property {Color} color=255,255,255 - The base color of the line, which is multiplied with the color of the texture for + * rendering. + * @property {string} textures="" - The URL of a JPG or PNG texture to use for the lines. If you want transparency, use PNG + * format. + * @property {boolean} isUVModeStretch=true - If true, the texture is stretched to fill the whole line, otherwise + * the texture repeats along the line. + * @example Draw a textured "V". + * var entity = Entities.addEntity({ + * type: "PolyLine", + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -5 })), + * rotation: MyAvatar.orientation, + * linePoints: [ + * { x: -1, y: 0.5, z: 0 }, + * { x: 0, y: 0, z: 0 }, + * { x: 1, y: 0.5, z: 0 } + * ], + * normals: [ + * { x: 0, y: 0, z: 1 }, + * { x: 0, y: 0, z: 1 }, + * { x: 0, y: 0, z: 1 } + * ], + * strokeWidths: [ 0.1, 0.1, 0.1 ], + * color: { red: 255, green: 0, blue: 0 }, // Use just the red channel from the image. + * textures: "http://hifi-production.s3.amazonaws.com/DomainContent/Toybox/flowArts/trails.png", + * isUVModeStretch: true, + * lifetime: 300 // Delete after 5 minutes. + * }); + */ + +/**jsdoc + * The "PolyVox" {@link Entities.EntityType|EntityType} displays a set of textured voxels. + * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.
+ * If you have two or more neighboring PolyVox entities of the same size abutting each other, you can display them as joined by + * configuring their voxelSurfaceStyle and neighbor ID properties.
+ * PolyVox entities uses a library from Volumes of Fun. Their + * library documentation may be useful to read. + * @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 + * 1,1,1 to 128,128,128. The dimensions of each voxel is + * dimensions / voxelVolumesize. + * @property {string} voxelData="ABAAEAAQAAAAHgAAEAB42u3BAQ0AAADCoPdPbQ8HFAAAAPBuEAAAAQ==" - Base-64 encoded compressed dump of + * the PolyVox data. This property is typically not used in scripts directly; rather, functions that manipulate a PolyVox + * entity update it.
+ * The size of this property increases with the size and complexity of the PolyVox entity, with the size depending on how + * the particular entity's voxels compress. Because this property value has to fit within a High Fidelity datagram packet + * there is a limit to the size and complexity of a PolyVox entity, and edits which would result in an overflow are + * rejected. + * @property {Entities.PolyVoxSurfaceStyle} voxelSurfaceStyle=2 - The style of rendering the voxels' surface and how + * neighboring PolyVox entities are joined. + * @property {string} xTextureURL="" - URL of the texture to map to surfaces perpendicular to the entity's x-axis. JPG or PNG + * format. If no texture is specified the surfaces display white. + * @property {string} yTextureURL="" - URL of the texture to map to surfaces perpendicular to the entity's y-axis. JPG or PNG + * format. If no texture is specified the surfaces display white. + * @property {string} zTextureURL="" - URL of the texture to map to surfaces perpendicular to the entity's z-axis. JPG or PNG + * format. If no texture is specified the surfaces display white. + * @property {Uuid} xNNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's -ve x-axis direction, if you + * want them joined. Set to {@link Uuid|Uuid.NULL} if there is none or you don't want to join them. + * @property {Uuid} yNNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's -ve y-axis direction, if you + * want them joined. Set to {@link Uuid|Uuid.NULL} if there is none or you don't want to join them. + * @property {Uuid} zNNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's -ve z-axis direction, if you + * want them joined. Set to {@link Uuid|Uuid.NULL} if there is none or you don't want to join them. + * @property {Uuid} xPNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's +ve x-axis direction, if you + * want them joined. Set to {@link Uuid|Uuid.NULL} if there is none or you don't want to join them. + * @property {Uuid} yPNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's +ve y-axis direction, if you + * want them joined. Set to {@link Uuid|Uuid.NULL} if there is none or you don't want to join them. + * @property {Uuid} zPNeighborID=Uuid.NULL - ID of the neighboring PolyVox entity in the entity's +ve z-axis direction, if you + * want them joined. Set to {@link Uuid|Uuid.NULL} if there is none or you don't want to join them. + * @example Create a textured PolyVox sphere. + * var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 })); + * var texture = "http://public.highfidelity.com/cozza13/tuscany/Concrete2.jpg"; + * var polyVox = Entities.addEntity({ + * type: "PolyVox", + * position: position, + * dimensions: { x: 2, y: 2, z: 2 }, + * xTextureURL: texture, + * yTextureURL: texture, + * zTextureURL: texture, + * lifetime: 300 // Delete after 5 minutes. + * }); + * Entities.setVoxelSphere(polyVox, position, 0.8, 255); + */ + +/**jsdoc + * The "Shape" {@link Entities.EntityType|EntityType} displays an entity of a specified shape. + * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * @typedef {object} Entities.EntityProperties-Shape + * @property {Entities.Shape} shape="Sphere" - The shape of the entity. + * @property {Vec3} dimensions=0.1,0.1,0.1 - The dimensions of the entity. + * @property {Color} color=255,255,255 - The color of the entity. + * @example Create a cylinder. + * var shape = Entities.addEntity({ + * type: "Shape", + * shape: "Cylinder", + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })), + * dimensions: { x: 0.4, y: 0.6, z: 0.4 }, + * lifetime: 300 // Delete after 5 minutes. + * }); + */ + +/**jsdoc + * The "Sphere" {@link Entities.EntityType|EntityType} is the same as the "Shape" + * {@link Entities.EntityType|EntityType} except that its initial shape value is always set to + * "Sphere" when the entity is created. This property value can subsequently be changed (i.e. so that the entity + * is no longer displayed as a sphere). + * @typedef {object} Entities.EntityProperties-Sphere + */ + +/**jsdoc + * The "Text" {@link Entities.EntityType|EntityType} displays a 2D rectangle of text in the domain. + * It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * @typedef {object} Entities.EntityProperties-Text + * @property {Vec3} dimensions=0.1,0.1,0.01 - The dimensions of the entity. + * @property {string} text="" - The text to display on the face of the entity. Text wraps if necessary to fit. New lines can be + * created using \n. Overflowing lines are not displayed. + * @property {number} lineHeight=0.1 - The height of each line of text (thus determining the font size). + * @property {Color} textColor=255,255,255 - The color of the text. + * @property {Color} backgroundColor=0,0,0 - The color of the background rectangle. + * @property {boolean} faceCamera=false - If true, the entity is oriented to face each user's camera (i.e., it + * differs for each user present). + * @example Create a text entity. + * var text = Entities.addEntity({ + * type: "Text", + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })), + * dimensions: { x: 0.6, y: 0.3, z: 0.01 }, + * lineHeight: 0.12, + * text: "Hello\nthere!", + * faceCamera: true, + * lifetime: 300 // Delete after 5 minutes. + * }); + */ + +/**jsdoc + * The "Web" {@link Entities.EntityType|EntityType} displays a browsable Web page. Each user views their own copy + * of the Web page: if one user navigates to another page on the entity, other users do not see the change; if a video is being + * played, users don't see it in sync. + * The entity has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}. + * @typedef {object} Entities.EntityProperties-Web + * @property {Vec3} dimensions=0.1,0.1,0.01 - The dimensions of the entity. + * @property {string} sourceUrl="" - The URL of the Web page to display. This value does not change as you or others navigate + * on the Web entity. + * @property {number} dpi=30 - The resolution to display the page at, in dots per inch + * @example Create a Web entity displaying at 1920 x 1080 resolution. + * var METERS_TO_INCHES = 39.3701; + * var entity = Entities.addEntity({ + * type: "Web", + * sourceUrl: "https://highfidelity.com/", + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -4 })), + * rotation: MyAvatar.orientation, + * dimensions: { + * x: 3, + * y: 3 * 1080 / 1920, + * z: 0.01 + * }, + * dpi: 1920 / (3 * METERS_TO_INCHES), + * lifetime: 300 // Delete after 5 minutes. + * }); + */ + +/**jsdoc + * The "Zone" {@link Entities.EntityType|EntityType} is a volume of lighting effects and avatar permissions. + * 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 {ShapeType} shapeType="box" - The shape of the volume in which the zone's lighting effects and avatar + * permissions have effect. Reverts to the default value if set to "none", or set to "compound" + * and compoundShapeURL is "". + * @property {string} compoundShapeURL="" - The OBJ file to use for the compound shape if shapeType is + * "compound". + * + * @property {string} keyLightMode="inherit" - Configures the key light in the zone. Possible values:
+ * "inherit": The key light from any enclosing zone continues into this zone.
+ * "disabled": The key light from any enclosing zone and the key light of this zone are disabled in this + * zone.
+ * "enabled": The key light properties of this zone are enabled, overriding the key light of from any + * enclosing zone. + * @property {Entities.KeyLight} keyLight - The key light properties of the zone. + * + * @property {string} ambientLightMode="inherit" - Configures the ambient light in the zone. Possible values:
+ * "inherit": The ambient light from any enclosing zone continues into this zone.
+ * "disabled": The ambient light from any enclosing zone and the ambient light of this zone are disabled in + * this zone.
+ * "enabled": The ambient light properties of this zone are enabled, overriding the ambient light from any + * enclosing zone. + * @property {Entities.AmbientLight} ambientLight - The ambient light properties of the zone. + * + * @property {string} skyboxMode="inherit" - Configures the skybox displayed in the zone. Possible values:
+ * "inherit": The skybox from any enclosing zone is dislayed in this zone.
+ * "disabled": The skybox from any enclosing zone and the skybox of this zone are disabled in this zone.
+ * "enabled": The skybox properties of this zone are enabled, overriding the skybox from any enclosing zone. + * @property {Entities.Skybox} skybox - The skybox properties of the zone. + * + * @property {string} hazeMode="inherit" - Configures the haze in the zone. Possible values:
+ * "inherit": The haze from any enclosing zone continues into this zone.
+ * "disabled": The haze from any enclosing zone and the haze of this zone are disabled in this zone.
+ * "enabled": The haze properties of this zone are enabled, overriding the haze from any enclosing zone. + * @property {Entities.Haze} haze - The haze properties of the zone. + * + * @property {boolean} flyingAllowed=true - If true then visitors can fly in the zone; otherwise they cannot. + * @property {boolean} ghostingAllowed=true - If true then visitors with avatar collisions turned off will not + * collide with content in the zone; otherwise visitors will always collide with content in the zone. + + * @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.
+ * 
+ * function filter(properties) {
+ *     // Test and edit properties object values,
+ *     // e.g., properties.modelURL, as required.
+ *     return properties;
+ * }
+ *
+ * + * @example Create a zone that casts a red key light along the x-axis. + * var zone = Entities.addEntity({ + * type: "Zone", + * position: MyAvatar.position, + * dimensions: { x: 100, y: 100, z: 100 }, + * keyLightMode: "enabled", + * keyLight: { + * "color": { "red": 255, "green": 0, "blue": 0 }, + * "direction": { "x": 1, "y": 0, "z": 0 } + * }, + * lifetime: 300 // Delete after 5 minutes. + * }); + */ + QScriptValue EntityItemProperties::copyToScriptValue(QScriptEngine* engine, bool skipDefaults, bool allowUnknownCreateTime, bool strictSemantics) const { // If strictSemantics is true and skipDefaults is false, then all and only those properties are copied for which the property flag // is included in _desiredProperties, or is one of the specially enumerated ALWAYS properties below. @@ -465,7 +1066,7 @@ QScriptValue EntityItemProperties::copyToScriptValue(QScriptEngine* engine, bool COPY_PROXY_PROPERTY_TO_QSCRIPTVALUE_GETTER(PROP_DYNAMIC, dynamic, collisionsWillMove, getDynamic()); // legacy support COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_HREF, href); COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_DESCRIPTION, description); - COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_FACE_CAMERA, faceCamera); + COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_FACE_CAMERA, faceCamera); // Text only. COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_ACTION_DATA, actionData); COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_LOCKED, locked); COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_USER_DATA, userData); @@ -486,7 +1087,7 @@ QScriptValue EntityItemProperties::copyToScriptValue(QScriptEngine* engine, bool COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_NAME, name); COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_COLLISION_SOUND_URL, collisionSoundURL); - // Boxes, Spheres, Light, Line, Model(??), Particle, PolyLine + // Light, Line, Model, ParticleEffect, PolyLine, Shape COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_COLOR, color); // Particles only @@ -534,12 +1135,15 @@ QScriptValue EntityItemProperties::copyToScriptValue(QScriptEngine* engine, bool if (_type == EntityTypes::Model || _type == EntityTypes::Zone || _type == EntityTypes::ParticleEffect) { COPY_PROPERTY_TO_QSCRIPTVALUE_GETTER(PROP_SHAPE_TYPE, shapeType, getShapeTypeAsString()); } + + // FIXME: Shouldn't provide a shapeType property for Box and Sphere entities? if (_type == EntityTypes::Box) { COPY_PROPERTY_TO_QSCRIPTVALUE_GETTER(PROP_SHAPE_TYPE, shapeType, QString("Box")); } if (_type == EntityTypes::Sphere) { COPY_PROPERTY_TO_QSCRIPTVALUE_GETTER(PROP_SHAPE_TYPE, shapeType, QString("Sphere")); } + if (_type == EntityTypes::Box || _type == EntityTypes::Sphere || _type == EntityTypes::Shape) { COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_SHAPE, shape); } @@ -618,13 +1222,21 @@ QScriptValue EntityItemProperties::copyToScriptValue(QScriptEngine* engine, bool if (_type == EntityTypes::Line || _type == EntityTypes::PolyLine) { COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_LINE_WIDTH, lineWidth); COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_LINE_POINTS, linePoints); - COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_NORMALS, normals); - COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_STROKE_COLORS, strokeColors); - COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_STROKE_WIDTHS, strokeWidths); - COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_TEXTURES, textures); - COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_IS_UV_MODE_STRETCH, isUVModeStretch); + COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_NORMALS, normals); // Polyline only. + COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_STROKE_COLORS, strokeColors); // Polyline only. + COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_STROKE_WIDTHS, strokeWidths); // Polyline only. + COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_TEXTURES, textures); // Polyline only. + COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_IS_UV_MODE_STRETCH, isUVModeStretch); // Polyline only. } + /**jsdoc + * The axis-aligned bounding box of an entity. + * @typedef Entities.BoundingBox + * @property {Vec3} brn - The bottom right near (minimum axes values) corner of the AA box. + * @property {Vec3} tfl - The top far left (maximum axes values) corner of the AA box. + * @property {Vec3} center - The center of the AA box. + * @property {Vec3} dimensions - The dimensions of the AA box. + */ if (!skipDefaults && !strictSemantics) { AABox aaBox = getAABox(); QScriptValue boundingBox = engine->newObject(); @@ -646,6 +1258,7 @@ QScriptValue EntityItemProperties::copyToScriptValue(QScriptEngine* engine, bool COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_PARENT_ID, parentID); COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_PARENT_JOINT_INDEX, parentJointIndex); + COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_QUERY_AA_CUBE, queryAACube); COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_LOCAL_POSITION, localPosition); @@ -654,13 +1267,23 @@ QScriptValue EntityItemProperties::copyToScriptValue(QScriptEngine* engine, bool COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_LOCAL_ANGULAR_VELOCITY, localAngularVelocity); COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_LOCAL_DIMENSIONS, localDimensions); - COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_CLIENT_ONLY, clientOnly); - COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_OWNING_AVATAR_ID, owningAvatarID); + COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_CLIENT_ONLY, clientOnly); // Gettable but not settable + COPY_PROPERTY_TO_QSCRIPTVALUE(PROP_OWNING_AVATAR_ID, owningAvatarID); // Gettable but not settable // Rendering info if (!skipDefaults && !strictSemantics) { QScriptValue renderInfo = engine->newObject(); + /**jsdoc + * Information on how an entity is rendered. Properties are only filled in for Model entities; other + * entity types have an empty object, {}. + * @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 {boolean} hasTransparent - Is true if any of the textures has transparency. + * @property {number} drawCalls - The number of draw calls required to render the entity. + */ // currently only supported by models if (_type == EntityTypes::Model) { renderInfo.setProperty("verticesCount", (int)getRenderInfoVertexCount()); // FIXME - theoretically the number of vertex could be > max int @@ -673,6 +1296,7 @@ QScriptValue EntityItemProperties::copyToScriptValue(QScriptEngine* engine, bool COPY_PROPERTY_TO_QSCRIPTVALUE_GETTER_NO_SKIP(renderInfo, renderInfo); // Gettable but not settable } + // FIXME: These properties should already have been set above. properties.setProperty("clientOnly", convertScriptValue(engine, getClientOnly())); properties.setProperty("owningAvatarID", convertScriptValue(engine, getOwningAvatarID())); diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h index d1b321dbca..9a752cbc76 100644 --- a/libraries/entities/src/EntityScriptingInterface.h +++ b/libraries/entities/src/EntityScriptingInterface.h @@ -72,7 +72,15 @@ void RayToEntityIntersectionResultFromScriptValue(const QScriptValue& object, Ra /**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. + * * @namespace Entities + * @property {number} currentAvatarEnergy - Deprecated + * @property {number} costMultiplier - Deprecated + * @property {Uuid} keyboardFocusEntity - Get or set the {@link Entities.EntityType|Web} entity that has keyboard focus. + * If no entity has keyboard focus, get returns null; set to null or {@link Uuid|Uuid.NULL} to + * clear keyboard focus. */ /// handles scripting of Entity commands from JS passed to assigned clients class EntityScriptingInterface : public OctreeScriptingInterface, public Dependency { diff --git a/libraries/entities/src/EntityTypes.h b/libraries/entities/src/EntityTypes.h index 316bf2b813..6101c4608b 100644 --- a/libraries/entities/src/EntityTypes.h +++ b/libraries/entities/src/EntityTypes.h @@ -35,6 +35,45 @@ typedef EntityItemPointer (*EntityTypeFactory)(const EntityItemID& entityID, con class EntityTypes { public: + /**jsdoc + *

An entity may be one of the following types:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
ValueDescriptionProperties
BoxA rectangular prism. This is identical to the Shape EntityType except + * that it is always created with an initial shape property value of "Cube".{@link Entities.EntityProperties-Box|EntityProperties-Box}
LightA local lighting effect.{@link Entities.EntityProperties-Light|EntityProperties-Light}
LineA sequence of one or more simple straight lines.{@link Entities.EntityProperties-Line|EntityProperties-Line}
ModelA mesh model from an FBX or OBJ file.{@link Entities.EntityProperties-Model|EntityProperties-Model}
ParticleEffectA particle system that can be used to simulate things such as fire, + * smoke, snow, magic spells, etc.{@link Entities.EntityProperties-ParticleEffect|EntityProperties-ParticleEffect}
PolyLineA sequence of one or more textured straight lines.{@link Entities.EntityProperties-PolyLine|EntityProperties-PolyLine}
PolyVoxA set of textured voxels.{@link Entities.EntityProperties-PolyVox|EntityProperties-PolyVox}
ShapeA basic entity such as a cube. + * See also, the Box and Sphere entity types.{@link Entities.EntityProperties-Shape|EntityProperties-Shape}
SphereA sphere. This is identical to the Shape EntityType except that it is + * always created with an initial shape property value of "Sphere".{@link Entities.EntityProperties-Sphere|EntityProperties-Sphere}
TextA pane of text oriented in space.{@link Entities.EntityProperties-Text|EntityProperties-Text}
WebA browsable Web page.{@link Entities.EntityProperties-Web|EntityProperties-Web}
ZoneA volume of lighting effects and avatar permissions.{@link Entities.EntityProperties-Zone|EntityProperties-Zone}
+ * @typedef {string} Entities.EntityType + */ typedef enum EntityType_t { Unknown, Model, diff --git a/libraries/entities/src/HazePropertyGroup.h b/libraries/entities/src/HazePropertyGroup.h index 939391caf9..1437a5fe12 100644 --- a/libraries/entities/src/HazePropertyGroup.h +++ b/libraries/entities/src/HazePropertyGroup.h @@ -40,6 +40,35 @@ static const float INITIAL_HAZE_BACKGROUND_BLEND{ 0.0f }; static const float INITIAL_KEY_LIGHT_RANGE{ 1000.0f }; 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. + * @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 + * color is haze. + * @property {Color} hazeColor=128,154,179 - The color of the haze when looking away from the key light. + * @property {boolean} hazeEnableGlare=false - If true then the haze is colored with glare from the key light; + * hazeGlareColor and hazeGlareAngle are used. + * @property {Color} hazeGlareColor=255,299,179 - The color of the haze when looking towards the key light. + * @property {number} hazeGlareAngle=20 - The angle in degrees across the circle around the key light that the glare color and + * haze color are blended 50/50. + * + * @property {boolean} hazeAltitudeEffect=false - If true then haze decreases with altitude as defined by the + * entity's local coordinate system; hazeBaseRef and hazeCeiling are used. + * @property {number} hazeBaseRef=0 - The y-azis value in the entity's local coordinate system at which the haze density starts + * reducing with altitude. + * @property {number} hazeCeiling=200 - The y-axis value in the entity's local coordinate system at which the haze density has + * reduced to 5%. + * + * @property {number} hazeBackgroundBlend=0 - The proportion of the skybox image to show through the haze: 0.0 + * displays no skybox image; 1.0 displays no haze. + * + * @property {boolean} hazeAttenuateKeyLight=false - Currently not supported. + * @property {number} hazeKeyLightRange=1000 - Currently not supported. + * @property {number} hazeKeyLightAltitude=200 - Currently not supported. + */ class HazePropertyGroup : public PropertyGroup { public: // EntityItemProperty related helpers diff --git a/libraries/entities/src/KeyLightPropertyGroup.h b/libraries/entities/src/KeyLightPropertyGroup.h index f33ebb282d..dea18f4708 100644 --- a/libraries/entities/src/KeyLightPropertyGroup.h +++ b/libraries/entities/src/KeyLightPropertyGroup.h @@ -27,6 +27,13 @@ class OctreePacketData; class EntityTreeElementExtraEncodeData; class ReadBitstreamToTreeParams; +/**jsdoc + * 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. + * @property {Vec3} direction=0,-1,0 - The direction the light is shining. + */ class KeyLightPropertyGroup : public PropertyGroup { public: // EntityItemProperty related helpers diff --git a/libraries/entities/src/PolyVoxEntityItem.h b/libraries/entities/src/PolyVoxEntityItem.h index 47d2a4b4e1..7843a929cb 100644 --- a/libraries/entities/src/PolyVoxEntityItem.h +++ b/libraries/entities/src/PolyVoxEntityItem.h @@ -59,6 +59,25 @@ class PolyVoxEntityItem : public EntityItem { virtual int getOnCount() const { return 0; } + /**jsdoc + *

A PolyVoxSurfaceStyle may be one of the following:

+ * + * + * + * + * + * + * + * + * + * + *
ValueTypeDescription
0Marching cubes.Chamfered edges. Open volume. + * Joins neighboring PolyVox entities reasonably well.
1Cubic.Square edges. Open volume. + * Joins neighboring PolyVox entities cleanly.
2Edged cubic.Square edges. Enclosed volume. + * Joins neighboring PolyVox entities cleanly.
3Edged marching cubes.Chamfered edges. Enclosed volume. + * Doesn't join neighboring PolyVox entities.
+ * @typedef {number} Entities.PolyVoxSurfaceStyle + */ enum PolyVoxSurfaceStyle { SURFACE_MARCHING_CUBES, SURFACE_CUBIC, diff --git a/libraries/entities/src/ShapeEntityItem.cpp b/libraries/entities/src/ShapeEntityItem.cpp index cbcfcaaa1d..7b8f97be36 100644 --- a/libraries/entities/src/ShapeEntityItem.cpp +++ b/libraries/entities/src/ShapeEntityItem.cpp @@ -20,6 +20,33 @@ #include "ShapeEntityItem.h" namespace entity { + + /**jsdoc + *

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

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
ValueDimensionsNotes
"Circle"2DA circle oriented in 3D.
"Cube"3D
"Cone"3D
"Cylinder"3D
"Dodecahedron"3D
"Hexagon"3DA hexagonal prism.
"Icosahedron"3D
"Octagon"3DAn octagonal prism.
"Octahedron"3D
"Quad"2DA square oriented in 3D.
"Sphere"3D
"Tetrahedron"3D
"Torus"3DNot implemented.
"Triangle"3DA triangular prism.
+ * @typedef {string} Entities.Shape + */ static const std::array shapeStrings { { "Triangle", "Quad", @@ -32,7 +59,7 @@ namespace entity { "Octahedron", "Dodecahedron", "Icosahedron", - "Torus", + "Torus", // Not implemented yet. "Cone", "Cylinder" } }; diff --git a/libraries/entities/src/ShapeEntityItem.h b/libraries/entities/src/ShapeEntityItem.h index 84ce1ce57e..184dfa4dd9 100644 --- a/libraries/entities/src/ShapeEntityItem.h +++ b/libraries/entities/src/ShapeEntityItem.h @@ -103,7 +103,7 @@ public: protected: - float _alpha { 1 }; + float _alpha { 1 }; // FIXME: This property is not used. rgbColor _color; entity::Shape _shape { entity::Shape::Sphere }; diff --git a/libraries/entities/src/SkyboxPropertyGroup.h b/libraries/entities/src/SkyboxPropertyGroup.h index 8298a7b74e..d7b422bf11 100644 --- a/libraries/entities/src/SkyboxPropertyGroup.h +++ b/libraries/entities/src/SkyboxPropertyGroup.h @@ -27,6 +27,13 @@ class OctreePacketData; class EntityTreeElementExtraEncodeData; class ReadBitstreamToTreeParams; +/**jsdoc + * A skybox is defined by the following properties. + * @typedef {object} Entities.Skybox + * @property {Color} color=0,0,0 - Sets the color of the sky if url is "", otherwise modifies the + * color of the cube map image. + * @property {string} url="" - A cube map image that is used to render the sky. + */ class SkyboxPropertyGroup : public PropertyGroup { public: // EntityItemProperty related helpers diff --git a/libraries/render-utils/src/GeometryCache.cpp b/libraries/render-utils/src/GeometryCache.cpp index a082a681c9..ccfe1f2caa 100644 --- a/libraries/render-utils/src/GeometryCache.cpp +++ b/libraries/render-utils/src/GeometryCache.cpp @@ -74,32 +74,6 @@ static std::array MAPPING GeometryCache::Cylinder, } }; -/**jsdoc -*

{@link Entities} and {@link Overlays} may have the following geometrical shapes:

-* -* -* -* -* -* -* -* -* -* -* -* -* -* -* -* -* -* -* -* -* -*
ValueDescription
LineA 1D line oriented in 3 dimensions.
TriangleA triangular prism.
QuadA 2D square oriented in 3 dimensions.
HexagonA hexagonal prism.
OctagonAn octagonal prism.
CircleA 2D circle oriented in 3 dimensions.
CubeA cube.
SphereA sphere.
TetrahedronA tetrahedron.
OctahedronAn octahedron.
DodecahedronA dodecahedron.
IcosahedronAn icosahedron.
TorusA torus. Not implemented.
ConeA cone.
CylinderA cylinder.
-* @typedef {string} Shape -*/ static const std::array GEOCACHE_SHAPE_STRINGS{ { "Line", "Triangle", diff --git a/libraries/shared/src/PhysicsCollisionGroups.h b/libraries/shared/src/PhysicsCollisionGroups.h index 794f338dc5..0eb1d2021f 100644 --- a/libraries/shared/src/PhysicsCollisionGroups.h +++ b/libraries/shared/src/PhysicsCollisionGroups.h @@ -64,6 +64,24 @@ const int16_t BULLET_COLLISION_MASK_OTHER_AVATAR = BULLET_COLLISION_MASK_DEFAULT // COLLISIONLESS gets an empty mask. const int16_t BULLET_COLLISION_MASK_COLLISIONLESS = 0; +/**jsdoc + *

An entity may collide with the following types of items:

+ * + * + * + * + * + * + * + * + * + * + * + *
ValueDescription
1Static entities — non-dynamic entities with no velocity.
2Dynamic entities — entities that have their dynamic property set to + * true.
4Kinematic entities — non-dynamic entities with velocity.
8My avatar.
16Other avatars.
+ *

The values for the collision types that are enabled are added together to give the CollisionMask value.

+ * @typedef {number} Entities.CollisionMask + */ // The USER collision groups are exposed to script and can be used to generate per-object collision masks. // They are not necessarily the same as the BULLET_COLLISION_GROUPS, but we start them off with matching numbers. diff --git a/libraries/shared/src/RegisteredMetaTypes.cpp b/libraries/shared/src/RegisteredMetaTypes.cpp index 7b455beae5..c597db6dc1 100644 --- a/libraries/shared/src/RegisteredMetaTypes.cpp +++ b/libraries/shared/src/RegisteredMetaTypes.cpp @@ -689,6 +689,15 @@ QScriptValue qColorToScriptValue(QScriptEngine* engine, const QColor& color) { return object; } +/**jsdoc + * An axis-aligned cube, defined as the bottom right near (minimum axes values) corner of the cube plus the dimension of its + * sides. + * @typedef {object} AACube + * @property {number} x - X coordinate of the brn corner of the cube. + * @property {number} y - Y coordinate of the brn corner of the cube. + * @property {number} z - Z coordinate of the brn corner of the cube. + * @property {number} scale - The dimensions of each side of the cube. + */ QScriptValue aaCubeToScriptValue(QScriptEngine* engine, const AACube& aaCube) { QScriptValue obj = engine->newObject(); const glm::vec3& corner = aaCube.getCorner(); diff --git a/libraries/shared/src/ShapeInfo.cpp b/libraries/shared/src/ShapeInfo.cpp index 8cdc4bcf14..968292da87 100644 --- a/libraries/shared/src/ShapeInfo.cpp +++ b/libraries/shared/src/ShapeInfo.cpp @@ -1,6 +1,6 @@ // // ShapeInfo.cpp -// libraries/physics/src +// libraries/shared/src // // Created by Andrew Meadows 2014.10.29 // Copyright 2014 High Fidelity, Inc. @@ -15,6 +15,33 @@ #include "NumericalConstants.h" // for MILLIMETERS_PER_METER +/**jsdoc + *

A ShapeType defines the shape used for collisions or zones.

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
ValueDescription
"none"No shape.
"box"A cube.
"sphere"A sphere.
"capsule-x"A capsule (cylinder with spherical ends) oriented on the x-axis.
"capsule-y"A capsule (cylinder with spherical ends) oriented on the y-axis.
"capsule-z"A capsule (cylinder with spherical ends) oriented on the z-axis.
"cylinder-x"A cylinder oriented on the x-axis.
"cylinder-y"A cylinder oriented on the y-axis.
"cylinder-z"A cylinder oriented on the z-axis.
"hull"Not used.
"compound"A compound convex hull specified in an OBJ file.
"simple-hull"A convex hull automatically generated from the model.
"simple-compound"A compound convex hull automatically generated from the model, using + * sub-meshes.
"static-mesh"The exact shape of the model.
"plane"A plane.
+ * @typedef {string} ShapeType + */ // Originally within EntityItemProperties.cpp const char* shapeTypeNames[] = { "none", diff --git a/tools/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js index bb556814e8..3897ebea07 100644 --- a/tools/jsdoc/plugins/hifi.js +++ b/tools/jsdoc/plugins/hifi.js @@ -27,7 +27,6 @@ exports.handlers = { '../../libraries/entities/src', '../../libraries/networking/src', '../../libraries/pointers/src', - '../../libraries/render-utils/src', '../../libraries/shared/src', '../../libraries/shared/src/shared', '../../libraries/script-engine/src',