Up vector implementation and OrientedPathFollow.

3 files changed, 73 insertions, 1 deletions

diff --git a/doc/classes/Curve2D.xml b/doc/classes/Curve2D.xml
index 71bdaff688..26de8be42c 100644
--- a/doc/classes/Curve2D.xml
+++ b/doc/classes/Curve2D.xml
@@ -55,6 +55,8 @@
 			<argument index="0" name="to_point" type="Vector2">
 			</argument>
 			<description>
+				Returns the closest offset to [code]to_point[/code]. This offset is meant to be used in [method interpolate_baked].
+				[code]to_point[/code] must be in this curve's local space.
 			</description>
 		</method>
 		<method name="get_closest_point" qualifiers="const">
@@ -63,6 +65,8 @@
 			<argument index="0" name="to_point" type="Vector2">
 			</argument>
 			<description>
+				Returns the closest point (in curve's local space) to [code]to_point[/code].
+				[code]to_point[/code] must be in this curve's local space.
 			</description>
 		</method>
 		<method name="get_point_count" qualifiers="const">
diff --git a/doc/classes/Curve3D.xml b/doc/classes/Curve3D.xml
index c012e2794e..1355c74faf 100644
--- a/doc/classes/Curve3D.xml
+++ b/doc/classes/Curve3D.xml
@@ -56,12 +56,22 @@
 				Returns the cache of tilts as a [RealArray].
 			</description>
 		</method>
+		<method name="get_baked_up_vectors" qualifiers="const">
+			<return type="PoolVector3Array">
+			</return>
+			<description>
+				Returns the cache of up vectors as a [PoolVector3Array].
+				If [member up_vector_enabled] is [code]false[/code], the cache will be empty.
+			</description>
+		</method>
 		<method name="get_closest_offset" qualifiers="const">
 			<return type="float">
 			</return>
 			<argument index="0" name="to_point" type="Vector3">
 			</argument>
 			<description>
+				Returns the closest offset to [code]to_point[/code]. This offset is meant to be used in one of the interpolate_baked* methods.
+				[code]to_point[/code] must be in this curve's local space.
 			</description>
 		</method>
 		<method name="get_closest_point" qualifiers="const">
@@ -70,6 +80,8 @@
 			<argument index="0" name="to_point" type="Vector3">
 			</argument>
 			<description>
+				Returns the closest point (in curve's local space) to [code]to_point[/code].
+				[code]to_point[/code] must be in this curve's local space.
 			</description>
 		</method>
 		<method name="get_point_count" qualifiers="const">
@@ -140,6 +152,19 @@
 				Cubic interpolation tends to follow the curves better, but linear is faster (and often, precise enough).
 			</description>
 		</method>
+		<method name="interpolate_baked_up_vector" qualifiers="const">
+			<return type="Vector3">
+			</return>
+			<argument index="0" name="offset" type="float">
+			</argument>
+			<argument index="1" name="apply_tilt" type="bool" default="false">
+			</argument>
+			<description>
+				Returns an up vector within the curve at position [code]offset[/code], where [code]offset[/code] is measured as a distance in 3D units along the curve.
+				To do that, it finds the two cached up vectors where the [code]offset[/code] lies between, then interpolates the values. If [code]apply_tilt[/code] is [code]true[/code], an interpolated tilt is applied to the interpolated up vector.
+				If the curve has no up vectors, the function sends an error to the console, and returns (0, 1, 0).
+			</description>
+		</method>
 		<method name="interpolatef" qualifiers="const">
 			<return type="Vector3">
 			</return>
@@ -200,7 +225,7 @@
 			</argument>
 			<description>
 				Sets the tilt angle in radians for the point "idx". If the index is out of bounds, the function sends an error to the console.
-				The tilt controls the rotation along the look-at axis an object traveling the path would have. In the case of a curve controlling a [PathFollow], this tilt is an offset over the natural tilt the PathFollow calculates.
+				The tilt controls the rotation along the look-at axis an object traveling the path would have. In the case of a curve controlling a [PathFollow] or [OrientedPathFollow], this tilt is an offset over the natural tilt the [PathFollow] or [OrientedPathFollow] calculates.
 			</description>
 		</method>
 		<method name="tessellate" qualifiers="const">
@@ -222,6 +247,9 @@
 		<member name="bake_interval" type="float" setter="set_bake_interval" getter="get_bake_interval">
 			The distance in meters between two adjacent cached points. Changing it forces the cache to be recomputed the next time the [method get_baked_points] or [method get_baked_length] function is called. The smaller the distance, the more points in the cache and the more memory it will consume, so use with care.
 		</member>
+		<member name="up_vector_enabled" type="bool" setter="set_up_vector_enabled" getter="is_up_vector_enabled">
+			If [code]true[/code], the curve will bake up vectors used for orientation. See [OrientedPathFollow]. Changing it forces the cache to be recomputed.
+		</member>
 	</members>
 	<constants>
 	</constants>
diff --git a/doc/classes/OrientedPathFollow.xml b/doc/classes/OrientedPathFollow.xml
new file mode 100644
index 0000000000..c32e545ff5
--- /dev/null
+++ b/doc/classes/OrientedPathFollow.xml
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OrientedPathFollow" inherits="Spatial" category="Core" version="3.1">
+	<brief_description>
+		Oriented point sampler for a [Path].
+	</brief_description>
+	<description>
+		This node behaves like [PathFollow], except it uses its parent [Path] up vector information to enforce orientation. 
+		Make sure to check if the curve of this node's parent [Path] has up vectors enabled. See [PathFollow] and [Curve3D] for further information. 
+	</description>
+	<tutorials>
+	</tutorials>
+	<demos>
+	</demos>
+	<methods>
+	</methods>
+	<members>
+		<member name="cubic_interp" type="bool" setter="set_cubic_interpolation" getter="get_cubic_interpolation">
+			If [code]true[/code] the position between two cached points is interpolated cubically, and linearly otherwise.
+			The points along the [Curve3D] of the [Path] are precomputed before use, for faster calculations. The point at the requested offset is then calculated interpolating between two adjacent cached points. This may present a problem if the curve makes sharp turns, as the cached points may not follow the curve closely enough.
+			There are two answers to this problem: Either increase the number of cached points and increase memory consumption, or make a cubic interpolation between two points at the cost of (slightly) slower calculations.
+		</member>
+		<member name="h_offset" type="float" setter="set_h_offset" getter="get_h_offset">
+			The node's offset along the curve.
+		</member>
+		<member name="loop" type="bool" setter="set_loop" getter="has_loop">
+			If [code]true[/code], any offset outside the path's length will wrap around, instead of stopping at the ends. Use it for cyclic paths.
+		</member>
+		<member name="offset" type="float" setter="set_offset" getter="get_offset">
+			The distance from the first vertex, measured in 3D units along the path. This sets this node's position to a point within the path.
+		</member>
+		<member name="unit_offset" type="float" setter="set_unit_offset" getter="get_unit_offset">
+			The distance from the first vertex, considering 0.0 as the first vertex and 1.0 as the last. This is just another way of expressing the offset within the path, as the offset supplied is multiplied internally by the path's length.
+		</member>
+		<member name="v_offset" type="float" setter="set_v_offset" getter="get_v_offset">
+			The node's offset perpendicular to the curve.
+		</member>
+	</members>
+	<constants>
+	</constants>
+</class>