Entities

Description

The Entities API provides facilities to create and interact with entities. Entities are 2D and 3D objects that are visible to everyone and typically are persisted to the domain. For Interface scripts, the entities available are those that Interface has displayed and so knows about.

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts • Server Entity Scripts • Assignment Client Scripts

Properties

Name Type Summary
keyboardFocusEntity Uuid Get or set the Web entity that has keyboard focus. If no entity has keyboard focus, get returns null; set to null or Uuid.NULL to clear keyboard focus.

Methods

Name Return Value Summary
AABoxIntersectsCapsule boolean Check whether an axis-aligned box and a capsule intersect.
addAction Uuid Add an action to an entity. An action is registered with the physics engine and is applied every physics simulation step. Any entity may have more than one action associated with it, but only as many as will fit in an entity's actionData property.
addEntity Uuid Add a new entity with specified properties.
addEntity Uuid Add a new entity with specified properties.
appendPoint boolean Append a point to a Line entity.
callEntityClientMethod None Call a method in a specific user's client entity script from a server entity script. The entity script method must be exposed as a property in the target client entity script.
callEntityMethod None Call a method in a client entity script from a client script or client entity script, or call a method in a server entity script from a server entity script. The entity script method must be exposed as a property in the target client entity script. Additionally, if calling a server entity script, the server entity script must include the method's name in an exposed property called remotelyCallable that is an array of method names that can be called.
callEntityServerMethod None Call a method in a server entity script from a client script or client entity script. The entity script method must be exposed as a property in the target server entity script. Additionally, the target server entity script must include the method's name in an exposed property called remotelyCallable that is an array of method names that can be called.
canAdjustLocks boolean Check whether or not you can change the locked property of entities. Locked entities have their locked property set to true and cannot be edited or deleted. Whether or not you can change entities' locked properties is configured in the domain server's permissions.
canReplaceContent boolean Check whether or not you can replace the domain's content set.
canRez boolean Check whether or not you can rez (create) new entities in the domain.
canRezCertified boolean Check whether or not you can rez (create) new certified entities in the domain. Certified entities are entities that have PoP certificates.
canRezTmp boolean Check whether or not you can rez (create) new temporary entities in the domain. Temporary entities are entities with a finite lifetime property value set.
canRezTmpCertified boolean Check whether or not you can rez (create) new temporary certified entities in the domain. Temporary entities are entities with a finite lifetime property value set. Certified entities are entities that have PoP certificates.
canWriteAssets boolean Check whether or not you can make changes to the asset server's assets.
cloneEntity Uuid Create a clone of an entity. A clone can be created by a client that doesn't have rez permissions in the current domain. The entity must have its cloneable property set to true. The clone has a modified name, other properties set per its clone related-properties, and its clone-related properties are set to defaults.
deleteAction boolean Delete an action from an entity.
deleteEntity None Delete an entity.
deleteEntity None Get an entities type as a string.
dumpTree None Dumps debug information about all entities in Interface's local in-memory tree of entities it knows about to the program log.
editEntity Uuid Update an entity with specified properties.
emitScriptEvent None Send a script event over a Web entity's EventBridge to the Web page's scripts.
findClosestEntity Uuid Find the non-local entity with a position closest to a specified point and within a specified radius.
findEntities Array.<Uuid> Find all non-local entities that intersect a sphere defined by a center point and radius.
findEntitiesByName Array.<Uuid> Find all non-local entities with a particular name that intersect a sphere defined by a center point and radius.
findEntitiesByType Array.<Uuid> Find all non-local entities of a particular type that intersect a sphere defined by a center point and radius.
findEntitiesInBox Array.<Uuid> Find all non-local entities whose axis-aligned boxes intersect a search axis-aligned box defined by its minimum coordinates corner and dimensions.
findEntitiesInFrustum Array.<Uuid> Find all non-local entities whose axis-aligned boxes intersect a search frustum.
findRayIntersection Entities.RayToEntityIntersectionResult Find the first non-local entity intersected by a PickRay. Light and Zone entities are not intersected unless they've been configured as pickable using setLightsArePickable and setZonesArePickable, respectively.
getAbsoluteJointRotationInObjectFrame Quat Get the translation of a joint in a Model entity relative to the entity's position and orientation.
getAbsoluteJointTranslationInObjectFrame Vec3 Get the translation of a joint in a Model entity relative to the entity's position and orientation.
getActionArguments Entities.ActionArguments Get the arguments of an action.
getActionIDs Array.<Uuid> Get the IDs of the actions that are associated with an entity.
getChildrenIDs Array.<Uuid> Get the IDs of entities and avatars that are directly parented to an entity or avatar model. Recurse on the IDs returned by the function to get all descendants of an entity or avatar.
getChildrenIDsOfJoint Array.<Uuid> Get the IDs of entities and avatars that are directly parented to an entity or avatar model's joint.
getDrawZoneBoundaries boolean Get whether or not Zone entities' boundaries should be drawn. Currently not used.
getEntityLocalTransform Mat4 Get the object to parent transform, excluding scale, of an entity.
getEntityObject object Get the entity script object. In particular, this is useful for accessing the event bridge for a Web entity.
getEntityProperties Entities.EntityProperties Get the properties of an entity.
getEntityTransform Mat4 Get the object to world transform, excluding scale, of an entity.
getJointIndex number Get the index of a named joint in a Model entity.
getJointNames Array.<string> Get the names of all the joints in a Model entity.
getJointParent number Get the index of the parent joint.
getKeyboardFocusEntity Uuid Get the ID of the Web entity that has keyboard focus.
getLifetimeBPS number Get the entity bytes per second send rate of the client over its lifetime.
getLifetimeBPSQueued number Get the entity bytes per second queued rate of the client over its lifetime.
getLifetimeBytesQueued number Get the total bytes of entity packets queued by the client over its lifetime.
getLifetimeBytesSent number Get the total bytes of entity packets sent by the client over its lifetime.
getLifetimeInSeconds number Get the lifetime of the client from the first entity packet sent until now, in seconds.
getLifetimeInUsecs number Get the lifetime of the client from the first entity packet sent until now, in microseconds.
getLifetimePacketsQueued number Get the total number of entity packets queued by the client over its lifetime.
getLifetimePacketsSent number Get the total number of entity packets sent by the client over its lifetime.
getLifetimePPS number Get the entity packets per second send rate of the client over its lifetime.
getLifetimePPSQueued number Get the entity packets per second queued rate of the client over its lifetime.
getLightsArePickable boolean Get whether or not ray picks intersect the bounding box of Light entities. Ray picks are done using findRayIntersection, or the Picks API.
getLocalJointRotation Quat Get the local rotation of a joint in a Model entity.
getLocalJointTranslation Vec3 Get the local translation of a joint in a Model entity.
getMeshes None Get the meshes in a Model or PolyVox entity.

Deprecated: This function is deprecated and will be removed. Use the Graphics API instead.

getMultipleEntityProperties Array.<Entities.EntityProperties> Get the properties of multiple entities.
getNestableType string Get the type — entity or avatar — of an in-world item.
getPacketsPerSecond number Get the maximum number of entity packets that the client can send per second.
getPropertyInfo Entities.EntityPropertyInfo Get information about entity properties including a minimum to maximum range for numerical properties as well as property enum value.
getServerScriptStatus boolean Gets the status of server entity script attached to an entity
getStaticCertificateJSON string Get the static certificate for an entity. The static certificate contains static properties of the item which cannot be altered.
getZonesArePickable boolean Get whether or not ray picks intersect the bounding box of Zone entities. Ray picks are done using findRayIntersection, or the Picks API.
hasPacketsToSend boolean Check whether the client has entity packets waiting to be sent.
isAddedEntity boolean Check if there is an object of a given ID.
isChildOfParent boolean Check whether an entity has an entity as an ancestor (parent, parent's parent, etc.).
isLoaded boolean Check whether an entities's assets have been loaded. For example, for an Model entity the result indicates whether its textures have been loaded.
localCoordsToVoxelCoords Vec3 Convert local coordinates to voxel coordinates in a PolyVox entity. Local coordinates are relative to the minimum axes value corner of the entity, with the scale being the same as world coordinates.
localToWorldAngularVelocity Vec3
localToWorldDimensions Vec3
localToWorldPosition Vec3
localToWorldRotation Quat
localToWorldVelocity Vec3
packetsToSendCount number Get the number of entity packets the client has waiting to be sent.
queryPropertyMetadata boolean Get metadata for certain entity properties such as script and serverScripts.
queryPropertyMetadata boolean Get metadata for certain entity properties such as script and serverScripts.
reloadServerScripts boolean Reloads an entity's server entity script such that the latest version re-downloaded.
sendClickDownOnEntity None Emit a clickDownOnEntity event.
sendClickReleaseOnEntity None Emit a clickReleaseOnEntity event.
sendHoldingClickOnEntity None Emit a holdingClickOnEntity event.
sendHoverEnterEntity None Emit a hoverEnterEntity event.
sendHoverLeaveEntity None Emit a hoverLeaveEntity event.
sendHoverOverEntity None Emit a hoverOverEntity event.
sendMouseMoveOnEntity None Emit a mouseMoveOnEntity event.
sendMousePressOnEntity None Emit a mousePressOnEntity event.
sendMouseReleaseOnEntity None Emit a mouseReleaseOnEntity event.
serversExist boolean Check whether servers exist for the client to send entity packets to, i.e., whether you are connected to a domain and its entity server is working.
setAbsoluteJointRotationInObjectFrame boolean Set the rotation of a joint in a Model entity relative to the entity's position and orientation.
setAbsoluteJointTranslationInObjectFrame boolean Set the translation of a joint in a Model entity relative to the entity's position and orientation.
setAllPoints boolean Set the linePoints property of a Line entity.
setAllVoxels None Set the values of all voxels in a PolyVox entity.
setDrawZoneBoundaries None Set whether or not Zone entities' boundaries should be drawn. Currently not used.
setKeyboardFocusEntity None Set the Web entity that has keyboard focus.
setLightsArePickable None Set whether or not ray picks intersect the bounding box of Light entities. By default, Light entities are not intersected. The setting lasts for the Interface session. Ray picks are done using findRayIntersection, or the Picks API.
setLocalJointRotation boolean Set the local rotation of a joint in a Model entity.
setLocalJointRotations boolean Set the local rotations of joints in a Model entity.
setLocalJointsData boolean Set the local rotations and translations of joints in a Model entity. This is the same as calling both setLocalJointRotations and setLocalJointTranslations at the same time.
setLocalJointTranslation boolean Set the local translation of a joint in a Model entity.
setLocalJointTranslations boolean Set the local translations of joints in a Model entity.
setPacketsPerSecond None Set the maximum number of entity packets that the client can send per second.
setVoxel None Set the value of a particular voxels in a PolyVox entity.
setVoxelCapsule None Set the values of all voxels in a capsule-shaped portion of a PolyVox entity.
setVoxelsInCuboid None Set the values of all voxels in a cubic portion of a PolyVox entity.
setVoxelSphere None Set the values of all voxels in a spherical portion of a PolyVox entity.
setZonesArePickable None Set whether or not ray picks intersect the bounding box of Zone entities. By default, Light entities are not intersected. The setting lasts for the Interface session. Ray picks are done using findRayIntersection, or the Picks API.
textSize Size Calculates the size of the given text in the specified object if it is a text entity.
updateAction boolean Update an entity action.
verifyStaticCertificateProperties boolean Verify the entity's proof of provenance, i.e., that the entity's certificateID property was produced by High Fidelity signing the entity's static certificate JSON.
voxelCoordsToLocalCoords Vec3 Convert voxel coordinates in a PolyVox entity to local coordinates relative to the minimum axes value corner of the entity, with the scale being the same as world coordinates.
voxelCoordsToWorldCoords Vec3 Convert voxel coordinates in a PolyVox entity to world coordinates. Voxel coordinates are relative to the minimum axes values corner of the entity with a scale of Vec3.ONE being the dimensions of each voxel.
wantsHandControllerPointerEvents boolean Check whether an entity wants hand controller pointer events. For example, a Web entity does but a Shape entity doesn't.
worldCoordsToVoxelCoords Vec3 Convert world coordinates to voxel coordinates in a PolyVox entity. Voxel coordinates are relative to the minimum axes values corner of the entity, with a scale of Vec3.ONE being the dimensions of each voxel.
worldToLocalAngularVelocity Vec3
worldToLocalDimensions Vec3
worldToLocalPosition Vec3
worldToLocalRotation Quat
worldToLocalVelocity Vec3

Signals

Name Summary
addingEntity Triggered when an entity is added to Interface's local in-memory tree of entities it knows about. This may occur when entities are loaded upon visiting a domain, when the user rotates their view so that more entities become visible, and when any type of entity is added (e.g., by {@Entities.addEntity|addEntity}).
addingWearable Triggered when an 'wearable' entity is added to Interface's local in-memory tree of entities it knows about. This may occur when 'wearable' entities are added to avatar
canAdjustLocksChanged Triggered when your ability to change the locked property of entities changes.
canRezCertifiedChanged Triggered when your ability to rez (create) certified entities changes. Certified entities are entities that have PoP certificates.
canRezChanged Triggered when your ability to rez (create) entities changes.
canRezTmpCertifiedChanged Triggered when your ability to rez (create) temporary certified entities changes. Temporary entities are entities with a finite lifetime property value set. Certified entities are entities that have PoP certificates.
canRezTmpChanged Triggered when your ability to rez (create) temporary entities changes. Temporary entities are entities with a finite lifetime property value set.
canWriteAssetsChanged Triggered when your ability to make changes to the asset server's assets changes.
clearingEntities Triggered when you disconnect from a domain, at which time Interface's local in-memory tree of entities it knows about is cleared.
clickDownOnEntity Triggered when a mouse button is clicked while the mouse cursor is on an entity. Note: Not triggered by controller.
clickReleaseOnEntity Triggered when a mouse button is released after clicking on an entity, even if the mouse cursor has moved off the entity. Note: Not triggered by controller.
collisionWithEntity Triggered on the client that is the physics simulation owner during the collision of two entities. Note: Isn't triggered for a collision with an avatar.
deletingEntity Triggered when an entity is deleted.
deletingWearable Triggered when an 'wearable' entity is deleted.
enterEntity Triggered when an avatar enters an entity.
holdingClickOnEntity Repeatedly triggered while a mouse button continues to be held after clicking an entity, even if the mouse cursor has moved off the entity. Note: Not triggered by controller.
hoverEnterEntity Triggered when the mouse cursor or controller laser starts hovering on an entity.
hoverLeaveEntity Triggered when the mouse cursor or controller laser stops hovering over an entity.
hoverOverEntity Repeatedly triggered when the mouse cursor or controller laser moves while hovering over an entity.
leaveEntity Triggered when an avatar leaves an entity.
mouseDoublePressOffEntity Triggered when a mouse button is double-clicked while the mouse cursor is not on an entity.
mouseDoublePressOnEntity Triggered when a mouse button is double-clicked while the mouse cursor is on an entity.
mouseMoveOnEntity Repeatedly triggered while the mouse cursor or controller laser moves on an entity.
mousePressOffEntity Triggered when a mouse button is clicked while the mouse cursor is not on an entity.
mousePressOnEntity Triggered when a mouse button is clicked while the mouse cursor is on an entity, or a controller trigger is fully pressed while its laser is on an entity.
mouseReleaseOnEntity Triggered when a mouse button is released after clicking on an entity or the controller trigger is partly or fully released after pressing on an entity, even if the mouse pointer or controller laser has moved off the entity.
preload Triggered when the script starts for a user.

Note: Can only be connected to via this.preload = function (...) { ... } in the entity script.

Available in:Client Entity ScriptsServer Entity Scripts
unload Triggered when the script terminates for a user.

Note: Can only be connected to via this.unoad = function () { ... } in the entity script.

Available in:Client Entity ScriptsServer Entity Scripts
webEventReceived Triggered in when a script in a Web entity's Web page script sends an event over the script's EventBridge.

Type Definitions

ActionArguments
Type: object

Different entity action types have different arguments: some common to all actions (listed below) and some specific to each ActionType (linked to below). The arguments are accessed as an object of property names and values.

Properties

Name Type Summary
type Entities.ActionType The type of action.
tag string A string that a script can use for its own purposes.

Default Value: ""

ttl number How long the action should exist, in seconds, before it is automatically deleted. A value of 0 means that the action should not be deleted.

Default Value: 0

isMine boolean Is true if you created the action during your current Interface session, false otherwise. Read-only.

Default Value: true

::no-motion-state boolean Is present when the entity hasn't been registered with the physics engine yet (e.g., if the action hasn't been properly configured), otherwise undefined. Read-only.
::active boolean Is true when the action is modifying the entity's motion, false otherwise. Is present once the entity has been registered with the physics engine, otherwise undefined. Read-only.
::motion-type Entities.PhysicsMotionType How the entity moves with the action. Is present once the entity has been registered with the physics engine, otherwise undefined. Read-only.

See:

ActionArguments-BallSocket
Type: object

The "ball-socket" ActionType connects two entities with a ball and socket joint. It has arguments in addition to the common ActionArguments.

Properties

Name Type Summary
pivot Vec3 The local offset of the joint relative to the entity's position.

Default Value: 0,0,0

otherEntityID Uuid The ID of the other entity that is connected to the joint.

Default Value: null

otherPivot Vec3 The local offset of the joint relative to the other entity's position.

Default Value: 0,0,0

ActionArguments-ConeTwist
Type: object

The "cone-twist" ActionType connects two entities with a joint that can move through a cone and can twist. It has arguments in addition to the common ActionArguments.

Properties

Name Type Summary
pivot Vec3 The local offset of the joint relative to the entity's position.

Default Value: 0,0,0

axis Vec3 The axis of the entity that moves through the cone. Must be a non-zero vector.

Default Value: 1,0,0

otherEntityID Uuid The ID of the other entity that is connected to the joint.

Default Value: null

otherPivot Vec3 The local offset of the joint relative to the other entity's position.

Default Value: 0,0,0

otherAxis Vec3 The axis of the other entity that moves through the cone. Must be a non-zero vector.

Default Value: 1,0,0

swingSpan1 number The angle through which the joint can move in one axis of the cone, in radians.

Default Value: 6.238

swingSpan2 number The angle through which the joint can move in the other axis of the cone, in radians.

Default Value: 6.238

twistSpan number The angle through with the joint can twist, in radians.

Default Value: 6.238

ActionArguments-FarGrab
Type: object

The "far-grab" ActionType moves and rotates an entity to a target position and orientation, optionally relative to another entity. Collisions between the entity and the user's avatar are disabled during the far-grab. It has arguments in addition to the common ActionArguments.

Properties

Name Type Summary
targetPosition Vec3 The target position.

Default Value: 0,0,0

targetRotation Quat The target rotation.

Default Value: 0,0,0,1

otherID Uuid If an entity ID, the targetPosition and targetRotation are relative to this entity's position and rotation.

Default Value: null

linearTimeScale number Controls how long it takes for the entity's position to catch up with the target position. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the action is applied using an exponential decay.

Default Value: 3.4e+38

angularTimeScale number Controls how long it takes for the entity's orientation to catch up with the target orientation. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the action is applied using an exponential decay.

Default Value: 3.4e+38

ActionArguments-Hinge
Type: object

The "hinge" ActionType lets an entity pivot about an axis or connects two entities with a hinge joint. It has arguments in addition to the common ActionArguments.

Properties

Name Type Summary
pivot Vec3 The local offset of the joint relative to the entity's position.

Default Value: 0,0,0

axis Vec3 The axis of the entity that it pivots about. Must be a non-zero vector.

Default Value: 1,0,0

otherEntityID Uuid The ID of the other entity that is connected to the joint, if any. If none is specified then the first entity simply pivots about its specified axis.

Default Value: null

otherPivot Vec3 The local offset of the joint relative to the other entity's position.

Default Value: 0,0,0

otherAxis Vec3 The axis of the other entity that it pivots about. Must be a non-zero vector.

Default Value: 1,0,0

low number The most negative angle that the hinge can take, in radians.

Default Value: -6.283

high number The most positive angle that the hinge can take, in radians.

Default Value: 6.283

angle number The current angle of the hinge. Read-only.

Default Value: 0

ActionArguments-Hold
Type: object

The "hold" ActionType positions and rotates an entity relative to an avatar's hand. Collisions between the entity and the user's avatar are disabled during the hold. It has arguments in addition to the common ActionArguments.

Properties

Name Type Summary
holderID Uuid The ID of the avatar holding the entity.

Default Value: MyAvatar.sessionUUID

relativePosition Vec3 The target position relative to the avatar's hand.

Default Value: 0,0,0

relativeRotation Vec3 The target rotation relative to the avatar's hand.

Default Value: 0,0,0,1

timeScale number Controls how long it takes for the entity's position and rotation to catch up with the target. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the action is applied using an exponential decay.

Default Value: 3.4e+38

hand string The hand holding the entity: "left" or "right".

Default Value: right

kinematic boolean If true, the entity is made kinematic during the action; the entity won't lag behind the hand but constraint actions such as "hinge" won't act properly.

Default Value: false

kinematicSetVelocity boolean If true and kinematic is true, the entity's velocity property will be set during the action, e.g., so that other scripts may use the value.

Default Value: false

ignoreIK boolean If true, the entity follows the HMD controller rather than the avatar's hand.

Default Value: false

ActionArguments-Offset
Type: object

The "offset" ActionType moves an entity so that it is a set distance away from a target point. It has arguments in addition to the common ActionArguments.

Properties

Name Type Summary
pointToOffsetFrom Vec3 The target point to offset the entity from.

Default Value: 0,0,0

linearDistance number The distance away from the target point to position the entity.

Default Value: 0

linearTimeScale number Controls how long it takes for the entity's position to catch up with the target offset. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the action is applied using an exponential decay.

Default Value: 34e+38

ActionArguments-Slider
Type: object

The "slider" ActionType lets an entity slide and rotate along an axis, or connects two entities that slide and rotate along a shared axis. It has arguments in addition to the common ActionArguments.

Properties

Name Type Summary
point Vec3 The local position of a point in the entity that slides along the axis.

Default Value: 0,0,0

axis Vec3 The axis of the entity that slides along the joint. Must be a non-zero vector.

Default Value: 1,0,0

otherEntityID Uuid The ID of the other entity that is connected to the joint, if any. If non is specified then the first entity simply slides and rotates about its specified axis.

Default Value: null

otherPoint Vec3 The local position of a point in the other entity that slides along the axis.

Default Value: 0,0,0

axis Vec3 The axis of the other entity that slides along the joint. Must be a non-zero vector.

Default Value: 1,0,0

linearLow number The most negative linear offset from the entity's initial point that the entity can have along the slider.

Default Value: 1.17e-38

linearHigh number The most positive linear offset from the entity's initial point that the entity can have along the slider.

Default Value: 3.40e+38

angularLow number The most negative angle that the entity can rotate about the axis if the action involves only one entity, otherwise the most negative angle the rotation can be between the two entities. In radians.

Default Value: -6.283

angularHigh number The most positive angle that the entity can rotate about the axis if the action involves only one entity, otherwise the most positive angle the rotation can be between the two entities. In radians.

Default Value: 6.283

linearPosition number The current linear offset the entity is from its initial point if the action involves only one entity, otherwise the linear offset between the two entities' action points. Read-only.

Default Value: 0

angularPosition number The current angular offset of the entity from its initial rotation if the action involves only one entity, otherwise the angular offset between the two entities. Read-only.

Default Value: 0

ActionArguments-Tractor
Type: object

The "tractor" ActionType moves and rotates an entity to a target position and orientation, optionally relative to another entity. It has arguments in addition to the common ActionArguments.

Properties

Name Type Summary
targetPosition Vec3 The target position.

Default Value: 0,0,0

targetRotation Quat The target rotation.

Default Value: 0,0,0,1

otherID Uuid If an entity ID, the targetPosition and targetRotation are relative to this entity's position and rotation.

Default Value: null

otherJointIndex Uuid If an entity JointIndex, the targetPosition and targetRotation are relative to this entity's joint's position and rotation.

Default Value: null

linearTimeScale number Controls how long it takes for the entity's position to catch up with the target position. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the action is applied using an exponential decay.

Default Value: 3.4e+38

angularTimeScale number Controls how long it takes for the entity's orientation to catch up with the target orientation. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the action is applied using an exponential decay.

Default Value: 3.4e+38

ActionArguments-TravelOriented
Type: object

The "travel-oriented" ActionType orients an entity to align with its direction of travel. It has arguments in addition to the common ActionArguments.

Properties

Name Type Summary
forward Vec3 The axis of the entity to align with the entity's direction of travel.

Default Value: 0,0,0

angularTimeScale number Controls how long it takes for the entity's orientation to catch up with the direction of travel. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the action is applied using an exponential decay.

Default Value: 0.1

ActionType
Type: string

An entity action may be one of the following types:

ValueTypeDescriptionArguments
"far-grab"Avatar action Moves and rotates an entity to a target position and orientation, optionally relative to another entity. Collisions between the entity and the user's avatar are disabled during the far-grab. Entities.ActionArguments-FarGrab
"hold"Avatar action Positions and rotates an entity relative to an avatar's hand. Collisions between the entity and the user's avatar are disabled during the hold. Entities.ActionArguments-Hold
"offset"Object action Moves an entity so that it is a set distance away from a target point. Entities.ActionArguments-Offset
"tractor"Object action Moves and rotates an entity to a target position and orientation, optionally relative to another entity. Entities.ActionArguments-Tractor
"travel-oriented"Object action Orients an entity to align with its direction of travel. Entities.ActionArguments-TravelOriented
"hinge"Object constraint Lets an entity pivot about an axis or connects two entities with a hinge joint. Entities.ActionArguments-Hinge
"slider"Object constraint Lets an entity slide and rotate along an axis, or connects two entities that slide and rotate along a shared axis. ActionArguments-Slider
"cone-twist"Object constraint Connects two entities with a joint that can move through a cone and can twist. Entities.ActionArguments-ConeTwist
"ball-socket"Object constraint Connects two entities with a ball and socket joint. Entities.ActionArguments-BallSocket
"spring"Synonym for "tractor". Legacy value.

AmbientLight
Type: object

Ambient light is defined by the following properties.

Properties

Name Type Summary
ambientIntensity number The intensity of the light.

Default Value: 0.5

ambientURL string A cube map image that defines the color of the light coming from each direction. If "" then the entity's Skybox url property value is used, unless that also is "" in which case the entity's ambientLightMode property is set to "inherit".

Default Value: ""

AnimationProperties
Type: object

The AnimationProperties are used to configure an animation.

Properties

Name Type Summary
url string The URL of the FBX file that has the animation.

Default Value: ""

fps number The speed in frames/s that the animation is played at.

Default Value: 30

firstFrame number The first frame to play in the animation.

Default Value: 0

lastFrame number The last frame to play in the animation.

Default Value: 100000

currentFrame number The current frame being played in the animation.

Default Value: 0

running boolean If true then the animation should play.

Default Value: false

loop boolean If true then the animation should be continuously repeated in a loop.

Default Value: true

hold boolean If true then the rotations and translations of the last frame played should be maintained when the animation stops playing.

Default Value: false

Bloom
Type: object

Bloom is defined by the following properties.

Properties

Name Type Summary
bloomIntensity number The intensity of the bloom effect.

Default Value: 0.25

bloomThreshold number The threshold for the bloom effect.

Default Value: 0.7

bloomSize number The size of the bloom effect.

Default Value: 0.9

BoundingBox
Type: object

The axis-aligned bounding box of an entity.

Properties

Name Type Summary
brn Vec3 The bottom right near (minimum axes values) corner of the AA box.
tfl Vec3 The top far left (maximum axes values) corner of the AA box.
center Vec3 The center of the AA box.
dimensions Vec3 The dimensions of the AA box.
CollisionMask
Type: number

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. For example, a value of 31 means that an entity will collide with all item types.

EntityProperties
Type: object

Different entity types have different properties: some common to all entities (listed below) and some specific to each EntityType (linked to below). The properties are accessed as an object of property names and values.

Properties

Name Type Summary
id Uuid The ID of the entity. Read-only.
name string A name for the entity. Need not be unique.

Default Value: ""

type Entities.EntityType The entity type. You cannot change the type of an entity after it's created. (Though its value may switch among "Box", "Shape", and "Sphere" depending on changes to the shape property set for entities of these types.) Read-only.
entityHostType EntityHostType How this entity will behave, including if and how it is sent to other people. The value can only be set at entity creation by using the entityHostType parameter in Entities.addEntity. Read-only.

Default Value: "domain"

avatarEntity boolean If true then the entity is an avatar entity; An avatar entity follows you to each domain you visit, rendering at the same world coordinates unless it's parented to your avatar. Value cannot be changed after the entity is created.
The value can only be set at entity creation by using the entityHostType parameter in Entities.addEntity. clientOnly is an alias. Read-only.

Default Value: false

localEntity boolean If true then the entity is a local entity; Local entities only render for you and are not sent over the wire. Value cannot be changed after the entity is created.
The value can only be set at entity creation by using the entityHostType parameter in Entities.addEntity. Read-only.

Default Value: false

owningAvatarID Uuid The session ID of the owning avatar if avatarEntity is true, otherwise Uuid.NULL. Read-only.

Default Value: Uuid.NULL

created string The UTC date and time that the entity was created, in ISO 8601 format as yyyy-MM-ddTHH:mm:ssZ. Read-only.
age number The age of the entity in seconds since it was created. Read-only.
ageAsText string The age of the entity since it was created, formatted as h hours m minutes s seconds.
lifetime number How long an entity lives for, in seconds, before being automatically deleted. A value of -1 means that the entity lives for ever.

Default Value: -1

lastEdited number When the entity was last edited, expressed as the number of microseconds since 1970-01-01T00:00:00 UTC. Read-only.
lastEditedBy Uuid The session ID of the avatar or agent that most recently created or edited the entity. Read-only.
locked boolean 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.

Default Value: false

visible boolean Whether or not the entity is rendered. If true then the entity is rendered.

Default Value: true

canCastShadow boolean Whether or not the entity can cast a shadow. Currently applicable only to Model and Shape entities. Shadows are cast if inside a Zone entity with castShadows enabled in its keyLight property.

Default Value: true

isVisibleInSecondaryCamera boolean Whether or not the entity is rendered in the secondary camera. If true then the entity is rendered.

Default Value: true

renderLayer RenderLayer In which layer this entity renders.

Default Value: "world"

primitiveMode PrimitiveMode How this entity's geometry is rendered.

Default Value: "solid"

ignorePickIntersection boolean If true, picks ignore the entity.

Default Value: false

position Vec3 The position of the entity.

Default Value: 0,0,0

rotation Quat The orientation of the entity with respect to world coordinates.

Default Value: 0,0,0,1

registrationPoint Vec3 The point in the entity that is set to the entity's position and is rotated about, Vec3.ZEROVec3.ONE. A value of Vec3.ZERO is the entity's minimum x, y, z corner; a value of Vec3.ONE is the entity's maximum x, y, z corner.

Default Value: 0.5,0.5,0.5

naturalPosition Vec3 The center of the entity's unscaled mesh model if it has one, otherwise Vec3.ZERO. Read-only.

Default Value: 0,0,0

naturalDimensions Vec3 The dimensions of the entity's unscaled mesh model if it has one, otherwise Vec3.ONE. Read-only.
velocity Vec3 The linear velocity of the entity in m/s with respect to world coordinates.

Default Value: 0,0,0

damping number How much to slow down the linear velocity of an entity over time, 0.01.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.

Default Value: 0.39347

angularVelocity Vec3 The angular velocity of the entity in rad/s with respect to its axes, about its registration point.

Default Value: 0,0,0

angularDamping number How much to slow down the angular velocity of an entity over time, 0.01.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.

Default Value: 0.39347

gravity Vec3 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 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.

Default Value: 0,0,0

acceleration Vec3 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 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.

Default Value: 0,0,0

restitution number The "bounciness" of an entity when it collides, 0.00.99. The higher the value, the more bouncy.

Default Value: 0.5

friction number How much to slow down an entity when it's moving against another, 0.010.0. The higher the value, the more quickly it slows down. Examples: 0.1 for ice, 0.9 for sandpaper.

Default Value: 0.5

density number The density of the entity in kg/m3, 100 for balsa wood – 10000 for silver. The density is used in conjunction with the entity's bounding box volume to work out its mass in the application of physics.

Default Value: 1000

collisionless boolean Whether or not the entity should collide with items per its collisionMask property. If true then the entity does not collide. A synonym is ignoreForCollisions.

Default Value: false

collisionMask Entities.CollisionMask What types of items the entity should collide with.

Default Value: 31

collidesWith string Synonym for collisionMask, in text format.

Default Value: "static,dynamic,kinematic,myAvatar,otherAvatar,"

collisionSoundURL string The sound to play when the entity experiences a collision. Valid file formats are as per the SoundCache object.

Default Value: ""

dynamic boolean Whether or not the entity should be affected by collisions. If true then the entity's movement is affected by collisions. A synonym is collisionsWillMove.

Default Value: false

href string A "hifi://" metaverse address that a user is taken to when they click on the entity.

Default Value: ""

description string A description of the href property value.

Default Value: ""

userData string Used to store extra data about the entity in JSON format. WARNING: Other apps such as the Create app can also use this property, so make sure you handle data stored by other apps — edit only your bit and leave the rest of the data intact. You can use JSON.parse() to parse the string into a JavaScript object which you can manipulate the properties of, and use JSON.stringify() to convert the object into a string to put in the property.

Default Value: ""

script string The URL of the client entity script, if any, that is attached to the entity.

Default Value: ""

scriptTimestamp number Intended to be used to indicate when the client entity script was loaded. Should be an integer number of milliseconds since midnight GMT on January 1, 1970 (e.g., as supplied by Date.now(). If you update the property's value, the script is re-downloaded and reloaded. This is how the "reload" button beside the "script URL" field in properties tab of the Create app works.

Default Value: 0

serverScripts string The URL of the server entity script, if any, that is attached to the entity.

Default Value: ""

parentID Uuid The ID of the entity or avatar that this entity is parented to. Uuid.NULL if the entity is not parented.

Default Value: Uuid.NULL

parentJointIndex number 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.

Default Value: 65535

localPosition Vec3 The position of the entity relative to its parent if the entity is parented, otherwise the same value as position. If the entity is parented to an avatar and is an avatarEntity so that it scales with the avatar, this value remains the original local position value while the avatar scale changes.

Default Value: 0,0,0

localRotation Quat The rotation of the entity relative to its parent if the entity is parented, otherwise the same value as rotation.

Default Value: 0,0,0,1

localVelocity Vec3 The velocity of the entity relative to its parent if the entity is parented, otherwise the same value as velocity.

Default Value: 0,0,0

localAngularVelocity Vec3 The angular velocity of the entity relative to its parent if the entity is parented, otherwise the same value as position.

Default Value: 0,0,0

localDimensions Vec3 The dimensions of the entity. If the entity is parented to an avatar and is an avatarEntity so that it scales with the avatar, this value remains the original dimensions value while the avatar scale changes.
boundingBox Entities.BoundingBox The axis-aligned bounding box that tightly encloses the entity. Read-only.
queryAACube AACube 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.
actionData string Base-64 encoded compressed dump of the actions associated with the entity. This property is typically not used in scripts directly; rather, functions that manipulate an entity's actions update it. The size of this property increases with the number of actions. Because this property value has to fit within a High Fidelity datagram packet there is a limit to the number of actions that an entity can have, and edits which would result in overflow are rejected. Read-only.

Default Value: ""

renderInfo Entities.RenderInfo Information on the cost of rendering the entity. Currently information is only provided for Model entities. Read-only.
cloneable boolean If true then the entity can be cloned via Entities.cloneEntity.

Default Value: false

cloneLifetime number The entity lifetime for clones created from this entity.

Default Value: 300

cloneLimit number The total number of clones of this entity that can exist in the domain at any given time.

Default Value: 0

cloneDynamic boolean If true then clones created from this entity will have their dynamic property set to true.

Default Value: false

cloneAvatarEntity boolean If true then clones created from this entity will be created as avatar entities: their avatarEntity property will be set to true.

Default Value: false

cloneOriginID Uuid The ID of the entity that this entity was cloned from.
grab Entities.Grab The grab-related properties.
itemName string Certifiable name of the Marketplace item.

Default Value: ""

itemDescription string Certifiable description of the Marketplace item.

Default Value: ""

itemCategories string Certifiable category of the Marketplace item.

Default Value: ""

itemArtist string Certifiable artist that created the Marketplace item.

Default Value: ""

itemLicense string Certifiable license URL for the Marketplace item.

Default Value: ""

limitedRun number Certifiable maximum integer number of editions (copies) of the Marketplace item allowed to be sold.

Default Value: 4294967295

editionNumber number Certifiable integer edition (copy) number or the Marketplace item. Each copy sold in the Marketplace is numbered sequentially, starting at 1.

Default Value: 0

entityInstanceNumber number 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.

Default Value: 0

marketplaceID string Certifiable UUID for the Marketplace item, as used in the URL of the item's download and its Marketplace Web page.

Default Value: ""

certificateID string Hash of the entity's static certificate JSON, signed by the artist's private key.

Default Value: ""

staticCertificateVersion number The version of the method used to generate the certificateID.

Default Value: 0

See:

EntityProperties-Box
Type: object

The "Box" EntityType is the same as the "Shape" EntityType except that its shape value is always set to "Cube" when the entity is created. If its shape property value is subsequently changed then the entity's type will be reported as "Sphere" if the shape is set to "Sphere", otherwise it will be reported as "Shape".

EntityProperties-Gizmo
Type: object

The "Gizmo" EntityType displays an entity that could be used as UI. It has properties in addition to the common EntityProperties.

Properties

Name Type Summary
gizmoType GizmoType The gizmo type of the entity.

Default Value: "ring"

ring Entities.RingGizmo The ring gizmo properties.
EntityProperties-Grid
Type: object

The "Grid" EntityType displays a grid on a 2D plane. It has properties in addition to the common EntityProperties.

Properties

Name Type Summary
color Color The color of the grid.

Default Value: 255,255,255

alpha number The alpha of the grid.

Default Value: 1

followCamera boolean If true, the grid is always visible even as the camera moves to another position.

Default Value: true

majorGridEvery number Integer number of minorGridEvery intervals at which to draw a thick grid line. Minimum value = 1.

Default Value: 5

minorGridEvery number Real number of meters at which to draw thin grid lines. Minimum value = 0.001.

Default Value: 1

pulse Entities.Pulse The pulse-related properties. Deprecated.
Example

Create a grid entity.

var grid = Entities.addEntity({
    type: "Grid",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    dimensions: { x: 100.0, y: 100.0, z: 0.01 },
    followCamera: false,
    majorGridEvery: 4,
    minorGridEvery: 0.5,
    lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-Image
Type: object

The "Image" EntityType displays an image on a 2D rectangle in the domain. It has properties in addition to the common EntityProperties.

Properties

Name Type Summary
imageURL string The URL of the image to use.

Default Value: ""

emissive boolean Whether or not the image should be emissive (unlit).

Default Value: false

keepAspectRatio boolean Whether or not the image should maintain its aspect ratio.

Default Value: true

billboardMode BillboardMode If "none", the entity is not billboarded. If "yaw", the entity will be oriented to follow your camera around the y-axis. If "full" the entity will be oriented to face your camera. The following deprecated behavior is also supported: you can also set "faceCamera" to true to set billboardMode to "yaw", and you can set "isFacingAvatar" to true to set billboardMode to "full". Setting either to false sets the mode to "none"

Default Value: "none"

subImage Rect x: 0, y: 0, width: -1, height: -1 } - The portion of the image to display. If width or height are -1, defaults to the full image in that dimension.

Default Value: {

color Color The color of the image.

Default Value: 255,255,255

alpha number The alpha of the image.

Default Value: 1

pulse Entities.Pulse The pulse-related properties. Deprecated.
Example

Create a image entity.

var image = Entities.addEntity({
    type: "Image",
    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 },
    imageURL: "https://images.pexels.com/photos/1020315/pexels-photo-1020315.jpeg",
    billboardMode: "yaw",
    lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-Light
Type: object

The "Light" EntityType adds local lighting effects. It has properties in addition to the common EntityProperties.

Properties

Name Type Summary
dimensions Vec3 The dimensions of the entity. Entity surface outside these dimensions are not lit by the light.

Default Value: 0.1,0.1,0.1

color Color The color of the light emitted.

Default Value: 255,255,255

intensity number The brightness of the light.

Default Value: 1

falloffRadius number The distance from the light's center at which intensity is reduced by 25%.

Default Value: 0.1

isSpotlight boolean If true then the light is directional, emitting along the entity's local negative z-axis; otherwise the light is a point light which emanates in all directions.

Default Value: false

exponent number Affects the softness of the spotlight beam: the higher the value the softer the beam.

Default Value: 0

cutoff number Affects the size of the spotlight beam: the higher the value the larger the beam.

Default Value: 1.57

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.
});
EntityProperties-Line
Type: object

The "Line" EntityType draws thin, straight lines between a sequence of two or more points. Deprecated: Use PolyLines instead. It has properties in addition to the common EntityProperties.

Properties

Name Type Summary
dimensions Vec3 The dimensions of the entity. Must be sufficient to contain all the linePoints.

Default Value: 0.1,0.1,0.1

linePoints Array.<Vec3> 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.

Default Value: []

color Color The color of the line.

Default Value: 255,255,255

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.
});
EntityProperties-Material
Type: object

The "Material" EntityType modifies the existing materials on entities and avatars. It has properties in addition to the common EntityProperties.
To apply a material to an entity, set the material entity's parentID property to the entity ID. To apply a material to an avatar, set the material entity's parentID property to the avatar's session UUID. To apply a material to your avatar such that it persists across domains and log-ins, create the material as an avatar entity by setting the entityHostType parameter in Entities.addEntity to "avatar". Material entities render as non-scalable spheres if they don't have their parent set.

Properties

Name Type Summary
materialURL string URL to a MaterialResource. If you append #name to the URL, the material with that name in the MaterialResource will be applied to the entity.
Alternatively, set the property value to "materialData" to use the materialData property for the MaterialResource values.

Default Value: ""

priority number The priority for applying the material to its parent. Only the highest priority material is applied, with materials of the same priority randomly assigned. Materials that come with the model have a priority of 0.

Default Value: 0

parentMaterialName string Selects the mesh part or parts within the parent to which to apply the material. If in the format "mat::string", all mesh parts with material name "string" are replaced. Otherwise the property value is parsed as an unsigned integer, specifying the mesh part index to modify. If "all", all mesh parts will be replaced. If an array (starts with "[" and ends with "]"), the string will be split at each "," and each element will be parsed as either a number or a string if it starts with "mat::". In other words, "[0,1,mat::string,mat::string2]" will replace mesh parts 0 and 1, and any mesh parts with material "string" or "string2". Do not put spaces around the commas. Invalid values are parsed to 0.

Default Value: "0"

materialMappingMode string How the material is mapped to the entity. Either "uv" or "projected". In "uv" mode, the material will be evaluated within the UV space of the mesh it is applied to. In "projected" mode, the 3D transform of the Material Entity will be used to evaluate the texture coordinates for the material.

Default Value: "uv"

materialMappingPos Vec2 Offset position in UV-space of the top left of the material, range { x: 0, y: 0 }{ x: 1, y: 1 }.

Default Value: 0,0

materialMappingScale Vec2 How much to scale the material within the parent's UV-space.

Default Value: 1,1

materialMappingRot number How much to rotate the material within the parent's UV-space, in degrees.

Default Value: 0

materialData string Used to store MaterialResource data as a JSON string. You can use JSON.parse() to parse the string into a JavaScript object which you can manipulate the properties of, and use JSON.stringify() to convert the object into a string to put in the property.

Default Value: ""

materialRepeat boolean If true, the material will repeat. If false, fragments outside of texCoord 0 - 1 will be discarded. Works in both "uv" and "projected" modes.

Default Value: true

Example

Color a sphere using a Material entity.

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
        }
    }),
});
EntityProperties-Model
Type: object

The "Model" EntityType displays an FBX or OBJ model. It has properties in addition to the common EntityProperties.

Properties

Name Type Summary
dimensions Vec3 The dimensions of the entity. When adding an entity, if no dimensions value is specified then the model is automatically sized to its naturalDimensions.

Default Value: 0.1,0.1,0.1

modelScale Vec3 The scale factor applied to the model's dimensions. Deprecated.
color Color Currently not used.

Default Value: 255,255,255

modelURL string The URL of the FBX of OBJ model. Baked FBX models' URLs end in ".baked.fbx".

Default Value: ""

textures string A JSON string of texture name, URL pairs used when rendering the model in place of the model's original textures. Use a texture name from the originalTextures property to override that texture. Only the texture names and URLs to be overridden need be specified; original textures are used where there are no overrides. You can use JSON.stringify() to convert a JavaScript object of name, URL pairs into a JSON string.

Default Value: ""

originalTextures string 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.

Default Value: "{}"

shapeType ShapeType The shape of the collision hull used if collisions are enabled.

Default Value: "none"

compoundShapeURL string The model file to use for the compound shape if shapeType is "compound".

Default Value: ""

animation Entities.AnimationProperties An animation to play on the model.
jointRotations Array.<Quat> Joint rotations applied to the model; [] if none are applied or the model hasn't loaded. The array indexes are per getJointIndex. Rotations are relative to each joint's parent.
Joint rotations can be set by 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.

Default Value: [

jointRotationsSet Array.<boolean> 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 getJointIndex.

Default Value: [

jointTranslations Array.<Vec3> Joint translations applied to the model; [] if none are applied or the model hasn't loaded. The array indexes are per getJointIndex. Rotations are relative to each joint's parent.
Joint translations can be set by 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.

Default Value: [

jointTranslationsSet Array.<boolean> 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 getJointIndex.

Default Value: [

relayParentJoints boolean If true and the entity is parented to an avatar, then the avatar's joint rotations are applied to the entity's joints.

Default Value: false

groupCulled boolean If true, the mesh parts of the model are LOD culled as a group. If false, separate mesh parts will be LOD culled individually.

Default Value: false

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.
});
EntityProperties-ParticleEffect
Type: object

The "ParticleEffect" 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 EntityProperties.

Properties

Name Type Summary
isEmitting boolean If true then particles are emitted.

Default Value: true

maxParticles number The maximum number of particles to render at one time. Older particles are deleted if necessary when new ones are created.

Default Value: 1000

lifespan number How long, in seconds, each particle lives.

Default Value: 3s

emitRate number The number of particles per second to emit.

Default Value: 15

emitSpeed number The speed, in m/s, that each particle is emitted at.

Default Value: 5

speedSpread number 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.

Default Value: 1

emitAcceleration Vec3 The acceleration that is applied to each particle during its lifetime. The default is Earth's gravity value.

Default Value: 0,-9.8,0

accelerationSpread Vec3 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}.

Default Value: 0,0,0

dimensions Vec3 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.
emitterShouldTrail boolean If true then particles are "left behind" as the emitter moves, otherwise they stay with the entity's dimensions.

Default Value: false

emitOrientation Quat The orientation of particle emission relative to the entity's axes. By default, particles emit along the entity's local z-axis, and azimuthStart and azimuthFinish are relative to the entity's local x-axis. The default value is a rotation of -90 degrees about the local x-axis, i.e., the particles emit vertically.

Default Value: -0.707,0,0,0.707

emitDimensions Vec3 The dimensions of the shape from which particles are emitted. The shape is specified with shapeType.

Default Value: 0,0,0

emitRadiusStart number The starting radius within the shape at which particles start being emitted; range 0.01.0 for the center to the surface, respectively. Particles are emitted from the portion of the shape that lies between emitRadiusStart and the shape's surface.

Default Value: 1

polarStart number The angle in radians from the entity's local z-axis at which particles start being emitted within the shape; range 0Math.PI. Particles are emitted from the portion of the shape that lies between polarStart and polarFinish. Only used if shapeType is ellipsoid or sphere.

Default Value: 0

polarFinish number The angle in radians from the entity's local z-axis at which particles stop being emitted within the shape; range 0Math.PI. Particles are emitted from the portion of the shape that lies between polarStart and polarFinish. Only used if shapeType is ellipsoid or sphere.

Default Value: 0

azimuthStart number The angle in radians from the entity's local x-axis about the entity's local z-axis at which particles start being emitted; range -Math.PIMath.PI. Particles are emitted from the portion of the shape that lies between azimuthStart and azimuthFinish. Only used if shapeType is ellipsoid, sphere, or circle.

Default Value: -Math.PI

azimuthFinish number The angle in radians from the entity's local x-axis about the entity's local z-axis at which particles stop being emitted; range -Math.PIMath.PI. Particles are emitted from the portion of the shape that lies between azimuthStart and azimuthFinish. Only used if shapeType is ellipsoid, sphere, or circle..

Default Value: Math.PI

textures string The URL of a JPG or PNG image file to display for each particle. If you want transparency, use PNG format.

Default Value: ""

particleRadius number The radius of each particle at the middle of its life.

Default Value: 0.025

radiusStart number The radius of each particle at the start of its life. If NaN, the particleRadius value is used.

Default Value: NaN

radiusFinish number The radius of each particle at the end of its life. If NaN, the particleRadius value is used.

Default Value: NaN

radiusSpread number The spread in radius that each particle is given. If particleRadius == 0.5 and radiusSpread == 0.25, each particle will have a radius in the range 0.250.75.

Default Value: 0

color Color The color of each particle at the middle of its life.

Default Value: 255,255,255

colorStart ColorFloat The color of each particle at the start of its life. If any of the component values are undefined, the color value is used.

Default Value: {}

colorFinish ColorFloat The color of each particle at the end of its life. If any of the component values are undefined, the color value is used.

Default Value: {}

colorSpread Color The spread in color that each particle is given. If color == {red: 100, green: 100, blue: 100} and colorSpread == {red: 10, green: 25, blue: 50}, each particle will have a color in the range {red: 90, green: 75, blue: 50}{red: 110, green: 125, blue: 150}.

Default Value: 0,0,0

alpha number The alpha of each particle at the middle of its life.

Default Value: 1

alphaStart number The alpha of each particle at the start of its life. If NaN, the alpha value is used.

Default Value: NaN

alphaFinish number The alpha of each particle at the end of its life. If NaN, the alpha value is used.

Default Value: NaN

alphaSpread number The spread in alpha that each particle is given. If alpha == 0.5 and alphaSpread == 0.25, each particle will have an alpha in the range 0.250.75.

Default Value: 0

particleSpin number The spin of each particle at the middle of its life. In the range -2*PI2*PI.

Default Value: 0

spinStart number The spin of each particle at the start of its life. In the range -2*PI2*PI. If NaN, the particleSpin value is used.

Default Value: NaN

spinFinish number The spin of each particle at the end of its life. In the range -2*PI2*PI. If NaN, the particleSpin value is used.

Default Value: NaN

spinSpread number The spread in spin that each particle is given. In the range 02*PI. If particleSpin == PI and spinSpread == PI/2, each particle will have a spin in the range PI/23*PI/2.

Default Value: 0

rotateWithEntity boolean Whether or not the particles' spin will rotate with the entity. If false, when particleSpin == 0, the particles will point up in the world. If true, they will point towards the entity's up vector, based on its orientation.

Default Value: false

pulse Entities.Pulse The pulse-related properties. Deprecated.
shapeType ShapeType The shape of the collision hull used if collisions are enabled.

Default Value: "ellipsoid"

compoundShapeURL string The model file to use for the compound shape if shapeType is "compound".

Default Value: ""

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.
});
EntityProperties-PolyLine
Type: object

The "PolyLine" EntityType draws textured, straight lines between a sequence of points. It has properties in addition to the common EntityProperties.

Properties

Name Type Summary
dimensions Vec3 The dimensions of the entity, i.e., the size of the bounding box that contains the lines drawn.

Default Value: 1,1,1

linePoints Array.<Vec3> 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.

Default Value: [

normals Array.<Vec3> 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.

Default Value: [

strokeWidths Array.<number> The widths, in m, of the line at the linePoints. Must be specified in order for the entity to render.

Default Value: [

strokeColors Array.<Vec3> The base colors of each point, which are multiplied with the color of the texture, going from 0-1. If strokeColors.length < the number of points, color is used for the remaining points.

Default Value: [

color Color Used as the color for each point if strokeColors is too short.

Default Value: 255,255,255

textures string The URL of a JPG or PNG texture to use for the lines. If you want transparency, use PNG format.

Default Value: ""

isUVModeStretch boolean If true, the texture is stretched to fill the whole line, otherwise the texture repeats along the line.

Default Value: true

glow bool If true, the alpha of the strokes will drop off farther from the center.

Default Value: false

faceCamera bool If true, each line segment will rotate to face the camera.

Default Value: false

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.
});
EntityProperties-PolyVox
Type: object

The "PolyVox" EntityType displays a set of textured voxels. It has properties in addition to the common 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.

Properties

Name Type Summary
dimensions Vec3 The dimensions of the entity.

Default Value: 0.1,0.1,0.1

voxelVolumeSize Vec3 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.

Default Value: 32,32,32

voxelData string 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.

Default Value: "ABAAEAAQAAAAHgAAEAB42u3BAQ0AAADCoPdPbQ8HFAAAAPBuEAAAAQ=="

voxelSurfaceStyle Entities.PolyVoxSurfaceStyle The style of rendering the voxels' surface and how neighboring PolyVox entities are joined.

Default Value: 2

xTextureURL string URL of the texture to map to surfaces perpendicular to the entity's local x-axis. JPG or PNG format. If no texture is specified the surfaces display white.

Default Value: ""

yTextureURL string URL of the texture to map to surfaces perpendicular to the entity's local y-axis. JPG or PNG format. If no texture is specified the surfaces display white.

Default Value: ""

zTextureURL string URL of the texture to map to surfaces perpendicular to the entity's local z-axis. JPG or PNG format. If no texture is specified the surfaces display white.

Default Value: ""

xNNeighborID Uuid ID of the neighboring PolyVox entity in the entity's -ve local x-axis direction, if you want them joined. Set to Uuid.NULL if there is none or you don't want to join them.

Default Value: Uuid.NULL

yNNeighborID Uuid ID of the neighboring PolyVox entity in the entity's -ve local y-axis direction, if you want them joined. Set to Uuid.NULL if there is none or you don't want to join them.

Default Value: Uuid.NULL

zNNeighborID Uuid ID of the neighboring PolyVox entity in the entity's -ve local z-axis direction, if you want them joined. Set to Uuid.NULL if there is none or you don't want to join them.

Default Value: Uuid.NULL

xPNeighborID Uuid ID of the neighboring PolyVox entity in the entity's +ve local x-axis direction, if you want them joined. Set to Uuid.NULL if there is none or you don't want to join them.

Default Value: Uuid.NULL

yPNeighborID Uuid ID of the neighboring PolyVox entity in the entity's +ve local y-axis direction, if you want them joined. Set to Uuid.NULL if there is none or you don't want to join them.

Default Value: Uuid.NULL

zPNeighborID Uuid ID of the neighboring PolyVox entity in the entity's +ve local z-axis direction, if you want them joined. Set to Uuid.NULL if there is none or you don't want to join them.

Default Value: Uuid.NULL

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);
EntityProperties-Shape
Type: object

The "Shape" EntityType displays an entity of a specified shape. It has properties in addition to the common EntityProperties.

Properties

Name Type Summary
shape Entities.Shape The shape of the entity.

Default Value: "Sphere"

dimensions Vec3 The dimensions of the entity.

Default Value: 0.1,0.1,0.1

color Color The color of the entity.

Default Value: 255,255,255

alpha number The alpha of the shape.

Default Value: 1

pulse Entities.Pulse The pulse-related properties. Deprecated.
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.
});
EntityProperties-Sphere
Type: object

The "Sphere" EntityType is the same as the "Shape" EntityType except that its shape value is always set to "Sphere" when the entity is created. If its shape property value is subsequently changed then the entity's type will be reported as "Box" if the shape is set to "Cube", otherwise it will be reported as "Shape".

EntityProperties-Text
Type: object

The "Text" EntityType displays a 2D rectangle of text in the domain. It has properties in addition to the common EntityProperties.

Properties

Name Type Summary
dimensions Vec3 The dimensions of the entity.

Default Value: 0.1,0.1,0.01

text string 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.

Default Value: ""

lineHeight number The height of each line of text (thus determining the font size).

Default Value: 0.1

textColor Color The color of the text.

Default Value: 255,255,255

textAlpha number The text alpha.

Default Value: 1.0

backgroundColor Color The color of the background rectangle.

Default Value: 0,0,0

backgroundAlpha number The background alpha.

Default Value: 1.0

billboardMode BillboardMode If "none", the entity is not billboarded. If "yaw", the entity will be oriented to follow your camera around the y-axis. If "full" the entity will be oriented to face your camera. The following deprecated behavior is also supported: you can also set "faceCamera" to true to set billboardMode to "yaw", and you can set "isFacingAvatar" to true to set billboardMode to "full". Setting either to false sets the mode to "none"

Default Value: "none"

leftMargin number The left margin, in meters.

Default Value: 0.0

rightMargin number The right margin, in meters.

Default Value: 0.0

topMargin number The top margin, in meters.

Default Value: 0.0

bottomMargin number The bottom margin, in meters.

Default Value: 0.0

pulse Entities.Pulse The pulse-related properties. Deprecated.
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!",
    billboardMode: "yaw",
    lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-Web
Type: object

The "Web" 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 EntityProperties.

Properties

Name Type Summary
dimensions Vec3 The dimensions of the entity.

Default Value: 0.1,0.1,0.01

color Color The color of the web surface.

Default Value: 255,255,255

alpha number The alpha of the web surface.

Default Value: 1

billboardMode BillboardMode If "none", the entity is not billboarded. If "yaw", the entity will be oriented to follow your camera around the y-axis. If "full" the entity will be oriented to face your camera. The following deprecated behavior is also supported: you can also set "faceCamera" to true to set billboardMode to "yaw", and you can set "isFacingAvatar" to true to set billboardMode to "full". Setting either to false sets the mode to "none"

Default Value: "none"

sourceUrl string The URL of the Web page to display. This value does not change as you or others navigate on the Web entity.

Default Value: ""

dpi number The resolution to display the page at, in dots per inch. If you convert this to dots per meter (multiply by 1 / 0.0254 = 39.3701) then multiply dimensions.x and dimensions.y by that value you get the resolution in pixels.

Default Value: 30

scriptURL string The URL of a JavaScript file to inject into the Web page.

Default Value: ""

maxFPS number The maximum update rate for the Web content, in frames/second.

Default Value: 10

inputMode WebInputMode The user input mode to use.

Default Value: "touch"

pulse Entities.Pulse The pulse-related properties. Deprecated.
showKeyboardFocusHighlight boolean Whether or not to show the keyboard focus highlight when this entity has focus.
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.
});
EntityProperties-Zone
Type: object

The "Zone" EntityType is a volume of lighting effects and avatar permissions. Avatar interaction events such as Entities.enterEntity are also often used with a Zone entity. It has properties in addition to the common EntityProperties.

Properties

Name Type Summary
dimensions Vec3 The size of the volume in which the zone's lighting effects and avatar permissions have effect.

Default Value: 0.1,0.1,0.1

shapeType ShapeType 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 "".

Default Value: "box"

compoundShapeURL string The model file to use for the compound shape if shapeType is "compound".

Default Value: ""

keyLightMode string 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.

Default Value: "inherit"

keyLight Entities.KeyLight The key light properties of the zone.
ambientLightMode string 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.

Default Value: "inherit"

ambientLight Entities.AmbientLight The ambient light properties of the zone.
skyboxMode string 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.

Default Value: "inherit"

skybox Entities.Skybox The skybox properties of the zone.
hazeMode string 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.

Default Value: "inherit"

haze Entities.Haze The haze properties of the zone.
bloomMode string Configures the bloom in the zone. Possible values:
"inherit": The bloom from any enclosing zone continues into this zone.
"disabled": The bloom from any enclosing zone and the bloom of this zone are disabled in this zone.
"enabled": The bloom properties of this zone are enabled, overriding the bloom from any enclosing zone.

Default Value: "inherit"

bloom Entities.Bloom The bloom properties of the zone.
flyingAllowed boolean If true then visitors can fly in the zone; otherwise they cannot. Only works on domain entities.

Default Value: true

ghostingAllowed boolean If true then visitors with avatar collisions turned off will not collide with content in the zone; otherwise visitors will always collide with content in the zone. Only works on domain entities.

Default Value: true

filterURL string 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.

Default Value: ""

avatarPriority string Configures the update priority of contained avatars to other clients.
"inherit": Priority from enclosing zones is unchanged.
"crowd": Priority in this zone is the normal priority.
"hero": Avatars in this zone will have an increased update priority

function filter(properties) {
    // Test and edit properties object values,
    // e.g., properties.modelURL, as required.
    return properties;
}

Default Value: "inherit"

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.
});
EntityType
Type: string

An entity may be one of the following types:

ValueDescriptionProperties
"Box"A rectangular prism. This is a synonym of "Shape" for the case where the entity's shape property value is "Cube".
If an entity is created with its type set to "Box" it will always be created with a shape property value of "Cube". If an entity of type Shape or Sphere has its shape set to "Cube" then its type will be reported as "Box".
EntityProperties-Box
"Sphere"A sphere. This is a synonym of "Shape" for the case where the entity's shape property value is "Sphere".
If an entity is created with its type set to "Sphere" it will always be created with a shape property value of "Sphere". If an entity of type Box or Shape has its shape set to "Sphere" then its type will be reported as "Sphere".
EntityProperties-Sphere
"Shape"A basic entity such as a cube. See also, the "Box" and "Sphere" entity types. EntityProperties-Shape
"Model"A mesh model from an FBX or OBJ file. EntityProperties-Model
"Text"A pane of text oriented in space. EntityProperties-Text
"Image"An image oriented in space. EntityProperties-Image
"Web"A browsable Web page. EntityProperties-Web
"ParticleEffect"A particle system that can be used to simulate things such as fire, smoke, snow, magic spells, etc. EntityProperties-ParticleEffect
"Line"A sequence of one or more simple straight lines. EntityProperties-Line
"PolyLine"A sequence of one or more textured straight lines. EntityProperties-PolyLine
"PolyVox"A set of textured voxels. EntityProperties-PolyVox
"Grid"A grid of lines in a plane. EntityProperties-Grid
"Gizmo"An entity with various UI-related properties. EntityProperties-Gizmo
"Light"A local lighting effect. EntityProperties-Light
"Zone"A volume of lighting effects and avatar permissions. EntityProperties-Zone
"Material"Modifies the existing materials on entities and avatars. EntityProperties-Material

Grab
Type: object

Grab is defined by the following properties.

Properties

Name Type Summary
grabbable boolean If true the entity can be grabbed.

Default Value: true

grabKinematic boolean If true the entity is updated in a kinematic manner. If false it will be grabbed using a tractor action. A kinematic grab will make the item appear more tightly held, but will cause it to behave poorly when interacting with dynamic entities.

Default Value: true

grabFollowsController boolean If true the entity will follow the motions of the hand-controller even if the avatar's hand can't get to the implied position. This should be true for tools, pens, etc and false for things meant to decorate the hand.

Default Value: true

triggerable boolean If true the entity will receive calls to trigger Controller entity methods.

Default Value: false

equippable boolean If true the entity can be equipped.

Default Value: true

equippableLeftPosition Vec3 Positional offset from the left hand, when equipped.

Default Value: 0,0,0

equippableLeftRotation Quat Rotational offset from the left hand, when equipped.

Default Value: 0,0,0,1

equippableRightPosition Vec3 Positional offset from the right hand, when equipped.

Default Value: 0,0,0

equippableRightRotation Quat Rotational offset from the right hand, when equipped.

Default Value: 0,0,0,1

equippableIndicatorURL string If non-empty, this model will be used to indicate that an entity is equippable, rather than the default.

Default Value: ""

equippableIndicatorScale Vec3 If equippableIndicatorURL is non-empty, this controls the scale of the displayed indicator.

Default Value: 1,1,1

equippableIndicatorOffset Vec3 If equippableIndicatorURL is non-empty, this controls the relative offset of the displayed object from the equippable entity.

Default Value: 0,0,0

Haze
Type: object

Haze is defined by the following properties.

Properties

Name Type Summary
hazeRange number The horizontal distance at which visibility is reduced to 95%; i.e., 95% of each pixel's color is haze.

Default Value: 1000

hazeColor Color The color of the haze when looking away from the key light.

Default Value: 128,154,179

hazeEnableGlare boolean If true then the haze is colored with glare from the key light; hazeGlareColor and hazeGlareAngle are used.

Default Value: false

hazeGlareColor Color The color of the haze when looking towards the key light.

Default Value: 255,299,179

hazeGlareAngle number The angle in degrees across the circle around the key light that the glare color and haze color are blended 50/50.

Default Value: 20

hazeAltitudeEffect boolean If true then haze decreases with altitude as defined by the entity's local coordinate system; hazeBaseRef and hazeCeiling are used.

Default Value: false

hazeBaseRef number The y-axis value in the entity's local coordinate system at which the haze density starts reducing with altitude.

Default Value: 0

hazeCeiling number The y-axis value in the entity's local coordinate system at which the haze density has reduced to 5%.

Default Value: 200

hazeBackgroundBlend number The proportion of the skybox image to show through the haze: 0.0 displays no skybox image; 1.0 displays no haze.

Default Value: 0

hazeAttenuateKeyLight boolean Currently not supported.

Default Value: false

hazeKeyLightRange number Currently not supported.

Default Value: 1000

hazeKeyLightAltitude number Currently not supported.

Default Value: 200

KeyLight
Type: object

A key light is defined by the following properties.

Properties

Name Type Summary
color Color The color of the light.

Default Value: 255,255,255

intensity number The intensity of the light.

Default Value: 1

direction Vec3 The direction the light is shining.

Default Value: 0,-1,0

castShadows boolean If true then shadows are cast. Shadows are cast by avatars, plus Model and Shape entities that have their canCastShadow property set to true.

Default Value: false

PhysicsMotionType
Type: string

An entity's physics motion type may be one of the following:

ValueDescription
"static"There is no motion because the entity is locked — its locked property is set to true.
"kinematic"Motion is applied without physical laws (e.g., damping) because the entity is not locked and has its dynamic property set to false.
"dynamic"Motion is applied according to physical laws (e.g., damping) because the entity is not locked and has its dynamic property set to true.

PolyVoxSurfaceStyle
Type: number

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.

Pulse
Type: object

Pulse is defined by the following properties.

Properties

Name Type Summary
min number The minimum value of the pulse multiplier.

Default Value: 0

max number The maximum value of the pulse multiplier.

Default Value: 1

period number The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from min to max, then max to min in one period.

Default Value: 1

colorMode PulseMode If "in", the color is pulsed in phase with the pulse period; if "out" the color is pulsed out of phase with the pulse period.

Default Value: "none"

alphaMode PulseMode If "in", the alpha is pulsed in phase with the pulse period; if "out" the alpha is pulsed out of phase with the pulse period.

Default Value: "none"

RayToEntityIntersectionResult
Type: object

The result of a PickRay search using findRayIntersection.

Properties

Name Type Summary
intersects boolean true if the PickRay intersected an entity, otherwise false.
accurate boolean Is always true.
entityID Uuid The ID if the entity intersected, if any, otherwise null.
distance number The distance from the PickRay origin to the intersection point.
intersection Vec3 The intersection point.
surfaceNormal Vec3 The surface normal of the entity at the intersection point.
face BoxFace The face of the entity's axis-aligned box that the ray intersects.
extraInfo object Extra information depending on the entity intersected. Currently, only Model entities provide extra information, and the information provided depends on the precisionPicking parameter value that the search function was called with.
RenderInfo
Type: object

Information on how an entity is rendered. Properties are only filled in for Model entities; other entity types have an empty object, {}.

Properties

Name Type Summary
verticesCount number The number of vertices in the entity.
texturesCount number The number of textures in the entity.
textureSize number The total size of the textures in the entity, in bytes.
hasTransparent boolean Is true if any of the textures has transparency.
drawCalls number The number of draw calls required to render the entity.
RingGizmo
Type: object

A RingGizmo is defined by the following properties.

Properties

Name Type Summary
startAngle number The angle at which the ring will start, in degrees.

Default Value: 0

endAngle number The angle at which the ring will end, in degrees.

Default Value: 360

innerRadius number The inner radius of the ring as a fraction of the total radius. 0-1.

Default Value: 0

innerStartColor Color The color at the inner start point of the ring.
innerEndColor Color The color at the inner end point of the ring.
outerStartColor Color The color at the outer start point of the ring.
outerEndColor Color The color at the outer end point of the ring.
innerStartAlpha number The alpha at the inner start point of the ring.

Default Value: 1

innerEndAlpha number The alpha at the inner end point of the ring.

Default Value: 1

outerStartAlpha number The alpha at the outer start point of the ring.

Default Value: 1

outerEndAlpha number The alpha at the outer end point of the ring.

Default Value: 1

hasTickMarks boolean Whether or not to render tick marks.

Default Value: false

majorTickMarksAngle number The angle between major tick marks, in degrees.
minorTickMarksAngle number The angle between minor tick marks, in degrees.
majorTickMarksLength number The length of the major tick marks, as a fraction of the radius. A positive value draws tick marks outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.
minorTickMarksLength number The length of the minor tick marks, as a fraction of the radius. A positive value draws tick marks outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.
majorTickMarksColor Color The color of the major tick marks.
minorTickMarksColor Color The color of the minor tick marks.
Shape
Type: string

A Shape, Box, or Sphere 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.

Skybox
Type: object

A skybox is defined by the following properties.

Properties

Name Type Summary
color Color Sets the color of the sky if url is "", otherwise modifies the color of the cube map image.

Default Value: 0,0,0

url string A cube map image that is used to render the sky.

Default Value: ""

getMeshesCallback( meshes, success )
Type: function

Called when Entities.getMeshes is complete.

Deprecated: This function is deprecated and will be removed. Use the Graphics API instead.

getServerScriptStatusCallback( success, isRunning, status, errorInfo )
Type: function

Called when Entities.getServerScriptStatus is complete.

queryPropertyMetadataCallback( error, result )
Type: function

Called when Entities.queryPropertyMetadata is complete.

Method Details

(static) AABoxIntersectsCapsule( brn, dimensions, start, end, radius ) → {boolean}
Returns: true if the AA box and capsule intersect, otherwise false.

Check whether an axis-aligned box and a capsule intersect.

Parameters

Name Type Description
brn Vec3 The bottom right near (minimum axes values) corner of the AA box.
dimensions Vec3 The dimensions of the AA box.
start Vec3 One end of the capsule.
end Vec3 The other end of the capsule.
radius number The radiues of the capsule.
(static) addAction( actionType, entityID, arguments ) → {Uuid}
Returns: The ID of the action added if successfully added, otherwise null.

Add an action to an entity. An action is registered with the physics engine and is applied every physics simulation step. Any entity may have more than one action associated with it, but only as many as will fit in an entity's actionData property.

Parameters

Name Type Description
actionType Entities.ActionType The type of action.
entityID Uuid The ID of the entity to add the action to.
arguments Entities.ActionArguments Configure the action.
Example

Constrain a cube to move along a vertical line.

var entityID = Entities.addEntity({
    type: "Box",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -5 })),
    dimensions: { x: 0.5, y: 0.5, z: 0.5 },
    dynamic: true,
    collisionless: false,
    userData: "{ \"grabbableKey\": { \"grabbable\": true, \"kinematic\": false } }",
    lifetime: 300  // Delete after 5 minutes.
});

var actionID = Entities.addAction("slider", entityID, {
    axis: { x: 0, y: 1, z: 0 },
    linearLow: 0,
    linearHigh: 0.6
});
(static) addEntity( properties, entityHostTypeopt ) → {Uuid}
Returns: The ID of the entity if successfully created, otherwise Uuid.NULL.

Add a new entity with specified properties.

Parameters

Name Type Attributes Default Value Description
properties Entities.EntityProperties The properties of the entity to create.
entityHostType EntityHostType <optional>
"domain" If "avatar" the entity is created as an avatar entity. An avatar entity follows you to each domain you visit, rendering at the same world coordinates unless it's parented to your avatar. If "local", the entity is created as a local entity, which will only render for you and isn't sent over the wire. Otherwise it is created as a normal entity and sent over the entity server.
Example

Create a box entity in front of your avatar.

var entityID = Entities.addEntity({
    type: "Box",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.5, y: 0.5, z: 0.5 }
});
print("Entity created: " + entityID);
(static) addEntity( properties, avatarEntityopt ) → {Uuid}
Returns: The ID of the entity if successfully created, otherwise Uuid.NULL.

Add a new entity with specified properties.

Parameters

Name Type Attributes Default Value Description
properties Entities.EntityProperties The properties of the entity to create.
avatarEntity boolean <optional>
false Whether to create an avatar entity or a domain entity
(static) appendPoint( entityID, point ) → {boolean}
Returns: true if the point was added to the line, otherwise false. The point may fail to be added if the entity does not exist, the entity is not a Line entity, the point is outside the entity's dimensions, or the maximum number of points has been reached.

Append a point to a Line entity.

Parameters

Name Type Description
entityID Uuid The ID of the Line entity.
point Vec3 The point to add to the line. The coordinates are relative to the entity's position.
Example

Append a point to a Line entity.

// Draw a line between two points.
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 }
    ],
    color: { red: 255, green: 0, blue: 0 },
    lifetime: 300  // Delete after 5 minutes.
});

// Add a third point to create a "V".
Entities.appendPoint(entity, { x: 1, y: 1, z: 0 });
(static) callEntityClientMethod( clientSessionID, entityID, method, parametersopt )

Call a method in a specific user's client entity script from a server entity script. The entity script method must be exposed as a property in the target client entity script.

Parameters

Name Type Attributes Default Value Description
clientSessionID Uuid The session ID of the user to call the method in.
entityID Uuid The ID of the entity to call the method in.
method string The name of the method to call.
parameters Array.<string> <optional>
[] The parameters to call the specified method with.
(static) callEntityMethod( entityID, method, parametersopt )

Call a method in a client entity script from a client script or client entity script, or call a method in a server entity script from a server entity script. The entity script method must be exposed as a property in the target client entity script. Additionally, if calling a server entity script, the server entity script must include the method's name in an exposed property called remotelyCallable that is an array of method names that can be called.

Parameters

Name Type Attributes Default Value Description
entityID Uuid The ID of the entity to call the method in.
method string The name of the method to call.
parameters Array.<string> <optional>
[] The parameters to call the specified method with.
(static) callEntityServerMethod( entityID, method, parametersopt )

Call a method in a server entity script from a client script or client entity script. The entity script method must be exposed as a property in the target server entity script. Additionally, the target server entity script must include the method's name in an exposed property called remotelyCallable that is an array of method names that can be called.

Parameters

Name Type Attributes Default Value Description
entityID Uuid The ID of the entity to call the method in.
method string The name of the method to call.
parameters Array.<string> <optional>
[] The parameters to call the specified method with.
(static) canAdjustLocks( ) → {boolean}
Returns: true if the client can change the locked property of entities, otherwise false.

Check whether or not you can change the locked property of entities. Locked entities have their locked property set to true and cannot be edited or deleted. Whether or not you can change entities' locked properties is configured in the domain server's permissions.

Example

Set an entity's locked property to true if you can.

if (Entities.canAdjustLocks()) {
    Entities.editEntity(entityID, { locked: true });
} else {
    Window.alert("You do not have the permissions to set an entity locked!");
}
(static) canReplaceContent( ) → {boolean}
Returns: true if the domain server will allow the script to replace the domain's content set, otherwise false.

Check whether or not you can replace the domain's content set.

(static) canRez( ) → {boolean}
Returns: true if the domain server will allow the script to rez (create) new entities, otherwise false.

Check whether or not you can rez (create) new entities in the domain.

(static) canRezCertified( ) → {boolean}
Returns: true if the domain server will allow the script to rez (create) new certified entities, otherwise false.

Check whether or not you can rez (create) new certified entities in the domain. Certified entities are entities that have PoP certificates.

(static) canRezTmp( ) → {boolean}
Returns: true if the domain server will allow the script to rez (create) new temporary entities, otherwise false.

Check whether or not you can rez (create) new temporary entities in the domain. Temporary entities are entities with a finite lifetime property value set.

(static) canRezTmpCertified( ) → {boolean}
Returns: true if the domain server will allow the script to rez (create) new temporary certified entities, otherwise false.

Check whether or not you can rez (create) new temporary certified entities in the domain. Temporary entities are entities with a finite lifetime property value set. Certified entities are entities that have PoP certificates.

(static) canWriteAssets( ) → {boolean}
Returns: true if the domain server will allow the script to make changes to the asset server's assets, otherwise false.

Check whether or not you can make changes to the asset server's assets.

(static) cloneEntity( entityID ) → {Uuid}
Returns: The ID of the new entity if successfully cloned, otherwise Uuid.NULL.

Create a clone of an entity. A clone can be created by a client that doesn't have rez permissions in the current domain. The entity must have its cloneable property set to true. The clone has a modified name, other properties set per its clone related-properties, and its clone-related properties are set to defaults.

Parameters

Name Type Description
entityID Uuid The ID of the entity to clone.
(static) deleteAction( entityID, actionID ) → {boolean}
Returns: true if the update was successful, otherwise false.

Delete an action from an entity.

Parameters

Name Type Description
entityID Uuid The ID of entity to delete the action from.
actionID Uuid The ID of the action to delete.
(static) deleteEntity( entityID )

Delete an entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity to delete.
Example

Delete an entity a few seconds after creating it.

var entityID = Entities.addEntity({
    type: "Box",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.5, y: 0.5, z: 0.5 }
});

Script.setTimeout(function () {
    Entities.deleteEntity(entityID);
}, 3000);
(static) deleteEntity( id )

Get an entities type as a string.

Parameters

Name Type Description
id Uuid The id of the entity to get the type of.
(static) dumpTree( )

Dumps debug information about all entities in Interface's local in-memory tree of entities it knows about to the program log.

(static) editEntity( entityID, properties ) → {Uuid}
Returns: The ID of the entity if the edit was successful, otherwise null.

Update an entity with specified properties.

Parameters

Name Type Description
entityID Uuid The ID of the entity to edit.
properties Entities.EntityProperties The properties to update the entity with.
Example

Change the color of an entity.

var entityID = Entities.addEntity({
    type: "Box",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.5, y: 0.5, z: 0.5 }
});
var properties = Entities.getEntityProperties(entityID, ["color"]);
print("Entity color: " + JSON.stringify(properties.color));

Entities.editEntity(entityID, {
    color: { red: 255, green: 0, blue: 0 }
});
properties = Entities.getEntityProperties(entityID, ["color"]);
print("Entity color: " + JSON.stringify(properties.color));
(static) emitScriptEvent( entityID, message )

Send a script event over a Web entity's EventBridge to the Web page's scripts.

Parameters

Name Type Description
entityID Uuid The ID of the Web entity.
message string The message to send.
(static) findClosestEntity( center, radius ) → {Uuid}
Returns: The ID of the entity that is closest to the center and within the radius if there is one, otherwise null.

Find the non-local entity with a position closest to a specified point and within a specified radius.

Parameters

Name Type Description
center Vec3 The point about which to search.
radius number The radius within which to search.
Example

Find the closest entity within 10m of your avatar.

var entityID = Entities.findClosestEntity(MyAvatar.position, 10);
print("Closest entity: " + entityID);
(static) findEntities( center, radius ) → {Array.<Uuid>}
Returns: An array of entity IDs that were found that intersect the search sphere. The array is empty if no entities could be found.

Find all non-local entities that intersect a sphere defined by a center point and radius.

Parameters

Name Type Description
center Vec3 The point about which to search.
radius number The radius within which to search.
Example

Report how many entities are within 10m of your avatar.

var entityIDs = Entities.findEntities(MyAvatar.position, 10);
print("Number of entities within 10m: " + entityIDs.length);
(static) findEntitiesByName( entityName, center, radius, caseSensitiveopt ) → {Array.<Uuid>}
Returns: An array of entity IDs that have the specified name and intersect the search sphere. The array is empty if no entities could be found.

Find all non-local entities with a particular name that intersect a sphere defined by a center point and radius.

Parameters

Name Type Attributes Default Value Description
entityName string The name of the entity to search for.
center Vec3 The point about which to search.
radius number The radius within which to search.
caseSensitive boolean <optional>
false If true then the search is case-sensitive.
Example

Report the number of entities with the name, "Light-Target".

var entityIDs = Entities.findEntitiesByName("Light-Target", MyAvatar.position, 10, false);
print("Number of entities with the name Light-Target: " + entityIDs.length);
(static) findEntitiesByType( entityType, center, radius ) → {Array.<Uuid>}
Returns: An array of entity IDs of the specified type that intersect the search sphere. The array is empty if no entities could be found.

Find all non-local entities of a particular type that intersect a sphere defined by a center point and radius.

Parameters

Name Type Description
entityType Entities.EntityType The type of entity to search for.
center Vec3 The point about which to search.
radius number The radius within which to search.
Example

Report the number of Model entities within 10m of your avatar.

var entityIDs = Entities.findEntitiesByType("Model", MyAvatar.position, 10);
print("Number of Model entities within 10m: " + entityIDs.length);
(static) findEntitiesInBox( corner, dimensions ) → {Array.<Uuid>}
Returns: An array of entity IDs whose AA boxes intersect the search AA box. The array is empty if no entities could be found.

Find all non-local entities whose axis-aligned boxes intersect a search axis-aligned box defined by its minimum coordinates corner and dimensions.

Parameters

Name Type Description
corner Vec3 The corner of the search AA box with minimum co-ordinate values.
dimensions Vec3 The dimensions of the search AA box.
(static) findEntitiesInFrustum( frustum ) → {Array.<Uuid>}
Returns: An array of entity IDs axis-aligned boxes intersect the frustum. The array is empty if no entities could be found.

Find all non-local entities whose axis-aligned boxes intersect a search frustum.

Parameters

Name Type Description
frustum ViewFrustum The frustum to search in. The position, orientation, projection, and centerRadius properties must be specified.
Example

Report the number of entities in view.

var entityIDs = Entities.findEntitiesInFrustum(Camera.frustum);
print("Number of entities in view: " + entityIDs.length);
(static) findRayIntersection( pickRay, precisionPickingopt, entitiesToIncludeopt, entitiesToDiscardopt, visibleOnlyopt, collideableOnlyopt ) → {Entities.RayToEntityIntersectionResult}
Returns: The result of the search for the first intersected entity.

Find the first non-local entity intersected by a PickRay. Light and Zone entities are not intersected unless they've been configured as pickable using setLightsArePickable and setZonesArePickable, respectively.

Parameters

Name Type Attributes Default Value Description
pickRay PickRay The PickRay to use for finding entities.
precisionPicking boolean <optional>
false If true and the intersected entity is a Model entity, the result's extraInfo property includes more information than it otherwise would.
entitiesToInclude Array.<Uuid> <optional>
[] If not empty then the search is restricted to these entities.
entitiesToDiscard Array.<Uuid> <optional>
[] Entities to ignore during the search.
visibleOnly boolean <optional>
false If true then only entities that are visible are searched.
collideableOnly boolean <optional>
false If true then only entities that are not collisionless are searched.
Example

Find the entity directly in front of your avatar.

var pickRay = {
    origin: MyAvatar.position,
    direction: Quat.getFront(MyAvatar.orientation)
};

var intersection = Entities.findRayIntersection(pickRay, true);
if (intersection.intersects) {
    print("Entity in front of avatar: " + intersection.entityID);
} else {
    print("No entity in front of avatar.");
}
(static) getAbsoluteJointRotationInObjectFrame( entityID, jointIndex ) → {Quat}
Returns: The rotation of the joint relative to the entity's orientation if the entity is a Model entity, the entity is loaded, and the joint index is valid; otherwise Quat.IDENTITY.

Get the translation of a joint in a Model entity relative to the entity's position and orientation.

Parameters

Name Type Description
entityID Uuid The ID of the entity.
jointIndex number The integer index of the joint.
Example

Compare the local and absolute rotations of an avatar model's left hand joint.

entityID = Entities.addEntity({
    type: "Model",
    modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    rotation: MyAvatar.orientation,
    lifetime: 300  // Delete after 5 minutes.
});

Script.setTimeout(function () {
    // Joint data aren't available until after the model has loaded.
    var index = Entities.getJointIndex(entityID, "LeftHand");
    var localRotation = Entities.getLocalJointRotation(entityID, index);
    var absoluteRotation = Entities.getAbsoluteJointRotationInObjectFrame(entityID, index);
    print("Left hand local rotation: " + JSON.stringify(Quat.safeEulerAngles(localRotation)));
    print("Left hand absolute rotation: " + JSON.stringify(Quat.safeEulerAngles(absoluteRotation)));
}, 2000);
(static) getAbsoluteJointTranslationInObjectFrame( entityID, jointIndex ) → {Vec3}
Returns: The translation of the joint relative to the entity's position and orientation if the entity is a Model entity, the entity is loaded, and the joint index is valid; otherwise Vec3.ZERO.

Get the translation of a joint in a Model entity relative to the entity's position and orientation.

Parameters

Name Type Description
entityID Uuid The ID of the entity.
jointIndex number The integer index of the joint.
(static) getActionArguments( entityID, actionID ) → {Entities.ActionArguments}
Returns: The arguments of the requested action if found, otherwise an empty object.

Get the arguments of an action.

Parameters

Name Type Description
entityID Uuid The ID of the entity with the action.
actionID Uuid The ID of the action to get the arguments of.
(static) getActionIDs( entityID ) → {Array.<Uuid>}
Returns: An array of action IDs if any are found, otherwise an empty array.

Get the IDs of the actions that are associated with an entity.

Parameters

Name Type Description
entityID Uuid The entity to get the action IDs for.
(static) getChildrenIDs( parentID ) → {Array.<Uuid>}
Returns: An array of entity and avatar IDs that are parented directly to the parentID entity or avatar. Does not include children's children, etc. The array is empty if no children can be found or parentID cannot be found.

Get the IDs of entities and avatars that are directly parented to an entity or avatar model. Recurse on the IDs returned by the function to get all descendants of an entity or avatar.

Parameters

Name Type Description
parentID Uuid The ID of the entity or avatar to get the children IDs of.
Example

Report the children of an entity.

function createEntity(description, position, parent) {
    var entity = Entities.addEntity({
        type: "Sphere",
        position: position,
        dimensions: Vec3.HALF,
        parentID: parent,
        lifetime: 300  // Delete after 5 minutes.
    });
    print(description + ": " + entity);
    return entity;
}

var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 2, z: -5 }));
var root = createEntity("Root", position, Uuid.NULL);
var child = createEntity("Child", Vec3.sum(position, { x: 0, y: -1, z: 0 }), root);
var grandChild = createEntity("Grandchild", Vec3.sum(position, { x: 0, y: -2, z: 0 }), child);

var children = Entities.getChildrenIDs(root);
print("Children of root: " + JSON.stringify(children));  // Only the child entity.
(static) getChildrenIDsOfJoint( parentID, jointIndex ) → {Array.<Uuid>}
Returns: An array of entity and avatar IDs that are parented directly to the parentID entity or avatar at the jointIndex joint. Does not include children's children, etc. The array is empty if no children can be found or parentID cannot be found.

Get the IDs of entities and avatars that are directly parented to an entity or avatar model's joint.

Parameters

Name Type Description
parentID Uuid The ID of the entity or avatar to get the children IDs of.
jointIndex number Integer number of the model joint to get the children IDs of.
Example

Report the children of your avatar's right hand.

function createEntity(description, position, parent) {
    var entity = Entities.addEntity({
        type: "Sphere",
        position: position,
        dimensions: Vec3.HALF,
        parentID: parent,
        lifetime: 300  // Delete after 5 minutes.
    });
    print(description + ": " + entity);
    return entity;
}

var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 2, z: -5 }));
var root = createEntity("Root", position, Uuid.NULL);
var child = createEntity("Child", Vec3.sum(position, { x: 0, y: -1, z: 0 }), root);

Entities.editEntity(root, {
    parentID: MyAvatar.sessionUUID,
    parentJointIndex: MyAvatar.getJointIndex("RightHand")
});

var children = Entities.getChildrenIDsOfJoint(MyAvatar.sessionUUID, MyAvatar.getJointIndex("RightHand"));
print("Children of hand: " + JSON.stringify(children));  // Only the root entity.
(static) getDrawZoneBoundaries( ) → {boolean}
Returns: true if Zone entities' boundaries should be drawn, otherwise false.

Get whether or not Zone entities' boundaries should be drawn. Currently not used.

(static) getEntityLocalTransform( entityID ) → {Mat4}
Returns: The entity's object to parent transform excluding scale (i.e., translation and rotation, with scale of 1) if the entity can be found, otherwise a transform with zero translation and rotation and a scale of 1.

Get the object to parent transform, excluding scale, of an entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity.
Example

Position and rotation in an entity's local transform.

function createEntity(position, rotation, parent) {
    var entity = Entities.addEntity({
        type: "Box",
        position: position,
        rotation: rotation,
        dimensions: Vec3.HALF,
        parentID: parent,
        lifetime: 300  // Delete after 5 minutes.
    });
    return entity;
}

var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 2, z: -5 }));

var parent = createEntity(position, MyAvatar.orientation, Uuid.NULL);

var childTranslation = { x: 0, y: -1.5, z: 0 };
var childRotation = Quat.fromPitchYawRollDegrees(0, 45, 0);
var child = createEntity(Vec3.sum(position, childTranslation), Quat.multiply(childRotation, MyAvatar.orientation), parent);

var transform = Entities.getEntityLocalTransform(child);
print("Transform: " + JSON.stringify(transform));
print("Translation: " + JSON.stringify(Mat4.extractTranslation(transform)));  // childTranslation
print("Rotation: " + JSON.stringify(Quat.safeEulerAngles(Mat4.extractRotation(transform))));  // childRotation
print("Scale: " + JSON.stringify(Mat4.extractScale(transform)));  // { x: 1, y: 1, z: 1 }
(static) getEntityObject( id ) → {object}
Returns: The script object for the entity if found.

Get the entity script object. In particular, this is useful for accessing the event bridge for a Web entity.

Parameters

Name Type Description
id Uuid The ID of the entity to get the script object of.
(static) getEntityProperties( entityID, desiredPropertiesopt ) → {Entities.EntityProperties}
Returns: The properties of the entity if the entity can be found, otherwise an empty object.

Get the properties of an entity.

Parameters

Name Type Attributes Default Value Description
entityID Uuid The ID of the entity to get the properties of.
desiredProperties Array.<string> <optional>
[] Array of the names of the properties to get. If the array is empty, all properties are returned.
Example

Report the color of a new box entity.

var entityID = Entities.addEntity({
    type: "Box",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.5, y: 0.5, z: 0.5 }
});
var properties = Entities.getEntityProperties(entityID, ["color"]);
print("Entity color: " + JSON.stringify(properties.color));
(static) getEntityTransform( entityID ) → {Mat4}
Returns: The entity's object to world transform excluding scale (i.e., translation and rotation, with scale of 1) if the entity can be found, otherwise a transform with zero translation and rotation and a scale of 1.

Get the object to world transform, excluding scale, of an entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity.
Example

Position and rotation in an entity's world transform.

var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 1, z: -2 }));
var orientation = MyAvatar.orientation;
print("Position: " + JSON.stringify(position));
print("Orientation: " + JSON.stringify(orientation));

var entityID = Entities.addEntity({
    type: "Sphere",
    position: position,
    rotation: orientation,
    dimensions: Vec3.HALF,
    lifetime: 300  // Delete after 5 minutes.
});

var transform = Entities.getEntityTransform(entityID);
print("Transform: " + JSON.stringify(transform));
print("Translation: " + JSON.stringify(Mat4.extractTranslation(transform)));  // Same as position.
print("Rotation: " + JSON.stringify(Mat4.extractRotation(transform)));  // Same as orientation.
print("Scale: " + JSON.stringify(Mat4.extractScale(transform)));  // { x: 1, y: 1, z: 1 }
(static) getJointIndex( entityID, name ) → {number}
Returns: The integer index of the joint if the entity is a Model entity, the entity is loaded, and the joint is present; otherwise -1. The joint indexes are in order per getJointNames.

Get the index of a named joint in a Model entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity.
name string The name of the joint.
Example

Report the index of a model's head joint.

entityID = Entities.addEntity({
    type: "Model",
    modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    rotation: MyAvatar.orientation,
    lifetime: 300  // Delete after 5 minutes.
});

Script.setTimeout(function () {
    // Joint data aren't available until after the model has loaded.
    var index = Entities.getJointIndex(entityID, "Head");
    print("Head joint index: " + index);
}, 2000);
(static) getJointNames( entityID ) → {Array.<string>}
Returns: The names of all the joints in the entity if it is a Model entity and is loaded, otherwise an empty array. The joint names are in order per getJointIndex.

Get the names of all the joints in a Model entity.

Parameters

Name Type Description
entityID Uuid The ID of the Model entity.
Example

Report a model's joint names.

entityID = Entities.addEntity({
    type: "Model",
    modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    rotation: MyAvatar.orientation,
    lifetime: 300  // Delete after 5 minutes.
});

Script.setTimeout(function () {
    // Joint data aren't available until after the model has loaded.
    var jointNames = Entities.getJointNames(entityID);
    print("Joint names: " + JSON.stringify(jointNames));
}, 2000);
(static) getJointParent( entityID, index ) → {number}
Returns: The index of the parent joint.

Get the index of the parent joint.

Parameters

Name Type Description
entityID Uuid The ID of the entity.
index number The integer index of the joint.
(static) getKeyboardFocusEntity( ) → {Uuid}
Returns: The ID of the Web entity that has focus, if any, otherwise null.

Get the ID of the Web entity that has keyboard focus.

(static) getLifetimeBPS( ) → {number}
Returns: Entity bytes per second send rate of the client over its lifetime.

Get the entity bytes per second send rate of the client over its lifetime.

(static) getLifetimeBPSQueued( ) → {number}
Returns: Entity bytes per second queued rate of the client over its lifetime.

Get the entity bytes per second queued rate of the client over its lifetime.

(static) getLifetimeBytesQueued( ) → {number}
Returns: The total bytes of entity packets queued by the client over its lifetime.

Get the total bytes of entity packets queued by the client over its lifetime.

(static) getLifetimeBytesSent( ) → {number}
Returns: The total bytes of entity packets sent by the client over its lifetime.

Get the total bytes of entity packets sent by the client over its lifetime.

(static) getLifetimeInSeconds( ) → {number}
Returns: Lifetime of the client from the first entity packet sent until now, in seconds.

Get the lifetime of the client from the first entity packet sent until now, in seconds.

(static) getLifetimeInUsecs( ) → {number}
Returns: Lifetime of the client from the first entity packet sent until now, in microseconds.

Get the lifetime of the client from the first entity packet sent until now, in microseconds.

(static) getLifetimePacketsQueued( ) → {number}
Returns: The total number of entity packets queued by the client over its lifetime.

Get the total number of entity packets queued by the client over its lifetime.

(static) getLifetimePacketsSent( ) → {number}
Returns: The total number of entity packets sent by the client over its lifetime.

Get the total number of entity packets sent by the client over its lifetime.

(static) getLifetimePPS( ) → {number}
Returns: Entity packets per second send rate of the client over its lifetime.

Get the entity packets per second send rate of the client over its lifetime.

(static) getLifetimePPSQueued( ) → {number}
Returns: Entity packets per second queued rate of the client over its lifetime.

Get the entity packets per second queued rate of the client over its lifetime.

(static) getLightsArePickable( ) → {boolean}
Returns: true if ray picks intersect the bounding box of Light entities, otherwise false.

Get whether or not ray picks intersect the bounding box of Light entities. Ray picks are done using findRayIntersection, or the Picks API.

(static) getLocalJointRotation( entityID, jointIndex ) → {Quat}
Returns: The local rotation of the joint if the entity is a Model entity, the entity is loaded, and the joint index is valid; otherwise Quat.IDENTITY.

Get the local rotation of a joint in a Model entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity.
jointIndex number The integer index of the joint.
Example

Report the local rotation of an avatar model's head joint.

entityID = Entities.addEntity({
    type: "Model",
    modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    rotation: MyAvatar.orientation,
    lifetime: 300  // Delete after 5 minutes.
});

Script.setTimeout(function () {
    // Joint data aren't available until after the model has loaded.
    var index = Entities.getJointIndex(entityID, "Head");
    var rotation = Entities.getLocalJointRotation(entityID,  index);
    print("Head local rotation: " + JSON.stringify(Quat.safeEulerAngles(rotation)));
}, 2000);
(static) getLocalJointTranslation( entityID, jointIndex ) → {Vec3}
Returns: The local translation of the joint if the entity is a Model entity, the entity is loaded, and the joint index is valid; otherwise Vec3.ZERO.

Get the local translation of a joint in a Model entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity.
jointIndex number The integer index of the joint.
(static) getMeshes( entityID, callback )

Get the meshes in a Model or PolyVox entity.

Deprecated: This function is deprecated and will be removed. Use the Graphics API instead.

Parameters

Name Type Description
entityID Uuid The ID of the Model or PolyVox entity to get the meshes of.
callback Entities~getMeshesCallback The function to call upon completion.
(static) getMultipleEntityProperties( entityIDs, desiredPropertiesopt ) → {Array.<Entities.EntityProperties>}
Returns: The properties of the entity if the entity can be found, otherwise an empty object.

Get the properties of multiple entities.

Parameters

Name Type Attributes Default Value Description
entityIDs Array.<Uuid> The IDs of the entities to get the properties of.
desiredProperties Array.<string> | string <optional>
[] Either string with property name or array of the names of the properties to get. If the array is empty, all properties are returned.
Example

Retrieve the names of the nearby entities

var SEARCH_RADIUS = 50; // meters
var entityIds = Entities.findEntities(MyAvatar.position, SEARCH_RADIUS);
var propertySets = Entities.getMultipleEntityProperties(entityIds, "name");
print("Nearby entity names: " + JSON.stringify(propertySets));
(static) getNestableType( id ) → {string}
Returns: The type of the item: "entity" if the item is an entity, "avatar" if the item is an avatar; otherwise "unknown" if the item cannot be found.

Get the type — entity or avatar — of an in-world item.

Parameters

Name Type Description
id Uuid The ID of the item to get the type of.
Example

Print some nestable types.

var entity = Entities.addEntity({
    type: "Sphere",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 1, z: -2 })),
    lifetime: 300  // Delete after 5 minutes.
});

print(Entities.getNestableType(entity));  // "entity"
print(Entities.getNestableType(Uuid.generate()));  // "unknown"
(static) getPacketsPerSecond( ) → {number}
Returns: Integer maximum number of entity packets that the client can send per second.

Get the maximum number of entity packets that the client can send per second.

(static) getPropertyInfo( propertyName ) → {Entities.EntityPropertyInfo}
Returns: The information data including propertyEnum, minimum, and maximum if the property can be found, otherwise an empty object.

Get information about entity properties including a minimum to maximum range for numerical properties as well as property enum value.

Parameters

Name Type Description
propertyName string The name of the property to get the information for.
(static) getServerScriptStatus( entityID, callback ) → {boolean}
Returns: true always.

Gets the status of server entity script attached to an entity

Parameters

Name Type Description
entityID Uuid The ID of the entity to get the server entity script status for.
callback Entities~getServerScriptStatusCallback The function to call upon completion.
(static) getStaticCertificateJSON( entityID ) → {string}
Returns: The entity's static certificate as a JSON string if the entity can be found, otherwise an empty string.

Get the static certificate for an entity. The static certificate contains static properties of the item which cannot be altered.

Parameters

Name Type Description
entityID Uuid The ID of the entity to get the static certificate for.
(static) getZonesArePickable( ) → {boolean}
Returns: true if ray picks intersect the bounding box of Zone entities, otherwise false.

Get whether or not ray picks intersect the bounding box of Zone entities. Ray picks are done using findRayIntersection, or the Picks API.

(static) hasPacketsToSend( ) → {boolean}
Returns: true if the client has entity packets waiting to be sent, otherwise false.

Check whether the client has entity packets waiting to be sent.

(static) isAddedEntity( id ) → {boolean}
Returns: true if an object with the given ID exists, false otherwise.

Check if there is an object of a given ID.

Parameters

Name Type Description
id Uuid The ID to check.
(static) isChildOfParent( childID, parentID ) → {boolean}
Returns: true if the childID entity has the parentID entity as a parent or grandparent etc., otherwise false.

Check whether an entity has an entity as an ancestor (parent, parent's parent, etc.).

Parameters

Name Type Description
childID Uuid The ID of the child entity to test for being a child, grandchild, etc.
parentID Uuid The ID of the parent entity to test for being a parent, grandparent, etc.
Example

Check that a grandchild entity is a child of its grandparent.

function createEntity(description, position, parent) {
    var entity = Entities.addEntity({
        type: "Sphere",
        position: position,
        dimensions: Vec3.HALF,
        parentID: parent,
        lifetime: 300  // Delete after 5 minutes.
    });
    print(description + ": " + entity);
    return entity;
}

var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 2, z: -5 }));
var root = createEntity("Root", position, Uuid.NULL);
var child = createEntity("Child", Vec3.sum(position, { x: 0, y: -1, z: 0 }), root);
var grandChild = createEntity("Grandchild", Vec3.sum(position, { x: 0, y: -2, z: 0 }), child);

print("grandChild has root as parent: " + Entities.isChildOfParent(grandChild, root));  // true
(static) isLoaded( id ) → {boolean}
Returns: true if the entity's assets have been loaded, otherwise false.

Check whether an entities's assets have been loaded. For example, for an Model entity the result indicates whether its textures have been loaded.

Parameters

Name Type Description
id Uuid The ID of the entity to check.
(static) localCoordsToVoxelCoords( entityID, localCoords ) → {Vec3}
Returns: The voxel coordinates of the worldCoords if the entityID is a PolyVox entity, otherwise Vec3.ZERO. The value may be fractional.

Convert local coordinates to voxel coordinates in a PolyVox entity. Local coordinates are relative to the minimum axes value corner of the entity, with the scale being the same as world coordinates.

Parameters

Name Type Description
entityID Uuid The ID of the PolyVox entity.
localCoords Vec3 The local coordinates. May be outside the entity's bounding box.
(static) localToWorldAngularVelocity( localAngularVelocity, parentID, parentJointIndex, scalesWithparent ) → {Vec3}
Returns: Vec3

Parameters

Name Type Description
localAngularVelocity Vec3
parentID Uuid
parentJointIndex number
scalesWithparent boolean
(static) localToWorldDimensions( localDimensions, parentID, parentJointIndex, scalesWithparent ) → {Vec3}
Returns: Vec3

Parameters

Name Type Description
localDimensions Vec3
parentID Uuid
parentJointIndex number
scalesWithparent boolean
(static) localToWorldPosition( localPosition, parentID, parentJointIndex, scalesWithparent ) → {Vec3}
Returns: Vec3

Parameters

Name Type Description
localPosition Vec3
parentID Uuid
parentJointIndex number
scalesWithparent boolean
(static) localToWorldRotation( localRotation, parentID, parentJointIndex, scalesWithparent ) → {Quat}
Returns: Quat

Parameters

Name Type Description
localRotation Quat
parentID Uuid
parentJointIndex number
scalesWithparent boolean
(static) localToWorldVelocity( localVelocity, parentID, parentJointIndex, scalesWithparent ) → {Vec3}
Returns: Vec3

Parameters

Name Type Description
localVelocity Vec3
parentID Uuid
parentJointIndex number
scalesWithparent boolean
(static) packetsToSendCount( ) → {number}
Returns: Integer number of entity packets the client has waiting to be sent.

Get the number of entity packets the client has waiting to be sent.

(static) queryPropertyMetadata( entityID, property, scope, callback ) → {boolean}
Returns: true if the request for metadata was successfully sent to the server, otherwise false.

Get metadata for certain entity properties such as script and serverScripts.

Throws:

Throws an error if property is not handled yet or callback is not a function.

Parameters

Name Type Description
entityID Uuid The ID of the entity to get the metadata for.
property string The property name to get the metadata for.
scope object The "this" context that the callback will be executed within.
callback Entities~queryPropertyMetadataCallback The function to call upon completion.
(static) queryPropertyMetadata( entityID, property, callback ) → {boolean}
Returns: true if the request for metadata was successfully sent to the server, otherwise false.

Get metadata for certain entity properties such as script and serverScripts.

Throws:

Throws an error if property is not handled yet or callback is not a function.

Parameters

Name Type Description
entityID Uuid The ID of the entity to get the metadata for.
property string The property name to get the metadata for.
callback Entities~queryPropertyMetadataCallback The function to call upon completion.
(static) reloadServerScripts( entityID ) → {boolean}
Returns: true if the reload request was successfully sent to the server, otherwise false.

Reloads an entity's server entity script such that the latest version re-downloaded.

Parameters

Name Type Description
entityID Uuid The ID of the entity to reload the server entity script of.
(static) sendClickDownOnEntity( entityID, event )

Emit a clickDownOnEntity event.

Parameters

Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
(static) sendClickReleaseOnEntity( entityID, event )

Emit a clickReleaseOnEntity event.

Parameters

Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
(static) sendHoldingClickOnEntity( entityID, event )

Emit a holdingClickOnEntity event.

Parameters

Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
(static) sendHoverEnterEntity( entityID, event )

Emit a hoverEnterEntity event.

Parameters

Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
(static) sendHoverLeaveEntity( entityID, event )

Emit a hoverLeaveEntity event.

Parameters

Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
(static) sendHoverOverEntity( entityID, event )

Emit a hoverOverEntity event.

Parameters

Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
(static) sendMouseMoveOnEntity( entityID, event )

Emit a mouseMoveOnEntity event.

Parameters

Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
(static) sendMousePressOnEntity( entityID, event )

Emit a mousePressOnEntity event.

Parameters

Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
(static) sendMouseReleaseOnEntity( entityID, event )

Emit a mouseReleaseOnEntity event.

Parameters

Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
(static) serversExist( ) → {boolean}
Returns: true if servers exist for the client to send entity packets to, otherwise false.

Check whether servers exist for the client to send entity packets to, i.e., whether you are connected to a domain and its entity server is working.

(static) setAbsoluteJointRotationInObjectFrame( entityID, jointIndex, rotation ) → {boolean}
Returns: true if the entity is a Model entity, the entity is loaded, the joint index is valid, and the rotation is different to the joint's current rotation; otherwise false.

Set the rotation of a joint in a Model entity relative to the entity's position and orientation.

Parameters

Name Type Description
entityID Uuid The ID of the entity.
jointIndex number The integer index of the joint.
rotation Quat The rotation to set the joint to relative to the entity's orientation.
Example

Raise an avatar model's left palm.

entityID = Entities.addEntity({
    type: "Model",
    modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    rotation: MyAvatar.orientation,
    lifetime: 300  // Delete after 5 minutes.
});

Script.setTimeout(function () {
    // Joint data aren't available until after the model has loaded.
    var index = Entities.getJointIndex(entityID, "LeftHand");
    var absoluteRotation = Entities.getAbsoluteJointRotationInObjectFrame(entityID, index);
    absoluteRotation = Quat.multiply(Quat.fromPitchYawRollDegrees(0, 0, 90), absoluteRotation);
    var success = Entities.setAbsoluteJointRotationInObjectFrame(entityID, index, absoluteRotation);
    print("Success: " + success);
}, 2000);
(static) setAbsoluteJointTranslationInObjectFrame( entityID, jointIndex, translation ) → {boolean}
Returns: trueif the entity is a Model entity, the entity is loaded, the joint index is valid, and the translation is different to the joint's current translation; otherwise false.

Set the translation of a joint in a Model entity relative to the entity's position and orientation.

Parameters

Name Type Description
entityID Uuid The ID of the entity.
jointIndex number The integer index of the joint.
translation Vec3 The translation to set the joint to relative to the entity's position and orientation.
(static) setAllPoints( entityID, points ) → {boolean}
Returns: true if the entity's property was updated, otherwise false. The property may fail to be updated if the entity does not exist, the entity is not a Line entity, one of the points is outside the entity's dimensions, or the number of points is greater than the maximum allowed.

Set the linePoints property of a Line entity.

Parameters

Name Type Description
entityID Uuid The ID of the Line entity.
points Array.<Vec3> The array of points to set the entity's linePoints property to.
Example

Change the shape of a Line entity.

// Draw a horizontal line between two points.
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: 0, z: 0 },
        { x:1, y: -0, z: 0 }
    ],
    color: { red: 255, green: 0, blue: 0 },
    lifetime: 300  // Delete after 5 minutes.
});

// Change the line to be a "V".
Script.setTimeout(function () {
    Entities.setAllPoints(entity, [
        { x: -1, y: 1, z: 0 },
        { x: 0, y: -1, z: 0 },
        { x: 1, y: 1, z: 0 },
    ]);
}, 2000);
(static) setAllVoxels( entityID, value )

Set the values of all voxels in a PolyVox entity.

Parameters

Name Type Description
entityID Uuid The ID of the PolyVox entity.
value number If value % 256 == 0 then each voxel is cleared, otherwise each voxel is set.
Example

Create a PolyVox cube.

var entity = Entities.addEntity({
    type: "PolyVox",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 })),
    dimensions: { x: 2, y: 2, z: 2 },
    voxelVolumeSize: { x: 16, y: 16, z: 16 },
    lifetime: 300  // Delete after 5 minutes.
});
Entities.setAllVoxels(entity, 1);
(static) setDrawZoneBoundaries( value )

Set whether or not Zone entities' boundaries should be drawn. Currently not used.

Parameters

Name Type Description
value boolean Set to true if Zone entities' boundaries should be drawn, otherwise false.
(static) setKeyboardFocusEntity( id )

Set the Web entity that has keyboard focus.

Parameters

Name Type Description
id Uuid The ID of the Web entity to set keyboard focus to. Use null or Uuid.NULL to unset keyboard focus from an entity.
(static) setLightsArePickable( value )

Set whether or not ray picks intersect the bounding box of Light entities. By default, Light entities are not intersected. The setting lasts for the Interface session. Ray picks are done using findRayIntersection, or the Picks API.

Parameters

Name Type Description
value boolean Set true to make ray picks intersect the bounding box of Light entities, otherwise false.
(static) setLocalJointRotation( entityID, jointIndex, rotation ) → {boolean}
Returns: true if the entity is a Model entity, the entity is loaded, the joint index is valid, and the rotation is different to the joint's current rotation; otherwise false.

Set the local rotation of a joint in a Model entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity.
jointIndex number The integer index of the joint.
rotation Quat The local rotation to set the joint to.
Example

Make an avatar model turn its head left.

entityID = Entities.addEntity({
    type: "Model",
    modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    rotation: MyAvatar.orientation,
    lifetime: 300  // Delete after 5 minutes.
});

Script.setTimeout(function () {
    // Joint data aren't available until after the model has loaded.
    var index = Entities.getJointIndex(entityID, "Head");
    var rotation = Quat.fromPitchYawRollDegrees(0, 60, 0);
    var success = Entities.setLocalJointRotation(entityID, index, rotation);
    print("Success: " + success);
}, 2000);
(static) setLocalJointRotations( entityID, rotations ) → {boolean}
Returns: true if the entity is a Model entity, the entity is loaded, the model has joints, and at least one of the rotations is different to the model's current rotations; otherwise false.

Set the local rotations of joints in a Model entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity.
rotations Array.<Quat> The local rotations to set the joints to.
Example

Raise both palms of an avatar model.

entityID = Entities.addEntity({
    type: "Model",
    modelURL: "https://hifi-content.s3.amazonaws.com/milad/production/Examples/Models/Avatars/blue_suited.fbx",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    rotation: MyAvatar.orientation,
    lifetime: 300  // Delete after 5 minutes.
});

Script.setTimeout(function () {
    // Joint data aren't available until after the model has loaded.

    // Get all the joint rotations.
    var jointNames = Entities.getJointNames(entityID);
    var jointRotations = [];
    for (var i = 0, length = jointNames.length; i < length; i++) {
        var index = Entities.getJointIndex(entityID, jointNames[i]);
        jointRotations.push(Entities.getLocalJointRotation(entityID, index));
    }

    // Raise both palms.
    var index = jointNames.indexOf("LeftHand");
    jointRotations[index] = Quat.multiply(Quat.fromPitchYawRollDegrees(-90, 0, 0), jointRotations[index]);
    index = jointNames.indexOf("RightHand");
    jointRotations[index] = Quat.multiply(Quat.fromPitchYawRollDegrees(-90, 0, 0), jointRotations[index]);

    // Update all the joint rotations.
    var success = Entities.setLocalJointRotations(entityID, jointRotations);
    print("Success: " + success);
}, 2000);
(static) setLocalJointsData( entityID, rotations, translations ) → {boolean}
Returns: true if the entity is a Model entity, the entity is loaded, the model has joints, and at least one of the rotations or translations is different to the model's current values; otherwise false.

Set the local rotations and translations of joints in a Model entity. This is the same as calling both setLocalJointRotations and setLocalJointTranslations at the same time.

Parameters

Name Type Description
entityID Uuid The ID of the entity.
rotations Array.<Quat> The local rotations to set the joints to.
translations Array.<Vec3> The local translations to set the joints to.
(static) setLocalJointTranslation( entityID, jointIndex, translation ) → {boolean}
Returns: trueif the entity is a Model entity, the entity is loaded, the joint index is valid, and the translation is different to the joint's current translation; otherwise false.

Set the local translation of a joint in a Model entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity.
jointIndex number The integer index of the joint.
translation Vec3 The local translation to set the joint to.
(static) setLocalJointTranslations( entityID, translations ) → {boolean}
Returns: trueif the entity is a Model entity, the entity is loaded, the model has joints, and at least one of the translations is different to the model's current translations; otherwise false.

Set the local translations of joints in a Model entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity.
translations Array.<Vec3> The local translations to set the joints to.
(static) setPacketsPerSecond( packetsPerSecond )

Set the maximum number of entity packets that the client can send per second.

Parameters

Name Type Description
packetsPerSecond number Integer maximum number of entity packets that the client can send per second.
(static) setVoxel( entityID, position, value )

Set the value of a particular voxels in a PolyVox entity.

Parameters

Name Type Description
entityID Uuid The ID of the PolyVox entity.
position Vec3 The position relative to the minimum axes values corner of the entity. The position coordinates are rounded to the nearest integer to get the voxel coordinate. The minimum axes corner voxel is { x: 0, y: 0, z: 0 }.
value number If value % 256 == 0 then voxel is cleared, otherwise the voxel is set.
Example

Create a cube PolyVox entity and clear the minimum axes corner voxel.

var entity = Entities.addEntity({
    type: "PolyVox",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 })),
    dimensions: { x: 2, y: 2, z: 2 },
    voxelVolumeSize: { x: 16, y: 16, z: 16 },
    lifetime: 300  // Delete after 5 minutes.
});
Entities.setAllVoxels(entity, 1);
Entities.setVoxel(entity, { x: 0, y: 0, z: 0 }, 0);
(static) setVoxelCapsule( entityID, start, end, radius, value )

Set the values of all voxels in a capsule-shaped portion of a PolyVox entity.

Parameters

Name Type Description
entityID Uuid The ID of the PolyVox entity.
start Vec3 The center of the sphere of voxels to set, in world coordinates.
end Vec3 The center of the sphere of voxels to set, in world coordinates.
radius number The radius of the capsule cylinder and spherical ends, in world coordinates.
value number If value % 256 == 0 then each voxel is cleared, otherwise each voxel is set.
Example

Create a PolyVox capsule shape.

var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 }));
var polyVox = Entities.addEntity({
    type: "PolyVox",
    position: position,
    dimensions: { x: 2, y: 2, z: 2 },
    voxelVolumeSize: { x: 32, y: 32, z: 32 },
    lifetime: 300  // Delete after 5 minutes.
});
var startPosition = Vec3.sum({ x: -0.5, y: 0, z: 0 }, position);
var endPosition = Vec3.sum({ x: 0.5, y: 0, z: 0 }, position);
Entities.setVoxelCapsule(polyVox, startPosition, endPosition, 0.5, 255);
(static) setVoxelsInCuboid( entityID, lowPosition, cuboidSize, value )

Set the values of all voxels in a cubic portion of a PolyVox entity.

Parameters

Name Type Description
entityID Uuid The ID of the PolyVox entity.
lowPosition Vec3 The position of the minimum axes value corner of the cube of voxels to set, in voxel coordinates.
cuboidSize Vec3 The size of the cube of voxels to set, in voxel coordinates.
value number If value % 256 == 0 then each voxel is cleared, otherwise each voxel is set.
Example

Create a PolyVox cube and clear the voxels in one corner.

var polyVox = Entities.addEntity({
    type: "PolyVox",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 2, y: 2, z: 2 },
    voxelVolumeSize: { x: 16, y: 16, z: 16 },
    lifetime: 300  // Delete after 5 minutes.
});
Entities.setAllVoxels(polyVox, 1);
var cuboidPosition = { x: 12, y: 12, z: 12 };
var cuboidSize = { x: 4, y: 4, z: 4 };
Entities.setVoxelsInCuboid(polyVox, cuboidPosition, cuboidSize, 0);
(static) setVoxelSphere( entityID, center, radius, value )

Set the values of all voxels in a spherical portion of a PolyVox entity.

Parameters

Name Type Description
entityID Uuid The ID of the PolyVox entity.
center Vec3 The center of the sphere of voxels to set, in world coordinates.
radius number The radius of the sphere of voxels to set, in world coordinates.
value number If value % 256 == 0 then each voxel is cleared, otherwise each voxel is set.
Example

Create a PolyVox sphere.

var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 }));
var polyVox = Entities.addEntity({
    type: "PolyVox",
    position: position,
    dimensions: { x: 2, y: 2, z: 2 },
    voxelVolumeSize: { x: 32, y: 32, z: 32 },
    lifetime: 300  // Delete after 5 minutes.
});
Entities.setVoxelSphere(polyVox, position, 0.9, 255);
(static) setZonesArePickable( value )

Set whether or not ray picks intersect the bounding box of Zone entities. By default, Light entities are not intersected. The setting lasts for the Interface session. Ray picks are done using findRayIntersection, or the Picks API.

Parameters

Name Type Description
value boolean Set true to make ray picks intersect the bounding box of Zone entities, otherwise false.
(static) textSize( id, text ) → {Size}
Returns: The size of the text in meters if the object is a text entity, otherwise { height: 0, width : 0 }.

Calculates the size of the given text in the specified object if it is a text entity.

Parameters

Name Type Description
id Uuid The ID of the entity to use for calculation.
text string The string to calculate the size of.
(static) updateAction( entityID, actionID, arguments ) → {boolean}
Returns: true if the update was successful, otherwise false.

Update an entity action.

Parameters

Name Type Description
entityID Uuid The ID of the entity with the action to update.
actionID Uuid The ID of the action to update.
arguments Entities.ActionArguments The arguments to update.
(static) verifyStaticCertificateProperties( entityID ) → {boolean}
Returns: true if the entity can be found an its certificateID property is present and its value matches the entity's static certificate JSON; otherwise false.

Verify the entity's proof of provenance, i.e., that the entity's certificateID property was produced by High Fidelity signing the entity's static certificate JSON.

Parameters

Name Type Description
entityID Uuid The ID of the entity to verify.
(static) voxelCoordsToLocalCoords( entityID, voxelCoords ) → {Vec3}
Returns: The local coordinates of the voxelCoords if the entityID is a PolyVox entity, otherwise Vec3.ZERO.

Convert voxel coordinates in a PolyVox entity to local coordinates relative to the minimum axes value corner of the entity, with the scale being the same as world coordinates.

Parameters

Name Type Description
entityID Uuid The ID of the PolyVox entity.
voxelCoords Vec3 The voxel coordinates. May be fractional and outside the entity's bounding box.
Example

Get the world dimensions of a voxel in a PolyVox entity.

var polyVox = Entities.addEntity({
    type: "PolyVox",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 })),
    dimensions: { x: 2, y: 2, z: 2 },
    voxelVolumeSize: { x: 16, y: 16, z: 16 },
    lifetime: 300  // Delete after 5 minutes.
});
var voxelDimensions = Entities.voxelCoordsToLocalCoords(polyVox, Vec3.ONE);
print("Voxel dimensions: " + JSON.stringify(voxelDimensions));
(static) voxelCoordsToWorldCoords( entityID, voxelCoords ) → {Vec3}
Returns: The world coordinates of the voxelCoords if the entityID is a PolyVox entity, otherwise Vec3.ZERO.

Convert voxel coordinates in a PolyVox entity to world coordinates. Voxel coordinates are relative to the minimum axes values corner of the entity with a scale of Vec3.ONE being the dimensions of each voxel.

Parameters

Name Type Description
entityID Uuid The ID of the PolyVox entity.
voxelCoords Vec3 The voxel coordinates. May be fractional and outside the entity's bounding box.
Example

Create a PolyVox cube with the 0,0,0 voxel replaced by a sphere.

// Cube PolyVox with 0,0,0 voxel missing.
var polyVox = Entities.addEntity({
    type: "PolyVox",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 })),
    dimensions: { x: 2, y: 2, z: 2 },
    voxelVolumeSize: { x: 16, y: 16, z: 16 },
    lifetime: 300  // Delete after 5 minutes.
});
Entities.setAllVoxels(polyVox, 1);
Entities.setVoxel(polyVox, { x: 0, y: 0, z: 0 }, 0);

// Red sphere in 0,0,0 corner position.
var cornerPosition = Entities.voxelCoordsToWorldCoords(polyVox, { x: 0, y: 0, z: 0 });
var voxelDimensions = Vec3.multiply(2 / 16, Vec3.ONE);
var sphere = Entities.addEntity({
    type: "Sphere",
    position: Vec3.sum(cornerPosition, Vec3.multiply(0.5, voxelDimensions)),
    dimensions: voxelDimensions,
    color: { red: 255, green: 0, blue: 0 },
    lifetime: 300  // Delete after 5 minutes.
});
(static) wantsHandControllerPointerEvents( entityID ) → {boolean}
Returns: true if the entity can be found and it wants hand controller pointer events, otherwise false.

Check whether an entity wants hand controller pointer events. For example, a Web entity does but a Shape entity doesn't.

Parameters

Name Type Description
entityID Uuid The ID of the entity.
(static) worldCoordsToVoxelCoords( entityID, worldCoords ) → {Vec3}
Returns: The voxel coordinates of the worldCoords if the entityID is a PolyVox entity, otherwise Vec3.ZERO. The value may be fractional.

Convert world coordinates to voxel coordinates in a PolyVox entity. Voxel coordinates are relative to the minimum axes values corner of the entity, with a scale of Vec3.ONE being the dimensions of each voxel.

Parameters

Name Type Description
entityID Uuid The ID of the PolyVox entity.
worldCoords Vec3 The world coordinates. May be outside the entity's bounding box.
(static) worldToLocalAngularVelocity( worldAngularVelocity, parentID, parentJointIndex, scalesWithparent ) → {Vec3}
Returns: Vec3

Parameters

Name Type Description
worldAngularVelocity Vec3
parentID Uuid
parentJointIndex number
scalesWithparent boolean
(static) worldToLocalDimensions( worldDimensions, parentID, parentJointIndex, scalesWithparent ) → {Vec3}
Returns: Vec3

Parameters

Name Type Description
worldDimensions Vec3
parentID Uuid
parentJointIndex number
scalesWithparent boolean
(static) worldToLocalPosition( worldPosition, parentID, parentJointIndex, scalesWithparent ) → {Vec3}
Returns: Vec3

Parameters

Name Type Description
worldPosition Vec3
parentID Uuid
parentJointIndex number
scalesWithparent boolean
(static) worldToLocalRotation( worldRotation, parentID, parentJointIndex, scalesWithparent ) → {Quat}
Returns: Quat

Parameters

Name Type Description
worldRotation Quat
parentID Uuid
parentJointIndex number
scalesWithparent boolean
(static) worldToLocalVelocity( worldVelocity, parentID, parentJointIndex, scalesWithparent ) → {Vec3}
Returns: Vec3

Parameters

Name Type Description
worldVelocity Vec3
parentID Uuid
parentJointIndex number
scalesWithparent boolean

Signal Details

addingEntity( entityID )
Returns: Signal

Triggered when an entity is added to Interface's local in-memory tree of entities it knows about. This may occur when entities are loaded upon visiting a domain, when the user rotates their view so that more entities become visible, and when any type of entity is added (e.g., by {@Entities.addEntity|addEntity}).

Parameters

Name Type Description
entityID Uuid The ID of the entity added.
Example

Report when an entity is added.

Entities.addingEntity.connect(function (entityID) {
    print("Added entity: " + entityID);
});
addingWearable( entityID )
Returns: Signal

Triggered when an 'wearable' entity is added to Interface's local in-memory tree of entities it knows about. This may occur when 'wearable' entities are added to avatar

Parameters

Name Type Description
entityID Uuid The ID of the 'wearable' entity added.
Example

Report when an 'wearable' entity is added.

Entities.addingWearable.connect(function (entityID) {
    print("Added wearable: " + entityID);
});
canAdjustLocksChanged( canAdjustLocks )
Returns: Signal

Triggered when your ability to change the locked property of entities changes.

Parameters

Name Type Description
canAdjustLocks boolean true if the script can change the locked property of an entity, otherwise false.
Example

Report when your ability to change locks changes.

function onCanAdjustLocksChanged(canAdjustLocks) {
    print("You can adjust entity locks: " + canAdjustLocks);
}
Entities.canAdjustLocksChanged.connect(onCanAdjustLocksChanged);
canRezCertifiedChanged( canRezCertified )
Returns: Signal

Triggered when your ability to rez (create) certified entities changes. Certified entities are entities that have PoP certificates.

Parameters

Name Type Description
canRezCertified boolean true if the script can rez (create) certified entities, otherwise false.
canRezChanged( canRez )
Returns: Signal

Triggered when your ability to rez (create) entities changes.

Parameters

Name Type Description
canRez boolean true if the script can rez (create) entities, otherwise false.
canRezTmpCertifiedChanged( canRezTmpCertified )
Returns: Signal

Triggered when your ability to rez (create) temporary certified entities changes. Temporary entities are entities with a finite lifetime property value set. Certified entities are entities that have PoP certificates.

Parameters

Name Type Description
canRezTmpCertified boolean true if the script can rez (create) temporary certified entities, otherwise false.
canRezTmpChanged( canRezTmp )
Returns: Signal

Triggered when your ability to rez (create) temporary entities changes. Temporary entities are entities with a finite lifetime property value set.

Parameters

Name Type Description
canRezTmp boolean true if the script can rez (create) temporary entities, otherwise false.
canWriteAssetsChanged( canWriteAssets )
Returns: Signal

Triggered when your ability to make changes to the asset server's assets changes.

Parameters

Name Type Description
canWriteAssets boolean true if the script can change the ? property of an entity, otherwise false.
clearingEntities( )
Returns: Signal

Triggered when you disconnect from a domain, at which time Interface's local in-memory tree of entities it knows about is cleared.

Example

Report when Interfaces's entity tree is cleared.

Entities.clearingEntities.connect(function () {
    print("Entities cleared");
});
clickDownOnEntity( entityID, event )
Returns: Signal

Triggered when a mouse button is clicked while the mouse cursor is on an entity. Note: Not triggered by controller.

Parameters

Name Type Description
entityID Uuid The ID of the entity that was clicked.
event PointerEvent Details of the event.
clickReleaseOnEntity( entityID, event )
Returns: Signal

Triggered when a mouse button is released after clicking on an entity, even if the mouse cursor has moved off the entity. Note: Not triggered by controller.

Parameters

Name Type Description
entityID Uuid The ID of the entity that was originally clicked.
event PointerEvent Details of the event.
collisionWithEntity( idA, idB, collision )
Returns: Signal

Triggered on the client that is the physics simulation owner during the collision of two entities. Note: Isn't triggered for a collision with an avatar.

Parameters

Name Type Description
idA Uuid The ID of one entity in the collision. For an entity script, this is the ID of the entity containing the script.
idB Uuid The ID of the other entity in the collision.
collision Collision The details of the collision.
Example

Change the color of an entity when it collides with another entity.

var entityScript = (function () {
    function randomInteger(min, max) {
        return Math.floor(Math.random() * (max - min + 1)) + min;
    }

    this.collisionWithEntity = function (myID, otherID, collision) {
        Entities.editEntity(myID, {
            color: {
                red: randomInteger(128, 255),
                green: randomInteger(128, 255),
                blue: randomInteger(128, 255)
            }
        });
    };
});

var entityID = Entities.addEntity({
    type: "Box",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    dimensions: { x: 0.5, y: 0.5, z: 0.5 },
    color: { red: 128, green: 128, blue: 128 },
    gravity: { x: 0, y: -9.8, z: 0 },
    velocity: { x: 0, y: 0.1, z: 0 },  // Kick off physics.
    dynamic: true,
    collisionless: false,  // So that collision events are generated.
    script: "(" + entityScript + ")",  // Could host the script on a Web server instead.
    lifetime: 300  // Delete after 5 minutes.
});
deletingEntity( entityID )
Returns: Signal

Triggered when an entity is deleted.

Parameters

Name Type Description
entityID Uuid The ID of the entity deleted.
Example

Report when an entity is deleted.

Entities.deletingEntity.connect(function (entityID) {
    print("Deleted entity: " + entityID);
});
deletingWearable( entityID )
Returns: Signal

Triggered when an 'wearable' entity is deleted.

Parameters

Name Type Description
entityID Uuid The ID of the 'wearable' entity deleted.
Example

Report when an 'wearable' entity is deleted.

Entities.deletingWearable.connect(function (entityID) {
    print("Deleted wearable: " + entityID);
});
enterEntity( entityID )
Returns: Signal

Triggered when an avatar enters an entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity that the avatar entered.
Example

Change the color of an entity when an avatar enters or leaves.

var entityScript = (function () {
    this.enterEntity = function (entityID) {
        print("Enter entity");
        Entities.editEntity(entityID, {
            color: { red: 255, green: 64, blue: 64 },
        });
    };
    this.leaveEntity = function (entityID) {
        print("Leave entity");
        Entities.editEntity(entityID, {
            color: { red: 128, green: 128, blue: 128 },
        });
    };
});

var entityID = Entities.addEntity({
    type: "Sphere",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    dimensions: { x: 3, y: 3, z: 3 },
    color: { red: 128, green: 128, blue: 128 },
    collisionless: true,  // So that avatar can walk through entity.
    script: "(" + entityScript + ")",  // Could host the script on a Web server instead.
    lifetime: 300  // Delete after 5 minutes.
});
holdingClickOnEntity( entityID, event )
Returns: Signal

Repeatedly triggered while a mouse button continues to be held after clicking an entity, even if the mouse cursor has moved off the entity. Note: Not triggered by controller.

Parameters

Name Type Description
entityID Uuid The ID of the entity that was originally clicked.
event PointerEvent Details of the event.
hoverEnterEntity( entityID, event )
Returns: Signal

Triggered when the mouse cursor or controller laser starts hovering on an entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity that is being hovered.
event PointerEvent Details of the event.
hoverLeaveEntity( entityID, event )
Returns: Signal

Triggered when the mouse cursor or controller laser stops hovering over an entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity that was being hovered.
event PointerEvent Details of the event.
hoverOverEntity( entityID, event )
Returns: Signal

Repeatedly triggered when the mouse cursor or controller laser moves while hovering over an entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity that is being hovered.
event PointerEvent Details of the event.
leaveEntity( entityID )
Returns: Signal

Triggered when an avatar leaves an entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity that the avatar left.
mouseDoublePressOffEntity( event )
Returns: Signal

Triggered when a mouse button is double-clicked while the mouse cursor is not on an entity.

Parameters

Name Type Description
event PointerEvent Details of the event.
mouseDoublePressOnEntity( entityID, event )
Returns: Signal

Triggered when a mouse button is double-clicked while the mouse cursor is on an entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity that was double-pressed.
event PointerEvent Details of the event.
mouseMoveOnEntity( entityID, event )
Returns: Signal

Repeatedly triggered while the mouse cursor or controller laser moves on an entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity that was moved on.
event PointerEvent Details of the event.
mousePressOffEntity( event )
Returns: Signal

Triggered when a mouse button is clicked while the mouse cursor is not on an entity.

Parameters

Name Type Description
event PointerEvent Details of the event.
mousePressOnEntity( entityID, event )
Returns: Signal

Triggered when a mouse button is clicked while the mouse cursor is on an entity, or a controller trigger is fully pressed while its laser is on an entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity that was pressed.
event PointerEvent Details of the event.
Example

Report when an entity is clicked with the mouse or laser.

function onMousePressOnEntity(entityID, event) {
    print("Clicked on entity: " + entityID);
}

Entities.mousePressOnEntity.connect(onMousePressOnEntity);
mouseReleaseOnEntity( entityID, event )
Returns: Signal

Triggered when a mouse button is released after clicking on an entity or the controller trigger is partly or fully released after pressing on an entity, even if the mouse pointer or controller laser has moved off the entity.

Parameters

Name Type Description
entityID Uuid The ID of the entity that was originally pressed.
event PointerEvent Details of the event.
preload( entityID )
Returns: Signal

Triggered when the script starts for a user.

Note: Can only be connected to via this.preload = function (...) { ... } in the entity script.

Available in:Client Entity ScriptsServer Entity Scripts

Parameters

Name Type Description
entityID Uuid The ID of the entity that the script is running in.
Example

Get the ID of the entity that a client entity script is running in.

var entityScript = (function () {
    this.entityID = Uuid.NULL;

    this.preload = function (entityID) {
        this.entityID = entityID;
        print("Entity ID: " + this.entityID);
    };
);

var entityID = Entities.addEntity({
    type: "Box",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    dimensions: { x: 0.5, y: 0.5, z: 0.5 },
    color: { red: 255, green: 0, blue: 0 },
    script: "(" + entityScript + ")",  // Could host the script on a Web server instead.
    lifetime: 300  // Delete after 5 minutes.
});
unload( )
Returns: Signal

Triggered when the script terminates for a user.

Note: Can only be connected to via this.unoad = function () { ... } in the entity script.

Available in:Client Entity ScriptsServer Entity Scripts

webEventReceived( entityID, message )
Returns: Signal

Triggered in when a script in a Web entity's Web page script sends an event over the script's EventBridge.

Parameters

Name Type Description
entityID Uuid The ID of the entity that event was received from.
message string The message received.