Class FloodPath
Extends
Path
Public
Calculates paths from everywhere to a single point.
This path is a bit special, because it does not do anything useful by itself. What it does is that it calculates paths to all nodes it can reach, it floods the graph. This data will remain stored in the path. Then you can calculate a FloodPathTracer path. That path will trace the path from its starting point all the way to where this path started. A FloodPathTracer search is extremely fast to calculate compared to a normal path request.
It is very useful in for example tower defence games, where all your AIs will walk to the same point but from different places, and you do not update the graph or change the target point very often.
Usage:
At start, you calculate ONE FloodPath and save the reference (it will be needed later).
Then when a unit is spawned or needs its path recalculated, start a FloodPathTracer path from the unit's position. It will then find the shortest path to the point specified when you calculated the FloodPath extremely quickly.
If you update the graph (for example place a tower in a TD game) or need to change the target point, you calculate a new FloodPath and make all AIs calculate new FloodPathTracer paths.
Note
Since a FloodPathTracer path only uses precalculated information, it will always use the same penalties/tags as the FloodPath it references. If you want to use different penalties/tags, you will have to calculate a new FloodPath.
Here follows some example code of the above list of steps: public static FloodPath fpath;
public void Start () {
fpath = FloodPath.Construct (someTargetPosition, null);
AstarPath.StartPath (fpath);
}
When searching for a new path to someTargetPosition from let's say transform.position, you do FloodPathTracer fpathTrace = FloodPathTracer.Construct (transform.position,fpath,null);
seeker.StartPath (fpathTrace,OnPathComplete);
Where OnPathComplete is your callback function.
Another thing to note is that if you are using an NNConstraint on the FloodPathTracer, they must always inherit from FloodPathConstraint.
The easiest is to just modify the instance of FloodPathConstraint which is created as the default one.
Integration with the built-in movement scripts
The built-in movement scripts cannot calculate a FloodPathTracer path themselves, but you can use the SetPath method to assign such a path to them: var ai = GetComponent<IAstarAI>();
// Disable the agent's own path recalculation code
ai.canSearch = false;
ai.SetPath(FloodPathTracer.Construct(ai.position, floodPath));
A* Pro Feature:
This is an A* Pathfinding Project Pro feature only. This function/class/variable might not exist in the Free version of the A* Pathfinding Project or the functionality might be limited.
The Pro version can be bought here
Public Methods
FloodPath
()
Default constructor.
Do not use this. Instead use the static Construct method which can handle path pooling.
Public Static Methods
Public Variables
bool
saveParents = true
If false, will not save any information.
Used by some internal parts of the system which doesn't need it.
Inherited Public Members
void
BlockUntilCalculated
()
Blocks until this path has been calculated and returned.
Normally it takes a few frames for a path to be calculated and returned. This function will ensure that the path will be calculated when this function returns and that the callback for that path has been called.
Use this function only if you really need to. There is a point to spreading path calculations out over several frames. It smoothes out the framerate and makes sure requesting a large number of paths at the same time does not cause lag.
Note
Graph updates and other callbacks might get called during the execution of this function.
Path p = seeker.StartPath (transform.position, transform.position + Vector3.forward * 10);
p.BlockUntilCalculated();
// The path is calculated now
bool
CanTraverse
(
)
Returns if the node can be traversed.
This per default equals to if the node is walkable and if the node's tag is included in enabledTags
void
Claim
(
)
Claim this path (pooling).
A claim on a path will ensure that it is not pooled. If you are using a path, you will want to claim it when you first get it and then release it when you will not use it anymore. When there are no claims on the path, it will be reset and put in a pool.
This is essentially just reference counting.
The object passed to this method is merely used as a way to more easily detect when pooling is not done correctly. It can be any object, when used from a movement script you can just pass "this". This class will throw an exception if you try to call Claim on the same path twice with the same object (which is usually not what you want) or if you try to call Release with an object that has not been used in a Claim call for that path. The object passed to the Claim method needs to be the same as the one you pass to this method.
Current state of the path.
void
Error
()
Aborts the path because of an error.
Sets error to true. This function is called when an error has occurred (e.g a valid path could not be found).
void
FailWithError
(
)
Causes the path to fail and sets errorLog to msg.
bool
FloodingPath
True for paths that want to search all nodes and not jump over nodes as optimizations.
This disables Jump Point Search when that is enabled to prevent e.g ConstantPath and FloodPath to become completely useless.
uint
GetConnectionSpecialCost
(
GraphNode | a | Moving from this node |
GraphNode | b | Moving to this node |
uint | currentCost | The cost of moving between the nodes. Return this value if there is no meaningful special cost to return. |
)
May be called by graph nodes to get a special cost for some connections.
Nodes may call it when PathNode.flag2 is set to true, for example mesh nodes, which have a very large area can be marked on the start and end nodes, this method will be called to get the actual cost for moving from the start position to its neighbours instead of as would otherwise be the case, from the start node's position to its neighbours. The position of a node and the actual start point on the node can vary quite a lot.
The default behaviour of this method is to return the previous cost of the connection, essentiall making no change at all.
This method should return the same regardless of the order of a and b. That is f(a,b) == f(b,a) should hold.
uint
GetTagPenalty
(
int | tag | A value between 0 (inclusive) and 32 (exclusive). |
)
Returns penalty for the given tag.
float
GetTotalLength
()
Total Length of the path.
Calculates the total length of the vectorPath. Cache this rather than call this function every time since it will calculate the length every time, not just return a cached value.
uint
GetTraversalCost
(
)
Returns the cost of traversing the given node.
bool
IsDone
()
True if this path is done calculating.
Note
The callback for the path might not have been called yet.
See
Seeker.IsDone which also takes into account if the path callback has been called and had Modifiers applied.
Returns the state of the path in the pathfinding pipeline.
void
Release
(
System.Object | o | |
bool | silent=false | |
)
Releases a path claim (pooling).
Removes the claim of the path by the specified object. When the claim count reaches zero, the path will be pooled, all variables will be cleared and the path will be put in a pool to be used again. This is great for performance since fewer allocations are made.
If the silent parameter is true, this method will remove the claim by the specified object but the path will not be pooled if the claim count reches zero unless a Release call (not silent) has been made earlier. This is used by the internal pathfinding components such as Seeker and AstarPath so that they will not cause paths to be pooled. This enables users to skip the claim/release calls if they want without the path being pooled by the Seeker or AstarPath and thus causing strange bugs.
IEnumerator
WaitForPath
()
Waits until this path has been calculated and returned.
Allows for very easy scripting. IEnumerator Start () {
var path = seeker.StartPath(transform.position, transform.position + transform.forward*10, null);
yield return StartCoroutine(path.WaitForPath());
// The path is calculated now
}
Callback to call when the path is complete.
This is usually sent to the Seeker component which post processes the path and then calls a callback to the script which requested the path
float
duration
How long it took to calculate this path in milliseconds.
bool
error
If the path failed, this is true.
See
errorLog
This is equivalent to checking path.CompleteState == PathCompleteState.Error
string
errorLog
Additional info on why a path failed.
Determines which heuristic to use.
float
heuristicScale = 1F
Scale of the heuristic values.
Constraint for how to search for nodes.
Holds the path as a Node array.
All nodes the path traverses. This may not be the same nodes as the post processed path traverses.
ushort
pathID
ID of this path.
Used to distinguish between different paths
int
searchedNodes
Number of nodes this path has searched.
int[]
tagPenalties
Penalties for each tag.
Tag 0 which is the default tag, will have added a penalty of tagPenalties[0]. These should only be positive values since the A* algorithm cannot handle negative penalties.
When assigning an array to this property it must have a length of 32.
Note
Setting this to null, or trying to assign an array which does not have a length of 32, will make all tag penalties be treated as if they are zero.
If you are using a Seeker. The Seeker will set this value to what is set in the inspector field when you call seeker.StartPath. So you need to change the Seeker's value via script, not set this value.
Provides additional traversal information to a path request.
List<Vector3>
vectorPath
Holds the (possibly post processed) path as a Vector3 list.
Private/Protected Members
uint
CalculateHScore
(
)
Estimated cost from the specified node to the target.
void
CalculateStep
(
)
Opens nodes until there are none left to search (or until the max time limit has been exceeded)
void
Cleanup
()
Always called after the path has been calculated.
Guaranteed to be called before other paths have been calculated on the same thread. Use for cleaning up things like node tagging and similar.
string
DebugString
(
)
Returns a string with information about it.
More information is emitted when logMode == Heavy. An empty string is returned if logMode == None or logMode == OnlyErrors and this path did not fail.
void
DebugStringPrefix
(
PathLog | logMode | |
System.Text.StringBuilder | text | |
)
Writes text shared for all overrides of DebugString to the string builder.
void
DebugStringSuffix
(
PathLog | logMode | |
System.Text.StringBuilder | text | |
)
Writes text shared for all overrides of DebugString to the string builder.
void
Initialize
()
Initializes the path.
Sets up the open list and adds the first node to it
void
OnEnterPool
()
Called when the path enters the pool.
This method should release e.g pooled lists and other pooled resources The base version of this method releases vectorPath and path lists. Reset() will be called after this function, not before.
Warning
Do not call this function manually.
void
Prepare
()
Called before the path is started.
Called right before Initialize
void
PrepareBase
(
)
Prepares low level path variables for calculation.
Called before a path search will take place. Always called before the Prepare, Initialize and CalculateStep functions
void
Reset
()
Reset all values to their default values.
Note
All inheriting path types (e.g ConstantPath, RandomPath, etc.) which declare their own variables need to override this function, resetting ALL their variables to enable pooling of paths. If this is not done, trying to use that path type for pooling could result in weird behaviour. The best way is to reset to default values the variables declared in the extended path type and then call the base function in inheriting types with base.Reset().
void
ReturnPath
()
Calls callback to return the calculated path.
void
Trace
(
)
Traces the calculated path from the end node to the start.
This will build an array (path) of the nodes this path will pass through and also set the vectorPath array to the path arrays positions. Assumes the vectorPath and path are empty and not null (which will be the case for a correctly initialized path).
The node currently being processed.
Target to use for H score calculations.
Target to use for H score calculation.
Used alongside hTarget.
bool
hasBeenReset
True if the Reset function has been called.
Used to alert users when they are doing something wrong.
int[]
internalTagPenalties
The tag penalties that are actually used.
If manualTagPenalties is null, this will be ZeroTagPenalties
int[]
manualTagPenalties
Tag penalties set by other scripts.
Internal linked list implementation.
Warning
This is used internally by the system. You should never change this.
Data for the thread calculating this path.