Selection

Description

The Selection API provides a means of grouping together and highlighting avatars and entities in named lists.

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

Example

Outline an entity when it is grabbed by the mouse or a controller.

// Create an entity and copy the following script into the entity's "Script URL" field.
// Move the entity behind another entity to see the occluded outline.
(function () {
    var LIST_NAME = "SelectionExample",
        ITEM_TYPE = "entity",
        HIGHLIGHT_STYLE = {
            outlineUnoccludedColor: { red: 0, green: 180, blue: 239 },
            outlineUnoccludedAlpha: 0.5,
            outlineOccludedColor: { red: 239, green: 180, blue: 0 },
            outlineOccludedAlpha: 0.5,
            outlineWidth: 4
        };

    Selection.enableListHighlight(LIST_NAME, HIGHLIGHT_STYLE);

    this.startNearGrab = function (entityID) {
        Selection.addToSelectedItemsList(LIST_NAME, ITEM_TYPE, entityID);
    };

    this.startDistanceGrab = function (entityID) {
        Selection.addToSelectedItemsList(LIST_NAME, ITEM_TYPE, entityID);
    };

    this.releaseGrab = function (entityID) {
        Selection.removeFromSelectedItemsList(LIST_NAME, ITEM_TYPE, entityID);
    };

    Script.scriptEnding.connect(function () {
        Selection.removeListFromMap(LIST_NAME);
    });
});

Methods

Name Return Value Summary
addToSelectedItemsList boolean Adds an item to a selection list. The list is created if it doesn't exist.
clearSelectedItemsList boolean Removes all items from a selection list.
disableListHighlight boolean Disables highlighting for a selection list.

Note: This function implicitly calls disableListToScene.

disableListToScene boolean Disables scene selection for a selection list.
enableListHighlight boolean Enables highlighting for a selection list. All items in or subsequently added to the list are displayed with the highlight effect specified. The method can be called multiple times with different values in the style to modify the highlighting.

Note: This function implicitly calls enableListToScene.

enableListToScene boolean Enables scene selection for a selection list. All items in or subsequently added to the list are sent to a scene selection in the rendering engine for debugging purposes.
getHighlightedListNames Array.<string> Gets the names of all current selection lists that have highlighting enabled.
getListHighlightStyle Selection.HighlightStyle Gets the current highlighting style for a selection list.
getListNames Array.<string> Gets the names of all current selection lists.
getSelectedItemsList Selection.SelectedItemsList Gets the list of avatars and entities in a selection list.
printList None Prints the list of avatars and entities in a selection to the program log (but not the Script Log window).
removeFromSelectedItemsList boolean Removes an item from a selection list.
removeListFromMap boolean Deletes a selection list.

Signals

Name Summary
selectedItemsListChanged Triggered when a selection list's content changes or the list is deleted.

Type Definitions

HighlightStyle
Type: object

The highlighting style of a selection list.

Properties

Name Type Summary
outlineUnoccludedColor Color Unoccluded outline color.

Default Value: 255,178,51

outlineOccludedColor Color Occluded outline color.

Default Value: 255,178,51

fillUnoccludedColor Color Unoccluded fill color.

Default Value: 51,178,255

fillOccludedColor Color Occluded fill color.

Default Value: 51,178,255

outlineUnoccludedAlpha number Unoccluded outline alpha, range 0.01.0.

Default Value: 0.9

outlineOccludedAlpha number Occluded outline alpha, range 0.01.0.

Default Value: 0.9

fillUnoccludedAlpha number Unoccluded fill alpha, range 0.01.0.

Default Value: 0.0

fillOccludedAlpha number Occluded fill alpha, range 0.01.0.

Default Value: 0.0

outlineWidth number Width of the outline, in pixels.

Default Value: 2

isOutlineSmooth boolean true to fade the outside edge of the outline, false to have a sharp edge.

Default Value: false

ItemType
Type: string

The type of a specific item in a selection list.

ValueDescription
"avatar"The item is an avatar.
"entity"The item is an entity.

SelectedItemsList
Type: object

A selection list.

Properties

Name Type Summary
avatars Array.<Uuid> The IDs of the avatars in the selection list.
entities Array.<Uuid> The IDs of the entities in the selection list.

Method Details

(static) addToSelectedItemsList( listName, itemType, itemID ) → {boolean}
Returns: true if the item was successfully added or already existed in the list, otherwise false.

Adds an item to a selection list. The list is created if it doesn't exist.

Parameters

Name Type Description
listName string The name of the selection list to add the item to.
itemType Selection.ItemType The type of item being added.
itemID Uuid The ID of the item to add.
(static) clearSelectedItemsList( listName ) → {boolean}
Returns: true always.

Removes all items from a selection list.

Parameters

Name Type Description
listName string The name of the selection list.
(static) disableListHighlight( listName ) → {boolean}
Returns: true always.

Disables highlighting for a selection list.

Note: This function implicitly calls disableListToScene.

Parameters

Name Type Description
listName string The name of the selection list.
(static) disableListToScene( listName ) → {boolean}
Returns: true always.

Disables scene selection for a selection list.

Parameters

Name Type Description
listName string The name of the selection list.
(static) enableListHighlight( listName, highlightStyle ) → {boolean}
Returns: true always.

Enables highlighting for a selection list. All items in or subsequently added to the list are displayed with the highlight effect specified. The method can be called multiple times with different values in the style to modify the highlighting.

Note: This function implicitly calls enableListToScene.

Parameters

Name Type Description
listName string The name of the selection list.
highlightStyle Selection.HighlightStyle The highlight style.
(static) enableListToScene( listName ) → {boolean}
Returns: true always.

Enables scene selection for a selection list. All items in or subsequently added to the list are sent to a scene selection in the rendering engine for debugging purposes.

Parameters

Name Type Description
listName string The name of the selection list.
(static) getHighlightedListNames( ) → {Array.<string>}
Returns: The names of the selection lists that currently have highlighting enabled.

Gets the names of all current selection lists that have highlighting enabled.

(static) getListHighlightStyle( listName ) → {Selection.HighlightStyle}
Returns: The highlight style of the selection list if the list exists and highlighting is enabled, otherwise an empty object.

Gets the current highlighting style for a selection list.

Parameters

Name Type Description
listName string The name of the selection list.
(static) getListNames( ) → {Array.<string>}
Returns: The names of all current selection lists.

Gets the names of all current selection lists.

Example

List all the current selection lists.

print("Selection lists: " + Selection.getListNames());
(static) getSelectedItemsList( listName ) → {Selection.SelectedItemsList}
Returns: The content of the selection list if the list exists, otherwise an empty object.

Gets the list of avatars and entities in a selection list.

Parameters

Name Type Description
listName string The name of the selection list.
(static) printList( listName )

Prints the list of avatars and entities in a selection to the program log (but not the Script Log window).

Parameters

Name Type Description
listName string The name of the selection list.
(static) removeFromSelectedItemsList( listName, itemType, itemID ) → {boolean}
Returns: true if the item was successfully removed or was not in the list, otherwise false.

Removes an item from a selection list.

Parameters

Name Type Description
listName string The name of the selection list to remove the item from.
itemType Selection.ItemType The type of item being removed.
itemID Uuid The ID of the item to remove.
(static) removeListFromMap( listName ) → {boolean}
Returns: true if the selection existed and was successfully removed, otherwise false.

Deletes a selection list.

Parameters

Name Type Description
listName string The name of the selection list to delete.

Signal Details

selectedItemsListChanged( listName )
Returns: Signal

Triggered when a selection list's content changes or the list is deleted.

Parameters

Name Type Description
listName string The name of the selection list that changed.