Overlays

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.

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) {
    ...
};
getOverlayType Overlays.OverlayType

Gets the type of an overlay.

height number

Gets the height of the Interface window or HUD surface.

isAddedOverlay boolean

Checks if an overlay (or entity) exists.

isLoaded boolean

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

sendHoverEnterOverlay None

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

sendHoverLeaveOverlay None

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

sendHoverOverOverlay None

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

sendMouseMoveOnOverlay None

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

sendMousePressOnOverlay None

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

sendMouseReleaseOnOverlay None

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

setKeyboardFocusOverlay None

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

textSize Size

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

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

width number

Gets the width of the Interface window or HUD surface.

Signals

Name Summary
hoverEnterOverlay

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

hoverLeaveOverlay

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

hoverOverOverlay

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

mouseDoublePressOffOverlay

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

mouseDoublePressOnOverlay

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

mouseMoveOnOverlay

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

mousePressOffOverlay

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

mousePressOnOverlay

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

mouseReleaseOnOverlay

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

overlayDeleted

Triggered when an overlay (or entity) is deleted.

Type Definitions

OverlayProperties
Type: object

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

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

Properties

Name Type Summary
id Uuid

The ID of the overlay. Read-only.

type Overlays.OverlayType

The overlay's type. Read-only.

visible boolean

true if the overlay is rendered, false if it isn't.

Default Value: true

See:

OverlayProperties-Image
Type: object

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

Properties

Name Type Summary
bounds Rect

The position and size of the image display area, in pixels. Write-only.

x number

Integer left, x-coordinate value of the image display area = bounds.x. Write-only.

y number

Integer top, y-coordinate value of the image display area = bounds.y. Write-only.

width number

Integer width of the image display area = bounds.width. Write-only.

height number

Integer height of the image display area = bounds.height. Write-only.

imageURL string

The URL of the image file to display. The image is scaled to fit to the bounds. Write-only.

subImage Rect

The portion of the image to use. If not specified, the whole image is used. Write-only.

color Color

The color to apply over the top of the image to colorize it. Write-only.

Default Value: 0,0,0

alpha number

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

Default Value: 0.0

OverlayProperties-Rectangle
Type: object

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

Properties

Name Type Summary
bounds Rect

The position and size of the rectangle, in pixels. Write-only.

x number

Integer left, x-coordinate value = bounds.x. Write-only.

y number

Integer top, y-coordinate value = bounds.y. Write-only.

width number

Integer width of the rectangle = bounds.width. Write-only.

height number

Integer height of the rectangle = bounds.height. Write-only.

radius number

Integer corner radius, in pixels. Write-only.

Default Value: 0

color Color

The color of the overlay. Write-only.

Default Value: 0,0,0

alpha number

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

Default Value: 1.0

borderWidth number

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

Default Value: 1

borderColor Color

The color of the border. Write-only.

Default Value: 0,0,0

borderAlpha number

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

Default Value: 1.0

OverlayProperties-Text
Type: object

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

Properties

Name Type Summary
bounds Rect

The position and size of the rectangle, in pixels. Write-only.

x number

Integer left, x-coordinate value = bounds.x. Write-only.

y number

Integer top, y-coordinate value = bounds.y. Write-only.

width number

Integer width of the rectangle = bounds.width. Write-only.

height number

Integer height of the rectangle = bounds.height. Write-only.

margin number

The leftMargin and topMargin values, in pixels. Write-only.

Default Value: 0

leftMargin number

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

Default Value: 0

topMargin number

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

Default Value: 0

text string

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

Default Value: ""

font.size number

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

Default Value: 18

lineHeight number

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

Default Value: 18

color Color

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

Default Value: 255,255,255

alpha number

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

Default Value: 1.0

backgroundColor Color

The color of the background rectangle. Write-only.

Default Value: 0,0,0

backgroundAlpha number

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

Default Value: 0.7

OverlayType
Type: string

An overlay may be one of the following types:

Value2D/3DDescriptionProperties
"rectangle"2D A rectangle. OverlayProperties-Rectangle
"image"2D An image. OverlayProperties-Image
"text"2D Some text. OverlayProperties-Text
"cube"3D

A cube. A "shape" overlay can also be used to create a cube.

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.

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.

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) 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) 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.overte.org/Bazaar/Assets/Textures/Defaults/Interface/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);