Entities

Available in: Interface Scripts Client Entity Scripts Server Entity Scripts Assignment Client Scripts

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

Signals

Type Definitions

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

Methods

AABoxIntersectsCapsule(brn, dimensions, start, end, radius) → {boolean}
Check whether an axis-aligned box and a capsule intersect.
Parameters:
Name Type Description
brn Vec3 The bottom right near (minimum axes values) corner of the AA box.
dimensions Vec3 The dimensions of the AA box.
start Vec3 One end of the capsule.
end Vec3 The other end of the capsule.
radius number The radiues of the capsule.
Returns:
true if the AA box and capsule intersect, otherwise false.
Type: boolean
addAction(actionType, entityID, arguments) → {Uuid}
Add an action to an entity. An action is registered with the physics engine and is applied every physics simulation step. Any entity may have more than one action associated with it, but only as many as will fit in an entity's actionData property.
Parameters:
Name Type Description
actionType Entities.ActionType The type of action.
entityID Uuid The ID of the entity to add the action to.
arguments Entities.ActionArguments Configure the action.
Returns:
The ID of the action added if successfully added, otherwise null.
Type: Uuid
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
});
addEntity(properties, clientOnlyopt) → {Uuid}
Add a new entity with specified properties.
Parameters:
Name Type Attributes Default Description
properties Entities.EntityProperties The properties of the entity to create.
clientOnly boolean <optional>
false If true, or if clientOnly is set true in the properties, the entity is created as an avatar entity; otherwise it is created on the server. An avatar entity follows you to each domain you visit, rendering at the same world coordinates unless it's parented to your avatar.
Returns:
The ID of the entity if successfully created, otherwise Uuid.NULL.
Type: Uuid
Example

Create a box entity in front of your avatar.

var entityID = Entities.addEntity({
  type: "Box",
  position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
  rotation: MyAvatar.orientation,
  dimensions: { x: 0.5, y: 0.5, z: 0.5 }
});
print("Entity created: " + entityID);
appendPoint(entityID, point) → {boolean}
Append a point to a Line entity.
Parameters:
Name Type Description
entityID Uuid The ID of the Line entity.
point Vec3 The point to add to the line. The coordinates are relative to the entity's position.
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.
Type: boolean
Example

Append a point to a Line entity.

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

// Add a third point to create a "V".
Entities.appendPoint(entity, { x: 1, y: 1, z: 0 });
callEntityClientMethod(clientSessionID, entityID, method, parametersopt)
Call a method in a specific user's client entity script from a server entity script. The entity script method must be exposed as a property in the target client entity script.
Parameters:
Name Type Attributes Default Description
clientSessionID Uuid The session ID of the user to call the method in.
entityID Uuid The ID of the entity to call the method in.
method string The name of the method to call.
parameters Array.<string> <optional>
[] The parameters to call the specified method with.
callEntityMethod(entityID, method, parametersopt)
Call a method in a client entity script from a client script or client entity script, or call a method in a server entity script from a server entity script. The entity script method must be exposed as a property in the target client entity script. Additionally, if calling a server entity script, the server entity script must include the method's name in an exposed property called remotelyCallable that is an array of method names that can be called.
Parameters:
Name Type Attributes Default Description
entityID Uuid The ID of the entity to call the method in.
method string The name of the method to call.
parameters Array.<string> <optional>
[] The parameters to call the specified method with.
callEntityServerMethod(entityID, method, parametersopt)
Call a method in a server entity script from a client script or client entity script. The entity script method must be exposed as a property in the target server entity script. Additionally, the target server entity script must include the method's name in an exposed property called remotelyCallable that is an array of method names that can be called.
Parameters:
Name Type Attributes Default Description
entityID Uuid The ID of the entity to call the method in.
method string The name of the method to call.
parameters Array.<string> <optional>
[] The parameters to call the specified method with.
canAdjustLocks() → {boolean}
Check whether or not you can change the locked property of entities. Locked entities have their locked property set to true and cannot be edited or deleted. Whether or not you can change entities' locked properties is configured in the domain server's permissions.
Returns:
true if the client can change the locked property of entities, otherwise false.
Type: boolean
Example

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

if (Entities.canAdjustLocks()) {
  Entities.editEntity(entityID, { locked: true });
} else {
  Window.alert("You do not have the permissions to set an entity locked!");
}
canReplaceContent() → {boolean}
Check whether or not you can replace the domain's content set.
Returns:
true if the domain server will allow the script to replace the domain's content set, otherwise false.
Type: boolean
canRez() → {boolean}
Check whether or not you can rez (create) new entities in the domain.
Returns:
true if the domain server will allow the script to rez (create) new entities, otherwise false.
Type: boolean
canRezCertified() → {boolean}
Check whether or not you can rez (create) new certified entities in the domain. Certified entities are entities that have PoP certificates.
Returns:
true if the domain server will allow the script to rez (create) new certified entities, otherwise false.
Type: boolean
canRezTmp() → {boolean}
Check whether or not you can rez (create) new temporary entities in the domain. Temporary entities are entities with a finite lifetime property value set.
Returns:
true if the domain server will allow the script to rez (create) new temporary entities, otherwise false.
Type: boolean
canRezTmpCertified() → {boolean}
Check whether or not you can rez (create) new temporary certified entities in the domain. Temporary entities are entities with a finite lifetime property value set. Certified entities are entities that have PoP certificates.
Returns:
true if the domain server will allow the script to rez (create) new temporary certified entities, otherwise false.
Type: boolean
canWriteAssets() → {boolean}
Check whether or not you can make changes to the asset server's assets.
Returns:
true if the domain server will allow the script to make changes to the asset server's assets, otherwise false.
Type: boolean
cloneEntity(entityID) → {Uuid}
Create a clone of an entity. A clone can be created by a client that doesn't have rez permissions in the current domain. The entity must have its cloneable property set to true. The clone has a modified name, other properties set per its clone related-properties, and its clone-related properties are set to defaults.
Parameters:
Name Type Description
entityID Uuid The ID of the entity to clone.
Returns:
The ID of the new entity if successfully cloned, otherwise Uuid.NULL.
Type: Uuid
deleteAction(entityID, actionID) → {boolean}
Delete an action from an entity.
Parameters:
Name Type Description
entityID Uuid The ID of entity to delete the action from.
actionID Uuid The ID of the action to delete.
Returns:
true if the update was successful, otherwise false.
Type: boolean
deleteEntity(entityID)
Delete an entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity to delete.
Example

Delete an entity a few seconds after creating it.

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

Script.setTimeout(function () {
  Entities.deleteEntity(entityID);
}, 3000);
dumpTree()
Dumps debug information about all entities in Interface's local in-memory tree of entities it knows about — domain and client-only — to the program log.
editEntity(entityID, properties) → {Uuid}
Update an entity with specified properties.
Parameters:
Name Type Description
entityID Uuid The ID of the entity to edit.
properties Entities.EntityProperties The properties to update the entity with.
Returns:
The ID of the entity if the edit was successful, otherwise null.
Type: Uuid
Example

Change the color of an entity.

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

Entities.editEntity(entityID, {
  color: { red: 255, green: 0, blue: 0 }
});
properties = Entities.getEntityProperties(entityID, ["color"]);
print("Entity color: " + JSON.stringify(properties.color));
emitScriptEvent(entityID, message)
Send a script event over a Web entity's EventBridge to the Web page's scripts.
Parameters:
Name Type Description
entityID Uuid The ID of the Web entity.
message string The message to send.
To Do:
  • This function is currently not implemented.
findClosestEntity(center, radius) → {Uuid}
Find the 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.
Returns:
The ID of the entity that is closest to the center and within the radius if there is one, otherwise null.
Type: Uuid
Example

Find the closest entity within 10m of your avatar.

var entityID = Entities.findClosestEntity(MyAvatar.position, 10);
print("Closest entity: " + entityID);
findEntities(center, radius) → {Array.<Uuid>}
Find all entities that intersect a sphere defined by a center point and radius.
Parameters:
Name Type Description
center Vec3 The point about which to search.
radius number The radius within which to search.
Returns:
An array of entity IDs that were found that intersect the search sphere. The array is empty if no entities could be found.
Type: Array.< Uuid>
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);
findEntitiesByName(entityName, center, radius, caseSensitiveopt) → {Array.<Uuid>}
Find all entities of a particular name that intersect a sphere defined by a center point and radius.
Parameters:
Name Type Attributes Default Description
entityName string The name of the entity to search for.
center Vec3 The point about which to search.
radius number The radius within which to search.
caseSensitive boolean <optional>
false If true then the search is case-sensitive.
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.
Type: Array.< Uuid>
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);
findEntitiesByType(entityType, center, radius) → {Array.<Uuid>}
Find all entities of a particular type that intersect a sphere defined by a center point and radius.
Parameters:
Name Type Description
entityType Entities.EntityType The type of entity to search for.
center Vec3 The point about which to search.
radius number The radius within which to search.
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.
Type: Array.< Uuid>
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);
findEntitiesInBox(corner, dimensions) → {Array.<Uuid>}
Find all entities whose axis-aligned boxes intersect a search axis-aligned box defined by its minimum coordinates corner and dimensions.
Parameters:
Name Type Description
corner Vec3 The corner of the search AA box with minimum co-ordinate values.
dimensions Vec3 The dimensions of the search AA box.
Returns:
An array of entity IDs whose AA boxes intersect the search AA box. The array is empty if no entities could be found.
Type: Array.< Uuid>
findEntitiesInFrustum(frustum) → {Array.<Uuid>}
Find all entities whose axis-aligned boxes intersect a search frustum.
Parameters:
Name Type Description
frustum ViewFrustum The frustum to search in. The position, orientation, projection, and centerRadius properties must be specified.
Returns:
An array of entity IDs axis-aligned boxes intersect the frustum. The array is empty if no entities could be found.
Type: Array.< Uuid>
Example

Report the number of entities in view.

var entityIDs = Entities.findEntitiesInFrustum(Camera.frustum);
print("Number of entities in view: " + entityIDs.length);
findRayIntersection(pickRay, precisionPickingopt, entitiesToIncludeopt, entitiesToDiscard opt, visibleOnlyopt, collideableOnlyopt) → {Entities.RayToEntityIntersectionResult}
Find the first 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 Description
pickRay PickRay The PickRay to use for finding entities.
precisionPicking boolean <optional>
false If true and the intersected entity is a Model entity, the result's extraInfo property includes more information than it otherwise would.
entitiesToInclude Array.<Uuid> <optional>
[] If not empty then the search is restricted to these entities.
entitiesToDiscard Array.<Uuid> <optional>
[] Entities to ignore during the search.
visibleOnly boolean <optional>
false If true then only entities that are visible are searched.
collideableOnly boolean <optional>
false If true then only entities that are not collisionless are searched.
Returns:
The result of the search for the first intersected entity.
Type: Entities.RayToEntityIntersectionResult
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.");
}
findRayIntersectionBlocking(pickRay, precisionPickingopt, entitiesToIncludeopt, entitiesToDiscard opt)
Find the first entity intersected by a PickRay. Light and Zone entities are not intersected unless they've been configured as pickable using setLightsArePickable and setZonesArePickable, respectively.
This is a synonym for findRayIntersection.
Parameters:
Name Type Attributes Default Description
pickRay PickRay The PickRay to use for finding entities.
precisionPicking boolean <optional>
false If true and the intersected entity is a Model entity, the result's extraInfo property includes more information than it otherwise would.
entitiesToInclude Array.<Uuid> <optional>
[] If not empty then the search is restricted to these entities.
entitiesToDiscard Array.<Uuid> <optional>
[] Entities to ignore during the search.
Deprecated:
This function is deprecated and will soon be removed. Use findRayIntersection instead; it blocks and performs the same function.
getAbsoluteJointRotationInObjectFrame(entityID, jointIndex) → {Quat}
Get the translation of a joint in a Model entity relative to the entity's position and orientation.
Parameters:
Name Type Description
entityID Uuid The ID of the entity.
jointIndex number The integer index of the joint.
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.
Type: Quat
Example

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

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

Script.setTimeout(function () {
  // Joint data aren't available until after the model has loaded.
  var index = Entities.getJointIndex(entityID, "LeftHand");
  var localRotation = Entities.getLocalJointRotation(entityID, index);
  var absoluteRotation = Entities.getAbsoluteJointRotationInObjectFrame(entityID, index);
  print("Left hand local rotation: " + JSON.stringify(Quat.safeEulerAngles(localRotation)));
  print("Left hand absolute rotation: " + JSON.stringify(Quat.safeEulerAngles(absoluteRotation)));
}, 2000);
getAbsoluteJointTranslationInObjectFrame(entityID, jointIndex) → {Vec3}
Get the translation of a joint in a Model entity relative to the entity's position and orientation.
Parameters:
Name Type Description
entityID Uuid The ID of the entity.
jointIndex number The integer index of the joint.
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.
Type: Vec3
getActionArguments(entityID, actionID) → {Entities.ActionArguments}
Get the arguments of an action.
Parameters:
Name Type Description
entityID Uuid The ID of the entity with the action.
actionID Uuid The ID of the action to get the arguments of.
Returns:
The arguments of the requested action if found, otherwise an empty object.
Type: Entities.ActionArguments
getActionIDs(entityID) → {Array.<Uuid>}
Get the IDs of the actions that are associated with an entity.
Parameters:
Name Type Description
entityID Uuid The entity to get the action IDs for.
Returns:
An array of action IDs if any are found, otherwise an empty array.
Type: Array.< Uuid>
getChildrenIDs(parentID) → {Array.<Uuid>}
Get the IDs of entities, overlays, and avatars that are directly parented to an entity, overlay, or avatar model. Recurse on the IDs returned by the function to get all descendants of an entity, overlay, or avatar.
Parameters:
Name Type Description
parentID Uuid The ID of the entity, overlay, or avatar to get the children IDs of.
Returns:
An array of entity, overlay, and avatar IDs that are parented directly to the parentID entity, overlay, or avatar. Does not include children's children, etc. The array is empty if no children can be found or parentID cannot be found.
Type: Array.< Uuid>
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.
getChildrenIDsOfJoint(parentID, jointIndex) → {Array.<Uuid>}
Get the IDs of entities, overlays, and avatars that are directly parented to an entity, overlay, or avatar model's joint.
Parameters:
Name Type Description
parentID Uuid The ID of the entity, overlay, or avatar to get the children IDs of.
jointIndex number Integer number of the model joint to get the children IDs of.
Returns:
An array of entity, overlay, and avatar IDs that are parented directly to the parentID entity, overlay, 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.
Type: Array.< Uuid>
Example

Report the children of your avatar's right hand.

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

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

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

var children = Entities.getChildrenIDsOfJoint(MyAvatar.sessionUUID, MyAvatar.getJointIndex("RightHand"));
print("Children of hand: " + JSON.stringify(children));  // Only the root entity.
getDrawZoneBoundaries() → {boolean}
Get whether or not Zone entities' boundaries should be drawn. Currently not used.
Returns:
true if Zone entities' boundaries should be drawn, otherwise false.
Type: boolean
getEntityLocalTransform(entityID) → {Mat4}
Get the object to parent transform, excluding scale, of an entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity.
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.
Type: Mat4
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 }
getEntityProperties(entityID, desiredPropertiesopt) → {Entities.EntityProperties}
Get the properties of an entity.
Parameters:
Name Type Attributes Default Description
entityID Uuid The ID of the entity to get the properties of.
desiredProperties Array.<string> <optional>
[] Array of the names of the properties to get. If the array is empty, all properties are returned.
Returns:
The properties of the entity if the entity can be found, otherwise an empty object.
Type: Entities.EntityProperties
Example

Report the color of a new box entity.

var entityID = Entities.addEntity({
  type: "Box",
  position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
  rotation: MyAvatar.orientation,
  dimensions: { x: 0.5, y: 0.5, z: 0.5 }
});
var properties = Entities.getEntityProperties(entityID, ["color"]);
print("Entity color: " + JSON.stringify(properties.color));
getEntityTransform(entityID) → {Mat4}
Get the object to world transform, excluding scale, of an entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity.
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.
Type: Mat4
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 }
getJointIndex(entityID, name) → {number}
Get the index of a named joint in a Model entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity.
name string The name of the joint.
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.
Type: number
Example

Report the index of a model's head joint.

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

Script.setTimeout(function () {
  // Joint data aren't available until after the model has loaded.
  var index = Entities.getJointIndex(entityID, "Head");
  print("Head joint index: " + index);
}, 2000);
getJointNames(entityID) → {Array.<string>}
Get the names of all the joints in a Model entity.
Parameters:
Name Type Description
entityID Uuid The ID of the Model entity.
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.
Type: Array.<string>
Example

Report a model's joint names.

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

Script.setTimeout(function () {
  // Joint data aren't available until after the model has loaded.
  var jointNames = Entities.getJointNames(entityID);
  print("Joint names: " + JSON.stringify(jointNames));
}, 2000);
getKeyboardFocusEntity() → {Uuid}
Get the ID of the Web entity that has keyboard focus.
Returns:
The ID of the Web entity that has focus, if any, otherwise null.
Type: Uuid
getLifetimeBPS() → {number}
Get the entity bytes per second send rate of the client over its lifetime.
Returns:
Entity bytes per second send rate of the client over its lifetime.
Type: number
getLifetimeBPSQueued() → {number}
Get the entity bytes per second queued rate of the client over its lifetime.
Returns:
Entity bytes per second queued rate of the client over its lifetime.
Type: number
getLifetimeBytesQueued() → {number}
Get the total bytes of entity packets queued by the client over its lifetime.
Returns:
The total bytes of entity packets queued by the client over its lifetime.
Type: number
getLifetimeBytesSent() → {number}
Get the total bytes of entity packets sent by the client over its lifetime.
Returns:
The total bytes of entity packets sent by the client over its lifetime.
Type: number
getLifetimeInSeconds() → {number}
Get the lifetime of the client from the first entity packet sent until now, in seconds.
Returns:
Lifetime of the client from the first entity packet sent until now, in seconds.
Type: number
getLifetimeInUsecs() → {number}
Get the lifetime of the client from the first entity packet sent until now, in microseconds.
Returns:
Lifetime of the client from the first entity packet sent until now, in microseconds.
Type: number
getLifetimePacketsQueued() → {number}
Get the total number of entity packets queued by the client over its lifetime.
Returns:
The total number of entity packets queued by the client over its lifetime.
Type: number
getLifetimePacketsSent() → {number}
Get the total number of entity packets sent by the client over its lifetime.
Returns:
The total number of entity packets sent by the client over its lifetime.
Type: number
getLifetimePPS() → {number}
Get the entity packets per second send rate of the client over its lifetime.
Returns:
Entity packets per second send rate of the client over its lifetime.
Type: number
getLifetimePPSQueued() → {number}
Get the entity packets per second queued rate of the client over its lifetime.
Returns:
Entity packets per second queued rate of the client over its lifetime.
Type: number
getLightsArePickable() → {boolean}
Get whether or not ray picks intersect the bounding box of Light entities. Ray picks are done using findRayIntersection or findRayIntersectionBlocking, or the Picks and RayPick APIs.
Returns:
true if ray picks intersect the bounding box of Light entities, otherwise false.
Type: boolean
getLocalJointRotation(entityID, jointIndex) → {Quat}
Get the local rotation of a joint in a Model entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity.
jointIndex number The integer index of the joint.
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.
Type: Quat
Example

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

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

Script.setTimeout(function () {
  // Joint data aren't available until after the model has loaded.
  var index = Entities.getJointIndex(entityID, "Head");
  var rotation = Entities.getLocalJointRotation(entityID,  index);
  print("Head local rotation: " + JSON.stringify(Quat.safeEulerAngles(rotation)));
}, 2000);
getLocalJointTranslation(entityID, jointIndex) → {Vec3}
Get the local translation of a joint in a Model entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity.
jointIndex number The integer index of the joint.
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.
Type: Vec3
getMeshes(entityID, callback)
Get the meshes in a Model or PolyVox entity.
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.
Deprecated:
Use the Graphics API instead.
getNestableType(entityID) → {string}
Get the type — entity, overlay, or avatar — of an in-world item.
Parameters:
Name Type Description
entityID Uuid The ID of the item to get the type of.
Returns:
The type of the item: "entity" if the item is an entity, "overlay" if the the item is an overlay, "avatar" if the item is an avatar; otherwise "unknown" if the item cannot be found.
Type: string
Example

Print some nestable types.

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

print(Entities.getNestableType(entity));  // "entity"
print(Entities.getNestableType(Uuid.generate()));  // "unknown"
getPacketsPerSecond() → {number}
Get the maximum number of entity packets that the client can send per second.
Returns:
Integer maximum number of entity packets that the client can send per second.
Type: number
getServerScriptStatus(entityID, callback) → {boolean}
Gets the status of server entity script attached to an entity
Parameters:
Name Type Description
entityID Uuid The ID of the entity to get the server entity script status for.
callback Entities~getServerScriptStatusCallback The function to call upon completion.
Returns:
true always.
Type: boolean
getStaticCertificateJSON(entityID) → {string}
Get the static certificate for an entity. The static certificate contains static properties of the item which cannot be altered.
Parameters:
Name Type Description
entityID Uuid The ID of the entity to get the static certificate for.
Returns:
The entity's static certificate as a JSON string if the entity can be found, otherwise an empty string.
Type: string
getZonesArePickable() → {boolean}
Get whether or not ray picks intersect the bounding box of Zone entities. Ray picks are done using findRayIntersection or findRayIntersectionBlocking, or the Picks and RayPick APIs.
Returns:
true if ray picks intersect the bounding box of Zone entities, otherwise false.
Type: boolean
hasPacketsToSend() → {boolean}
Check whether the client has entity packets waiting to be sent.
Returns:
true if the client has entity packets waiting to be sent, otherwise false.
Type: boolean
isChildOfParent(childID, parentID) → {boolean}
Check whether an entity or overlay has an entity as an ancestor (parent, parent's parent, etc.).
Parameters:
Name Type Description
childID Uuid The ID of the child entity or overlay to test for being a child, grandchild, etc.
parentID Uuid The ID of the parent entity to test for being a parent, grandparent, etc.
Returns:
true if the childID entity or overlay has the parentID entity as a parent or grandparent etc., otherwise false.
Type: boolean
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
localCoordsToVoxelCoords(entityID, localCoords) → {Vec3}
Convert local coordinates to voxel coordinates in a PolyVox entity. Local coordinates are relative to the minimum axes value corner of the entity, with the scale being the same as world coordinates.
Parameters:
Name Type Description
entityID Uuid The ID of the PolyVox entity.
localCoords Vec3 The local coordinates. May be outside the entity's bounding box.
Returns:
The voxel coordinates of the worldCoords if the entityID is a PolyVox entity, otherwise Vec3.ZERO. The value may be fractional.
Type: Vec3
packetsToSendCount() → {number}
Get the number of entity packets the client has waiting to be sent.
Returns:
Integer number of entity packets the client has waiting to be sent.
Type: number
queryPropertyMetadata(entityID, property, scope, callback) → {boolean}
Get metadata for certain entity properties such as script and serverScripts.
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.
Throws:
Throws an error if property is not handled yet or callback is not a function.
Returns:
true if the request for metadata was successfully sent to the server, otherwise false.
Type: boolean
queryPropertyMetadata(entityID, property, callback) → {boolean}
Get metadata for certain entity properties such as script and serverScripts.
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.
Throws:
Throws an error if property is not handled yet or callback is not a function.
Returns:
true if the request for metadata was successfully sent to the server, otherwise false.
Type: boolean
reloadServerScripts(entityID) → {boolean}
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.
Returns:
true if the reload request was successfully sent to the server, otherwise false.
Type: boolean
sendClickDownOnEntity(entityID, event)
Emit a clickDownOnEntity event.
Parameters:
Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
sendClickReleaseOnEntity(entityID, event)
Emit a clickReleaseOnEntity event.
Parameters:
Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
sendHoldingClickOnEntity(entityID, event)
Emit a holdingClickOnEntity event.
Parameters:
Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
sendHoverEnterEntity(entityID, event)
Emit a hoverEnterEntity event.
Parameters:
Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
sendHoverLeaveEntity(entityID, event)
Emit a hoverLeaveEntity event.
Parameters:
Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
sendHoverOverEntity(entityID, event)
Emit a hoverOverEntity event.
Parameters:
Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
sendMouseMoveOnEntity(entityID, event)
Emit a mouseMoveOnEntity event.
Parameters:
Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
sendMousePressOnEntity(entityID, event)
Emit a mousePressOnEntity event.
Parameters:
Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
sendMouseReleaseOnEntity(entityID, event)
Emit a mouseReleaseOnEntity event.
Parameters:
Name Type Description
entityID Uuid The ID of the entity to emit the event for.
event PointerEvent The event details.
serversExist() → {boolean}
Check whether servers exist for the client to send entity packets to, i.e., whether you are connected to a domain and its entity server is working.
Returns:
true if servers exist for the client to send entity packets to, otherwise false.
Type: boolean
setAbsoluteJointRotationInObjectFrame(entityID, jointIndex, rotation) → {boolean}
Set the rotation of a joint in a Model entity relative to the entity's position and orientation.
Parameters:
Name Type Description
entityID Uuid The ID of the entity.
jointIndex number The integer index of the joint.
rotation Quat The rotation to set the joint to relative to the entity's orientation.
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.
Type: boolean
Example

Raise an avatar model's left palm.

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

Script.setTimeout(function () {
  // Joint data aren't available until after the model has loaded.
  var index = Entities.getJointIndex(entityID, "LeftHand");
  var absoluteRotation = Entities.getAbsoluteJointRotationInObjectFrame(entityID, index);
  absoluteRotation = Quat.multiply(Quat.fromPitchYawRollDegrees(0, 0, 90), absoluteRotation);
  var success = Entities.setAbsoluteJointRotationInObjectFrame(entityID, index, absoluteRotation);
  print("Success: " + success);
}, 2000);
setAbsoluteJointTranslationInObjectFrame(entityID, jointIndex, translation) → {boolean}
Set the translation of a joint in a Model entity relative to the entity's position and orientation.
Parameters:
Name Type Description
entityID Uuid The ID of the entity.
jointIndex number The integer index of the joint.
translation Vec3 The translation to set the joint to relative to the entity's position and orientation.
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.
Type: boolean
setAllPoints(entityID, points) → {boolean}
Set the linePoints property of a Line entity.
Parameters:
Name Type Description
entityID Uuid The ID of the Line entity.
points Array.<Vec3> The array of points to set the entity's linePoints property to.
Returns:
true if the entity's property was updated, otherwise false. The property may fail to be updated if the entity does not exist, the entity is not a Line entity, one of the points is outside the entity's dimensions, or the number of points is greater than the maximum allowed.
Type: boolean
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);
setAllVoxels(entityID, value)
Set the values of all voxels in a PolyVox entity.
Parameters:
Name Type Description
entityID Uuid The ID of the PolyVox entity.
value number If value % 256 == 0 then each voxel is cleared, otherwise each voxel is set.
Example

Create a PolyVox cube.

var entity = Entities.addEntity({
  type: "PolyVox",
  position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 })),
  dimensions: { x: 2, y: 2, z: 2 },
  voxelVolumeSize: { x: 16, y: 16, z: 16 },
  lifetime: 300  // Delete after 5 minutes.
});
Entities.setAllVoxels(entity, 1);
setDrawZoneBoundaries(value)
Set whether or not Zone entities' boundaries should be drawn. Currently not used.
Parameters:
Name Type Description
value boolean Set to true if Zone entities' boundaries should be drawn, otherwise false.
setKeyboardFocusEntity(entityID)
Set the Web entity that has keyboard focus.
Parameters:
Name Type Description
entityID Uuid The ID of the Web entity to set keyboard focus to. Use null or Uuid.NULL to unset keyboard focus from an entity.
setLightsArePickable(value)
Set whether or not ray picks intersect the bounding box of Light entities. By default, Light entities are not intersected. The setting lasts for the Interface session. Ray picks are done using findRayIntersection or findRayIntersectionBlocking, or the Picks and RayPick APIs.
Parameters:
Name Type Description
value boolean Set true to make ray picks intersect the bounding box of Light entities, otherwise false.
setLocalJointRotation(entityID, jointIndex, rotation) → {boolean}
Set the local rotation of a joint in a Model entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity.
jointIndex number The integer index of the joint.
rotation Quat The local rotation to set the joint to.
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.
Type: boolean
Example

Make an avatar model turn its head left.

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

Script.setTimeout(function () {
  // Joint data aren't available until after the model has loaded.
  var index = Entities.getJointIndex(entityID, "Head");
  var rotation = Quat.fromPitchYawRollDegrees(0, 60, 0);
  var success = Entities.setLocalJointRotation(entityID, index, rotation);
  print("Success: " + success);
}, 2000);
setLocalJointRotations(entityID, rotations) → {boolean}
Set the local rotations of joints in a Model entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity.
rotations Array.<Quat> The local rotations to set the joints to.
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.
Type: boolean
Example

Raise both palms of an avatar model.

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

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

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

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

  // Update all the joint rotations.
  var success = Entities.setLocalJointRotations(entityID, jointRotations);
  print("Success: " + success);
}, 2000);
setLocalJointsData(entityID, rotations, translations) → {boolean}
Set the local rotations and translations of joints in a Model entity. This is the same as calling both setLocalJointRotations and setLocalJointTranslations at the same time.
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.
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.
Type: boolean
setLocalJointTranslation(entityID, jointIndex, translation) → {boolean}
Set the local translation of a joint in a Model entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity.
jointIndex number The integer index of the joint.
translation Vec3 The local translation to set the joint to.
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.
Type: boolean
setLocalJointTranslations(entityID, translations) → {boolean}
Set the local translations of joints in a Model entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity.
translations Array.<Vec3> The local translations to set the joints to.
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.
Type: boolean
setPacketsPerSecond(packetsPerSecond)
Set the maximum number of entity packets that the client can send per second.
Parameters:
Name Type Description
packetsPerSecond number Integer maximum number of entity packets that the client can send per second.
setVoxel(entityID, position, value)
Set the value of a particular voxels in a PolyVox entity.
Parameters:
Name Type Description
entityID Uuid The ID of the PolyVox entity.
position Vec3 The position relative to the minimum axes values corner of the entity. The position coordinates are rounded to the nearest integer to get the voxel coordinate. The minimum axes corner voxel is { x: 0, y: 0, z: 0 }.
value number If value % 256 == 0 then voxel is cleared, otherwise the voxel is set.
Example

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

var entity = Entities.addEntity({
  type: "PolyVox",
  position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 })),
  dimensions: { x: 2, y: 2, z: 2 },
  voxelVolumeSize: { x: 16, y: 16, z: 16 },
  lifetime: 300  // Delete after 5 minutes.
});
Entities.setAllVoxels(entity, 1);
Entities.setVoxel(entity, { x: 0, y: 0, z: 0 }, 0);
setVoxelCapsule(entityID, start, end, radius, value)
Set the values of all voxels in a capsule-shaped portion of a PolyVox entity.
Parameters:
Name Type Description
entityID Uuid The ID of the PolyVox entity.
start Vec3 The center of the sphere of voxels to set, in world coordinates.
end Vec3 The center of the sphere of voxels to set, in world coordinates.
radius number The radius of the capsule cylinder and spherical ends, in world coordinates.
value number If value % 256 == 0 then each voxel is cleared, otherwise each voxel is set.
Example

Create a PolyVox capsule shape.

var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 }));
var polyVox = Entities.addEntity({
  type: "PolyVox",
  position: position,
  dimensions: { x: 2, y: 2, z: 2 },
  voxelVolumeSize: { x: 32, y: 32, z: 32 },
  lifetime: 300  // Delete after 5 minutes.
});
var startPosition = Vec3.sum({ x: -0.5, y: 0, z: 0 }, position);
var endPosition = Vec3.sum({ x: 0.5, y: 0, z: 0 }, position);
Entities.setVoxelCapsule(polyVox, startPosition, endPosition, 0.5, 255);
setVoxelsInCuboid(entityID, lowPosition, cuboidSize, value)
Set the values of all voxels in a cubic portion of a PolyVox entity.
Parameters:
Name Type Description
entityID Uuid The ID of the PolyVox entity.
lowPosition Vec3 The position of the minimum axes value corner of the cube of voxels to set, in voxel coordinates.
cuboidSize Vec3 The size of the cube of voxels to set, in voxel coordinates.
value number If value % 256 == 0 then each voxel is cleared, otherwise each voxel is set.
Example

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

var polyVox = Entities.addEntity({
  type: "PolyVox",
  position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 })),
  rotation: MyAvatar.orientation,
  dimensions: { x: 2, y: 2, z: 2 },
  voxelVolumeSize: { x: 16, y: 16, z: 16 },
  lifetime: 300  // Delete after 5 minutes.
});
Entities.setAllVoxels(polyVox, 1);
var cuboidPosition = { x: 12, y: 12, z: 12 };
var cuboidSize = { x: 4, y: 4, z: 4 };
Entities.setVoxelsInCuboid(polyVox, cuboidPosition, cuboidSize, 0);
setVoxelSphere(entityID, center, radius, value)
Set the values of all voxels in a spherical portion of a PolyVox entity.
Parameters:
Name Type Description
entityID Uuid The ID of the PolyVox entity.
center Vec3 The center of the sphere of voxels to set, in world coordinates.
radius number The radius of the sphere of voxels to set, in world coordinates.
value number If value % 256 == 0 then each voxel is cleared, otherwise each voxel is set.
Example

Create a PolyVox sphere.

var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 }));
var polyVox = Entities.addEntity({
  type: "PolyVox",
  position: position,
  dimensions: { x: 2, y: 2, z: 2 },
  voxelVolumeSize: { x: 32, y: 32, z: 32 },
  lifetime: 300  // Delete after 5 minutes.
});
Entities.setVoxelSphere(polyVox, position, 0.9, 255);
setZonesArePickable(value)
Set whether or not ray picks intersect the bounding box of Zone entities. By default, Light entities are not intersected. The setting lasts for the Interface session. Ray picks are done using findRayIntersection or findRayIntersectionBlocking, or the Picks and RayPick APIs.
Parameters:
Name Type Description
value boolean Set true to make ray picks intersect the bounding box of Zone entities, otherwise false.
updateAction(entityID, actionID, arguments) → {boolean}
Update an entity action.
Parameters:
Name Type Description
entityID Uuid The ID of the entity with the action to update.
actionID Uuid The ID of the action to update.
arguments Entities.ActionArguments The arguments to update.
Returns:
true if the update was successful, otherwise false.
Type: boolean
verifyStaticCertificateProperties(entityID) → {boolean}
Verify the entity's proof of provenance, i.e., that the entity's certificateID property was produced by High Fidelity signing the entity's static certificate JSON.
Parameters:
Name Type Description
entityID Uuid The ID of the entity to verify.
Returns:
true if the entity can be found an its certificateID property is present and its value matches the entity's static certificate JSON; otherwise false.
Type: boolean
voxelCoordsToLocalCoords(entityID, voxelCoords) → {Vec3}
Convert voxel coordinates in a PolyVox entity to local coordinates relative to the minimum axes value corner of the entity, with the scale being the same as world coordinates.
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.
Returns:
The local coordinates of the voxelCoords if the entityID is a PolyVox entity, otherwise Vec3.ZERO.
Type: Vec3
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));
voxelCoordsToWorldCoords(entityID, voxelCoords) → {Vec3}
Convert voxel coordinates in a PolyVox entity to world coordinates. Voxel coordinates are relative to the minimum axes values corner of the entity with a scale of Vec3.ONE being the dimensions of each voxel.
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.
Returns:
The world coordinates of the voxelCoords if the entityID is a PolyVox entity, otherwise Vec3.ZERO.
Type: Vec3
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.
});
wantsHandControllerPointerEvents(entityID) → {boolean}
Check whether an entity wants hand controller pointer events. For example, a Web entity does but a Shape entity doesn't.
Parameters:
Name Type Description
entityID Uuid The ID of the entity.
Returns:
true if the entity can be found and it wants hand controller pointer events, otherwise false.
Type: boolean
worldCoordsToVoxelCoords(entityID, worldCoords) → {Vec3}
Convert world coordinates to voxel coordinates in a PolyVox entity. Voxel coordinates are relative to the minimum axes values corner of the entity, with a scale of Vec3.ONE being the dimensions of each voxel.
Parameters:
Name Type Description
entityID Uuid The ID of the PolyVox entity.
worldCoords Vec3 The world coordinates. May be outside the entity's bounding box.
Returns:
The voxel coordinates of the worldCoords if the entityID is a PolyVox entity, otherwise Vec3.ZERO. The value may be fractional.
Type: Vec3

Signals

addingEntity(entityID) → {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 a domain or client-only entity is added (e.g., by {@Entities.addEntity|addEntity}).
Parameters:
Name Type Description
entityID Uuid The ID of the entity added.
Returns:
Type: Signal
Example

Report when an entity is added.

Entities.addingEntity.connect(function (entityID) {
  print("Added entity: " + entityID);
});
canAdjustLocksChanged(canAdjustLocks) → {Signal}
Triggered when your ability to change the locked property of entities changes.
Parameters:
Name Type Description
canAdjustLocks boolean true if the script can change the locked property of an entity, otherwise false.
Returns:
Type: Signal
Example

Report when your ability to change locks changes.

function onCanAdjustLocksChanged(canAdjustLocks) {
  print("You can adjust entity locks: " + canAdjustLocks);
}
Entities.canAdjustLocksChanged.connect(onCanAdjustLocksChanged);
canRezCertifiedChanged(canRezCertified) → {Signal}
Triggered when your ability to rez (create) certified entities changes. Certified entities are entities that have PoP certificates.
Parameters:
Name Type Description
canRezCertified boolean true if the script can rez (create) certified entities, otherwise false.
Returns:
Type: Signal
canRezChanged(canRez) → {Signal}
Triggered when your ability to rez (create) entities changes.
Parameters:
Name Type Description
canRez boolean true if the script can rez (create) entities, otherwise false.
Returns:
Type: Signal
canRezTmpCertifiedChanged(canRezTmpCertified) → {Signal}
Triggered when your ability to rez (create) temporary certified entities changes. Temporary entities are entities with a finite lifetime property value set. Certified entities are entities that have PoP certificates.
Parameters:
Name Type Description
canRezTmpCertified boolean true if the script can rez (create) temporary certified entities, otherwise false.
Returns:
Type: Signal
canRezTmpChanged(canRezTmp) → {Signal}
Triggered when your ability to rez (create) temporary entities changes. Temporary entities are entities with a finite lifetime property value set.
Parameters:
Name Type Description
canRezTmp boolean true if the script can rez (create) temporary entities, otherwise false.
Returns:
Type: Signal
canWriteAssetsChanged(canWriteAssets) → {Signal}
Triggered when your ability to make changes to the asset server's assets changes.
Parameters:
Name Type Description
canWriteAssets boolean true if the script can change the ? property of an entity, otherwise false.
Returns:
Type: Signal
clearingEntities() → {Signal}
Triggered when you disconnect from a domain, at which time Interface's local in-memory tree of entities it knows about is cleared.
Returns:
Type: Signal
Example

Report when Interfaces's entity tree is cleared.

Entities.clearingEntities.connect(function () {
  print("Entities cleared");
});
clickDownOnEntity(entityID, event) → {Signal}
Triggered when a mouse button is clicked while the mouse cursor is on an entity. Note: Not triggered by controller.
Parameters:
Name Type Description
entityID Uuid The ID of the entity that was clicked.
event PointerEvent Details of the event.
Returns:
Type: Signal
clickReleaseOnEntity(entityID, event) → {Signal}
Triggered when a mouse button is released after clicking on an entity, even if the mouse cursor has moved off the entity. Note: Not triggered by controller.
Parameters:
Name Type Description
entityID Uuid The ID of the entity that was originally clicked.
event PointerEvent Details of the event.
Returns:
Type: Signal
collisionWithEntity(idA, idB, collision) → {Signal}
Triggered on the client that is the physics simulation owner during the collision of two entities. Note: Isn't triggered for a collision with an avatar.
Parameters:
Name Type Description
idA Uuid The ID of one entity in the collision. For an entity script, this is the ID of the entity containing the script.
idB Uuid The ID of the other entity in the collision.
collision Collision The details of the collision.
Returns:
Type: Signal
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) → {Signal}
Triggered when an entity is deleted.
Parameters:
Name Type Description
entityID Uuid The ID of the entity deleted.
Returns:
Type: Signal
Example

Report when an entity is deleted.

Entities.deletingEntity.connect(function (entityID) {
  print("Deleted entity: " + entityID);
});
enterEntity(entityID) → {Signal}
Triggered when an avatar enters an entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity that the avatar entered.
Returns:
Type: Signal
Example

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

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

var entityID = Entities.addEntity({
  type: "Sphere",
  position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
  dimensions: { x: 3, y: 3, z: 3 },
  color: { red: 128, green: 128, blue: 128 },
  collisionless: true,  // So that avatar can walk through entity.
  script: "(" + entityScript + ")",  // Could host the script on a Web server instead.
  lifetime: 300  // Delete after 5 minutes.
});
holdingClickOnEntity(entityID, event) → {Signal}
Repeatedly triggered while a mouse button continues to be held after clicking an entity, even if the mouse cursor has moved off the entity. Note: Not triggered by controller.
Parameters:
Name Type Description
entityID Uuid The ID of the entity that was originally clicked.
event PointerEvent Details of the event.
Returns:
Type: Signal
hoverEnterEntity(entityID, event) → {Signal}
Triggered when the mouse cursor or controller laser starts hovering on an entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity that is being hovered.
event PointerEvent Details of the event.
Returns:
Type: Signal
hoverLeaveEntity(entityID, event) → {Signal}
Triggered when the mouse cursor or controller laser stops hovering over an entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity that was being hovered.
event PointerEvent Details of the event.
Returns:
Type: Signal
hoverOverEntity(entityID, event) → {Signal}
Repeatedly triggered when the mouse cursor or controller laser moves while hovering over an entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity that is being hovered.
event PointerEvent Details of the event.
Returns:
Type: Signal
leaveEntity(entityID) → {Signal}
Triggered when an avatar leaves an entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity that the avatar left.
Returns:
Type: Signal
mouseDoublePressOffEntity(event) → {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.
Returns:
Type: Signal
mouseDoublePressOnEntity(entityID, event) → {Signal}
Triggered when a mouse button is double-clicked while the mouse cursor is on an entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity that was double-pressed.
event PointerEvent Details of the event.
Returns:
Type: Signal
mouseMoveOnEntity(entityID, event) → {Signal}
Repeatedly triggered while the mouse cursor or controller laser moves on an entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity that was moved on.
event PointerEvent Details of the event.
Returns:
Type: Signal
mousePressOffEntity(event) → {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.
Returns:
Type: Signal
mousePressOnEntity(entityID, event) → {Signal}
Triggered when a mouse button is clicked while the mouse cursor is on an entity, or a controller trigger is fully pressed while its laser is on an entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity that was pressed.
event PointerEvent Details of the event.
Returns:
Type: Signal
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) → {Signal}
Triggered when a mouse button is released after clicking on an entity or the controller trigger is partly or fully released after pressing on an entity, even if the mouse pointer or controller laser has moved off the entity.
Parameters:
Name Type Description
entityID Uuid The ID of the entity that was originally pressed.
event PointerEvent Details of the event.
Returns:
Type: Signal
preload(entityID) → {Signal}
Triggered when the script starts for a user.

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

Available in: Client Entity Scripts Server Entity Scripts
Parameters:
Name Type Description
entityID Uuid The ID of the entity that the script is running in.
Returns:
Type: Signal
Example

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

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

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

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

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

Available in: Client Entity Scripts Server Entity Scripts
Returns:
Type: Signal
webEventReceived(entityID, message) → {Signal}
Triggered in when a script in a Web entity's Web page script sends an event over the script's EventBridge.
Parameters:
Name Type Description
entityID Uuid The ID of the entity that event was received from.
message string The message received.
Returns:
Type: Signal

Type Definitions

ActionArguments
Different entity action types have different arguments: some common to all actions (listed below) and some specific to each ActionType (linked to below). The arguments are accessed as an object of property names and values.
Type: object
Properties:
Name Type Default Description
type Entities.ActionType The type of action.
tag string "" A string that a script can use for its own purposes.
ttl number 0 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.
isMine boolean true Is true if you created the action during your current Interface session, false otherwise. Read-only.
::no-motion-state boolean Is present when the entity hasn't been registered with the physics engine yet (e.g., if the action hasn't been properly configured), otherwise undefined. Read-only.
::active boolean Is true when the action is modifying the entity's motion, false otherwise. Is present once the entity has been registered with the physics engine, otherwise undefined. Read-only.
::motion-type Entities.PhysicsMotionType How the entity moves with the action. Is present once the entity has been registered with the physics engine, otherwise undefined. Read-only.
See:
ActionArguments-BallSocket
The "ball-socket" ActionType connects two entities with a ball and socket joint. It has arguments in addition to the common ActionArguments.
Type: object
Properties:
Name Type Default Description
pivot Vec3 0,0,0 The local offset of the joint relative to the entity's position.
otherEntityID Uuid null The ID of the other entity that is connected to the joint.
otherPivot Vec3 0,0,0 The local offset of the joint relative to the other entity's position.
ActionArguments-ConeTwist
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.
Type: object
Properties:
Name Type Default Description
pivot Vec3 0,0,0 The local offset of the joint relative to the entity's position.
axis Vec3 1,0,0 The axis of the entity that moves through the cone. Must be a non-zero vector.
otherEntityID Uuid null The ID of the other entity that is connected to the joint.
otherPivot Vec3 0,0,0 The local offset of the joint relative to the other entity's position.
otherAxis Vec3 1,0,0 The axis of the other entity that moves through the cone. Must be a non-zero vector.
swingSpan1 number 6.238 The angle through which the joint can move in one axis of the cone, in radians.
swingSpan2 number 6.238 The angle through which the joint can move in the other axis of the cone, in radians.
twistSpan number 6.238 The angle through with the joint can twist, in radians.
ActionArguments-FarGrab
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.
Type: object
Properties:
Name Type Default Description
targetPosition Vec3 0,0,0 The target position.
targetRotation Quat 0,0,0,1 The target rotation.
otherID Uuid null If an entity ID, the targetPosition and targetRotation are relative to this entity's position and rotation.
linearTimeScale number 3.4e+38 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.
angularTimeScale number 3.4e+38 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.
ActionArguments-Hinge
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.
Type: object
Properties:
Name Type Default Description
pivot Vec3 0,0,0 The local offset of the joint relative to the entity's position.
axis Vec3 1,0,0 The axis of the entity that it pivots about. Must be a non-zero vector.
otherEntityID Uuid null 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.
otherPivot Vec3 0,0,0 The local offset of the joint relative to the other entity's position.
otherAxis Vec3 1,0,0 The axis of the other entity that it pivots about. Must be a non-zero vector.
low number -6.283 The most negative angle that the hinge can take, in radians.
high number 6.283 The most positive angle that the hinge can take, in radians.
angle number 0 The current angle of the hinge. Read-only.
ActionArguments-Hold
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.
Type: object
Properties:
Name Type Default Description
holderID Uuid MyAvatar.sessionUUID The ID of the avatar holding the entity.
relativePosition Vec3 0,0,0 The target position relative to the avatar's hand.
relativeRotation Vec3 0,0,0,1 The target rotation relative to the avatar's hand.
timeScale number 3.4e+38 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.
hand string right The hand holding the entity: "left" or "right".
kinematic boolean false If true, the entity is made kinematic during the action; the entity won't lag behind the hand but constraint actions such as "hinge" won't act properly.
kinematicSetVelocity boolean false If true and kinematic is true, the entity's velocity property will be set during the action, e.g., so that other scripts may use the value.
ignoreIK boolean false If true, the entity follows the HMD controller rather than the avatar's hand.
ActionArguments-Offset
The "offset" ActionType moves an entity so that it is a set distance away from a target point. It has arguments in addition to the common ActionArguments.
Type: object
Properties:
Name Type Default Description
pointToOffsetFrom Vec3 0,0,0 The target point to offset the entity from.
linearDistance number 0 The distance away from the target point to position the entity.
linearTimeScale number 34e+38 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.
ActionArguments-Slider
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.
Type: object
Properties:
Name Type Default Description
point Vec3 0,0,0 The local position of a point in the entity that slides along the axis.
axis Vec3 1,0,0 The axis of the entity that slides along the joint. Must be a non-zero vector.
otherEntityID Uuid null The ID of the other entity that is connected to the joint, if any. If non is specified then the first entity simply slides and rotates about its specified axis.
otherPoint Vec3 0,0,0 The local position of a point in the other entity that slides along the axis.
axis Vec3 1,0,0 The axis of the other entity that slides along the joint. Must be a non-zero vector.
linearLow number 1.17e-38 The most negative linear offset from the entity's initial point that the entity can have along the slider.
linearHigh number 3.40e+38 The most positive linear offset from the entity's initial point that the entity can have along the slider.
angularLow number -6.283 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.
angularHigh number 6.283 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.
linearPosition number 0 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.
angularPosition number 0 The current angular offset of the entity from its initial rotation if the action involves only one entity, otherwise the angular offset between the two entities. Read-only.
ActionArguments-Tractor
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.
Type: object
Properties:
Name Type Default Description
targetPosition Vec3 0,0,0 The target position.
targetRotation Quat 0,0,0,1 The target rotation.
otherID Uuid null If an entity ID, the targetPosition and targetRotation are relative to this entity's position and rotation.
linearTimeScale number 3.4e+38 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.
angularTimeScale number 3.4e+38 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.
ActionArguments-TravelOriented
The "travel-oriented" ActionType orients an entity to align with its direction of travel. It has arguments in addition to the common ActionArguments.
Type: object
Properties:
Name Type Default Description
forward Vec3 0,0,0 The axis of the entity to align with the entity's direction of travel.
angularTimeScale number 0.1 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.
ActionType

An entity action may be one of the following types:

Value Type Description Arguments
"far-grab" Avatar action Moves and rotates an entity to a target position and orientation, optionally relative to another entity. Collisions between the entity and the user's avatar are disabled during the far-grab. Entities.ActionArguments-FarGrab
"hold" Avatar action Positions and rotates an entity relative to an avatar's hand. Collisions between the entity and the user's avatar are disabled during the hold. Entities.ActionArguments-Hold
"offset" Object action Moves an entity so that it is a set distance away from a target point. Entities.ActionArguments-Offset
"tractor" Object action Moves and rotates an entity to a target position and orientation, optionally relative to another entity. Entities.ActionArguments-Tractor
"travel-oriented" Object action Orients an entity to align with its direction of travel. Entities.ActionArguments-TravelOriented
"hinge" Object constraint Lets an entity pivot about an axis or connects two entities with a hinge joint. Entities.ActionArguments-Hinge
"slider" Object constraint Lets an entity slide and rotate along an axis, or connects two entities that slide and rotate along a shared axis. ActionArguments-Slider
"cone-twist" Object constraint Connects two entities with a joint that can move through a cone and can twist. Entities.ActionArguments-ConeTwist
"ball-socket" Object constraint Connects two entities with a ball and socket joint. Entities.ActionArguments-BallSocket
"spring" Synonym for "tractor". Legacy value.
Type: string
AmbientLight
Ambient light is defined by the following properties.
Type: object
Properties:
Name Type Default Description
ambientIntensity number 0.5 The intensity of the light.
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".
AnimationProperties
The AnimationProperties are used to configure an animation.
Type: object
Properties:
Name Type Default Description
url string "" The URL of the FBX file that has the animation.
fps number 30 The speed in frames/s that the animation is played at.
firstFrame number 0 The first frame to play in the animation.
lastFrame number 100000 The last frame to play in the animation.
currentFrame number 0 The current frame being played in the animation.
running boolean false If true then the animation should play.
loop boolean true If true then the animation should be continuously repeated in a loop.
hold boolean false If true then the rotations and translations of the last frame played should be maintained when the animation stops playing.
Bloom
Bloom is defined by the following properties.
Type: object
Properties:
Name Type Default Description
bloomIntensity number 0.25 The intensity of the bloom effect.
bloomThreshold number 0.7 The threshold for the bloom effect.
bloomSize number 0.9 The size of the bloom effect.
BoundingBox
The axis-aligned bounding box of an entity.
Type: object
Properties:
Name Type Description
brn Vec3 The bottom right near (minimum axes values) corner of the AA box.
tfl Vec3 The top far left (maximum axes values) corner of the AA box.
center Vec3 The center of the AA box.
dimensions Vec3 The dimensions of the AA box.
CollisionMask

An entity may collide with the following types of items:

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

The values for the collision types that are enabled are added together to give the CollisionMask value. For example, a value of 31 means that an entity will collide with all item types.

Type: number
EntityProperties
Different entity types have different properties: some common to all entities (listed below) and some specific to each EntityType (linked to below). The properties are accessed as an object of property names and values.
Type: object
Properties:
Name Type Default Description
id Uuid The ID of the entity. Read-only.
name string "" A name for the entity. Need not be unique.
type Entities.EntityType The entity type. You cannot change the type of an entity after it's created. (Though its value may switch among "Box", "Shape", and "Sphere" depending on changes to the shape property set for entities of these types.) Read-only.
clientOnly boolean false If true then the entity is an avatar entity; otherwise it is a server entity. An avatar entity follows you to each domain you visit, rendering at the same world coordinates unless it's parented to your avatar. Value cannot be changed after the entity is created.
The value can also be set at entity creation by using the clientOnly parameter in Entities.addEntity.
owningAvatarID Uuid Uuid.NULL The session ID of the owning avatar if clientOnly is true, otherwise Uuid.NULL. Read-only.
created string The UTC date and time that the entity was created, in ISO 8601 format as yyyy-MM-ddTHH:mm:ssZ. Read-only.
age number The age of the entity in seconds since it was created. Read-only.
ageAsText string The age of the entity since it was created, formatted as h hours m minutes s seconds.
lifetime number -1 How long an entity lives for, in seconds, before being automatically deleted. A value of -1 means that the entity lives for ever.
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 false Whether or not the entity can be edited or deleted. If true then the entity's properties other than locked cannot be changed, and the entity cannot be deleted.
visible boolean true Whether or not the entity is rendered. If true then the entity is rendered.
canCastShadow boolean true Whether or not the entity can cast a shadow. Currently applicable only to Model and Shape entities. Shadows are cast if inside a Zone entity with castShadows enabled in its keyLight property.
isVisibleInSecondaryCamera boolean true Whether or not the entity is rendered in the secondary camera. If true then the entity is rendered.
position Vec3 0,0,0 The position of the entity.
rotation Quat 0,0,0,1 The orientation of the entity with respect to world coordinates.
registrationPoint Vec3 0.5,0.5,0.5 The point in the entity that is set to the entity's position and is rotated about, Vec3.ZEROVec3.ONE. A value of Vec3.ZERO is the entity's minimum x, y, z corner; a value of Vec3.ONE is the entity's maximum x, y, z corner.
naturalPosition Vec3 0,0,0 The center of the entity's unscaled mesh model if it has one, otherwise Vec3.ZERO. Read-only.
naturalDimensions Vec3 The dimensions of the entity's unscaled mesh model if it has one, otherwise Vec3.ONE. Read-only.
velocity Vec3 0,0,0 The linear velocity of the entity in m/s with respect to world coordinates.
damping number 0.39347 How much to slow down the linear velocity of an entity over time, 0.01.0. A higher damping value slows down the entity more quickly. The default value is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to 1/e = 0.368 of its initial value.
angularVelocity Vec3 0,0,0 The angular velocity of the entity in rad/s with respect to its axes, about its registration point.
angularDamping number 0.39347 How much to slow down the angular velocity of an entity over time, 0.01.0. A higher damping value slows down the entity more quickly. The default value is for an exponential decay timescale of 2.0s, where it takes 2.0s for the movement to slow to 1/e = 0.368 of its initial value.
gravity Vec3 0,0,0 The acceleration due to gravity in m/s 2 that the entity should move with, in world coordinates. Set to { x: 0, y: -9.8, z: 0 } to simulate Earth's gravity. Gravity is applied to an entity's motion only if its dynamic property is true. If changing an entity's gravity from Vec3.ZERO, you need to give it a small velocity in order to kick off physics simulation. The gravity value is applied in addition to the acceleration value.
acceleration Vec3 0,0,0 A general acceleration in m/s 2 that the entity should move with, in world coordinates. The acceleration is applied to an entity's motion only if its dynamic property is true. If changing an entity's acceleration from Vec3.ZERO, you need to give it a small velocity in order to kick off physics simulation. The acceleration value is applied in addition to the gravity value.
restitution number 0.5 The "bounciness" of an entity when it collides, 0.00.99. The higher the value, the more bouncy.
friction number 0.5 How much to slow down an entity when it's moving against another, 0.010.0. The higher the value, the more quickly it slows down. Examples: 0.1 for ice, 0.9 for sandpaper.
density number 1000 The density of the entity in kg/m 3, 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.
collisionless boolean false Whether or not the entity should collide with items per its collisionMask property. If true then the entity does not collide.
ignoreForCollisions boolean false Synonym for collisionless.
collisionMask Entities.CollisionMask 31 What types of items the entity should collide with.
collidesWith string "static,dynamic,kinematic,myAvatar,otherAvatar," Synonym for collisionMask, in text format.
collisionSoundURL string "" The sound to play when the entity experiences a collision. Valid file formats are as per the SoundCache object.
dynamic boolean false Whether or not the entity should be affected by collisions. If true then the entity's movement is affected by collisions.
collisionsWillMove boolean false Synonym for dynamic.
href string "" A "hifi://" metaverse address that a user is taken to when they click on the entity.
description string "" A description of the href property value.
userData string "" Used to store extra data about the entity in JSON format. WARNING: Other apps such as the Create app can also use this property, so make sure you handle data stored by other apps — edit only your bit and leave the rest of the data intact. You can use JSON.parse() to parse the string into a JavaScript object which you can manipulate the properties of, and use JSON.stringify() to convert the object into a string to put in the property.
script string "" The URL of the client entity script, if any, that is attached to the entity.
scriptTimestamp number 0 Intended to be used to indicate when the client entity script was loaded. Should be an integer number of milliseconds since midnight GMT on January 1, 1970 (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.
serverScripts string "" The URL of the server entity script, if any, that is attached to the entity.
parentID Uuid Uuid.NULL The ID of the entity or avatar that this entity is parented to. Uuid.NULL if the entity is not parented.
parentJointIndex number 65535 The joint of the entity or avatar that this entity is parented to. Use 65535 or -1 to parent to the entity or avatar's position and orientation rather than a joint.
localPosition Vec3 0,0,0 The position of the entity relative to its parent if the entity is parented, otherwise the same value as position. If the entity is parented to an avatar and is clientOnly so that it scales with the avatar, this value remains the original local position value while the avatar scale changes.
localRotation Quat 0,0,0,1 The rotation of the entity relative to its parent if the entity is parented, otherwise the same value as rotation.
localVelocity Vec3 0,0,0 The velocity of the entity relative to its parent if the entity is parented, otherwise the same value as velocity.
localAngularVelocity Vec3 0,0,0 The angular velocity of the entity relative to its parent if the entity is parented, otherwise the same value as position.
localDimensions Vec3 The dimensions of the entity. If the entity is parented to an avatar and is clientOnly so that it scales with the avatar, this value remains the original dimensions value while the avatar scale changes.
boundingBox Entities.BoundingBox The axis-aligned bounding box that tightly encloses the entity. Read-only.
queryAACube AACube The axis-aligned cube that determines where the entity lives in the entity server's octree. The cube may be considerably larger than the entity in some situations, e.g., when the entity is grabbed by an avatar: the position of the entity is determined through avatar mixer updates and so the AA cube is expanded in order to reduce unnecessary entity server updates. Scripts should not change this property's value.
actionData string "" Base-64 encoded compressed dump of the actions associated with the entity. This property is typically not used in scripts directly; rather, functions that manipulate an entity's actions update it. The size of this property increases with the number of actions. Because this property value has to fit within a High Fidelity datagram packet there is a limit to the number of actions that an entity can have, and edits which would result in overflow are rejected. Read-only.
renderInfo Entities.RenderInfo Information on the cost of rendering the entity. Currently information is only provided for Model entities. Read-only.
cloneable boolean false If true then the entity can be cloned via Entities.cloneEntity.
cloneLifetime number 300 The entity lifetime for clones created from this entity.
cloneLimit number 0 The total number of clones of this entity that can exist in the domain at any given time.
cloneDynamic boolean false If true then clones created from this entity will have their dynamic property set to true.
cloneAvatarEntity boolean false If true then clones created from this entity will be created as avatar entities: their clientOnly property will be set to true.
cloneOriginID Uuid The ID of the entity that this entity was cloned from.
itemName string "" Certifiable name of the Marketplace item.
itemDescription string "" Certifiable description of the Marketplace item.
itemCategories string "" Certifiable category of the Marketplace item.
itemArtist string "" Certifiable artist that created the Marketplace item.
itemLicense string "" Certifiable license URL for the Marketplace item.
limitedRun number 4294967295 Certifiable maximum integer number of editions (copies) of the Marketplace item allowed to be sold.
editionNumber number 0 Certifiable integer edition (copy) number or the Marketplace item. Each copy sold in the Marketplace is numbered sequentially, starting at 1.
entityInstanceNumber number 0 Certifiable integer instance number for identical entities in a Marketplace item. A Marketplace item may have identical parts. If so, then each is numbered sequentially with an instance number.
marketplaceID string "" Certifiable UUID for the Marketplace item, as used in the URL of the item's download and its Marketplace Web page.
certificateID string "" Hash of the entity's static certificate JSON, signed by the artist's private key.
staticCertificateVersion number 0 The version of the method used to generate the certificateID.
See:
EntityProperties-Box
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".
Type: object
EntityProperties-Light
The "Light" EntityType adds local lighting effects. It has properties in addition to the common EntityProperties.
Type: object
Properties:
Name Type Default Description
dimensions Vec3 0.1,0.1,0.1 The dimensions of the entity. Entity surface outside these dimensions are not lit by the light.
color Color 255,255,255 The color of the light emitted.
intensity number 1 The brightness of the light.
falloffRadius number 0.1 The distance from the light's center at which intensity is reduced by 25%.
isSpotlight boolean false If true then the light is directional, emitting along the entity's local negative z-axis; otherwise the light is a point light which emanates in all directions.
exponent number 0 Affects the softness of the spotlight beam: the higher the value the softer the beam.
cutoff number 1.57 Affects the size of the spotlight beam: the higher the value the larger the beam.
Example

Create a spotlight pointing at the ground.

Entities.addEntity({
  type: "Light",
  position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -4 })),
  rotation: Quat.fromPitchYawRollDegrees(-75, 0, 0),
  dimensions: { x: 5, y: 5, z: 5 },
  intensity: 100,
  falloffRadius: 0.3,
  isSpotlight: true,
  exponent: 20,
  cutoff: 30,
  lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-Line
The "Line" EntityType draws thin, straight lines between a sequence of two or more points. It has properties in addition to the common EntityProperties.
Type: object
Properties:
Name Type Default Description
dimensions Vec3 0.1,0.1,0.1 The dimensions of the entity. Must be sufficient to contain all the linePoints.
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.
lineWidth number 2 Currently not used.
color Color 255,255,255 The color of the line.
Example

Draw lines in a "V".

var entity = Entities.addEntity({
  type: "Line",
  position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -5 })),
  rotation: MyAvatar.orientation,
  dimensions: { x: 2, y: 2, z: 1 },
  linePoints: [
      { x: -1, y: 1, z: 0 },
      { x: 0, y: -1, z: 0 },
      { x: 1, y: 1, z: 0 },
  ],
  color: { red: 255, green: 0, blue: 0 },
  lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-Material
The "Material" EntityType modifies the existing materials on Model entities, Shape entities (albedo only), model overlays, and avatars. It has properties in addition to the common EntityProperties.
To apply a material to an entity or overlay, set the material entity's parentID property to the entity or overlay's 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 clientOnly parameter in Entities.addEntity to true. Material entities render as non-scalable spheres if they don't have their parent set.
Type: object
Properties:
Name Type Default Description
materialURL string "" URL to a MaterialResource. If you append ?name to the URL, the material with that name in the MaterialResource will be applied to the entity.
Alternatively, set the property value to "materialData" to use the materialData property for the MaterialResource values.
priority number 0 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.
parentMaterialName string | number "0" Selects the submesh or submeshes within the parent to apply the material to. If in the format "mat::string", all submeshes with material name "string" are replaced. Otherwise the property value is parsed as an unsigned integer, specifying the mesh index to modify. Invalid values are parsed to 0.
materialMappingMode string "uv" How the material is mapped to the entity. Either "uv" or "projected". Currently, only "uv" is supported.
materialMappingPos Vec2 0,0 Offset position in UV-space of the top left of the material, range { x: 0, y: 0 }{ x: 1, y: 1 }.
materialMappingScale Vec2 1,1 How much to scale the material within the parent's UV-space.
materialMappingRot number 0 How much to rotate the material within the parent's UV-space, in degrees.
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.
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: {
          // Can only set albedo on a Shape entity.
          // Value overrides entity's "color" property.
          albedo: [1.0, 1.0, 0]  // Yellow
      }
  }),
});
EntityProperties-Model
The "Model" EntityType displays an FBX or OBJ model. It has properties in addition to the common EntityProperties.
Type: object
Properties:
Name Type Default Description
dimensions Vec3 0.1,0.1,0.1 The dimensions of the entity. When adding an entity, if no dimensions value is specified then the model is automatically sized to its naturalDimensions.
color Color 255,255,255 Currently not used.
modelURL string "" The URL of the FBX of OBJ model. Baked FBX models' URLs end in ".baked.fbx".
Note: If the name ends with "default-image-model.fbx" then the entity is considered to be an "Image" entity, in which case the textures property should be set per the example.
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.
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.
shapeType ShapeType "none" The shape of the collision hull used if collisions are enabled.
compoundShapeURL string "" The OBJ file to use for the compound shape if shapeType is "compound".
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.
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.
jointTranslations Array.<Vec3> [] Joint translations applied to the model; [] if none are applied or the model hasn't loaded. The array indexes are per getJointIndex. Rotations are relative to each joint's parent.
Joint translations can be set by setLocalJointTranslation and similar functions, or by setting the value of this property. If you set a joint translation using this property you also need to set the corresponding jointTranslationsSet value to true.
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.
relayParentJoints boolean false If true and the entity is parented to an avatar, then the avatar's joint rotations are applied to the entity's joints.
Examples

Rez a Vive tracker puck.

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

Create an "Image" entity like you can in the Create app.

var IMAGE_MODEL = "https://hifi-content.s3.amazonaws.com/DomainContent/production/default-image-model.fbx";
var DEFAULT_IMAGE = "https://hifi-content.s3.amazonaws.com/DomainContent/production/no-image.jpg";
var entity = Entities.addEntity({
  type: "Model",
  position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -3 })),
  rotation: MyAvatar.orientation,
  dimensions: {
      x: 0.5385,
      y: 0.2819,
      z: 0.0092
  },
  shapeType: "box",
  collisionless: true,
  modelURL: IMAGE_MODEL,
  textures: JSON.stringify({ "tex.picture": DEFAULT_IMAGE }),
  lifetime: 300  // Delete after 5 minutes
});
EntityProperties-ParticleEffect
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.
Type: object
Properties:
Name Type Default Description
isEmitting boolean true If true then particles are emitted.
maxParticles number 1000 The maximum number of particles to render at one time. Older particles are deleted if necessary when new ones are created.
lifespan number 3s How long, in seconds, each particle lives.
emitRate number 15 The number of particles per second to emit.
emitSpeed number 5 The speed, in m/s, that each particle is emitted at.
speedSpread number 1 The spread in speeds at which particles are emitted at. If emitSpeed == 5 and speedSpread == 1, particles will be emitted with speeds in the range 4m/s – 6m/s.
emitAcceleration vec3 0,-9.8,0 The acceleration that is applied to each particle during its lifetime. The default is Earth's gravity value.
accelerationSpread vec3 0,0,0 The spread in accelerations that each particle is given. If emitAccelerations == {x: 0, y: -9.8, z: 0} and accelerationSpread == {x: 0, y: 1, z: 0}, each particle will have an acceleration in the range {x: 0, y: -10.8, z: 0}{x: 0, y: -8.8, z: 0}.
dimensions Vec3 The dimensions of the particle effect, i.e., a bounding box containing all the particles during their lifetimes, assuming that emitterShouldTrail is false. Read-only.
emitterShouldTrail boolean false If true then particles are "left behind" as the emitter moves, otherwise they stay with the entity's dimensions.
emitOrientation Quat -0.707,0,0,0.707 The orientation of particle emission relative to the entity's axes. By default, particles emit along the entity's 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.
emitDimensions vec3 0,0,0 The dimensions of the ellipsoid from which particles are emitted.
emitRadiusStart number 1 The starting radius within the ellipsoid at which particles start being emitted; range 0.01.0 for the ellipsoid center to the ellipsoid surface, respectively. Particles are emitted from the portion of the ellipsoid that lies between emitRadiusStart and the ellipsoid's surface.
polarStart number 0 The angle in radians from the entity's local z-axis at which particles start being emitted within the ellipsoid; range 0Math.PI. Particles are emitted from the portion of the ellipsoid that lies between polarStart and polarFinish.
polarFinish number 0 The angle in radians from the entity's local z-axis at which particles stop being emitted within the ellipsoid; range 0Math.PI. Particles are emitted from the portion of the ellipsoid that lies between polarStart and polarFinish.
azimuthStart number -Math.PI 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 ellipsoid that lies between azimuthStart and azimuthFinish.
azimuthFinish number Math.PI 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 ellipsoid that lies between azimuthStart and azimuthFinish.
textures string "" The URL of a JPG or PNG image file to display for each particle. If you want transparency, use PNG format.
particleRadius number 0.025 The radius of each particle at the middle of its life.
radiusStart number NaN The radius of each particle at the start of its life. If NaN, the particleRadius value is used.
radiusFinish number NaN The radius of each particle at the end of its life. If NaN, the particleRadius value is used.
radiusSpread number 0 The spread in radius that each particle is given. If particleRadius == 0.5 and radiusSpread == 0.25, each particle will have a radius in the range 0.250.75.
color Color 255,255,255 The color of each particle at the middle of its life.
colorStart Color {} The color of each particle at the start of its life. If any of the component values are undefined, the color value is used.
colorFinish Color {} The color of each particle at the end of its life. If any of the component values are undefined, the color value is used.
colorSpread Color 0,0,0 The spread in color that each particle is given. If color == {red: 100, green: 100, blue: 100} and colorSpread == {red: 10, green: 25, blue: 50}, each particle will have a color in the range {red: 90, green: 75, blue: 50}{red: 110, green: 125, blue: 150}.
alpha number 1 The alpha of each particle at the middle of its life.
alphaStart number NaN The alpha of each particle at the start of its life. If NaN, the alpha value is used.
alphaFinish number NaN The alpha of each particle at the end of its life. If NaN, the alpha value is used.
alphaSpread number 0 The spread in alpha that each particle is given. If alpha == 0.5 and alphaSpread == 0.25, each particle will have an alpha in the range 0.250.75.
particleSpin number 0 The spin of each particle at the middle of its life. In the range -2*PI2*PI.
spinStart number NaN The spin of each particle at the start of its life. In the range -2*PI2*PI. If NaN, the particleSpin value is used.
spinFinish number NaN The spin of each particle at the end of its life. In the range -2*PI2*PI. If NaN, the particleSpin value is used.
spinSpread number 0 The spread in spin that each particle is given. In the range 02*PI. If particleSpin == PI and spinSpread == PI/2, each particle will have a spin in the range PI/23*PI/2.
rotateWithEntity boolean false Whether or not the particles' spin will rotate with the entity. If false, when particleSpin == 0, the particles will point up in the world. If true, they will point towards the entity's up vector, based on its orientation.
shapeType ShapeType "none" Currently not used. Read-only.
Example

Create a ball of green smoke.

particles = Entities.addEntity({
  type: "ParticleEffect",
  position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -4 })),
  lifespan: 5,
  emitRate: 10,
  emitSpeed: 0.02,
  speedSpread: 0.01,
  emitAcceleration: { x: 0, y: 0.02, z: 0 },
  polarFinish: Math.PI,
  textures: "https://content.highfidelity.com/DomainContent/production/Particles/wispy-smoke.png",
  particleRadius: 0.1,
  color: { red: 0, green: 255, blue: 0 },
  alphaFinish: 0,
  lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-PolyLine
The "PolyLine" EntityType draws textured, straight lines between a sequence of points. It has properties in addition to the common EntityProperties.
Type: object
Properties:
Name Type Default Description
dimensions Vec3 1,1,1 The dimensions of the entity, i.e., the size of the bounding box that contains the lines drawn.
linePoints Array.<Vec3> [] The sequence of points to draw lines between. The values are relative to the entity's position. A maximum of 70 points can be specified. Must be specified in order for the entity to render.
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.
strokeWidths Array.<number> [] The widths, in m, of the line at the linePoints. Must be specified in order for the entity to render.
lineWidth number 2 Currently not used.
strokeColors Array.<Vec3> [] Currently not used.
color Color 255,255,255 The base color of the line, which is multiplied with the color of the texture for rendering.
textures string "" The URL of a JPG or PNG texture to use for the lines. If you want transparency, use PNG format.
isUVModeStretch boolean true If true, the texture is stretched to fill the whole line, otherwise the texture repeats along the line.
Example

Draw a textured "V".

var entity = Entities.addEntity({
  type: "PolyLine",
  position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -5 })),
  rotation: MyAvatar.orientation,
  linePoints: [
      { x: -1, y: 0.5, z: 0 },
      { x: 0, y: 0, z: 0 },
      { x: 1, y: 0.5, z: 0 }
  ],
  normals: [
      { x: 0, y: 0, z: 1 },
      { x: 0, y: 0, z: 1 },
      { x: 0, y: 0, z: 1 }
  ],
  strokeWidths: [ 0.1, 0.1, 0.1 ],
  color: { red: 255, green: 0, blue: 0 },  // Use just the red channel from the image.
  textures: "http://hifi-production.s3.amazonaws.com/DomainContent/Toybox/flowArts/trails.png",
  isUVModeStretch: true,
  lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-PolyVox
The "PolyVox" EntityType displays a set of textured voxels. It has properties in addition to the common EntityProperties. If you have two or more neighboring PolyVox entities of the same size abutting each other, you can display them as joined by configuring their voxelSurfaceStyle and neighbor ID properties.
PolyVox entities uses a library from Volumes of Fun. Their library documentation may be useful to read.
Type: object
Properties:
Name Type Default Description
dimensions Vec3 0.1,0.1,0.1 The dimensions of the entity.
voxelVolumeSize Vec3 32,32,32 Integer number of voxels along each axis of the entity, in the range 1,1,1 to 128,128,128. The dimensions of each voxel is dimensions / voxelVolumesize.
voxelData string "ABAAEAAQAAAAHgAAEAB42u3BAQ0AAADCoPdPbQ8HFAAAAPBuEAAAAQ==" Base-64 encoded compressed dump of the PolyVox data. This property is typically not used in scripts directly; rather, functions that manipulate a PolyVox entity update it.
The size of this property increases with the size and complexity of the PolyVox entity, with the size depending on how the particular entity's voxels compress. Because this property value has to fit within a High Fidelity datagram packet there is a limit to the size and complexity of a PolyVox entity, and edits which would result in an overflow are rejected.
voxelSurfaceStyle Entities.PolyVoxSurfaceStyle 2 The style of rendering the voxels' surface and how neighboring PolyVox entities are joined.
xTextureURL string "" URL of the texture to map to surfaces perpendicular to the entity's local x-axis. JPG or PNG format. If no texture is specified the surfaces display white.
yTextureURL string "" URL of the texture to map to surfaces perpendicular to the entity's local y-axis. JPG or PNG format. If no texture is specified the surfaces display white.
zTextureURL string "" URL of the texture to map to surfaces perpendicular to the entity's local z-axis. JPG or PNG format. If no texture is specified the surfaces display white.
xNNeighborID Uuid Uuid.NULL 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.
yNNeighborID Uuid Uuid.NULL 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.
zNNeighborID Uuid Uuid.NULL 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.
xPNeighborID Uuid Uuid.NULL 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.
yPNeighborID Uuid Uuid.NULL 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.
zPNeighborID Uuid Uuid.NULL 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.
Example

Create a textured PolyVox sphere.

var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.5, z: -8 }));
var texture = "http://public.highfidelity.com/cozza13/tuscany/Concrete2.jpg";
var polyVox = Entities.addEntity({
  type: "PolyVox",
  position: position,
  dimensions: { x: 2, y: 2, z: 2 },
  xTextureURL: texture,
  yTextureURL: texture,
  zTextureURL: texture,
  lifetime: 300  // Delete after 5 minutes.
});
Entities.setVoxelSphere(polyVox, position, 0.8, 255);
EntityProperties-Shape
The "Shape" EntityType displays an entity of a specified shape. It has properties in addition to the common EntityProperties.
Type: object
Properties:
Name Type Default Description
shape Entities.Shape "Sphere" The shape of the entity.
dimensions Vec3 0.1,0.1,0.1 The dimensions of the entity.
color Color 255,255,255 The color of the entity.
Example

Create a cylinder.

var shape = Entities.addEntity({
  type: "Shape",
  shape: "Cylinder",
  position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
  dimensions: { x: 0.4, y: 0.6, z: 0.4 },
  lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-Sphere
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".
Type: object
EntityProperties-Text
The "Text" EntityType displays a 2D rectangle of text in the domain. It has properties in addition to the common EntityProperties.
Type: object
Properties:
Name Type Default Description
dimensions Vec3 0.1,0.1,0.01 The dimensions of the entity.
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.
lineHeight number 0.1 The height of each line of text (thus determining the font size).
textColor Color 255,255,255 The color of the text.
backgroundColor Color 0,0,0 The color of the background rectangle.
faceCamera boolean false If true, the entity is oriented to face each user's camera (i.e., it differs for each user present).
Example

Create a text entity.

var text = Entities.addEntity({
  type: "Text",
  position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
  dimensions: { x: 0.6, y: 0.3, z: 0.01 },
  lineHeight: 0.12,
  text: "Hello\nthere!",
  faceCamera: true,
  lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-Web
The "Web" EntityType displays a browsable Web page. Each user views their own copy of the Web page: if one user navigates to another page on the entity, other users do not see the change; if a video is being played, users don't see it in sync. The entity has properties in addition to the common EntityProperties.
Type: object
Properties:
Name Type Default Description
dimensions Vec3 0.1,0.1,0.01 The dimensions of the entity.
sourceUrl string "" The URL of the Web page to display. This value does not change as you or others navigate on the Web entity.
dpi number 30 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.
Example

Create a Web entity displaying at 1920 x 1080 resolution.

var METERS_TO_INCHES = 39.3701;
var entity = Entities.addEntity({
  type: "Web",
  sourceUrl: "https://highfidelity.com/",
  position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -4 })),
  rotation: MyAvatar.orientation,
  dimensions: {
      x: 3,
      y: 3 * 1080 / 1920,
      z: 0.01
  },
  dpi: 1920 / (3 * METERS_TO_INCHES),
  lifetime: 300  // Delete after 5 minutes.
});
EntityProperties-Zone
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.
Type: object
Properties:
Name Type Default Description
dimensions Vec3 0.1,0.1,0.1 The size of the volume in which the zone's lighting effects and avatar permissions have effect.
shapeType ShapeType "box" The shape of the volume in which the zone's lighting effects and avatar permissions have effect. Reverts to the default value if set to "none", or set to "compound" and compoundShapeURL is "".
compoundShapeURL string "" The OBJ file to use for the compound shape if shapeType is "compound".
keyLightMode string "inherit" Configures the key light in the zone. Possible values:
"inherit": The key light from any enclosing zone continues into this zone.
"disabled": The key light from any enclosing zone and the key light of this zone are disabled in this zone.
"enabled": The key light properties of this zone are enabled, overriding the key light of from any enclosing zone.
keyLight Entities.KeyLight The key light properties of the zone.
ambientLightMode string "inherit" Configures the ambient light in the zone. Possible values:
"inherit": The ambient light from any enclosing zone continues into this zone.
"disabled": The ambient light from any enclosing zone and the ambient light of this zone are disabled in this zone.
"enabled": The ambient light properties of this zone are enabled, overriding the ambient light from any enclosing zone.
ambientLight Entities.AmbientLight The ambient light properties of the zone.
skyboxMode string "inherit" Configures the skybox displayed in the zone. Possible values:
"inherit": The skybox from any enclosing zone is dislayed in this zone.
"disabled": The skybox from any enclosing zone and the skybox of this zone are disabled in this zone.
"enabled": The skybox properties of this zone are enabled, overriding the skybox from any enclosing zone.
skybox Entities.Skybox The skybox properties of the zone.
hazeMode string "inherit" Configures the haze in the zone. Possible values:
"inherit": The haze from any enclosing zone continues into this zone.
"disabled": The haze from any enclosing zone and the haze of this zone are disabled in this zone.
"enabled": The haze properties of this zone are enabled, overriding the haze from any enclosing zone.
haze Entities.Haze The haze properties of the zone.
bloomMode string "inherit" Configures the bloom in the zone. Possible values:
"inherit": The bloom from any enclosing zone continues into this zone.
"disabled": The bloom from any enclosing zone and the bloom of this zone are disabled in this zone.
"enabled": The bloom properties of this zone are enabled, overriding the bloom from any enclosing zone.
bloom Entities.Bloom The bloom properties of the zone.
flyingAllowed boolean true If true then visitors can fly in the zone; otherwise they cannot.
ghostingAllowed boolean true If true then visitors with avatar collisions turned off will not collide with content in the zone; otherwise visitors will always collide with content in the zone.
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) {
  // Test and edit properties object values,
  // e.g., properties.modelURL, as required.
  return properties;
}
Example

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

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

An entity may be one of the following types:

Value Description Properties
"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
"Light" A local lighting effect. EntityProperties-Light
"Line" A sequence of one or more simple straight lines. EntityProperties-Line
"Material" Modifies the existing materials on Model entities, Shape entities (albedo only), model overlays, and avatars. EntityProperties-Material
"Model" A mesh model from an FBX or OBJ file. EntityProperties-Model
"ParticleEffect" A particle system that can be used to simulate things such as fire, smoke, snow, magic spells, etc. EntityProperties-ParticleEffect
"PolyLine" A sequence of one or more textured straight lines. EntityProperties-PolyLine
"PolyVox" A set of textured voxels. EntityProperties-PolyVox
"Shape" A basic entity such as a cube. See also, the "Box" and "Sphere" entity types. EntityProperties-Shape
"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
"Text" A pane of text oriented in space. EntityProperties-Text
"Web" A browsable Web page. EntityProperties-Web
"Zone" A volume of lighting effects and avatar permissions. EntityProperties-Zone
Type: string
Haze
Haze is defined by the following properties.
Type: object
Properties:
Name Type Default Description
hazeRange number 1000 The horizontal distance at which visibility is reduced to 95%; i.e., 95% of each pixel's color is haze.
hazeColor Color 128,154,179 The color of the haze when looking away from the key light.
hazeEnableGlare boolean false If true then the haze is colored with glare from the key light; hazeGlareColor and hazeGlareAngle are used.
hazeGlareColor Color 255,299,179 The color of the haze when looking towards the key light.
hazeGlareAngle number 20 The angle in degrees across the circle around the key light that the glare color and haze color are blended 50/50.
hazeAltitudeEffect boolean false If true then haze decreases with altitude as defined by the entity's local coordinate system; hazeBaseRef and hazeCeiling are used.
hazeBaseRef number 0 The y-axis value in the entity's local coordinate system at which the haze density starts reducing with altitude.
hazeCeiling number 200 The y-axis value in the entity's local coordinate system at which the haze density has reduced to 5%.
hazeBackgroundBlend number 0 The proportion of the skybox image to show through the haze: 0.0 displays no skybox image; 1.0 displays no haze.
hazeAttenuateKeyLight boolean false Currently not supported.
hazeKeyLightRange number 1000 Currently not supported.
hazeKeyLightAltitude number 200 Currently not supported.
KeyLight
A key light is defined by the following properties.
Type: object
Properties:
Name Type Default Description
color Color 255,255,255 The color of the light.
intensity number 1 The intensity of the light.
direction Vec3 0,-1,0 The direction the light is shining.
castShadows boolean false If true then shadows are cast. Shadows are cast by avatars, plus Model and Shape entities that have their canCastShadow property set to true.
PhysicsMotionType

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

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

A PolyVoxSurfaceStyle may be one of the following:

Value Type Description
0 Marching cubes. Chamfered edges. Open volume. Joins neighboring PolyVox entities reasonably well.
1 Cubic. Square edges. Open volume. Joins neighboring PolyVox entities cleanly.
2 Edged cubic. Square edges. Enclosed volume. Joins neighboring PolyVox entities cleanly.
3 Edged marching cubes. Chamfered edges. Enclosed volume. Doesn't join neighboring PolyVox entities.
Type: number
RayToEntityIntersectionResult
The result of a PickRay search using findRayIntersection or findRayIntersectionBlocking.
Type: object
Properties:
Name Type Description
intersects boolean true if the PickRay intersected an entity, otherwise false.
accurate boolean Is always true.
entityID Uuid The ID if the entity intersected, if any, otherwise null.
distance number The distance from the PickRay origin to the intersection point.
intersection Vec3 The intersection point.
surfaceNormal Vec3 The surface normal of the entity at the intersection point.
face BoxFace The face of the entity's axis-aligned box that the ray intersects.
extraInfo object Extra information depending on the entity intersected. Currently, only Model entities provide extra information, and the information provided depends on the precisionPicking parameter value that the search function was called with.
RenderInfo
Information on how an entity is rendered. Properties are only filled in for Model entities; other entity types have an empty object, {}.
Type: object
Properties:
Name Type Description
verticesCount number The number of vertices in the entity.
texturesCount number The number of textures in the entity.
textureSize number The total size of the textures in the entity, in bytes.
hasTransparent boolean Is true if any of the textures has transparency.
drawCalls number The number of draw calls required to render the entity.
Shape

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

Value Dimensions Notes
"Circle" 2D A circle oriented in 3D.
"Cube" 3D
"Cone" 3D
"Cylinder" 3D
"Dodecahedron" 3D
"Hexagon" 3D A hexagonal prism.
"Icosahedron" 3D
"Octagon" 3D An octagonal prism.
"Octahedron" 3D
"Quad" 2D A square oriented in 3D.
"Sphere" 3D
"Tetrahedron" 3D
"Torus" 3D Not implemented.
"Triangle" 3D A triangular prism.
Type: string
Skybox
A skybox is defined by the following properties.
Type: object
Properties:
Name Type Default Description
color Color 0,0,0 Sets the color of the sky if url is "", otherwise modifies the color of the cube map image.
url string "" A cube map image that is used to render the sky.
getMeshesCallback(meshes, success)
Called when Entities.getMeshes is complete.
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.
Deprecated:
Use the Graphics API instead.
getServerScriptStatusCallback(success, isRunning, status, errorInfo)
Called when Entities.getServerScriptStatus 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)
Called when Entities.queryPropertyMetadata 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.