Globals

Type Definitions
AACube
AttachmentData
BoxFace
Collision
CollisionContact
CollisionPickResult
CollisionRegion
Color
ContactEventType
FBXAnimationFrame
IntersectingObject
KeyboardModifiers
KeyEvent
Material
MaterialResource
MouseEvent
ParabolaPickResult
PickParabola
PickRay
PickType
PointerEvent
Pose
Quat
RayPickResult
Rect
RGBS
Shape
ShapeType
Size
StylusPickResult
StylusTip
TouchEvent
Vec2
Vec3
Vec3Color
Vec4
ViewFrustum
WheelEvent

Type Definitions

AACube
An axis-aligned cube, defined as the bottom right near (minimum axes values) corner of the cube plus the dimension of its sides.
Type: object
Properties:
Name Type Description
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.
AttachmentData
Type: object
Properties:
Name Type Description
modelUrl string
jointName string
translation Vec3
rotation Vec3
scale number
soft boolean
BoxFace

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

Value Description
"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.
Type: string
Collision
Type: object
Properties:
Name Type Description
type ContactEventType The contact type of the collision event.
idA Uuid The ID of one of the entities in the collision.
idB Uuid The ID of the other of the entities in the collision.
penetration Vec3 The amount of penetration between the two entities.
contactPoint Vec3 The point of contact.
velocityChange Vec3 The change in relative velocity of the two entities, in m/s.
CollisionContact
A pair of points that represents part of an overlap between a Collision Pick and an object in the physics engine. Points which are further apart represent deeper overlap
Type: object
Properties:
Name Type Description
pointOnPick Vec3 A point representing a penetration of the object's surface into the volume of the pick, in world space.
pointOnObject Vec3 A point representing a penetration of the pick's surface into the volume of the found object, in world space.
CollisionPickResult
An intersection result for a Collision Pick.
Type: object
Properties:
Name Type Description
intersects boolean If there was at least one valid intersection (intersectingObjects.length > 0)
intersectingObjects Array.<IntersectingObject> The collision information of each object which intersect with the CollisionRegion.
collisionRegion CollisionRegion The CollisionRegion that was used. Valid even if there was no intersection.
CollisionRegion
A CollisionRegion defines a volume for checking collisions in the physics simulation.
Type: object
Properties:
Name Type Description
shape Shape The information about the collision region's size and shape.
position Vec3 The position of the collision region, relative to a parent if defined.
orientation Quat The orientation of the collision region, relative to a parent if defined.
threshold float The approximate minimum penetration depth for a test object to be considered in contact with the collision region.
parentID Uuid The ID of the parent, either an avatar, an entity, or an overlay.
parentJointIndex number The joint of the parent to parent to, for example, the joints on the model of an avatar. (default = 0, no joint)
joint string If "Mouse," parents the pick to the mouse. If "Avatar," parents the pick to MyAvatar's head. Otherwise, parents to the joint of the given name on MyAvatar.
Color
An RGB color value.
Type: object
Properties:
Name Type Description
red number Red component value. Integer in the range 0 - 255.
green number Green component value. Integer in the range 0 - 255.
blue number Blue component value. Integer in the range 0 - 255.
ContactEventType

The type of a collision contact event.

Value Description
0 Start of the collision.
1 Continuation of the collision.
2 End of the collision.
Type: number
FBXAnimationFrame
Type: object
Properties:
Name Type Description
rotations Array.<Quat>
translations Array.<Vec3>
IntersectingObject
Information about the Collision Pick's intersection with an object
Type: object
Properties:
Name Type Description
id QUuid The ID of the object.
type number The type of the object, either Picks.INTERSECTED_ENTITY() or Picks.INTERSECTED_AVATAR()
collisionContacts Array.<CollisionContact> Pairs of points representing penetration information between the pick and the object
KeyboardModifiers

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:

Key Hexadecimal value Decimal value Description
Shift 0x02000000 33554432 A Shift key on the keyboard is pressed.
Control 0x04000000 67108864 A control key on the keyboard is pressed. On Windows the "control" key is the Ctrl key; on OSX it is the Command key.
Alt 0x08000000 134217728 An Alt key on the keyboard is pressed.
Meta 0x10000000 268435456 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.
Keypad 0x20000000 536870912 A keypad button is pressed.
Group 0x40000000 1073741824 X11 operating system only: An AltGr / Mode_switch key on the keyboard is pressed.
Type: number
KeyEvent
A keyboard key event.
Type: object
Properties:
Name Type Description
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));
});
Material
A material such as may be used by a Material entity.
Type: object
Properties:
Name Type Default Description
name string "" A name for the material.
model string "hifi_pbr" Currently not used.
emissive Vec3Color | RGBS The emissive color, i.e., the color that the material emits. A Vec3Color value is treated as sRGB. A RGBS value can be either RGB or sRGB.
opacity number 1.0 The opacity, 0.01.0.
unlit boolean false If true, the material is not lit.
albedo Vec3Color | RGBS The albedo color. A Vec3Color value is treated as sRGB. A RGBS value can be either RGB or sRGB.
roughness number The roughness, 0.01.0.
metallic number The metallicness, 0.01.0.
scattering number The scattering, 0.01.0.
emissiveMap string URL of emissive texture image.
albedoMap string URL of albedo texture image.
opacityMap string URL of opacity texture image. Set value the same as the albedoMap value for transparency.
roughnessMap string URL of roughness texture image. Can use this or glossMap, but not both.
glossMap string URL of gloss texture image. Can use this or roughnessMap, but not both.
metallicMap string URL of metallic texture image. Can use this or specularMap, but not both.
specularMap string URL of specular texture image. Can use this or metallicMap, but not both.
normalMap string URL of normal texture image. Can use this or bumpMap, but not both.
bumpMap string URL of bump texture image. Can use this or normalMap, but not both.
occlusionMap string URL of occlusion texture image.
scatteringMap string URL of scattering texture image. Only used if normalMap or bumpMap is specified.
lightMap string URL of light map texture image. Currently not used.
MaterialResource
A material or set of materials such as may be used by a Material entity.
Type: object
Properties:
Name Type Default Description
materialVersion number 1 The version of the material. Currently not used.
materials Material | Array.<Material> The details of the material or materials.
MouseEvent
A controller mouse movement or button event.
Type: object
Properties:
Name Type Description
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
An intersection result for a Parabola Pick.
Type: object
Properties:
Name Type Description
type number The intersection type.
intersects boolean If there was a valid intersection (type != INTERSECTED_NONE)
objectID Uuid The ID of the intersected object. Uuid.NULL for the HUD or invalid intersections.
distance number The distance to the intersection point from the origin of the parabola, not along the parabola.
parabolicDistance number The distance to the intersection point from the origin of the parabola, along the parabola.
intersection Vec3 The intersection point in world-space.
surfaceNormal Vec3 The surface normal at the intersected point. All NANs if type == INTERSECTED_HUD.
extraInfo Variant Additional intersection details when available for Model objects.
parabola PickParabola The PickParabola that was used. Valid even if there was no intersection.
PickParabola
A PickParabola defines a parabola with a starting point, intitial velocity, and acceleration.
Type: object
Properties:
Name Type Description
origin Vec3 The starting position of the PickParabola.
velocity Vec3 The starting velocity of the parabola.
acceleration Vec3 The acceleration that the parabola experiences.
PickRay
A PickRay defines a vector with a starting point. It is used, for example, when finding entities or overlays that lie under a mouse click or intersect a laser beam.
Type: object
Properties:
Name Type Description
origin Vec3 The starting position of the PickRay.
direction Vec3 The direction that the PickRay travels.
PickType
Type: number
PointerEvent
A PointerEvent defines a 2D or 3D mouse or similar pointer event.
Type: object
Properties:
Name Type Description
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 overlay or entity XY plane, where applicable.
pos3D Vec3 The 3D position of the event on the intersected overlay or entity, 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
The pose of a joint or other item relative to the world or a parent.
Type: object
Properties:
Name Type Description
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.
Quat
A quaternion value. See also the Quat object.
Type: object
Properties:
Name Type Description
x number Imaginary component i.
y number Imaginary component j.
z number Imaginary component k.
w number Real component.
RayPickResult
An intersection result for a Ray Pick.
Type: object
Properties:
Name Type Description
type number The intersection type.
intersects boolean If there was a valid intersection (type != INTERSECTED_NONE)
objectID Uuid The ID of the intersected object. Uuid.NULL for the HUD or invalid intersections.
distance number The distance to the intersection point from the origin of the ray.
intersection Vec3 The intersection point in world-space.
surfaceNormal Vec3 The surface normal at the intersected point. All NANs if type == INTERSECTED_HUD.
extraInfo Variant Additional intersection details when available for Model objects.
searchRay PickRay The PickRay that was used. Valid even if there was no intersection.
Rect
Defines a rectangular portion of an image or screen.
Type: object
Properties:
Name Type Description
x number Integer left, x-coordinate value.
y number Integer top, y-coordinate value.
width number Integer width of the rectangle.
height number Integer height of the rectangle.
RGBS

An RGB or SRGB color value.

Index Type Attributes Default Value
0 number Red component value. Number in the range 0.01.0.
1 number Green component value. Number in the range 0.01.0.
2 number Blue component value. Number in the range 0.01.0.
3 boolean <optional> false If true then the color is an SRGB color.
Type: array
Shape
A Shape defines a physical volume.
Type: object
Properties:
Name Type Description
shapeType string The type of shape to use. Can be one of the following: "box", "sphere", "capsule-x", "capsule-y", "capsule-z", "cylinder-x", "cylinder-y", "cylinder-z"
dimensions Vec3 The size to scale the shape to.
ShapeType

A ShapeType defines the shape used for collisions or zones.

Value Description
"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.
Type: string
Size
A 2D size value.
Type: object
Properties:
Name Type Description
height number The height value.
width number The width value.
StylusPickResult
An intersection result for a Stylus Pick.
Type: object
Properties:
Name Type Description
type number The intersection type.
intersects boolean If there was a valid intersection (type != INTERSECTED_NONE)
objectID Uuid The ID of the intersected object. Uuid.NULL for the HUD or invalid intersections.
distance number The distance to the intersection point from the origin of the ray.
intersection Vec3 The intersection point in world-space.
surfaceNormal Vec3 The surface normal at the intersected point. All NANs if type == INTERSECTED_HUD.
extraInfo Variant Additional intersection details when available for Model objects.
stylusTip StylusTip The StylusTip that was used. Valid even if there was no intersection.
StylusTip
A StylusTip defines the tip of a stylus.
Type: object
Properties:
Name Type Description
side number The hand the tip is attached to: 0 for left, 1 for right.
position Vec3 The position of the stylus tip.
orientation Quat The orientation of the stylus tip.
velocity Vec3 The velocity of the stylus tip.
TouchEvent
A display or device touch event.
Type: object
Properties:
Name Type Description
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));
});
Vec2
A 2-dimensional vector.
Type: object
Properties:
Name Type Description
x number X-coordinate of the vector.
y number Y-coordinate of the vector.
Vec3
A 3-dimensional vector. See also the Vec3 object.
Type: object
Properties:
Name Type Description
x number X-coordinate of the vector.
y number Y-coordinate of the vector.
z number Z-coordinate of the vector.
Vec3Color
A color vector. See also the Vec3 object.
Type: object
Properties:
Name Type Description
x number Red component value. Integer in the range 0 - 255.
y number Green component value. Integer in the range 0 - 255.
z number Blue component value. Integer in the range 0 - 255.
Vec4
A 4-dimensional vector.
Type: object
Properties:
Name Type Description
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
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).
Type: object
Properties:
Name Type Description
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.
WheelEvent
A mouse wheel event.
Type: object
Properties:
Name Type Description
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));
});