From 2065a7f9e3c202b480dac80c1416d2b2d39a584d Mon Sep 17 00:00:00 2001
From: Harvey Ball <me@harveyball.com>
Date: Mon, 8 May 2017 15:19:57 +0100
Subject: [PATCH] feat(Locomotion): add method to force teleport.

The Basic Teleport script (and therefore any child script) now has a
method called `ForceTeleport` which can be used to force the teleporter
to update it's position without needing to listen to a destination
marker event. Which can be useful if the play area needs setting to
a specific position without wanting to use a destination marker, such
as setting a spawn point.
---
 .../Scripts/Locomotion/VRTK_BasicTeleport.cs  | 33 +++++++++++++++++--
 DOCUMENTATION.md                              | 24 ++++++++++++++
 2 files changed, 55 insertions(+), 2 deletions(-)

diff --git a/Assets/VRTK/Scripts/Locomotion/VRTK_BasicTeleport.cs b/Assets/VRTK/Scripts/Locomotion/VRTK_BasicTeleport.cs
index dc6173168..cb7c170ef 100644
--- a/Assets/VRTK/Scripts/Locomotion/VRTK_BasicTeleport.cs
+++ b/Assets/VRTK/Scripts/Locomotion/VRTK_BasicTeleport.cs
@@ -114,7 +114,7 @@ public virtual bool ValidLocation(Transform target, Vector3 destinationPosition)
             }
 
             bool validNavMeshLocation = false;
-            if (target)
+            if (target != null)
             {
                 NavMeshHit hit;
                 validNavMeshLocation = NavMesh.SamplePosition(destinationPosition, out hit, navMeshLimitDistance, NavMesh.AllAreas);
@@ -124,7 +124,36 @@ public virtual bool ValidLocation(Transform target, Vector3 destinationPosition)
                 validNavMeshLocation = true;
             }
 
-            return (validNavMeshLocation && target && !(VRTK_PolicyList.Check(target.gameObject, targetListPolicy)));
+            return (validNavMeshLocation && target != null && !(VRTK_PolicyList.Check(target.gameObject, targetListPolicy)));
+        }
+
+        /// <summary>
+        /// The ForceTeleport/1 method forces the teleport to update position without needing to listen for a Destination Marker event.
+        /// </summary>
+        /// <param name="teleportArgs">The pseudo Destination Marker event for the teleport action.</param>
+        public virtual void ForceTeleport(DestinationMarkerEventArgs teleportArgs)
+        {
+            DoTeleport(this, teleportArgs);
+        }
+
+        /// <summary>
+        /// The ForceTeleport/3 method forces the teleport to update position without needing to listen for a Destination Marker event.
+        ///  It will build a destination marker out of the provided parameters.
+        /// </summary>
+        /// <param name="target">The Transform of the destination object.</param>
+        /// <param name="destinationPosition">The world position to teleport to.</param>
+        /// <param name="destinationRotation">The world rotation to teleport to.</param>
+        public virtual void ForceTeleport(Transform target, Vector3 destinationPosition, Quaternion? destinationRotation = null)
+        {
+            DestinationMarkerEventArgs teleportArgs = new DestinationMarkerEventArgs();
+            teleportArgs.distance = Vector3.Distance(new Vector3(headset.position.x, playArea.position.y, headset.position.z), destinationPosition);
+            teleportArgs.target = target;
+            teleportArgs.raycastHit = new RaycastHit();
+            teleportArgs.destinationPosition = destinationPosition;
+            teleportArgs.destinationRotation = destinationRotation;
+            teleportArgs.forceDestinationPosition = false;
+            teleportArgs.enableTeleport = true;
+            ForceTeleport(teleportArgs);
         }
 
         protected virtual void OnEnable()
diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md
index 0848b2c5a..a84f52b9b 100644
--- a/DOCUMENTATION.md
+++ b/DOCUMENTATION.md
@@ -1659,6 +1659,30 @@ The ToggleTeleportEnabled method is used to determine whether the teleporter wil
 
 The ValidLocation method determines if the given target is a location that can be teleported to
 
+#### ForceTeleport/1
+
+  > `public virtual void ForceTeleport(DestinationMarkerEventArgs teleportArgs)`
+
+  * Parameters
+   * `DestinationMarkerEventArgs teleportArgs` - The pseudo Destination Marker event for the teleport action.
+  * Returns
+   * _none_
+
+The ForceTeleport/1 method forces the teleport to update position without needing to listen for a Destination Marker event.
+
+#### ForceTeleport/3
+
+  > `public virtual void ForceTeleport(Transform target, Vector3 destinationPosition, Quaternion? destinationRotation = null)`
+
+  * Parameters
+   * `Transform target` - The Transform of the destination object.
+   * `Vector3 destinationPosition` - The world position to teleport to.
+   * `Quaternion? destinationRotation` - The world rotation to teleport to.
+  * Returns
+   * _none_
+
+The ForceTeleport/3 method forces the teleport to update position without needing to listen for a Destination Marker event. It will build a destination marker out of the provided parameters.
+
 ### Example
 
 `VRTK/Examples/004_CameraRig_BasicTeleport` uses the `VRTK_SimplePointer` script on the Controllers to initiate a laser pointer by pressing the `Touchpad` on the controller and when the laser pointer is deactivated (release the `Touchpad`) then the user is teleported to the location of the laser pointer tip as this is where the pointer destination marker position is set to.