Picks

Available in: Interface Scripts Client Entity Scripts

The Picks API lets you create and manage objects for repeatedly calculating intersections in different ways.
Methods

Type Definitions

Properties:
Name Type Description
PICK_NOTHING number A filter flag. Don't intersect with anything. Read-only.
PICK_ENTITIES number A filter flag. Include entities when intersecting. Read-only.
PICK_OVERLAYS number A filter flag. Include overlays when intersecting. Read-only.
PICK_AVATARS number A filter flag. Include avatars when intersecting. Read-only.
PICK_HUD number A filter flag. Include the HUD sphere when intersecting in HMD mode. Read-only.
PICK_COARSE number A filter flag. Pick against coarse meshes, instead of exact meshes. Read-only.
PICK_INCLUDE_INVISIBLE number A filter flag. Include invisible objects when intersecting. Read-only.
PICK_INCLUDE_NONCOLLIDABLE number A filter flag. Include non-collidable objects when intersecting. Read-only.
PICK_ALL_INTERSECTIONS number Read-only.
INTERSECTED_NONE number An intersection type. Intersected nothing with the given filter flags. Read-only.
INTERSECTED_ENTITY number An intersection type. Intersected an entity. Read-only.
INTERSECTED_OVERLAY number An intersection type. Intersected an overlay. Read-only.
INTERSECTED_AVATAR number An intersection type. Intersected an avatar. Read-only.
INTERSECTED_HUD number An intersection type. Intersected the HUD sphere. Read-only.
perFrameTimeBudget number The max number of usec to spend per frame updating Pick results. Read-only.

Methods

createPick(type, properties) → {number}
Adds 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, depending on which optional parameters you pass, you could create a Static Ray Pick, a Mouse Ray Pick, or a Joint Ray Pick.
Parameters:
Name Type Description
type PickType A PickType that specifies the method of picking to use
properties Picks.RayPickProperties | Picks.StylusPickProperties A PickProperties object, containing all the properties for initializing this Pick
Returns:
The ID of the created Pick. Used for managing the Pick. 0 if invalid.
Type: number
disablePick(uid)
Disables a Pick.
Parameters:
Name Type Description
uid number The ID of the Pick, as returned by Picks.createPick.
enablePick(uid)
Enables a Pick.
Parameters:
Name Type Description
uid number The ID of the Pick, as returned by Picks.createPick.
getPrevPickResult(uid) → {RayPickResult|StylusPickResult}
Get the most recent pick result from this Pick. This will be updated as long as the Pick is enabled.
Parameters:
Name Type Description
uid number The ID of the Pick, as returned by Picks.createPick.
Returns:
The most recent intersection result. This will be different for different PickTypes.
Type: RayPickResult | StylusPickResult
INTERSECTED_AVATAR() → {number}
Returns:
Type: number
INTERSECTED_ENTITY() → {number}
Returns:
Type: number
INTERSECTED_HUD() → {number}
Returns:
Type: number
INTERSECTED_NONE() → {number}
Returns:
Type: number
INTERSECTED_OVERLAY() → {number}
Returns:
Type: number
isLeftHand(uid) → {boolean}
Check if a Pick is associated with the left hand.
Parameters:
Name Type Description
uid number The ID of the Pick, as returned by Picks.createPick.
Returns:
True if the Pick is a Joint Ray Pick with joint == "_CONTROLLER_LEFTHAND" or "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", or a Stylus Pick with hand == 0.
Type: boolean
isMouse(uid) → {boolean}
Check if a Pick is associated with the system mouse.
Parameters:
Name Type Description
uid number The ID of the Pick, as returned by Picks.createPick.
Returns:
True if the Pick is a Mouse Ray Pick, false otherwise.
Type: boolean
isRightHand(uid) → {boolean}
Check if a Pick is associated with the right hand.
Parameters:
Name Type Description
uid number The ID of the Pick, as returned by Picks.createPick.
Returns:
True if the Pick is a Joint Ray Pick with joint == "_CONTROLLER_RIGHTHAND" or "_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND", or a Stylus Pick with hand == 1.
Type: boolean
PICK_ALL_INTERSECTIONS() → {number}
Returns:
Type: number
PICK_AVATARS() → {number}
Returns:
Type: number
PICK_COARSE() → {number}
Returns:
Type: number
PICK_ENTITIES() → {number}
Returns:
Type: number
PICK_HUD() → {number}
Returns:
Type: number
PICK_INCLUDE_INVISIBLE() → {number}
Returns:
Type: number
PICK_INCLUDE_NONCOLLIDABLE() → {number}
Returns:
Type: number
PICK_NOTHING() → {number}
Returns:
Type: number
PICK_OVERLAYS() → {number}
Returns:
Type: number
removePick(uid)
Removes a Pick.
Parameters:
Name Type Description
uid number The ID of the Pick, as returned by Picks.createPick.
setIgnoreItems(uid, ignoreItems)
Sets a list of Entity IDs, Overlay IDs, and/or Avatar IDs to ignore during intersection. Not used by Stylus Picks.
Parameters:
Name Type Description
uid number The ID of the Pick, as returned by Picks.createPick.
ignoreItems Array.<Uuid> A list of IDs to ignore.
setIncludeItems(uid, includeItems)
Sets a list of Entity IDs, Overlay IDs, and/or Avatar IDs to include during intersection, instead of intersecting with everything. Stylus Picks only intersect with objects in their include list.
Parameters:
Name Type Description
uid number The ID of the Pick, as returned by Picks.createPick.
includeItems Array.<Uuid> A list of IDs to include.
setPrecisionPicking(uid, precisionPicking)
Sets whether or not to use precision picking.
Parameters:
Name Type Description
uid number The ID of the Pick, as returned by Picks.createPick.
precisionPicking boolean Whether or not to use precision picking

Type Definitions

RayPickProperties
A set of properties that can be passed to Picks.createPick to create a new Ray Pick.
Type: object
Properties:
Name Type Attributes Default Description
enabled boolean <optional>
false If this Pick should start enabled or not. Disabled Picks do not updated their pick results.
filter number <optional>
Picks.PICK_NOTHING The filter for this Pick to use, constructed using filter flags combined using bitwise OR.
maxDistance number <optional>
0.0 The max distance at which this Pick will intersect. 0.0 = no max. <0.0 is invalid.
joint string <optional>
Only for Joint or Mouse Ray Picks. If "Mouse", it will create a Ray Pick that follows the system mouse, in desktop or HMD. If "Avatar", it will create a Joint Ray Pick that follows your avatar's head. Otherwise, it will create a Joint Ray Pick that follows the given joint, if it exists on your current avatar.
posOffset Vec3 <optional>
Vec3.ZERO Only for Joint Ray Picks. A local joint position offset, in meters. x = upward, y = forward, z = lateral
dirOffset Vec3 <optional>
Vec3.UP Only for Joint Ray Picks. A local joint direction offset. x = upward, y = forward, z = lateral
position Vec3 <optional>
Only for Static Ray Picks. The world-space origin of the ray.
direction Vec3 <optional>
-Vec3.UP Only for Static Ray Picks. The world-space direction of the ray.
StylusPickProperties
A set of properties that can be passed to Picks.createPick to create a new Stylus Pick.
Type: object
Properties:
Name Type Attributes Default Description
hand number <optional>
-1 An integer. 0 == left, 1 == right. Invalid otherwise.
enabled boolean <optional>
false If this Pick should start enabled or not. Disabled Picks do not updated their pick results.
filter number <optional>
Picks.PICK_NOTHING The filter for this Pick to use, constructed using filter flags combined using bitwise OR.
maxDistance number <optional>
0.0 The max distance at which this Pick will intersect. 0.0 = no max. <0.0 is invalid.