Selection

Description

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

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

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.