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

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 Ray Pointers only. If true, the end of the Pointer will always rotate to face the avatar.
centerEndY boolean <optional>
true Ray Pointers only. If false, the end of the Pointer will be moved up by half of its height.
lockEnd boolean <optional>
false Ray Pointers only. If true, the end of the Pointer will lock on to the center of the object at which the laser is pointing.
distanceScaleEnd boolean <optional>
false Ray Pointers only. If true, the dimensions of the end of the Pointer will scale linearly with distance.
scaleWithAvatar boolean <optional>
false Ray Pointers only. If true, the width of the Pointer's path will scale linearly with your avatar's scale.
enabled boolean <optional>
false
renderStates Array.<Pointers.RayPointerRenderState> <optional>
Ray Pointers only. A list of different visual states to switch between.
defaultRenderStates Array.<Pointers.DefaultRayPointerRenderState> <optional>
Ray Pointers only. A list of different visual states to use if there is no intersection.
hover boolean <optional>
false If this Pointer should generate hover events.
triggers Array.<Pointers.Trigger> <optional>
Ray Pointers only. A list of different triggers mechanisms that control this Pointer's click event generation.
RayPointerRenderState
A set of properties used to 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 The name of this render state, used by Pointers.setRenderState and Pointers.editRenderState
start Overlays.OverlayProperties <optional>
All of the properties you would normally pass to Overlays.addOverlay, plus the type (as a type field). An overlay to represent the beginning of the Ray Pointer, if desired.
path Overlays.OverlayProperties <optional>
All of the properties you would normally pass to Overlays.addOverlay, plus the type (as a type field), which must be "line3d". An overlay to represent the path of the Ray Pointer, if desired.
end Overlays.OverlayProperties <optional>
All of the properties you would normally pass to Overlays.addOverlay, plus the type (as a type field). An overlay to represent the end of the Ray Pointer, if desired.
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 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".