Picks

Description

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

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

Properties

Name Type Summary
PICK_ENTITIES number A filter flag. Include domain and avatar entities when intersecting. Read-only.. Deprecated.
PICK_OVERLAYS number A filter flag. Include local entities when intersecting. Read-only.. Deprecated.
PICK_DOMAIN_ENTITIES number A filter flag. Include domain entities when intersecting. Read-only..
PICK_AVATAR_ENTITIES number A filter flag. Include avatar entities when intersecting. Read-only..
PICK_LOCAL_ENTITIES number A filter flag. Include local entities 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_INCLUDE_VISIBLE number A filter flag. Include visible objects when intersecting. Read-only..
PICK_INCLUDE_INVISIBLE number A filter flag. Include invisible objects when intersecting. Read-only..
PICK_INCLUDE_COLLIDABLE number A filter flag. Include collidable objects when intersecting. Read-only..
PICK_INCLUDE_NONCOLLIDABLE number A filter flag. Include non-collidable objects when intersecting. Read-only..
PICK_PRECISE number A filter flag. Pick against exact meshes. Read-only..
PICK_COARSE number A filter flag. Pick against coarse meshes. 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_LOCAL_ENTITY number An intersection type. Intersected a local entity.
INTERSECTED_OVERLAY number An intersection type. Intersected an entity (3D Overlays no longer exist). 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.

Methods

Name Return Value Summary
createPick 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. Picks created with this method always intersect at least visible and collidable things
disablePick None Disables a Pick.
enablePick None Enables a Pick.
getPrevPickResult RayPickResult | StylusPickResult | ParabolaPickResult | CollisionPickResult Get the most recent pick result from this Pick. This will be updated as long as the Pick is enabled.
INTERSECTED_AVATAR number
INTERSECTED_ENTITY number
INTERSECTED_HUD number
INTERSECTED_NONE number
INTERSECTED_OVERLAY number
INTERSECTED_OVERLAY number
isLeftHand boolean Check if a Pick is associated with the left hand.
isMouse boolean Check if a Pick is associated with the system mouse.
isRightHand boolean Check if a Pick is associated with the right hand.
PICK_ALL_INTERSECTIONS number
PICK_AVATAR_ENTITIES number
PICK_AVATARS number
PICK_COARSE number
PICK_DOMAIN_ENTITIES number
PICK_ENTITIES number
PICK_HUD number
PICK_INCLUDE_COLLIDABLE number
PICK_INCLUDE_INVISIBLE number
PICK_INCLUDE_NONCOLLIDABLE number
PICK_INCLUDE_VISIBLE number
PICK_LOCAL_ENTITIES number
PICK_OVERLAYS number
PICK_PRECISE number
removePick None Removes a Pick.
setIgnoreItems None Sets a list of Entity IDs and/or Avatar IDs to ignore during intersection. 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. Stylus Picks only intersect with objects in their include list.
setPrecisionPicking None Sets whether or not to use precision picking.

Type Definitions

CollisionPickProperties
Type: object

A set of properties that can be passed to Picks.createPick to create a new Collision Pick.

Properties

Name Type Attributes Summary
enabled boolean <optional>
If this Pick should start enabled or not. Disabled Picks do not updated their pick results.

Default Value: false

filter number <optional>
The filter for this Pick to use, constructed using filter flags combined using bitwise OR.

Default Value: 0

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>
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.

Default Value: 8

parentID Uuid The ID of the parent, either an avatar, an entity, or a pick.
parentJointIndex number <optional>
The joint of the parent to parent to, for example, the joints on the model of an avatar. (default = 0, no joint)

Default Value: 0

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>
If true, the collision pick's dimensions and threshold will adjust according to the scale of the parent.

Default Value: true

ParabolaPickProperties
Type: object

A set of properties that can be passed to Picks.createPick to create a new Parabola Pick.

Properties

Name Type Attributes Summary
enabled boolean <optional>
If this Pick should start enabled or not. Disabled Picks do not updated their pick results.

Default Value: false

filter number <optional>
The filter for this Pick to use, constructed using filter flags combined using bitwise OR.

Default Value: 0

maxDistance number <optional>
The max distance at which this Pick will intersect. 0.0 = no max. < 0.0 is invalid.

Default Value: 0.0

parentID Uuid The ID of the parent, either an avatar, an entity, or a pick.
parentJointIndex number <optional>
The joint of the parent to parent to, for example, the joints on the model of an avatar. (default = 0, no joint)

Default Value: 0

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>
Only for Joint Parabola Picks. A local joint position offset, in meters. x = upward, y = forward, z = lateral

Default Value: Vec3.ZERO

dirOffset Vec3 <optional>
Only for Joint Parabola Picks. A local joint direction offset. x = upward, y = forward, z = lateral

Default Value: Vec3.UP

position Vec3 <optional>
Only for Static Parabola Picks. The world-space origin of the parabola segment.
direction Vec3 <optional>
Only for Static Parabola Picks. The world-space direction of the parabola segment.

Default Value: -Vec3.FRONT

speed number <optional>
The initial speed of the parabola, i.e. the initial speed of the projectile whose trajectory defines the parabola.

Default Value: 1

accelerationAxis Vec3 <optional>
The acceleration of the parabola, i.e. the acceleration of the projectile whose trajectory defines the parabola, both magnitude and direction.

Default Value: -Vec3.UP

rotateAccelerationWithAvatar boolean <optional>
Whether or not the acceleration axis should rotate with the avatar's local Y axis.

Default Value: true

rotateAccelerationWithParent boolean <optional>
Whether or not the acceleration axis should rotate with the parent's local Y axis, if available.

Default Value: false

scaleWithParent boolean <optional>
If true, the velocity and acceleration of the Pick will scale linearly with the parent, if available. scaleWithAvatar is an alias but is deprecated.

Default Value: true

RayPickProperties
Type: object

A set of properties that can be passed to Picks.createPick to create a new Ray Pick.

Properties

Name Type Attributes Summary
enabled boolean <optional>
If this Pick should start enabled or not. Disabled Picks do not updated their pick results.

Default Value: false

filter number <optional>
The filter for this Pick to use, constructed using filter flags combined using bitwise OR.

Default Value: 0

maxDistance number <optional>
The max distance at which this Pick will intersect. 0.0 = no max. < 0.0 is invalid.

Default Value: 0.0

parentID Uuid The ID of the parent, either an avatar, an entity, or a pick.
parentJointIndex number <optional>
The joint of the parent to parent to, for example, the joints on the model of an avatar. (default = 0, no joint)

Default Value: 0

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>
Only for Joint Ray Picks. A local joint position offset, in meters. x = upward, y = forward, z = lateral

Default Value: Vec3.ZERO

dirOffset Vec3 <optional>
Only for Joint Ray Picks. A local joint direction offset. x = upward, y = forward, z = lateral

Default Value: Vec3.UP

position Vec3 <optional>
Only for Static Ray Picks. The world-space origin of the ray.
direction Vec3 <optional>
Only for Static Ray Picks. The world-space direction of the ray.

Default Value: -Vec3.UP

StylusPickProperties
Type: object

A set of properties that can be passed to Picks.createPick to create a new Stylus Pick.

Properties

Name Type Attributes Summary
hand number <optional>
An integer. 0 == left, 1 == right. Invalid otherwise.

Default Value: -1

enabled boolean <optional>
If this Pick should start enabled or not. Disabled Picks do not updated their pick results.

Default Value: false

filter number <optional>
The filter for this Pick to use, constructed using filter flags combined using bitwise OR.

Default Value: 0

maxDistance number <optional>
The max distance at which this Pick will intersect. 0.0 = no max. < 0.0 is invalid.

Default Value: 0.0

Method Details

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

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. Picks created with this method always intersect at least visible and collidable things

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
(static) disablePick( uid )

Disables a Pick.

Parameters

Name Type Description
uid number The ID of the Pick, as returned by Picks.createPick.
(static) enablePick( uid )

Enables a Pick.

Parameters

Name Type Description
uid number The ID of the Pick, as returned by Picks.createPick.
(static) getPrevPickResult( uid ) → {RayPickResult|StylusPickResult|ParabolaPickResult|CollisionPickResult}
Returns: The most recent intersection result. This will be different for different PickTypes.

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.
(static) INTERSECTED_AVATAR( ) → {number}
Returns: number

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

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

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

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

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

(static) isLeftHand( uid ) → {boolean}
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.

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.
(static) isMouse( uid ) → {boolean}
Returns: True if the Pick is a Mouse Ray or Parabola Pick, false otherwise.

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.
(static) isRightHand( uid ) → {boolean}
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.

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.
(static) PICK_ALL_INTERSECTIONS( ) → {number}
Returns: number

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

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

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

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

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

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

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

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

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

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

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

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

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

(static) removePick( uid )

Removes a Pick.

Parameters

Name Type Description
uid number The ID of the Pick, as returned by Picks.createPick.
(static) setIgnoreItems( uid, ignoreItems )

Sets a list of Entity 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.
(static) setIncludeItems( uid, includeItems )

Sets a list of Entity 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.
(static) 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