Overlays

Description

The Overlays API provides facilities to create and interact with overlays. These are 2D and 3D objects visible only to yourself and that aren't persisted to the domain. They are used for UI.

Note: 3D overlays are local Entities, internally, so many of the methods also work with entities.

3D overlays are deprecated: Use local Entities for these instead.

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

Properties

Name Type Summary
keyboardFocusOverlay Uuid The "web3d" overlay (Web entity) that has keyboard focus. If no overlay (entity) has keyboard focus, returns null; set to null or Uuid.NULL to clear keyboard focus.

Methods

Name Return Value Summary
addOverlay Uuid Adds an overlay to the scene.
cloneOverlay Uuid Creates a clone of an existing overlay (or entity).

Note: For cloning behavior of 3D overlays and entities, see Entities.cloneEntity.

deleteOverlay None Deletes an overlay (or entity).
editOverlay boolean Edits an overlay's (or entity's) properties.
editOverlays boolean Edits the properties of multiple overlays (or entities).
findOverlays Array.<Uuid> Gets a list of visible 3D overlays (local entities) with bounding boxes that touch a search sphere.
findRayIntersection Overlays.RayToOverlayIntersectionResult Finds the closest 3D overlay (or local entity) intersected by a PickRay.
getKeyboardFocusOverlay Uuid Gets the ID of the "web3d" overlay (Web entity) that has keyboard focus.
getOverlayAtPoint Uuid Gets the ID of the 2D overlay at a particular point on the desktop screen or HUD surface.
getOverlayObject object Gets an overlay's (or entity's) script object. In particular, this is useful for accessing a "web3d" overlay's EventBridge script object to exchange messages with the web page script.

To send a message from an Interface script to a "web3d" overlay over its event bridge:

var overlayObject = Overlays.getOverlayObject(overlayID);
overlayObject.emitScriptEvent(message);

To receive a message from a "web3d" overlay over its event bridge in an Interface script:

var overlayObject = Overlays.getOverlayObject(overlayID);
overlayObject.webEventReceived.connect(function(message) {
    ...
};
getOverlaysProperties object.<Uuid, Overlays.OverlayProperties> Gets the values of multiple overlays' (or entities') properties.
getOverlayType Overlays.OverlayType Gets the type of an overlay.
getProperties Overlays.OverlayProperties Gets specified property values of a 3D overlay (or entity).

Note: 2D overlays' property values cannot be retrieved.

getProperty object Gets a specified property value of a 3D overlay (or entity).

Note: 2D overlays' property values cannot be retrieved.

height number Gets the height of the Interface window or HUD surface.
isAddedOverlay boolean Checks if an overlay (or entity) exists.
isLoaded boolean Checks whether an overlay's (or entity's) assets have been loaded. For example, for an "image" overlay, the result indicates whether its image has been loaded.
sendHoverEnterOverlay None Generates a hover enter event on an overlay (or local entity).
sendHoverLeaveOverlay None Generates a hover leave event on an overlay (or local entity).
sendHoverOverOverlay None Generates a hover over event on an overlay (or entity).
sendMouseMoveOnOverlay None Generates a mouse move event on an overlay (or local entity).
sendMousePressOnOverlay None Generates a mouse press event on an overlay (or local entity).
sendMouseReleaseOnOverlay None Generates a mouse release event on an overlay (or local entity).
setKeyboardFocusOverlay None Sets the "web3d" overlay (Web entity) that has keyboard focus.
textSize Size Calculates the size of some text in a text overlay (or entity). The overlay (or entity) need not be set visible.

Note: The size of text in a 3D overlay (or entity) cannot be calculated immediately after the overlay (or entity) is created; a short delay is required while the overlay (or entity) finishes being created.

width number Gets the width of the Interface window or HUD surface.

Signals

Name Summary
hoverEnterOverlay Triggered when a mouse cursor starts hovering over an overlay. Only occurs for 3D overlays (unless you use sendHoverEnterOverlay for a 2D overlay).
hoverLeaveOverlay Triggered when a mouse cursor finishes hovering over an overlay. Only occurs for 3D overlays (unless you use sendHoverLeaveOverlay for a 2D overlay).
hoverOverOverlay Triggered when a mouse cursor continues hovering over an overlay. Only occurs for 3D overlays (unless you use sendHoverOverOverlay for a 2D overlay).
mouseDoublePressOffOverlay Triggered when a mouse double press event occurs on something other than a 3D overlay.
mouseDoublePressOnOverlay Triggered when a mouse double press event occurs on an overlay. Only occurs for 3D overlays.
mouseMoveOnOverlay Triggered when a mouse move event occurs on an overlay. Only occurs for 3D overlays (unless you use sendMouseMoveOnOverlay for a 2D overlay).
mousePressOffOverlay Triggered when a mouse press event occurs on something other than a 3D overlay.
mousePressOnOverlay Triggered when a mouse press event occurs on an overlay. Only occurs for 3D overlays (unless you use sendMousePressOnOverlay for a 2D overlay).
mouseReleaseOnOverlay Triggered when a mouse release event occurs on an overlay. Only occurs for 3D overlays (unless you use sendMouseReleaseOnOverlay for a 2D overlay).
overlayDeleted Triggered when an overlay (or entity) is deleted.

Type Definitions

OverlayProperties
Type: object

Different overlay types have different properties: some common to all overlays (listed in the table) and some specific to each OverlayType (linked to below).

3D overlays are local entities, internally, so they also support the relevant entity's properties.

Properties

Name Type Summary
id Uuid The ID of the overlay. Read-only.
type Overlays.OverlayType The overlay's type. Read-only.
visible boolean true if the overlay is rendered, false if it isn't.

Default Value: true

See:

OverlayProperties-Circle3D
Type: object

The "circle3d" OverlayType is for 3D circles. It has properties in addition to the common OverlayProperties. It additionally has properties per the Gizmo entity, with the gizmoType property value being "ring".

Deprecated: Use local Entities instead.

Properties

Name Type Summary
name string The name of the overlay.
pulseMax number The maximum value of the pulse multiplier.

Default Value: 0

pulseMin number The minimum value of the pulse multiplier.

Default Value: 0

pulsePeriod number The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from pulseMin to pulseMax, then pulseMax to pulseMin in one period.

Default Value: 1

alphaPulse number If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

colorPulse number If non-zero, the color of the overlay is pulsed: the color value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

position Vec3 The position of the overlay center. Synonyms: p1, point, and start.
dimensions Vec3 The dimensions of the overlay. Synonyms: scale, size. Read-only.
rotation Quat The orientation of the overlay. Synonym: orientation.
localPosition Vec3 The local position of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as position.
localRotation Quat The orientation of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as rotation. Synonym: localOrientation.
isSolid boolean true if the overlay is rendered as a solid, false if it is rendered as a wire frame. Synonyms: solid, isFilled, and filled. Antonyms: isWire and wire.

Default Value: false

ignorePickIntersection boolean true if Picks ignore the overlay, false if they don't. Synonym: ignoreRayIntersection.

Default Value: false

drawInFront boolean true if the overlay is rendered on top of the world layer but behind the HUD surface.

Default Value: false

drawHUDLayer boolean true if the overlay is rendered in front of everything, including the HUD surface.

Default Value: false

grabbable boolean true if the overlay can be grabbed, false if it can't be.

Default Value: false

parentID Uuid The avatar, entity, or overlay that the overlay is parented to.

Default Value: null

parentJointIndex number Integer value specifying the joint of the entity or avatar that the entity is parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather than a joint.

Default Value: 65535

startAt number The counter-clockwise angle from the overlay's x-axis that drawing starts at, in degrees.

Default Value: 0

endAt number The counter-clockwise angle from the overlay's x-axis that drawing ends at, in degrees.

Default Value: 360

outerRadius number The outer radius of the overlay in meters. Synonym: radius.

Default Value: 1

innerRadius number The inner radius of the overlay in meters.

Default Value: 0

color Color Sets the color of the overlay. Setting this value sets the values of innerStartColor, innerEndColor, outerStartColor, and outerEndColor. Write-only.
startColor Color Sets the values of innerStartColor and outerStartColor. Write-only.
endColor Color Sets the values of innerEndColor and outerEndColor. Write-only.
innerColor Color Sets the values of innerStartColor and innerEndColor. Write-only.
outerColor Color Sets the values of outerStartColor and outerEndColor. Write-only.
innerStartcolor Color The color at the inner start point of the overlay.

Default Value: 255,255,255

innerEndColor Color The color at the inner end point of the overlay.

Default Value: 255,255,255

outerStartColor Color The color at the outer start point of the overlay.

Default Value: 255,255,255

outerEndColor Color The color at the outer end point of the overlay.

Default Value: 255,255,255

alpha number Sets the opacity of the overlay, 0.01.0. Setting this value sets the values of innerStartAlpha, innerEndAlpha, outerStartAlpha, and outerEndAlpha. Synonym: Alpha.
startAlpha number Sets the values of innerStartAlpha and outerStartAlpha. Write-only.
endAlpha number Sets the values of innerEndAlpha and outerEndAlpha. Write-only.
innerAlpha number Sets the values of innerStartAlpha and innerEndAlpha. Write-only.
outerAlpha number Sets the values of outerStartAlpha and outerEndAlpha. Write-only.
innerStartAlpha number The opacity at the inner start point of the overlay, 0.01.0.

Default Value: 0.7

innerEndAlpha number The opacity at the inner end point of the overlay, 0.01.0.

Default Value: 0.7

outerStartAlpha number The opacity at the outer start point of the overlay, 0.01.0.

Default Value: 0.7

outerEndAlpha number The opacity at the outer end point of the overlay, 0.01.0.

Default Value: 0.7

hasTickMarks boolean true if tick marks are drawn, false if they aren't.

Default Value: false

majorTickMarksAngle number The angle between major tick marks, in degrees.

Default Value: 0

minorTickMarksAngle number The angle between minor tick marks, in degrees.

Default Value: 0

majorTickMarksLength number The length of the major tick marks, in meters. A positive value draws tick marks outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.

Default Value: 0

minorTickMarksLength number The length of the minor tick marks, in meters. A positive value draws tick marks outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.

Default Value: 0

majorTickMarksColor Color The color of the major tick marks.

Default Value: 0,0,0

minorTickMarksColor Color The color of the minor tick marks.

Default Value: 0,0,0

OverlayProperties-Cube
Type: object

The "cube" OverlayType is for 3D cubes. It has properties in addition to the common OverlayProperties. It additionally has properties per the Box entity.

Deprecated: Use local Entities instead.

Properties

Name Type Summary
name string The name of the overlay.
color Color The color of the overlay.

Default Value: 255,255,255

alpha number The opacity of the overlay, 0.01.0.

Default Value: 0.7

pulseMax number The maximum value of the pulse multiplier.

Default Value: 0

pulseMin number The minimum value of the pulse multiplier.

Default Value: 0

pulsePeriod number The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from pulseMin to pulseMax, then pulseMax to pulseMin in one period.

Default Value: 1

alphaPulse number If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

colorPulse number If non-zero, the color of the overlay is pulsed: the color value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

position Vec3 The position of the overlay center. Synonyms: p1, point, and start.
dimensions Vec3 The dimensions of the overlay. Synonyms: scale, size.
rotation Quat The orientation of the overlay. Synonym: orientation.
localPosition Vec3 The local position of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as position.
localRotation Quat The orientation of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as rotation. Synonym: localOrientation.
isSolid boolean true if the overlay is rendered as a solid, false if it is rendered as a wire frame. Synonyms: solid, isFilled, and filled. Antonyms: isWire and wire.

Default Value: false

ignorePickIntersection boolean true if Picks ignore the overlay, false if they don't. Synonym: ignoreRayIntersection.

Default Value: false

drawInFront boolean true if the overlay is rendered on top of the world layer but behind the HUD surface.

Default Value: false

drawHUDLayer boolean true if the overlay is rendered in front of everything, including the HUD surface.

Default Value: false

grabbable boolean true if the overlay can be grabbed, false if it can't be.

Default Value: false

parentID Uuid The avatar, entity, or overlay that the overlay is parented to.

Default Value: null

parentJointIndex number Integer value specifying the joint of the entity or avatar that the entity is parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather than a joint.

Default Value: 65535

OverlayProperties-Grid
Type: object

The "grid" OverlayType is for 3D grids. It has properties in addition to the common OverlayProperties. It additionally has properties per the Grid entity.

Deprecated: Use local Entities instead.

Properties

Name Type Summary
name string The name of the overlay.
color Color The color of the overlay.

Default Value: 255,255,255

alpha number The opacity of the overlay, 0.01.0.

Default Value: 0.7

pulseMax number The maximum value of the pulse multiplier.

Default Value: 0

pulseMin number The minimum value of the pulse multiplier.

Default Value: 0

pulsePeriod number The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from pulseMin to pulseMax, then pulseMax to pulseMin in one period.

Default Value: 1

alphaPulse number If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

colorPulse number If non-zero, the color of the overlay is pulsed: the color value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

position Vec3 The position of the overlay center. Synonyms: p1, point, and start.
dimensions Vec3 The dimensions of the overlay. Synonyms: scale, size.
rotation Quat The orientation of the overlay. Synonym: orientation.
localPosition Vec3 The local position of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as position.
localRotation Quat The orientation of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as rotation. Synonym: localOrientation.
ignorePickIntersection boolean true if Picks ignore the overlay, false if they don't. Synonym: ignoreRayIntersection.

Default Value: false

drawInFront boolean true if the overlay is rendered on top of the world layer but behind the HUD surface.

Default Value: false

drawHUDLayer boolean true if the overlay is rendered in front of everything, including the HUD surface.

Default Value: false

grabbable boolean true if the overlay can be grabbed, false if it can't be.

Default Value: false

parentID Uuid The avatar, entity, or overlay that the overlay is parented to.

Default Value: null

parentJointIndex number Integer value specifying the joint of the entity or avatar that the entity is parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather than a joint.

Default Value: 65535

OverlayProperties-Image
Type: object

The "image" OverlayType is for 2D images. It has properties in addition to the common OverlayProperties.

Properties

Name Type Summary
bounds Rect The position and size of the image display area, in pixels. Write-only.
x number Integer left, x-coordinate value of the image display area = bounds.x. Write-only.
y number Integer top, y-coordinate value of the image display area = bounds.y. Write-only.
width number Integer width of the image display area = bounds.width. Write-only.
height number Integer height of the image display area = bounds.height. Write-only.
imageURL string The URL of the image file to display. The image is scaled to fit to the bounds. Write-only.
subImage Rect The portion of the image to use. If not specified, the whole image is used. Write-only.
color Color The color to apply over the top of the image to colorize it. Write-only.

Default Value: 0,0,0

alpha number The opacity of the color applied over the top of the image, 0.01.0. Write-only.

Default Value: 0.0

OverlayProperties-Image3D
Type: object

The "image3D" OverlayType is for 3D images. It has properties in addition to the common OverlayProperties. It additionally has properties per the Image entity.

Deprecated: Use local Entities instead.

Properties

Name Type Summary
name string The name of the overlay.
color Color The color of the overlay.

Default Value: 255,255,255

alpha number The opacity of the overlay, 0.01.0.

Default Value: 0.7

pulseMax number The maximum value of the pulse multiplier.

Default Value: 0

pulseMin number The minimum value of the pulse multiplier.

Default Value: 0

pulsePeriod number The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from pulseMin to pulseMax, then pulseMax to pulseMin in one period.

Default Value: 1

alphaPulse number If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

colorPulse number If non-zero, the color of the overlay is pulsed: the color value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

position Vec3 The position of the overlay center. Synonyms: p1, point, and start.
dimensions Vec3 The dimensions of the overlay. Synonyms: scale, size.
rotation Quat The orientation of the overlay. Synonym: orientation.
localPosition Vec3 The local position of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as position.
localRotation Quat The orientation of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as rotation. Synonym: localOrientation.
ignorePickIntersection boolean true if Picks ignore the overlay, false if they don't. Synonym: ignoreRayIntersection.

Default Value: false

drawInFront boolean true if the overlay is rendered on top of the world layer but behind the HUD surface.

Default Value: false

drawHUDLayer boolean true if the overlay is rendered in front of everything, including the HUD surface.

Default Value: false

grabbable boolean true if the overlay can be grabbed, false if it can't be.

Default Value: false

parentID Uuid The avatar, entity, or overlay that the overlay is parented to.

Default Value: null

parentJointIndex number Integer value specifying the joint of the entity or avatar that the entity is parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather than a joint.

Default Value: 65535

url string The URL of the image to display.
OverlayProperties-Line3D
Type: object

The "line3d" OverlayType is for 3D lines. It has properties in addition to the common OverlayProperties. It additionally has properties per the PolyLine entity.

Deprecated: Use local Entities instead.

Properties

Name Type Summary
name string The name of the overlay.
color Color The color of the overlay.

Default Value: 255,255,255

alpha number The opacity of the overlay, 0.01.0.

Default Value: 0.7

position Vec3 The position of the overlay center. Synonyms: p1, point, and start.
dimensions Vec3 The dimensions of the overlay. Synonyms: scale, size.
rotation Quat The orientation of the overlay. Synonym: orientation.
localPosition Vec3 The local position of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as position.
localRotation Quat The orientation of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as rotation. Synonym: localOrientation.
ignorePickIntersection boolean true if Picks ignore the overlay, false if they don't. Synonym: ignoreRayIntersection.

Default Value: false

drawInFront boolean true if the overlay is rendered on top of the world layer but behind the HUD surface.

Default Value: false

drawHUDLayer boolean true if the overlay is rendered in front of everything, including the HUD surface.

Default Value: false

grabbable boolean true if the overlay can be grabbed, false if it can't be.

Default Value: false

parentID Uuid The avatar, entity, or overlay that the overlay is parented to.

Default Value: null

parentJointIndex number Integer value specifying the joint of the entity or avatar that the entity is parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather than a joint.

Default Value: 65535

endParentID Uuid The avatar, entity, or overlay that the end point of the line is parented to.

Currently doesn't work.

Default Value: null

endParentJointIndex number Integer value specifying the skeleton joint that the end point of the line is attached to if parentID is an avatar skeleton. A value of 65535 means "no joint".

Currently doesn't work.

Default Value: 65535

start Vec3 The start point of the line. Synonyms: startPoint and p1.

If parentID is set, use localStart to set the local position of the start point.

end Vec3 The end point of the line. Synonyms: endPoint and p2.

If parentID is set, use localEnd to set the local position of the end point.

localStart Vec3 The local position of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as start.
localEnd Vec3 The local position of the overlay relative to its parent if the overlay has a endParentID set, otherwise the same value as end.
length number The length of the line, in meters. This can be set after creating a line with start and end points.

Currently doesn't work.

glow number If glow > 0, the line is rendered with a glow.

Default Value: 0

lineWidth number Width of the line, in meters.

You can set this property's value but currently cannot retrieve its value. Use the strokeWidths property to retrieve its value instead.

Default Value: 0.02

OverlayProperties-Model
Type: object

The "model" OverlayType is for 3D models. It has properties in addition to the common OverlayProperties. It additionally has properties per the Model entity.

Deprecated: Use local Entities instead.

Properties

Name Type Summary
name string The name of the overlay.
position Vec3 The position of the overlay center. Synonyms: p1, point, and start.
dimensions Vec3 The dimensions of the overlay. Synonyms: size.
scale Vec3 The scale factor applied to the model's dimensions.
rotation Quat The orientation of the overlay. Synonym: orientation.
localPosition Vec3 The local position of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as position.
localRotation Quat The orientation of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as rotation. Synonym: localOrientation.
ignorePickIntersection boolean true if Picks ignore the overlay, false if they don't. Synonym: ignoreRayIntersection.

Default Value: false

drawInFront boolean true if the overlay is rendered on top of the world layer but behind the HUD surface.

Default Value: false

drawHUDLayer boolean true if the overlay is rendered in front of everything, including the HUD surface.

Default Value: false

grabbable boolean true if the overlay can be grabbed, false if it can't be.

Default Value: false

parentID Uuid The avatar, entity, or overlay that the overlay is parented to.

Default Value: null

parentJointIndex number Integer value specifying the joint of the entity or avatar that the entity is parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather than a joint.

Default Value: 65535

url string The URL of the FBX or OBJ model used for the overlay.
loadPriority number The priority for loading and displaying the overlay. Overlays with higher values load first. Currently not used.

Default Value: 0.0

textures Object.<string, string> | string Texture name, URL pairs used when rendering the model in place of the model's original textures, per the Entities.EntityProperties-Model property of the same name.

The value can be an object or a JSON string when setting the value; it is a JSON string when getting the value.

animationSettings Entities.AnimationProperties An animation to play on the model.
OverlayProperties-Rectangle
Type: object

The "rectangle" OverlayType is for 2D rectangles. It has properties in addition to the common OverlayProperties.

Properties

Name Type Summary
bounds Rect The position and size of the rectangle, in pixels. Write-only.
x number Integer left, x-coordinate value = bounds.x. Write-only.
y number Integer top, y-coordinate value = bounds.y. Write-only.
width number Integer width of the rectangle = bounds.width. Write-only.
height number Integer height of the rectangle = bounds.height. Write-only.
radius number Integer corner radius, in pixels. Write-only.

Default Value: 0

color Color The color of the overlay. Write-only.

Default Value: 0,0,0

alpha number The opacity of the overlay, 0.01.0. Write-only.

Default Value: 1.0

borderWidth number Integer width of the border, in pixels. The border is drawn within the rectangle's bounds. It is not drawn unless either borderColor or borderAlpha are specified. Write-only.

Default Value: 1

borderColor Color The color of the border. Write-only.

Default Value: 0,0,0

borderAlpha number The opacity of the border, 0.01.0. Write-only.

Default Value: 1.0

OverlayProperties-Rectangle3D
Type: object

The "rectangle3D" OverlayType is for 3D rectangles. It has properties in addition to the common OverlayProperties. It additionally has properties per the Shape entity, with the shape property value being "Quad".

Deprecated: Use local Entities instead.

Properties

Name Type Summary
name string The name of the overlay.
color Color The color of the overlay.

Default Value: 255,255,255

alpha number The opacity of the overlay, 0.01.0.

Default Value: 0.7

pulseMax number The maximum value of the pulse multiplier.

Default Value: 0

pulseMin number The minimum value of the pulse multiplier.

Default Value: 0

pulsePeriod number The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from pulseMin to pulseMax, then pulseMax to pulseMin in one period.

Default Value: 1

alphaPulse number If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

colorPulse number If non-zero, the color of the overlay is pulsed: the color value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

position Vec3 The position of the overlay center. Synonyms: p1, point, and start.
dimensions Vec3 The dimensions of the overlay. Synonyms: scale, size.
rotation Quat The orientation of the overlay. Synonym: orientation.
localPosition Vec3 The local position of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as position.
localRotation Quat The orientation of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as rotation. Synonym: localOrientation.
isSolid boolean true if the overlay is rendered as a solid, false if it is rendered as a wire frame. Synonyms: solid, isFilled, and filled. Antonyms: isWire and wire.

Default Value: false

ignorePickIntersection boolean true if Picks ignore the overlay, false if they don't. Synonym: ignoreRayIntersection.

Default Value: false

drawInFront boolean true if the overlay is rendered on top of the world layer but behind the HUD surface.

Default Value: false

drawHUDLayer boolean true if the overlay is rendered in front of everything, including the HUD surface.

Default Value: false

grabbable boolean true if the overlay can be grabbed, false if it can't be.

Default Value: false

parentID Uuid The avatar, entity, or overlay that the overlay is parented to.

Default Value: null

parentJointIndex number Integer value specifying the joint of the entity or avatar that the entity is parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather than a joint.

Default Value: 65535

OverlayProperties-Shape
Type: object

The "shape" OverlayType is for 3D shapes. It has properties in addition to the common OverlayProperties. It additionally has properties per the Shape entity.

Deprecated: Use local Entities instead.

Properties

Name Type Summary
name string The name of the overlay.
color Color The color of the overlay.

Default Value: 255,255,255

alpha number The opacity of the overlay, 0.01.0.

Default Value: 0.7

pulseMax number The maximum value of the pulse multiplier.

Default Value: 0

pulseMin number The minimum value of the pulse multiplier.

Default Value: 0

pulsePeriod number The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from pulseMin to pulseMax, then pulseMax to pulseMin in one period.

Default Value: 1

alphaPulse number If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

colorPulse number If non-zero, the color of the overlay is pulsed: the color value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

position Vec3 The position of the overlay center. Synonyms: p1, point, and start.
dimensions Vec3 The dimensions of the overlay. Synonyms: scale, size.
rotation Quat The orientation of the overlay. Synonym: orientation.
localPosition Vec3 The local position of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as position.
localRotation Quat The orientation of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as rotation. Synonym: localOrientation.
isSolid boolean true if the overlay is rendered as a solid, false if it is rendered as a wire frame. Synonyms: solid, isFilled, and filled. Antonyms: isWire and wire.

Default Value: false

ignorePickIntersection boolean true if Picks ignore the overlay, false if they don't. Synonym: ignoreRayIntersection.

Default Value: false

drawInFront boolean true if the overlay is rendered on top of the world layer but behind the HUD surface.

Default Value: false

drawHUDLayer boolean true if the overlay is rendered in front of everything, including the HUD surface.

Default Value: false

grabbable boolean true if the overlay can be grabbed, false if it can't be.

Default Value: false

parentID Uuid The avatar, entity, or overlay that the overlay is parented to.

Default Value: null

parentJointIndex number Integer value specifying the joint of the entity or avatar that the entity is parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather than a joint.

Default Value: 65535

shape Overlays.Shape The geometrical shape of the overlay.

Default Value: Hexagon

OverlayProperties-Sphere
Type: object

The "sphere" OverlayType is for 3D spheres. It has properties in addition to the common OverlayProperties. It additionally has properties per the Sphere entity.

Deprecated: Use local Entities instead.

Properties

Name Type Summary
name string The name of the overlay.
color Color The color of the overlay.

Default Value: 255,255,255

alpha number The opacity of the overlay, 0.01.0.

Default Value: 0.7

pulseMax number The maximum value of the pulse multiplier.

Default Value: 0

pulseMin number The minimum value of the pulse multiplier.

Default Value: 0

pulsePeriod number The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from pulseMin to pulseMax, then pulseMax to pulseMin in one period.

Default Value: 1

alphaPulse number If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

colorPulse number If non-zero, the color of the overlay is pulsed: the color value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

position Vec3 The position of the overlay center. Synonyms: p1, point, and start.
dimensions Vec3 The dimensions of the overlay. Synonyms: scale, size.
rotation Quat The orientation of the overlay. Synonym: orientation.
localPosition Vec3 The local position of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as position.
localRotation Quat The orientation of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as rotation. Synonym: localOrientation.
isSolid boolean true if the overlay is rendered as a solid, false if it is rendered as a wire frame. Synonyms: solid, isFilled, and filled. Antonyms: isWire and wire.

Default Value: false

ignorePickIntersection boolean true if Picks ignore the overlay, false if they don't. Synonym: ignoreRayIntersection.

Default Value: false

drawInFront boolean true if the overlay is rendered on top of the world layer but behind the HUD surface.

Default Value: false

drawHUDLayer boolean true if the overlay is rendered in front of everything, including the HUD surface.

Default Value: false

grabbable boolean true if the overlay can be grabbed, false if it can't be.

Default Value: false

parentID Uuid The avatar, entity, or overlay that the overlay is parented to.

Default Value: null

parentJointIndex number Integer value specifying the joint of the entity or avatar that the entity is parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather than a joint.

Default Value: 65535

OverlayProperties-Text
Type: object

The "text" OverlayType is for 2D text. It has properties in addition to the common OverlayProperties.

Properties

Name Type Summary
bounds Rect The position and size of the rectangle, in pixels. Write-only.
x number Integer left, x-coordinate value = bounds.x. Write-only.
y number Integer top, y-coordinate value = bounds.y. Write-only.
width number Integer width of the rectangle = bounds.width. Write-only.
height number Integer height of the rectangle = bounds.height. Write-only.
margin number The leftMargin and topMargin values, in pixels. Write-only.

Default Value: 0

leftMargin number The left margin's size, in pixels. This value is also used for the right margin. Write-only.

Default Value: 0

topMargin number The top margin's size, in pixels. This value is also used for the bottom margin. Write-only.

Default Value: 0

text string The text to display. Text does not automatically wrap; use "\n" for a line break. Text is clipped to the bounds. Write-only.

Default Value: ""

font.size number The size of the text, in pixels. Write-only.

Default Value: 18

lineHeight number The height of a line of text, in pixels. Write-only.

Default Value: 18

color Color The color of the text. Synonym: textColor. Write-only.

Default Value: 255,255,255

alpha number The opacity of the overlay, 0.01.0. Write-only.

Default Value: 1.0

backgroundColor Color The color of the background rectangle. Write-only.

Default Value: 0,0,0

backgroundAlpha number The opacity of the background rectangle, 0.01.0. Write-only.

Default Value: 0.7

OverlayProperties-Text3D
Type: object

The "text3D" OverlayType is for 3D text. It has properties in addition to the common OverlayProperties. It additionally has properties per the Text entity.

Deprecated: Use local Entities instead.

Properties

Name Type Summary
name string The name of the overlay.
color Color The color of the overlay text. Synonym: textColor.

Default Value: 255,255,255

alpha number The opacity of the overlay text, 0.01.0.

Currently not used; use textAlpha instead.

Default Value: 0.7

pulseMax number The maximum value of the pulse multiplier.

Default Value: 0

pulseMin number The minimum value of the pulse multiplier.

Default Value: 0

pulsePeriod number The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from pulseMin to pulseMax, then pulseMax to pulseMin in one period.

Default Value: 1

alphaPulse number If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

colorPulse number If non-zero, the color of the overlay is pulsed: the color value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

position Vec3 The position of the overlay center. Synonyms: p1, point, and start.
dimensions Vec3 The dimensions of the overlay. Synonyms: scale, size.
rotation Quat The orientation of the overlay. Synonym: orientation.
localPosition Vec3 The local position of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as position.
localRotation Quat The orientation of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as rotation. Synonym: localOrientation.
ignorePickIntersection boolean true if Picks ignore the overlay, false if they don't. Synonym: ignoreRayIntersection.

Default Value: false

drawInFront boolean true if the overlay is rendered on top of the world layer but behind the HUD surface.

Default Value: false

drawHUDLayer boolean true if the overlay is rendered in front of everything, including the HUD surface.

Default Value: false

grabbable boolean true if the overlay can be grabbed, false if it can't be.

Default Value: false

parentID Uuid The avatar, entity, or overlay that the overlay is parented to.

Default Value: null

parentJointIndex number Integer value specifying the joint of the entity or avatar that the entity is parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather than a joint.

Default Value: 65535

OverlayProperties-Web3D
Type: object

The "web3d" OverlayType is for 3D web surfaces. It has properties in addition to the common OverlayProperties. It additionally has properties per the Web entity.

Deprecated: Use local Entities instead.

Properties

Name Type Summary
name string The name of the overlay.
color Color The color of the overlay.

Default Value: 255,255,255

alpha number The opacity of the overlay, 0.01.0.

Default Value: 0.7

pulseMax number The maximum value of the pulse multiplier.

Default Value: 0

pulseMin number The minimum value of the pulse multiplier.

Default Value: 0

pulsePeriod number The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from pulseMin to pulseMax, then pulseMax to pulseMin in one period.

Default Value: 1

alphaPulse number If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

colorPulse number If non-zero, the color of the overlay is pulsed: the color value is multiplied by the current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise used.)

Default Value: 0

position Vec3 The position of the overlay center. Synonyms: p1, point, and start.
dimensions Vec3 The dimensions of the overlay. Synonyms: scale, size.
rotation Quat The orientation of the overlay. Synonym: orientation.
localPosition Vec3 The local position of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as position.
localRotation Quat The orientation of the overlay relative to its parent if the overlay has a parentID set, otherwise the same value as rotation. Synonym: localOrientation.
ignorePickIntersection boolean true if Picks ignore the overlay, false if they don't. Synonym: ignoreRayIntersection.

Default Value: false

drawInFront boolean true if the overlay is rendered on top of the world layer but behind the HUD surface.

Default Value: false

drawHUDLayer boolean true if the overlay is rendered in front of everything, including the HUD surface.

Default Value: false

grabbable boolean true if the overlay can be grabbed, false if it can't be.

Default Value: false

parentID Uuid The avatar, entity, or overlay that the overlay is parented to.

Default Value: null

parentJointIndex number Integer value specifying the joint of the entity or avatar that the entity is parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather than a joint.

Default Value: 65535

url string The URL of the web page to display.
OverlayType
Type: string

An overlay may be one of the following types:

Value2D/3DDescriptionProperties
"rectangle"2D A rectangle. OverlayProperties-Rectangle
"image"2D An image. OverlayProperties-Image
"text"2D Some text. OverlayProperties-Text
"cube"3D A cube. A "shape" overlay can also be used to create a cube.
Deprecated.
OverlayProperties-Cube
"sphere"3D A sphere. A "shape" overlay can also be used to create a sphere.
Deprecated.
OverlayProperties-Sphere
"shape"3D A geometric shape, such as a cube, sphere, or cylinder.
Deprecated.
OverlayProperties-Shape
"model"3D A model.
Deprecated.
OverlayProperties-Model
"image3d"3D An image. Synonym: "billboard".
Deprecated.
OverlayProperties-Image3D
"rectangle3d"3D A rectangle.
Deprecated.
OverlayProperties-Rectangle3D
"text3d"3D Some text.
Deprecated.
OverlayProperties-Text3D
"web3d"3D Web content.
Deprecated.
OverlayProperties-Web3D
"line3d"3D A line.
Deprecated.
OverlayProperties-Line3D
"grid"3D A grid of lines in a plane.
Deprecated.
OverlayProperties-Grid
"circle3d"3D A circle.
Deprecated.
OverlayProperties-Circle3D

2D overlays are rendered on the display surface in desktop mode and on the HUD surface in HMD mode. 3D overlays are rendered at a position and orientation in-world.

3D overlays are deprecated. Use local Entities instead.

RayToOverlayIntersectionResult
Type: object

The result of a PickRay search using findRayIntersection.

Properties

Name Type Summary
intersects boolean true if the PickRay intersected with a 3D overlay, otherwise false.
overlayID Uuid The UUID of the local entity that was intersected.
distance number The distance from the PickRay origin to the intersection point.
surfaceNormal Vec3 The normal of the overlay surface at the intersection point.
intersection Vec3 The position of the intersection point.
extraInfo object Additional intersection details, if available.
Shape
Type: string

A "shape" OverlayType may display as one of the following geometrical shapes:

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

Method Details

(static) addOverlay( type, properties ) → {Uuid}
Returns: The ID of the newly created overlay if successful, otherwise Uuid.NULL.

Adds an overlay to the scene.

Parameters

Name Type Description
type Overlays.OverlayType The type of the overlay to add.
properties Overlays.OverlayProperties The properties of the overlay to add.
Example

Add a cube overlay in front of your avatar.

var overlay = Overlays.addOverlay("cube", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.3, y: 0.3, z: 0.3 },
    solid: true
});
(static) cloneOverlay( id ) → {Uuid}
Returns: The ID of the new overlay (or entity) if successful, otherwise Uuid.NULL.

Creates a clone of an existing overlay (or entity).

Note: For cloning behavior of 3D overlays and entities, see Entities.cloneEntity.

Parameters

Name Type Description
id Uuid The ID of the overlay (or entity) to clone.
(static) deleteOverlay( id )

Deletes an overlay (or entity).

Parameters

Name Type Description
id Uuid The ID of the overlay (or entity) to delete.
(static) editOverlay( id, properties ) → {boolean}
Returns: false if Interface is exiting. Otherwise, if a 2D overlay then true always, and if a 3D overlay then true if the overlay was found and edited, otherwise false.

Edits an overlay's (or entity's) properties.

Parameters

Name Type Description
id Uuid The ID of the overlay (or entity) to edit.
properties Overlays.OverlayProperties The properties changes to make.
Example

Add an overlay in front of your avatar then change its color.

var overlay = Overlays.addOverlay("cube", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.3, y: 0.3, z: 0.3 },
    solid: true
});

var success = Overlays.editOverlay(overlay, {
    color: { red: 255, green: 0, blue: 0 }
});
print("Success: " + success);
(static) editOverlays( propertiesById ) → {boolean}
Returns: false if Interface is exiting, otherwise true.

Edits the properties of multiple overlays (or entities).

Parameters

Name Type Description
propertiesById object.<Uuid, Overlays.OverlayProperties> An object with overlay (or entity) IDs as keys and OverlayProperties edits to make as values.
Example

Create two overlays in front of your avatar then change their colors.

var overlayA = Overlays.addOverlay("cube", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: -0.3, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.3, y: 0.3, z: 0.3 },
    solid: true
});
var overlayB = Overlays.addOverlay("cube", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0.3, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.3, y: 0.3, z: 0.3 },
    solid: true
});

var overlayEdits = {};
overlayEdits[overlayA] = { color: { red: 255, green: 0, blue: 0 } };
overlayEdits[overlayB] = { color: { red: 0, green: 255, blue: 0 } };
var success = Overlays.editOverlays(overlayEdits);
print("Success: " + success);
(static) findOverlays( center, radius ) → {Array.<Uuid>}
Returns: The IDs of the overlays (local entities) that are visible and have bounding boxes that touch a search sphere.

Gets a list of visible 3D overlays (local entities) with bounding boxes that touch a search sphere.

Parameters

Name Type Description
center Vec3 The center of the search sphere.
radius number The radius of the search sphere.
Example

Create two overlays in front of your avatar then search for overlays near your avatar.

var overlayA = Overlays.addOverlay("cube", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: -0.3, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.3, y: 0.3, z: 0.3 },
    solid: true
});
print("Overlay A: " + overlayA);
var overlayB = Overlays.addOverlay("cube", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0.3, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.3, y: 0.3, z: 0.3 },
    solid: true
});
print("Overlay B: " + overlayB);

var overlaysFound = Overlays.findOverlays(MyAvatar.position, 5.0);
print("Overlays found: " + JSON.stringify(overlaysFound));
(static) findRayIntersection( pickRay, precisionPickingopt, includeopt, discardopt, visibleOnlyopt, collideableOnlyopt ) → {Overlays.RayToOverlayIntersectionResult}
Returns: The result of the search for the first intersected overlay (or local entity.

Finds the closest 3D overlay (or local entity) intersected by a PickRay.

Parameters

Name Type Attributes Default Value Description
pickRay PickRay The PickRay to use for finding overlays.
precisionPicking boolean <optional>
false true to pick against precise meshes, false to pick against coarse meshes. If true and the intersected entity is a model, the result's extraInfo property includes more information than it otherwise would.
include Array.<Uuid> <optional>
[] If not empty, then the search is restricted to these overlays (and local entities).
discard Array.<Uuid> <optional>
[] Overlays (and local entities) to ignore during the search.
visibleOnly boolean <optional>
false true if only overlays (and local entities) that are visible should be searched.
collideableOnly boolean <optional>
false true if only local entities that are not collisionless should be searched.
Example

Create a cube overlay in front of your avatar. Report 3D overlay intersection details for mouse clicks.

var overlay = Overlays.addOverlay("cube", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.3, y: 0.3, z: 0.3 },
    solid: true
});

Controller.mousePressEvent.connect(function (event) {
    var pickRay = Camera.computePickRay(event.x, event.y);
    var intersection = Overlays.findRayIntersection(pickRay);
    print("Intersection: " + JSON.stringify(intersection));
});
(static) getKeyboardFocusOverlay( ) → {Uuid}
Returns: The ID of the "web3d" overlay (Web entity) that has focus, if any, otherwise null.

Gets the ID of the "web3d" overlay (Web entity) that has keyboard focus.

(static) getOverlayAtPoint( point ) → {Uuid}
Returns: The ID of the 2D overlay at the specified point if found, otherwise null.

Gets the ID of the 2D overlay at a particular point on the desktop screen or HUD surface.

Parameters

Name Type Description
point Vec2 The point to check for an overlay.
Example

Create a 2D overlay and add an event function that reports the overlay clicked on, if any.

var overlay = Overlays.addOverlay("rectangle", {
    bounds: { x: 100, y: 100, width: 200, height: 100 },
    color: { red: 255, green: 255, blue: 255 }
});
print("Created: " + overlay);

Controller.mousePressEvent.connect(function (event) {
    var overlay = Overlays.getOverlayAtPoint({ x: event.x, y: event.y });
    print("Clicked: " + overlay);
});
(static) getOverlayObject( overlayID ) → {object}
Returns: The script object for the overlay if found.

Gets an overlay's (or entity's) script object. In particular, this is useful for accessing a "web3d" overlay's EventBridge script object to exchange messages with the web page script.

To send a message from an Interface script to a "web3d" overlay over its event bridge:

var overlayObject = Overlays.getOverlayObject(overlayID);
overlayObject.emitScriptEvent(message);

To receive a message from a "web3d" overlay over its event bridge in an Interface script:

var overlayObject = Overlays.getOverlayObject(overlayID);
overlayObject.webEventReceived.connect(function(message) {
    ...
};

Parameters

Name Type Description
overlayID Uuid The ID of the overlay to get the script object of.
Example

Exchange messages with a "web3d" overlay.

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

        EventBridge.scriptEventReceived.connect(onScriptEventReceived);

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

// Interface script file.
var web3DOverlay = Overlays.addOverlay("web3d", {
    type: "Web",
    position : Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y : 0.5, z : -3 })),
    rotation : MyAvatar.orientation,
    sourceUrl : Script.resolvePath("web3d.html"),
    alpha : 1.0
    });

var overlayObject;

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

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

Script.setTimeout(function() {
    overlayObject = Overlays.getOverlayObject(web3DOverlay);
    overlayObject.webEventReceived.connect(onWebEventReceived);
}, 500);

Script.scriptEnding.connect(function() {
    Overlays.deleteOverlay(web3DOverlay);
});
(static) getOverlaysProperties( propertiesById ) → {object.<Uuid, Overlays.OverlayProperties>}
Returns: An object with overlay (or entity) IDs as keys and OverlayProperties as values.

Gets the values of multiple overlays' (or entities') properties.

Parameters

Name Type Description
propertiesById object.<Uuid, Array.<string>> An object with overlay (or entity) IDs as keys and arrays of the names of properties to get for each as values.
Example

Create two cube overlays in front of your avatar then get some of their properties.

var overlayA = Overlays.addOverlay("cube", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: -0.3, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.3, y: 0.3, z: 0.3 },
    solid: true
});
var overlayB = Overlays.addOverlay("cube", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0.3, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.3, y: 0.3, z: 0.3 },
    solid: true
});
var propertiesToGet = {};
propertiesToGet[overlayA] = ["color", "alpha"];
propertiesToGet[overlayB] = ["dimensions"];
var properties = Overlays.getOverlaysProperties(propertiesToGet);
print("Overlays properties: " + JSON.stringify(properties));
(static) getOverlayType( id ) → {Overlays.OverlayType}
Returns: The type of the overlay if found, otherwise "unknown".

Gets the type of an overlay.

Parameters

Name Type Description
id Uuid The ID of the overlay to get the type of.
Example

Create an overlay in front of your avatar then get and report its type.

var overlay = Overlays.addOverlay("cube", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.3, y: 0.3, z: 0.3 },
    solid: true
});
var type = Overlays.getOverlayType(overlay);
print("Type: " + type); // cube
(static) getProperties( id, properties ) → {Overlays.OverlayProperties}
Returns: The values of valid properties if the overlay can be found, otherwise an empty object.

Gets specified property values of a 3D overlay (or entity).

Note: 2D overlays' property values cannot be retrieved.

Parameters

Name Type Description
id Uuid The ID of the overlay (or entity).
properties Array.<string> The names of the properties to get the values of.
Example

Create an overlay in front of your avatar then report some of its properties.

var overlay = Overlays.addOverlay("cube", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.3, y: 0.3, z: 0.3 },
    solid: true
});
var properties = Overlays.getProperties(overlay, ["color", "alpha", "grabbable"]);
print("Overlay properties: " + JSON.stringify(properties));
(static) getProperty( id, property ) → {object}
Returns: The value of the property if the 3D overlay and property can be found, otherwise undefined.

Gets a specified property value of a 3D overlay (or entity).

Note: 2D overlays' property values cannot be retrieved.

Parameters

Name Type Description
id Uuid The ID of the 3D overlay (or entity).
property string The name of the property to get the value of.
Example

Create an overlay in front of your avatar then report its alpha property value.

var overlay = Overlays.addOverlay("cube", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.3, y: 0.3, z: 0.3 },
    solid: true
});
var alpha = Overlays.getProperty(overlay, "alpha");
print("Overlay alpha: " + alpha);
(static) height( ) → {number}
Returns: The height, in pixels, of the Interface window if in desktop mode or the HUD surface if in HMD mode.

Gets the height of the Interface window or HUD surface.

(static) isAddedOverlay( id ) → {boolean}
Returns: true if an overlay (or entity) with the given ID exists, false if it doesn't.

Checks if an overlay (or entity) exists.

Parameters

Name Type Description
id Uuid The ID of the overlay (or entity) to check.
(static) isLoaded( id ) → {boolean}
Returns: true if the overlay's (or entity's) assets have been loaded, otherwise false.

Checks whether an overlay's (or entity's) assets have been loaded. For example, for an "image" overlay, the result indicates whether its image has been loaded.

Parameters

Name Type Description
id Uuid The ID of the overlay (or entity) to check.
Example

Create an image overlay and report whether its image is loaded after 1s.

var overlay = Overlays.addOverlay("image", {
    bounds: { x: 100, y: 100, width: 200, height: 200 },
    imageURL: "https://content.highfidelity.com/DomainContent/production/Particles/wispy-smoke.png"
});
Script.setTimeout(function () {
    var isLoaded = Overlays.isLoaded(overlay);
    print("Image loaded: " + isLoaded);
}, 1000);
(static) sendHoverEnterOverlay( id, event )

Generates a hover enter event on an overlay (or local entity).

Parameters

Name Type Description
id Uuid The ID of the overlay (or local entity) to generate a hover enter event on.
event PointerEvent The hover enter event details.
(static) sendHoverLeaveOverlay( id, event )

Generates a hover leave event on an overlay (or local entity).

Parameters

Name Type Description
id Uuid The ID of the overlay (or local entity) to generate a hover leave event on.
event PointerEvent The hover leave event details.
(static) sendHoverOverOverlay( id, event )

Generates a hover over event on an overlay (or entity).

Parameters

Name Type Description
id Uuid The ID of the overlay (or local entity) to generate a hover over event on.
event PointerEvent The hover over event details.
(static) sendMouseMoveOnOverlay( id, event )

Generates a mouse move event on an overlay (or local entity).

Parameters

Name Type Description
id Uuid The ID of the overlay (or local entity) to generate a mouse move event on.
event PointerEvent The mouse move event details.
(static) sendMousePressOnOverlay( id, event )

Generates a mouse press event on an overlay (or local entity).

Parameters

Name Type Description
id Uuid The ID of the overlay (or local entity) to generate a mouse press event on.
event PointerEvent The mouse press event details.
Example

Create a 2D rectangle overlay plus a 3D cube overlay and generate mousePressOnOverlay events for the 2D overlay.

var overlay3D = Overlays.addOverlay("cube", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.3, y: 0.3, z: 0.3 },
    solid: true
});
print("3D overlay: " + overlay);

var overlay2D = Overlays.addOverlay("rectangle", {
    bounds: { x: 100, y: 100, width: 200, height: 100 },
    color: { red: 255, green: 255, blue: 255 }
});
print("2D overlay: " + overlay);

// Overlays.mousePressOnOverlay by default applies only to 3D overlays.
Overlays.mousePressOnOverlay.connect(function(overlayID, event) {
    print("Clicked: " + overlayID);
});

Controller.mousePressEvent.connect(function (event) {
    // Overlays.getOverlayAtPoint applies only to 2D overlays.
    var overlay = Overlays.getOverlayAtPoint({ x: event.x, y: event.y });
    if (overlay) {
        Overlays.sendMousePressOnOverlay(overlay, {
            type: "press",
            id: 0,
            pos2D: event
        });
    }
});
(static) sendMouseReleaseOnOverlay( id, event )

Generates a mouse release event on an overlay (or local entity).

Parameters

Name Type Description
id Uuid The ID of the overlay (or local entity) to generate a mouse release event on.
event PointerEvent The mouse release event details.
(static) setKeyboardFocusOverlay( id )

Sets the "web3d" overlay (Web entity) that has keyboard focus.

Parameters

Name Type Description
id Uuid The ID of the "web3d" overlay (Web entity) to set keyboard focus to. Use null or Uuid.NULL to unset keyboard focus from an overlay (entity).
(static) textSize( id, text ) → {Size}
Returns: The size of the text if the object is a text overlay (or entity), otherwise { height: 0, width : 0 }. If the object is a 2D overlay, the size is in pixels; if the object is a 3D overlay (or entity), the size is in meters.

Calculates the size of some text in a text overlay (or entity). The overlay (or entity) need not be set visible.

Note: The size of text in a 3D overlay (or entity) cannot be calculated immediately after the overlay (or entity) is created; a short delay is required while the overlay (or entity) finishes being created.

Parameters

Name Type Description
id Uuid The ID of the overlay (or entity) to use for calculation.
text string The string to calculate the size of.
Example

Calculate the size of "hello" in a 3D text entity.

var overlay = Overlays.addOverlay("text3d", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -2 })),
    rotation: MyAvatar.orientation,
    lineHeight: 0.2,
    visible: false
});

Script.setTimeout(function() {
    var textSize = Overlays.textSize(overlay, "hello");
    print("Size of \"hello\": " + JSON.stringify(textSize));
}, 500);
(static) width( ) → {number}
Returns: The width, in pixels, of the Interface window if in desktop mode or the HUD surface if in HMD mode.

Gets the width of the Interface window or HUD surface.

Signal Details

hoverEnterOverlay( id, event )
Returns: Signal

Triggered when a mouse cursor starts hovering over an overlay. Only occurs for 3D overlays (unless you use sendHoverEnterOverlay for a 2D overlay).

Parameters

Name Type Description
id Uuid The ID of the overlay the mouse moved event occurred on.
event PointerEvent The mouse move event details.
Example

Create a cube overlay in front of your avatar and report when you start hovering your mouse over it.

var overlay = Overlays.addOverlay("cube", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.3, y: 0.3, z: 0.3 },
    solid: true
});
print("Overlay: " + overlay);
Overlays.hoverEnterOverlay.connect(function(overlayID, event) {
    print("Hover enter: " + overlayID);
});
hoverLeaveOverlay( id, event )
Returns: Signal

Triggered when a mouse cursor finishes hovering over an overlay. Only occurs for 3D overlays (unless you use sendHoverLeaveOverlay for a 2D overlay).

Parameters

Name Type Description
id Uuid The ID of the overlay the hover leave event occurred on.
event PointerEvent The hover leave event details.
hoverOverOverlay( id, event )
Returns: Signal

Triggered when a mouse cursor continues hovering over an overlay. Only occurs for 3D overlays (unless you use sendHoverOverOverlay for a 2D overlay).

Parameters

Name Type Description
id Uuid The ID of the overlay the hover over event occurred on.
event PointerEvent The hover over event details.
mouseDoublePressOffOverlay( )
Returns: Signal

Triggered when a mouse double press event occurs on something other than a 3D overlay.

mouseDoublePressOnOverlay( id, event )
Returns: Signal

Triggered when a mouse double press event occurs on an overlay. Only occurs for 3D overlays.

Parameters

Name Type Description
id Uuid The ID of the overlay the mouse double press event occurred on.
event PointerEvent The mouse double press event details.
mouseMoveOnOverlay( id, event )
Returns: Signal

Triggered when a mouse move event occurs on an overlay. Only occurs for 3D overlays (unless you use sendMouseMoveOnOverlay for a 2D overlay).

Parameters

Name Type Description
id Uuid The ID of the overlay the mouse moved event occurred on.
event PointerEvent The mouse move event details.
mousePressOffOverlay( )
Returns: Signal

Triggered when a mouse press event occurs on something other than a 3D overlay.

mousePressOnOverlay( id, event )
Returns: Signal

Triggered when a mouse press event occurs on an overlay. Only occurs for 3D overlays (unless you use sendMousePressOnOverlay for a 2D overlay).

Parameters

Name Type Description
id Uuid The ID of the overlay the mouse press event occurred on.
event PointerEvent The mouse press event details.
Example

Create a cube overlay in front of your avatar and report mouse clicks on it.

var overlay = Overlays.addOverlay("cube", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.3, y: 0.3, z: 0.3 },
    solid: true
});
print("My overlay: " + overlay);

Overlays.mousePressOnOverlay.connect(function(overlayID, event) {
    if (overlayID === overlay) {
        print("Clicked on my overlay");
    }
});
mouseReleaseOnOverlay( id, event )
Returns: Signal

Triggered when a mouse release event occurs on an overlay. Only occurs for 3D overlays (unless you use sendMouseReleaseOnOverlay for a 2D overlay).

Parameters

Name Type Description
id Uuid The ID of the overlay the mouse release event occurred on.
event PointerEvent The mouse release event details.
overlayDeleted( id )
Returns: Signal

Triggered when an overlay (or entity) is deleted.

Parameters

Name Type Description
id Uuid The ID of the overlay (or entity) that was deleted.
Example

Create an overlay then delete it after 1s.

var overlay = Overlays.addOverlay("cube", {
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    dimensions: { x: 0.3, y: 0.3, z: 0.3 },
    solid: true
});
print("Overlay: " + overlay);

Overlays.overlayDeleted.connect(function(overlayID) {
    print("Deleted: " + overlayID);
});
Script.setTimeout(function () {
    Overlays.deleteOverlay(overlay);
}, 1000);