feat(Interaction): add helper for interaction unity events

Assets/VRTK/Scripts/Helper/UnityEvents/VRTK_InteractableObject_UnityEvents.cs

@@ -0,0 +1,70 @@
+using UnityEngine;
+using System.Collections;
+using UnityEngine.Events;
+using VRTK;
+
+[RequireComponent (typeof(VRTK_InteractableObject))]
+public class VRTK_InteractableObject_UnityEvents : MonoBehaviour 
+{
+
+	private VRTK_InteractableObject io;
+
+	[System.Serializable]
+	public class UnityObjectEvent: UnityEvent<GameObject> {};
+	public UnityObjectEvent OnTouch;
+	public UnityObjectEvent OnUntouch; 
+	public UnityObjectEvent OnGrab; 
+	public UnityObjectEvent OnUngrab; 
+	public UnityObjectEvent OnUse; 
+	public UnityObjectEvent OnUnuse;  
+
+	private void OnEnable () 
+	{
+		io.InteractableObjectTouched += Touch;
+		io.InteractableObjectUntouched += UnTouch;
+		io.InteractableObjectGrabbed += Grab;
+		io.InteractableObjectUngrabbed += UnGrab;
+		io.InteractableObjectUsed += Use;
+		io.InteractableObjectUnused += Unuse;
+	}
+
+	private void Touch(object o, InteractableObjectEventArgs e)
+	{
+		OnTouch.Invoke(e.interactingObject);
+	}
+
+	private void UnTouch(object o, InteractableObjectEventArgs e)
+	{
+		OnUntouch.Invoke(e.interactingObject);
+	}
+
+	private void Grab(object o, InteractableObjectEventArgs e)
+	{
+		OnGrab.Invoke(e.interactingObject);
+	}
+
+	private void UnGrab(object o, InteractableObjectEventArgs e)
+	{
+		OnUngrab.Invoke(e.interactingObject);
+	}
+
+	private void Use(object o, InteractableObjectEventArgs e)
+	{
+		OnUse.Invoke(e.interactingObject);
+	}
+
+	private void Unuse(object o, InteractableObjectEventArgs e)
+	{
+		OnUnuse.Invoke(e.interactingObject);
+	}
+
+	private void OnDisable () 
+	{
+		io.InteractableObjectTouched -= Touch;
+		io.InteractableObjectUntouched -= UnTouch;
+		io.InteractableObjectGrabbed -= Grab;
+		io.InteractableObjectUngrabbed -= UnGrab;
+		io.InteractableObjectUsed -= Use;
+		io.InteractableObjectUnused -= Unuse;
+	}
+}

DOCUMENTATION.md

@@ -963,11 +963,11 @@ The concept that the VR user has a physical in game presence which is accomplish
 
   * `PresenceFallStarted` - Emitted when a gravity based fall has started
   * `PresenceFallEnded` - Emitted when a gravity based fall has ended
-  
+
 #### Event Payload
 
   * `float fallDistance` - The total height the player has dropped from a gravity based fall.
-  
+
 ### Class Methods
 
 #### SetFallingPhysicsOnlyParams/1
@@ -989,9 +989,9 @@ The SetFallingPhysicsOnlyParams method will toggle the `fallingPhysicsOnly` clas
    * _none_
   * Returns
    * `bool` - Returns if the player is in a physics falling state or not.
-   
+
 The IsFalling method will return if the class is using physics based falling and is currently in a falling state.
-   
+
 #### GetHeadset/0
 
   > `public Transform GetHeadset()`
@@ -1012,7 +1012,7 @@ The GetHeadset method returns the transform of the object representing the VR he
   * Returns
    * _none_
 
-The StartPhysicsFall method initializes the physics based fall state, enable physics and send out the `PresenceFallStarted` event. 
+The StartPhysicsFall method initializes the physics based fall state, enable physics and send out the `PresenceFallStarted` event.
 
 #### StopPhysicsFall/0
 
@@ -1026,7 +1026,7 @@ The StartPhysicsFall method initializes the physics based fall state, enable phy
 The StopPhysicsFall method ends the physics based fall state, disables physics and send out the `PresenceFallEnded` event.
 
 ### Example
-  
+
 `VRTK/Examples/017_CameraRig_TouchpadWalking` has a collection of walls and slopes that can be traversed by the user with the touchpad but the user cannot pass through the objects as they are collidable and the rigidbody physics won't allow the intersection to occur.
 
 ---
@@ -1119,7 +1119,7 @@ The basis of this script is to provide a simple mechanism for identifying object
    * `Override Hide` means hiding the controller when grabbed, overriding controller settings.
    * `Override Dont Hide` means *not* hiding the controller when grabbed, overriding controller settings.
   * **Stay Grabbed On Teleport:** If this is checked then the object will stay grabbed to the controller when a teleport occurs. If it is unchecked then the object will be released when a teleport occurs.
-  
+
 #### Grab Mechanics
   * **Grab Attach Type:** This determines how the grabbed item will be attached to the controller when it is grabbed.
    * `Fixed Joint` attaches the object to the controller with a fixed joint meaning it tracks the position and rotation of the controller with perfect 1:1 tracking.
@@ -1159,6 +1159,17 @@ The basis of this script is to provide a simple mechanism for identifying object
   * `InteractableObjectUsed` - Emitted when another object uses the current object (e.g. a controller).
   * `InteractableObjectUnused` - Emitted when the other object stops using the current object.
 
+### Unity Events
+
+Adding the `VRTK_InteractableObject_UnityEvents` component to an Interactable Object allows access to `UnityEvents` that will react identically to the Class Events.
+
+  * `OnTouch` - Emitted when another object touches the current object.
+  * `OnUntouch` - Emitted when the other object stops touching the current object.
+  * `OnGrab` - Emitted when another object grabs the current object (e.g. a controller).
+  * `OnUngrab` - Emitted when the other object stops grabbing the current object.
+  * `OnUse` - Emitted when another object uses the current object (e.g. a controller).
+  * `OnUnuse` - Emitted when the other object stops using the current object.
+
 #### Event Payload
 
   * `GameObject interactingObject` - The object that is initiating the interaction (e.g. a controller)
@@ -1622,7 +1633,7 @@ The AttemptGrab method will attempt to grab the currently touched object without
 The GetGrabbedObject method returns the current object being grabbed by the controller.
 
 ### Example
-  
+
 `VRTK/Examples/005_Controller/BasicObjectGrabbing` demonstrates the grabbing of interactable objects that have the `VRTK_InteractableObject` script attached to them. The objects can be picked up and thrown around.
 
 `VRTK/Examples/013_Controller_UsingAndGrabbingMultipleObjects` demonstrates that each controller can grab and use objects independently and objects can also be toggled to their use state simultaneously.
@@ -1657,7 +1668,7 @@ If a valid interactable object is usable then pressing the set `Use` button on t
 
   * `uint controllerIndex` - The index of the controller doing the interaction
   * `GameObject target` - The GameObject of the interactable object that is being interacted with by the controller
-  
+
 ### Class Methods
 
 #### GetUsingObject/0
@@ -1800,12 +1811,12 @@ All 3D controls extend the `VRTK_Control` abstract class which provides a defaul
 ### Class Events
 
   * `OnValueChanged` - Emitted when the control is interacted with.
-  
+
 #### Event Payload
 
   * `float value` - The current value in the context of the control extending this abstract class.
   * `float value` - The normalized value in the range between 0 and 100 of the control extending this abstract class.
-  
+
 ### Class Methods
 
 #### GetValue/0
@@ -1896,7 +1907,7 @@ The script will instantiate the required Rigidbody, Interactable and HingeJoint
   * **Lid:** The game object for the lid.
   * **Body:** The game object for the body.
   * **Handle:** The game object for the handle.
-  * **Content:** The parent game object for the chest content elements. 
+  * **Content:** The parent game object for the chest content elements.
   * **Hide Content:** Makes the content invisible while the chest is closed.
   * **Max Angle:** The maximum opening angle of the chest.
 
@@ -1923,7 +1934,7 @@ The script will instantiate the required Rigidbodies, Interactable and HingeJoin
   * **Door:** The game object for the door. Can also be an empty parent or left empty if the script is put onto the actual door mesh. If no colliders exist yet a collider will tried to be automatically attached to all children that expose renderers.
   * **Handles:** The game object for the handles. Can also be an empty parent or left empty. If empty the door can only be moved using the rigidbody mode of the controller. If no collider exists yet a compound collider made up of all children will try to be calculated but this will fail if the door is rotated. In that case a manual collider will need to be assigned.
   * **Frame:** The game object for the frame to which the door is attached. Should only be set if the frame will move as well to ensure that the door moves along with the frame.
-  * **Content:** The parent game object for the door content elements. 
+  * **Content:** The parent game object for the door content elements.
   * **Hide Content:** Makes the content invisible while the door is closed.
   * **Max Angle:** The maximum opening angle of the door.
   * **Open Inward:** Can the door be pulled to open.
@@ -1953,8 +1964,8 @@ It is possible to supply a third game object which is the root of the contents i
 
   * **Direction:** The axis on which the chest should open. All other axis will be frozen.
   * **Body:** The game object for the body.
-  * **Handle:** The game object for the handle. 
-  * **Content:** The parent game object for the drawer content elements. 
+  * **Handle:** The game object for the handle.
+  * **Content:** The parent game object for the drawer content elements.
   * **Hide Content:** Makes the content invisible while the drawer is closed.
   * **Snapping:** Keeps the drawer closed with a slight force. This way the drawer will not gradually open due to some minor physics effect.
 
@@ -2413,4 +2424,4 @@ A scene that demonstrates how the Bezier Pointer can display an object (teleport
 
 A scene that demonstrates how to set up the climbing mechanism with different activities to try it with. A `VRTK_PlayerClimb` object is needed on the `[CameraRig]`. `VRTK_HeightAdjustTeleport` is also added to the `[CameraRig]` to allow movement, but also to allow walking off edges with `UseGravity` enabled. Various objects with a `VRTK_InteractableObject` component are scattered throughout the level. They all have the `GrabAttachMechanic` set to `Climbable`.
 
-[Catlike Coding]: http://catlikecoding.com/unity/tutorials/curves-and-splines/
+[Catlike Coding]: http://catlikecoding.com/unity/tutorials/curves-and-splines/