Guides

VRTK_PlayAreaCursor

Overview

Provides a visual representation of the play area boundaries that tracks to the cursor position of a pointer.

Optional Components:

  • VRTK_PointerDirectionIndicator - A Pointer Direction Indicator to set the cursor rotation to.

Script Usage:

  • Place the VRTK_PlayAreaCursor script on the same GameObject as the Pointer Renderer script it is linked to.
  • Link the required Play Area Cursor script to the Playarea Cursor parameter on the required Pointer Renderer script.

Script Dependencies:

  • A Base Pointer Renderer script attached to a valid Pointer script is required so the PlayArea Cursor script can be linked to follow the valid Base Pointer Renderer cursor GameObject.

Inspector Parameters

  • Use Pointer Color: If this is checked then the pointer valid/invalid colours will also be used to change the colour of the play area cursor when colliding/not colliding.
  • Play Area Cursor Dimensions: Determines the size of the play area cursor and collider. If the values are left as zero then the Play Area Cursor will be sized to the calibrated Play Area space.
  • Handle Play Area Cursor Collisions: If this is checked then if the play area cursor is colliding with any other object then the pointer colour will change to the Pointer Miss Color and the DestinationMarkerSet event will not be triggered, which will prevent teleporting into areas where the play area will collide.
  • Headset Out Of Bounds Is Collision: If this is checked then if the user's headset is outside of the play area cursor bounds then it is considered a collision even if the play area isn't colliding with anything.
  • Display On Invalid Location: If this is checked then the play area cursor will be displayed when the location is invalid.
  • Target List Policy: A specified VRTK_PolicyList to use to determine whether the play area cursor collisions will be acted upon.
  • Direction Indicator: A custom Pointer Direction Indicator to use to determine the rotation of the Play Area Cursor.
  • Valid Location Object: A custom GameObject to use for the play area cursor representation for when the location is valid.
  • Invalid Location Object: A custom GameObject to use for the play area cursor representation for when the location is invalid.

Class Events

  • PlayAreaCursorStartCollision - Emitted when the play area collides with another object.
  • PlayAreaCursorEndCollision - Emitted when the play area stops colliding with another object.

Unity Events

Adding the VRTK_PlayAreaCursor_UnityEvents component to VRTK_PlayAreaCursor object allows access to UnityEvents that will react identically to the Class Events.

  • All C# delegate events are mapped to a Unity Event with the On prefix. e.g. MyEvent -> OnMyEvent.

Event Payload

  • collidedWith - The collider that is/was being collided with.

Class Methods

HasCollided/0

public virtual bool HasCollided()

  • Parameters
    • none
  • Returns
    • bool - Returns true if the play area is colliding with a valid object and false if not.

The HasCollided method returns the state of whether the play area cursor has currently collided with another valid object.

SetHeadsetPositionCompensation/1

public virtual void SetHeadsetPositionCompensation(bool state)

  • Parameters
    • bool state - The state of whether to take the position of the headset within the play area into account when setting the destination marker.
  • Returns
    • none

The SetHeadsetPositionCompensation method determines whether the offset position of the headset from the centre of the play area should be taken into consideration when setting the destination marker. If true then it will take the offset position into consideration.

SetPlayAreaCursorCollision/2

public virtual void SetPlayAreaCursorCollision(bool state, Collider collider = null)

  • Parameters
    • bool state - The state of whether to check for play area collisions.
    • Collider collider - The state of whether to check for play area collisions.
  • Returns
    • none

The SetPlayAreaCursorCollision method determines whether play area collisions should be taken into consideration with the play area cursor.

SetMaterialColor/2

public virtual void SetMaterialColor(Color color, bool validity)

  • Parameters
    • Color color - The colour to update the play area cursor material to.
    • bool validity - Determines if the colour being set is based from a valid location or invalid location.
  • Returns
    • none

The SetMaterialColor method sets the current material colour on the play area cursor.

SetPlayAreaCursorTransform/1

public virtual void SetPlayAreaCursorTransform(Vector3 location)

  • Parameters
    • Vector3 location - The location where to draw the play area cursor.
  • Returns
    • none

The SetPlayAreaCursorTransform method is used to update the position of the play area cursor in world space to the given location.

ToggleState/1

public virtual void ToggleState(bool state)

  • Parameters
    • bool state - The state of whether to show or hide the play area cursor.
  • Returns
    • none

The ToggleState method enables or disables the visibility of the play area cursor.

IsActive/0

public virtual bool IsActive()

  • Parameters
    • none
  • Returns
    • bool - Returns true if the play area cursor GameObject is active.

The IsActive method returns whether the play area cursor GameObject is active or not.

GetPlayAreaContainer/0

public virtual GameObject GetPlayAreaContainer()

  • Parameters
    • none
  • Returns
    • GameObject - The GameObject that is the container of the play area cursor.

The GetPlayAreaContainer method returns the created GameObject that holds the play area cursor representation.

ToggleVisibility/1

public virtual void ToggleVisibility(bool state)

  • Parameters
    • bool state - The state of the cursor visibility. True will show the renderers and false will hide the renderers.
  • Returns
    • none

The ToggleVisibility method enables or disables the play area cursor renderers to allow the cursor to be seen or hidden.

Example

VRTK/Examples/012_Controller_PointerWithAreaCollision shows how a Bezier Pointer with the Play Area Cursor and Collision Detection enabled can be used to traverse a game area but not allow teleporting into areas where the walls or other objects would fall into the play area space enabling the user to enter walls.