Pointers

Available in: Interface Scripts Client Entity Scripts

The Pointers API lets you create and manage objects for repeatedly calculating intersections in different ways, as well as the visual representation of those objects. Pointers can also be configured to automatically generate PointerEvents on Entities and Overlays.
Methods

Type Definitions

Methods

createPointer(type, properties) → {number}
Adds a new Pointer 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 Pointer, a Mouse Ray Pointer, or a Joint Ray Pointer.
Parameters:
Name Type Description
type PickType A PickType that specifies the method of picking to use
properties Pointers.LaserPointerProperties | Pointers.StylusPointerProperties | Pointers.ParabolaPointerProperties A PointerProperties object, containing all the properties for initializing this Pointer and the Picks.PickProperties for the Pick that this Pointer will use to do its picking.
Returns:
The ID of the created Pointer. Used for managing the Pointer. 0 if invalid.
Type: number
Example

Create a left hand Ray Pointer that triggers events on left controller trigger click and changes color when it's intersecting something.

var end = {
  type: "sphere",
  dimensions: {x:0.5, y:0.5, z:0.5},
  solid: true,
  color: {red:0, green:255, blue:0},
  ignoreRayIntersection: true
};
var end2 = {
  type: "sphere",
  dimensions: {x:0.5, y:0.5, z:0.5},
  solid: true,
  color: {red:255, green:0, blue:0},
  ignoreRayIntersection: true
};

var renderStates = [ {name: "test", end: end} ];
var defaultRenderStates = [ {name: "test", distance: 10.0, end: end2} ];
var pointer = Pointers.createPointer(PickType.Ray, {
  joint: "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND",
  filter: Picks.PICK_OVERLAYS | Picks.PICK_ENTITIES | Picks.PICK_INCLUDE_NONCOLLIDABLE,
  renderStates: renderStates,
  defaultRenderStates: defaultRenderStates,
  distanceScaleEnd: true,
  triggers: [ {action: Controller.Standard.LTClick, button: "Focus"}, {action: Controller.Standard.LTClick, button: "Primary"} ],
  hover: true,
  enabled: true
});
Pointers.setRenderState(pointer, "test");
disablePointer(uid)
Disables a Pointer.
Parameters:
Name Type Description
uid number The ID of the Pointer, as returned by Pointers.createPointer.
editRenderState(uid, renderState, properties)
Edit some visual aspect of a Pointer. Currently only supported for Ray Pointers.
Parameters:
Name Type Description
uid number The ID of the Pointer, as returned by Pointers.createPointer.
renderState string The name of the render state you want to edit.
properties Pointers.RayPointerRenderState The new properties for renderStates item.
enablePointer(uid)
Enables a Pointer.
Parameters:
Name Type Description
uid number The ID of the Pointer, as returned by Pointers.createPointer.
getPointerProperties(uid) → {Pointers.LaserPointerProperties|Pointers.StylusPointerProperties|Pointers.ParabolaPointerProperties}
Returns information about an existing Pointer
Parameters:
Name Type Description
uid number The ID of the Pointer, as returned by Pointers.createPointer.
Returns:
The information about the Pointer. Currently only includes renderStates and defaultRenderStates with associated overlay IDs.
Type: Pointers.LaserPointerProperties | Pointers.StylusPointerProperties | Pointers.ParabolaPointerProperties
getPrevPickResult(uid) → {RayPickResult|StylusPickResult}
Get the most recent pick result from this Pointer. This will be updated as long as the Pointer is enabled, regardless of the render state.
Parameters:
Name Type Description
uid number The ID of the Pointer, as returned by Pointers.createPointer.
Returns:
The most recent intersection result. This will be slightly different for different PickTypes.
Type: RayPickResult | StylusPickResult
isLeftHand(uid) → {boolean}
Check if a Pointer is associated with the left hand.
Parameters:
Name Type Description
uid number The ID of the Pointer, as returned by Pointers.createPointer.
Returns:
True if the Pointer is a Joint Ray Pointer with joint == "_CONTROLLER_LEFTHAND" or "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", or a Stylus Pointer with hand == 0
Type: boolean
isMouse(uid) → {boolean}
Check if a Pointer is associated with the system mouse.
Parameters:
Name Type Description
uid number The ID of the Pointer, as returned by Pointers.createPointer.
Returns:
True if the Pointer is a Mouse Ray Pointer, false otherwise.
Type: boolean
isRightHand(uid) → {boolean}
Check if a Pointer is associated with the right hand.
Parameters:
Name Type Description
uid number The ID of the Pointer, as returned by Pointers.createPointer.
Returns:
True if the Pointer is a Joint Ray Pointer with joint == "_CONTROLLER_RIGHTHAND" or "_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND", or a Stylus Pointer with hand == 1
Type: boolean
removePointer(uid)
Removes a Pointer.
Parameters:
Name Type Description
uid number The ID of the Pointer, as returned by Pointers.createPointer.
setIgnoreItems(uid, ignoreItems)
Sets a list of Entity IDs, Overlay IDs, and/or Avatar IDs to ignore during intersection. Not used by Stylus Pointers.
Parameters:
Name Type Description
uid number The ID of the Pointer, as returned by Pointers.createPointer.
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 Pointers only intersect with objects in their include list.
Parameters:
Name Type Description
uid number The ID of the Pointer, as returned by Pointers.createPointer.
includeItems Array.<Uuid> A list of IDs to include.
setLength(uid, length)
Sets the length of this Pointer. No effect on Stylus Pointers.
Parameters:
Name Type Description
uid number The ID of the Pointer, as returned by Pointers.createPointer.
length number The desired length of the Pointer.
setLockEndUUID(uid, objectID, isOverlay, offsetMatopt)
Lock a Pointer onto a specific object (overlay, entity, or avatar). Optionally, provide an offset in object-space, otherwise the Pointer will lock on to the center of the object. Not used by Stylus Pointers.
Parameters:
Name Type Attributes Description
uid number The ID of the Pointer, as returned by Pointers.createPointer.
objectID Uuid The ID of the object to which to lock on.
isOverlay boolean False for entities or avatars, true for overlays
offsetMat Mat4 <optional>
The offset matrix to use if you do not want to lock on to the center of the object.
setPrecisionPicking(uid, precisionPicking)
Sets whether or not to use precision picking.
Parameters:
Name Type Description
uid number The ID of the Pointer, as returned by Pointers.createPointer.
precisionPicking boolean Whether or not to use precision picking
setRenderState(uid, renderState)
Set the render state of a Pointer. For Ray Pointers, this means switching between their Pointers.RayPointerRenderStates, or "" to turn off rendering and hover/trigger events. For Stylus Pointers, there are three built-in options: "events on" (render and send events, the default), "events off" (render but don't send events), and "disabled" (don't render, don't send events).
Parameters:
Name Type Description
uid number The ID of the Pointer, as returned by Pointers.createPointer.
renderState string The name of the render state to which you want to switch.

Type Definitions

DefaultParabolaPointerRenderState
A set of properties used to define the visual aspect of a Parabola Pointer in the case that the Pointer is not intersecting something. Same as a Pointers.ParabolaPointerRenderState, but with an additional distance field.
Type: object
Properties:
Name Type Description
distance number The distance along the parabola at which to render the end of this Parabola Pointer, if one is defined.
DefaultRayPointerRenderState
A set of properties used to define the visual aspect of a Ray Pointer in the case that the Pointer is not intersecting something. Same as a Pointers.RayPointerRenderState, but with an additional distance field.
Type: object
Properties:
Name Type Description
distance number The distance at which to render the end of this Ray Pointer, if one is defined.
LaserPointerProperties
A set of properties that can be passed to Pointers.createPointer to create a new Pointer. Contains the relevant Picks.PickProperties to define the underlying Pick.
Type: object
Properties:
Name Type Attributes Default Description
faceAvatar boolean <optional>
false If true, the end of the Pointer will always rotate to face the avatar.
centerEndY boolean <optional>
true If false, the end of the Pointer will be moved up by half of its height.
lockEnd boolean <optional>
false If true, the end of the Pointer will lock on to the center of the object at which the pointer is pointing.
distanceScaleEnd boolean <optional>
false If true, the dimensions of the end of the Pointer will scale linearly with distance.
scaleWithParent boolean <optional>
false If true, the width of the Pointer's path will scale linearly with the pick parent's scale. scaleWithAvatar is an alias but is deprecated.
followNormal boolean <optional>
false If true, the end of the Pointer will rotate to follow the normal of the intersected surface.
followNormalStrength number <optional>
0.0 The strength of the interpolation between the real normal and the visual normal if followNormal is true. 0-1. If 0 or 1, the normal will follow exactly.
enabled boolean <optional>
false
renderStates Array.<Pointers.RayPointerRenderState> | Object.<string, Pointers.RayPointerRenderState> <optional>
A collection of different visual states to switch between. When using Pointers.createPointer, a list of RayPointerRenderStates. When returned from Pointers.getPointerProperties, a map between render state names and RayPointRenderStates.
defaultRenderStates Array.<Pointers.DefaultRayPointerRenderState> | Object.<string, Pointers.DefaultRayPointerRenderState> <optional>
A collection of different visual states to use if there is no intersection. When using Pointers.createPointer, a list of DefaultRayPointerRenderStates. When returned from Pointers.getPointerProperties, a map between render state names and DefaultRayPointRenderStates.
hover boolean <optional>
false If this Pointer should generate hover events.
triggers Array.<Pointers.Trigger> <optional>
A list of different triggers mechanisms that control this Pointer's click event generation.
ParabolaPointerProperties
A set of properties that can be passed to Pointers.createPointer to create a new Pointer. Contains the relevant Picks.PickProperties to define the underlying Pick.
Type: object
Properties:
Name Type Attributes Default Description
faceAvatar boolean <optional>
false If true, the end of the Pointer will always rotate to face the avatar.
centerEndY boolean <optional>
true If false, the end of the Pointer will be moved up by half of its height.
lockEnd boolean <optional>
false If true, the end of the Pointer will lock on to the center of the object at which the pointer is pointing.
distanceScaleEnd boolean <optional>
false If true, the dimensions of the end of the Pointer will scale linearly with distance.
scaleWithParent boolean <optional>
true If true, the width of the Pointer's path will scale linearly with the pick parent's scale. scaleWithAvatar is an alias but is deprecated.
followNormal boolean <optional>
false If true, the end of the Pointer will rotate to follow the normal of the intersected surface.
followNormalStrength number <optional>
0.0 The strength of the interpolation between the real normal and the visual normal if followNormal is true. 0-1. If 0 or 1, the normal will follow exactly.
enabled boolean <optional>
false
renderStates Array.<Pointers.ParabolaPointerRenderState> | Object.<string, Pointers.ParabolaPointerRenderState> <optional>
A collection of different visual states to switch between. When using Pointers.createPointer, a list of ParabolaPointerRenderStates. When returned from Pointers.getPointerProperties, a map between render state names and ParabolaPointerRenderStates.
defaultRenderStates Array.<Pointers.DefaultParabolaPointerRenderState> | Object.<string, Pointers.DefaultParabolaPointerRenderState> <optional>
A collection of different visual states to use if there is no intersection. When using Pointers.createPointer, a list of DefaultParabolaPointerRenderStates. When returned from Pointers.getPointerProperties, a map between render state names and DefaultParabolaPointerRenderStates.
hover boolean <optional>
false If this Pointer should generate hover events.
triggers Array.<Pointers.Trigger> <optional>
A list of different triggers mechanisms that control this Pointer's click event generation.
ParabolaPointerRenderState
A set of properties used to define the visual aspect of a Parabola Pointer in the case that the Pointer is intersecting something.
Type: object
Properties:
Name Type Attributes Description
name string When using Pointers.createPointer, the name of this render state, used by Pointers.setRenderState and Pointers.editRenderState
start Overlays.OverlayProperties | QUuid <optional>
When using Pointers.createPointer, an optionally defined overlay to represent the beginning of the Parabola Pointer, using the properties you would normally pass to Overlays.addOverlay, plus the type (as a type field). When returned from Pointers.getPointerProperties, the ID of the created overlay if it exists, or a null ID otherwise.
path Pointers.ParabolaProperties <optional>
When using Pointers.createPointer, the optionally defined rendering properties of the parabolic path defined by the Parabola Pointer. Not defined in Pointers.getPointerProperties.
end Overlays.OverlayProperties | QUuid <optional>
When using Pointers.createPointer, an optionally defined overlay to represent the end of the Parabola Pointer, using the properties you would normally pass to Overlays.addOverlay, plus the type (as a type field). When returned from Pointers.getPointerProperties, the ID of the created overlay if it exists, or a null ID otherwise.
ParabolaProperties
The rendering properties of the parabolic path
Type: object
Properties:
Name Type Default Description
color Color 255,255,255 The color of the parabola.
alpha number 1.0 The alpha of the parabola.
width number 0.01 The width of the parabola, in meters.
isVisibleInSecondaryCamera boolean false The width of the parabola, in meters.
drawInFront boolean false If true, the parabola is rendered in front of other items in the scene.
RayPointerRenderState
A set of properties which define the visual aspect of a Ray Pointer in the case that the Pointer is intersecting something.
Type: object
Properties:
Name Type Attributes Description
name string When using Pointers.createPointer, the name of this render state, used by Pointers.setRenderState and Pointers.editRenderState
start Overlays.OverlayProperties | QUuid <optional>
When using Pointers.createPointer, an optionally defined overlay to represent the beginning of the Ray Pointer, using the properties you would normally pass to Overlays.addOverlay, plus the type (as a type field). When returned from Pointers.getPointerProperties, the ID of the created overlay if it exists, or a null ID otherwise.
path Overlays.OverlayProperties | QUuid <optional>
When using Pointers.createPointer, an optionally defined overlay to represent the path of the Ray Pointer, using the properties you would normally pass to Overlays.addOverlay, plus the type (as a type field), which must be "line3d". When returned from Pointers.getPointerProperties, the ID of the created overlay if it exists, or a null ID otherwise.
end Overlays.OverlayProperties | QUuid <optional>
When using Pointers.createPointer, an optionally defined overlay to represent the end of the Ray Pointer, using the properties you would normally pass to Overlays.addOverlay, plus the type (as a type field). When returned from Pointers.getPointerProperties, the ID of the created overlay if it exists, or a null ID otherwise.
StylusPointerProperties
A set of properties that can be passed to Pointers.createPointer to create a new Pointer. Contains the relevant Picks.PickProperties to define the underlying Pick.
Type: object
Properties:
Name Type Attributes Default Description
hover boolean <optional>
false If this pointer should generate hover events.
enabled boolean <optional>
false
Trigger
A trigger mechanism for Ray and Parabola Pointers.
Type: object
Properties:
Name Type Description
action Controller.Standard | Controller.Actions | function This can be a built-in Controller action, like Controller.Standard.LTClick, or a function that evaluates to >= 1.0 when you want to trigger button.
button string Which button to trigger. "Primary", "Secondary", "Tertiary", and "Focus" are currently supported. Only "Primary" will trigger clicks on web surfaces. If "Focus" is triggered, it will try to set the entity or overlay focus to the object at which the Pointer is aimed. Buttons besides the first three will still trigger events, but event.button will be "None".