LaserPointers - Vircadia API Docs

Description

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

The LaserPointers API is a subset of the Pointers API. It lets you create, manage, and visually represent objects for repeatedly calculating ray intersections with avatars, entities, and overlays. Ray pointers can also be configured to generate events on entities and overlays intersected.

Deprecated: This API is deprecated and will be removed. Use Pointers instead.

Methods

Name	Return Value	Summary
`createLaserPointer`	number	Creates a new ray pointer. The pointer can have a wide range of behaviors depending on the properties specified. For example, it 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.
`disableLaserPointer`	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 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.
`enableLaserPointer`	None	Enables and shows a pointer. Enabled pointers update their pick results and generate events.
`getPrevRayPickResult`	RayPickResult	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 pointer with `joint` property set to `"_CONTROLLER_LEFTHAND"` or `"_CAMERA_RELATIVE_CONTROLLER_LEFTHAND"`.
`isMouse`	boolean	Checks if a pointer is associated with the system mouse: a pointer with `joint` property set to `"Mouse"`.
`isRightHand`	boolean	Checks if a pointer is associated with the right hand: a pointer with `joint` property set to `"_CONTROLLER_RIGHTHAND"` or `"_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND"`.
`removeLaserPointer`	None	Removes (deletes) a pointer.
`setIgnoreItems`	None	Sets a list of entity and avatar IDs that a pointer should ignore during intersection.
`setIncludeItems`	None	Sets a list of entity and avatar IDs that a pointer should include during intersection, instead of intersecting with everything.
`setLaserLength`	None	Sets the length of a pointer.
`setLockEndUUID`	None	Locks a pointer onto a specific entity or avatar.
`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.

Method Details

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

Creates a new ray pointer. The pointer can have a wide range of behaviors depending on the properties specified. For example, it 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
`properties`	Pointers.RayPointerProperties	The properties of the pointer, including the properties of the underlying pick that the pointer uses to do its picking.

(static) disableLaserPointer( 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 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.

Parameters

Name	Type	Description
`id`	number	The ID of the pointer.
`renderState`	string	The name of the render state to edit.
`properties`	Pointers.RayPointerRenderState	The new properties for the render state. Only the overlay properties to change need be specified.

(static) enableLaserPointer( 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) getPrevRayPickResult( id ) → {RayPickResult}
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 pointer with joint property set to "_CONTROLLER_LEFTHAND" or "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND".

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 pointer with joint property set to "Mouse".

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 pointer with joint property set to "_CONTROLLER_RIGHTHAND" or "_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND".

Parameters

Name	Type	Description
`id`	number	The ID of the pointer.

(static) removeLaserPointer( 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.

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.

Parameters

Name	Type	Description
`id`	number	The ID of the pointer.
`includeItems`	Array.<Uuid>	A list of IDs to include.

(static) setLaserLength( id, laserLength )

Sets the length of a pointer.

Parameters

Name	Type	Description
`id`	number	The ID of the pointer.
`laserLength`	number	The desired length of the pointer.

(static) setLockEndUUID( id, targetID, isAvatar, offsetopt )

Locks a pointer onto a specific entity or avatar.

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( renderState, id )

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

Parameters

Name Type Description

renderState

string

The name of the render state to set the pointer to. 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.

id

number

The ID of the pointer.