Entities

Description

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 scripts, the entities available to scripts are those that Interface has displayed and so knows about.

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 NameCorresponding Signal
clickDownOnEntityEntities.clickDownOnEntity
clickReleaseOnEntityEntities.clickReleaseOnEntity
collisionWithEntityEntities.collisionWithEntity
enterEntityEntities.enterEntity
holdingClickOnEntityEntities.holdingClickOnEntity
hoverEnterEntityEntities.hoverEnterEntity
hoverLeaveEntityEntities.hoverLeaveEntity
hoverOverEntityEntities.hoverOverEntity
leaveEntityEntities.leaveEntity
mouseDoublePressOnEntityEntities.mouseDoublePressOnEntity
mouseMoveOnEntityEntities.mouseMoveOnEntity
mouseMoveEventDeprecated: Use mouseMoveOnEntity instead.
mousePressOnEntityEntities.mousePressOnEntity
mouseReleaseOnEntityEntities.mouseReleaseOnEntity

See Entities.clickDownOnEntity for an example.

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

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 avatar entity (entityHostType property is "avatar") or domain entity (entityHostType property is "domain").
addEntity Uuid Adds a new domain, avatar, or local entity.
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.
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.
findEntitiesByName Array.<Uuid> Finds all domain and avatar entities with a particular name that intersect a sphere.
findEntitiesByType Array.<Uuid> Finds all domain and avatar entities of a particular type that intersect a sphere.
findEntitiesInBox Array.<Uuid> Finds all domain and avatar entities whose axis-aligned boxes intersect a search axis-aligned box.
findEntitiesInFrustum Array.<Uuid> Finds all domain and avatar entities whose axis-aligned boxes intersect a search frustum.
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 translation 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. 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.
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, but only if the entity has an entity method exposed for this event.

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, but only if the entity has an entity method exposed for this event.

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.

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

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

Available in:Client Entity ScriptsServer Entity Scripts
webEventReceived Triggered 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.PIMath.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:

ValueTypeDescriptionArguments
"far-grab"Avatar action Moves and rotates an entity to a target position and orientation, optionally relative to another entity. Collisions between the entity and the user's avatar are disabled during the far-grab. Entities.ActionArguments-FarGrab
"hold"Avatar action Positions and rotates an entity relative to an avatar's hand. Collisions between the entity and the user's avatar are disabled during the hold. Entities.ActionArguments-Hold
"offset"Object action Moves an entity so that it is a 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 FBX file that has the animation.

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.

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

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

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

Default Value: -1

lastEdited number When the entity was last edited, expressed as the number of microseconds since 1970-01-01T00:00:00 UTC. Read-only.
lastEditedBy Uuid The session ID of the avatar or agent that most recently created or edited the entity. Read-only.
locked boolean 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.ZEROVec3.ONE. A value of Vec3.ZERO is the entity's minimum x, y, z corner; a value of Vec3.ONE is the entity's maximum x, y, z corner.

Default Value: 0.5,0.5,0.5

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

Default Value: 0,0,0

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

Default Value: 0,0,0

damping number How much the linear velocity of an entity slows down over time, range 0.01.0. A higher damping value slows down the entity more quickly. The default value is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to 1/e = 0.368 of its initial value.

Default Value: 0.39347

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

Default Value: 0,0,0

angularDamping number How much the angular velocity of an entity slows down over time, range 0.01.0. A higher damping value slows down the entity more quickly. The default value is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to 1/e = 0.368 of its initial value.

Default Value: 0.39347

gravity Vec3 The acceleration due to gravity in m/s2 that the entity should move with, in world coordinates. 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. The gravity value is applied in addition to the acceleration value.

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 A general acceleration in m/s2 that the entity should move with, in world coordinates. The acceleration is applied to an entity's motion only if its dynamic property is true. The acceleration value is applied in addition to the gravity value.

If changing an entity's acceleration from Vec3.ZERO, you need to give it a small velocity in order to kick off physics simulation.

Default Value: 0,0,0

restitution number The "bounciness" of an entity when it collides, range 0.00.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.010.0. The higher the value, the more quickly it slows down. Examples: 0.1 for ice, 0.9 for sandpaper.

Default Value: 0.5

density number The density of the entity in kg/m3, range 10010000. 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 High Fidelity 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.
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-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.

billboardMode BillboardMode Whether the entity is billboarded to face the camera.

Default Value: "none"

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. If you append "#name" to the URL, the material with that name in the MaterialResource will be applied to the entity. Alternatively, set the property value to "materialData" to use the materialData property for the MaterialResource values.

Default Value: ""

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 FBX models' URLs end in ".baked.fbx". 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.

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 Vive tracker puck.

var entity = Entities.addEntity({
    type: "Model",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -2 })),
    rotation: MyAvatar.orientation,
    modelURL: "http://content.highfidelity.com/seefo/production/puck-attach/vive_tracker_puck.obj",
    dimensions: { x: 0.0945, y: 0.0921, z: 0.0423 },
    lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-ParticleEffect
Type: object

The "ParticleEffect" EntityType displays a particle system that can be used to simulate things such as fire, smoke, snow, magic spells, etc. The particles emanate from an ellipsoid or part thereof. It has properties in addition to the common EntityProperties.

Properties

Name Type Summary
isEmitting boolean 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 46m/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.01.0 for the center to the surface, respectively. Particles are emitted from the portion of the shape that lies between emitRadiusStart and the shape's surface.

Default Value: 1

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

Default Value: 0

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

Default Value: 0

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

Default Value: -Math.PI

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

Default Value: Math.PI

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

Default Value: ""

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

Default Value: 0.025

radiusStart number The radius of each particle at the start of its life. If 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.250.75.

Default Value: 0

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

Default Value: 255,255,255

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

Default Value: 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.250.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.PI2 * Math.PI radians.

Default Value: 0

spinStart number The rotation of each particle at the start of its life, range -2 * Math.PI2 * 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.PI2 * 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 02 * 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 / 23 * 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.highfidelity.com/DomainContent/production/Particles/wispy-smoke.png",
    particleRadius: 0.1,
    color: { red: 0, green: 255, blue: 0 },
    alphaFinish: 0,
    lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-PolyLine
Type: object

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

Properties

Name Type Summary
dimensions Vec3 The dimensions of the entity, i.e., the size of the bounding box that contains the lines drawn. 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.01.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.01.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: "http://hifi-production.s3.amazonaws.com/DomainContent/Toybox/flowArts/trails.png",
    isUVModeStretch: true,
    lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-PolyVox
Type: object

The "PolyVox" EntityType displays a set of textured voxels. It has properties in addition to the common EntityProperties. If you have two or more neighboring PolyVox entities of the same size abutting each other, you can display them as joined by configuring their voxelSurfaceStyle and 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 High Fidelity 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.01.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-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 should be unaffected by lighting. Otherwise, the text is lit by the keylight and local lights.

Default Value: false

billboardMode BillboardMode Whether the entity is billboarded to face the camera.

Default Value: "none"

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

billboardMode BillboardMode Whether the entity is billboarded to face the camera.

Default Value: "none"

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

Example

Create a Web entity displaying at 1920 x 1080 resolution.

var METERS_TO_INCHES = 39.3701;
var entity = Entities.addEntity({
    type: "Web",
    sourceUrl: "https://highfidelity.com/",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -4 })),
    rotation: MyAvatar.orientation,
    dimensions: {
        x: 3,
        y: 3 * 1080 / 1920,
        z: 0.01
    },
    dpi: 1920 / (3 * METERS_TO_INCHES),
    lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-Zone
Type: object

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

Properties

Name Type Summary
dimensions Vec3 The 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"

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:

ValueDescriptionProperties
"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:

ValueDescription
"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. Use this to fine-tune your shadows to your scene to prevent shadow acne and peter panning. In the range 0.01.0.

Default Value: 0.5

shadowMaxDistance number The max distance from your view at which shadows will be computed. Higher values will cover more of your scene, but with less precision. In the range 1.0250.0.

Default Value: 40.0

Material
Type: object

A material used in a MaterialResource.

Properties

Name Type Summary
model string Different material models support different properties and rendering modes. Supported models are: "hifi_pbr".

Default Value: "hifi_pbr"

name string A name for the material. Supported by all material models.

Default Value: ""

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.01.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.01.0. Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.

Default Value: 1.0

unlit boolean | string true if the material is not lit, false if it is. 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.01.0. A RGBS value can be either RGB or sRGB. Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
roughness number | string The roughness, range 0.01.0. Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
metallic number | string The metallicness, range 0.01.0. Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
scattering number | string The scattering, range 0.01.0. Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
emissiveMap string The URL of the emissive texture image. Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
albedoMap string The URL of the albedo texture image. Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
opacityMap string The URL of the opacity texture image. Set the value the same as the albedoMap value for transparency. "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. 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. 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. 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. 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. Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
scatteringMap string The URL of the scattering texture image. 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. 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" model only.

Default Value: false

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> The details of the material or materials.
NestableType
Type: string

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

ValueDescription
"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:

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

PolyVoxSurfaceStyle
Type: number

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

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

PrimitiveMode
Type: string

How the geometry of an entity is rendered.

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

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

ValueDescription
"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.01.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:

ValueDimensionsNotes
"Circle"2DA circle oriented in 3D.
"Cone"3D
"Cube"3D
"Cylinder"3D
"Dodecahedron"3D
"Hexagon"3DA hexagonal prism.
"Icosahedron"3D
"Octagon"3DAn octagonal prism.
"Octahedron"3D
"Quad"2DA square oriented in 3D.
"Sphere"3D
"Tetrahedron"3D
"Torus"3DNot implemented.
"Triangle"3DA triangular prism.

Skybox
Type: object

A skybox is defined by the following properties:

Properties

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

Default Value: 0,0,0

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

Default Value: ""

getMeshesCallback( meshes, success )
Type: function

Called when a Entities.getMeshes call is complete.

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

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

Called when a Entities.getServerScriptStatus call is complete.

queryPropertyMetadataCallback( error, result )
Type: function

Called when a Entities.queryPropertyMetadata call is complete.

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, 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) 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) 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) 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.

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.

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.

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.

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.

Parameters

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

Report the number of entities in view.

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

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 translation of a joint in a Model entity relative to the entity's position and orientation.

Parameters

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

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

entityID = Entities.addEntity({
    type: "Model",
    modelURL: "https://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. 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",
    posi