Overlays - Vircadia API Docs

Description

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

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.

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

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-Rectangle
OverlayProperties-Image
OverlayProperties-Text
OverlayProperties-Cube — Deprecated.
OverlayProperties-Sphere — Deprecated.
OverlayProperties-Shape — Deprecated.
OverlayProperties-Model — Deprecated.
OverlayProperties-Rectangle3D — Deprecated.
OverlayProperties-Image3D — Deprecated.
OverlayProperties-Text3D — Deprecated.
OverlayProperties-Web3D — Deprecated.
OverlayProperties-Line3D — Deprecated.
OverlayProperties-Grid — Deprecated.
OverlayProperties-Circle3D — Deprecated.

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.0` – `1.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.0` – `1.0`. Default Value: 0.7
innerEndAlpha	number	The opacity at the inner end point of the overlay, `0.0` – `1.0`. Default Value: 0.7
outerStartAlpha	number	The opacity at the outer start point of the overlay, `0.0` – `1.0`. Default Value: 0.7
outerEndAlpha	number	The opacity at the outer end point of the overlay, `0.0` – `1.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.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	`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.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	`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.0` – `1.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.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	`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.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	`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. Currently doesn't work. 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`. Note: 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`. Note: 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`. Currently doesn't work.
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`. Currently doesn't work.
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 glTF, FBX, or OBJ model used for the overlay. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs respectively). Baked models' URLs have ".baked" before the file type. Model files may also be compressed in GZ format, in which case the URL ends in ".gz".
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.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
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. 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.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	`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.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	`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.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	`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.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, `0.0` – `1.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.0` – `1.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.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	`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:

Value	2D/3D	Description	Properties
`"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:

Value	Dimensions	Description
`"Circle"`	2D	A circle oriented in 3D.
`"Cone"`	3D
`"Cube"`	3D
`"Cylinder"`	3D
`"Dodecahedron"`	3D
`"Hexagon"`	3D	A hexagonal prism.
`"Icosahedron"`	3D
`"Octagon"`	3D	An octagonal prism.
`"Octahedron"`	3D
`"Quad"`	2D	A square oriented in 3D.
`"Sphere"`	3D
`"Tetrahedron"`	3D
`"Torus"`	3D	Not implemented.
`"Triangle"`	3D	A triangular prism.

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.vircadia.com/eu-c-1/vircadia-assets/interface/default/default_particle.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);