Documented classes Curve*, Path*, and PathFollow*

doc/base/classes.xml

@@ -8712,14 +8712,18 @@
 </class>
 <class name="Curve2D" inherits="Resource" category="Core">
 	<brief_description>
+	Describes a Bezier curve in 2D space.
 	</brief_description>
 	<description>
+	This class describes a Bezier curve in 2D space. It is mainly used to give a shape to a [Path2D], but can be manually sampled for other purposes.
+It keeps a cache of precalculated points along the curve, to speed further calculations up.
 	</description>
 	<methods>
 		<method name="get_point_count" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
+			Returns the number of points describing the curve.
 			</description>
 		</method>
 		<method name="add_point">
@@ -8732,6 +8736,8 @@
 			<argument index="3" name="atpos" type="int" default="-1">
 			</argument>
 			<description>
+			Adds a point to a curve, at position "pos", with control points "in" and "out".
+If "atpos" is given, the point is inserted before the point number "atpos", moving that point (and every point after) after the inserted point. If "atpos" is not given, or is an illegal value (atpos &lt;0 or atpos &gt;= [method get_point_count]), the point will be appended at the end of the point list.
 			</description>
 		</method>
 		<method name="set_point_pos">
@@ -8740,6 +8746,7 @@
 			<argument index="1" name="pos" type="Vector2">
 			</argument>
 			<description>
+			Sets the position for the vertex "idx". If the index is out of bounds, the function sends an error to the console.
 			</description>
 		</method>
 		<method name="get_point_pos" qualifiers="const">
@@ -8748,6 +8755,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+			Returns the position of the vertex "idx". If the index is out of bounds, the function sends an error to the console, and returns (0, 0).
 			</description>
 		</method>
 		<method name="set_point_in">
@@ -8756,6 +8764,7 @@
 			<argument index="1" name="pos" type="Vector2">
 			</argument>
 			<description>
+			Sets the position of the control point leading to the vertex "idx". If the index is out of bounds, the function sends an error to the console.
 			</description>
 		</method>
 		<method name="get_point_in" qualifiers="const">
@@ -8764,6 +8773,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+			Returns the position of the control point leading to the vertex "idx". If the index is out of bounds, the function sends an error to the console, and returns (0, 0).
 			</description>
 		</method>
 		<method name="set_point_out">
@@ -8772,6 +8782,7 @@
 			<argument index="1" name="pos" type="Vector2">
 			</argument>
 			<description>
+			Sets the position of the control point leading out of the vertex "idx". If the index is out of bounds, the function sends an error to the console.
 			</description>
 		</method>
 		<method name="get_point_out" qualifiers="const">
@@ -8780,12 +8791,14 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+			Returns the position of the control point leading out of the vertex "idx". If the index is out of bounds, the function sends an error to the console, and returns (0, 0).
 			</description>
 		</method>
 		<method name="remove_point">
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+			Deletes the point "idx" from the curve. Sends an error to the console if "idx" is out of bounds.
 			</description>
 		</method>
 		<method name="interpolate" qualifiers="const">
@@ -8796,6 +8809,8 @@
 			<argument index="1" name="t" type="float">
 			</argument>
 			<description>
+			Returns the position between the vertex "idx" and the vertex "idx"+1, where "t" controls if the point is the first vertex (t = 0.0), the last vertex (t = 1.0), or in between. Values of "t" outside the range (0.0 &gt;= t  &lt;=1) give strange, but predictable results.
+If "idx" is out of bounds it is truncated to the first or last vertex, and "t" is ignored. If the curve has no points, the function sends an error to the console, and returns (0, 0).
 			</description>
 		</method>
 		<method name="interpolatef" qualifiers="const">
@@ -8804,24 +8819,28 @@
 			<argument index="0" name="fofs" type="float">
 			</argument>
 			<description>
+			Returns the position at the vertex "fofs". It calls [method interpolate] using the integer part of fofs as "idx", and its fractional part as "t".
 			</description>
 		</method>
 		<method name="set_bake_interval">
 			<argument index="0" name="distance" type="float">
 			</argument>
 			<description>
+			Sets the distance in pixels between two adjacent cached points. Changing it forces the cache to be recomputed the next time a xxx_baked_xxx function is called. The less distance, the more points the cache will have, and the more memory it will consume, so use with care.
 			</description>
 		</method>
 		<method name="get_bake_interval" qualifiers="const">
 			<return type="float">
 			</return>
 			<description>
+			Returns the distance between two adjacent cached points.
 			</description>
 		</method>
 		<method name="get_baked_length" qualifiers="const">
 			<return type="float">
 			</return>
 			<description>
+			Returns the total length of the curve, based on the cached points. Given enough density (see [method set_bake_interval]), it should be approximate enough.
 			</description>
 		</method>
 		<method name="interpolate_baked" qualifiers="const">
@@ -8832,12 +8851,30 @@
 			<argument index="1" name="cubic" type="bool" default="false">
 			</argument>
 			<description>
+			Returns a point within the curve at position "offset", where "offset" is measured as a pixel distance along the curve.
+To do that, it finds the two cached points where the "offset" lies between, then interpolates the values. This interpolation is cubic if "cubic" is set to true, or linear if set to false.
+Cubic interpolation tends to follow the curves better, but linear is faster (and often, precise enough).
 			</description>
 		</method>
 		<method name="get_baked_points" qualifiers="const">
 			<return type="Vector2Array">
 			</return>
 			<description>
+			Returns the cache of points as a [Vector2Array].
+			</description>
+		</method>
+		<method name="tesselate" qualifiers="const">
+			<argument index="0" name="max_stages" type="int" default="5">
+			</argument>
+			<argument index="1" name="tolerance_degrees" type="float" default="4">
+			</argument>
+			<return type="Vector2Array">
+			</return>
+			<description>
+			Returns a list of points along the curve, with a curvature controlled point density. That is, the curvier parts will have more points than the straighter parts.
+This approximation makes straight segments between each point, then subdivides those segments until the resulting shape is similar enough.
+"max_stages" controls how many subdivisions a curve segment may face before it is considered approximate enough. Each subdivision splits the segment in half, so the default 5 stages may mean up to 32 subdivisions per curve segment. Increase with care!
+"tolerance_degrees" controls how many degrees the midpoint of a segment may deviate from the real curve, before the segment has to be subdivided.
 			</description>
 		</method>
 		<method name="tesselate" qualifiers="const">
@@ -8856,14 +8893,18 @@
 </class>
 <class name="Curve3D" inherits="Resource" category="Core">
 	<brief_description>
+	Describes a Bezier curve in 3D space.
 	</brief_description>
 	<description>
+	This class describes a Bezier curve in 3D space. It is mainly used to give a shape to a [Path], but can be manually sampled for other purposes.
+It keeps a cache of precalculated points along the curve, to speed further calculations up.
 	</description>
 	<methods>
 		<method name="get_point_count" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
+			Returns the number of points describing the curve.
 			</description>
 		</method>
 		<method name="add_point">
@@ -8876,6 +8917,8 @@
 			<argument index="3" name="atpos" type="int" default="-1">
 			</argument>
 			<description>
+			Adds a point to a curve, at position "pos", with control points "in" and "out".
+If "atpos" is given, the point is inserted before the point number "atpos", moving that point (and every point after) after the inserted point. If "atpos" is not given, or is an illegal value (atpos &lt;0 or atpos &gt;= [method get_point_count]), the point will be appended at the end of the point list.
 			</description>
 		</method>
 		<method name="set_point_pos">
@@ -8884,6 +8927,7 @@
 			<argument index="1" name="pos" type="Vector3">
 			</argument>
 			<description>
+			Sets the position for the vertex "idx". If the index is out of bounds, the function sends an error to the console.
 			</description>
 		</method>
 		<method name="get_point_pos" qualifiers="const">
@@ -8892,6 +8936,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+			Returns the position of the vertex "idx". If the index is out of bounds, the function sends an error to the console, and returns (0, 0, 0).
 			</description>
 		</method>
 		<method name="set_point_tilt">
@@ -8900,6 +8945,8 @@
 			<argument index="1" name="tilt" type="float">
 			</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 travelling 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.
 			</description>
 		</method>
 		<method name="get_point_tilt" qualifiers="const">
@@ -8908,6 +8955,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+			Returns the tilt angle in radians for the point "idx". If the index is out of bounds, the function sends an error to the console, and returns 0.
 			</description>
 		</method>
 		<method name="set_point_in">
@@ -8916,6 +8964,7 @@
 			<argument index="1" name="pos" type="Vector3">
 			</argument>
 			<description>
+			Sets the position of the control point leading to the vertex "idx". If the index is out of bounds, the function sends an error to the console.
 			</description>
 		</method>
 		<method name="get_point_in" qualifiers="const">
@@ -8924,6 +8973,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+			Returns the position of the control point leading to the vertex "idx". If the index is out of bounds, the function sends an error to the console, and returns (0, 0, 0).
 			</description>
 		</method>
 		<method name="set_point_out">
@@ -8932,6 +8982,7 @@
 			<argument index="1" name="pos" type="Vector3">
 			</argument>
 			<description>
+			Sets the position of the control point leading out of the vertex "idx". If the index is out of bounds, the function sends an error to the console.
 			</description>
 		</method>
 		<method name="get_point_out" qualifiers="const">
@@ -8940,12 +8991,14 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+			Returns the position of the control point leading out of the vertex "idx". If the index is out of bounds, the function sends an error to the console, and returns (0, 0, 0).
 			</description>
 		</method>
 		<method name="remove_point">
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+			Deletes the point "idx" from the curve. Sends an error to the console if "idx" is out of bounds.
 			</description>
 		</method>
 		<method name="interpolate" qualifiers="const">
@@ -8956,6 +9009,8 @@
 			<argument index="1" name="t" type="float">
 			</argument>
 			<description>
+			Returns the position between the vertex "idx" and the vertex "idx"+1, where "t" controls if the point is the first vertex (t = 0.0), the last vertex (t = 1.0), or in between. Values of "t" outside the range (0.0 &gt;= t  &lt;=1) give strange, but predictable results.
+If "idx" is out of bounds it is truncated to the first or last vertex, and "t" is ignored. If the curve has no points, the function sends an error to the console, and returns (0, 0, 0).
 			</description>
 		</method>
 		<method name="interpolatef" qualifiers="const">
@@ -8964,24 +9019,28 @@
 			<argument index="0" name="fofs" type="float">
 			</argument>
 			<description>
+			Returns the position at the vertex "fofs". It calls [method interpolate] using the integer part of fofs as "idx", and its fractional part as "t".
 			</description>
 		</method>
 		<method name="set_bake_interval">
 			<argument index="0" name="distance" type="float">
 			</argument>
 			<description>
+			Sets the distance in 3D units between two adjacent cached points. Changing it forces the cache to be recomputed the next time a xxx_baked_xxx function is called. The less distance, the more points the cache will have, and the more memory it will consume, so use with care.
 			</description>
 		</method>
 		<method name="get_bake_interval" qualifiers="const">
 			<return type="float">
 			</return>
 			<description>
+			Returns the distance between two adjacent cached points.
 			</description>
 		</method>
 		<method name="get_baked_length" qualifiers="const">
 			<return type="float">
 			</return>
 			<description>
+			Returns the total length of the curve, based on the cached points. Given enough density (see [method set_bake_interval]), it should be approximate enough.
 			</description>
 		</method>
 		<method name="interpolate_baked" qualifiers="const">
@@ -8992,18 +9051,37 @@
 			<argument index="1" name="cubic" type="bool" default="false">
 			</argument>
 			<description>
+			Returns a point within the curve at position "offset", where "offset" is measured as a distance in 3D units along the curve.
+To do that, it finds the two cached points where the "offset" lies between, then interpolates the values. This interpolation is cubic if "cubic" is set to true, or linear if set to false.
+Cubic interpolation tends to follow the curves better, but linear is faster (and often, precise enough).
 			</description>
 		</method>
 		<method name="get_baked_points" qualifiers="const">
 			<return type="Vector3Array">
 			</return>
 			<description>
+			Returns the cache of points as a [Vector3Array].
 			</description>
 		</method>
 		<method name="get_baked_tilts" qualifiers="const">
 			<return type="RealArray">
 			</return>
 			<description>
+			Returns the cache of tilts as a [RealArray].
+			</description>
+		</method>
+		<method name="tesselate" qualifiers="const">
+			<argument index="0" name="max_stages" type="int" default="5">
+			</argument>
+			<argument index="1" name="tolerance_degrees" type="float" default="4">
+			</argument>
+			<return type="Vector3Array">
+			</return>
+			<description>
+			Returns a list of points along the curve, with a curvature controlled point density. That is, the curvier parts will have more points than the straighter parts.
+This approximation makes straight segments between each point, then subdivides those segments until the resulting shape is similar enough.
+"max_stages" controls how many subdivisions a curve segment may face before it is considered approximate enough. Each subdivision splits the segment in half, so the default 5 stages may mean up to 32 subdivisions per curve segment. Increase with care!
+"tolerance_degrees" controls how many degrees the midpoint of a segment may deviate from the real curve, before the segment has to be subdivided.
 			</description>
 		</method>
 		<method name="tesselate" qualifiers="const">
@@ -21229,20 +21307,24 @@
 </class>
 <class name="Path" inherits="Spatial" category="Core">
 	<brief_description>
+	Container for a [Curve3D].
 	</brief_description>
 	<description>
+	This class is a container/Node-ification of a [Curve3D], so it can have [Spatial] properties and [Node] info.
 	</description>
 	<methods>
 		<method name="set_curve">
 			<argument index="0" name="curve" type="Curve3D">
 			</argument>
 			<description>
+			Sets the [Curve3D].
 			</description>
 		</method>
 		<method name="get_curve" qualifiers="const">
 			<return type="Curve3D">
 			</return>
 			<description>
+			Returns the [Curve3D] contained.
 			</description>
 		</method>
 	</methods>
@@ -21251,20 +21333,24 @@
 </class>
 <class name="Path2D" inherits="Node2D" category="Core">
 	<brief_description>
+	Container for a [Curve2D].
 	</brief_description>
 	<description>
+	This class is a container/Node-ification of a [Curve2D], so it can have [Node2D] properties and [Node] info.
 	</description>
 	<methods>
 		<method name="set_curve">
 			<argument index="0" name="curve" type="Curve2D">
 			</argument>
 			<description>
+			Sets the [Curve2D].
 			</description>
 		</method>
 		<method name="get_curve" qualifiers="const">
 			<return type="Curve2D">
 			</return>
 			<description>
+			Returns the [Curve2D] contained.
 			</description>
 		</method>
 	</methods>
@@ -21273,197 +21359,245 @@
 </class>
 <class name="PathFollow" inherits="Spatial" category="Core">
 	<brief_description>
+	Point sampler for a [Path].
 	</brief_description>
 	<description>
+	This node takes its parent [Path], and returns the coordinates of a point within it, given a distance from the first vertex.
+It is useful for making other nodes follow a path, without coding the movement pattern. For that, the nodes must be descendants of this node. Then, when setting an offset in this node, the descendant nodes will move accordingly.
 	</description>
 	<methods>
 		<method name="set_offset">
 			<argument index="0" name="offset" type="float">
 			</argument>
 			<description>
+			Sets 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.
 			</description>
 		</method>
 		<method name="get_offset" qualifiers="const">
 			<return type="float">
 			</return>
 			<description>
+			Returns the distance along the path in 3D units.
 			</description>
 		</method>
 		<method name="set_h_offset">
 			<argument index="0" name="h_offset" type="float">
 			</argument>
 			<description>
+			Moves this node in the X axis. As this node's position will be set every time its offset is set, this allows many PathFollow to share the same curve (and thus the same movement pattern), yet not return the same position for a given path offset.
+A similar effect may be achieved moving the this node's descendants.
 			</description>
 		</method>
 		<method name="get_h_offset" qualifiers="const">
 			<return type="float">
 			</return>
 			<description>
+			Returns the X displacement this node has from its parent [Path].
 			</description>
 		</method>
 		<method name="set_v_offset">
 			<argument index="0" name="v_offset" type="float">
 			</argument>
 			<description>
+			Moves this node in the Y axis, for the same reasons of [method set_h_offset].
 			</description>
 		</method>
 		<method name="get_v_offset" qualifiers="const">
 			<return type="float">
 			</return>
 			<description>
+			Returns the Y displacement this node has from its parent [Path].
 			</description>
 		</method>
 		<method name="set_unit_offset">
 			<argument index="0" name="unit_offset" type="float">
 			</argument>
 			<description>
+			Sets 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.
 			</description>
 		</method>
 		<method name="get_unit_offset" qualifiers="const">
 			<return type="float">
 			</return>
 			<description>
+			Returns the distance along the path as a number in the range 0.0 (for the first vertex) to 1.0 (for the last).
 			</description>
 		</method>
 		<method name="set_rotation_mode">
 			<argument index="0" name="rotation_mode" type="int">
 			</argument>
 			<description>
+			Allows or forbids rotation on one or more axes, per the constants below.
 			</description>
 		</method>
 		<method name="get_rotation_mode" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
+			Returns the rotation mode. The constants below list which axes are allowed to rotate for each mode.
 			</description>
 		</method>
 		<method name="set_cubic_interpolation">
 			<argument index="0" name="enable" type="bool">
 			</argument>
 			<description>
+			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.
+This method controls whether the position between two cached points is interpolated linearly, or cubicly.
 			</description>
 		</method>
 		<method name="get_cubic_interpolation" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
+			This method returns whether the position between two cached points (see [method set_cubic_interpolation]) is interpolated linearly, or cubicly.
 			</description>
 		</method>
 		<method name="set_loop">
 			<argument index="0" name="loop" type="bool">
 			</argument>
 			<description>
+			If set, any offset outside the path's length (whether set by [method set_offset] or [method set_unit_offset] will wrap around, instead of stopping at the ends. Set it for cyclic paths.
 			</description>
 		</method>
 		<method name="has_loop" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
+			Returns whether this node wraps its offsets around, or truncates them to the path ends.
 			</description>
 		</method>
 	</methods>
 	<constants>
 		<constant name="ROTATION_NONE" value="0">
+		Forbids the PathFollow to rotate.
 		</constant>
 		<constant name="ROTATION_Y" value="1">
+		Allows the PathFollow to rotate in the Y axis only.
 		</constant>
 		<constant name="ROTATION_XY" value="2">
+		Allows the PathFollow to rotate in both the X, and Y axes.
 		</constant>
 		<constant name="ROTATION_XYZ" value="3">
+		Allows the PathFollow to rotate in any axis.
 		</constant>
 	</constants>
 </class>
 <class name="PathFollow2D" inherits="Node2D" category="Core">
 	<brief_description>
+	Point sampler for a [Path2D].
 	</brief_description>
 	<description>
+	This node takes its parent [Path2D], and returns the coordinates of a point within it, given a distance from the first vertex.
+It is useful for making other nodes follow a path, without coding the movement pattern. For that, the nodes must be descendants of this node. Then, when setting an offset in this node, the descendant nodes will move accordingly.
 	</description>
 	<methods>
 		<method name="set_offset">
 			<argument index="0" name="offset" type="float">
 			</argument>
 			<description>
+			Sets the distance from the first vertex, measured in pixels along the path. This sets this node's position to a point within the path.
 			</description>
 		</method>
 		<method name="get_offset" qualifiers="const">
 			<return type="float">
 			</return>
 			<description>
+			Returns the distance along the path in pixels.
 			</description>
 		</method>
 		<method name="set_h_offset">
 			<argument index="0" name="h_offset" type="float">
 			</argument>
 			<description>
+			Moves this node horizontally. As this node's position will be set every time its offset is set, this allows many PathFollow2D to share the same curve (and thus the same movement pattern), yet not return the same position for a given path offset.
+A similar effect may be achieved moving this node's descendants.
 			</description>
 		</method>
 		<method name="get_h_offset" qualifiers="const">
 			<return type="float">
 			</return>
 			<description>
+			Returns the horizontal displacement this node has from its parent [Path2D].
 			</description>
 		</method>
 		<method name="set_v_offset">
 			<argument index="0" name="v_offset" type="float">
 			</argument>
 			<description>
+			Moves the PathFollow2D vertically, for the same reasons of [method set_h_offset].
 			</description>
 		</method>
 		<method name="get_v_offset" qualifiers="const">
 			<return type="float">
 			</return>
 			<description>
+			Returns the vertical displacement this node has from its parent [Path2D].
 			</description>
 		</method>
 		<method name="set_unit_offset">
 			<argument index="0" name="unit_offset" type="float">
 			</argument>
 			<description>
+			Sets 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.
 			</description>
 		</method>
 		<method name="get_unit_offset" qualifiers="const">
 			<return type="float">
 			</return>
 			<description>
+			Returns the distance along the path as a number in the range 0.0 (for the first vertex) to 1.0 (for the last).
 			</description>
 		</method>
 		<method name="set_rotate">
 			<argument index="0" name="enable" type="bool">
 			</argument>
 			<description>
+			If set, this node rotates to follow the path, making its descendants rotate.
 			</description>
 		</method>
 		<method name="is_rotating" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
+			Returns whether this node rotates to follow the path.
 			</description>
 		</method>
 		<method name="set_cubic_interpolation">
 			<argument index="0" name="enable" type="bool">
 			</argument>
 			<description>
+			The points along the [Curve2D] of the [Path2D] 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.
+This method controls whether the position between two cached points is interpolated linearly, or cubicly.
 			</description>
 		</method>
 		<method name="get_cubic_interpolation" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
+			This method returns whether the position between two cached points (see [method set_cubic_interpolation]) is interpolated linearly, or cubicly.
 			</description>
 		</method>
 		<method name="set_loop">
 			<argument index="0" name="loop" type="bool">
 			</argument>
 			<description>
+			If set, any offset outside the path's length (whether set by [method set_offset] or [method set_unit_offset] will wrap around, instead of stopping at the ends. Set it for cyclic paths.
 			</description>
 		</method>
 		<method name="has_loop" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
+			Returns whether this node wraps its offsets around, or truncates them to the path ends.
 			</description>
 		</method>
 	</methods>
+	<members>
+		<member name="lookahead" type="float">
+		</member>
+	</members>
 	<constants>
 	</constants>
 </class>