Entities - Vircadia API Docs

Description

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

The Entities API provides facilities to create and interact with entities. Entities are 2D or 3D objects displayed in-world. Depending on their EntityHostType, they may persist in the domain as "domain" entities, travel to different domains with a user as "avatar" entities, or be visible only to an individual user as "local" entities (a.k.a. "overlays").

Note: For Interface, avatar, and client entity scripts, the entities available to scripts are those that Interface has displayed and so knows about. For assignment client scripts, the entities available are those that are "seen" by the EntityViewer. For entity server scripts, all entities are available.

Entity Types & Properties

For a list of the entity types that you can use, see Entity Types.

For the properties of the different entity types, see Entity Properties. Some properties are universal to all entity types, and some are specific to particular entity types.

Entity Methods

Some of the API's signals correspond to entity methods that are called, if present, in the entity being interacted with. The client or server entity script must expose them as a property. However, unlike Entities.callEntityMethod, server entity scripts do not need to list them in an remotelyCallable property. The entity methods are called with parameters per their corresponding signal.

Method Name	Corresponding Signal
`clickDownOnEntity`	Entities.clickDownOnEntity
`clickReleaseOnEntity`	Entities.clickReleaseOnEntity
`collisionWithEntity`	Entities.collisionWithEntity
`enterEntity`	Entities.enterEntity
`holdingClickOnEntity`	Entities.holdingClickOnEntity
`hoverEnterEntity`	Entities.hoverEnterEntity
`hoverLeaveEntity`	Entities.hoverLeaveEntity
`hoverOverEntity`	Entities.hoverOverEntity
`leaveEntity`	Entities.leaveEntity
`mouseDoublePressOnEntity`	Entities.mouseDoublePressOnEntity
`mouseMoveOnEntity`	Entities.mouseMoveOnEntity
`mouseMoveEvent`	Deprecated: Use `mouseMoveOnEntity` instead.
`mousePressOnEntity`	Entities.mousePressOnEntity
`mouseReleaseOnEntity`	Entities.mouseReleaseOnEntity

See Entities.clickDownOnEntity for an example.

Properties

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

Methods

Name	Return Value	Summary
`AABoxIntersectsCapsule`	boolean	Checks whether an axis-aligned box and a capsule intersect.
`addAction`	Uuid	Adds 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	Adds a new domain, avatar, or local entity.
`addEntity`	Uuid	Adds a new avatar entity (`entityHostType` property is `"avatar"`) or domain entity (`entityHostType` property is `"domain"`).
`appendPoint`	boolean	Appends a point to a Line entity. Deprecated: This function is deprecated and will be removed. Use PolyLine entities instead.
`callEntityClientMethod`	None	Calls 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. Additionally, the client 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.
`callEntityMethod`	None	Calls a method in a client entity script from an Interface, avatar, or client entity script, or calls 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 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	Calls a method in a server entity script from an Interface, avatar, or client entity script. The server entity script method must be exposed as a property in the target server entity script. Additionally, 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.
`canAdjustLocks`	boolean	Checks whether or not the script can change the `locked` property of entities. Locked entities have their `locked` property set to `true` and cannot be edited or deleted.
`canGetAndSetPrivateUserData`	boolean	Checks whether or not the script can get and set the `privateUserData` property of entities.
`canReplaceContent`	boolean	Checks whether or not the script can replace the domain's content set.
`canRez`	boolean	Checks whether or not the script can rez (create) new entities in the domain.
`canRezAvatarEntities`	boolean	Checks whether or not the script can rez avatar entities.
`canRezCertified`	boolean	Checks whether or not the script can rez (create) new certified entities in the domain. Certified entities are entities that have PoP certificates.
`canRezTmp`	boolean	Checks whether or not the script can rez (create) new temporary entities in the domain. Temporary entities are entities with a finite `lifetime` property value set.
`canRezTmpCertified`	boolean	Checks whether or not the script 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	Checks whether or not the script can make changes to the asset server's assets.
`cloneEntity`	Uuid	Creates a clone of an entity. The clone has the same properties as the original except that: it has a modified `name` property, clone-related properties are set per the original entity's clone-related properties (e.g., `cloneLifetime`), and its clone-related properties are set to their defaults. Domain entities must have their `cloneable` property value be `true` in order to be cloned. A domain entity can be cloned by a client that doesn't have rez permissions in the domain. Avatar entities must have their `cloneable` and `cloneAvatarEntity` property values be `true` in order to be cloned.
`deleteAction`	boolean	Deletes an action from an entity.
`deleteEntity`	None	Deletes an entity.
`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	Edits an entity, changing one or more of its property values.
`emitScriptEvent`	None	Sends a message to a Web entity's HTML page. To receive the message, the web page's script must connect to the `EventBridge` that is automatically provided to the script: `EventBridge.scriptEventReceived.connect(function(message) { ... });` Use Entities.webEventReceived to receive messages from the Web entity's HTML page. Alternatively, you can use Entities.getEntityObject to exchange messages over a Web entity's HTML event bridge.
`findClosestEntity`	Uuid	Finds the domain or avatar entity with a position closest to a specified point and within a specified radius.
`findEntities`	Array.<Uuid>	Finds all domain and avatar entities that intersect a sphere. Note: Server entity scripts only find entities that have a server entity script running in them or a parent entity. You can apply a dummy script to entities that you want found in a search.
`findEntitiesByName`	Array.<Uuid>	Finds all domain and avatar entities with a particular name that intersect a sphere. Note: Server entity scripts only find entities that have a server entity script running in them or a parent entity. You can apply a dummy script to entities that you want found in a search.
`findEntitiesByType`	Array.<Uuid>	Finds all domain and avatar entities of a particular type that intersect a sphere. Note: Server entity scripts only find entities that have a server entity script running in them or a parent entity. You can apply a dummy script to entities that you want found in a search.
`findEntitiesInBox`	Array.<Uuid>	Finds all domain and avatar entities whose axis-aligned boxes intersect a search axis-aligned box. Note: Server entity scripts only find entities that have a server entity script running in them or a parent entity. You can apply a dummy script to entities that you want found in a search.
`findEntitiesInFrustum`	Array.<Uuid>	Finds all domain and avatar entities whose axis-aligned boxes intersect a search frustum. Note: Server entity scripts only find entities that have a server entity script running in them or a parent entity. You can apply a dummy script to entities that you want found in a search.
`findRayIntersection`	Entities.RayToEntityIntersectionResult	Finds the first avatar or domain 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	Gets the rotation of a joint in a Model entity relative to the entity's position and orientation.
`getAbsoluteJointTranslationInObjectFrame`	Vec3	Gets the translation of a joint in a Model entity relative to the entity's position and orientation.
`getActionArguments`	Entities.ActionArguments	Gets the arguments of an action.
`getActionIDs`	Array.<Uuid>	Gets the IDs of the actions that are associated with an entity.
`getChildrenIDs`	Array.<Uuid>	Gets the IDs of entities and avatars that are directly parented to an entity or avatar model. To get all descendants, you can recurse on the IDs returned.
`getChildrenIDsOfJoint`	Array.<Uuid>	Gets the IDs of entities and avatars that are directly parented to an entity or avatar model's joint. To get all descendants, you can use getChildrenIDs to recurse on the IDs returned.
`getDrawZoneBoundaries`	boolean	Gets whether or not Zone entities' boundaries should be drawn. Currently not used.
`getEntityLocalTransform`	Mat4	Gets the object to parent transform, excluding scale, of an entity.
`getEntityObject`	object	Gets an entity's script object. In particular, this is useful for accessing a Web entity's HTML `EventBridge` script object to exchange messages with the web page script. To send a message from an Interface script to a Web entity over its event bridge: `var entityObject = Entities.getEntityObject(entityID); entityObject.emitScriptEvent(message);` To receive a message from a Web entity over its event bridge in an Interface script: `var entityObject = Entities.getentityObject(entityID); entityObject.webEventReceived.connect(function(message) { ... };` Alternatively, you can use Entities.emitScriptEvent and Entities.webEventReceived to exchange messages with a Web entity over its event bridge.
`getEntityProperties`	Entities.EntityProperties	Gets an entity's property values.
`getEntityTransform`	Mat4	Gets the object to world transform, excluding scale, of an entity.
`getEntityType`	Entities.EntityType	Gets an entity's type.
`getJointIndex`	number	Gets the index of a named joint in a Model entity.
`getJointNames`	Array.<string>	Gets the names of all the joints in a Model entity.
`getJointParent`	number	Gets the index of the parent joint of a joint in a Model entity.
`getKeyboardFocusEntity`	Uuid	Gets the ID of the Web entity that has keyboard focus.
`getLifetimeBPS`	number	Gets the entity bytes per second send rate of the client over its lifetime.
`getLifetimeBPSQueued`	number	Gets the entity bytes per second queued rate of the client over its lifetime.
`getLifetimeBytesQueued`	number	Gets the total bytes of entity packets queued by the client over its lifetime.
`getLifetimeBytesSent`	number	Gets the total bytes of entity packets sent by the client over its lifetime.
`getLifetimeInSeconds`	number	Gets the lifetime of the client from the first entity packet sent until now, in seconds.
`getLifetimeInUsecs`	number	Gets the lifetime of the client from the first entity packet sent until now, in microseconds.
`getLifetimePacketsQueued`	number	Gets the total number of entity packets queued by the client over its lifetime.
`getLifetimePacketsSent`	number	Gets the total number of entity packets sent by the client over its lifetime.
`getLifetimePPS`	number	Gets the entity packets per second send rate of the client over its lifetime.
`getLifetimePPSQueued`	number	Gets the entity packets per second queued rate of the client over its lifetime.
`getLightsArePickable`	boolean	Gets whether or not ray picks intersect the bounding box of Light entities. Ray picks are performed using findRayIntersection, or the Picks API.
`getLocalJointRotation`	Quat	Gets the local rotation of a joint in a Model entity.
`getLocalJointTranslation`	Vec3	Gets the local translation of a joint in a Model entity.
`getMeshes`	None	Gets the meshes in a Model or PolyVox entity. Deprecated: This function is deprecated and will be removed. It no longer works for Model entities. Use the Graphics API instead.
`getMultipleEntityProperties`	Array.<Entities.EntityProperties>	Gets the properties of multiple entities.
`getNestableType`	Entities.NestableType	Gets the type — entity or avatar — of an in-world item.
`getPacketsPerSecond`	number	Gets the maximum number of entity packets that the client can send per second.
`getPropertyInfo`	Entities.EntityPropertyInfo	Gets information about an entity property, including a minimum to maximum range for some numerical properties.
`getServerScriptStatus`	boolean	Gets the status of a server entity script attached to an entity.
`getStaticCertificateJSON`	string	Gets the static certificate for an entity. The static certificate contains static properties of the item which cannot be altered.
`getZonesArePickable`	boolean	Gets whether or not ray picks intersect the bounding box of Zone entities. Ray picks are performed using findRayIntersection, or the Picks API.
`hasPacketsToSend`	boolean	Checks whether the client has entity packets waiting to be sent.
`isAddedEntity`	boolean	Checks if there is an entity with a specified ID.
`isChildOfParent`	boolean	Checks whether an entity has an entity as an ancestor (parent, parent's parent, etc.).
`isLoaded`	boolean	Checks whether an entity's assets have been loaded. For example, for an `Model` entity the result indicates whether its textures have been loaded.
`localCoordsToVoxelCoords`	Vec3	Converts 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. 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.
`localToWorldAngularVelocity`	Vec3	Converts a Euler angular velocity in an avatar, entity, or joint's local coordinate to an angular velocity in world coordinates.
`localToWorldDimensions`	Vec3	Converts dimensions in an avatar or entity's local coordinates to dimensions in world coordinates.
`localToWorldPosition`	Vec3	Converts a position in an avatar, entity, or joint's local coordinate to a position in world coordinates.
`localToWorldRotation`	Quat	Converts a rotation or orientation in an avatar, entity, or joint's local coordinate to a rotation in world coordinates.
`localToWorldVelocity`	Vec3	Converts a velocity in an avatar, entity, or joint's local coordinate to a velocity in world coordinates.
`packetsToSendCount`	number	Gets the number of entity packets the client has waiting to be sent.
`queryPropertyMetadata`	boolean	Gets metadata for certain entity properties such as `script` and `serverScripts`.
`queryPropertyMetadata`	boolean	Gets 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	Emits a clickDownOnEntity event.
`sendClickReleaseOnEntity`	None	Emits a clickReleaseOnEntity event.
`sendHoldingClickOnEntity`	None	Emits a holdingClickOnEntity event.
`sendHoverEnterEntity`	None	Emits a hoverEnterEntity event.
`sendHoverLeaveEntity`	None	Emits a hoverLeaveEntity event.
`sendHoverOverEntity`	None	Emits a hoverOverEntity event.
`sendMouseMoveOnEntity`	None	Emits a mouseMoveOnEntity event.
`sendMousePressOnEntity`	None	Emits a mousePressOnEntity event.
`sendMouseReleaseOnEntity`	None	Emits a mouseReleaseOnEntity event.
`serversExist`	boolean	Checks 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	Sets the rotation of a joint in a Model entity relative to the entity's position and orientation.
`setAbsoluteJointTranslationInObjectFrame`	boolean	Sets the translation of a joint in a Model entity relative to the entity's position and orientation.
`setAllPoints`	boolean	Sets all the points in a Line entity. Deprecated: This function is deprecated and will be removed. Use PolyLine entities instead.
`setAllVoxels`	None	Sets the values of all voxels in a PolyVox entity.
`setDrawZoneBoundaries`	None	Sets whether or not Zone entities' boundaries should be drawn. Currently not used.
`setKeyboardFocusEntity`	None	Sets the Web entity that has keyboard focus.
`setLightsArePickable`	None	Sets 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 performed using findRayIntersection, or the Picks API.
`setLocalJointRotation`	boolean	Sets the local rotation of a joint in a Model entity.
`setLocalJointRotations`	boolean	Sets the local rotations of joints in a Model entity.
`setLocalJointsData`	boolean	Sets 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	Sets the local translation of a joint in a Model entity.
`setLocalJointTranslations`	boolean	Sets the local translations of joints in a Model entity.
`setPacketsPerSecond`	None	Sets the maximum number of entity packets that the client can send per second.
`setVoxel`	None	Sets the value of a particular voxel in a PolyVox entity.
`setVoxelCapsule`	None	Sets the values of all voxels in a capsule-shaped portion of a PolyVox entity.
`setVoxelsInCuboid`	None	Sets the values of all voxels in a cubic portion of a PolyVox entity.
`setVoxelSphere`	None	Sets the values of all voxels in a spherical portion of a PolyVox entity.
`setZonesArePickable`	None	Sets whether or not ray picks intersect the bounding box of Zone entities. By default, Zone entities are not intersected. The setting lasts for the Interface session. Ray picks are performed using findRayIntersection, or the Picks API.
`textSize`	Size	Calculates the size of some text in a Text entity. The entity need not be set visible. Note: The size of text in a Text entity cannot be calculated immediately after the entity is created; a short delay is required while the entity finishes being created.
`updateAction`	boolean	Updates an entity action.
`verifyStaticCertificateProperties`	boolean	Verifies 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	Converts voxel coordinates in a PolyVox entity to local coordinates. Local coordinates are relative to the minimum axes value corner of the entity, with the scale being the same as 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.
`voxelCoordsToWorldCoords`	Vec3	Converts 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	Checks whether an entity wants hand controller pointer events. For example, a Web entity does but a Shape entity doesn't.
`worldCoordsToVoxelCoords`	Vec3	Converts 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	Converts a Euler angular velocity in world coordinates to an angular velocity in an avatar, entity, or joint's local coordinates.
`worldToLocalDimensions`	Vec3	Converts dimensions in world coordinates to dimensions in an avatar or entity's local coordinates.
`worldToLocalPosition`	Vec3	Converts a position in world coordinates to a position in an avatar, entity, or joint's local coordinates.
`worldToLocalRotation`	Quat	Converts a rotation or orientation in world coordinates to rotation in an avatar, entity, or joint's local coordinates.
`worldToLocalVelocity`	Vec3	Converts a velocity in world coordinates to a velocity in an avatar, entity, or joint's local coordinates.

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 created (e.g., by addEntity).
`addingWearable`	Triggered when a "wearable" entity is added to Interface's local in-memory tree of entities it knows about, for example when adding a "wearable" to your avatar.
`canAdjustLocksChanged`	Triggered when your ability to change the `locked` property of entities changes.
`canGetAndSetPrivateUserDataChanged`	Triggered when your ability to get and set private user data changes.
`canRezAvatarEntitiesChanged`	Triggered when your ability to use avatar entities is changed.
`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 that 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 controllers. See also, Entity Methods and Script.addEventHandler.
`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 controllers. See also, Entity Methods and Script.addEventHandler.
`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. See also, Entity Methods and Script.addEventHandler.
`deletingEntity`	Triggered when an entity is deleted.
`deletingWearable`	Triggered when a "wearable" entity is deleted, for example when removing a "wearable" from your avatar.
`enterEntity`	Triggered when an avatar enters an entity. Note: At the initial loading of the script, if the avatar is already present inside the entity, it might be too late to catch this event when the script runs, so it won't trigger. The preload signal can be used to handle those cases. See also, Entity Methods and Script.addEventHandler.
`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 controllers. See also, Entity Methods and Script.addEventHandler.
`hoverEnterEntity`	Triggered when the mouse cursor or controller laser starts hovering on an entity. See also, Entity Methods and Script.addEventHandler.
`hoverLeaveEntity`	Triggered when the mouse cursor or controller laser stops hovering over an entity. See also, Entity Methods and Script.addEventHandler.
`hoverOverEntity`	Repeatedly triggered when the mouse cursor or controller laser moves while hovering over an entity. See also, Entity Methods and Script.addEventHandler.
`leaveEntity`	Triggered when an avatar leaves an entity. See also, Entity Methods and Script.addEventHandler.
`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. See also, Entity Methods and Script.addEventHandler.
`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. See also, Entity Methods and Script.addEventHandler.
`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. See also, Entity Methods and Script.addEventHandler.
`preload`	Triggered when the script starts for a user. See also, Script.entityScriptPreloadFinished. Note: Can only be connected to via `this.preload = function (...) { ... }` in the entity script. Supported Script Types: Client Entity Scripts • Server 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. Supported Script Types: Client Entity Scripts • Server Entity Scripts
`webEventReceived`	Triggered when a script in a Web entity's HTML sends an event over the entity's HTML event bridge. The HTML web page can send a message by calling: `EventBridge.emitWebEvent(message);` Use Entities.emitScriptEvent to send messages to the Web entity's HTML page. Alternatively, you can use Entities.getEntityObject to exchange messages over a Web entity's HTML event bridge.

Type Definitions

ActionArguments
Type: object

Different entity action types have different arguments: some common to all actions (listed in the table) and some specific to each ActionType (linked to below).

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	`true` if the action was created during the current client session, `false` if it wasn't. Read-only. Default Value: true
::no-motion-state	boolean	Is present with a value of `true` when the entity hasn't been registered with the physics engine yet (e.g., if the action hasn't been properly configured), otherwise the property is `undefined`. Read-only.
::active	boolean	`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 the property is `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 the property is `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

otherEntityID

Uuid

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

Default Value: null

pivot

Vec3

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

Default Value: 0,0,0

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
otherEntityID	Uuid	The ID of the other entity that is connected to the joint. Default Value: null
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
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: 2*Math.PI
swingSpan2	number	The angle through which the joint can move in the other axis of the cone, in radians. Default Value: 2*Math.PI
twistSpan	number	The angle through with the joint can twist, in radians. Default Value: 2*Math.PI

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
otherID	Uuid	If an entity ID, the `targetPosition` and `targetRotation` are relative to the entity's position and rotation. Default Value: null
otherJointIndex	Uuid	If a joint index in the `otherID` entity, the `targetPosition` and `targetRotation` are relative to the entity joint's position and rotation. Default Value: null
targetPosition	Vec3	The target position. Default Value: 0,0,0
targetRotation	Quat	The target rotation. Default Value: 0,0,0,1
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
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
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
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: -2*Math.PI
high	number	The most positive angle that the hinge can take, in radians. Default Value: 2*Math.PI
angle	number	The current angle of the hinge, in radians, range `-Math.PI` – `Math.PI`. 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
hand	string	The hand holding the entity: `"left"` or `"right"`. Default Value: right
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
kinematic	boolean	`true` if 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. `false` if the entity is not made kinematic during the action Default Value: false
kinematicSetVelocity	boolean	`true` if, when `kinematic` is `true`, the entity's velocity will be set during the action, e.g., so that other scripts may use the value. `false` if the entity's velocity will not be set during the action. Default Value: false
ignoreIK	boolean	`true` if the entity follows the HMD controller, `false` if it follows the avatar's hand. Default Value: false

ActionArguments-Offset
Type: object

The "offset" ActionType moves an entity so that it is a defined 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
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 slides and rotates about its specified `axis`. Default Value: null
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
otherPoint	Vec3	The local position of a point in the other entity that slides along the axis. Default Value: 0,0,0
otherAxis	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: -2*Math.PI
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: Math.PI
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. In radians. 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
otherID	Uuid	If an entity ID, the `targetPosition` and `targetRotation` are relative to the entity's position and rotation. Default Value: null
otherJointIndex	Uuid	If a joint index in the `otherID` entity, the `targetPosition` and `targetRotation` are relative to the entity joint's position and rotation. Default Value: null
targetPosition	Vec3	The target position. Default Value: 0,0,0
targetRotation	Quat	The target rotation. Default Value: 0,0,0,1
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:

Value	Type	Description	Arguments
`"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 defined 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"`. Deprecated.

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

An animation is configured by the following properties:

Properties

Name	Type	Summary
url	string	The URL of the glTF or FBX file that has the animation. glTF files may be in JSON or binary format (".gltf" or ".glb" URLs respectively). Warning: glTF animations currently do not always animate correctly. Default Value: ""
allowTranslation	boolean	`true` to enable translations contained in the animation to be played, `false` to disable translations. Default Value: true
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	`true` if the animation should play, `false` if it shouldn't. Default Value: false
loop	boolean	`true` if the animation is continuously repeated in a loop, `false` if it isn't. Default Value: true
hold	boolean	`true` if the rotations and translations of the last frame played are maintained when the animation stops playing, `false` if they aren't. Default Value: false

AvatarPriorityMode
Type: string

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

Value	Description
`"inherit"`	The update priority from any enclosing zone continues into this zone.
`"crowd"`	The update priority in this zone is the normal priority.
`"hero"`	Avatars in this zone have an increased update priority.

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.

ComponentMode
Type: string

How an effect is applied in a Zone entity.

Value	Description
`"inherit"`	The effect from any enclosing zone continues into this zone.
`"disabled"`	The effect — from any enclosing zone and this zone — is disabled in this zone.
`"enabled"`	The effect from this zone is enabled, overriding the effect from any enclosing zone.

EntityHostType
Type: string

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

Value	Description
`"domain"`	Domain entities are stored on the domain, are visible to everyone, and are sent to everyone by the entity server.
`"avatar"`	Avatar entities are stored on an Interface client, are visible to everyone, and are sent to everyone by the avatar mixer. They follow the client to each domain visited, displaying at the same domain coordinates unless parented to the client's avatar.
`"local"`	Local entities are ephemeral — they aren't stored anywhere — and are visible only to the client. They follow the client to each domain visited, displaying at the same domain coordinates unless parented to the client's avatar. Additionally, local entities are always collisionless.

EntityProperties
Type: object

Different entity types have different properties: some common to all entities (listed in the table) and some specific to each EntityType (linked to below).

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's type. You cannot change the type of an entity after it's created. However, its value may switch among `"Box"`, `"Shape"`, and `"Sphere"` depending on changes to the `shape` property set for entities of these types. Read-only.
entityHostType	Entities.EntityHostType	How the entity is hosted and sent to others for display. The value can only be set at entity creation by one of the Entities.addEntity methods. Read-only. Default Value: "domain"
avatarEntity	boolean	`true` if the entity is an avatar entity, `false` if it isn't. The value is per the `entityHostType` property value, set at entity creation by one of the Entities.addEntity methods. Read-only. Default Value: false
clientOnly	boolean	A synonym for `avatarEntity`. Read-only. Default Value: false
localEntity	boolean	`true` if the entity is a local entity, `false` if it isn't. The value is per the `entityHostType` property value, set at entity creation by one of the Entities.addEntity methods. 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	number	When the entity was created, expressed as the number of microseconds since 1970-01-01T00:00:00 UTC. 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	`true` if properties other than `locked` cannot be changed and the entity cannot be deleted, `false` if all properties can be changed and the entity can be deleted. Default Value: false
visible	boolean	`true` if the entity is rendered, `false` if it isn't. Default Value: true
canCastShadow	boolean	`true` if the entity can cast a shadow, `false` if it can't. 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	`true` if the entity is rendered in the secondary camera, `false` if it isn't. Default Value: true
renderLayer	Entities.RenderLayer	The layer that the entity renders in. Default Value: "world"
primitiveMode	Entities.PrimitiveMode	How the entity's geometry is rendered. Default Value: "solid"
ignorePickIntersection	boolean	`true` if Picks and RayPick ignore the entity, `false` if they don't. Default Value: false
position	Vec3	The position of the entity in world coordinates. Default Value: 0,0,0
rotation	Quat	The orientation of the entity in 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, range Vec3.ZERO – Vec3.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 or image 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 the linear velocity of an entity slows down over time, range `0.0` – `1.0`. A higher damping value slows down the entity more quickly. The default value is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to `1/e = 0.368` of its initial value. 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 the angular velocity of an entity slows down over time, range `0.0` – `1.0`. A higher damping value slows down the entity more quickly. The default value is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to `1/e = 0.368` of its initial value. Default Value: 0.39347
gravity	Vec3	The acceleration due to gravity in m/s² that the entity should move with, in world coordinates. Use a value of `{ x: 0, y: -9.8, z: 0 }` to simulate Earth's gravity. Gravity is applied to an entity's motion only if its `dynamic` property is `true`. If changing an entity's `gravity` from Vec3.ZERO, you need to give it a small `velocity` in order to kick off physics simulation. Default Value: 0,0,0
acceleration	Vec3	The current, measured acceleration of the entity, in m/s². Deprecated: This property is deprecated and will be removed.
restitution	number	The "bounciness" of an entity when it collides, range `0.0` – `0.99`. The higher the value, the more bouncy. Default Value: 0.5
friction	number	How much an entity slows down when it's moving against another, range `0.0` – `10.0`. The higher the value, the more quickly it slows down. Examples: `0.1` for ice, `0.9` for sandpaper. Default Value: 0.5
density	number	The density of the entity in kg/m³, range `100` – `10000`. Examples: `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	`true` if the entity shouldn't collide, `false` if it collides with items per its `collisionMask` property. Default Value: false
ignoreForCollisions	boolean	Synonym for `collisionless`.
collisionMask	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 that's played when the entity experiences a collision. Valid file formats are per SoundObject. Default Value: ""
dynamic	boolean	`true` if the entity's movement is affected by collisions, `false` if it isn't. Default Value: false
collisionsWillMove	boolean	A synonym for `dynamic`.
href	string	A "hifi://" metaverse address that a user is teleported 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 may also use this property, so make sure you handle data stored by other apps: edit only your bit and leave the rest of the data intact. You can use `JSON.parse()` to parse the string into a JavaScript object which you can manipulate the properties of, and use `JSON.stringify()` to convert the object into a string to put back in the property. Default Value: ""
privateUserData	string	Like `userData`, but only accessible by server entity scripts, assignment client scripts, and users who have "Can Get and Set Private User Data" permissions in the domain. Default Value: ""
script	string	The URL of the client entity script, if any, that is attached to the entity. Default Value: ""
scriptTimestamp	number	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 the entity is parented to. A value of Uuid.NULL is used if the entity is not parented. Default Value: Uuid.NULL
parentJointIndex	number	The joint of the entity or avatar that the entity is parented to. Use `65535` or `-1` to parent to the entity or avatar's position and orientation rather than a joint. 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 avatar entity 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 `angularVelocity`. Default Value: 0,0,0
localDimensions	Vec3	The dimensions of the entity. If the entity is parented to an avatar and is an avatar entity so that it scales with the avatar, this value remains the original dimensions value while the avatar scale changes.
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, e.g., Entities.addAction. The size of this property increases with the number of actions. Because this property value has to fit within a Vircadia datagram packet, there is a limit to the number of actions that an entity can have; 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	`true` if the domain or avatar entity can be cloned via Entities.cloneEntity, `false` if it can't be. 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	`true` if clones created from this entity will have their `dynamic` property set to `true`, `false` if they won't. Default Value: false
cloneAvatarEntity	boolean	`true` if clones created from this entity will be created as avatar entities, `false` if they won't be. Default Value: false
cloneOriginID	Uuid	The ID of the entity that this entity was cloned from.
renderWithZones	Array.<Uuid>	A list of entity IDs representing with which zones this entity should render. If it is empty, this entity will render normally. Otherwise, this entity will only render if your avatar is within one of the zones in this list. Default Value: []
billboardMode	BillboardMode	Whether the entity is billboarded to face the camera. Use the rotation property to control which axis is facing you. Default Value: "none"
grab	Entities.Grab	The entity's 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 multiple, 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"`. See: EntityProperties-Shape

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

See:

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

dimensions

Vec3

The dimensions of the entity.

Default Value: 0.1,0.001,0.1

gizmoType

Entities.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
dimensions	Vec3	0.1,0.1,0.01 - The dimensions of the entity.
color	Color	The color of the grid. Default Value: 255,255,255
alpha	number	The opacity of the grid. Default Value: 1
pulse	Entities.Pulse	Color and alpha pulse. Deprecated: This property is deprecated and will be removed.
followCamera	boolean	`true` if the grid is always visible even as the camera moves to another position, `false` if it doesn't follow the camrmea. 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

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
dimensions	Vec3	The dimensions of the entity. Default Value: 0.1,0.1,0.01
imageURL	string	The URL of the image to use. Default Value: ""
emissive	boolean	`true` if the image should be emissive (unlit), `false` if it shouldn't. Default Value: false
keepAspectRatio	boolean	`true` if the image should maintain its aspect ratio, `false` if it shouldn't. Default Value: true
subImage	Rect	The portion of the image to display. If width or height are `0`, it defaults to the full image in that dimension. Default Value: 0,0,0,0
color	Color	The color of the image. Default Value: 255,255,255
alpha	number	The opacity of the image. Default Value: 1
pulse	Entities.Pulse	Color and alpha pulse. Deprecated: This property is deprecated and will be removed.
faceCamera	boolean	`true` if `billboardMode` is `"yaw"`, `false` if it isn't. Setting this property to `false` sets the `billboardMode` to `"none"`. Deprecated: This property is deprecated and will be removed.
isFacingAvatar	boolean	`true` if `billboardMode` is `"full"`, `false` if it isn't. Setting this property to `false` sets the `billboardMode` to `"none"`. Deprecated: This property is deprecated and will be removed.

Example

Create an 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. Surfaces 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	`true` if the light is directional, emitting along the entity's local negative z-axis; `false` if 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. It has properties in addition to the common EntityProperties.

Deprecated: Use PolyLine entities instead.

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 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" and set the entity's parentID property to MyAvatar.SELF_ID. Material entities render as non-scalable spheres if they don't have their parent set.

Properties

Name	Type	Summary
dimensions	Vec3	Used when `materialMappingMode == "projected"`. Default Value: 0.1,0.1,0.1
materialURL	string	URL to a MaterialResource. Alternatively, set the property value to `"materialData"` to use the `materialData` property for the MaterialResource values. If you append `"#name"` to the URL, the material with that name will be applied to the entity. You can also use the ID of another Material entity as the URL, in which case this material will act as a copy of that material, with its own unique material transform, priority, etc. Default Value: ""
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: ""
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. If `"all"`, then all mesh parts are replaced. Otherwise the property value is parsed as an unsigned integer, specifying the mesh part index to modify. If the string represents an array (starts with `"["` and ends with `"]"`), the string is split at each `","` and each element parsed as either a number or a string if it starts with `"mat::"`. For example, `"[0,1,mat::string,mat::string2]"` will replace mesh parts 0 and 1, and any mesh parts with material `"string"` or `"string2"`. Do not put spaces around the commas. Invalid values are parsed to `0`. Default Value: "0"
materialMappingMode	string	How the material is mapped to the entity. Either `"uv"` or `"projected"`. In `"uv"` mode, the material is evaluated within the UV space of the mesh it is applied to. In `"projected"` mode, the 3D transform (position, rotation, and dimensions) of the Material entity is used to evaluate the texture coordinates for the material. 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
materialRepeat	boolean	`true` if the material repeats, `false` if it doesn't. 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 a glTF, FBX, or OBJ model. When adding an entity, if no dimensions value is specified then the model is automatically sized to its naturalDimensions. 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
modelURL	string	The URL of the glTF, FBX, or OBJ model. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs respectively). Baked models' URLs have ".baked" before the file type. Model files may also be compressed in GZ format, in which case the URL ends in ".gz". Default Value: ""
modelScale	Vec3	The scale factor applied to the model's dimensions. Deprecated: This property is deprecated and will be removed.
blendshapeCoefficients	string	A JSON string of a map of blendshape names to values. Only stores set values. When editing this property, only coefficients that you are editing will change; it will not explicitly reset other coefficients.
useOriginalPivot	boolean	If `false`, the model will be centered based on its content, ignoring any offset in the model itself. If `true`, the model will respect its original offset. Currently, only pivots relative to `{x: 0, y: 0, z: 0}` are supported. Default Value: false
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: "{}"
color	Color	Currently not used. Default Value: 255,255,255
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. Translations 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	`true` if when the entity is parented to an avatar, the avatar's joint rotations are applied to the entity's joints; `false` if a parent avatar's joint rotations are not applied to the entity's joints. Default Value: false
groupCulled	boolean	`true` if the mesh parts of the model are LOD culled as a group, `false` if separate mesh parts are LOD culled individually. Default Value: false

Example

Rez a cowboy hat.

var entity = Entities.addEntity({
    type: "Model",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -2 })),
    rotation: MyAvatar.orientation,
    modelURL: "https://apidocs.vircadia.dev/models/cowboy-hat.fbx",
    dimensions: { x: 0.8569, y: 0.3960, z: 1.0744 },
    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	`true` if particles are being emitted, `false` if they aren't. 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. For example, if `emitSpeed == 5` and `speedSpread == 1`, particles will be emitted with speeds in the range `4` – `6`m/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. For example, if `emitAccelerations == {x: 0, y: -9.8, z: 0}` and `accelerationSpread == {x: 0, y: 1, z: 0}`, each particle will have an acceleration in the range `{x: 0, y: -10.8, z: 0}` – `{x: 0, y: -8.8, z: 0}`. 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 == false`. Read-only.
emitterShouldTrail	boolean	`true` if particles are "left behind" as the emitter moves, `false` if they stay within 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
shapeType	ShapeType	The shape from which particles are emitted. Default Value: "ellipsoid"
compoundShapeURL	string	The model file to use for the compound shape if `shapeType == "compound"`. Default Value: ""
emitDimensions	Vec3	The dimensions of the shape from which particles are emitted. Default Value: 0,0,0
emitRadiusStart	number	The starting radius within the shape at which particles start being emitted; range `0.0` – `1.0` for the center to the surface, respectively. Particles are emitted from the portion of the shape that lies between `emitRadiusStart` and the shape's surface. 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 `0` – `Math.PI`. Particles are emitted from the portion of the shape that lies between `polarStart` and `polarFinish`. Only used if `shapeType` is `"ellipsoid"` or `"sphere"`. 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 `0` – `Math.PI`. Particles are emitted from the portion of the shape that lies between `polarStart` and `polarFinish`. Only used if `shapeType` is `"ellipsoid"` or `"sphere"`. 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.PI` – `Math.PI`. Particles are emitted from the portion of the shape that lies between `azimuthStart` and `azimuthFinish`. Only used if `shapeType` is `"ellipsoid"`, `"sphere"`, or `"circle"`. 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.PI` – `Math.PI`. Particles are emitted from the portion of the shape that lies between `azimuthStart` and `azimuthFinish`. Only used if `shapeType` is `"ellipsoid"`, `"sphere"`, or `"circle"`. 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 `null`, the `particleRadius` value is used. Default Value: null
radiusFinish	number	The radius of each particle at the end of its life. If `null`, the `particleRadius` value is used. Default Value: null
radiusSpread	number	The spread in radius that each particle is given. For example, if `particleRadius == 0.5` and `radiusSpread == 0.25`, each particle will have a radius in the range `0.25` – `0.75`. 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: null,null,null
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: null,null,null
colorSpread	Color	The spread in color that each particle is given. For example, if `color == {red: 100, green: 100, blue: 100}` and `colorSpread == {red: 10, green: 25, blue: 50}`, each particle will have a color in the range `{red: 90, green: 75, blue: 50}` – `{red: 110, green: 125, blue: 150}`. Default Value: 0,0,0
alpha	number	The opacity of each particle at the middle of its life. Default Value: 1
alphaStart	number	The opacity of each particle at the start of its life. If `null`, the `alpha` value is used. Default Value: null
alphaFinish	number	The opacity of each particle at the end of its life. If `null`, the `alpha` value is used. Default Value: null
alphaSpread	number	The spread in alpha that each particle is given. For example, if `alpha == 0.5` and `alphaSpread == 0.25`, each particle will have an alpha in the range `0.25` – `0.75`. Default Value: 0
pulse	Entities.Pulse	Color and alpha pulse. Deprecated: This property is deprecated and will be removed.
particleSpin	number	The rotation of each particle at the middle of its life, range `-2 * Math.PI` – `2 * Math.PI` radians. Default Value: 0
spinStart	number	The rotation of each particle at the start of its life, range `-2 * Math.PI` – `2 * Math.PI` radians. If `null`, the `particleSpin` value is used. Default Value: null
spinFinish	number	The rotation of each particle at the end of its life, range `-2 * Math.PI` – `2 * Math.PI` radians. If `null`, the `particleSpin` value is used. Default Value: null
spinSpread	number	The spread in spin that each particle is given, range `0` – `2 * Math.PI` radians. For example, if `particleSpin == Math.PI` and `spinSpread == Math.PI / 2`, each particle will have a rotation in the range `Math.PI / 2` – `3 * Math.PI / 2`. Default Value: 0
rotateWithEntity	boolean	`true` if the particles' rotations are relative to the entity's instantaneous rotation, `false` if they're relative to world coordinates. If `true` with `particleSpin == 0`, the particles keep oriented per the entity's orientation. Default Value: false

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.vircadia.com/eu-c-1/vircadia-assets/interface/default/default_particle.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. Read-only. 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. 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, with values in the range `0.0,0.0,0.0` – `1.0,1.0,1.0`. These colors are multiplied with the color of the texture. If there are more line points than stroke colors, the `color` property value is used for the remaining points. Warning: The ordinate values are in the range `0.0` – `1.0`. Default Value: []
color	Color	Used as the color for each point if `strokeColors` doesn't have a value for the point. 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	`true` if the texture is stretched to fill the whole line, `false` if the texture repeats along the line. Default Value: true
glow	boolean	`true` if the opacity of the strokes drops off away from the line center, `false` if it doesn't. Default Value: false
faceCamera	boolean	`true` if each line segment rotates to face the camera, `false` if they don't. 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: "https://cdn-1.vircadia.com/us-e-1/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 various 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 Vircadia datagram packet, there is a limit to the size and complexity of a PolyVox entity; 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	The 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	The 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	The 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	The 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	The 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	The 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	The 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	The 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	The 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 opacity of the entity, range `0.0` – `1.0`. Default Value: 1
pulse	Entities.Pulse	Color and alpha pulse. Deprecated: This property is deprecated and will be removed.

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

See:

EntityProperties-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 opacity of the text. Default Value: 1.0
backgroundColor	Color	The color of the background rectangle. Default Value: 0,0,0
backgroundAlpha	number	The opacity of the background. Default Value: 1.0
pulse	Entities.Pulse	Color and alpha pulse. Deprecated: This property is deprecated and will be removed.
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
unlit	boolean	`true` if the entity is unaffected by lighting, `false` if it is lit by the key light and local lights. Default Value: false
font	string	The font to render the text with. It can be one of the following: `"Courier"`, `"Inconsolata"`, `"Roboto"`, `"Timeless"`, or a path to a .sdff file. Default Value: ""
textEffect	Entities.TextEffect	The effect that is applied to the text. Default Value: "none"
textEffectColor	Color	The color of the effect. Default Value: 255,255,255
textEffectThickness	number	The magnitude of the text effect, range `0.0` – `0.5`. Default Value: 0.2
alignment	Entities.TextAlignment	How the text is aligned against its background. Default Value: "left"
faceCamera	boolean	`true` if `billboardMode` is `"yaw"`, `false` if it isn't. Setting this property to `false` sets the `billboardMode` to `"none"`. Deprecated: This property is deprecated and will be removed.
isFacingAvatar	boolean	`true` if `billboardMode` is `"full"`, `false` if it isn't. Setting this property to `false` sets the `billboardMode` to `"none"`. Deprecated: This property is deprecated and will be removed.

Example

Create a text entity.

var text = Entities.addEntity({
    type: "Text",
    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. Internally, a Web entity is rendered as a non-repeating, upside down texture, so additional transformations may be necessary if you reference a Web entity texture by UUID. 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
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: ""
color	Color	The color of the web surface. This color tints the web page displayed: the pixel colors on the web page are multiplied by the property color. For example, a value of `{ red: 255, green: 0, blue: 0 }` lets only the red channel of pixels' colors through. Default Value: 255,255,255
alpha	number	The opacity of the web surface. Default Value: 1
pulse	Entities.Pulse	Color and alpha pulse. Deprecated: This property is deprecated and will be removed.
faceCamera	boolean	`true` if `billboardMode` is `"yaw"`, `false` if it isn't. Setting this property to `false` sets the `billboardMode` to `"none"`. Deprecated: This property is deprecated and will be removed.
isFacingAvatar	boolean	`true` if `billboardMode` is `"full"`, `false` if it isn't. Setting this property to `false` sets the `billboardMode` to `"none"`. Deprecated: This property is deprecated and will be removed.
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"
showKeyboardFocusHighlight	boolean	`true` if the entity is highlighted when it has keyboard focus, `false` if it isn't. Default Value: true
useBackground	boolean	`true` if the web entity should have a background, `false` if the web entity's background should be transparent. The webpage must have CSS properties for transparency set on the `background-color` for this property to have an effect. Default Value: true
userAgent	string	The user agent for the web entity to use when visiting web pages. Default value: `Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.113 Mobile Safari/537.36`

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://vircadia.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 dimensions 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	Entities.ComponentMode	Configures the key light in the zone. Default Value: "inherit"
keyLight	Entities.KeyLight	The key light properties of the zone.
ambientLightMode	Entities.ComponentMode	Configures the ambient light in the zone. Default Value: "inherit"
ambientLight	Entities.AmbientLight	The ambient light properties of the zone.
skyboxMode	Entities.ComponentMode	Configures the skybox displayed in the zone. Default Value: "inherit"
skybox	Entities.Skybox	The skybox properties of the zone.
hazeMode	Entities.ComponentMode	Configures the haze in the zone. Default Value: "inherit"
haze	Entities.Haze	The haze properties of the zone.
bloomMode	Entities.ComponentMode	Configures the bloom in the zone. Default Value: "inherit"
bloom	Entities.Bloom	The bloom properties of the zone.
flyingAllowed	boolean	`true` if visitors can fly in the zone; `false` if they cannot. Only works for domain entities. Default Value: true
ghostingAllowed	boolean	`true` if visitors with avatar collisions turned off will not collide with content in the zone; `false` if visitors will always collide with content in the zone. Only works for 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: function filter(properties) { // Check and edit properties object values, // e.g., properties.modelURL, as required. return properties; } Default Value: ""
avatarPriority	Entities.AvatarPriorityMode	Configures the priority of updates from avatars in the zone to other clients. Default Value: "inherit"
screenshare	Entities.ScreenshareMode	Configures a zone for screen-sharing. 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.
});

EntityPropertyInfo
Type: object

Information about an entity property.

Properties

Name	Type	Summary
propertyEnum	number	The internal number of the property.
minimum	string	The minimum numerical value the property may have, if available, otherwise `""`.
maximum	string	The maximum numerical value the property may have, if available, otherwise `""`.

EntityType
Type: string

An entity may be one of the following types:

Value	Description	Properties
`"Shape"`	A basic entity such as a cube. See also, the `"Box"` and `"Sphere"` entity types.	EntityProperties-Shape
`"Box"`	A rectangular prism. This is a synonym of `"Shape"` for the case where the entity's `shape` property value is `"Cube"`. If an entity is created with its `type` set to `"Box"` it will always be created with a `shape` property value of `"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
`"Model"`	A mesh model from a glTF, 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"`	A gizmo intended for UI.	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

GizmoType
Type: string

A Gizmo entity may be one of the following types:

Value	Description
`"ring"`	A ring gizmo.

Grab
Type: object

Grabbing behavior is defined by the following properties:

Properties

Name	Type	Summary
grabbable	boolean	`true` if the entity can be grabbed, `false` if it can't be. Default Value: true
grabKinematic	boolean	`true` if the entity will be updated in a kinematic manner when grabbed; `false` if 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	`true` if the entity will follow the motions of the hand controller even if the avatar's hand can't get to the implied position, `false` if it will follow the motions of the avatar's hand. This should be set `true` for tools, pens, etc. and `false` for things meant to decorate the hand. Default Value: true
triggerable	boolean	`true` if the entity will receive calls to trigger Controller entity methods, `false` if it won't. Default Value: false
grabDelegateToParent	boolean	`true` if when the entity is grabbed, the grab will be transferred to its parent entity if there is one; `false` if the grab won't be transferred, so a child entity can be grabbed and moved relative to its parent. Default Value: true
equippable	boolean	`true` if the entity can be equipped, `false` if it cannot. 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	`true` if the haze is colored with glare from the key light, `false` if it isn't. If `true`, then `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	`true` if haze decreases with altitude as defined by the entity's local coordinate system, `false` if it doesn't. If `true`, then `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	`true` if the haze attenuates the key light, `false` if it doesn't. If `true`, then `hazeKeyLightRange` and `hazeKeyLightAltitude` are used. Default Value: false
hazeKeyLightRange	number	The distance at which the haze attenuates the key light by 95%. Default Value: 1000
hazeKeyLightAltitude	number	The altitude at which the haze starts attenuating the key light (i.e., the altitude at which the distance starts being calculated). 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	`true` if shadows are cast, `false` if they aren't. Shadows are cast by avatars, plus Model and Shape entities that have their `canCastShadow` property set to `true`. Default Value: false
shadowBias	number	The bias of the shadows cast by the light, range `0.0` – `1.0`. This fine-tunes shadows cast by the light, to prevent shadow acne and peter panning. Default Value: 0.5
shadowMaxDistance	number	The maximum distance from the camera position at which shadows will be computed, range `1.0` – `250.0`. Higher values cover more of the scene but with less precision. Default Value: 40.0

Material
Type: object

A material used in a MaterialResource.

Properties

Name	Type	Summary
name	string	A name for the material. Supported by all material models. Default Value: ""
model	string	Different material models support different properties and rendering modes. Supported models are: `"hifi_pbr"`, `"hifi_shader_simple"`. Default Value: "hifi_pbr"
emissive	ColorFloat \| RGBS \| string	The emissive color, i.e., the color that the material emits. A ColorFloat value is treated as sRGB and must have component values in the range `0.0` – `1.0`. A RGBS value can be either RGB or sRGB. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
opacity	number \| string	The opacity, range `0.0` – `1.0`. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` and `"hifi_shader_simple"` models only. Default Value: 1.0
unlit	boolean \| string	`true` if the material is unaffected by lighting, `false` if it is lit by the key light and local lights. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only. Default Value: false
albedo	ColorFloat \| RGBS \| string	The albedo color. A ColorFloat value is treated as sRGB and must have component values in the range `0.0` – `1.0`. A RGBS value can be either RGB or sRGB. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` and `"hifi_shader_simple"` models only.
roughness	number \| string	The roughness, range `0.0` – `1.0`. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
metallic	number \| string	The metallicness, range `0.0` – `1.0`. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
scattering	number \| string	The scattering, range `0.0` – `1.0`. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
emissiveMap	string	The URL of the emissive texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
albedoMap	string	The URL of the albedo texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
opacityMap	string	The URL of the opacity texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Set the value the same as the `albedoMap` value for transparency. `"hifi_pbr"` model only.
opacityMapMode	string	The mode defining the interpretation of the opacity map. Values can be: `"OPACITY_MAP_OPAQUE"` for ignoring the opacity map information. `"OPACITY_MAP_MASK"` for using the `opacityMap` as a mask, where only the texel greater than `opacityCutoff` are visible and rendered opaque. `"OPACITY_MAP_BLEND"` for using the `opacityMap` for alpha blending the material surface with the background. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
opacityCutoff	number \| string	The opacity cutoff threshold used to determine the opaque texels of the `opacityMap` when `opacityMapMode` is `"OPACITY_MAP_MASK"`. Range `0.0` – `1.0`. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
cullFaceMode	string	The mode defining which side of the geometry should be rendered. Values can be: `"CULL_NONE"` to render both sides of the geometry. `"CULL_FRONT"` to cull the front faces of the geometry. `"CULL_BACK"` (the default) to cull the back faces of the geometry. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only. Default Value: "CULL_BACK"
cullFaceMode	string	The mode defining which side of the geometry should be rendered. Values can be: `"CULL_NONE"` for rendering both sides of the geometry. `"CULL_FRONT"` for culling the front faces of the geometry. `"CULL_BACK"` (the default) for culling the back faces of the geometry. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
roughnessMap	string	The URL of the roughness texture image. You can use this or `glossMap`, but not both. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
glossMap	string	The URL of the gloss texture image. You can use this or `roughnessMap`, but not both. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
metallicMap	string	The URL of the metallic texture image, or an entity ID. An entity ID may be that of an Image or Web entity. You can use this or `specularMap`, but not both. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
specularMap	string	The URL of the specular texture image, or an entity ID. An entity ID may be that of an Image or Web entity. You can use this or `metallicMap`, but not both. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
normalMap	string	The URL of the normal texture image, or an entity ID. An entity ID may be that of an Image or Web entity. You can use this or `bumpMap`, but not both. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
bumpMap	string	The URL of the bump texture image, or an entity ID. An entity ID may be that of an Image or Web entity. You can use this or `normalMap`, but not both. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
occlusionMap	string	The URL of the occlusion texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
scatteringMap	string	The URL of the scattering texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Only used if `normalMap` or `bumpMap` is specified. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
lightMap	string	The URL of the light map texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
texCoordTransform0	Mat4 \| string	The transform to use for all of the maps apart from `occlusionMap` and `lightMap`. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
texCoordTransform1	Mat4 \| string	The transform to use for `occlusionMap` and `lightMap`. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only.
lightmapParams	string	Parameters for controlling how `lightMap` is used. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only. Currently not used.
materialParams	string	Parameters for controlling the material projection and repetition. Set to `"fallthrough"` to fall through to the material below. `"hifi_pbr"` model only. Currently not used.
defaultFallthrough	boolean	`true` if all properties fall through to the material below unless they are set, `false` if properties respect their individual fall-through settings. `"hifi_pbr"` and `"hifi_shader_simple"` models only. Default Value: false
procedural	ProceduralData	The definition of a procedural shader material. `"hifi_shader_simple"` model only.

MaterialResource
Type: object

A material or set of materials used by a Material entity.

Properties

Name

Type

Summary

materialVersion

number

The version of the material. Currently not used.

Default Value: 1

materials

Entities.Material | Array.<Entities.Material> | string

The details of the material or materials, or the ID of another Material entity.

NestableType
Type: string

An in-world item may be one of the following types:

Value	Description
`"entity"`	The item is an entity.
`"avatar"`	The item is an avatar.
`"unknown"`	The item cannot be found.

PhysicsMotionType
Type: string

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

Value	Description
`"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

The surface of a PolyVox entity may be one of the following styles:

Value	Type	Description
`0`	Marching cubes.	Chamfered edges. Open volume. Joins neighboring PolyVox entities reasonably well.
`1`	Cubic.	Square edges. Open volume. Joins neighboring PolyVox entities cleanly.
`2`	Edged cubic.	Square edges. Enclosed volume. Joins neighboring PolyVox entities cleanly.
`3`	Edged marching cubes.	Chamfered edges. Enclosed volume. Doesn't join neighboring PolyVox entities.

PrimitiveMode
Type: string

How the geometry of an entity is rendered.

Value	Description
`"solid"`	The entity is drawn as a solid shape.
`"lines"`	The entity is drawn as wireframe.

Pulse
Type: object

A color and alpha pulse that an entity may have.

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	Entities.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	Entities.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"

PulseMode
Type: string

Pulse modes for color and alpha pulsing.

Value	Description
`"none"`	No pulsing.
`"in"`	Pulse in phase with the pulse period.
`"out"`	Pulse out of phase with the pulse period.

RayToEntityIntersectionResult
Type: object

The result of a findRayIntersection search using a PickRay.

Properties

Name	Type	Summary
intersects	boolean	`true` if the PickRay intersected an entity, `false` if it didn't.
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.
texturesSize	number	The total size of the textures in the entity, in bytes.
hasTransparent	boolean	`true` if any of the textures has transparency, `false` if none of them do.
drawCalls	number	The number of draw calls required to render the entity.

RenderLayer
Type: string

A layer in which an entity may be rendered.

Value	Description
`"world"`	The entity is drawn in the world with everything else.
`"front"`	The entity is drawn on top of the world layer but behind the HUD surface.
`"hud"`	The entity is drawn on top of other layers and the HUD surface.

RingGizmo
Type: object

A ring Gizmo entity is defined by the following properties:

Properties

Name	Type	Summary
startAngle	number	The angle at which the ring starts, in degrees. Default Value: 0
endAngle	number	The angle at which the ring ends, in degrees. Default Value: 360
innerRadius	number	The inner radius of the ring as a fraction of the total radius, range `0.0` — `1.0`. Default Value: 0
innerStartColor	Color	The color at the inner start point of the ring. Default Value: 255,255,255
innerEndColor	Color	The color at the inner end point of the ring. Default Value: 255,255,255
outerStartColor	Color	The color at the outer start point of the ring. Default Value: 255,255,255
outerEndColor	Color	The color at the outer end point of the ring. Default Value: 255,255,255
innerStartAlpha	number	The opacity at the inner start point of the ring. Default Value: 1
innerEndAlpha	number	The opacity at the inner end point of the ring. Default Value: 1
outerStartAlpha	number	The opacity at the outer start point of the ring. Default Value: 1
outerEndAlpha	number	The opacity at the outer end point of the ring. Default Value: 1
hasTickMarks	boolean	`true` to render tick marks, otherwise `false`. Default Value: false
majorTickMarksAngle	number	The angle between major tick marks, in degrees. Default Value: 0
minorTickMarksAngle	number	The angle between minor tick marks, in degrees. Default Value: 0
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. Default Value: 0
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. Default Value: 0
majorTickMarksColor	Color	The color of the major tick marks. Default Value: 255,255,255
minorTickMarksColor	Color	The color of the minor tick marks. Default Value: 255,255,255

Shape
Type: string

A "Shape", "Box", or "Sphere" EntityType may display as one of the following geometrical shapes:

Value	Dimensions	Notes
`"Circle"`	2D	A circle oriented in 3D.
`"Cone"`	3D
`"Cube"`	3D
`"Cylinder"`	3D
`"Dodecahedron"`	3D
`"Hexagon"`	3D	A hexagonal prism.
`"Icosahedron"`	3D
`"Octagon"`	3D	An octagonal prism.
`"Octahedron"`	3D
`"Quad"`	2D	A square oriented in 3D.
`"Sphere"`	3D
`"Tetrahedron"`	3D
`"Torus"`	3D	Not implemented.
`"Triangle"`	3D	A 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: ""

TextAlignment
Type: string

A Text entity may use one of the following alignments:

Value	Description
`"left"`	Text is aligned to the left side.
`"center"`	Text is centered.
`"right"`	Text is aligned to the right side.

TextEffect
Type: string

A Text entity may use one of the following effects:

Value	Description
`"none"`	No effect.
`"outline"`	An outline effect.
`"outline fill"`	An outline effect, with fill.
`"shadow"`	A shadow effect.

getMeshesCallback( meshes, success )
Type: function

Called when a Entities.getMeshes call is complete.

Deprecated: This function is deprecated and will be removed. It no longer works for Model entities. Use the Graphics API instead.

Parameters

Name	Type	Description
`meshes`	Array.<MeshProxy>	If `success` is `true`, a MeshProxy per mesh in the `Model` or `PolyVox` entity; otherwise `undefined`.
`success`	boolean	`true` if the Entities.getMeshes call was successful, `false` otherwise. The call may be unsuccessful if the requested entity could not be found.

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

Called when a Entities.getServerScriptStatus call is complete.

Parameters

Name	Type	Description
`success`	boolean	`true` if the server entity script status could be obtained, otherwise `false`.
`isRunning`	boolean	`true` if there is a server entity script running, otherwise `false`.
`status`	string	`"running"` if there is a server entity script running, otherwise an error string.
`errorInfo`	string	`""` if there is a server entity script running, otherwise it may contain extra information on the error.

queryPropertyMetadataCallback( error, result )
Type: function

Called when a Entities.queryPropertyMetadata call is complete.

Parameters

Name	Type	Description
`error`	string	`undefined` if there was no error, otherwise an error message.
`result`	object	The metadata for the requested entity property if there was no error, otherwise `undefined`.

Method Details

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

Checks 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 radius of the capsule.

(static) addAction( actionType, entityID, arguments ) → {Uuid}
Returns: The ID of the action if successfully added, otherwise null.

Adds 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	Configures 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.

Adds a new domain, avatar, or local entity.

Parameters

Name	Type	Attributes	Default Value	Description
`properties`	Entities.EntityProperties			The properties of the entity to create.
`entityHostType`	Entities.EntityHostType	<optional>	"domain"	The type of entity to create.

Example

Create a box domain entity in front of your avatar.

var entityID = Entities.addEntity({
    type: "Box",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.5, y: 0.5, z: 0.5 },
    lifetime: 300  // Delete after 5 minutes.
});
print("Entity created: " + entityID);

(static) addEntity( properties, avatarEntityopt ) → {Uuid}
Returns: The ID of the entity if successfully created, otherwise Uuid.NULL.

Adds a new avatar entity (entityHostType property is "avatar") or domain entity (entityHostType property is "domain").

Parameters

Name	Type	Attributes	Default Value	Description
`properties`	Entities.EntityProperties			The properties of the entity to create.
`avatarEntity`	boolean	<optional>	false	`true` to create an avatar entity, `false` to create 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.

Appends a point to a Line entity.

Deprecated: This function is deprecated and will be removed. Use PolyLine entities instead.

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".
Script.setTimeout(function () {
    Entities.appendPoint(entity, { x: 1, y: 1, z: 0 });
}, 50); // Wait for the entity to be created.

(static) callEntityClientMethod( clientSessionID, entityID, method, parametersopt )

Calls 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. Additionally, the client 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
`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. The method is called with the entity ID as the first parameter and the `parameters` value as the second parameter.
`parameters`	Array.<string>	<optional>	[]	The additional parameters to call the specified method with.

Example

Call a method in a client entity script from a server entity script.

// Client entity script.
var clientEntityScript = (function () {
    this.entityMethod = function (id, params) {
        print("Method at client entity : " + id + " ; " + params[0] + ", " + params[1]);
    };
    this.remotelyCallable = [
        "entityMethod"
    ];
});

// Server entity script.
var serverEntityScript = (function () {
    var clientSessionID,
        clientEntityID;

    function callClientMethod() {
        // Server entity script call to client entity script.
        Entities.callEntityClientMethod(clientSessionID, clientEntityID, "entityMethod", ["hello", 12]);
    }

    // Obtain client entity details then call client entity method.
    this.entityMethod = function (id, params) {
        clientSessionID = params[0];
        clientEntityID = params[1];
        callClientMethod();
    };
    this.remotelyCallable = [
        "entityMethod"
    ];
});

// Entity that hosts the client entity script.
var clientEntityID = Entities.addEntity({
    type: "Box",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: -1, y: 0, z: -5 })),
    dimensions: { x: 0.5, y: 0.5, z: 0.5 },
    script: "(" + clientEntityScript + ")",  // Could host the script on a Web server instead.
    lifetime: 300  // Delete after 5 minutes.
});

// Entity that hosts the server entity script.
var serverEntityID = Entities.addEntity({
    type: "Box",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 1, y: 0, z: -5 })),
    dimensions: { x: 0.5, y: 0.5, z: 0.5 },
    serverScripts: "(" + serverEntityScript + ")",  // Could host the script on a Web server instead.
    lifetime: 300  // Delete after 5 minutes.
});

// Interface script call to the server entity script.
Script.setTimeout(function () {
    Entities.callEntityServerMethod(serverEntityID, "entityMethod", [MyAvatar.sessionUUID, clientEntityID]);
}, 1000); // Wait for the entities to be created.

(static) callEntityMethod( entityID, method, parametersopt )

Calls a method in a client entity script from an Interface, avatar, or client entity script, or calls 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 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. The method is called with the entity ID as the first parameter and the `parameters` value as the second parameter.
`parameters`	Array.<string>	<optional>	[]	The additional parameters to call the specified method with.

Example

Call a method in a client entity script from an Interface script.

// Client entity script.
var entityScript = (function () {
    this.entityMethod = function (id, params) {
        print("Method at entity : " + id + " ; " + params[0] + ", " + params[1]);
    };
});

// Entity that hosts the client entity script.
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 },
    script: "(" + entityScript + ")",  // Could host the script on a Web server instead.
    lifetime: 300  // Delete after 5 minutes.
});

// Interface script call to the client entity script.
Script.setTimeout(function () {
    Entities.callEntityMethod(entityID, "entityMethod", ["hello", 12]);
}, 1000); // Wait for the entity to be created.

(static) callEntityServerMethod( entityID, method, parametersopt )

Calls a method in a server entity script from an Interface, avatar, or client entity script. The server entity script method must be exposed as a property in the target server entity script. Additionally, 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. The method is called with the entity ID as the first parameter and the `parameters` value as the second parameter.
`parameters`	Array.<string>	<optional>	[]	The additional parameters to call the specified method with.

Example

Call a method in a server entity script from an Interface script.

// Server entity script.
var entityScript = (function () {
    this.entityMethod = function (id, params) {
        print("Method at entity : " + id + " ; " + params[0] + ", " + params[1]); // In server log.
    };
    this.remotelyCallable = [
        "entityMethod"
    ];
});

// Entity that hosts the server entity script.
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 },
    serverScripts: "(" + entityScript + ")",  // Could host the script on a Web server instead.
    lifetime: 300  // Delete after 5 minutes.
});

// Interface script call to the server entity script.
Script.setTimeout(function () {
    Entities.callEntityServerMethod(entityID, "entityMethod", ["hello", 12]);
}, 1000); // Wait for the entity to be created.

(static) canAdjustLocks( ) → {boolean}
Returns: true if the domain server will allow the script to change the locked property of entities, otherwise false.

Checks whether or not the script can change the locked property of entities. Locked entities have their locked property set to true and cannot be edited or deleted.

Example

Lock an entity 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) canGetAndSetPrivateUserData( ) → {boolean} Returns: `true` if the domain server will allow the script to get and set the `privateUserData` property of entities, otherwise `false`.
Checks whether or not the script can get and set the `privateUserData` property of entities.

(static) canReplaceContent( ) → {boolean} Returns: `true` if the domain server will allow the script to replace the domain's content set, otherwise `false`.
Checks whether or not the script 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`.
Checks whether or not the script can rez (create) new entities in the domain.

(static) canRezAvatarEntities( ) → {boolean} Returns: `true` if the domain server will allow the script to rez avatar entities, otherwise `false`.
Checks whether or not the script can rez avatar entities.

(static) canRezCertified( ) → {boolean} Returns: `true` if the domain server will allow the script to rez (create) new certified entities, otherwise `false`.
Checks whether or not the script 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`.
Checks whether or not the script 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`.
Checks whether or not the script 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`.
Checks whether or not the script 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.

Creates a clone of an entity. The clone has the same properties as the original except that: it has a modified name property, clone-related properties are set per the original entity's clone-related properties (e.g., cloneLifetime), and its clone-related properties are set to their defaults.

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

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

Parameters

Name	Type	Description
`entityID`	Uuid	The ID of the entity to clone.

(static) deleteAction( entityID, actionID ) → {boolean}
Returns: true if the delete was successful, otherwise false.

Deletes 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 )

Deletes 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) 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 or Uuid.NULL.

Edits an entity, changing one or more of its property values.

Parameters

Name	Type	Description
`entityID`	Uuid	The ID of the entity to edit.
`properties`	Entities.EntityProperties	The new property values.

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 },
    lifetime: 300  // Delete after 5 minutes.
});
var properties = Entities.getEntityProperties(entityID, ["color"]);
print("Entity color: " + JSON.stringify(properties.color));

Script.setTimeout(function () { // Wait for the entity to be created before editing.
    Entities.editEntity(entityID, {
        color: { red: 255, green: 0, blue: 0 }
    });
    properties = Entities.getEntityProperties(entityID, ["color"]);
    print("Entity color: " + JSON.stringify(properties.color));
}, 50);

(static) emitScriptEvent( entityID, message )

Sends a message to a Web entity's HTML page. To receive the message, the web page's script must connect to the EventBridge that is automatically provided to the script:

EventBridge.scriptEventReceived.connect(function(message) {
    ...
});

Use Entities.webEventReceived to receive messages from the Web entity's HTML page.

Alternatively, you can use Entities.getEntityObject to exchange messages over a Web entity's HTML event bridge.

Parameters

Name	Type	Description
`entityID`	Uuid	The ID of the Web entity to send the message to.
`message`	string	The message to send.

Example

Exchange messages with a Web entity.

// HTML file, name: "webEntity.html".
<!DOCTYPE html>
<html>
<head>
    <title>HELLO</title>
</head>
<body>
    <h1>HELLO</h1>
    <script>
        function onScriptEventReceived(message) {
            // Message received from the script.
            console.log("Message received: " + message);
        }

        EventBridge.scriptEventReceived.connect(onScriptEventReceived);

        setTimeout(function () {
            // Send a message to the script.
            EventBridge.emitWebEvent("hello");
        }, 5000);
    </script>
</body>
</html>

// Script file.
var webEntity = Entities.addEntity({
    type: "Web",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -3 })),
    rotation: MyAvatar.orientation,
    sourceUrl: Script.resolvePath("webEntity.html"),
    alpha: 1.0,
    lifetime: 300  // 5 min
});

function onWebEventReceived(entityID, message) {
    if (entityID === webEntity) {
        // Message received.
        print("Message received: " + message);

        // Send a message back.
        Entities.emitScriptEvent(webEntity, message + " back");
    }
}

Entities.webEventReceived.connect(onWebEventReceived);

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

Finds the domain or avatar 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 intersect the search sphere. The array is empty if no entities could be found.

Finds all domain and avatar entities that intersect a sphere.

Note: Server entity scripts only find entities that have a server entity script running in them or a parent entity. You can apply a dummy script to entities that you want found in a search.

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.

Finds all domain and avatar entities with a particular name that intersect a sphere.

Note: Server entity scripts only find entities that have a server entity script running in them or a parent entity. You can apply a dummy script to entities that you want found in a search.

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	`true` if the search is case-sensitive, `false` if it is case-insensitive.

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.

Finds all domain and avatar entities of a particular type that intersect a sphere.

Note: Server entity scripts only find entities that have a server entity script running in them or a parent entity. You can apply a dummy script to entities that you want found in a search.

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.

Finds all domain and avatar entities whose axis-aligned boxes intersect a search axis-aligned box.

Note: Server entity scripts only find entities that have a server entity script running in them or a parent entity. You can apply a dummy script to entities that you want found in a search.

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 whose axis-aligned boxes intersect the search frustum. The array is empty if no entities could be found.

Finds all domain and avatar entities whose axis-aligned boxes intersect a search frustum.

Note: Server entity scripts only find entities that have a server entity script running in them or a parent entity. You can apply a dummy script to entities that you want found in a search.

Parameters

Name	Type	Description
`frustum`	ViewFrustum	The frustum to search in. The `position`, `orientation`, `projection`, and `centerRadius` properties must be specified. The `fieldOfView` and `aspectRatio` properties are not used; these values are specified by the `projection`.

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.

Finds the first avatar or domain 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 pick ray to use for finding entities.
`precisionPicking`	boolean	<optional>	false	`true` to pick against precise meshes, `false` to pick against coarse meshes. 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	`true` if only entities that are `visible` are searched for, `false` if their visibility doesn't matter.
`collideableOnly`	boolean	<optional>	false	`true` if only entities that are not `collisionless` are searched, `false` if their collideability doesn't matter.

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.

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

Example

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

entityID = Entities.addEntity({
    type: "Model",
    modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
    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.

Gets 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 action if found, otherwise an empty object.

Gets 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: The action IDs if any are found, otherwise an empty array.

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

Gets the IDs of entities and avatars that are directly parented to an entity or avatar model. To get all descendants, you can recurse on the IDs returned.

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.

Gets the IDs of entities and avatars that are directly parented to an entity or avatar model's joint. To get all descendants, you can use getChildrenIDs to recurse on the IDs returned.

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);

Script.setTimeout(function () { // Wait for the entity to be created before editing.
    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.
}, 50);

(static) getDrawZoneBoundaries( ) → {boolean} Returns: `true` if Zone entities' boundaries should be drawn, otherwise `false`.
Gets 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. If the entity doesn't have a parent, its world transform is returned.

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

Gets an entity's script object. In particular, this is useful for accessing a Web entity's HTML EventBridge script object to exchange messages with the web page script.

To send a message from an Interface script to a Web entity over its event bridge:

var entityObject = Entities.getEntityObject(entityID);
entityObject.emitScriptEvent(message);

To receive a message from a Web entity over its event bridge in an Interface script:

var entityObject = Entities.getentityObject(entityID);
entityObject.webEventReceived.connect(function(message) {
    ...
};

Alternatively, you can use Entities.emitScriptEvent and Entities.webEventReceived to exchange messages with a Web entity over its event bridge.

Parameters

Name	Type	Description
`id`	Uuid	The ID of the entity to get the script object for.

Example

Exchange messages with a Web entity.

// HTML file, name: "webEntity.html".
<!DOCTYPE html>
<html>
<head>
    <title>HELLO</title>
</head>
<body>
    <h1>HELLO</h1>
    <script>
        function onScriptEventReceived(message) {
            // Message received from the script.
            console.log("Message received: " + message);
        }
   
        EventBridge.scriptEventReceived.connect(onScriptEventReceived);
   
        setTimeout(function () {
            // Send a message to the script.
            EventBridge.emitWebEvent("hello");
        }, 5000);
    </script>
</body>
</html>

// Interface script file.
var webEntity = Entities.addEntity({
    type: "Web",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -3 })),
    rotation: MyAvatar.orientation,
    sourceUrl: Script.resolvePath("webEntity.html"),
    alpha: 1.0,
    lifetime: 300  // 5 min
});

var webEntityObject;

function onWebEventReceived(message) {
    // Message received.
    print("Message received: " + message);

    // Send a message back.
    webEntityObject.emitScriptEvent(message + " back");
}

Script.setTimeout(function () {
    webEntityObject = Entities.getEntityObject(webEntity);
    webEntityObject.webEventReceived.connect(onWebEventReceived);
}, 500);

Script.scriptEnding.connect(function () {
    Entities.deleteEntity(webEntity);
});

(static) getEntityProperties( entityID, desiredPropertiesopt ) → {Entities.EntityProperties}
Returns: The specified properties of the entity if the entity can be found, otherwise an empty object. If no properties are specified, then all properties are returned.

Gets an entity's property values.

Parameters

Name	Type	Attributes	Default Value	Description
`entityID`	Uuid			The ID of the entity to get the properties of.
`desiredProperties`	string \| Array.<string>	<optional>	[]	The name or names of the properties to get. For properties that are objects (e.g., the `"keyLight"` property), use the property and subproperty names in dot notation (e.g., `"keyLight.color"`).

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 },
    lifetime: 300  // Delete after 5 minutes.
});
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.

Gets 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) getEntityType( id ) → {Entities.EntityType}
Returns: The type of the entity.

Gets an entity's type.

Parameters

Name	Type	Description
`id`	Uuid	The ID of the entity to get the type of.

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

Gets 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://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
    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.

Gets 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://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
    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 if found, otherwise -1.

Gets the index of the parent joint of a joint in a Model entity.

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`.
Gets 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.
Gets 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.
Gets 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.
Gets 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.
Gets 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.
Gets 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.
Gets 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.
Gets 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.
Gets 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.
Gets 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.
Gets 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`.
Gets whether or not ray picks intersect the bounding box of Light entities. Ray picks are performed 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.

Gets 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://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
    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.

Gets 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 )

Gets the meshes in a Model or PolyVox entity.

Deprecated: This function is deprecated and will be removed. It no longer works for Model entities. 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 specified properties of each entity for each entity that can be found. If none of the entities can be found, then an empty array is returned. If no properties are specified, then all properties are returned.

Gets 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>	[]	The name or names of the properties to get. For properties that are objects (e.g., the `"keyLight"` property), use the property and subproperty names in dot notation (e.g., `"keyLight.color"`).

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 ) → {Entities.NestableType}
Returns: The type of the item.

Gets 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

Report 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.
Gets the maximum number of entity packets that the client can send per second.

(static) getPropertyInfo( propertyName ) → {Entities.EntityPropertyInfo}
Returns: The information about the property if it can be found, otherwise an empty object.

Gets information about an entity property, including a minimum to maximum range for some numerical properties.

Parameters

Name	Type	Description
`propertyName`	string	The name of the property to get the information for.

Example

Report property information for some properties.

print("alpha: " + JSON.stringify(Entities.getPropertyInfo("alpha")));
print("script: " + JSON.stringify(Entities.getPropertyInfo("script")));

(static) getServerScriptStatus( entityID, callback ) → {boolean}
Returns: true always.

Gets the status of a 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 of.
`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 "".

Gets 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`.
Gets whether or not ray picks intersect the bounding box of Zone entities. Ray picks are performed using findRayIntersection, or the Picks API.

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

(static) isAddedEntity( id ) → {boolean}
Returns: true if an entity with the specified ID exists, false if it doesn't.

Checks if there is an entity with a specified 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.

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

Checks whether an entity'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 and outside the entity's bounding box.

Converts 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. 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.
`localCoords`	Vec3	The local coordinates. The value may be outside the entity's bounding box.

(static) localToWorldAngularVelocity( localAngularVelocity, parentID, parentJointIndexopt, scalesWithParentopt ) → {Vec3}
Returns: The angular velocity converted to world coordinates if successful, otherwise Vec3.ZERO.

Converts a Euler angular velocity in an avatar, entity, or joint's local coordinate to an angular velocity in world coordinates.

Parameters

Name	Type	Attributes	Default Value	Description
`localAngularVelocity`	Vec3			The local Euler angular velocity to convert. (Can be in any unit, e.g., deg/s or rad/s.)
`parentID`	Uuid			The avatar or entity that the local coordinates are based on.
`parentJointIndex`	number	<optional>	-1	The joint in the avatar or entity that the local coordinates are based on. If `-1` then no joint is used and the local coordinates are based solely on the avatar or entity.
`scalesWithParent`	boolean	<optional>	false	Not used in the calculation.

(static) localToWorldDimensions( localDimensions, parentID, parentJointIndexopt, scalesWithParentopt ) → {Vec3}
Returns: The dimensions converted to world coordinates if successful, otherwise Vec3.ZERO.

Converts dimensions in an avatar or entity's local coordinates to dimensions in world coordinates.

Parameters

Name	Type	Attributes	Default Value	Description
`localDimensions`	Vec3			The local dimensions to convert.
`parentID`	Uuid			The avatar or entity that the local coordinates are based on.
`parentJointIndex`	number	<optional>	-1	Not used in the calculation.
`scalesWithParent`	boolean	<optional>	false	`true` if the local dimensions are scaled per the parent's scale, `false` if the local dimensions are at world scale.

(static) localToWorldPosition( localPosition, parentID, parentJointIndexopt, scalesWithparentopt ) → {Vec3}
Returns: The position converted to world coordinates if successful, otherwise Vec3.ZERO.

Converts a position in an avatar, entity, or joint's local coordinate to a position in world coordinates.

Parameters

Name	Type	Attributes	Default Value	Description
`localPosition`	Vec3			The local position to convert.
`parentID`	Uuid			The avatar or entity that the local coordinates are based on.
`parentJointIndex`	number	<optional>	-1	The joint in the avatar or entity that the local coordinates are based on. If `-1` then no joint is used and the local coordinates are based solely on the avatar or entity.
`scalesWithparent`	boolean	<optional>	false	`true` if the local dimensions are scaled per the parent's scale, `false` if the local dimensions are at world scale.

(static) localToWorldRotation( localRotation, parentID, parentJointIndexopt, scalesWithParentopt ) → {Quat}
Returns: The rotation converted to local coordinates if successful, otherwise Quat.IDENTITY.

Converts a rotation or orientation in an avatar, entity, or joint's local coordinate to a rotation in world coordinates.

Parameters

Name	Type	Attributes	Default Value	Description
`localRotation`	Quat			The local rotation to convert.
`parentID`	Uuid			The avatar or entity that the local coordinates are based on.
`parentJointIndex`	number	<optional>	-1	The joint in the avatar or entity that the local coordinates are based on. If `-1` then no joint is used and the local coordinates are based solely on the avatar or entity.
`scalesWithParent`	boolean	<optional>	false	Not used in the calculation.

(static) localToWorldVelocity( localVelocity, parentID, parentJointIndexopt, scalesWithParentopt ) → {Vec3}
Returns: The velocity converted to world coordinates it successful, otherwise Vec3.ZERO.

Converts a velocity in an avatar, entity, or joint's local coordinate to a velocity in world coordinates.

Parameters

Name	Type	Attributes	Default Value	Description
`localVelocity`	Vec3			The local velocity to convert.
`parentID`	Uuid			The avatar or entity that the local coordinates are based on.
`parentJointIndex`	number	<optional>	-1	The joint in the avatar or entity that the local coordinates are based on. If `-1` then no joint is used and the local coordinates are based solely on the avatar or entity.
`scalesWithParent`	boolean	<optional>	false	`true` if the local velocity is scaled per the parent's scale, `false` if the local velocity is at world scale.

(static) packetsToSendCount( ) → {number} Returns: Integer number of entity packets the client has waiting to be sent.
Gets the number of entity packets the client has waiting to be sent.

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

Gets 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) queryPropertyMetadata( entityID, property, scope, callback ) → {boolean}
Returns: true if the request for metadata was successfully sent to the server, otherwise false.

Gets 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) 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 )

Emits 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 )

Emits 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 )

Emits 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 )

Emits 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 )

Emits 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 )

Emits 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 )

Emits 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 )

Emits 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 )

Emits 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`.
Checks 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.

Sets 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://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
    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.

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

Sets all the points in a Line entity.

Deprecated: This function is deprecated and will be removed. Use PolyLine entities instead.

Parameters

Name	Type	Description
`entityID`	Uuid	The ID of the Line entity.
`points`	Array.<Vec3>	The points that the entity should draw lines between.

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 )

Sets 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 )

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

Parameters

Name	Type	Description
`value`	boolean	`true` if Zone entities' boundaries should be drawn, otherwise `false`.

(static) setKeyboardFocusEntity( id )

Sets 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 )

Sets 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 performed using findRayIntersection, or the Picks API.

Parameters

Name	Type	Description
`value`	boolean	`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.

Sets 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://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
    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.

Sets 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://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
    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.

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

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

Sets 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 )

Sets 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 )

Sets the value of a particular voxel 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 )

Sets 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 )

Sets 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 )

Sets 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 )

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

Parameters

Name	Type	Description
`value`	boolean	`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 some text in a Text entity. The entity need not be set visible.

Note: The size of text in a Text entity cannot be calculated immediately after the entity is created; a short delay is required while the entity finishes being created.

Parameters

Name	Type	Description
`id`	Uuid	The ID of the Text 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.

Updates 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, its certificateID property is present, and its value matches the entity's static certificate JSON; otherwise false.

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

Converts voxel coordinates in a PolyVox entity to local coordinates. Local coordinates are relative to the minimum axes value corner of the entity, with the scale being the same as 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. The value 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.

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

Checks 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 and outside the entity's bounding box.

Converts 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. The value may be outside the entity's bounding box.

(static) worldToLocalAngularVelocity( worldAngularVelocity, parentID, parentJointIndexopt, scalesWithParentopt ) → {Vec3}
Returns: The angular velocity converted to local coordinates if successful, otherwise Vec3.ZERO.

Converts a Euler angular velocity in world coordinates to an angular velocity in an avatar, entity, or joint's local coordinates.

Parameters

Name	Type	Attributes	Default Value	Description
`worldAngularVelocity`	Vec3			The world Euler angular velocity to convert. (Can be in any unit, e.g., deg/s or rad/s.)
`parentID`	Uuid			The avatar or entity that the local coordinates are based on.
`parentJointIndex`	number	<optional>	-1	The joint in the avatar or entity that the local coordinates are based on. If `-1` then no joint is used and the local coordinates are based solely on the avatar or entity.
`scalesWithParent`	boolean	<optional>	false	Not used in the calculation.

(static) worldToLocalDimensions( worldDimensions, parentID, parentJointIndexopt, scalesWithParentopt ) → {Vec3}
Returns: The dimensions converted to local coordinates if successful, otherwise Vec3.ZERO.

Converts dimensions in world coordinates to dimensions in an avatar or entity's local coordinates.

Parameters

Name	Type	Attributes	Default Value	Description
`worldDimensions`	Vec3			The world dimensions to convert.
`parentID`	Uuid			The avatar or entity that the local coordinates are based on.
`parentJointIndex`	number	<optional>	-1	Not used in the calculation.
`scalesWithParent`	boolean	<optional>	false	`true` to scale the local dimensions per the parent's scale, `false` for the local dimensions to be at world scale.

(static) worldToLocalPosition( worldPosition, parentID, parentJointIndexopt, scalesWithParentopt ) → {Vec3}
Returns: The position converted to local coordinates if successful, otherwise Vec3.ZERO.

Converts a position in world coordinates to a position in an avatar, entity, or joint's local coordinates.

Parameters

Name	Type	Attributes	Default Value	Description
`worldPosition`	Vec3			The world position to convert.
`parentID`	Uuid			The avatar or entity that the local coordinates are based on.
`parentJointIndex`	number	<optional>	-1	The joint in the avatar or entity that the local coordinates are based on. If `-1` then no joint is used and the local coordinates are based solely on the avatar or entity.
`scalesWithParent`	boolean	<optional>	false	`true` to scale the local position per the parent's scale, `false` for the local position to be at world scale.

Example

Report the local coordinates of an entity parented to another.

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

var parentEntity = Entities.addEntity({
    type: "Box",
    position: parentPosition,
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.5, y: 0.5, z: 0.5 },
    lifetime: 300  // Delete after 5 minutes.
});
var childEntity = Entities.addEntity({
    type: "Sphere",
    position: childPosition,
    dimensions: { x: 0.5, y: 0.5, z: 0.5 },
    parentID: parentEntity,
    lifetime: 300  // Delete after 5 minutes.
});

var localPosition = Entities.worldToLocalPosition(childPosition, parentEntity);
print("Local position: " + JSON.stringify(localPosition));  // 0, 1, 0.
localPosition = Entities.getEntityProperties(childEntity, "localPosition").localPosition;
print("Local position: " + JSON.stringify(localPosition));  // The same.

(static) worldToLocalRotation( worldRotation, parentID, parentJointIndexopt, scalesWithParentopt ) → {Quat}
Returns: The rotation converted to local coordinates if successful, otherwise Quat.IDENTITY.

Converts a rotation or orientation in world coordinates to rotation in an avatar, entity, or joint's local coordinates.

Parameters

Name	Type	Attributes	Default Value	Description
`worldRotation`	Quat			The world rotation to convert.
`parentID`	Uuid			The avatar or entity that the local coordinates are based on.
`parentJointIndex`	number	<optional>	-1	The joint in the avatar or entity that the local coordinates are based on. If `-1` then no joint is used and the local coordinates are based solely on the avatar or entity.
`scalesWithParent`	boolean	<optional>	false	Not used in the calculation.

(static) worldToLocalVelocity( worldVelocity, parentID, parentJointIndexopt, scalesWithParentopt ) → {Vec3}
Returns: The velocity converted to local coordinates if successful, otherwise Vec3.ZERO.

Converts a velocity in world coordinates to a velocity in an avatar, entity, or joint's local coordinates.

Parameters

Name	Type	Attributes	Default Value	Description
`worldVelocity`	Vec3			The world velocity to convert.
`parentID`	Uuid			The avatar or entity that the local coordinates are based on.
`parentJointIndex`	number	<optional>	-1	The joint in the avatar or entity that the local coordinates are based on. If `-1` then no joint is used and the local coordinates are based solely on the avatar or entity.
`scalesWithParent`	boolean	<optional>	false	`true` to scale the local velocity per the parent's scale, `false` for the local velocity to be at world scale.

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 created (e.g., by 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 a "wearable" entity is added to Interface's local in-memory tree of entities it knows about, for example when adding a "wearable" to your avatar.

Parameters

Name	Type	Description
`entityID`	Uuid	The ID of the "wearable" entity added.

Example

Report when a "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, `false` if it can't.

Example

Report when your ability to change locks changes.

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

canGetAndSetPrivateUserDataChanged( canGetAndSetPrivateUserData )
Returns: Signal

Triggered when your ability to get and set private user data changes.

Parameters

Name	Type	Description
`canGetAndSetPrivateUserData`	boolean	`true` if the script can change the `privateUserData` property of an entity, `false` if it can't.

canRezAvatarEntitiesChanged( canRezAvatarEntities )
Returns: Signal

Triggered when your ability to use avatar entities is changed.

Parameters

Name	Type	Description
`canRezAvatarEntities`	boolean	`true` if the script can change edit avatar entities, `false` if it can't.

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, `false` if it can't.

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, `false` if it can't.

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, `false` if it can't.

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, `false` if it can't.

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 asset server's assets, `false` if it can't.

clearingEntities( )
Returns: Signal

Triggered when you disconnect from a domain, at which time Interface's local in-memory tree of entities that 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 controllers.

See also, Entity Methods and Script.addEventHandler.

Parameters

Name	Type	Description
`entityID`	Uuid	The ID of the entity that was clicked on.
`event`	PointerEvent	Details of the event.

Example

Compare clickDownOnEntity signal and entity script method.

var entityScript = (function () {
    // Method is called for only this entity.
    this.clickDownOnEntity = function (entityID, event) {
        print("Entity : Clicked sphere ; " + event.type);
    };
});

var sphereID = Entities.addEntity({
    type: "Sphere",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
    script: "(" + entityScript + ")",  // Could host the script on a Web server instead.
    lifetime: 300  // Delete after 5 minutes.
});

Entities.clickDownOnEntity.connect(function (entityID, event) {
    // Signal is triggered for all entities.
    if (entityID === sphereID) {
        print("Interface : Clicked sphere ; " + event.type);
    } else {
        print("Interface : Clicked another entity ; " + event.type);
    }
});

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

See also, Entity Methods and Script.addEventHandler.

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.

See also, Entity Methods and Script.addEventHandler.

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 a "wearable" entity is deleted, for example when removing a "wearable" from your avatar.

Parameters

Name	Type	Description
`entityID`	Uuid	The ID of the "wearable" entity deleted.

Example

Report when a "wearable" entity is deleted.

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

enterEntity( entityID )
Returns: Signal

Triggered when an avatar enters an entity. Note: At the initial loading of the script, if the avatar is already present inside the entity, it might be too late to catch this event when the script runs, so it won't trigger. The preload signal can be used to handle those cases.

See also, Entity Methods and Script.addEventHandler.

Parameters

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

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

See also, Entity Methods and Script.addEventHandler.

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.

See also, Entity Methods and Script.addEventHandler.

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.

See also, Entity Methods and Script.addEventHandler.

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.

See also, Entity Methods and Script.addEventHandler.

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.

See also, Entity Methods and Script.addEventHandler.

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 on.
`event`	PointerEvent	Details of the event.

mouseMoveOnEntity( entityID, event )
Returns: Signal

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

See also, Entity Methods and Script.addEventHandler.

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.

See also, Entity Methods and Script.addEventHandler.

Parameters

Name	Type	Description
`entityID`	Uuid	The ID of the entity that was pressed on.
`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.

See also, Entity Methods and Script.addEventHandler.

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. See also, Script.entityScriptPreloadFinished.

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

Supported Script Types: Client Entity Scripts • Server 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( entityID )
Returns: Signal

Triggered when the script terminates for a user.

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

Supported Script Types: Client Entity Scripts • Server Entity Scripts

Parameters

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

webEventReceived( entityID, message )
Returns: Signal

Triggered when a script in a Web entity's HTML sends an event over the entity's HTML event bridge. The HTML web page can send a message by calling:

EventBridge.emitWebEvent(message);

Use Entities.emitScriptEvent to send messages to the Web entity's HTML page.

Alternatively, you can use Entities.getEntityObject to exchange messages over a Web entity's HTML event bridge.

Parameters

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