Picks

Description

The Picks API lets you create and manage objects for repeatedly calculating intersections.

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

Properties

Name Type Summary
PICK_DOMAIN_ENTITIES FilterFlags Include domain entities when intersecting. Read-only.
PICK_AVATAR_ENTITIES FilterFlags Include avatar entities when intersecting. Read-only.
PICK_LOCAL_ENTITIES FilterFlags Include local entities when intersecting. Read-only.
PICK_AVATARS FilterFlags Include avatars when intersecting. Read-only.
PICK_HUD FilterFlags Include the HUD sphere when intersecting in HMD mode. Read-only.
PICK_ENTITIES FilterFlags Include domain and avatar entities when intersecting. Read-only.

Deprecated: This property is deprecated and will be removed. Use PICK_DOMAIN_ENTITIES | PICK_AVATAR_ENTITIES instead.

PICK_OVERLAYS FilterFlags Include local entities when intersecting. Read-only.

Deprecated: This property is deprecated and will be removed. Use PICK_LOCAL_ENTITIES instead.

PICK_INCLUDE_VISIBLE FilterFlags Include visible objects when intersecting. Read-only.

Warning: Is currently always enabled by default but may not be in the future.

PICK_INCLUDE_INVISIBLE FilterFlags Include invisible objects when intersecting. Read-only.
PICK_INCLUDE_COLLIDABLE FilterFlags Include collidable objects when intersecting. Read-only.

Warning: Is currently always enabled by default but may not be in the future.

PICK_INCLUDE_NONCOLLIDABLE FilterFlags Include non-collidable objects when intersecting. Read-only.
PICK_PRECISE FilterFlags Pick against exact meshes. Read-only.
PICK_COARSE FilterFlags Pick against coarse meshes. Read-only.
PICK_ALL_INTERSECTIONS FilterFlags If set, returns all intersections instead of just the closest. Read-only.

Warning: Not yet implemented.

INTERSECTED_NONE IntersectionType Intersected nothing. Read-only.
INTERSECTED_ENTITY IntersectionType Intersected an entity. Read-only.
INTERSECTED_LOCAL_ENTITY IntersectionType Intersected a local entity. Read-only.
INTERSECTED_OVERLAY IntersectionType Intersected a local entity. (3D overlays no longer exist.) Read-only.

Deprecated: This property is deprecated and will be removed. Use INTERSECTED_LOCAL_ENTITY instead.

INTERSECTED_AVATAR IntersectionType Intersected an avatar. Read-only.
INTERSECTED_HUD IntersectionType Intersected the HUD sphere. Read-only.
perFrameTimeBudget number The maximum time, in microseconds, to spend per frame updating pick results.

Methods

Name Return Value Summary
createPick number Creates a new pick. Different PickTypes use different properties, and within one PickType the properties you choose can lead to a wide range of behaviors. For example, with PickType.Ray, the properties could configure a mouse ray pick, an avatar head ray pick, or a joint ray pick.

Warning: Picks created using this method currently always intersect at least visible and collidable things but this may not always be the case.

disablePick None Disables a pick. Disabled picks do not update their pick results.
enablePick None Enables a pick. Enabled picks update their pick results.
getPrevPickResult RayPickResult | ParabolaPickResult | StylusPickResult | CollisionPickResult Gets the most recent result from a pick. A pick continues to be updated ready to return a result, as long as it is enabled.

Note: Stylus picks only intersect with objects in their include list, set using setIncludeItems.

INTERSECTED_AVATAR number

Deprecated: This function is deprecated and will be removed. Use the Picks.INTERSECTED_AVATAR property instead.

INTERSECTED_ENTITY number

Deprecated: This function is deprecated and will be removed. Use the Picks.INTERSECTED_ENTITY property instead.

INTERSECTED_HUD number

Deprecated: This function is deprecated and will be removed. Use the Picks.INTERSECTED_HUD property instead.

INTERSECTED_LOCAL_ENTITY number

Deprecated: This function is deprecated and will be removed. Use the Picks.INTERSECTED_LOCAL_ENTITY property instead.

INTERSECTED_NONE number

Deprecated: This function is deprecated and will be removed. Use the Picks.INTERSECTED_NONE property instead.

INTERSECTED_OVERLAY number

Deprecated: This function is deprecated and will be removed. Use the Picks.INTERSECTED_LOCAL_ENTITY property instead.

isLeftHand boolean Checks if a pick is associated with the left hand: a ray or parabola pick with joint set to "_CONTROLLER_LEFTHAND" or "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", or a stylus pick with hand set to 0.
isMouse boolean Checks if a pick is associated with the system mouse: a ray or parabola pick with joint set to "Mouse".
isRightHand boolean Checks if a pick is associated with the right hand: a ray or parabola pick with joint set to "_CONTROLLER_RIGHTHAND" or "_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND", or a stylus pick with hand set to 1.
PICK_ALL_INTERSECTIONS number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_ALL_INTERSECTIONS property instead.

PICK_AVATAR_ENTITIES number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_AVATAR_ENTITIES property instead.

PICK_AVATARS number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_AVATARS property instead.

PICK_COARSE number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_COARSE property instead.

PICK_DOMAIN_ENTITIES number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_DOMAIN_ENTITIES property instead.

PICK_ENTITIES number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_DOMAIN_ENTITIES | Picks.PICK_AVATAR_ENTITIES properties expression instead.

PICK_HUD number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_HUD property instead.

PICK_INCLUDE_COLLIDABLE number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_INCLUDE_COLLIDABLE property instead.

PICK_INCLUDE_INVISIBLE number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_INCLUDE_INVISIBLE property instead.

PICK_INCLUDE_NONCOLLIDABLE number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_INCLUDE_NONCOLLIDABLE property instead.

PICK_INCLUDE_VISIBLE number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_INCLUDE_VISIBLE property instead.

PICK_LOCAL_ENTITIES number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_LOCAL_ENTITIES property instead.

PICK_OVERLAYS number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_LOCAL_ENTITIES property instead.

PICK_PRECISE number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_PRECISE property instead.

removePick None Removes (deletes) a pick.
setIgnoreItems None Sets a list of entity and avatar IDs to ignore during intersection.

Note: Not used by stylus picks.

setIncludeItems None Sets a list of entity IDs and/or avatar IDs to include during intersection, instead of intersecting with everything.

Note: Stylus picks only intersect with objects in their include list.

setPrecisionPicking None Sets whether or not to use precision picking, i.e., whether to pick against precise meshes or coarse meshes. This has the same effect as using the PICK_PRECISE or PICK_COARSE filter flags.

Type Definitions

CollisionPickProperties
Type: object

A set of properties that can be passed to Picks.createPick when creating a new collision pick.

Properties

Name Type Attributes Summary
enabled boolean <optional>
true if this pick should start enabled, false if it should start disabled. Disabled picks do not update their pick results.

Default Value: false

filter FilterFlags <optional>
The filter for this pick to use. Construct using Picks FilterFlags property values (e.g., Picks.PICK_DOMAIN_ENTTITIES) combined with | (bitwise OR) operators.

Note: Collision picks do not intersect the HUD.

Default Value: 0

maxDistance number <optional>
The maximum distance at which this pick will intersect. A value of 0.0 means no maximum.

Default Value: 0.0

parentID Uuid <optional>
The ID of the parent: an avatar, an entity, or another pick.
parentJointIndex number <optional>
The joint of the parent to parent to, for example, an avatar joint. A value of 0 means no joint.
Used only if parentID is specified.

Default Value: 0

joint string <optional>
"Mouse" parents the pick to the mouse; "Avatar" parents the pick to the user's avatar head; a joint name parents to the joint in the user's avatar; otherwise, the pick is "static", not parented to anything.
Used only if parentID is not specified.
scaleWithParent boolean <optional>
true to scale the pick's dimensions and threshold according to the scale of the parent.

Default Value: true

shape Shape The collision region's shape and size. Dimensions are in world coordinates but scale with the parent if defined.
position Vec3 The position of the collision region, relative to the parent if defined.
orientation Quat The orientation of the collision region, relative to the parent if defined.
threshold number The approximate minimum penetration depth for a test object to be considered in contact with the collision region. The depth is in world coordinates but scales with the parent if defined.
collisionGroup CollisionMask <optional>
The type of objects the collision region collides as. Objects whose collision masks overlap with the region's collision group are considered to be colliding with the region.

Default Value: 8

ParabolaPickProperties
Type: object

A set of properties that can be passed to Picks.createPick when creating a new parabola pick.

Properties

Name Type Attributes Summary
enabled boolean <optional>
true if this pick should start enabled, false if it should start disabled. Disabled picks do not update their pick results.

Default Value: false

filter number <optional>
The filter for this pick to use. Construct using Picks FilterFlags property values (e.g., Picks.PICK_DOMAIN_ENTTITIES) combined with | (bitwise OR) operators.

Default Value: 0

maxDistance number <optional>
The maximum distance at which this pick will intersect. A value of 0.0 means no maximum.

Default Value: 0.0

parentID Uuid <optional>
The ID of the parent: an avatar, an entity, or another pick.
parentJointIndex number <optional>
The joint of the parent to parent to, for example, an avatar joint. A value of 0 means no joint.
Used only if parentID is specified.

Default Value: 0

joint string <optional>
"Mouse" parents the pick to the mouse; "Avatar" parents the pick to the user's avatar head; a joint name parents to the joint in the user's avatar; otherwise, the pick is "static", not parented to anything. Used only if parentID is not specified.
position Vec3 <optional>
The offset of the parabola origin from its parent if parented, otherwise the parabola origin in world coordinates.

Default Value: Vec3.ZERO

posOffset Vec3 <optional>
Synonym for position.
direction Vec3 <optional>
The offset of the parabola direction from its parent's y-axis if parented, otherwise the parabola direction in world coordinates.

Default Value: Vec3.UP direction if joint is specified, otherwise Vec3.FRONT.

dirOffset Vec3 <optional>
Synonym for direction.
orientation Quat <optional>
Alternative property for specifying direction. The value is applied to the default direction value.
speed number <optional>
The initial speed of the parabola in m/s, i.e., the initial speed of a virtual projectile whose trajectory defines the parabola.

Default Value: 1

accelerationAxis Vec3 <optional>
The acceleration of the parabola in m/s2, i.e., the acceleration of a virtual projectile whose trajectory defines the parabola, both magnitude and direction.

Default Value: -Vec3.UP

rotateAccelerationWithAvatar boolean <optional>
true if the acceleration axis should rotate with the avatar about the avatar's y-axis, false if it shouldn't.

Default Value: true

rotateAccelerationWithParent boolean <optional>
true if the acceleration axis should rotate with the parent about the parent's y-axis, if available.

Default Value: false

scaleWithParent boolean <optional>
true if the velocity and acceleration of the pick should scale with the avatar or other parent.

Default Value: true

scaleWithAvatar boolean <optional>
Synonym for scalewithParent.

Deprecated: This property is deprecated and will be removed.

Default Value: true

RayPickProperties
Type: object

A set of properties that can be passed to Picks.createPick when creating a new ray pick.

Properties

Name Type Attributes Summary
enabled boolean <optional>
true if this pick should start enabled, false if it should start disabled. Disabled picks do not update their pick results.

Default Value: false

filter FilterFlags <optional>
The filter for this pick to use. Construct using Picks FilterFlags property values (e.g., Picks.PICK_DOMAIN_ENTTITIES) combined with | (bitwise OR) operators.

Default Value: 0

maxDistance number <optional>
The maximum distance at which this pick will intersect. A value of 0.0 means no maximum.

Default Value: 0.0

parentID Uuid <optional>
The ID of the parent: an avatar, an entity, or another pick.
parentJointIndex number <optional>
The joint of the parent to parent to, for example, an avatar joint. A value of 0 means no joint.
Used only if parentID is specified.

Default Value: 0

joint string <optional>
"Mouse" parents the pick to the mouse; "Avatar" parents the pick to the user's avatar head; a joint name parents to the joint in the user's avatar; otherwise, the pick is "static", not parented to anything.
Used only if parentID is not specified.
position Vec3 <optional>
The offset of the ray origin from its parent if parented, otherwise the ray origin in world coordinates.

Default Value: Vec3.ZERO

posOffset Vec3 <optional>
Synonym for position.
direction Vec3 <optional>
The offset of the ray direction from its parent's y-axis if parented, otherwise the ray direction in world coordinates.

Default Value: Vec3.UP direction if joint is specified, otherwise -Vec3.UP.

dirOffset Vec3 <optional>
Synonym for direction.
orientation Quat <optional>
Alternative property for specifying direction. The value is applied to the default direction value.
StylusPickProperties
Type: object

A set of properties that can be passed to Picks.createPick when creating a new stylus pick.

Properties

Name Type Attributes Summary
hand number <optional>
0 for the left hand, 1 for the right hand, invalid (-1) otherwise.

Default Value: -1

enabled boolean <optional>
true if this pick should start enabled, false if it should start disabled. Disabled picks do not update their pick results.

Default Value: false

filter number <optional>
The filter for this pick to use. Construct using Picks FilterFlags property values (e.g., Picks.PICK_DOMAIN_ENTTITIES) combined with | (bitwise OR) operators.

Note: Stylus picks do not intersect avatars or the HUD.

Default Value: 0

maxDistance number <optional>
The maximum distance at which this pick will intersect. A value of 0.0 means no maximum.

Default Value: 0.0

tipOffset Vec3 <optional>
The position of the stylus tip relative to the hand position at default avatar scale.

Default Value: 0,0.095,0

Method Details

(static) createPick( type, properties ) → {number}
Returns: The ID of the pick created. 0 if invalid.

Creates a new pick. Different PickTypes use different properties, and within one PickType the properties you choose can lead to a wide range of behaviors. For example, with PickType.Ray, the properties could configure a mouse ray pick, an avatar head ray pick, or a joint ray pick.

Warning: Picks created using this method currently always intersect at least visible and collidable things but this may not always be the case.

Parameters

Name Type Description
type PickType The type of picking to use.
properties Picks.RayPickProperties | Picks.ParabolaPickProperties | Picks.StylusPickProperties | Picks.CollisionPickProperties Properties of the pick, per the pick type.
(static) disablePick( id )

Disables a pick. Disabled picks do not update their pick results.

Parameters

Name Type Description
id number The ID of the pick.
(static) enablePick( id )

Enables a pick. Enabled picks update their pick results.

Parameters

Name Type Description
id number The ID of the pick.
(static) getPrevPickResult( id ) → {RayPickResult|ParabolaPickResult|StylusPickResult|CollisionPickResult}
Returns: The most recent intersection result.

Gets the most recent result from a pick. A pick continues to be updated ready to return a result, as long as it is enabled.

Note: Stylus picks only intersect with objects in their include list, set using setIncludeItems.

Parameters

Name Type Description
id number The ID of the pick.
Example

Highlight entities under your mouse in desktop mode or that you're looking at in HMD mode.

// Highlight.
var HIGHLIGHT_LIST_NAME = "highlightEntitiesExampleList";
var HIGHLIGHT_LIST_TYPE = "entity";
Selection.enableListHighlight(HIGHLIGHT_LIST_NAME, {});

// Ray pick.
var PICK_FILTER = Picks.PICK_DOMAIN_ENTITIES | Picks.PICK_AVATAR_ENTITIES
        | Picks.PICK_INCLUDE_COLLIDABLE | Picks.PICK_INCLUDE_NONCOLLIDABLE;
var rayPick = Picks.createPick(PickType.Ray, {
    enabled: true,
    filter: PICK_FILTER,
    joint: HMD.active ? "Avatar" : "Mouse"
});

// Highlight intersected entity.
var highlightedEntityID = null;
Script.update.connect(function () {
    var rayPickResult = Picks.getPrevPickResult(rayPick);
    if (rayPickResult.intersects) {
        if (rayPickResult.objectID !== highlightedEntityID) {
            if (highlightedEntityID) {
                Selection.removeFromSelectedItemsList(HIGHLIGHT_LIST_NAME, HIGHLIGHT_LIST_TYPE, highlightedEntityID);
            }
            highlightedEntityID = rayPickResult.objectID;
            Selection.addToSelectedItemsList(HIGHLIGHT_LIST_NAME, HIGHLIGHT_LIST_TYPE, highlightedEntityID);
        }
    } else {
        if (highlightedEntityID) {
            Selection.removeFromSelectedItemsList(HIGHLIGHT_LIST_NAME, HIGHLIGHT_LIST_TYPE, highlightedEntityID);
            highlightedEntityID = null;
        }
    }
});

// Clean up.
Script.scriptEnding.connect(function () {
    if (highlightedEntityID) {
        Selection.removeFromSelectedItemsList(HIGHLIGHT_LIST_NAME, HIGHLIGHT_LIST_TYPE, highlightedEntityID);
    }
});
(static) INTERSECTED_AVATAR( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.INTERSECTED_AVATAR property instead.

(static) INTERSECTED_ENTITY( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.INTERSECTED_ENTITY property instead.

(static) INTERSECTED_HUD( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.INTERSECTED_HUD property instead.

(static) INTERSECTED_LOCAL_ENTITY( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.INTERSECTED_LOCAL_ENTITY property instead.

(static) INTERSECTED_NONE( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.INTERSECTED_NONE property instead.

(static) INTERSECTED_OVERLAY( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.INTERSECTED_LOCAL_ENTITY property instead.

(static) isLeftHand( id ) → {boolean}
Returns: true if the pick is associated with the left hand, false if it isn't.

Checks if a pick is associated with the left hand: a ray or parabola pick with joint set to "_CONTROLLER_LEFTHAND" or "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", or a stylus pick with hand set to 0.

Parameters

Name Type Description
id number The ID of the pick.
(static) isMouse( id ) → {boolean}
Returns: true if the pick is associated with the system mouse, false if it isn't.

Checks if a pick is associated with the system mouse: a ray or parabola pick with joint set to "Mouse".

Parameters

Name Type Description
id number The ID of the pick.
(static) isRightHand( id ) → {boolean}
Returns: true if the pick is associated with the right hand, false if it isn't.

Checks if a pick is associated with the right hand: a ray or parabola pick with joint set to "_CONTROLLER_RIGHTHAND" or "_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND", or a stylus pick with hand set to 1.

Parameters

Name Type Description
id number The ID of the pick.
(static) PICK_ALL_INTERSECTIONS( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_ALL_INTERSECTIONS property instead.

(static) PICK_AVATAR_ENTITIES( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_AVATAR_ENTITIES property instead.

(static) PICK_AVATARS( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_AVATARS property instead.

(static) PICK_COARSE( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_COARSE property instead.

(static) PICK_DOMAIN_ENTITIES( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_DOMAIN_ENTITIES property instead.

(static) PICK_ENTITIES( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_DOMAIN_ENTITIES | Picks.PICK_AVATAR_ENTITIES properties expression instead.

(static) PICK_HUD( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_HUD property instead.

(static) PICK_INCLUDE_COLLIDABLE( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_INCLUDE_COLLIDABLE property instead.

(static) PICK_INCLUDE_INVISIBLE( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_INCLUDE_INVISIBLE property instead.

(static) PICK_INCLUDE_NONCOLLIDABLE( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_INCLUDE_NONCOLLIDABLE property instead.

(static) PICK_INCLUDE_VISIBLE( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_INCLUDE_VISIBLE property instead.

(static) PICK_LOCAL_ENTITIES( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_LOCAL_ENTITIES property instead.

(static) PICK_OVERLAYS( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_LOCAL_ENTITIES property instead.

(static) PICK_PRECISE( ) → {number}
Returns: number

Deprecated: This function is deprecated and will be removed. Use the Picks.PICK_PRECISE property instead.

(static) removePick( id )

Removes (deletes) a pick.

Parameters

Name Type Description
id number The ID of the pick.
(static) setIgnoreItems( id, ignoreItems )

Sets a list of entity and avatar IDs to ignore during intersection.

Note: Not used by stylus picks.

Parameters

Name Type Description
id number The ID of the pick.
ignoreItems Array.<Uuid> The list of IDs to ignore.
(static) setIncludeItems( id, includeItems )

Sets a list of entity IDs and/or avatar IDs to include during intersection, instead of intersecting with everything.

Note: Stylus picks only intersect with objects in their include list.

Parameters

Name Type Description
id number The ID of the pick.
includeItems Array.<Uuid> The list of IDs to include.
(static) setPrecisionPicking( id, precisionPicking )

Sets whether or not to use precision picking, i.e., whether to pick against precise meshes or coarse meshes. This has the same effect as using the PICK_PRECISE or PICK_COARSE filter flags.

Parameters

Name Type Description
id number The ID of the pick.
precisionPicking boolean true to use precision picking, false to use coarse picking.