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 | Picks.ParabolaPickProperties | Picks.CollisionPickProperties 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|ParabolaPickResult|CollisionPickResult}
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 | ParabolaPickResult | CollisionPickResult
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 or Parabola 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 or Parabola 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 or Parabola 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

CollisionPickProperties
A set of properties that can be passed to Picks.createPick to create a new Collision Pick.
Type: object
Properties:
Name Type Description
shape Shape The information about the collision region's size and shape.
position Vec3 The position of the collision region.
orientation Quat The orientation of the collision region.
ParabolaPickProperties
A set of properties that can be passed to Picks.createPick to create a new Parabola 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 Parabola Picks. If "Mouse", it will create a Parabola Pick that follows the system mouse, in desktop or HMD. If "Avatar", it will create a Joint Parabola Pick that follows your avatar's head. Otherwise, it will create a Joint Parabola Pick that follows the given joint, if it exists on your current avatar.
posOffset Vec3 <optional>
Vec3.ZERO Only for Joint Parabola Picks. A local joint position offset, in meters. x = upward, y = forward, z = lateral
dirOffset Vec3 <optional>
Vec3.UP Only for Joint Parabola Picks. A local joint direction offset. x = upward, y = forward, z = lateral
position Vec3 <optional>
Only for Static Parabola Picks. The world-space origin of the parabola segment.
direction Vec3 <optional>
-Vec3.FRONT Only for Static Parabola Picks. The world-space direction of the parabola segment.
speed number <optional>
1 The initial speed of the parabola, i.e. the initial speed of the projectile whose trajectory defines the parabola.
accelerationAxis Vec3 <optional>
-Vec3.UP The acceleration of the parabola, i.e. the acceleration of the projectile whose trajectory defines the parabola, both magnitude and direction.
rotateAccelerationWithAvatar boolean <optional>
true Whether or not the acceleration axis should rotate with your avatar's local Y axis.
scaleWithAvatar boolean <optional>
false If true, the velocity and acceleration of the Pick will scale linearly with your avatar.
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.