Entities

Description

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

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

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

Entity Types & Properties

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

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

Entity Methods

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

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

Properties

Name Type Summary
keyboardFocusEntity Uuid

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

Methods

Name Return Value Summary
AABoxIntersectsCapsule boolean

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

addAction Uuid

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

addEntity Uuid

Adds a new domain, avatar, or local entity.

addEntity Uuid

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

appendPoint boolean

Appends a point to a Line entity.

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

callEntityClientMethod None

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

callEntityMethod None

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

callEntityServerMethod None

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

canAdjustLocks boolean

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

canGetAndSetPrivateUserData boolean

Checks whether or not the script can get and set the privateUserData property of entities.

canReplaceContent boolean

Checks whether or not the script can replace the domain's content set.

canRez boolean

Checks whether or not the script can rez (create) new entities in the domain.

canRezAvatarEntities boolean

Checks whether or not the script can rez avatar entities.

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.

canWriteAssets boolean

Checks whether or not the script can make changes to the asset server's assets.

cloneEntity Uuid

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

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

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

deleteAction boolean

Deletes an action from an entity.

deleteEntity None

Deletes an entity.

dumpTree None

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

editEntity Uuid

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

emitScriptEvent None

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

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

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

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

findClosestEntity Uuid

Finds the domain or avatar entity with a position closest to a specified point and within a specified radius.

findEntities Array.<Uuid>

Finds all domain and avatar entities that intersect a sphere.

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

findEntitiesByName Array.<Uuid>

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

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

findEntitiesByType Array.<Uuid>

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

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

findEntitiesInBox Array.<Uuid>

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

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

findEntitiesInFrustum Array.<Uuid>

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

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

findRayIntersection Entities.RayToEntityIntersectionResult

Finds the first avatar or domain entity intersected by a PickRay. Light and Zone entities are not intersected unless they've been configured as pickable using setLightsArePickable and setZonesArePickable, respectively.

getAbsoluteJointRotationInObjectFrame Quat

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

getAbsoluteJointTranslationInObjectFrame Vec3

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

getActionArguments Entities.ActionArguments

Gets the arguments of an action.

getActionIDs Array.<Uuid>

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

getChildrenIDs Array.<Uuid>

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

getChildrenIDsOfJoint Array.<Uuid>

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

getDrawZoneBoundaries boolean

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

getEntityLocalTransform Mat4

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

getEntityObject object

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

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

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

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

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

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

getEntityProperties Entities.EntityProperties

Gets an entity's property values.

getEntityTransform Mat4

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

getEntityType Entities.EntityType

Gets an entity's type.

getJointIndex number

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

getJointNames Array.<string>

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

getJointParent number

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

getKeyboardFocusEntity Uuid

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

getLifetimeBPS number

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

getLifetimeBPSQueued number

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

getLifetimeBytesQueued number

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

getLifetimeBytesSent number

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

getLifetimeInSeconds number

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

getLifetimeInUsecs number

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

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.

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.

getLightsArePickable boolean

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

getLocalJointRotation Quat

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

getLocalJointTranslation Vec3

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

getMeshes None

Gets the meshes in a Model or PolyVox entity.

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

getMultipleEntityProperties Array.<Entities.EntityProperties>

Gets the properties of multiple entities.

getNestableType Entities.NestableType

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

getPacketsPerSecond number

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

getPropertyInfo Entities.EntityPropertyInfo

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

getServerScriptStatus boolean

Gets the status of a server entity script attached to an entity.

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.

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.

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.

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.

setVoxelSphere None

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

setVoxelsInCuboid None

Sets the values of all voxels in a cubic 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.

voxelCoordsToLocalCoords Vec3

Converts voxel coordinates in a PolyVox entity to local coordinates. Local coordinates are relative to the minimum axes value corner of the entity, with the scale being the same as world coordinates. Voxel coordinates are relative to the minimum axes values corner of the entity, with a scale of Vec3.ONE being the dimensions of each voxel.

voxelCoordsToWorldCoords Vec3

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

wantsHandControllerPointerEvents boolean

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

worldCoordsToVoxelCoords Vec3

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

worldToLocalAngularVelocity Vec3

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

worldToLocalDimensions Vec3

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

worldToLocalPosition Vec3

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

worldToLocalRotation Quat

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

worldToLocalVelocity Vec3

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

Signals

Name Summary
addingEntity

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

addingWearable

Triggered when a "wearable" entity is added to Interface's local in-memory tree of entities it knows about, for example when adding a "wearable" to your avatar.

canAdjustLocksChanged

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

canGetAndSetPrivateUserDataChanged

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

canRezAvatarEntitiesChanged

Triggered when your ability to use avatar entities is changed.

canRezChanged

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

canRezTmpChanged

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

canWriteAssetsChanged

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

clearingEntities

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

clickDownOnEntity

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

See also, Entity Methods and Script.addEventHandler.

clickReleaseOnEntity

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

See also, Entity Methods and Script.addEventHandler.

collisionWithEntity

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

See also, Entity Methods and Script.addEventHandler.

deletingEntity

Triggered when an entity is deleted.

deletingWearable

Triggered when a "wearable" entity is deleted, for example when removing a "wearable" from your avatar.

enterEntity

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

See also, Entity Methods and Script.addEventHandler.

holdingClickOnEntity

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

See also, Entity Methods and Script.addEventHandler.

hoverEnterEntity

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

See also, Entity Methods and Script.addEventHandler.

hoverLeaveEntity

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

See also, Entity Methods and Script.addEventHandler.

hoverOverEntity

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

See also, Entity Methods and Script.addEventHandler.

leaveEntity

Triggered when an avatar leaves an entity.

See also, Entity Methods and Script.addEventHandler.

mouseDoublePressOffEntity

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

mouseDoublePressOnEntity

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

mouseMoveOnEntity

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

See also, Entity Methods and Script.addEventHandler.

mousePressOffEntity

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

mousePressOnEntity

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

See also, Entity Methods and Script.addEventHandler.

mouseReleaseOnEntity

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

See also, Entity Methods and Script.addEventHandler.

unload

Triggered when the script terminates for a user.

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

Supported Script Types: Client Entity Scripts • Server Entity Scripts

webEventReceived

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

EventBridge.emitWebEvent(message);

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

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

Type Definitions

ActionArguments
Type: object

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

Properties

Name Type Summary
type Entities.ActionType

The type of action.

tag string

A string that a script can use for its own purposes.

Default Value: ""

ttl number

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

Default Value: 0

isMine boolean

true if the action was created during the current client session, false if it wasn't. Read-only.

Default Value: true

::no-motion-state boolean

Is present with a value of true when the entity hasn't been registered with the physics engine yet (e.g., if the action hasn't been properly configured), otherwise the property is undefined. Read-only.

::active boolean

true when the action is modifying the entity's motion, false otherwise. Is present once the entity has been registered with the physics engine, otherwise the property is undefined. Read-only.

::motion-type Entities.PhysicsMotionType

How the entity moves with the action. Is present once the entity has been registered with the physics engine, otherwise the property is undefined. Read-only.

See:

ActionArguments-BallSocket
Type: object

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

Properties

Name Type Summary
otherEntityID Uuid

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

Default Value: null

pivot Vec3

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

Default Value: 0,0,0

otherPivot Vec3

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

Default Value: 0,0,0

ActionArguments-ConeTwist
Type: object

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

Properties

Name Type Summary
otherEntityID Uuid

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

Default Value: null

pivot Vec3

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

Default Value: 0,0,0

axis Vec3

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

Default Value: 1,0,0

otherPivot Vec3

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

Default Value: 0,0,0

otherAxis Vec3

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

Default Value: 1,0,0

swingSpan1 number

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

Default Value: 2*Math.PI

swingSpan2 number

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

Default Value: 2*Math.PI

twistSpan number

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

Default Value: 2*Math.PI

ActionArguments-FarGrab
Type: object

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

Properties

Name Type Summary
otherID Uuid

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

Default Value: null

otherJointIndex Uuid

If a joint index in the otherID entity, the targetPosition and targetRotation are relative to the entity joint's position and rotation.

Default Value: null

targetPosition Vec3

The target position.

Default Value: 0,0,0

targetRotation Quat

The target rotation.

Default Value: 0,0,0,1

linearTimeScale number

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

Default Value: 3.4e+38

angularTimeScale number

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

Default Value: 3.4e+38

ActionArguments-Hinge
Type: object

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

Properties

Name Type Summary
otherEntityID Uuid

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

Default Value: null

pivot Vec3

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

Default Value: 0,0,0

axis Vec3

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

Default Value: 1,0,0

otherPivot Vec3

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

Default Value: 0,0,0

otherAxis Vec3

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

Default Value: 1,0,0

low number

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

Default Value: -2*Math.PI

high number

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

Default Value: 2*Math.PI

angle number

The current angle of the hinge, in radians, range -Math.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 glTF or FBX file that has the animation. glTF files may be in JSON or binary format (".gltf" or ".glb" URLs respectively).

Warning: glTF animations currently do not always animate correctly.

Default Value: ""

allowTranslation boolean

true to enable translations contained in the animation to be played, false to disable translations.

Default Value: true

fps number

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

Default Value: 30

firstFrame number

The first frame to play in the animation.

Default Value: 0

lastFrame number

The last frame to play in the animation.

Default Value: 100000

currentFrame number

The current frame being played in the animation.

Default Value: 0

running boolean

true if the animation should play, false if it shouldn't.

Default Value: false

loop boolean

true if the animation is continuously repeated in a loop, false if it isn't.

Default Value: true

hold boolean

true if the rotations and translations of the last frame played are maintained when the animation stops playing, false if they aren't.

Default Value: false

AvatarPriorityMode
Type: string

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

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 number

When the entity was created, expressed as the number of microseconds since 1970-01-01T00:00:00 UTC. Read-only.

age number

The age of the entity in seconds since it was created. Read-only.

ageAsText string

The age of the entity since it was created, formatted as h hours m minutes s seconds.

lifetime number

How long an entity lives for, in seconds, before being automatically deleted. A value of -1 means that the entity lives for ever.

Default Value: -1

lastEdited number

When the entity was last edited, expressed as the number of microseconds since 1970-01-01T00:00:00 UTC. Read-only.

lastEditedBy Uuid

The session ID of the avatar or agent that most recently created or edited the entity. Read-only.

locked boolean

true if properties other than locked cannot be changed and the entity cannot be deleted, false if all properties can be changed and the entity can be deleted.

Default Value: false

visible boolean

true if the entity is rendered, false if it isn't.

Default Value: true

canCastShadow boolean

true if the entity can cast a shadow, false if it can't. Currently applicable only to Model and Shape entities. Shadows are cast if inside a Zone entity with castShadows enabled in its keyLight property.

Default Value: true

isVisibleInSecondaryCamera boolean

true if the entity is rendered in the secondary camera, false if it isn't.

Default Value: true

renderLayer Entities.RenderLayer

The layer that the entity renders in.

Default Value: "world"

primitiveMode Entities.PrimitiveMode

How the entity's geometry is rendered.

Default Value: "solid"

ignorePickIntersection boolean

true if Picks and RayPick ignore the entity, false if they don't.

Default Value: false

position Vec3

The position of the entity in world coordinates.

Default Value: 0,0,0

rotation Quat

The orientation of the entity in world coordinates.

Default Value: 0,0,0,1

registrationPoint Vec3

The point in the entity that is set to the entity's position and is rotated about, range Vec3.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 or image if it has one, otherwise Vec3.ONE. Read-only.

velocity Vec3

The linear velocity of the entity in m/s with respect to world coordinates.

Default Value: 0,0,0

damping number

How much the linear velocity of an entity slows down over time, range 0.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.

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

Default Value: 0,0,0

acceleration Vec3

The current, measured acceleration of the entity, in m/s2.

Deprecated: This property is deprecated and will be removed.

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://" directory services 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 Overte datagram packet, there is a limit to the number of actions that an entity can have; edits which would result in overflow are rejected. Read-only.

Default Value: ""

renderInfo Entities.RenderInfo

Information on the cost of rendering the entity. Currently information is only provided for Model entities. Read-only.

cloneable boolean

true if the domain or avatar entity can be cloned via Entities.cloneEntity, false if it can't be.

Default Value: false

cloneLifetime number

The entity lifetime for clones created from this entity.

Default Value: 300

cloneLimit number

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

Default Value: 0

cloneDynamic boolean

true if clones created from this entity will have their dynamic property set to true, false if they won't.

Default Value: false

cloneAvatarEntity boolean

true if clones created from this entity will be created as avatar entities, false if they won't be.

Default Value: false

cloneOriginID Uuid

The ID of the entity that this entity was cloned from.

renderWithZones Array.<Uuid>

A list of entity IDs representing with which zones this entity should render. If it is empty, this entity will render normally. Otherwise, this entity will only render if your avatar is within one of the zones in this list.

Default Value: []

billboardMode BillboardMode

Whether the entity is billboarded to face the camera. Use the rotation property to control which axis is facing you.

Default Value: "none"

grab Entities.Grab

The entity's grab-related properties.

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.

faceCamera boolean

true if billboardMode is "yaw", false if it isn't. Setting this property to false sets the billboardMode to "none".

Deprecated: This property is deprecated and will be removed.

isFacingAvatar boolean

true if billboardMode is "full", false if it isn't. Setting this property to false sets the billboardMode to "none".

Deprecated: This property is deprecated and will be removed.

Example

Create an image entity.

var image = Entities.addEntity({
    type: "Image",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    dimensions: { x: 0.6, y: 0.3, z: 0.01 },
    imageURL: "https://images.pexels.com/photos/1020315/pexels-photo-1020315.jpeg",
    billboardMode: "yaw",
    lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-Light
Type: object

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

Properties

Name Type Summary
dimensions Vec3

The dimensions of the entity. Surfaces outside these dimensions are not lit by the light.

Default Value: 0.1,0.1,0.1

color Color

The color of the light emitted.

Default Value: 255,255,255

intensity number

The brightness of the light.

Default Value: 1

falloffRadius number

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

Default Value: 0.1

isSpotlight boolean

true if the light is directional, emitting along the entity's local negative z-axis; false if the light is a point light which emanates in all directions.

Default Value: false

exponent number

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

Default Value: 0

cutoff number

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

Default Value: 1.57

Example

Create a spotlight pointing at the ground.

Entities.addEntity({
    type: "Light",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -4 })),
    rotation: Quat.fromPitchYawRollDegrees(-75, 0, 0),
    dimensions: { x: 5, y: 5, z: 5 },
    intensity: 100,
    falloffRadius: 0.3,
    isSpotlight: true,
    exponent: 20,
    cutoff: 30,
    lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-Line
Type: object

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

Deprecated: Use PolyLine entities instead.

Properties

Name Type Summary
dimensions Vec3

The dimensions of the entity. Must be sufficient to contain all the linePoints.

Default Value: 0.1,0.1,0.1

linePoints Array.<Vec3>

The sequence of points to draw lines between. The values are relative to the entity's position. A maximum of 70 points can be specified. The property's value is set only if all the linePoints lie within the entity's dimensions.

Default Value: []

color Color

The color of the line.

Default Value: 255,255,255

Example

Draw lines in a "V".

var entity = Entities.addEntity({
    type: "Line",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -5 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 2, y: 2, z: 1 },
    linePoints: [
        { x: -1, y: 1, z: 0 },
        { x: 0, y: -1, z: 0 },
        { x: 1, y: 1, z: 0 },
    ],
    color: { red: 255, green: 0, blue: 0 },
    lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-Material
Type: object

The "Material" EntityType modifies existing materials on entities and avatars. It has properties in addition to the common EntityProperties.

To apply a material to an entity, set the material entity's parentID property to the entity ID. To apply a material to an avatar, set the material entity's parentID property to the avatar's session UUID. To apply a material to your avatar such that it persists across domains and log-ins, create the material as an avatar entity by setting the entityHostType parameter in Entities.addEntity to "avatar" and set the entity's parentID property to MyAvatar.SELF_ID. Material entities render as non-scalable spheres if they don't have their parent set.

Properties

Name Type Summary
dimensions Vec3

Used when materialMappingMode == "projected".

Default Value: 0.1,0.1,0.1

materialURL string

URL to a MaterialResource. Alternatively, set the property value to "materialData" to use the materialData property for the MaterialResource values. If you append "#name" to the URL, the material with that name will be applied to the entity. You can also use the ID of another Material entity as the URL, in which case this material will act as a copy of that material, with its own unique material transform, priority, etc.

Default Value: ""

materialData string

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

Default Value: ""

priority number

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

Default Value: 0

parentMaterialName string

Selects the mesh part or parts within the parent to which to apply the material. If in the format "mat::string", all mesh parts with material name "string" are replaced. If "all", then all mesh parts are replaced. Otherwise the property value is parsed as an unsigned integer, specifying the mesh part index to modify.

If the string represents an array (starts with "[" and ends with "]"), the string is split at each "," and each element parsed as either a number or a string if it starts with "mat::". For example, "[0,1,mat::string,mat::string2]" will replace mesh parts 0 and 1, and any mesh parts with material "string" or "string2". Do not put spaces around the commas. Invalid values are parsed to 0.

Default Value: "0"

materialMappingMode string

How the material is mapped to the entity. Either "uv" or "projected". In "uv" mode, the material is evaluated within the UV space of the mesh it is applied to. In "projected" mode, the 3D transform (position, rotation, and dimensions) of the Material entity is used to evaluate the texture coordinates for the material.

Default Value: "uv"

materialMappingPos Vec2

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

Default Value: 0,0

materialMappingScale Vec2

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

Default Value: 1,1

materialMappingRot number

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

Default Value: 0

materialRepeat boolean

true if the material repeats, false if it doesn't. If false, fragments outside of texCoord 0 – 1 will be discarded. Works in both "uv" and "projected" modes.

Default Value: true

Example

Color a sphere using a Material entity.

var entityID = Entities.addEntity({
    type: "Sphere",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    dimensions: { x: 1, y: 1, z: 1 },
    color: { red: 128, green: 128, blue: 128 },
    lifetime: 300  // Delete after 5 minutes.
});

var materialID = Entities.addEntity({
    type: "Material",
    parentID: entityID,
    materialURL: "materialData",
    priority: 1,
    materialData: JSON.stringify({
        materialVersion: 1,
        materials: {
            // Value overrides entity's "color" property.
            albedo: [1.0, 1.0, 0]  // Yellow
        }
    })
});
EntityProperties-Model
Type: object

The "Model" EntityType displays a glTF, FBX, or OBJ model. When adding an entity, if no dimensions value is specified then the model is automatically sized to its naturalDimensions. It has properties in addition to the common EntityProperties.

Properties

Name Type Summary
dimensions Vec3

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

Default Value: 0.1,0.1,0.1

modelURL string

The URL of the glTF, FBX, or OBJ model. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs respectively). Baked models' URLs have ".baked" before the file type. Model files may also be compressed in GZ format, in which case the URL ends in ".gz".

Default Value: ""

modelScale Vec3

The scale factor applied to the model's dimensions.

Deprecated: This property is deprecated and will be removed.

blendshapeCoefficients string

A JSON string of a map of blendshape names to values. Only stores set values. When editing this property, only coefficients that you are editing will change; it will not explicitly reset other coefficients.

useOriginalPivot boolean

If false, the model will be centered based on its content, ignoring any offset in the model itself. If true, the model will respect its original offset. Currently, only pivots relative to {x: 0, y: 0, z: 0} are supported.

Default Value: false

textures string

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

Default Value: ""

originalTextures string

A JSON string of texture name, URL pairs used in the model. The property value is filled in after the entity has finished rezzing (i.e., textures have loaded). You can use JSON.parse() to parse the JSON string into a JavaScript object of name, URL pairs. Read-only.

Default Value: "{}"

color Color

Currently not used.

Default Value: 255,255,255

shapeType ShapeType

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

Default Value: "none"

compoundShapeURL string

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

Default Value: ""

animation Entities.AnimationProperties

An animation to play on the model.

jointRotations Array.<Quat>

Joint rotations applied to the model; [] if none are applied or the model hasn't loaded. The array indexes are per getJointIndex. Rotations are relative to each joint's parent.

Joint rotations can be set by setLocalJointRotation and similar functions, or by setting the value of this property. If you set a joint rotation using this property, you also need to set the corresponding jointRotationsSet value to true.

Default Value: []

jointRotationsSet Array.<boolean>

true values for joints that have had rotations applied, false otherwise; [] if none are applied or the model hasn't loaded. The array indexes are per getJointIndex.

Default Value: []

jointTranslations Array.<Vec3>

Joint translations applied to the model; [] if none are applied or the model hasn't loaded. The array indexes are per getJointIndex. Translations are relative to each joint's parent.

Joint translations can be set by setLocalJointTranslation and similar functions, or by setting the value of this property. If you set a joint translation using this property you also need to set the corresponding jointTranslationsSet value to true.

Default Value: []

jointTranslationsSet Array.<boolean>

true values for joints that have had translations applied, false otherwise; [] if none are applied or the model hasn't loaded. The array indexes are per getJointIndex.

Default Value: []

relayParentJoints boolean

true if when the entity is parented to an avatar, the avatar's joint rotations are applied to the entity's joints; false if a parent avatar's joint rotations are not applied to the entity's joints.

Default Value: false

groupCulled boolean

true if the mesh parts of the model are LOD culled as a group, false if separate mesh parts are LOD culled individually.

Default Value: false

Example

Rez a cowboy hat.

var entity = Entities.addEntity({
    type: "Model",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -2 })),
    rotation: MyAvatar.orientation,
    modelURL: "https://apidocs.overte.org/examples/cowboy-hat.fbx",
    dimensions: { x: 0.8569, y: 0.3960, z: 1.0744 },
    lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-ParticleEffect
Type: object

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

Properties

Name Type Summary
isEmitting boolean

true if particles are being emitted, false if they aren't.

Default Value: true

maxParticles number

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

Default Value: 1000

lifespan number

How long, in seconds, each particle lives.

Default Value: 3s

emitRate number

The number of particles per second to emit.

Default Value: 15

emitSpeed number

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

Default Value: 5

speedSpread number

The spread in speeds at which particles are emitted at. For example, if emitSpeed == 5 and speedSpread == 1, particles will be emitted with speeds in the range 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.overte.org/Bazaar/Assets/Textures/Defaults/Interface/default_particle.png",
    particleRadius: 0.1,
    color: { red: 0, green: 255, blue: 0 },
    alphaFinish: 0,
    lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-PolyLine
Type: object

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

Properties

Name Type Summary
dimensions Vec3

The dimensions of the entity, i.e., the size of the bounding box that contains the lines drawn. Read-only.

Default Value: 0.1,0.1,0.1

linePoints Array.<Vec3>

The sequence of points to draw lines between. The values are relative to the entity's position. A maximum of 70 points can be specified.

Default Value: []

normals Array.<Vec3>

The normal vectors for the line's surface at the linePoints. The values are relative to the entity's orientation. Must be specified in order for the entity to render.

Default Value: []

strokeWidths Array.<number>

The widths, in m, of the line at the linePoints. Must be specified in order for the entity to render.

Default Value: []

strokeColors Array.<Vec3>

The base colors of each point, with values in the range 0.0,0.0,0.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: "https://hifi-content/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 Overte 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 },
    voxelVolumeSize: { x: 16, y: 16, z: 16 },
    voxelSurfaceStyle: 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 is unaffected by lighting, false if it is lit by the key light and local lights.

Default Value: false

font string

The font to render the text with. It can be one of the following: "Courier", "Inconsolata", "Roboto", "Timeless", or a path to a .sdff file.

Default Value: ""

textEffect Entities.TextEffect

The effect that is applied to the text.

Default Value: "none"

textEffectColor Color

The color of the effect.

Default Value: 255,255,255

textEffectThickness number

The magnitude of the text effect, range 0.00.5.

Default Value: 0.2

alignment Entities.TextAlignment

How the text is aligned against its background.

Default Value: "left"

faceCamera boolean

true if billboardMode is "yaw", false if it isn't. Setting this property to false sets the billboardMode to "none".

Deprecated: This property is deprecated and will be removed.

isFacingAvatar boolean

true if billboardMode is "full", false if it isn't. Setting this property to false sets the billboardMode to "none".

Deprecated: This property is deprecated and will be removed.

Example

Create a text entity.

var text = Entities.addEntity({
    type: "Text",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    dimensions: { x: 0.6, y: 0.3, z: 0.01 },
    lineHeight: 0.12,
    text: "Hello\nthere!",
    billboardMode: "yaw",
    lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-Web
Type: object

The "Web" EntityType displays a browsable web page. Each user views their own copy of the web page: if one user navigates to another page on the entity, other users do not see the change; if a video is being played, users don't see it in sync. Internally, a Web entity is rendered as a non-repeating, upside down texture, so additional transformations may be necessary if you reference a Web entity texture by UUID. It has properties in addition to the common EntityProperties.

Properties

Name Type Summary
dimensions Vec3

The dimensions of the entity.

Default Value: 0.1,0.1,0.01

sourceUrl string

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

Default Value: ""

color Color

The color of the web surface. This color tints the web page displayed: the pixel colors on the web page are multiplied by the property color. For example, a value of { red: 255, green: 0, blue: 0 } lets only the red channel of pixels' colors through.

Default Value: 255,255,255

alpha number

The opacity of the web surface.

Default Value: 1

pulse Entities.Pulse

Color and alpha pulse.

Deprecated: This property is deprecated and will be removed.

faceCamera boolean

true if billboardMode is "yaw", false if it isn't. Setting this property to false sets the billboardMode to "none".

Deprecated: This property is deprecated and will be removed.

isFacingAvatar boolean

true if billboardMode is "full", false if it isn't. Setting this property to false sets the billboardMode to "none".

Deprecated: This property is deprecated and will be removed.

dpi number

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

Default Value: 30

scriptURL string

The URL of a JavaScript file to inject into the web page.

Default Value: ""

maxFPS number

The maximum update rate for the web content, in frames/second.

Default Value: 10

inputMode WebInputMode

The user input mode to use.

Default Value: "touch"

showKeyboardFocusHighlight boolean

true if the entity is highlighted when it has keyboard focus, false if it isn't.

Default Value: true

useBackground boolean

true if the web entity should have a background, false if the web entity's background should be transparent. The webpage must have CSS properties for transparency set on the background-color for this property to have an effect.

Default Value: true

userAgent string

The user agent for the web entity to use when visiting web pages. Default value: Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.113 Mobile Safari/537.36

Example

Create a Web entity displaying at 1920 x 1080 resolution.

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

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

Properties

Name Type Summary
dimensions Vec3

The dimensions of the volume in which the zone's lighting effects and avatar permissions have effect.

Default Value: 0.1,0.1,0.1

shapeType ShapeType

The shape of the volume in which the zone's lighting effects and avatar permissions have effect. Reverts to the default value if set to "none", or set to "compound" and compoundShapeURL is "".

Default Value: "box"

compoundShapeURL string

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

Default Value: ""

keyLightMode Entities.ComponentMode

Configures the key light in the zone.

Default Value: "inherit"

keyLight Entities.KeyLight

The key light properties of the zone.

ambientLightMode Entities.ComponentMode

Configures the ambient light in the zone.

Default Value: "inherit"

ambientLight Entities.AmbientLight

The ambient light properties of the zone.

skyboxMode Entities.ComponentMode

Configures the skybox displayed in the zone.

Default Value: "inherit"

skybox Entities.Skybox

The skybox properties of the zone.

hazeMode Entities.ComponentMode

Configures the haze in the zone.

Default Value: "inherit"

haze Entities.Haze

The haze properties of the zone.

bloomMode Entities.ComponentMode

Configures the bloom in the zone.

Default Value: "inherit"

bloom Entities.Bloom

The bloom properties of the zone.

flyingAllowed boolean

true if visitors can fly in the zone; false if they cannot. Only works for domain entities.

Default Value: true

ghostingAllowed boolean

true if visitors with avatar collisions turned off will not collide with content in the zone; false if visitors will always collide with content in the zone. Only works for domain entities.

Default Value: true

filterURL string

The URL of a JavaScript file that filters changes to properties of entities within the zone. It is periodically executed for each entity in the zone. It can, for example, be used to not allow changes to certain properties:

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

Default Value: ""

avatarPriority Entities.AvatarPriorityMode

Configures the priority of updates from avatars in the zone to other clients.

Default Value: "inherit"

screenshare Entities.ScreenshareMode

Configures a zone for screen-sharing.

Default Value: "inherit"

Example

Create a zone that casts a red key light along the x-axis.

var zone = Entities.addEntity({
    type: "Zone",
    position: MyAvatar.position,
    dimensions: { x: 100, y: 100, z: 100 },
    keyLightMode: "enabled",
    keyLight: {
        "color": { "red": 255, "green": 0, "blue": 0 },
        "direction": { "x": 1, "y": 0, "z": 0 }
    },
    lifetime: 300  // Delete after 5 minutes.
});
EntityPropertyInfo
Type: object

Information about an entity property.

Properties

Name Type Summary
propertyEnum number

The internal number of the property.

minimum string

The minimum numerical value the property may have, if available, otherwise "".

maximum string

The maximum numerical value the property may have, if available, otherwise "".

EntityType
Type: string

An entity may be one of the following types:

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, range 0.01.0. This fine-tunes shadows cast by the light, to prevent shadow acne and peter panning.

Default Value: 0.5

shadowMaxDistance number

The maximum distance from the camera position at which shadows will be computed, range 1.0250.0. Higher values cover more of the scene but with less precision.

Default Value: 40.0

Material
Type: object

A material used in a MaterialResource.

Properties

Name Type Summary
name string

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

Default Value: ""

model string

Different material models support different properties and rendering modes. Supported models are: "hifi_pbr", "hifi_shader_simple", and "vrm_mtoon".

Default Value: "hifi_pbr"

emissive ColorFloat | RGBS | string

The emissive color, i.e., the color that the material emits. A ColorFloat value is treated as sRGB and must have component values in the range 0.01.0. A RGBS value can be either RGB or sRGB. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr", "vrm_mtoon".

opacity number | string

The opacity, range 0.01.0. Set to "fallthrough" to fall through to the material below. Supported models: all.

Default Value: 1.0

unlit boolean | string

true if the material is unaffected by lighting, false if it is lit by the key light and local lights. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr".

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. Supported models: all.

roughness number | string

The roughness, range 0.01.0. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr".

metallic number | string

The metallicness, range 0.01.0. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr".

scattering number | string

The scattering, range 0.01.0. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr".

emissiveMap string

The URL of the emissive texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr", "vrm_mtoon".

albedoMap string

The URL of the albedo texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr", "vrm_mtoon".

opacityMap string

The URL of the opacity texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Set the value the same as the albedoMap value for transparency. Supported models: "hifi_pbr", "vrm_mtoon".

opacityMapMode string

The mode defining the interpretation of the opacity map. Values can be:

  • "OPACITY_MAP_OPAQUE" for ignoring the opacity map information.
  • "OPACITY_MAP_MASK" for using the opacityMap as a mask, where only the texel greater than opacityCutoff are visible and rendered opaque.
  • "OPACITY_MAP_BLEND" for using the opacityMap for alpha blending the material surface with the background.
Set to "fallthrough" to fall through to the material below. Supported models: all.
opacityCutoff number | string

The opacity cutoff threshold used to determine the opaque texels of the opacityMap when opacityMapMode is "OPACITY_MAP_MASK". Range 0.01.0. Set to "fallthrough" to fall through to the material below. Supported models: all.

cullFaceMode string

The mode defining which side of the geometry should be rendered. Values can be:

  • "CULL_NONE" to render both sides of the geometry.
  • "CULL_FRONT" to cull the front faces of the geometry.
  • "CULL_BACK" (the default) to cull the back faces of the geometry.
Set to "fallthrough" to fall through to the material below. Supported models: all.

Default Value: "CULL_BACK"

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. Supported models: "hifi_pbr".

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. Supported models: "hifi_pbr".

metallicMap string

The URL of the metallic texture image, or an entity ID. An entity ID may be that of an Image or Web entity. You can use this or specularMap, but not both. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr".

specularMap string

The URL of the specular texture image, or an entity ID. An entity ID may be that of an Image or Web entity. You can use this or metallicMap, but not both. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr".

normalMap string

The URL of the normal texture image, or an entity ID. An entity ID may be that of an Image or Web entity. You can use this or bumpMap, but not both. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr", "vrm_mtoon".

bumpMap string

The URL of the bump texture image, or an entity ID. An entity ID may be that of an Image or Web entity. You can use this or normalMap, but not both. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr", "vrm_mtoon".

occlusionMap string

The URL of the occlusion texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr".

scatteringMap string

The URL of the scattering texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Only used if normalMap or bumpMap is specified. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr".

lightMap string

The URL of the light map texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr".

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. Supported models: "hifi_pbr", "vrm_mtoon".

texCoordTransform1 Mat4 | string

The transform to use for occlusionMap and lightMap. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr", "vrm_mtoon".

lightmapParams string

Parameters for controlling how lightMap is used. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr".

Currently not used.

materialParams string

Parameters for controlling the material projection and repetition. Set to "fallthrough" to fall through to the material below. Supported models: "hifi_pbr", "vrm_mtoon".

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. Supported models: all.

Default Value: false

procedural ProceduralData

The definition of a procedural shader material. Supported models: "hifi_shader_simple".

shade ColorFloat | RGBS | string

The shade 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. Supported models: "vrm_mtoon".

shadeMap string

The URL of the shade texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Set to "fallthrough" to fall through to the material below. Supported models: "vrm_mtoon".

shadingShift number | string

The shading shift. Set to "fallthrough" to fall through to the material below. Supported models: "vrm_mtoon".

shadingShiftMap string

The URL of the shading shift texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Set to "fallthrough" to fall through to the material below. Supported models: "vrm_mtoon".

shadingToony number | string

The shading toony factor. Range 0.01.0. Set to "fallthrough" to fall through to the material below. Supported models: "vrm_mtoon".

matcap ColorFloat | RGBS | string

The matcap 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. Supported models: "vrm_mtoon".

matcapMap string

The URL of the matcap texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Set to "fallthrough" to fall through to the material below. Supported models: "vrm_mtoon".

parametricRim ColorFloat | RGBS | string

The rim 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. Supported models: "vrm_mtoon".

parametricRimFresnelPower number | string

The parametric rim fresnel exponent. Set to "fallthrough" to fall through to the material below. Supported models: "vrm_mtoon".

parametricRimLift number | string

The parametric rim lift factor. Set to "fallthrough" to fall through to the material below. Supported models: "vrm_mtoon".

rimMap string

The URL of the rim texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Set to "fallthrough" to fall through to the material below. Supported models: "vrm_mtoon".

rimLightingMix number | string

How much to mix between the rim color and normal lighting. Range 0.01.0. Set to "fallthrough" to fall through to the material below. Supported models: "vrm_mtoon".

outlineWidthMode string

The mode defining how to render the outline. Values can be:

  • "none" (the default) to not render an outline.
  • "worldCoordinates" to render an outline with a constant world size, i.e. its apparent size depends on distance.
  • "screenCoordinates" to render an outline with a constant screen size, i.e. its apparent size remains constant.
Set to "fallthrough" to fall through to the material below. Supported models: "vrm_mtoon".

Default Value: "none"

outlineWidth number | string

The width of the outline, in meters if outlineWidthMode is "worldCoordinates", or a ratio of the screen height if outlineWidthMode is "screenCoordinates". Set to "fallthrough" to fall through to the material below. Supported models: "vrm_mtoon".

outline ColorFloat | RGBS | string

The outline 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. Supported models: "vrm_mtoon".

uvAnimationMaskMap string

The URL of the UV animation mask texture image, or an entity ID. An entity ID may be that of an Image or Web entity. Set to "fallthrough" to fall through to the material below. Supported models: "vrm_mtoon".

uvAnimationScrollXSpeed number | string

The speed of the UV scrolling animation in the X dimension, in UV units per second. Set to "fallthrough" to fall through to the material below. Supported models: "vrm_mtoon".

uvAnimationScrollYSpeed number | string

The speed of the UV scrolling animation in the Y dimension, in UV units per second. Set to "fallthrough" to fall through to the material below. Supported models: "vrm_mtoon".

uvAnimationRotationSpeed number | string

The speed of the UV scrolling rotation about (0.5, 0.5), in radians per second. Set to "fallthrough" to fall through to the material below. Supported models: "vrm_mtoon".

MaterialResource
Type: object

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

Properties

Name Type Summary
materialVersion number

The version of the material. Currently not used.

Default Value: 1

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

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

NestableType
Type: string

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

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

TextAlignment
Type: string

A Text entity may use one of the following alignments:

ValueDescription
"left"Text is aligned to the left side.
"center"Text is centered.
"right"Text is aligned to the right side.
TextEffect
Type: string

A Text entity may use one of the following effects:

ValueDescription
"none"No effect.
"outline"An outline effect.
"outline fill"An outline effect, with fill.
"shadow"A shadow effect.
getMeshesCallback( meshes, success )
Type: function

Called when a Entities.getMeshes call is complete.

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

Parameters

Name Type Description
meshes Array.<MeshProxy>

If success is true, a MeshProxy per mesh in the Model or PolyVox entity; otherwise undefined.

success boolean

true if the Entities.getMeshes call was successful, false otherwise. The call may be unsuccessful if the requested entity could not be found.

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

Called when a Entities.getServerScriptStatus call is complete.

Parameters

Name Type Description
success boolean

true if the server entity script status could be obtained, otherwise false.

isRunning boolean

true if there is a server entity script running, otherwise false.

status string

"running" if there is a server entity script running, otherwise an error string.

errorInfo string

"" if there is a server entity script running, otherwise it may contain extra information on the error.

queryPropertyMetadataCallback( error, result )
Type: function

Called when a Entities.queryPropertyMetadata call is complete.

Parameters

Name Type Description
error string

undefined if there was no error, otherwise an error message.

result object

The metadata for the requested entity property if there was no error, otherwise undefined.

Method Details

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

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

Parameters

Name Type Description
brn Vec3

The bottom right near (minimum axes values) corner of the AA box.

dimensions Vec3

The dimensions of the AA box.

start Vec3

One end of the capsule.

end Vec3

The other end of the capsule.

radius number

The radius of the capsule.

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

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

Parameters

Name Type Description
actionType Entities.ActionType

The type of action.

entityID Uuid

The ID of the entity to add the action to.

arguments Entities.ActionArguments

Configures the action.

Example

Constrain a cube to move along a vertical line.

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

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

Adds a new domain, avatar, or local entity.

Parameters

Name Type Attributes Default Value Description
properties Entities.EntityProperties

The properties of the entity to create.

entityHostType Entities.EntityHostType <optional>
"domain"

The type of entity to create.

Example

Create a box domain entity in front of your avatar.

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

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

Parameters

Name Type Attributes Default Value Description
properties Entities.EntityProperties

The properties of the entity to create.

avatarEntity boolean <optional>
false

true to create an avatar entity, false to create a domain entity.

(static) appendPoint( entityID, point ) → {boolean}
Returns: true if the point was added to the line, otherwise false. The point may fail to be added if the entity does not exist, the entity is not a Line entity, the point is outside the entity's dimensions, or the maximum number of points has been reached.

Appends a point to a Line entity.

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

Parameters

Name Type Description
entityID Uuid

The ID of the Line entity.

point Vec3

The point to add to the line. The coordinates are relative to the entity's position.

Example

Append a point to a Line entity.

// Draw a line between two points.
var entity = Entities.addEntity({
    type: "Line",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -5 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 2, y: 2, z: 1 },
    linePoints: [
        { x: -1, y: 1, z: 0 },
        { x: 0, y: -1, z: 0 }
    ],
    color: { red: 255, green: 0, blue: 0 },
    lifetime: 300  // Delete after 5 minutes.
});

// Add a third point to create a "V".
Script.setTimeout(function () {
    Entities.appendPoint(entity, { x: 1, y: 1, z: 0 });
}, 50); // Wait for the entity to be created.
(static) callEntityClientMethod( clientSessionID, entityID, method, parametersopt )

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

Parameters

Name Type Attributes Default Value Description
clientSessionID Uuid

The session ID of the user to call the method in.

entityID Uuid

The ID of the entity to call the method in.

method string

The name of the method to call. The method is called with the entity ID as the first parameter and the parameters value as the second parameter.

parameters Array.<string> <optional>
[]

The additional parameters to call the specified method with.

Example

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

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

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

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

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

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

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

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

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

Parameters

Name Type Attributes Default Value Description
entityID Uuid

The ID of the entity to call the method in.

method string

The name of the method to call. The method is called with the entity ID as the first parameter and the parameters value as the second parameter.

parameters Array.<string> <optional>
[]

The additional parameters to call the specified method with.

Example

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

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

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

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

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

Parameters

Name Type Attributes Default Value Description
entityID Uuid

The ID of the entity to call the method in.

method string

The name of the method to call. The method is called with the entity ID as the first parameter and the parameters value as the second parameter.

parameters Array.<string> <optional>
[]

The additional parameters to call the specified method with.

Example

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

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

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

// Interface script call to the server entity script.
Script.setTimeout(function () {
    Entities.callEntityServerMethod(entityID, "entityMethod", ["hello", 12]);
}, 1000); // Wait for the entity to be created.
(static) canAdjustLocks( ) → {boolean}
Returns: true if the domain server will allow the script to change the locked property of entities, otherwise false.

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

Example

Lock an entity if you can.

if (Entities.canAdjustLocks()) {
    Entities.editEntity(entityID, { locked: true });
} else {
    Window.alert("You do not have the permissions to set an entity locked!");
}
(static) canGetAndSetPrivateUserData( ) → {boolean}
Returns: true if the domain server will allow the script to get and set the privateUserData property of entities, otherwise false.

Checks whether or not the script can get and set the privateUserData property of entities.

(static) canReplaceContent( ) → {boolean}
Returns: true if the domain server will allow the script to replace the domain's content set, otherwise false.

Checks whether or not the script can replace the domain's content set.

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

Checks whether or not the script can rez (create) new entities in the domain.

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

Checks whether or not the script can rez avatar entities.

(static) 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) canWriteAssets( ) → {boolean}
Returns: true if the domain server will allow the script to make changes to the asset server's assets, otherwise false.

Checks whether or not the script can make changes to the asset server's assets.

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

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

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

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

Parameters

Name Type Description
entityID Uuid

The ID of the entity to clone.

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

Deletes an action from an entity.

Parameters

Name Type Description
entityID Uuid

The ID of entity to delete the action from.

actionID Uuid

The ID of the action to delete.

(static) deleteEntity( entityID )

Deletes an entity.

Parameters

Name Type Description
entityID Uuid

The ID of the entity to delete.

Example

Delete an entity a few seconds after creating it.

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

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

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

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

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

Parameters

Name Type Description
entityID Uuid

The ID of the entity to edit.

properties Entities.EntityProperties

The new property values.

Example

Change the color of an entity.

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

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

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

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

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

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

Parameters

Name Type Description
entityID Uuid

The ID of the Web entity to send the message to.

message string

The message to send.

Example

Exchange messages with a Web entity.

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

        EventBridge.scriptEventReceived.connect(onScriptEventReceived);

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

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

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

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

Entities.webEventReceived.connect(onWebEventReceived);
(static) findClosestEntity( center, radius ) → {Uuid}
Returns: The ID of the entity that is closest to the center and within the radius, if there is one, otherwise null.

Finds the domain or avatar entity with a position closest to a specified point and within a specified radius.

Parameters

Name Type Description
center Vec3

The point about which to search.

radius number

The radius within which to search.

Example

Find the closest entity within 10m of your avatar.

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

Finds all domain and avatar entities that intersect a sphere.

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

Parameters

Name Type Description
center Vec3

The point about which to search.

radius number

The radius within which to search.

Example

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

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

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

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

Parameters

Name Type Attributes Default Value Description
entityName string

The name of the entity to search for.

center Vec3

The point about which to search.

radius number

The radius within which to search.

caseSensitive boolean <optional>
false

true if the search is case-sensitive, false if it is case-insensitive.

Example

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

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

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

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

Parameters

Name Type Description
entityType Entities.EntityType

The type of entity to search for.

center Vec3

The point about which to search.

radius number

The radius within which to search.

Example

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

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

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

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

Parameters

Name Type Description
corner Vec3

The corner of the search AA box with minimum co-ordinate values.

dimensions Vec3

The dimensions of the search AA box.

(static) findEntitiesInFrustum( frustum ) → {Array.<Uuid>}
Returns: An array of entity IDs whose axis-aligned boxes intersect the search frustum. The array is empty if no entities could be found.

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

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

Parameters

Name Type Description
frustum ViewFrustum

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

Example

Report the number of entities in view.

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

Finds the first avatar or domain entity intersected by a PickRay. Light and Zone entities are not intersected unless they've been configured as pickable using setLightsArePickable and setZonesArePickable, respectively.

Parameters

Name Type Attributes Default Value Description
pickRay PickRay

The pick ray to use for finding entities.

precisionPicking boolean <optional>
false

true to pick against precise meshes, false to pick against coarse meshes. If true and the intersected entity is a Model entity, the result's extraInfo property includes more information than it otherwise would.

entitiesToInclude Array.<Uuid> <optional>
[]

If not empty, then the search is restricted to these entities.

entitiesToDiscard Array.<Uuid> <optional>
[]

Entities to ignore during the search.

visibleOnly boolean <optional>
false

true if only entities that are visible are searched for, false if their visibility doesn't matter.

collideableOnly boolean <optional>
false

true if only entities that are not collisionless are searched, false if their collideability doesn't matter.

Example

Find the entity directly in front of your avatar.

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

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

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

Parameters

Name Type Description
entityID Uuid

The ID of the entity.

jointIndex number

The integer index of the joint.

Example

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

entityID = Entities.addEntity({
    type: "Model",
    modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    rotation: MyAvatar.orientation,
    lifetime: 300  // Delete after 5 minutes.
});

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

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

Parameters

Name Type Description
entityID Uuid

The ID of the entity.

jointIndex number

The integer index of the joint.

(static) getActionArguments( entityID, actionID ) → {Entities.ActionArguments}
Returns: The arguments of the action if found, otherwise an empty object.

Gets the arguments of an action.

Parameters

Name Type Description
entityID Uuid

The ID of the entity with the action.

actionID Uuid

The ID of the action to get the arguments of.

(static) getActionIDs( entityID ) → {Array.<Uuid>}
Returns: The action IDs if any are found, otherwise an empty array.

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

Parameters

Name Type Description
entityID Uuid

The entity to get the action IDs for.

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

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

Parameters

Name Type Description
parentID Uuid

The ID of the entity or avatar to get the children IDs of.

Example

Report the children of an entity.

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

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

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

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

Parameters

Name Type Description
parentID Uuid

The ID of the entity or avatar to get the children IDs of.

jointIndex number

Integer number of the model joint to get the children IDs of.

Example

Report the children of your avatar's right hand.

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

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

Script.setTimeout(function () { // Wait for the entity to be created before editing.
    Entities.editEntity(root, {
        parentID: MyAvatar.sessionUUID,
        parentJointIndex: MyAvatar.getJointIndex("RightHand")
    });

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

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

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

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

Parameters

Name Type Description
entityID Uuid

The ID of the entity.

Example

Position and rotation in an entity's local transform.

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

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

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

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

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

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

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

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

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

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

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

Parameters

Name Type Description
id Uuid

The ID of the entity to get the script object for.

Example

Exchange messages with a Web entity.

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

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

var webEntityObject;

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

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

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

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

Gets an entity's property values.

Parameters

Name Type Attributes Default Value Description
entityID Uuid

The ID of the entity to get the properties of.

desiredProperties string | Array.<string> <optional>
[]

The name or names of the properties to get. For properties that are objects (e.g., the "keyLight" property), use the property and subproperty names in dot notation (e.g., "keyLight.color").

Example

Report the color of a new box entity.

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

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

Parameters

Name Type Description
entityID Uuid

The ID of the entity.

Example

Position and rotation in an entity's world transform.

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

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

var transform = Entities.getEntityTransform(entityID);
print("Transform: " + JSON.stringify(transform));
print("Translation: " + JSON.stringify(Mat4.extractTranslation(transform)));  // Same as position.
print("Rotation: " + JSON.stringify(Mat4.extractRotation(transform)));  // Same as orientation.
print("Scale: " + JSON.stringify(Mat4.extractScale(transform)));  // { x: 1, y: 1, z: 1 }
(static) getEntityType( id ) → {Entities.EntityType}
Returns: The type of the entity.

Gets an entity's type.

Parameters

Name Type Description
id Uuid

The ID of the entity to get the type of.

(static) getJointIndex( entityID, name ) → {number}
Returns: The integer index of the joint if the entity is a Model entity, the entity is loaded, and the joint is present; otherwise -1. The joint indexes are in order per getJointNames.

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

Parameters

Name Type Description
entityID Uuid

The ID of the entity.

name string

The name of the joint.

Example

Report the index of a model's head joint.

entityID = Entities.addEntity({
    type: "Model",
    modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    rotation: MyAvatar.orientation,
    lifetime: 300  // Delete after 5 minutes.
});

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

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

Parameters

Name Type Description
entityID Uuid

The ID of the Model entity.

Example

Report a model's joint names.

entityID = Entities.addEntity({
    type: "Model",
    modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    rotation: MyAvatar.orientation,
    lifetime: 300  // Delete after 5 minutes.
});

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

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

Parameters

Name Type Description
entityID Uuid

The ID of the entity.

index number

The integer index of the joint.

(static) getKeyboardFocusEntity( ) → {Uuid}
Returns: The ID of the Web entity that has focus, if any, otherwise null.

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

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

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

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

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

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

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

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

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

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

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

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

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

(static) 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) 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) getLightsArePickable( ) → {boolean}
Returns: true if ray picks intersect the bounding box of Light entities, otherwise false.

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

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

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

Parameters

Name Type Description
entityID Uuid

The ID of the entity.

jointIndex number

The integer index of the joint.

Example

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

entityID = Entities.addEntity({
    type: "Model",
    modelURL: "https://github.com/highfidelity/hifi-api-docs/blob/master/docs/blue_suited.fbx?raw=true",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
    rotation: MyAvatar.orientation,
    lifetime: 300  // Delete after 5 minutes.
});

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

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

Parameters

Name Type Description
entityID Uuid

The ID of the entity.

jointIndex number

The integer index of the joint.

(static) getMeshes( entityID, callback )

Gets the meshes in a Model or PolyVox entity.

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

Parameters

Name Type Description
entityID Uuid

The ID of the Model or PolyVox entity to get the meshes of.

callback Entities~getMeshesCallback

The function to call upon completion.

(static) getMultipleEntityProperties( entityIDs, desiredPropertiesopt ) → {Array.<Entities.EntityProperties>}
Returns: The specified properties of each entity for each entity that can be found. If none of the entities can be found, then an empty array is returned. If no properties are specified, then all properties are returned.

Gets the properties of multiple entities.

Parameters

Name Type Attributes Default Value Description
entityIDs Array.<Uuid>

The IDs of the entities to get the properties of.

desiredProperties Array.<string> | string <optional>
[]

The name or names of the properties to get. For properties that are objects (e.g., the "keyLight" property), use the property and subproperty names in dot notation (e.g., "keyLight.color"). Getting all subproperties with the name of an object is currently not supported (e.g., passing the "keyLight" property only).

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) 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) 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) 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) 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) 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) 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) 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) voxelCoordsToLocalCoords( entityID, voxelCoords ) → {Vec3}
Returns: The local coordinates of the voxelCoords if the entityID is a PolyVox entity, otherwise Vec3.ZERO.

Converts voxel coordinates in a PolyVox entity to local coordinates. Local coordinates are relative to the minimum axes value corner of the entity, with the scale being the same as world coordinates. Voxel coordinates are relative to the minimum axes values corner of the entity, with a scale of Vec3.ONE being the dimensions of each voxel.

Parameters

Name Type Description
entityID Uuid

The ID of the PolyVox entity.

voxelCoords Vec3

The voxel coordinates. The value may be fractional and outside the entity's bounding box.

Example

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

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

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

Parameters

Name Type Description
entityID Uuid

The ID of the PolyVox entity.

voxelCoords Vec3

The voxel coordinates. May be fractional and outside the entity's bounding box.

Example

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

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

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

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

Parameters

Name Type Description
entityID Uuid

The ID of the entity.

(static) worldCoordsToVoxelCoords( entityID, worldCoords ) → {Vec3}
Returns: The voxel coordinates of the worldCoords if the entityID is a PolyVox entity, otherwise Vec3.ZERO. The value may be fractional and outside the entity's bounding box.

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

Parameters

Name Type Description
entityID Uuid

The ID of the PolyVox entity.

worldCoords Vec3

The world coordinates. The value may be outside the entity's bounding box.

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

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

Parameters

Name Type Attributes Default Value Description
worldAngularVelocity Vec3

The world Euler angular velocity to convert. (Can be in any unit, e.g., deg/s or rad/s.)

parentID Uuid

The avatar or entity that the local coordinates are based on.

parentJointIndex number <optional>
-1

The joint in the avatar or entity that the local coordinates are based on. If -1 then no joint is used and the local coordinates are based solely on the avatar or entity.

scalesWithParent boolean <optional>
false

Not used in the calculation.

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

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

Parameters

Name Type Attributes Default Value Description
worldDimensions Vec3

The world dimensions to convert.

parentID Uuid

The avatar or entity that the local coordinates are based on.

parentJointIndex number <optional>
-1

Not used in the calculation.

scalesWithParent boolean <optional>
false

true to scale the local dimensions per the parent's scale, false for the local dimensions to be at world scale.

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

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

Parameters

Name Type Attributes Default Value Description
worldPosition Vec3

The world position to convert.

parentID Uuid

The avatar or entity that the local coordinates are based on.

parentJointIndex number <optional>
-1

The joint in the avatar or entity that the local coordinates are based on. If -1 then no joint is used and the local coordinates are based solely on the avatar or entity.

scalesWithParent boolean <optional>
false

true to scale the local position per the parent's scale, false for the local position to be at world scale.

Example

Report the local coordinates of an entity parented to another.

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

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

var localPosition = Entities.worldToLocalPosition(childPosition, parentEntity);
print("Local position: " + JSON.stringify(localPosition));  // 0, 1, 0.
localPosition = Entities.getEntityProperties(childEntity, "localPosition").localPosition;
print("Local position: " + JSON.stringify(localPosition));  // The same.
(static) worldToLocalRotation( worldRotation, parentID, parentJointIndexopt, scalesWithParentopt ) → {Quat}
Returns: The rotation converted to local coordinates if successful, otherwise Quat.IDENTITY.

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

Parameters

Name Type Attributes Default Value Description
worldRotation Quat

The world rotation to convert.

parentID Uuid

The avatar or entity that the local coordinates are based on.

parentJointIndex number <optional>
-1

The joint in the avatar or entity that the local coordinates are based on. If -1 then no joint is used and the local coordinates are based solely on the avatar or entity.

scalesWithParent boolean <optional>
false

Not used in the calculation.

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

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

Parameters

Name Type Attributes Default Value Description
worldVelocity Vec3

The world velocity to convert.

parentID Uuid

The avatar or entity that the local coordinates are based on.

parentJointIndex number <optional>
-1

The joint in the avatar or entity that the local coordinates are based on. If -1 then no joint is used and the local coordinates are based solely on the avatar or entity.

scalesWithParent boolean <optional>
false

true to scale the local velocity per the parent's scale, false for the local velocity to be at world scale.

Signal Details

addingEntity( entityID )
Returns: Signal

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

Parameters

Name Type Description
entityID Uuid

The ID of the entity added.

Example

Report when an entity is added.

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

Triggered when a "wearable" entity is added to Interface's local in-memory tree of entities it knows about, for example when adding a "wearable" to your avatar.

Parameters

Name Type Description
entityID Uuid

The ID of the "wearable" entity added.

Example

Report when a "wearable" entity is added.

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

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

Parameters

Name Type Description
canAdjustLocks boolean

true if the script can change the locked property of an entity, false if it can't.

Example

Report when your ability to change locks changes.

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

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

Parameters

Name Type Description
canGetAndSetPrivateUserData boolean

true if the script can change the privateUserData property of an entity, false if it can't.

canRezAvatarEntitiesChanged( canRezAvatarEntities )
Returns: Signal

Triggered when your ability to use avatar entities is changed.

Parameters

Name Type Description
canRezAvatarEntities boolean

true if the script can change edit avatar entities, false if it can't.

canRezChanged( canRez )
Returns: Signal

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

Parameters

Name Type Description
canRez boolean

true if the script can rez (create) entities, false if it can't.

canRezTmpChanged( canRezTmp )
Returns: Signal

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

Parameters

Name Type Description
canRezTmp boolean

true if the script can rez (create) temporary entities, false if it can't.

canWriteAssetsChanged( canWriteAssets )
Returns: Signal

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

Parameters

Name Type Description
canWriteAssets boolean

true if the script can change the asset server's assets, false if it can't.

clearingEntities( )
Returns: Signal

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

Example

Report when Interfaces's entity tree is cleared.

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

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

See also, Entity Methods and Script.addEventHandler.

Parameters

Name Type Description
entityID Uuid

The ID of the entity that was clicked on.

event PointerEvent

Details of the event.

Example

Compare clickDownOnEntity signal and entity script method.

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

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

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

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

See also, Entity Methods and Script.addEventHandler.

Parameters

Name Type Description
entityID Uuid

The ID of the entity that was originally clicked.

event PointerEvent

Details of the event.

collisionWithEntity( idA, idB, collision )
Returns: Signal

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

See also, Entity Methods and Script.addEventHandler.

Parameters

Name Type Description
idA Uuid

The ID of one entity in the collision. For an entity script, this is the ID of the entity containing the script.

idB Uuid

The ID of the other entity in the collision.

collision Collision

The details of the collision.

Example

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

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

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

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

Triggered when an entity is deleted.

Parameters

Name Type Description
entityID Uuid

The ID of the entity deleted.

Example

Report when an entity is deleted.

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

Triggered when a "wearable" entity is deleted, for example when removing a "wearable" from your avatar.

Parameters

Name Type Description
entityID Uuid

The ID of the "wearable" entity deleted.

Example

Report when a "wearable" entity is deleted.

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

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

See also, Entity Methods and Script.addEventHandler.

Parameters

Name Type Description
entityID Uuid

The ID of the entity that the avatar entered.

holdingClickOnEntity( entityID, event )
Returns: Signal

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

See also, Entity Methods and Script.addEventHandler.

Parameters

Name Type Description
entityID Uuid

The ID of the entity that was originally clicked.

event PointerEvent

Details of the event.

hoverEnterEntity( entityID, event )
Returns: Signal

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

See also, Entity Methods and Script.addEventHandler.

Parameters

Name Type Description
entityID Uuid

The ID of the entity that is being hovered.

event PointerEvent

Details of the event.

hoverLeaveEntity( entityID, event )
Returns: Signal

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

See also, Entity Methods and Script.addEventHandler.

Parameters

Name Type Description
entityID Uuid

The ID of the entity that was being hovered.

event PointerEvent

Details of the event.

hoverOverEntity( entityID, event )
Returns: Signal

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

See also, Entity Methods and Script.addEventHandler.

Parameters

Name Type Description
entityID Uuid

The ID of the entity that is being hovered.

event PointerEvent

Details of the event.

leaveEntity( entityID )
Returns: Signal

Triggered when an avatar leaves an entity.

See also, Entity Methods and Script.addEventHandler.

Parameters

Name Type Description
entityID Uuid

The ID of the entity that the avatar left.

mouseDoublePressOffEntity( event )
Returns: Signal

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

Parameters

Name Type Description
event PointerEvent

Details of the event.

mouseDoublePressOnEntity( entityID, event )
Returns: Signal

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

Parameters

Name Type Description
entityID Uuid

The ID of the entity that was double-pressed on.

event PointerEvent

Details of the event.

mouseMoveOnEntity( entityID, event )
Returns: Signal

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

See also, Entity Methods and Script.addEventHandler.

Parameters

Name Type Description
entityID Uuid

The ID of the entity that was moved on.

event PointerEvent

Details of the event.

mousePressOffEntity( event )
Returns: Signal

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

Parameters

Name Type Description
event PointerEvent

Details of the event.

mousePressOnEntity( entityID, event )
Returns: Signal

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

See also, Entity Methods and Script.addEventHandler.

Parameters

Name Type Description
entityID Uuid

The ID of the entity that was pressed on.

event PointerEvent

Details of the event.

Example

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

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

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

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

See also, Entity Methods and Script.addEventHandler.

Parameters

Name Type Description
entityID Uuid

The ID of the entity that was originally pressed.

event PointerEvent

Details of the event.

unload( entityID )
Returns: Signal

Triggered when the script terminates for a user.

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

Supported Script Types: Client Entity Scripts • Server Entity Scripts

Parameters

Name Type Description
entityID Uuid

The ID of the entity that the script is running in.

webEventReceived( entityID, message )
Returns: Signal

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

EventBridge.emitWebEvent(message);

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

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

Parameters

Name Type Description
entityID Uuid

The ID of the Web entity that the message was received from.

message string

The message received.