Overlays

Description

(Note: 3D Overlays are deprecated. Use local entities instead.) The Overlays API provides facilities to create and interact with overlays. Overlays are 2D and 3D objects visible only to yourself and that aren't persisted to the domain. They are used for UI.

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

Properties

Name Type Summary
keyboardFocusOverlay Uuid Get or set the Web entity that has keyboard focus. If no entity has keyboard focus, returns null; set to null or Uuid.NULL to clear keyboard focus.

Methods

Name Return Value Summary
addOverlay Uuid Add an overlay to the scene.
cloneOverlay Uuid Create a clone of an existing entity (or 2D overlay).
deleteOverlay None Delete an entity or 2D overlay.
editOverlay boolean Edit an overlay's properties.
editOverlays boolean Edit multiple overlays' properties.
findOverlays Array.<Uuid> Return a list of local entities with bounding boxes that touch a search sphere.
findRayIntersection Overlays.RayToOverlayIntersectionResult Find the closest 3D overlay intersected by a PickRay. Overlays with their drawInFront property set to true have priority over overlays that don't, except that tablet overlays have priority over any drawInFront overlays behind them. I.e., if a drawInFront overlay is behind one that isn't drawInFront, the drawInFront overlay is returned, but if a tablet overlay is in front of a drawInFront overlay, the tablet overlay is returned.
getKeyboardFocusOverlay Uuid Get the ID of the Web3D entity that has keyboard focus.
getOverlayAtPoint Uuid Get the ID of the 2D overlay at a particular point on the screen or HUD.
getOverlayObject object Get the overlay script object. In particular, this is useful for accessing the event bridge for a web3d overlay.
getOverlaysProperties object.<Uuid, Overlays.OverlayProperties> Get the values of multiple overlays' properties.
getOverlayType string Get the type of an entity or 2D overlay.
getProperties Overlays.OverlayProperties Get the values of an overlay's properties.
getProperty object Get the value of a 3D overlay's property.
height number Get the height of the window or HUD.
isAddedOverlay boolean Check if there is an object of a given ID.
isLoaded boolean Check whether an overlay's assets have been loaded. For example, for an image overlay the result indicates whether its image has been loaded.
sendHoverEnterOverlay None Generate a hover enter event on an overlay.
sendHoverLeaveOverlay None Generate a hover leave event on an overlay.
sendHoverOverOverlay None Generate a hover over event on an overlay.
sendMouseMoveOnOverlay None Generate a mouse move event on an overlay.
sendMousePressOnOverlay None Generate a mouse press event on an overlay.
sendMouseReleaseOnOverlay None Generate a mouse release event on an overlay.
setKeyboardFocusOverlay None Set the Web3D entity that has keyboard focus.
textSize Size Calculates the size of the given text in the specified object if it is a text entity or overlay.
width number Get the width of the window or HUD.

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 is deleted.

Type Definitions

OverlayProperties
Type: object

Different overlay types have different properties: some common to all overlays (listed below) and some specific to each OverlayType (linked to below). The properties are accessed as an object of property names and values. 3D Overlays are local entities, internally, so they also support the corresponding entity properties.

Properties

Name Type Summary
id Uuid The ID of the overlay. Read-only.
type Overlays.OverlayType The overlay type. Read-only.
visible boolean If true, the overlay is rendered, otherwise it is not rendered.

Default Value: true

See:

OverlayProperties-Circle
Type: object

The "Circle" OverlayType is for 3D circle.

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.0 - 1.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 Synonyms: solid, isFilled, and filled. Antonyms: isWire and wire.

Default Value: false

ignorePickIntersection boolean If true, picks ignore the overlay. ignoreRayIntersection is a synonym.

Default Value: false

drawInFront boolean If true, the overlay is rendered in front of objects in the world, but behind the HUD.

Default Value: false

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

Default Value: false

grabbable boolean Signal to grabbing scripts whether or not this overlay can be grabbed.

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 skeleton joint that the overlay is attached to if parentID is an avatar skeleton. A value of 65535 means "no joint".

Default Value: 65535

startAt number = 0 - The counter - clockwise angle from the overlay's x-axis that drawing starts at in degrees.
endAt number = 360 - The counter - clockwise angle from the overlay's x-axis that drawing ends at in degrees.
outerRadius number = 1 - The outer radius of the overlay in meters. Synonym: radius.
innerRadius number = 0 - The inner radius of the overlay in meters.
color Color = 255, 255, 255 - The color of the overlay. Setting this value also sets the values of innerStartColor, innerEndColor, outerStartColor, and outerEndColor.
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.
innerEndColor Color The color at the inner end point of the overlay.
outerStartColor Color The color at the outer start point of the overlay.
outerEndColor Color The color at the outer end point of the overlay.
alpha number = 0.5 - The opacity of the overlay, 0.0 -1.0. Setting this value also sets the values of innerStartAlpha, innerEndAlpha, outerStartAlpha, and outerEndAlpha. Synonym: Alpha; write - only.
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 = 0 - The alpha at the inner start point of the overlay.
innerEndAlpha number = 0 - The alpha at the inner end point of the overlay.
outerStartAlpha number = 0 - The alpha at the outer start point of the overlay.
outerEndAlpha number = 0 - The alpha at the outer end point of the overlay.
hasTickMarks boolean = false - If true, tick marks are drawn.
majorTickMarksAngle number = 0 - The angle between major tick marks, in degrees.
minorTickMarksAngle number = 0 - The angle between minor tick marks, in degrees.
majorTickMarksLength number = 0 - 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.
minorTickMarksLength number = 0 - 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.
majorTickMarksColor Color = 0, 0, 0 - The color of the major tick marks.
minorTickMarksColor Color = 0, 0, 0 - The color of the minor tick marks.
OverlayProperties-Cube
Type: object

The "Cube" OverlayType is for 3D cubes.

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.0 - 1.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 Synonyms: solid, isFilled, and filled. Antonyms: isWire and wire.

Default Value: false

ignorePickIntersection boolean If true, picks ignore the overlay. ignoreRayIntersection is a synonym.

Default Value: false

drawInFront boolean If true, the overlay is rendered in front of objects in the world, but behind the HUD.

Default Value: false

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

Default Value: false

grabbable boolean Signal to grabbing scripts whether or not this overlay can be grabbed.

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 skeleton joint that the overlay is attached to if parentID is an avatar skeleton. A value of 65535 means "no joint".

Default Value: 65535

OverlayProperties-Grid
Type: object

The "Grid" OverlayType is for 3D grid.

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.0 - 1.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 If true, picks ignore the overlay. ignoreRayIntersection is a synonym.

Default Value: false

drawInFront boolean If true, the overlay is rendered in front of objects in the world, but behind the HUD.

Default Value: false

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

Default Value: false

grabbable boolean Signal to grabbing scripts whether or not this overlay can be grabbed.

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 skeleton joint that the overlay is attached to if parentID is an avatar skeleton. A value of 65535 means "no joint".

Default Value: 65535

followCamera boolean If true, the grid is always visible even as the camera moves to another position.

Default Value: true

majorGridEvery number Integer number of minorGridEvery intervals at which to draw a thick grid line. Minimum value = 1.

Default Value: 5

minorGridEvery number Real number of meters at which to draw thin grid lines. Minimum value = 0.001.

Default Value: 1

OverlayProperties-Image
Type: object

The "Image" OverlayType is a 2D image.

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 Vec2 Integer coordinates of the top left pixel to start using image content from. Write-only.

Default Value: 0,0

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.0 - 1.0. Write-only.

Default Value: 0.0

OverlayProperties-Image3D
Type: object

The "Image3D" OverlayType is for 3D images.

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.0 - 1.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 If true, picks ignore the overlay. ignoreRayIntersection is a synonym.

Default Value: false

drawInFront boolean If true, the overlay is rendered in front of objects in the world, but behind the HUD.

Default Value: false

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

Default Value: false

grabbable boolean Signal to grabbing scripts whether or not this overlay can be grabbed.

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 skeleton joint that the overlay is attached to if parentID is an avatar skeleton. A value of 65535 means "no joint".

Default Value: 65535

isFacingAvatar boolean If true, the overlay is rotated to face the user's camera about an axis parallel to the user's avatar's "up" direction.
url string The URL of the PNG or JPG image to display.
subImage Rect The portion of the image to display. Defaults to the full image.
emissive boolean If true, the overlay is displayed at full brightness, otherwise it is rendered with scene lighting.
keepAspectRatio bool overlays will maintain the aspect ratio when the subImage is applied.

Default Value: true

OverlayProperties-Line
Type: object

The "Line" OverlayType is for 3D lines.

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.0 - 1.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 If true, picks ignore the overlay. ignoreRayIntersection is a synonym.

Default Value: false

drawInFront boolean If true, the overlay is rendered in front of objects in the world, but behind the HUD.

Default Value: false

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

Default Value: false

grabbable boolean Signal to grabbing scripts whether or not this overlay can be grabbed.

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 skeleton joint that the overlay is attached to if parentID is an avatar skeleton. A value of 65535 means "no joint".

Default Value: 65535

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

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

Default Value: 65535

start Vec3 The start point of the line. Synonyms: startPoint and p1.
end Vec3 The end point of the line. Synonyms: endPoint and p2.
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. Synonym: localPosition.
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.
glow number If glow > 0, the line is rendered with a glow.

Default Value: 0

lineWidth number Width of the line, in meters.

Default Value: 0.02

OverlayProperties-Model
Type: object

The "Model" OverlayType is for 3D models.

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 If true, picks ignore the overlay. ignoreRayIntersection is a synonym.

Default Value: false

drawInFront boolean If true, the overlay is rendered in front of objects in the world, but behind the HUD.

Default Value: false

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

Default Value: false

grabbable boolean Signal to grabbing scripts whether or not this overlay can be grabbed.

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 skeleton joint that the overlay is attached to if parentID is an avatar skeleton. A value of 65535 means "no 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.

Default Value: 0.0

textures object.<name, url> Maps the named textures in the model to the JPG or PNG images in the urls.
jointNames Array.<string> The names of the joints - if any - in the model. Read-only.
jointRotations Array.<Quat> The relative rotations of the model's joints.
jointTranslations Array.<Vec3> The relative translations of the model's joints.
jointOrientations Array.<Quat> The absolute orientations of the model's joints, in world coordinates. Read-only.
jointPositions Array.<Vec3> The absolute positions of the model's joints, in world coordinates. Read-only.
animationSettings.url string The URL of an FBX file containing an animation to play.

Default Value: ""

animationSettings.fps number The frame rate (frames/sec) to play the animation at.

Default Value: 0

animationSettings.firstFrame number The frame to start playing at.

Default Value: 0

animationSettings.lastFrame number The frame to finish playing at.

Default Value: 0

animationSettings.currentFrame number The current frame being played.

Default Value: 0

animationSettings.running boolean Whether or not the animation is playing.

Default Value: false

animationSettings.loop boolean Whether or not the animation should repeat in a loop.

Default Value: false

animationSettings.hold boolean Whether or not when the animation finishes, the rotations and translations of the last frame played should be maintained.

Default Value: false

animationSettings.allowTranslation boolean Whether or not translations contained in the animation should be played.

Default Value: false

OverlayProperties-Rectangle
Type: object

The "Rectangle" OverlayType is for 2D rectangles.

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.
color Color The color of the overlay. Write-only.

Default Value: 0,0,0

alpha number The opacity of the overlay, 0.0 - 1.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

radius number Integer corner radius, in pixels. Write-only.

Default Value: 0

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

Default Value: 0,0,0

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

Default Value: 1.0

OverlayProperties-Rectangle3D
Type: object

The "Rectangle3D" OverlayType is for 3D rectangles.

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.0 - 1.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 Synonyms: solid, isFilled, and filled. Antonyms: isWire and wire.

Default Value: false

ignorePickIntersection boolean If true, picks ignore the overlay. ignoreRayIntersection is a synonym.

Default Value: false

drawInFront boolean If true, the overlay is rendered in front of objects in the world, but behind the HUD.

Default Value: false

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

Default Value: false

grabbable boolean Signal to grabbing scripts whether or not this overlay can be grabbed.

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 skeleton joint that the overlay is attached to if parentID is an avatar skeleton. A value of 65535 means "no joint".

Default Value: 65535

OverlayProperties-Shape
Type: object

The "Shape" OverlayType is for 3D shapes.

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.0 - 1.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 Synonyms: solid, isFilled, and filled. Antonyms: isWire and wire.

Default Value: false

ignorePickIntersection boolean If true, picks ignore the overlay. ignoreRayIntersection is a synonym.

Default Value: false

drawInFront boolean If true, the overlay is rendered in front of objects in the world, but behind the HUD.

Default Value: false

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

Default Value: false

grabbable boolean Signal to grabbing scripts whether or not this overlay can be grabbed.

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 skeleton joint that the overlay is attached to if parentID is an avatar skeleton. A value of 65535 means "no 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.

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.0 - 1.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 Synonyms: solid, isFilled, and filled. Antonyms: isWire and wire.

Default Value: false

ignorePickIntersection boolean If true, picks ignore the overlay. ignoreRayIntersection is a synonym.

Default Value: false

drawInFront boolean If true, the overlay is rendered in front of objects in the world, but behind the HUD.

Default Value: false

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

Default Value: false

grabbable boolean Signal to grabbing scripts whether or not this overlay can be grabbed.

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 skeleton joint that the overlay is attached to if parentID is an avatar skeleton. A value of 65535 means "no joint".

Default Value: 65535

OverlayProperties-Text
Type: object

The "Text" OverlayType is for 2D text.

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 Sets 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.0 - 1.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. Write-only.

Default Value: 0.7

OverlayProperties-Text3D
Type: object

The "Text3D" OverlayType is for 3D text.

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.0 - 1.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 If true, picks ignore the overlay. ignoreRayIntersection is a synonym.

Default Value: false

drawInFront boolean If true, the overlay is rendered in front of objects in the world, but behind the HUD.

Default Value: false

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

Default Value: false

grabbable boolean Signal to grabbing scripts whether or not this overlay can be grabbed.

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 skeleton joint that the overlay is attached to if parentID is an avatar skeleton. A value of 65535 means "no joint".

Default Value: 65535

isFacingAvatar boolean If true, the overlay is rotated to face the user's camera about an axis parallel to the user's avatar's "up" direction.
text string The text to display.Text does not automatically wrap; use \n for a line break.

Default Value: ""

textAlpha number The text alpha value.

Default Value: 1

backgroundColor Color The background color.

Default Value: 0,0,0

backgroundAlpha number The background alpha value.

Default Value: 0.7

lineHeight number The height of a line of text in meters.

Default Value: 1

leftMargin number The left margin, in meters.

Default Value: 0.1

topMargin number The top margin, in meters.

Default Value: 0.1

rightMargin number The right margin, in meters.

Default Value: 0.1

bottomMargin number The bottom margin, in meters.

Default Value: 0.1

OverlayProperties-Web
Type: object

The "Web" OverlayType is for 3D web surfaces.

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.0 - 1.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 If true, picks ignore the overlay. ignoreRayIntersection is a synonym.

Default Value: false

drawInFront boolean If true, the overlay is rendered in front of objects in the world, but behind the HUD.

Default Value: false

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

Default Value: false

grabbable boolean Signal to grabbing scripts whether or not this overlay can be grabbed.

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 skeleton joint that the overlay is attached to if parentID is an avatar skeleton. A value of 65535 means "no joint".

Default Value: 65535

isFacingAvatar boolean If true, the overlay is rotated to face the user's camera about an axis parallel to the user's avatar's "up" direction.
url string The URL of the Web page to display.
scriptURL string The URL of a JavaScript file to inject into the Web page.

Default Value: ""

dpi number The dots per inch to display the Web page at, on the overlay.

Default Value: 30

maxFPS number The maximum update rate for the Web overlay content, in frames/second.

Default Value: 10

inputMode string The user input mode to use - either "Touch" or "Mouse".

Default Value: Touch

OverlayType
Type: string

An overlay may be one of the following types:

Value2D/3DDescription
image2DAn image. Synonym: billboard.
rectangle2DA rectangle.
text2DText.
cube3DA cube. Can also use a shape overlay to create a cube.
sphere3DA sphere. Can also use a shape overlay to create a sphere.
rectangle3d3DA rectangle.
shape3DA geometric shape, such as a cube, sphere, or cylinder.
model3DA model.
text3d3DText.
image3d3DAn image.
web3d3DWeb content.
line3d3DA line.
grid3DA grid of lines in a plane.
circle3d3DA circle.

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, but are deprecated (use local entities instead).

Each overlay type has different OverlayProperties.

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
"Line"1DA line oriented in 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.

Add 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 object if successful, otherwise Uuid.NULL.

Create a clone of an existing entity (or 2D overlay).

Parameters

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

Delete an entity or 2D overlay.

Parameters

Name Type Description
id Uuid The ID of the object to delete.
(static) editOverlay( id, properties ) → {boolean}
Returns: true if the overlay was found and edited, otherwise false.

Edit an overlay's properties.

Parameters

Name Type Description
id Uuid The ID of the overlay 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: true if all overlays were found and edited, otherwise false (some may have been found and edited).

Edit multiple overlays' properties.

Parameters

Name Type Description
propertiesById object.<Uuid, Overlays.OverlayProperties> An object with overlay 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: An array of entity IDs with bounding boxes that touch a search sphere.

Return a list of 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 cube entities in front of your avatar then search for entities 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 closest 3D overlay intersected by pickRay, taking into account overlayIDsToInclude and overlayIDsToExclude if they're not empty.

Find the closest 3D overlay intersected by a PickRay. Overlays with their drawInFront property set to true have priority over overlays that don't, except that tablet overlays have priority over any drawInFront overlays behind them. I.e., if a drawInFront overlay is behind one that isn't drawInFront, the drawInFront overlay is returned, but if a tablet overlay is in front of a drawInFront overlay, the tablet overlay is returned.

Parameters

Name Type Attributes Default Value Description
pickRay PickRay The PickRay to use for finding overlays.
precisionPicking boolean <optional>
false Unused; exists to match Entity API.
include Array.<Uuid> <optional>
[] If not empty then the search is restricted to these overlays.
discard Array.<Uuid> <optional>
[] Overlays to ignore during the search.
visibleOnly boolean <optional>
false If true then only entities that are visible are searched.
collideableOnly boolean <optional>
false If true then only entities that are not collisionless are searched.
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 Web overlay that has focus, if any, otherwise null.

Get the ID of the Web3D entity that has keyboard focus.

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

Get the ID of the 2D overlay at a particular point on the screen or HUD.

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.

Get the overlay script object. In particular, this is useful for accessing the event bridge for a web3d overlay.

Parameters

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

Receive "hello" messages from a web3d overlay.

// HTML file: name "web3d.html".
<!DOCTYPE html>
<html>
<head>
    <title>HELLO</title>
</head>
<body>
    <h1>HELLO</h1></h1>
    <script>
        setInterval(function () {
            EventBridge.emitWebEvent("hello");
        }, 2000);
    </script>
</body>
</html>

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

function onWebEventReceived(event) {
    print("onWebEventReceived() : " + JSON.stringify(event));
}

overlayObject = Overlays.getOverlayObject(web3dOverlay);
overlayObject.webEventReceived.connect(onWebEventReceived);

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

Get the values of multiple overlays' properties.

Parameters

Name Type Description
propertiesById object.<Uuid, Array.<string>> An object with overlay 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 ) → {string}
Returns: The type of the object if found, otherwise an empty string.

Get the type of an entity or 2D overlay.

Parameters

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

Create an object 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);
(static) getProperties( id, properties ) → {Overlays.OverlayProperties}
Returns: The values of valid properties if the overlay can be found, otherwise undefined.

Get the values of an overlay's properties.

Parameters

Name Type Description
id Uuid The ID of the overlay.
properties Array.<string> An array of names of 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.

Get the value of a 3D overlay's property.

Parameters

Name Type Description
id Uuid The ID of the overlay. Must be for a 3D OverlayType.
property string The name of the property value to get.
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 if in HMD mode.

Get the height of the window or HUD.

(static) isAddedOverlay( id ) → {boolean}
Returns: true if an object with the given ID exists, false otherwise.

Check if there is an object of a given ID.

Parameters

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

Check whether an overlay'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 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 )

Generate a hover enter event on an overlay.

Parameters

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

Generate a hover leave event on an overlay.

Parameters

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

Generate a hover over event on an overlay.

Parameters

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

Generate a mouse move event on an overlay.

Parameters

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

Generate a mouse press event on an overlay.

Parameters

Name Type Description
id Uuid The ID of the overlay 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 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("3D overlay: " + overlay);

var overlay = 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 )

Generate a mouse release event on an overlay.

Parameters

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

Set the Web3D entity that has keyboard focus.

Parameters

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

Calculates the size of the given text in the specified object if it is a text entity or overlay.

Parameters

Name Type Description
id Uuid The ID of the object 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,
    text: "hello",
    lineHeight: 0.2
});
var textSize = Overlays.textSize(overlay, "hello");
print("Size of \"hello\": " + JSON.stringify(textSize));
(static) width( ) → {number}
Returns: The width, in pixels, of the Interface window if in desktop mode or the HUD if in HMD mode.

Get the width of the window or HUD.

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 is deleted.

Parameters

Name Type Description
id Uuid The ID of the overlay 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);