From 69017974beb16dcfa971f9b6f33a4f005be57bef Mon Sep 17 00:00:00 2001 From: Franco Falleti Date: Tue, 12 Sep 2017 10:02:57 -0300 Subject: Document AStar (#11056) Add code examples --- doc/base/classes.xml | 71 ++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 58 insertions(+), 13 deletions(-) diff --git a/doc/base/classes.xml b/doc/base/classes.xml index 323ec8106d..a8e877ccd5 100644 --- a/doc/base/classes.xml +++ b/doc/base/classes.xml @@ -2881,6 +2881,7 @@ + Called when computing the cost between two connected points. @@ -2891,6 +2892,7 @@ + Called when estimating the cost between a point and the path's ending point. @@ -2903,7 +2905,12 @@ - Add a new point at the given position [code]pos[/code] with the given identifier [code]id[/code]. The [code]weight_scale[/code] has to be 1 or larger. + Adds a new point at the given position with the given identifier. The algorithm prefers points with lower [code]weight_scale[/code] to form a path. The [code]id[/code] must be 0 or larger, and the [code]weight_scale[/code] must be 1 or larger. + [codeblock] + var as = AStar.new() + + as.add_point(1, Vector3(1,0,0), 4) # Adds the point (1,0,0) with weight_scale=4 and id=1 + [/codeblock] @@ -2914,14 +2921,14 @@ - Returns if there is a connection/segment between points [code]id[/code] and [code]from_id[/code] + Returns whether there is a connection/segment between the given points. - Clear all the points and segments from AStar instance. + Clears all the points and segments. @@ -2934,7 +2941,16 @@ - Create a segment between points [code]id[/code] and [code]to_id[/code]. + Creates a segment between the given points. + [codeblock] + var as = AStar.new() + + as.add_point(1, Vector3(1,1,0)) + as.add_point(2, Vector3(0,5,0)) + + as.connect_points(1, 2, false) # If bidirectional=false it's only possible to go from point 1 to point 2 + # and not from point 2 to point 1. + [/codeblock] @@ -2945,13 +2961,14 @@ - Deletes a segment between points [code]id[/code] and [code]to_id[/code]. + Deletes the segment between the given points. + Returns an id with no point associated to it. @@ -2960,7 +2977,7 @@ - Returns the id of closest point of given point. -1 is returned if there are no points on AStar. + Returns the id of the closest point to [code]to_pos[/code]. Returns -1 if there are no points in the points pool. @@ -2969,7 +2986,18 @@ - Returns the position of closest point that has segments. + Returns the closest position to [code]to_pos[/code] that resides inside a segment between two connected points. + [codeblock] + var as = AStar.new() + + as.add_point(1, Vector3(0,0,0)) + as.add_point(2, Vector3(0,5,0)) + + as.connect_points(1, 2) + + var res = as.get_closest_pos_in_segment(Vector3(3,3,0)) # returns (0, 3, 0) + [/codeblock] + The result is in the segment that goes from [code]y=0[/code] to [code]y=5[/code]. It's the closest position in the segment to the given point. @@ -2980,7 +3008,24 @@ - Returns an array with the point ids of path found by AStar between two given points. + Returns an array with the ids of the points that form the path found by AStar between the given points. The array is ordered from the starting point to the ending point of the path. + [codeblock] + var as = AStar.new() + + as.add_point(1, Vector3(0,0,0)) + as.add_point(2, Vector3(0,1,0), 1) # default weight is 1 + as.add_point(3, Vector3(1,1,0)) + as.add_point(4, Vector3(2,0,0)) + + as.connect_points(1, 2, false) + as.connect_points(2, 3, false) + as.connect_points(4, 3, false) + as.connect_points(1, 4, false) + as.connect_points(5, 4, false) + + var res = as.get_id_path(1, 3) # returns [1, 2, 3] + [/codeblock] + If you change the 2nd point's weight to 3, then the result will be [code][1, 4, 3][/code] instead, because now even though the distance is longer, it's "easier" to get through point 4 than through point 2. @@ -2991,7 +3036,7 @@ - Returns an array with the points of path found by AStar between two given points. + Returns an array with the points that are in the path found by AStar between the given points. The array is ordered from the starting point to the ending point of the path. @@ -3000,7 +3045,7 @@ - Returns the position of point with given id. + Returns the position of the point associated with the given id. @@ -3009,7 +3054,7 @@ - Returns the weight scale of point with given id. + Returns the weight scale of the point associated with the given id. @@ -3018,7 +3063,7 @@ - Returns if the point with given id exists on AStar; + Returns whether a point associated with the given id exists. @@ -3027,7 +3072,7 @@ - Removes the point with given id. + Removes the point associated with the given id from the points pool. -- cgit v1.2.3