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 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.
shape Shape The information about the collision region's size and shape. Dimensions are in world space, but will scale with the parent if defined.
position Vec3 The position of the collision region, relative to a parent if defined.
orientation Quat The orientation of the collision region, relative to a parent if defined.
threshold float The approximate minimum penetration depth for a test object to be considered in contact with the collision region. The depth is measured in world space, but will scale with the parent if defined.
collisionGroup CollisionMask <optional>
8 The type of object this collision pick collides as. Objects whose collision masks overlap with the pick's collision group will be considered colliding with the pick.
parentID Uuid The ID of the parent, either an avatar, an entity, an overlay, or a pick.
parentJointIndex number <optional>
0 The joint of the parent to parent to, for example, the joints on the model of an avatar. (default = 0, no joint)
joint string If "Mouse," parents the pick to the mouse. If "Avatar," parents the pick to MyAvatar's head. Otherwise, parents to the joint of the given name on MyAvatar.
scaleWithParent boolean <optional>
true If true, the collision pick's dimensions and threshold will adjust according to the scale of the parent.
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.
parentID Uuid The ID of the parent, either an avatar, an entity, an overlay, or a pick.
parentJointIndex number <optional>
0 The joint of the parent to parent to, for example, the joints on the model of an avatar. (default = 0, no joint)
joint string If "Mouse," parents the pick to the mouse. If "Avatar," parents the pick to MyAvatar's head. Otherwise, parents to the joint of the given name on MyAvatar.
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 the avatar's local Y axis.
rotateAccelerationWithParent boolean <optional>
false Whether or not the acceleration axis should rotate with the parent's local Y axis, if available.
scaleWithParent boolean <optional>
true If true, the velocity and acceleration of the Pick will scale linearly with the parent, if available. scaleWithAvatar is an alias but is deprecated.
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.
parentID Uuid The ID of the parent, either an avatar, an entity, an overlay, or a pick.
parentJointIndex number <optional>
0 The joint of the parent to parent to, for example, the joints on the model of an avatar. (default = 0, no joint)
joint string If "Mouse," parents the pick to the mouse. If "Avatar," parents the pick to MyAvatar's head. Otherwise, parents to the joint of the given name on MyAvatar.
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.