Global

• Methods • Type Definitions • Method Details •

Methods

Name Return Value Summary
print None

Prints a message to the program log and emits Script.printedMessage. The message logged is the message values separated by spaces.

Alternatively, you can use Script.print or one of the console API methods.

Type Definitions

AACube
Type: object

An axis-aligned cube, defined as the bottom right near (minimum axes values) corner of the cube plus the dimension of its sides.

Properties

Name Type Summary
x number

X coordinate of the brn corner of the cube.
y number

Y coordinate of the brn corner of the cube.
z number

Z coordinate of the brn corner of the cube.
scale number

The dimensions of each side of the cube.
AntialiasingMode
Type: number

Antialiasing modes.

ValueNameDescription
0NONEAntialiasing is disabled.
1TAATemporal Antialiasing.
2FXAAFXAA.
3MODE_COUNTInducates number of antialiasing modes
AttachmentData
Type: object

Information on an attachment worn by the avatar.

Properties

Name Type Summary
modelUrl string

The URL of the glTF, FBX, or OBJ model file. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs respectively).
jointName string

The name of the joint that the attachment is parented to.
translation Vec3

The offset from the joint that the attachment is positioned at.
rotation Vec3

The rotation applied to the model relative to the joint orientation.
scale number

The scale applied to the attachment model.
soft boolean

If true and the model has a skeleton, the bones of the attached model's skeleton are rotated to fit the avatar's current pose. If true, the translation, rotation, and scale parameters are ignored.
AvatarDataRate
Type: string

The avatar mixer data comprises different types of data, with the data rates of each being tracked in kbps.

Rate NameDescription
"globalPosition"Incoming global position.
"localPosition"Incoming local position.
"handControllers"Incoming hand controllers.
"avatarBoundingBox"Incoming avatar bounding box.
"avatarOrientation"Incoming avatar orientation.
"avatarScale"Incoming avatar scale.
"lookAtPosition"Incoming look-at position.
"audioLoudness"Incoming audio loudness.
"sensorToWorkMatrix"Incoming sensor-to-world matrix.
"additionalFlags"Incoming additional avatar flags.
"parentInfo"Incoming parent information.
"faceTracker"Incoming face tracker data.
"jointData"Incoming joint data.
"jointDefaultPoseFlagsRate"Incoming joint default pose flags.
"farGrabJointRate"Incoming far grab joint.
"globalPositionOutbound"Outgoing global position.
"localPositionOutbound"Outgoing local position.
"avatarBoundingBoxOutbound"Outgoing avatar bounding box.
"avatarOrientationOutbound"Outgoing avatar orientation.
"avatarScaleOutbound"Outgoing avatar scale.
"lookAtPositionOutbound"Outgoing look-at position.
"audioLoudnessOutbound"Outgoing audio loudness.
"sensorToWorkMatrixOutbound"Outgoing sensor-to-world matrix.
"additionalFlagsOutbound"Outgoing additional avatar flags.
"parentInfoOutbound"Outgoing parent information.
"faceTrackerOutbound"Outgoing face tracker data.
"jointDataOutbound"Outgoing joint data.
"jointDefaultPoseFlagsOutbound"Outgoing joint default pose flags.
""When no rate name is specified, the total incoming data rate is provided.
AvatarEntityMap
Type: Object.<Uuid, Entities.EntityProperties>

An object with the UUIDs of avatar entities as keys and avatar entity properties objects as values.
AvatarSimulationRate
Type: string

An avatar has different types of data simulated at different rates, in Hz.

Rate NameDescription
"avatar" or ""The rate at which the avatar is updated even if not in view.
"avatarInView"The rate at which the avatar is updated if in view.
"skeletonModel"The rate at which the skeleton model is being updated, even if there are no joint data available.
"jointData"The rate at which joint data are being updated.
""When no rate name is specified, the "avatar" update rate is provided.
AvatarUpdateRate
Type: string

The avatar mixer data comprises different types of data updated at different rates, in Hz.

Rate NameDescription
"globalPosition"Global position.
"localPosition"Local position.
"handControllers"Hand controller positions and orientations.
"avatarBoundingBox"Avatar bounding box.
"avatarOrientation"Avatar orientation.
"avatarScale"Avatar scale.
"lookAtPosition"Look-at position.
"audioLoudness"Audio loudness.
"sensorToWorkMatrix"Sensor-to-world matrix.
"additionalFlags"Additional avatar flags.
"parentInfo"Parent information.
"faceTracker"Face tracker data.
"jointData"Joint data.
"farGrabJointData"Far grab joint data.
""When no rate name is specified, the overall update rate is provided.
BanFlags
Type: number

A set of flags for moderation ban actions. The value is constructed by using the | (bitwise OR) operator on the individual flag values.

Flag NameValueDescription
NO_BAN0Don't ban user when kicking. This does not currently have an effect.
BAN_BY_USERNAME1Ban the person by their username.
BAN_BY_FINGERPRINT2Ban the person by their machine fingerprint.
BAN_BY_IP4Ban the person by their IP address.
BillboardMode
Type: string

How an entity is billboarded.

ValueDescription
"none"The entity will not be billboarded.
"yaw"The entity will yaw, but not pitch, to face the camera. Its actual rotation will be ignored.
"full"The entity will yaw and pitch to face the camera. Its actual rotation will be ignored.
BoxFace
Type: string

A BoxFace specifies the face of an axis-aligned (AA) box.

ValueDescription
"MIN_X_FACE"The minimum x-axis face.
"MAX_X_FACE"The maximum x-axis face.
"MIN_Y_FACE"The minimum y-axis face.
"MAX_Y_FACE"The maximum y-axis face.
"MIN_Z_FACE"The minimum z-axis face.
"MAX_Z_FACE"The maximum z-axis face.
"UNKNOWN_FACE"Unknown value.
Collision
Type: object

Details of a collision between avatars and entities.

Properties

Name Type Summary
type ContactEventType

The contact type of the collision event.
idA Uuid

The ID of one of the avatars or entities in the collision.
idB Uuid

The ID of the other of the avatars or entities in the collision.
penetration Vec3

The amount of penetration between the two items.
contactPoint Vec3

The point of contact.
velocityChange Vec3

The change in relative velocity of the two items, in m/s.
Collision
Type: object

Details of a collision between avatars and entities.

Properties

Name Type Summary
type ContactEventType

The contact type of the collision event.
idA Uuid

The ID of one of the avatars or entities in the collision.
idB Uuid

The ID of the other of the avatars or entities in the collision.
penetration Vec3

The amount of penetration between the two items.
contactPoint Vec3

The point of contact.
velocityChange Vec3

The change in relative velocity of the two items, in m/s.
CollisionContact
Type: object

A pair of points that represents part of an overlap between a CollisionPick and an object in the physics engine. Points which are further apart represent deeper overlap.

Properties

Name Type Summary
pointOnPick Vec3

A point representing a penetration of the object's surface into the volume of the pick, in world coordinates.
pointOnObject Vec3

A point representing a penetration of the pick's surface into the volume of the object, in world coordinates.
normalOnPick Vec3

The normal vector pointing away from the pick, representing the direction of collision.
CollisionMask
Type: number

A collision may occur with the following types of items:

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

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

An intersection result for a collision pick.

Properties

Name Type Summary
intersects boolean

true if there is at least one intersection, false if there isn't.
intersectingObjects Array.<IntersectingObject>

All objects which intersect with the collisionRegion.
collisionRegion CollisionRegion

The collision region that was used. Valid even if there was no intersection.
CollisionRegion
Type: object

A volume for checking collisions in the physics simulation.

Properties

Name Type Attributes Summary
shape Shape

The collision region's shape and size. Dimensions are in world coordinates, but scale with the parent if defined.
loaded boolean

true if the shape has no model, or has a model and it is loaded, false if otherwise.
position Vec3

The position of the collision region, relative to the parent if defined.
orientation Quat

The orientation of the collision region, relative to the parent if defined.
threshold number

The approximate minimum penetration depth for a test object to be considered in contact with the collision region. The depth is in world coordinates but scales with the parent if defined.
collisionGroup CollisionMask <optional>

The type of objects the collision region collides as. Objects whose collision masks overlap with the region's collision group are considered to be colliding with the region.

Default Value: 8

Color
Type: object

A color vector. See also the Vec3 object.

Properties

Name Type Summary
red number

Red component value. Integer in the range 0 - 255. Synonyms: r, x.
green number

Green component value. Integer in the range 0 - 255. Synonyms: g, y.
blue number

Blue component value. Integer in the range 0 - 255. Synonyms: b, z.
Example

Colors can be set in multiple ways and modified with their aliases, but still stringify in the same way

Entities.editEntity(<id>, { color: { x: 1, y: 2, z: 3 }});                 // { red: 1, green: 2, blue: 3 }
Entities.editEntity(<id>, { color: { r: 4, g: 5, b: 6 }});                 // { red: 4, green: 5, blue: 6 }
Entities.editEntity(<id>, { color: { red: 7, green: 8, blue: 9 }});        // { red: 7, green: 8, blue: 9 }
Entities.editEntity(<id>, { color: [10, 11, 12] });                        // { red: 10, green: 11, blue: 12 }
Entities.editEntity(<id>, { color: 13 });                                  // { red: 13, green: 13, blue: 13 }
var color = Entities.getEntityProperties(<id>).color;                      // { red: 13, green: 13, blue: 13 }
color.g = 14;                                                              // { red: 13, green: 14, blue: 13 }
color.blue = 15;                                                           // { red: 13, green: 14, blue: 15 }
Entities.editEntity(<id>, { color: "red"});                                // { red: 255, green: 0, blue: 0 }
Entities.editEntity(<id>, { color: "#00FF00"});                            // { red: 0, green: 255, blue: 0 }
Color
Type: object

A color vector. See also the Vec3 object.

Properties

Name Type Summary
red number

Red component value. Integer in the range 0 - 255. Synonyms: r, x.
green number

Green component value. Integer in the range 0 - 255. Synonyms: g, y.
blue number

Blue component value. Integer in the range 0 - 255. Synonyms: b, z.
Example

Colors can be set in multiple ways and modified with their aliases, but still stringify in the same way

Entities.editEntity(<id>, { color: { x: 1, y: 2, z: 3 }});                 // { red: 1, green: 2, blue: 3 }
Entities.editEntity(<id>, { color: { r: 4, g: 5, b: 6 }});                 // { red: 4, green: 5, blue: 6 }
Entities.editEntity(<id>, { color: { red: 7, green: 8, blue: 9 }});        // { red: 7, green: 8, blue: 9 }
Entities.editEntity(<id>, { color: [10, 11, 12] });                        // { red: 10, green: 11, blue: 12 }
Entities.editEntity(<id>, { color: 13 });                                  // { red: 13, green: 13, blue: 13 }
var color = Entities.getEntityProperties(<id>).color;                      // { red: 13, green: 13, blue: 13 }
color.g = 14;                                                              // { red: 13, green: 14, blue: 13 }
color.blue = 15;                                                           // { red: 13, green: 14, blue: 15 }
Entities.editEntity(<id>, { color: "red"});                                // { red: 255, green: 0, blue: 0 }
Entities.editEntity(<id>, { color: "#00FF00"});                            // { red: 0, green: 255, blue: 0 }
ColorFloat
Type: object

A color vector with real values. Values may also be null. See also the Vec3 object.

Properties

Name Type Summary
red number

Red component value. Real in the range 0 - 255. Synonyms: r, x.
green number

Green component value. Real in the range 0 - 255. Synonyms: g, y.
blue number

Blue component value. Real in the range 0 - 255. Synonyms: b, z.
Example

ColorFloats can be set in multiple ways and modified with their aliases, but still stringify in the same way

Entities.editEntity(<id>, { color: { x: 1, y: 2, z: 3 }});                 // { red: 1, green: 2, blue: 3 }
Entities.editEntity(<id>, { color: { r: 4, g: 5, b: 6 }});                 // { red: 4, green: 5, blue: 6 }
Entities.editEntity(<id>, { color: { red: 7, green: 8, blue: 9 }});        // { red: 7, green: 8, blue: 9 }
Entities.editEntity(<id>, { color: [10, 11, 12] });                        // { red: 10, green: 11, blue: 12 }
Entities.editEntity(<id>, { color: 13 });                                  // { red: 13, green: 13, blue: 13 }
var color = Entities.getEntityProperties(<id>).color;                      // { red: 13, green: 13, blue: 13 }
color.g = 14;                                                              // { red: 13, green: 14, blue: 13 }
color.blue = 15;                                                           // { red: 13, green: 14, blue: 15 }
Entities.editEntity(<id>, { color: "red"});                                // { red: 255, green: 0, blue: 0 }
Entities.editEntity(<id>, { color: "#00FF00"});                            // { red: 0, green: 255, blue: 0 }
ColorFloat
Type: object

A color vector with real values. Values may also be null. See also the Vec3 object.

Properties

Name Type Summary
red number

Red component value. Real in the range 0 - 255. Synonyms: r, x.
green number

Green component value. Real in the range 0 - 255. Synonyms: g, y.
blue number

Blue component value. Real in the range 0 - 255. Synonyms: b, z.
Example

ColorFloats can be set in multiple ways and modified with their aliases, but still stringify in the same way

Entities.editEntity(<id>, { color: { x: 1, y: 2, z: 3 }});                 // { red: 1, green: 2, blue: 3 }
Entities.editEntity(<id>, { color: { r: 4, g: 5, b: 6 }});                 // { red: 4, green: 5, blue: 6 }
Entities.editEntity(<id>, { color: { red: 7, green: 8, blue: 9 }});        // { red: 7, green: 8, blue: 9 }
Entities.editEntity(<id>, { color: [10, 11, 12] });                        // { red: 10, green: 11, blue: 12 }
Entities.editEntity(<id>, { color: 13 });                                  // { red: 13, green: 13, blue: 13 }
var color = Entities.getEntityProperties(<id>).color;                      // { red: 13, green: 13, blue: 13 }
color.g = 14;                                                              // { red: 13, green: 14, blue: 13 }
color.blue = 15;                                                           // { red: 13, green: 14, blue: 15 }
Entities.editEntity(<id>, { color: "red"});                                // { red: 255, green: 0, blue: 0 }
Entities.editEntity(<id>, { color: "#00FF00"});                            // { red: 0, green: 255, blue: 0 }
ContactEventType
Type: number

The type of a collision contact event.

ValueDescription
0Start of the collision.
1Continuation of the collision.
2End of the collision.
DriveKey
Type: number

Logical keys that drive your avatar and camera.

ValueDescription
DriveKeys.TRANSLATE_XMove the user's avatar in the direction of its x-axis, if the camera isn't in independent or mirror modes.
DriveKeys.TRANSLATE_YMove the user's avatar in the direction of its -axis, if the camera isn't in independent or mirror modes.
DriveKeys.TRANSLATE_ZMove the user's avatar in the direction of its z-axis, if the camera isn't in independent or mirror modes.
DriveKeys.YAWRotate the user's avatar about its y-axis at a rate proportional to the control value, if the camera isn't in independent or mirror modes.
DriveKeys.STEP_TRANSLATE_XNo action.
DriveKeys.STEP_TRANSLATE_YNo action.
DriveKeys.STEP_TRANSLATE_ZNo action.
DriveKeys.STEP_YAWRotate the user's avatar about its y-axis in a step increment, if the camera isn't in independent or mirror modes.
DriveKeys.PITCHRotate the user's avatar head and attached camera about its negative x-axis (i.e., positive values pitch down) at a rate proportional to the control value, if the camera isn't in HMD, independent, or mirror modes.
DriveKeys.ZOOMZoom the camera in or out.
DriveKeys.DELTA_YAWRotate the user's avatar about its y-axis by an amount proportional to the control value, if the camera isn't in independent or mirror modes.
DriveKeys.DELTA_PITCHRotate the user's avatar head and attached camera about its negative x-axis (i.e., positive values pitch down) by an amount proportional to the control value, if the camera isn't in HMD, independent, or mirror modes.
FilterFlags
Type: number

A set of flags for a pick filter. The value is constructed by using the | (bitwise OR) operator on the individual flag values.

Flag NameValueDescription
PICK_DOMAIN_ENTITIES1Include domain entities when intersecting.
PICK_AVATAR_ENTITIES2Include avatar entities when intersecting.
PICK_LOCAL_ENTITIES4Include local entities when intersecting.
PICK_AVATATRS8Include avatars when intersecting.
PICK_HUD16Include the HUD surface when intersecting in HMD mode.
PICK_INCLUDE_VISIBLE32Include visible objects when intersecting.
PICK_INCLUDE_INVISIBLE64Include invisible objects when intersecting.
PICK_INCLUDE_COLLIDABLE128Include collidable objects when intersecting.
PICK_INCLUDE_NONCOLLIDABLE256Include non-collidable objects when intersecting.
PICK_PRECISE512Pick against exact meshes.
PICK_COARSE1024Pick against coarse meshes.
PICK_ALL_INTERSECTIONS2048Return all intersections instead of just the closest.
HandState
Type: number

The pointing state of the hands is specified by the following values:

ValueDescription
0No hand is pointing.
1The left hand is pointing.
2The right hand is pointing.
4It is the index finger that is pointing.

The values for the hand states are added together to give the HandState value. For example, if the left hand's finger is pointing, the value is 1 + 4 == 5.

IntersectingObject
Type: object

Information about a CollisionPick's intersection with an object.

Properties

Name Type Summary
id Uuid

The ID of the object.
type IntersectionType

The type of the object, either 1 for INTERSECTED_ENTITY or 3 for INTERSECTED_AVATAR.
collisionContacts Array.<CollisionContact>

Information on the penetration between the pick and the object.
IntersectionType
Type: number

The type of an intersection.

NameValueDescription
INTERSECTED_NONE0Intersected nothing.
INTERSECTED_ENTITY1Intersected an entity.
INTERSECTED_LOCAL_ENTITY2Intersected a local entity.
INTERSECTED_AVATAR3Intersected an avatar.
INTERSECTED_HUD4Intersected the HUD surface.
KeyEvent
Type: object

A keyboard key event.

Properties

Name Type Summary
key number

The Qt keyboard code of the key pressed. For a list of keyboard codes, see http://doc.qt.io/qt-5/qt.html#Key-enum.
text string

A string describing the key. For example, "a" for the "A" key if the Shift is not pressed, "F1" for the F1 key, "SPACE" for the space bar.
isShifted boolean

true if a Shift key was pressed when the event was generated, otherwise false.
isMeta boolean

true if a meta key was pressed when the event was generated, otherwise false. On Windows the "meta" key is the Windows key; on OSX it is the Control (Splat) key.
isControl boolean

true if a control key was pressed when the event was generated, otherwise false. On Windows the "control" key is the Ctrl key; on OSX it is the Command key.
isAlt boolean

true if an Alt key was pressed when the event was generated, otherwise false.
isKeypad boolean

true if the key is on the numeric keypad, otherwise false.
isAutoRepeat boolean

true if the event is a repeat for key that is being held down, otherwise false.
Example

Report the KeyEvent details for each key press.

Controller.keyPressEvent.connect(function (event) {
    print(JSON.stringify(event));
});
KeyboardModifiers
Type: number

A KeyboardModifiers value is used to specify which modifier keys on the keyboard are pressed. The value is the sum (bitwise OR) of the relevant combination of values from the following table:

KeyHexadecimal valueDecimal valueDescription
Shift0x0200000033554432 A Shift key on the keyboard is pressed.
Control0x0400000067108864 A control key on the keyboard is pressed. On Windows the "control" key is the Ctrl key; on OSX it is the Command key.
Alt0x08000000134217728 An Alt key on the keyboard is pressed.
Meta0x10000000268435456 A meta key on the keyboard is pressed. On Windows the "meta" key is the Windows key; on OSX it is the Control (Splat) key.
Keypad0x20000000536870912 A keypad button is pressed.
Group0x400000001073741824 X11 operating system only: An AltGr / Mode_switch key on the keyboard is pressed.
Mat4
Type: object

A 4 x 4 matrix, typically containing a scale, rotation, and translation transform. See also the Mat4 object.

Properties

Name Type Summary
r0c0 number

Row 0, column 0 value.
r1c0 number

Row 1, column 0 value.
r2c0 number

Row 2, column 0 value.
r3c0 number

Row 3, column 0 value.
r0c1 number

Row 0, column 1 value.
r1c1 number

Row 1, column 1 value.
r2c1 number

Row 2, column 1 value.
r3c1 number

Row 3, column 1 value.
r0c2 number

Row 0, column 2 value.
r1c2 number

Row 1, column 2 value.
r2c2 number

Row 2, column 2 value.
r3c2 number

Row 3, column 2 value.
r0c3 number

Row 0, column 3 value.
r1c3 number

Row 1, column 3 value.
r2c3 number

Row 2, column 3 value.
r3c3 number

Row 3, column 3 value.
Mat4
Type: object

A 4 x 4 matrix, typically containing a scale, rotation, and translation transform. See also the Mat4 object.

Properties

Name Type Summary
r0c0 number

Row 0, column 0 value.
r1c0 number

Row 1, column 0 value.
r2c0 number

Row 2, column 0 value.
r3c0 number

Row 3, column 0 value.
r0c1 number

Row 0, column 1 value.
r1c1 number

Row 1, column 1 value.
r2c1 number

Row 2, column 1 value.
r3c1 number

Row 3, column 1 value.
r0c2 number

Row 0, column 2 value.
r1c2 number

Row 1, column 2 value.
r2c2 number

Row 2, column 2 value.
r3c2 number

Row 3, column 2 value.
r0c3 number

Row 0, column 3 value.
r1c3 number

Row 1, column 3 value.
r2c3 number

Row 2, column 3 value.
r3c3 number

Row 3, column 3 value.
MeshFace
Type: object

A triangle in a mesh.

Properties

Name Type Summary
vertices Array.<number>

The indexes of the three vertices that make up the face.
MouseEvent
Type: object

A controller mouse movement or button event.

Properties

Name Type Summary
x number

Integer x-coordinate of the event on the Interface window or HMD HUD.
y number

Integer y-coordinate of the event on the Interface window or HMD HUD.
button string

"LEFT", "MIDDLE", or "RIGHT" if a button press or release caused the event, otherwise "NONE".
isLeftButton boolean

true if the left button was pressed when the event was generated, otherwise false.
isMiddleButton boolean

true if the middle button was pressed when the event was generated, otherwise false.
isRightButton boolean

true if the right button was pressed when the event was generated, otherwise false.
isShifted boolean

true if the Shift key was pressed when the event was generated, otherwise false.
isMeta boolean

true if the "meta" key was pressed when the event was generated, otherwise false. On Windows the "meta" key is the Windows key; on OSX it is the Control (Splat) key.
isControl boolean

true if the "control" key was pressed when the event was generated, otherwise false. On Windows the "control" key is the Ctrl key; on OSX it is the Command key.
isAlt boolean

true if the Alt key was pressed when the event was generated, otherwise false.
Example

Report the MouseEvent details for each mouse move.

Controller.mouseMoveEvent.connect(function (event) {
    print(JSON.stringify(event));
});
ParabolaPickResult
Type: object

An intersection result for a parabola pick.

Properties

Name Type Summary
type number

The intersection type.
intersects boolean

true if there's a valid intersection, false if there isn't.
objectID Uuid

The ID of the intersected object. null for HUD or invalid intersections.
distance number

The distance from the parabola origin to the intersection point in a straight line.
parabolicDistance number

The distance from the parabola origin to the intersection point along the arc of the parabola.
intersection Vec3

The intersection point in world coordinates.
surfaceNormal Vec3

The surface normal at the intersected point. All NaNs if type == Picks.INTERSECTED_HUD.
extraInfo SubmeshIntersection

Additional intersection details for model objects, otherwise { }.
parabola PickParabola

The pick parabola that was used. Valid even if there is no intersection.
PickParabola
Type: object

A parabola defined by a starting point, initial velocity, and acceleration. It is used, for example, when finding entities or avatars that intersect a parabolic beam.

Properties

Name Type Summary
origin Vec3

The starting position of the parabola, i.e., the initial position of a virtual projectile whose trajectory defines the parabola.
velocity Vec3

The starting velocity of the parabola in m/s, i.e., the initial speed of a virtual projectile whose trajectory defines the parabola.
acceleration Vec3

The acceleration that the parabola experiences in m/s2, i.e., the acceleration of a virtual projectile whose trajectory defines the parabola, both magnitude and direction.
PickRay
Type: object

A vector with a starting point. It is used, for example, when finding entities or avatars that lie under a mouse click or intersect a laser beam.

Properties

Name Type Summary
origin Vec3

The starting position of the ray.
direction Vec3

The direction that the ray travels.
PickType
Type: number

A type of pick.

ValueDescription
PickType.RayRay picks intersect a ray with objects in front of them, along their direction.
PickType.ParabolaParabola picks intersect a parabola with objects in front of them, along their arc.
PickType.StylusStylus picks provide "tapping" functionality on or into flat surfaces.
PickType.CollisionCollision picks intersect a collision volume with avatars and entities that have collisions.
PointerEvent
Type: object

A 2D or 3D mouse or similar pointer event.

Properties

Name Type Summary
type string

The type of event: "Press", "DoublePress", "Release", or "Move".
id number

Integer number used to identify the pointer: 0 = hardware mouse, 1 = left controller, 2 = right controller.
pos2D Vec2

The 2D position of the event on the intersected object XY plane, where applicable.
pos3D Vec3

The 3D position of the event on the intersected object, where applicable.
normal Vec3

The surface normal at the intersection point.
direction Vec3

The direction of the intersection ray.
button string

The name of the button pressed: None, Primary, Secondary, or Tertiary.
isPrimaryButton boolean

true if the button pressed was the primary button, otherwise undefined;
isLeftButton boolean

true if the button pressed was the primary button, otherwise undefined;
isSecondaryButton boolean

true if the button pressed was the secondary button, otherwise undefined;
isRightButton boolean

true if the button pressed was the secondary button, otherwise undefined;
isTertiaryButton boolean

true if the button pressed was the tertiary button, otherwise undefined;
isMiddleButton boolean

true if the button pressed was the tertiary button, otherwise undefined;
isPrimaryHeld boolean

true if the primary button is currently being pressed, otherwise false
isSecondaryHeld boolean

true if the secondary button is currently being pressed, otherwise false
isTertiaryHeld boolean

true if the tertiary button is currently being pressed, otherwise false
keyboardModifiers KeyboardModifiers

Integer value with bits set according to which keyboard modifier keys were pressed when the event was generated.
Pose
Type: object

The pose of a joint or other item relative to the world or a parent.

Properties

Name Type Summary
translation Vec3

Translation.
rotation Quat

Rotation.
velocity Vec3

Velocity in m/s.
angularVelocity Vec3

Angular velocity in rad/s.
valid boolean

true if the pose is valid, otherwise false.
ProceduralData
Type: object

The data used to define a Procedural shader material.

Properties

Name Type Summary
version number

The version of the procedural shader.

Default Value: 1

vertexShaderURL string

A link to a vertex shader. Currently, only GLSL shaders are supported. The shader must implement a different method depending on the version. If a procedural material contains a vertex shader, the bounding box of the material entity is used to cull the object to which the material is applied.
fragmentShaderURL string

A link to a fragment shader. Currently, only GLSL shaders are supported. The shader must implement a different method depending on the version. shaderUrl is an alias.
channels Array.<string>

An array of input texture URLs or entity IDs. Currently, up to 4 are supported. An entity ID may be that of an Image or Web entity.

Default Value: [

uniforms ProceduralUniforms

A ProceduralUniforms object containing all the custom uniforms to be passed to the shader.

Default Value: {}

ProceduralUniforms
Type: object

An object containing user-defined uniforms for communicating data to shaders.
Quat
Type: object

A quaternion value. See also the Quat API.

Properties

Name Type Summary
x number

Imaginary component i.
y number

Imaginary component j.
z number

Imaginary component k.
w number

Real component.
RGBS
Type: array

An RGB or SRGB color value.

IndexTypeAttributesDefaultValue
0number Red component value. Number in the range 0.0 – 1.0.
1number Green component value. Number in the range 0.0 – 1.0.
2number Blue component value. Number in the range 0.0 – 1.0.
3boolean<optional>false If true then the color is an SRGB color.
RayPickResult
Type: object

An intersection result for a ray pick.

Properties

Name Type Summary
type IntersectionType

The intersection type.
intersects boolean

true if there's a valid intersection, false if there isn't.
objectID Uuid

The ID of the intersected object. null for HUD or invalid intersections.
distance number

The distance from the ray origin to the intersection point.
intersection Vec3

The intersection point in world coordinates.
surfaceNormal Vec3

The surface normal at the intersected point. All NaNs if type == Picks.INTERSECTED_HUD.
extraInfo SubmeshIntersection

Additional intersection details for model objects, otherwise { }.
searchRay PickRay

The pick ray that was used. Valid even if there is no intersection.
RayToAvatarIntersectionResult
Type: object

Information about a ray-to-avatar intersection.

Properties

Name Type Summary
intersects boolean

true if an avatar is intersected, false if it isn't.
avatarID string

The ID of the avatar that is intersected.
distance number

The distance from the ray origin to the intersection.
face string

The name of the box face that is intersected; "UNKNOWN_FACE" if mesh was picked against.
intersection Vec3

The ray intersection point in world coordinates.
surfaceNormal Vec3

The surface normal at the intersection point.
jointIndex number

The index of the joint intersected.
extraInfo SubmeshIntersection

Extra information on the mesh intersected if mesh was picked against, {} if it wasn't.
Rect
Type: object

Defines a rectangular portion of an image or screen, or similar.

Properties

Name Type Summary
x number

Left, x-coordinate value.
y number

Top, y-coordinate value.
width number

Width of the rectangle.
height number

Height of the rectangle.
Rect
Type: object

Defines a rectangular portion of an image or screen, or similar.

Properties

Name Type Summary
x number

Left, x-coordinate value.
y number

Top, y-coordinate value.
width number

Width of the rectangle.
height number

Height of the rectangle.
RefreshRateProfileName
Type: string

Refresh rate profile.

ValueDescription
"Eco"Low refresh rate, which is reduced when Interface doesn't have focus or is minimized.
"Interactive"Medium refresh rate, which is reduced when Interface doesn't have focus or is minimized.
"Realtime"High refresh rate, even when Interface doesn't have focus or is minimized.
RefreshRateRegime
Type: number

Interface states that affect the refresh rate.

ValueNameDescription
0FOCUS_ACTIVEInterface has focus and the user is active or is in VR.
1FOCUS_INACTIVEInterface has focus and the user is inactive.
2UNFOCUSInterface doesn't have focus.
3MINIMIZEDInterface is minimized.
4STARTUPInterface is starting up.
5SHUTDOWNInterface is shutting down.
RefreshRateRegimeName
Type: string

Interface states that affect the refresh rate.

ValueDescription
"FocusActive"Interface has focus and the user is active or is in VR.
"FocusInactive"Interface has focus and the user is inactive.
"Unfocus"Interface doesn't have focus.
"Minimized"Interface is minimized.
"StartUp"Interface is starting up.
"ShutDown"Interface is shutting down.
Shape
Type: object

A physical volume.

Properties

Name Type Attributes Summary
shapeType ShapeType

The type of shape.

Default Value: "none"

modelUrl string <optional>

The model to load to for the shape if shapeType is one of "compound", "simple-hull", "simple-compound", or "static-mesh".

Default Value: ""

dimensions Vec3

The dimensions of the shape.
ShapeType
Type: string

Defines the shape used for collisions or zones.

ValueDescription
"none"No shape.
"box"A cube.
"sphere"A sphere.
"capsule-x"A capsule (cylinder with spherical ends) oriented on the x-axis.
"capsule-y"A capsule (cylinder with spherical ends) oriented on the y-axis.
"capsule-z"A capsule (cylinder with spherical ends) oriented on the z-axis.
"cylinder-x"A cylinder oriented on the x-axis.
"cylinder-y"A cylinder oriented on the y-axis.
"cylinder-z"A cylinder oriented on the z-axis.
"hull"Not used.
"compound"A compound convex hull specified in an OBJ file.
"simple-hull"A convex hull automatically generated from the model.
"simple-compound"A compound convex hull automatically generated from the model, using sub-meshes.
"static-mesh"The exact shape of the model.
"plane"A plane.
"ellipsoid"An ellipsoid.
"circle"A circle.
"multisphere"A convex hull generated from a set of spheres.
Size
Type: object

A 2D size value.

Properties

Name Type Summary
height number

The height value.
width number

The width value.
SkeletonJoint
Type: object

Information about a joint in an avatar's skeleton hierarchy.

Properties

Name Type Summary
name string

Joint name.
index number

Joint index.
parentIndex number

Index of this joint's parent (-1 if no parent).
StylusPickResult
Type: object

An intersection result for a stylus pick.

Properties

Name Type Summary
type number

The intersection type.
intersects boolean

true if there's a valid intersection, false if there isn't.
objectID Uuid

The ID of the intersected object. null for invalid intersections.
distance number

The distance to the intersection point from the stylus tip.
intersection Vec3

The intersection point in world coordinates.
surfaceNormal Vec3

The surface normal at the intersected point.
stylusTip StylusTip

The stylus tip at the time of the result. Valid even if there is no intersection.
StylusTip
Type: object

The tip of a stylus.

Properties

Name Type Summary
side number

The hand that the stylus is attached to: 0 for left hand, 1 for the right hand, -1 for invalid.
tipOffset Vec3

The position of the stylus tip relative to the body of the stylus.
position Vec3

The position of the stylus tip.
orientation Quat

The orientation of the stylus.
velocity Vec3

The velocity of the stylus tip.
SubmeshIntersection
Type: object

A submesh intersection point.

Properties

Name Type Summary
worldIntersectionPoint Vec3

The intersection point in world coordinates.
meshIntersectionPoint Vec3

The intersection point in model coordinates.
partIndex number

The index of the intersected mesh part within the submesh.
shapeID number

The index of the mesh part within the model.
subMeshIndex number

The index of the intersected submesh within the model.
subMeshName string

The name of the intersected submesh.
subMeshTriangleWorld Triangle

The vertices of the intersected mesh part triangle in world coordinates.
subMeshNormal Vec3

The normal of the intersected mesh part triangle in model coordinates.
subMeshTriangle Triangle

The vertices of the intersected mesh part triangle in model coordinates.
TouchEvent
Type: object

A display or device touch event.

Properties

Name Type Summary
x number

Integer x-coordinate of the average position of the touch events.
y number

Integer y-coordinate of the average position of the touch events.
isPressed boolean

true if the touch point has just been pressed, otherwise false.
isMoved boolean

true if the touch point has moved, otherwise false.
isStationary boolean

true if the touch point has not moved, otherwise false.
isReleased boolean

true if the touch point has just been released, otherwise false.
isShifted boolean

true if the Shift key was pressed when the event was generated, otherwise false.
isMeta boolean

true if the "meta" key was pressed when the event was generated, otherwise false. On Windows the "meta" key is the Windows key; on OSX it is the Control (Splat) key.
isControl boolean

true if the "control" key was pressed when the event was generated, otherwise false. On Windows the "control" key is the Ctrl key; on OSX it is the Command key.
isAlt boolean

true if the Alt key was pressed when the event was generated, otherwise false.
touchPoints number

Integer number of touch points.
points Array.<Vec2>

The coordinates of the touch points.
radius number

The radius of a circle centered on their average position that encompasses the touch points.
isPinching boolean

true if the radius has reduced since the most recent touch event with a different radius value, otherwise false.
isPinchOpening boolean

true if the radius has increased since the most recent touch event with a different radius value, otherwise false.
angle number

An angle calculated from the touch points, in degrees.
deltaAngle number

The change in the angle value since the previous touch event, in degrees, if the number of touch points is the same, otherwise 0.0.
angles Array.<number>

The angles of each touch point about the center of all the touch points, in degrees.
isRotating boolean

true if the angle of the touch event has changed since the previous touch event and the number of touch points is the same, otherwise false.
rotating string

"clockwise" or "counterClockwise" if the angle of the touch event has changed since the previous touch event and the number of touch points is the same, otherwise "none".
Example

Report the TouchEvent details when a touch event starts.

Controller.touchBeginEvent.connect(function (event) {
    print(JSON.stringify(event));
});
Triangle
Type: object

A triangle in a mesh.

Properties

Name Type Summary
v0 Vec3

The position of vertex 0 in the triangle.
v1 Vec3

The position of vertex 1 in the triangle.
v2 Vec3

The position of vertex 2 in the triangle.
UXMode
Type: number

User experience (UX) modes.

ValueNameDescription
0DESKTOPDesktop user experience.
1VRVR use experience.
UXModeName
Type: string

User experience (UX) modes.

ValueDescription
"Desktop"Desktop user experience.
"VR"VR user experience.
Uuid
Type: string

UUIDs (Universally Unique IDentifiers) are used to uniquely identify entities, avatars, and the like. They are represented in JavaScript as strings in the format, "{nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}", where the "n"s are hexadecimal digits.
Vec2
Type: object

A 2-dimensional vector.

Properties

Name Type Summary
x number

X-coordinate of the vector. Synonyms: u.
y number

Y-coordinate of the vector. Synonyms: v.
Example

Vec2s can be set in multiple ways and modified with their aliases, but still stringify in the same way

Entities.editEntity(<id>, { materialMappingPos: { x: 0.1, y: 0.2 }});          // { x: 0.1, y: 0.2 }
Entities.editEntity(<id>, { materialMappingPos: { u: 0.3, v: 0.4 }});          // { x: 0.3, y: 0.4 }
Entities.editEntity(<id>, { materialMappingPos: [0.5, 0.6] });                 // { x: 0.5, y: 0.6 }
Entities.editEntity(<id>, { materialMappingPos: 0.7 });                        // { x: 0.7, y: 0.7 }
var color = Entities.getEntityProperties(<id>).materialMappingPos;             // { x: 0.7, y: 0.7 }
color.v = 0.8;                                                                 // { x: 0.7, y: 0.8 }
Vec2
Type: object

A 2-dimensional vector.

Properties

Name Type Summary
x number

X-coordinate of the vector. Synonyms: u.
y number

Y-coordinate of the vector. Synonyms: v.
Example

Vec2s can be set in multiple ways and modified with their aliases, but still stringify in the same way

Entities.editEntity(<id>, { materialMappingPos: { x: 0.1, y: 0.2 }});          // { x: 0.1, y: 0.2 }
Entities.editEntity(<id>, { materialMappingPos: { u: 0.3, v: 0.4 }});          // { x: 0.3, y: 0.4 }
Entities.editEntity(<id>, { materialMappingPos: [0.5, 0.6] });                 // { x: 0.5, y: 0.6 }
Entities.editEntity(<id>, { materialMappingPos: 0.7 });                        // { x: 0.7, y: 0.7 }
var color = Entities.getEntityProperties(<id>).materialMappingPos;             // { x: 0.7, y: 0.7 }
color.v = 0.8;                                                                 // { x: 0.7, y: 0.8 }
Vec3
Type: object

A 3-dimensional vector. See also the Vec3 object.

Properties

Name Type Summary
x number

X-coordinate of the vector. Synonyms: r, red.
y number

Y-coordinate of the vector. Synonyms: g, green.
z number

Z-coordinate of the vector. Synonyms: b, blue.
Example

Vec3 values can be set in multiple ways and modified with their aliases, but still stringify in the same way.

Entities.editEntity(<id>, { position: { x: 1, y: 2, z: 3 }});                 // { x: 1, y: 2, z: 3 }
Entities.editEntity(<id>, { position: { r: 4, g: 5, b: 6 }});                 // { x: 4, y: 5, z: 6 }
Entities.editEntity(<id>, { position: { red: 7, green: 8, blue: 9 }});        // { x: 7, y: 8, z: 9 }
Entities.editEntity(<id>, { position: [10, 11, 12] });                        // { x: 10, y: 11, z: 12 }
Entities.editEntity(<id>, { position: 13 });                                  // { x: 13, y: 13, z: 13 }
var position = Entities.getEntityProperties(<id>).position;                   // { x: 13, y: 13, z: 13 }
position.g = 14;                                                              // { x: 13, y: 14, z: 13 }
position.blue = 15;                                                           // { x: 13, y: 14, z: 15 }
Entities.editEntity(<id>, { position: "red"});                                // { x: 255, y: 0, z: 0 }
Entities.editEntity(<id>, { position: "#00FF00"});                            // { x: 0, y: 255, z: 0 }
Vec3
Type: object

A 3-dimensional vector. See also the Vec3 object.

Properties

Name Type Summary
x number

X-coordinate of the vector. Synonyms: r, red.
y number

Y-coordinate of the vector. Synonyms: g, green.
z number

Z-coordinate of the vector. Synonyms: b, blue.
Example

Vec3 values can be set in multiple ways and modified with their aliases, but still stringify in the same way.

Entities.editEntity(<id>, { position: { x: 1, y: 2, z: 3 }});                 // { x: 1, y: 2, z: 3 }
Entities.editEntity(<id>, { position: { r: 4, g: 5, b: 6 }});                 // { x: 4, y: 5, z: 6 }
Entities.editEntity(<id>, { position: { red: 7, green: 8, blue: 9 }});        // { x: 7, y: 8, z: 9 }
Entities.editEntity(<id>, { position: [10, 11, 12] });                        // { x: 10, y: 11, z: 12 }
Entities.editEntity(<id>, { position: 13 });                                  // { x: 13, y: 13, z: 13 }
var position = Entities.getEntityProperties(<id>).position;                   // { x: 13, y: 13, z: 13 }
position.g = 14;                                                              // { x: 13, y: 14, z: 13 }
position.blue = 15;                                                           // { x: 13, y: 14, z: 15 }
Entities.editEntity(<id>, { position: "red"});                                // { x: 255, y: 0, z: 0 }
Entities.editEntity(<id>, { position: "#00FF00"});                            // { x: 0, y: 255, z: 0 }
Vec4
Type: object

A 4-dimensional vector.

Properties

Name Type Summary
x number

X-coordinate of the vector.
y number

Y-coordinate of the vector.
z number

Z-coordinate of the vector.
w number

W-coordinate of the vector.
Vec4
Type: object

A 4-dimensional vector.

Properties

Name Type Summary
x number

X-coordinate of the vector.
y number

Y-coordinate of the vector.
z number

Z-coordinate of the vector.
w number

W-coordinate of the vector.
ViewFrustum
Type: object

A ViewFrustum has a "keyhole" shape: a regular frustum for stuff that is visible plus a central sphere for stuff that is nearby (for physics simulation).

Properties

Name Type Summary
position Vec3

The location of the frustum's apex.
orientation Quat

The direction that the frustum is looking at.
centerRadius number

Center radius of the keyhole in meters.
fieldOfView number

Horizontal field of view in degrees.
aspectRatio number

Aspect ratio of the frustum.
projection Mat4

The projection matrix for the view defined by the frustum.
WebInputMode
Type: string

Specifies how a web surface processes events.

ValueDescription
"touch"Events are processed as touch events.
"mouse"Events are processed as mouse events.
WheelEvent
Type: object

A mouse wheel event.

Properties

Name Type Summary
x number

Integer x-coordinate of the event on the Interface window or HMD HUD.
y number

Integer y-coordinate of the event on the Interface window or HMD HUD.
delta number

Integer number indicating the direction and speed to scroll: positive numbers to scroll up, and negative numers to scroll down.
orientation string

The orientation of the wheel: "VERTICAL" for a typical mouse; "HORIZONTAL" for a "horizontal" wheel.
isLeftButton boolean

true if the left button was pressed when the event was generated, otherwise false.
isMiddleButton boolean

true if the middle button was pressed when the event was generated, otherwise false.
isRightButton boolean

true if the right button was pressed when the event was generated, otherwise false.
isShifted boolean

true if the Shift key was pressed when the event was generated, otherwise false.
isMeta boolean

true if the "meta" key was pressed when the event was generated, otherwise false. On Windows the "meta" key is the Windows key; on OSX it is the Control (Splat) key.
isControl boolean

true if the "control" key was pressed when the event was generated, otherwise false. On Windows the "control" key is the Ctrl key; on OSX it is the Command key.
isAlt boolean

true if the Alt key was pressed when the event was generated, otherwise false.
Example

Report the WheelEvent details for each wheel rotation.

Controller.wheelEvent.connect(function (event) {
    print(JSON.stringify(event));
});

Method Details

print( …messageopt )

Prints a message to the program log and emits Script.printedMessage. The message logged is the message values separated by spaces.

Alternatively, you can use Script.print or one of the console API methods.

Parameters

Name Type Attributes Description
message * <optional>
<repeatable>

The message values to print.