Pointers

• Methods • Type Definitions • Method Details •

Description

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

The Pointers API lets you create, manage, and visually represent objects for repeatedly calculating intersections with avatars, entities, and overlays. Pointers can also be configured to generate events on entities and overlays intersected.

Methods

Name Return Value Summary
createPointer number

Creates a new ray, parabola, or stylus pointer. The pointer can have a wide range of behaviors depending on the properties specified. For example, a ray pointer may be a static ray pointer, a mouse ray pointer, or joint ray pointer.

Warning: Pointers created using this method currently always intersect at least visible and collidable things but this may not always be the case.
disablePointer None

Disables and hides a pointer. Disabled pointers do not update their pick results or generate events.
editRenderState None

Edits a render state of a ray or parabola pointer, to change its visual appearance for the state when the pointer is intersecting something.

Note: You can only edit the properties of the existing parts of the pointer; you cannot change the type of any part.

Note: You cannot use this method to change the appearance of a default render state.

Note: Not able to be used with stylus pointers.
enablePointer None

Enables and shows a pointer. Enabled pointers update their pick results and generate events.
getPointerProperties Pointers.RayPointerProperties | Pointers.ParabolaPointerProperties | object

Gets information about a pointer.
getPointers Array.<number>

Gets all pointers which currently exist, including disabled pointers.
getPointerScriptParameters Pointers.RayPointerProperties | Pointers.ParabolaPointerProperties | Pointers.StylusPointerProperties

Gets the parameters that were passed in to Pointers.createPointer to create the pointer when the pointer was created through a script.

Note: These properties do not reflect the current state of the pointer. To get the current state of the pointer, see Pointers.getPointerProperties.

getPrevPickResult RayPickResult | ParabolaPickResult | StylusPickResult

Gets the most recent intersection of a pointer. A pointer continues to be updated ready to return a result, as long as it is enabled, regardless of the render state.
isLeftHand boolean

Checks if a pointer is associated with the left hand: a ray or parabola pointer with joint property set to "_CONTROLLER_LEFTHAND" or "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", or a stylus pointer with hand property set to 0.
isMouse boolean

Checks if a pointer is associated with the system mouse: a ray or parabola pointer with joint property set to "Mouse".
isPointerEnabled boolean

Gets the enabled status of a pointer. Enabled pointers update their pick results and generate events.
isRightHand boolean

Checks if a pointer is associated with the right hand: a ray or parabola pointer with joint property set to "_CONTROLLER_RIGHTHAND" or "_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND", or a stylus pointer with hand property set to 1.
removePointer None

Removes (deletes) a pointer.
setIgnoreItems None

Sets a list of entity and avatar IDs that a pointer should ignore during intersection.

Note: Not used by stylus pointers.
setIncludeItems None

Sets a list of entity and avatar IDs that a pointer should include during intersection, instead of intersecting with everything.

Note: Stylus pointers only intersect with items in their include list.
setLength None

Sets the length of a pointer.

Note: Not used by stylus pointers.
setLockEndUUID None

Locks a pointer onto a specific entity or avatar.

Note: Not used by stylus pointers.
setPrecisionPicking None

Sets whether or not a pointer should use precision picking, i.e., whether it should pick against precise meshes or coarse meshes. This has the same effect as using the PICK_PRECISE or PICK_COARSE filter flags.
setRenderState None

Sets the render state of a pointer, to change its visual appearance and possibly disable or enable it.

Type Definitions

DefaultParabolaPointerRenderState
Type: object

Properties that define the visual appearance of a parabola pointer when the pointer is not intersecting something. These are properties of Pointers.ParabolaPointerRenderState but with an additional property.

Properties

Name Type Summary
distance number

The distance along the parabola at which to render the end of the parabola pointer.

See:
DefaultRayPointerRenderState
Type: object

Properties that define the visual appearance of a ray pointer when the pointer is not intersecting something. These are the properties of Pointers.RayPointerRenderState but with an additional property.

Properties

Name Type Summary
distance number

The distance at which to render the end of the ray pointer.

See:
ParabolaPointerPath
Type: object

The visual appearance of the parabolic path.

Properties

Name Type Attributes Summary
color Color <optional>

The color of the parabola.

Default Value: 255,255,255

alpha number <optional>

The opacity of the parabola, range 0.0 – 1.0.

Default Value: 1.0

width number <optional>

The width of the parabola, in meters.

Default Value: 0.01

isVisibleInSecondaryCamera boolean <optional>

true if the parabola is rendered in the secondary camera, false if it isn't.

Default Value: false

drawInFront boolean <optional>

true if the parabola is rendered in front of objects in the world, but behind the HUD, false if it is occluded by objects in front of it.

Default Value: false

ParabolaPointerProperties
Type: object

The properties of a parabola pointer. These include the properties from the underlying parabola pick that the pointer uses.

Properties

Name Type Attributes Summary
faceAvatar boolean <optional>

true if the overlay rendered at the end of the ray rotates about the world y-axis to always face the avatar; false if it maintains its world orientation.

Default Value: false

centerEndY boolean <optional>

true if the overlay rendered at the end of the ray is centered on the ray end; false if the overlay is positioned against the surface if followNormal is true, or above the ray end if followNormal is false.

Default Value: true

lockEnd boolean <optional>

true if the end of the ray is locked to the center of the object at which the ray is pointing; false if the end of the ray is at the intersected surface.

Default Value: false

distanceScaleEnd boolean <optional>

true if the dimensions of the overlay at the end of the ray scale linearly with distance; false if they aren't.

Default Value: false

scaleWithParent boolean <optional>

true if the width of the ray's path and the size of the start and end overlays scale linearly with the pointer parent's scale; false if they don't scale.

Default Value: false

scaleWithAvatar boolean <optional>

A synonym for scalewithParent.

Deprecated: This property is deprecated and will be removed.

Default Value: false

followNormal boolean <optional>

true if the overlay rendered at the end of the ray rotates to follow the normal of the surface if one is intersected; false if it doesn't.

Default Value: false

followNormalStrength number <optional>

How quickly the overlay rendered at the end of the ray rotates to follow the normal of an intersected surface. If 0 or 1, the overlay rotation follows instantaneously; for other values, the larger the value the more quickly the rotation follows.

Default Value: 0.0

renderStates Array.<Pointers.ParabolaPointerRenderState> | Object.<string, Pointers.ParabolaPointerRenderState> <optional>

A set of visual states that can be switched among using Pointers.setRenderState. These define the visual appearance of the pointer when it is intersecting something.

When setting using Pointers.createPointer, an array of ParabolaPointerRenderState values.

When getting using Pointers.getPointerProperties, an object mapping render state names to ParabolaPointerRenderState values.
defaultRenderStates Array.<Pointers.DefaultParabolaPointerRenderState> | Object.<string, Pointers.DefaultParabolaPointerRenderState> <optional>

A set of visual states that can be switched among using Pointers.setRenderState. These define the visual appearance of the pointer when it is not intersecting something.

When setting using Pointers.createPointer, an array of DefaultParabolaPointerRenderState values.

When getting using Pointers.getPointerProperties, an object mapping render state names to DefaultParabolaPointerRenderState values.
hover boolean <optional>

true if the pointer generates Entities hover events, false if it doesn't.

Default Value: false

triggers Array.<Pointers.Trigger> <optional>

A list of ways that a Controller action or function should trigger events on the entity or overlay currently intersected.

Default Value: []

pointerType PickType

The type of pointer returned from Pointers.getPointerProperties or Pointers.getPointerScriptParameters. A parabola pointer's type is PickType.Parabola.
pickID number <optional>

The ID of the pick created alongside this pointer, returned from Pointers.getPointerProperties.

See:
ParabolaPointerRenderState
Type: object

Properties that define the visual appearance of a parabola pointer when the pointer is intersecting something.

Properties

Name Type Attributes Summary
name string

When creating using Pointers.createPointer, the name of the render state.
start Overlays.OverlayProperties | Uuid <optional>

When creating or editing using Pointers.createPointer or Pointers.editRenderState, the properties of an overlay to render at the start of the parabola pointer. The type property must be specified.

When getting using Pointers.getPointerProperties, the ID of the overlay rendered at the start of the parabola; null if there is no overlay.

path Pointers.ParabolaPointerPath | Uuid <optional>

When creating or editing using Pointers.createPointer or Pointers.editRenderState, the properties of the rendered path of the parabola pointer.

This property is not provided when getting using Pointers.getPointerProperties.

end Overlays.OverlayProperties | Uuid <optional>

When creating or editing using Pointers.createPointer or Pointers.editRenderState, the properties of an overlay to render at the end of the ray pointer. The type property must be specified.

When getting using Pointers.getPointerProperties, the ID of the overlay rendered at the end of the parabola; null if there is no overlay.

RayPointerProperties
Type: object

The properties of a ray pointer. These include the properties from the underlying ray pick that the pointer uses.

Properties

Name Type Attributes Summary
faceAvatar boolean <optional>

true if the overlay rendered at the end of the ray rotates about the world y-axis to always face the avatar; false if it maintains its world orientation.

Default Value: false

centerEndY boolean <optional>

true if the overlay rendered at the end of the ray is centered on the ray end; false if the overlay is positioned against the surface if followNormal is true, or above the ray end if followNormal is false.

Default Value: true

lockEnd boolean <optional>

true if the end of the ray is locked to the center of the object at which the ray is pointing; false if the end of the ray is at the intersected surface.

Default Value: false

distanceScaleEnd boolean <optional>

true if the dimensions of the overlay at the end of the ray scale linearly with distance; false if they aren't.

Default Value: false

scaleWithParent boolean <optional>

true if the width of the ray's path and the size of the start and end overlays scale linearly with the pointer parent's scale; false if they don't scale.

Default Value: false

scaleWithAvatar boolean <optional>

A synonym for scalewithParent.

Deprecated: This property is deprecated and will be removed.

Default Value: false

followNormal boolean <optional>

true if the overlay rendered at the end of the ray rotates to follow the normal of the surface if one is intersected; false if it doesn't.

Default Value: false

followNormalStrength number <optional>

How quickly the overlay rendered at the end of the ray rotates to follow the normal of an intersected surface. If 0 or 1, the overlay rotation follows instantaneously; for other values, the larger the value the more quickly the rotation follows.

Default Value: 0.0

renderStates Array.<Pointers.RayPointerRenderState> | Object.<string, Pointers.RayPointerRenderState> <optional>

A set of visual states that can be switched among using Pointers.setRenderState. These define the visual appearance of the pointer when it is intersecting something.

When setting using Pointers.createPointer, an array of RayPointerRenderState values.

When getting using Pointers.getPointerProperties, an object mapping render state names to RayPointerRenderState values.
defaultRenderStates Array.<Pointers.DefaultRayPointerRenderState> | Object.<string, Pointers.DefaultRayPointerRenderState> <optional>

A set of visual states that can be switched among using Pointers.setRenderState. These define the visual appearance of the pointer when it is not intersecting something.

When setting using Pointers.createPointer, an array of DefaultRayPointerRenderState values.

When getting using Pointers.getPointerProperties, an object mapping render state names to DefaultRayPointerRenderState values.
hover boolean <optional>

true if the pointer generates Entities hover events, false if it doesn't.

Default Value: false

triggers Array.<Pointers.Trigger> <optional>

A list of ways that a Controller action or function should trigger events on the entity or overlay currently intersected.

Default Value: []

pointerType PickType

The type of pointer returned from Pointers.getPointerProperties or Pointers.getPointerScriptParameters. A laser pointer's type is PickType.Ray.
pickID number <optional>

The ID of the pick created alongside this pointer, returned from Pointers.getPointerProperties.

See:
RayPointerRenderState
Type: object

Properties that define the visual appearance of a ray pointer when the pointer is intersecting something.

Properties

Name Type Attributes Summary
name string

When creating using Pointers.createPointer, the name of the render state.
start Overlays.OverlayProperties | Uuid <optional>

When creating or editing using Pointers.createPointer or Pointers.editRenderState, the properties of an overlay to render at the start of the ray pointer. The type property must be specified.

When getting using Pointers.getPointerProperties, the ID of the overlay rendered at the start of the ray; null if there is no overlay.

path Overlays.OverlayProperties | Uuid <optional>

When creating or editing using Pointers.createPointer or Pointers.editRenderState, the properties of the overlay rendered for the path of the ray pointer. The type property must be specified and be "line3d".

When getting using Pointers.getPointerProperties, the ID of the overlay rendered for the path of the ray; null if there is no overlay.

end Overlays.OverlayProperties | Uuid <optional>

When creating or editing using Pointers.createPointer or Pointers.editRenderState, the properties of an overlay to render at the end of the ray pointer. The type property must be specified.

When getting using Pointers.getPointerProperties, the ID of the overlay rendered at the end of the ray; null if there is no overlay.

StylusPointerModel
Type: object

The properties of a stylus pointer model.

Properties

Name Type Attributes Summary
url string <optional>

The url of a model to use for the stylus, to override the default stylus mode.
dimensions Vec3 <optional>

The dimensions of the stylus, to override the default stylus dimensions.
positionOffset Vec3 <optional>

The position offset of the model from the stylus tip, to override the default position offset.
rotationOffset Quat <optional>

The rotation offset of the model from the hand, to override the default rotation offset.
StylusPointerProperties
Type: object

The properties of a stylus pointer. These include the properties from the underlying stylus pick that the pointer uses.

Properties

Name Type Attributes Summary
model Pointers.StylusPointerModel <optional>

Override some or all of the default stylus model properties.
hover boolean <optional>

true if the pointer generates Entities hover events, false if it doesn't.

Default Value: false

pointerType PickType

The type of the stylus pointer returned from Pointers.getPointerProperties or Pointers.getPointerScriptParameters. A stylus pointer's type is PickType.Stylus.
pickID number <optional>

The ID of the pick created alongside this pointer, returned from Pointers.getPointerProperties.

See:
Trigger
Type: object

Specifies that a Controller action or function should trigger events on the entity or overlay currently intersected by a Ray or Parabola pointer.

Properties

Name Type Summary
action Controller.Standard | Controller.Actions | function

The controller output or function that triggers the events on the entity or overlay. If a function, it must return a number >= 1.0 to start the action and < 1.0 to terminate the action.
button string

Which button to trigger:

  • "Primary", "Secondary", and "Tertiary" cause Entities and Overlays mouse pointer events. Other button names also cause mouse events but the button property in the event will be "None".
  • "Focus" will try to give focus to the entity or overlay which the pointer is intersecting.

Method Details

(static) createPointer( type, properties ) → {number}
Returns: The ID of the pointer if successfully created, otherwise 0.

Creates a new ray, parabola, or stylus pointer. The pointer can have a wide range of behaviors depending on the properties specified. For example, a ray pointer may be a static ray pointer, a mouse ray pointer, or joint ray pointer.

Warning: Pointers created using this method currently always intersect at least visible and collidable things but this may not always be the case.

Parameters

Name Type Description
type PickType

The type of pointer to create. Cannot be PickType.Collision.
properties Pointers.RayPointerProperties | Pointers.ParabolaPointerProperties | Pointers.StylusPointerProperties

The properties of the pointer, per the pointer type, including the properties of the underlying pick that the pointer uses to do its picking.
Example

Create a ray pointer on the left hand that changes color when it's intersecting and that triggers events.
Note: Stop controllerScripts.js from running to disable similar behavior from it.

var intersectEnd = {
    type: "sphere",
    dimensions: { x: 0.2, y: 0.2, z: 0.2 },
    solid: true,
    color: { red: 0, green: 255, blue: 0 },
    ignorePickIntersection: true
};
var intersectedPath = {
    type: "line3d",
    color: { red: 0, green: 255, blue: 0 },
};
var searchEnd = {
    type: "sphere",
    dimensions: { x: 0.2, y: 0.2, z: 0.2 },
    solid: true,
    color: { red: 255, green: 0, blue: 0 },
    ignorePickIntersection: true
};
var searchPath = {
    type: "line3d",
    color: { red: 255, green: 0, blue: 0 },
};

var renderStates = [{ name: "example", path: intersectedPath, end: intersectEnd }];
var defaultRenderStates = [{ name: "example", distance: 20.0, path: searchPath, end: searchEnd }];

// Create the pointer.
var rayPointer = Pointers.createPointer(PickType.Ray, {
    joint: "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND",
    filter: Picks.PICK_LOCAL_ENTITIES | Picks.PICK_DOMAIN_ENTITIES | Picks.PICK_INCLUDE_NONCOLLIDABLE,
    renderStates: renderStates,
    defaultRenderStates: defaultRenderStates,
    hover: true,  // Generate hover events.
    triggers: [
        { action: Controller.Standard.LTClick, button: "Primary" },  // Generate mouse events.
        { action: Controller.Standard.LTClick, button: "Focus" }  // Focus on web entities.
    ],
    enabled: true
});
Pointers.setRenderState(rayPointer, "example");

// Hover events.
Entities.hoverEnterEntity.connect(function (entityID, event) {
    print("hoverEnterEntity() : " + entityID);
});
Entities.hoverLeaveEntity.connect(function (entityID, event) {
    print("hoverLeaveEntity() : " + entityID);
});

// Mouse events.
Entities.mousePressOnEntity.connect(function (entityID, event) {
    print("mousePressOnEntity() : " + entityID + " , " + event.button);
});
Entities.mouseReleaseOnEntity.connect(function (entityID, event) {
    print("mouseReleaseOnEntity() : " + entityID + " , " + event.button);
});

// Tidy up.
Script.scriptEnding.connect(function () {
    Pointers.removePointer(rayPointer);
});
(static) disablePointer( id )

Disables and hides a pointer. Disabled pointers do not update their pick results or generate events.

Parameters

Name Type Description
id number

The ID of the pointer.
(static) editRenderState( id, renderState, properties )

Edits a render state of a ray or parabola pointer, to change its visual appearance for the state when the pointer is intersecting something.

Note: You can only edit the properties of the existing parts of the pointer; you cannot change the type of any part.

Note: You cannot use this method to change the appearance of a default render state.

Note: Not able to be used with stylus pointers.

Parameters

Name Type Description
id number

The ID of the pointer.
renderState string

The name of the render state to edit.
properties Pointers.RayPointerRenderState | Pointers.ParabolaPointerRenderState

The new properties for the render state. Only the overlay properties to change need be specified.
Example

Change the dimensions of a ray pointer's intersecting end overlay.

var intersectEnd = {
    type: "sphere",
    dimensions: { x: 0.2, y: 0.2, z: 0.2 },
    solid: true,
    color: { red: 0, green: 255, blue: 0 },
    ignorePickIntersection: true
};
var intersectedPath = {
    type: "line3d",
    color: { red: 0, green: 255, blue: 0 },
};
var searchEnd = {
    type: "sphere",
    dimensions: { x: 0.2, y: 0.2, z: 0.2 },
    solid: true,
    color: { red: 255, green: 0, blue: 0 },
    ignorePickIntersection: true
};
var searchPath = {
    type: "line3d",
    color: { red: 255, green: 0, blue: 0 },
};

var renderStates = [ { name: "example", path: intersectedPath, end: intersectEnd } ];
var defaultRenderStates = [ { name: "example", distance: 20.0, path: searchPath, end: searchEnd } ];

// Create the pointer.
var rayPointer = Pointers.createPointer(PickType.Ray, {
    joint: "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND",
    filter: Picks.PICK_LOCAL_ENTITIES | Picks.PICK_DOMAIN_ENTITIES | Picks.PICK_INCLUDE_NONCOLLIDABLE,
    renderStates: renderStates,
    defaultRenderStates: defaultRenderStates,
    enabled: true
});
Pointers.setRenderState(rayPointer, "example");

// Edit the intersecting render state.
Script.setTimeout(function () {
    print("Edit render state");
    Pointers.editRenderState(rayPointer, "example", {
        end: { dimensions: { x: 0.5, y: 0.5, z: 0.5 } }
    });
}, 10000);

Script.setTimeout(function () {
    print("Edit render state");
    Pointers.editRenderState(rayPointer, "example", {
        end: { dimensions: { x: 0.2, y: 0.2, z: 0.2 } }
    });
}, 15000);

// Tidy up.
Script.scriptEnding.connect(function () {
    Pointers.removePointer(rayPointer);
});
(static) enablePointer( id )

Enables and shows a pointer. Enabled pointers update their pick results and generate events.

Parameters

Name Type Description
id number

The ID of the pointer.
(static) getPointerProperties( id ) → {Pointers.RayPointerProperties|Pointers.ParabolaPointerProperties|object}
Returns: The renderStates and defaultRenderStates for ray and parabola pointers, {} for stylus pointers.

Gets information about a pointer.

Parameters

Name Type Description
id number

The ID of the pointer.
Example

Report the properties of a parabola pointer.

var intersectEnd = {
    type: "sphere",
    dimensions: { x: 0.2, y: 0.2, z: 0.2 },
    solid: true,
    color: { red: 0, green: 255, blue: 0 },
    ignorePickIntersection: true
};
var intersectedPath = {
    color: { red: 0, green: 255, blue: 0 },
};
var searchEnd = {
    type: "sphere",
    dimensions: { x: 0.2, y: 0.2, z: 0.2 },
    solid: true,
    color: { red: 255, green: 0, blue: 0 },
    ignorePickIntersection: true
};
var searchPath = {
    color: { red: 255, green: 0, blue: 0 },
};

var renderStates = [{ name: "example", path: intersectedPath, end: intersectEnd }];
var defaultRenderStates = [{ name: "example", distance: 20.0, path: searchPath, end: searchEnd }];

// Create the pointer.
var parabolaPointer = Pointers.createPointer(PickType.Parabola, {
    joint: "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND",
    filter: Picks.PICK_LOCAL_ENTITIES | Picks.PICK_DOMAIN_ENTITIES | Picks.PICK_INCLUDE_NONCOLLIDABLE,
    renderStates: renderStates,
    defaultRenderStates: defaultRenderStates,
    enabled: true
});
Pointers.setRenderState(parabolaPointer, "example");

// Report the pointer properties.
Script.setTimeout(function () {
    var properties = Pointers.getPointerProperties(parabolaPointer);
    print("Pointer properties:" + JSON.stringify(properties));
}, 500);

// Tidy up.
Script.scriptEnding.connect(function () {
    Pointers.removePointer(parabolaPointer);
});
(static) getPointers( ) → {Array.<number>}
Returns: pointers - The IDs of the pointers.

Gets all pointers which currently exist, including disabled pointers.
(static) getPointerScriptParameters( id ) → {Pointers.RayPointerProperties|Pointers.ParabolaPointerProperties|Pointers.StylusPointerProperties}
Returns: Script-provided properties, per the pointer type.

Gets the parameters that were passed in to Pointers.createPointer to create the pointer when the pointer was created through a script.

Note: These properties do not reflect the current state of the pointer. To get the current state of the pointer, see Pointers.getPointerProperties.

Parameters

Name Type Description
id number

The ID of the pointer.
(static) getPrevPickResult( id ) → {RayPickResult|ParabolaPickResult|StylusPickResult}
Returns: The most recent intersection of the pointer.

Gets the most recent intersection of a pointer. A pointer continues to be updated ready to return a result, as long as it is enabled, regardless of the render state.

Parameters

Name Type Description
id number

The ID of the pointer.
(static) isLeftHand( id ) → {boolean}
Returns: true if the pointer is associated with the left hand, false if it isn't.

Checks if a pointer is associated with the left hand: a ray or parabola pointer with joint property set to "_CONTROLLER_LEFTHAND" or "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", or a stylus pointer with hand property set to 0.

Parameters

Name Type Description
id number

The ID of the pointer.
(static) isMouse( id ) → {boolean}
Returns: true if the pointer is associated with the system mouse, false if it isn't.

Checks if a pointer is associated with the system mouse: a ray or parabola pointer with joint property set to "Mouse".

Parameters

Name Type Description
id number

The ID of the pointer.
(static) isPointerEnabled( id ) → {boolean}
Returns: enabled - Whether or not the pointer is enabled.

Gets the enabled status of a pointer. Enabled pointers update their pick results and generate events.

Parameters

Name Type Description
id number

The ID of the pointer.
(static) isRightHand( id ) → {boolean}
Returns: true if the pointer is associated with the right hand, false if it isn't.

Checks if a pointer is associated with the right hand: a ray or parabola pointer with joint property set to "_CONTROLLER_RIGHTHAND" or "_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND", or a stylus pointer with hand property set to 1.

Parameters

Name Type Description
id number

The ID of the pointer.
(static) removePointer( id )

Removes (deletes) a pointer.

Parameters

Name Type Description
id number

The ID of the pointer.
(static) setIgnoreItems( id, ignoreItems )

Sets a list of entity and avatar IDs that a pointer should ignore during intersection.

Note: Not used by stylus pointers.

Parameters

Name Type Description
id number

The ID of the pointer.
ignoreItems Array.<Uuid>

A list of IDs to ignore.
(static) setIncludeItems( id, includeItems )

Sets a list of entity and avatar IDs that a pointer should include during intersection, instead of intersecting with everything.

Note: Stylus pointers only intersect with items in their include list.

Parameters

Name Type Description
id number

The ID of the pointer.
includeItems Array.<Uuid>

A list of IDs to include.
(static) setLength( id, length )

Sets the length of a pointer.

Note: Not used by stylus pointers.

Parameters

Name Type Description
id number

The ID of the pointer.
length number

The desired length of the pointer.
(static) setLockEndUUID( id, targetID, isAvatar, offsetopt )

Locks a pointer onto a specific entity or avatar.

Note: Not used by stylus pointers.

Parameters

Name Type Attributes Description
id number

The ID of the pointer.
targetID Uuid

The ID of the entity or avatar to lock the pointer on to.
isAvatar boolean

true if the target is an avatar, false if it is an entity.
offset Mat4 <optional>

The offset of the target point from the center of the target item. If not specified, the pointer locks on to the center of the target item.
(static) setPrecisionPicking( id, precisionPicking )

Sets whether or not a pointer should use precision picking, i.e., whether it should pick against precise meshes or coarse meshes. This has the same effect as using the PICK_PRECISE or PICK_COARSE filter flags.

Parameters

Name Type Description
id number

The ID of the pointer.
precisionPicking boolean

true to use precision picking, false to use coarse picking.
(static) setRenderState( id, renderState )

Sets the render state of a pointer, to change its visual appearance and possibly disable or enable it.

Parameters

Name Type Description
id number

The ID of the pointer.
renderState string

The name of the render state to set the pointer to.

For ray and parabola pointers, this may be:

  • The name of one of the render states set in the pointer's properties.
  • "", to hide the pointer and disable emitting of events.

For stylus pointers, the values may be:

  • "events on", to render and emit events (the default).
  • "events off", to render but don't emit events.
  • "disabled", to not render and not emit events.
Example

Switch a ray pointer between having a path and not having a path.

var intersectEnd = {
    type: "sphere",
    dimensions: { x: 0.2, y: 0.2, z: 0.2 },
    solid: true,
    color: { red: 0, green: 255, blue: 0 },
    ignorePickIntersection: true
};
var intersectedPath = {
    type: "line3d",
    color: { red: 0, green: 255, blue: 0 },
};
var searchEnd = {
    type: "sphere",
    dimensions: { x: 0.2, y: 0.2, z: 0.2 },
    solid: true,
    color: { red: 255, green: 0, blue: 0 },
    ignorePickIntersection: true
};
var searchPath = {
    type: "line3d",
    color: { red: 255, green: 0, blue: 0 },
};

var renderStates = [
    { name: "examplePath", path: intersectedPath, end: intersectEnd },
    { name: "exampleNoPath", end: intersectEnd }
];
var defaultRenderStates = [
    { name: "examplePath", distance: 20.0, path: searchPath, end: searchEnd },
    { name: "exampleNoPath", distance: 20.0, end: searchEnd }
];

// Create the pointer.
var rayPointer = Pointers.createPointer(PickType.Ray, {
    joint: "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND",
    filter: Picks.PICK_LOCAL_ENTITIES | Picks.PICK_DOMAIN_ENTITIES | Picks.PICK_INCLUDE_NONCOLLIDABLE,
    renderStates: renderStates,
    defaultRenderStates: defaultRenderStates,
    enabled: true
});
Pointers.setRenderState(rayPointer, "examplePath");

// Change states.
Script.setTimeout(function () {
    print("Without path");
    Pointers.setRenderState(rayPointer, "exampleNoPath");
}, 10000);

Script.setTimeout(function () {
    print("With path");
    Pointers.setRenderState(rayPointer, "examplePath");
}, 15000);

// Tidy up.
Script.scriptEnding.connect(function () {
    Pointers.removePointer(rayPointer);
});