feat(Interaction): add near touch to interact haptics

The Interact Haptics script now has an option for initiating haptics
on a near touch interaction event.

The Interact Haptics script has also been refactored to use the
Interactable Object events rather than having hard coded method calls
from the interaction scripts (Touch/Grab/Use) to the Interact Haptics
script.

The Interactable Object script has a new method to help subscribe
and unsubscribe from these interaction events and the Interact
Object Highlighter has also been refactored to use these new event
subscription helpers.

Author: thestonefox

Assets/VRTK/Documentation/API.md

@@ -4200,6 +4200,30 @@ The PerformSecondaryAction method returns whether the object has a secondary act
 
 The ResetIgnoredColliders method is used to clear any stored ignored colliders in case the `Ignored Colliders` array parameter is changed at runtime. This needs to be called manually if changes are made at runtime.
 
+#### SubscribeToInteractionEvent/2
+
+  > `public virtual void SubscribeToInteractionEvent(InteractionType givenType, InteractableObjectEventHandler methodCallback)`
+
+ * Parameters
+   * `InteractionType givenType` - The Interaction Type to register the events for.
+   * `InteractableObjectEventHandler methodCallback` - The method to execute when the Interaction Type is initiated.
+ * Returns
+   * _none_
+
+The SubscribeToInteractionEvent method subscribes a given method callback for the given Interaction Type.
+
+#### UnsubscribeFromInteractionEvent/2
+
+  > `public virtual void UnsubscribeFromInteractionEvent(InteractionType givenType, InteractableObjectEventHandler methodCallback)`
+
+ * Parameters
+   * `InteractionType givenType` - The Interaction Type that the previous event subscription was under.
+   * `InteractableObjectEventHandler methodCallback` - The method that was being executed when the Interaction Type was initiated.
+ * Returns
+   * _none_
+
+The UnsubscribeFromInteractionEvent method unsubscribes a previous event subscription for the given Interaction Type.
+
 ### Example
 
 `VRTK/Examples/005_Controller_BasicObjectGrabbing` uses the `VRTK_InteractTouch` and `VRTK_InteractGrab` scripts on the controllers to show how an interactable object can be grabbed and snapped to the controller and thrown around the game world.
@@ -4314,6 +4338,10 @@ The Interact Haptics script is attached on the same GameObject as an Interactabl
 
 ### Inspector Parameters
 
+ * **Clip On Near Touch:** Denotes the audio clip to use to rumble the controller on near touch.
+ * **Strength On Near Touch:** Denotes how strong the rumble in the controller will be on near touch.
+ * **Duration On Near Touch:** Denotes how long the rumble in the controller will last on near touch.
+ * **Interval On Near Touch:** Denotes interval betweens rumble in the controller on near touch.
  * **Clip On Touch:** Denotes the audio clip to use to rumble the controller on touch.
  * **Strength On Touch:** Denotes how strong the rumble in the controller will be on touch.
  * **Duration On Touch:** Denotes how long the rumble in the controller will last on touch.
@@ -4326,9 +4354,11 @@ The Interact Haptics script is attached on the same GameObject as an Interactabl
  * **Strength On Use:** Denotes how strong the rumble in the controller will be on use.
  * **Duration On Use:** Denotes how long the rumble in the controller will last on use.
  * **Interval On Use:** Denotes interval betweens rumble in the controller on use.
+ * **Object To Affect:** The Interactable Object to initiate the haptics from. If this is left blank, then the Interactable Object will need to be on the current or a parent GameObject.
 
 ### Class Events
 
+ * `InteractHapticsNearTouched` - Emitted when the haptics are from a near touch.
  * `InteractHapticsTouched` - Emitted when the haptics are from a touch.
  * `InteractHapticsGrabbed` - Emitted when the haptics are from a grab.
  * `InteractHapticsUsed` - Emitted when the haptics are from a use.
@@ -4345,6 +4375,28 @@ Adding the `VRTK_InteractHaptics_UnityEvents` component to `VRTK_InteractHaptics
 
 ### Class Methods
 
+#### CancelHaptics/1
+
+  > `public virtual void CancelHaptics(VRTK_ControllerReference controllerReference)`
+
+ * Parameters
+   * `VRTK_ControllerReference controllerReference` -
+ * Returns
+   * _none_
+
+The CancelHaptics method cancels any existing haptic feedback on the given controller.
+
+#### HapticsOnNearTouch/1
+
+  > `public virtual void HapticsOnNearTouch(VRTK_ControllerReference controllerReference)`
+
+ * Parameters
+   * `VRTK_ControllerReference controllerReference` - The reference to the controller to activate the haptic feedback on.
+ * Returns
+   * _none_
+
+The HapticsOnNearTouch method triggers the haptic feedback on the given controller for the settings associated with near touch.
+
 #### HapticsOnTouch/1
 
   > `public virtual void HapticsOnTouch(VRTK_ControllerReference controllerReference)`

Assets/VRTK/Source/Editor/VRTK_InteractHapticsEditor.cs

@@ -6,6 +6,11 @@
     [CustomEditor(typeof(VRTK_InteractHaptics))]
     public class VRTK_InteractHapticsEditor : Editor
     {
+        SerializedProperty clipOnNearTouch;
+        SerializedProperty strengthOnNearTouch;
+        SerializedProperty durationOnNearTouch;
+        SerializedProperty intervalOnNearTouch;
+
         SerializedProperty clipOnTouch;
         SerializedProperty strengthOnTouch;
         SerializedProperty durationOnTouch;
@@ -21,8 +26,15 @@ public class VRTK_InteractHapticsEditor : Editor
         SerializedProperty durationOnUse;
         SerializedProperty intervalOnUse;
 
+        SerializedProperty objectToAffect;
+
         private void OnEnable()
         {
+            clipOnNearTouch = serializedObject.FindProperty("clipOnNearTouch");
+            strengthOnNearTouch = serializedObject.FindProperty("strengthOnNearTouch");
+            durationOnNearTouch = serializedObject.FindProperty("durationOnNearTouch");
+            intervalOnNearTouch = serializedObject.FindProperty("intervalOnNearTouch");
+
             clipOnTouch = serializedObject.FindProperty("clipOnTouch");
             strengthOnTouch = serializedObject.FindProperty("strengthOnTouch");
             durationOnTouch = serializedObject.FindProperty("durationOnTouch");
@@ -37,14 +49,27 @@ private void OnEnable()
             strengthOnUse = serializedObject.FindProperty("strengthOnUse");
             durationOnUse = serializedObject.FindProperty("durationOnUse");
             intervalOnUse = serializedObject.FindProperty("intervalOnUse");
+
+            objectToAffect = serializedObject.FindProperty("objectToAffect");
         }
 
         public override void OnInspectorGUI()
         {
             serializedObject.Update();
 
             EditorGUILayout.Space();
-            EditorGUILayout.LabelField("Haptics On Touch", EditorStyles.boldLabel);
+            EditorGUILayout.LabelField("Haptics On Near Touch Settings", EditorStyles.boldLabel);
+
+            EditorGUILayout.ObjectField(clipOnNearTouch, typeof(AudioClip));
+            if (clipOnNearTouch.objectReferenceValue == null)
+            {
+                EditorGUILayout.PropertyField(strengthOnNearTouch);
+                EditorGUILayout.PropertyField(durationOnNearTouch);
+                EditorGUILayout.PropertyField(intervalOnNearTouch);
+            }
+
+            EditorGUILayout.Space();
+            EditorGUILayout.LabelField("Haptics On Touch Settings", EditorStyles.boldLabel);
 
             EditorGUILayout.ObjectField(clipOnTouch, typeof(AudioClip));
             if (clipOnTouch.objectReferenceValue == null)
@@ -55,7 +80,7 @@ public override void OnInspectorGUI()
             }
 
             EditorGUILayout.Space();
-            EditorGUILayout.LabelField("Haptics On Grab", EditorStyles.boldLabel);
+            EditorGUILayout.LabelField("Haptics On Grab Settings", EditorStyles.boldLabel);
 
             EditorGUILayout.ObjectField(clipOnGrab, typeof(AudioClip));
             if (clipOnGrab.objectReferenceValue == null)
@@ -66,7 +91,7 @@ public override void OnInspectorGUI()
             }
 
             EditorGUILayout.Space();
-            EditorGUILayout.LabelField("Haptics On Use", EditorStyles.boldLabel);
+            EditorGUILayout.LabelField("Haptics On Use Settings", EditorStyles.boldLabel);
 
             EditorGUILayout.ObjectField(clipOnUse, typeof(AudioClip));
             if (clipOnUse.objectReferenceValue == null)
@@ -76,6 +101,9 @@ public override void OnInspectorGUI()
                 EditorGUILayout.PropertyField(intervalOnUse);
             }
 
+            EditorGUILayout.Space();
+            EditorGUILayout.PropertyField(objectToAffect);
+
             serializedObject.ApplyModifiedProperties();
         }
     }

Assets/VRTK/Source/Scripts/Interactions/VRTK_InteractGrab.cs

@@ -499,18 +499,6 @@ protected virtual GameObject GetUndroppableObject()
             return null;
         }
 
-        protected virtual void AttemptHaptics(bool initialGrabAttempt)
-        {
-            if (grabbedObject != null && initialGrabAttempt)
-            {
-                VRTK_InteractHaptics doHaptics = grabbedObject.GetComponentInParent<VRTK_InteractHaptics>();
-                if (doHaptics != null)
-                {
-                    doHaptics.HapticsOnGrab(controllerReference);
-                }
-            }
-        }
-
         protected virtual void AttemptGrabObject()
         {
             GameObject objectToGrab = GetGrabbableObject();
@@ -529,7 +517,6 @@ protected virtual void PerformGrabAttempt(GameObject objectToGrab)
             IncrementGrabState();
             bool initialGrabAttempt = IsValidGrabAttempt(objectToGrab);
             undroppableGrabbedObject = GetUndroppableObject();
-            AttemptHaptics(initialGrabAttempt);
         }
 
         protected virtual bool ScriptValidGrab(VRTK_InteractableObject objectToGrabScript)

Assets/VRTK/Source/Scripts/Interactions/VRTK_InteractHaptics.cs

@@ -25,7 +25,19 @@ public struct InteractHapticsEventArgs
     [AddComponentMenu("VRTK/Scripts/Interactions/VRTK_InteractHaptics")]
     public class VRTK_InteractHaptics : MonoBehaviour
     {
-        [Header("Haptics On Touch")]
+        [Header("Haptics On Near Touch Settings")]
+
+        [Tooltip("Denotes the audio clip to use to rumble the controller on near touch.")]
+        public AudioClip clipOnNearTouch;
+        [Tooltip("Denotes how strong the rumble in the controller will be on near touch.")]
+        [Range(0, 1)]
+        public float strengthOnNearTouch = 0;
+        [Tooltip("Denotes how long the rumble in the controller will last on near touch.")]
+        public float durationOnNearTouch = 0f;
+        [Tooltip("Denotes interval betweens rumble in the controller on near touch.")]
+        public float intervalOnNearTouch = minInterval;
+
+        [Header("Haptics On Touch Settings")]
 
         [Tooltip("Denotes the audio clip to use to rumble the controller on touch.")]
         public AudioClip clipOnTouch;
@@ -37,7 +49,7 @@ public class VRTK_InteractHaptics : MonoBehaviour
         [Tooltip("Denotes interval betweens rumble in the controller on touch.")]
         public float intervalOnTouch = minInterval;
 
-        [Header("Haptics On Grab")]
+        [Header("Haptics On Grab Settings")]
 
         [Tooltip("Denotes the audio clip to use to rumble the controller on grab.")]
         public AudioClip clipOnGrab;
@@ -49,7 +61,7 @@ public class VRTK_InteractHaptics : MonoBehaviour
         [Tooltip("Denotes interval betweens rumble in the controller on grab.")]
         public float intervalOnGrab = minInterval;
 
-        [Header("Haptics On Use")]
+        [Header("Haptics On Use Settings")]
 
         [Tooltip("Denotes the audio clip to use to rumble the controller on use.")]
         public AudioClip clipOnUse;
@@ -61,6 +73,15 @@ public class VRTK_InteractHaptics : MonoBehaviour
         [Tooltip("Denotes interval betweens rumble in the controller on use.")]
         public float intervalOnUse = minInterval;
 
+        [Header("Custom Settings")]
+
+        [Tooltip("The Interactable Object to initiate the haptics from. If this is left blank, then the Interactable Object will need to be on the current or a parent GameObject.")]
+        public VRTK_InteractableObject objectToAffect;
+
+        /// <summary>
+        /// Emitted when the haptics are from a near touch.
+        /// </summary>
+        public event InteractHapticsEventHandler InteractHapticsNearTouched;
         /// <summary>
         /// Emitted when the haptics are from a touch.
         /// </summary>
@@ -76,6 +97,14 @@ public class VRTK_InteractHaptics : MonoBehaviour
 
         protected const float minInterval = 0.05f;
 
+        public virtual void OnInteractHapticsNearTouched(InteractHapticsEventArgs e)
+        {
+            if (InteractHapticsNearTouched != null)
+            {
+                InteractHapticsNearTouched(this, e);
+            }
+        }
+
         public virtual void OnInteractHapticsTouched(InteractHapticsEventArgs e)
         {
             if (InteractHapticsTouched != null)
@@ -100,6 +129,32 @@ public virtual void OnInteractHapticsUsed(InteractHapticsEventArgs e)
             }
         }
 
+        /// <summary>
+        /// The CancelHaptics method cancels any existing haptic feedback on the given controller.
+        /// </summary>
+        /// <param name="controllerReference"></param>
+        public virtual void CancelHaptics(VRTK_ControllerReference controllerReference)
+        {
+            VRTK_ControllerHaptics.CancelHapticPulse(controllerReference);
+        }
+
+        /// <summary>
+        /// The HapticsOnNearTouch method triggers the haptic feedback on the given controller for the settings associated with near touch.
+        /// </summary>
+        /// <param name="controllerReference">The reference to the controller to activate the haptic feedback on.</param>
+        public virtual void HapticsOnNearTouch(VRTK_ControllerReference controllerReference)
+        {
+            if (clipOnNearTouch != null)
+            {
+                VRTK_ControllerHaptics.TriggerHapticPulse(controllerReference, clipOnNearTouch);
+            }
+            else if (strengthOnNearTouch > 0 && durationOnNearTouch > 0f)
+            {
+                TriggerHapticPulse(controllerReference, strengthOnNearTouch, durationOnNearTouch, intervalOnNearTouch);
+            }
+            OnInteractHapticsNearTouched(SetEventPayload(controllerReference));
+        }
+
         /// <summary>
         /// The HapticsOnTouch method triggers the haptic feedback on the given controller for the settings associated with touch.
         /// </summary>
@@ -153,9 +208,29 @@ public virtual void HapticsOnUse(VRTK_ControllerReference controllerReference)
 
         protected virtual void OnEnable()
         {
-            if (!GetComponent<VRTK_InteractableObject>())
+            objectToAffect = (objectToAffect != null ? objectToAffect : GetComponentInParent<VRTK_InteractableObject>());
+
+            if (objectToAffect != null)
             {
-                VRTK_Logger.Error(VRTK_Logger.GetCommonMessage(VRTK_Logger.CommonMessageKeys.REQUIRED_COMPONENT_MISSING_FROM_GAMEOBJECT, "VRTK_InteractHaptics", "VRTK_InteractableObject", "the same"));
+                objectToAffect.SubscribeToInteractionEvent(VRTK_InteractableObject.InteractionType.NearTouch, NearTouchHaptics);
+                objectToAffect.SubscribeToInteractionEvent(VRTK_InteractableObject.InteractionType.Touch, TouchHaptics);
+                objectToAffect.SubscribeToInteractionEvent(VRTK_InteractableObject.InteractionType.Grab, GrabHaptics);
+                objectToAffect.SubscribeToInteractionEvent(VRTK_InteractableObject.InteractionType.Use, UseHaptics);
+            }
+            else
+            {
+                VRTK_Logger.Error(VRTK_Logger.GetCommonMessage(VRTK_Logger.CommonMessageKeys.REQUIRED_COMPONENT_MISSING_FROM_GAMEOBJECT, "VRTK_InteractHaptics", "VRTK_InteractableObject", "the same or parent"));
+            }
+        }
+
+        protected virtual void OnDisable()
+        {
+            if (objectToAffect != null)
+            {
+                objectToAffect.UnsubscribeFromInteractionEvent(VRTK_InteractableObject.InteractionType.NearTouch, NearTouchHaptics);
+                objectToAffect.UnsubscribeFromInteractionEvent(VRTK_InteractableObject.InteractionType.Touch, TouchHaptics);
+                objectToAffect.UnsubscribeFromInteractionEvent(VRTK_InteractableObject.InteractionType.Grab, GrabHaptics);
+                objectToAffect.UnsubscribeFromInteractionEvent(VRTK_InteractableObject.InteractionType.Use, UseHaptics);
             }
         }
 
@@ -170,5 +245,41 @@ protected virtual InteractHapticsEventArgs SetEventPayload(VRTK_ControllerRefere
             e.controllerReference = givenControllerReference;
             return e;
         }
+
+        protected virtual void NearTouchHaptics(object sender, InteractableObjectEventArgs e)
+        {
+            VRTK_ControllerReference controllerReference = VRTK_ControllerReference.GetControllerReference(e.interactingObject);
+            if (VRTK_ControllerReference.IsValid(controllerReference))
+            {
+                HapticsOnNearTouch(controllerReference);
+            }
+        }
+
+        protected virtual void TouchHaptics(object sender, InteractableObjectEventArgs e)
+        {
+            VRTK_ControllerReference controllerReference = VRTK_ControllerReference.GetControllerReference(e.interactingObject);
+            if (VRTK_ControllerReference.IsValid(controllerReference))
+            {
+                HapticsOnTouch(controllerReference);
+            }
+        }
+
+        protected virtual void GrabHaptics(object sender, InteractableObjectEventArgs e)
+        {
+            VRTK_ControllerReference controllerReference = VRTK_ControllerReference.GetControllerReference(e.interactingObject);
+            if (VRTK_ControllerReference.IsValid(controllerReference))
+            {
+                HapticsOnGrab(controllerReference);
+            }
+        }
+
+        protected virtual void UseHaptics(object sender, InteractableObjectEventArgs e)
+        {
+            VRTK_ControllerReference controllerReference = VRTK_ControllerReference.GetControllerReference(e.interactingObject);
+            if (VRTK_ControllerReference.IsValid(controllerReference))
+            {
+                HapticsOnUse(controllerReference);
+            }
+        }
     }
 }