A* Pathfinding Project  3.8.9
The A* Pathfinding Project for Unity 3D
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Properties Events Macros Groups Pages
Path Class Referenceabstract

Base class for all path types. More...

Detailed Description

Base class for all path types.

Public Member Functions

void AdvanceState (PathState s)
 Threadsafe increment of the state.
 
uint CalculateHScore (GraphNode node)
 Estimated cost from the specified node to the target.
 
abstract void CalculateStep (long targetTick)
 Calculates the until it is complete or the time has progressed past targetTick.
 
bool CanTraverse (GraphNode node)
 Returns if the node can be traversed.
 
void Claim (System.Object o)
 Claim this path (pooling).
 
virtual void Cleanup ()
 Always called after the path has been calculated.
 
virtual string DebugString (PathLog logMode)
 Returns a string with information about it.
 
void Error ()
 Aborts the path because of an error.
 
void ForceLogError (string msg)
 Logs an error and calls Error().
 
virtual uint GetConnectionSpecialCost (GraphNode a, GraphNode b, uint currentCost)
 May be called by graph nodes to get a special cost for some connections.
 
Int3 GetHTarget ()
 
PathState GetState ()
 Returns the state of the path in the pathfinding pipeline.
 
uint GetTagPenalty (int tag)
 Returns penalty for the given tag.
 
float GetTotalLength ()
 Total Length of the path.
 
uint GetTraversalCost (GraphNode node)
 
abstract void Initialize ()
 Initializes the path.
 
bool IsDone ()
 Returns if this path is done calculating.
 
void Log (string msg)
 Appends a message to the errorLog.
 
void LogError (string msg)
 Appends msg to errorLog and logs msg to the console.
 
virtual void OnEnterPool ()
 Called when the path enters the pool.
 
abstract void Prepare ()
 Called before the path is started.
 
void Release (System.Object o, bool silent=false)
 Releases a path claim (pooling).
 
void ReleaseSilent (System.Object o)
 Releases the path silently (pooling).
 
virtual void Reset ()
 Reset all values to their default values.
 
virtual void ReturnPath ()
 Calls callback to return the calculated path.
 
IEnumerator WaitForPath ()
 Waits until this path has been calculated and returned.
 

Public Attributes

OnPathDelegate callback
 Callback to call when the path is complete.
 
float duration
 The duration of this path in ms.
 
int enabledTags = -1
 Which graph tags are traversable.
 
Heuristic heuristic
 Determines which heuristic to use.
 
float heuristicScale = 1F
 Scale of the heuristic values.
 
OnPathDelegate immediateCallback
 Immediate callback to call when the path is complete.
 
NNConstraint nnConstraint = PathNNConstraint.Default
 Constraint for how to search for nodes.
 
List< GraphNodepath
 Holds the path as a Node array.
 
int searchedNodes
 Number of nodes this path has searched.
 
int searchIterations
 The number of frames/iterations this path has executed.
 
List< Vector3 > vectorPath
 Holds the (perhaps post processed) path as a Vector3 list.
 

Protected Member Functions

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.
 
bool HasExceededTime (int searchedNodes, long targetTime)
 
virtual void Trace (PathNode from)
 Traces the calculated path from the end node to the start.
 

Protected Attributes

PathNode currentR
 The node currently being processed.
 
bool hasBeenReset
 True if the Reset function has been called.
 
Int3 hTarget
 Target to use for H score calculations.
 
GraphNode hTargetNode
 Target to use for H score calculation.
 
int[] internalTagPenalties
 The tag penalties that are actually used.
 
int[] manualTagPenalties
 Tag penalties set by other scripts.
 
float maxFrameTime
 The max number of milliseconds per iteration (frame, in case of non-multithreading)
 

Package Functions

void PrepareBase (PathHandler pathHandler)
 Prepares low level path variables for calculation.
 

Package Attributes

Path next
 Internal linked list implementation.
 
bool pooled
 True if the path is currently pooled.
 

Properties

System.DateTime callTime [get, set]
 When the call was made to start the pathfinding for this path.
 
PathCompleteState CompleteState [get, set]
 Current state of the path.
 
bool error [get]
 If the path failed, this is true.
 
string errorLog [get]
 Log messages with info about eventual errors.
 
virtual bool FloodingPath [get]
 True for paths that want to search all nodes and not jump over nodes as optimizations.
 
PathHandler pathHandler [get, set]
 Data for the thread calculating this path.
 
ushort pathID [get, set]
 ID of this path.
 
bool recycled [get, set]
 True if the path is currently recycled (i.e in the path pool).
 
int[] tagPenalties [get, set]
 Penalties for each tag.
 

Private Member Functions

void ErrorCheck ()
 Does some error checking.
 

Private Attributes

string _errorLog = ""
 Additional info on what went wrong.
 
List< System.Object > claimed = new List<System.Object>()
 List of claims on this path with reference objects.
 
PathCompleteState pathCompleteState
 Current state of the path.
 
bool releasedNotSilent
 True if the path has been released with a non-silent call yet.
 
PathState state
 
System.Object stateLock = new object()
 

Static Private Attributes

static readonly int[] ZeroTagPenalties = new int[32]
 List of zeroes to use as default tag penalties.
 

Member Function Documentation

void AdvanceState ( PathState  s)

Threadsafe increment of the state.

uint CalculateHScore ( GraphNode  node)

Estimated cost from the specified node to the target.

See Also
https://en.wikipedia.org/wiki/A*_search_algorithm
abstract void CalculateStep ( long  targetTick)
pure virtual

Calculates the until it is complete or the time has progressed past targetTick.

Implemented in MultiTargetPath, ABPath, RandomPath, FloodPath, ConstantPath, FloodPathTracer, and XPath.

bool CanTraverse ( GraphNode  node)

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 ( System.Object  o)

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.

See Also
Release
Pool
Pooling
virtual void Cleanup ( )
virtual

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.

Reimplemented in MultiTargetPath, ABPath, and ConstantPath.

virtual string DebugString ( PathLog  logMode)
virtual

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.

Reimplemented in MultiTargetPath, and ABPath.

void DebugStringPrefix ( PathLog  logMode,
System.Text.StringBuilder  text 
)
protected

Writes text shared for all overrides of DebugString to the string builder.

See Also
DebugString
void DebugStringSuffix ( PathLog  logMode,
System.Text.StringBuilder  text 
)
protected

Writes text shared for all overrides of DebugString to the string builder.

See Also
DebugString
void Error ( )

Aborts the path because of an error.

Sets error to true. This function is called when an error has ocurred (e.g a valid path could not be found).

See Also
LogError
void ErrorCheck ( )
private

Does some error checking.

Makes sure the user isn't using old code paths and that no major errors have been done.

Exceptions
Anexception if any errors are found
void ForceLogError ( string  msg)

Logs an error and calls Error().

This is called only if something is very wrong or the user is doing something he/she really should not be doing.

virtual uint GetConnectionSpecialCost ( GraphNode  a,
GraphNode  b,
uint  currentCost 
)
virtual

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.

Parameters
aMoving from this node
bMoving to this node
currentCostThe cost of moving between the nodes. Return this value if there is no meaningful special cost to return.

Reimplemented in ABPath.

Int3 GetHTarget ( )
PathState GetState ( )

Returns the state of the path in the pathfinding pipeline.

uint GetTagPenalty ( int  tag)

Returns penalty for the given tag.

Parameters
tagA value between 0 (inclusive) and 32 (exclusive).
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.

Returns
Total length of vectorPath, if vectorPath is null positive infinity is returned.
uint GetTraversalCost ( GraphNode  node)
bool HasExceededTime ( int  searchedNodes,
long  targetTime 
)
protected
abstract void Initialize ( )
pure virtual

Initializes the path.

Sets up the open list and adds the first node to it

Implemented in MultiTargetPath, ABPath, RandomPath, FloodPath, ConstantPath, and FloodPathTracer.

bool IsDone ( )

Returns if this path is done calculating.

Returns
If CompleteState is not PathCompleteState.NotCalculated.
Note
The path might not have been returned yet.
Since
Added in 3.0.8
See Also
Seeker.IsDone
void Log ( string  msg)

Appends a message to the errorLog.

Nothing is logged to the console.

Note
If AstarPath.logPathResults is PathLog.None and this is a standalone player, nothing will be logged as an optimization.
void LogError ( string  msg)

Appends msg to errorLog and logs msg to the console.

Debug.Log call is only made if AstarPath.logPathResults is not equal to None and not equal to InGame. Consider calling Error() along with this call.

virtual void OnEnterPool ( )
virtual

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.

Reimplemented in MultiTargetPath, and ConstantPath.

abstract void Prepare ( )
pure virtual

Called before the path is started.

Called right before Initialize

Implemented in MultiTargetPath, ABPath, RandomPath, FloodPath, and ConstantPath.

void PrepareBase ( PathHandler  pathHandler)
package

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 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 memory since less 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.

See Also
Claim
PathPool
void ReleaseSilent ( System.Object  o)

Releases the path silently (pooling).

Deprecated:
Use Release(o, true) instead
virtual void Reset ( )
virtual

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 recycling of paths. If this is not done, trying to use that path type for pooling might result in weird behaviour. The best way is to reset to default values the variables declared in the extended path type and then call this base function in inheriting types with base.Reset ().
Warning
This function should not be called manually.

Reimplemented in ABPath, FloodPath, ConstantPath, RandomPath, FloodPathTracer, and XPath.

virtual void ReturnPath ( )
virtual

Calls callback to return the calculated path.

See Also
callback

Reimplemented in MultiTargetPath, and RandomPath.

virtual void Trace ( PathNode  from)
protectedvirtual

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).

Reimplemented in MultiTargetPath.

IEnumerator WaitForPath ( )

Waits until this path has been calculated and returned.

Allows for very easy scripting.

//In an IEnumerator function
Path p = Seeker.StartPath (transform.position, transform.position + Vector3.forward * 10);
yield return StartCoroutine (p.WaitForPath ());
//The path is calculated at this stage
Note
Do not confuse this with AstarPath.WaitForPath. This one will wait using yield until it has been calculated while AstarPath.WaitForPath will halt all operations until the path has been calculated.
Exceptions
System.InvalidOperationExceptionif the path is not started. Send the path to Seeker.StartPath or AstarPath.StartPath before calling this function.
See Also
AstarPath.WaitForPath

Member Data Documentation

string _errorLog = ""
private

Additional info on what went wrong.

See Also
error
OnPathDelegate callback

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

List<System.Object> claimed = new List<System.Object>()
private

List of claims on this path with reference objects.

PathNode currentR
protected

The node currently being processed.

float duration

The duration of this path in ms.

How long it took to calculate the path

int enabledTags = -1

Which graph tags are traversable.

This is a bitmask so -1 = all bits set = all tags traversable. For example, to set bit 5 to true, you would do

myPath.enabledTags |= 1 << 5;

To set it to false, you would do

myPath.enabledTags &= ~(1 << 5);

The Seeker has a popup field where you can set which tags to use.

Note
If you are using a Seeker. The Seeker will set this value to what is set in the inspector field on StartPath. So you need to change the Seeker value via script, not set this value if you want to change it via script.
See Also
CanTraverse
bool hasBeenReset
protected

True if the Reset function has been called.

Used to alert users when they are doing something wrong.

Heuristic heuristic

Determines which heuristic to use.

float heuristicScale = 1F

Scale of the heuristic values.

Int3 hTarget
protected

Target to use for H score calculations.

See Also
Pathfinding.Node.H
GraphNode hTargetNode
protected

Target to use for H score calculation.

Used alongside hTarget.

OnPathDelegate immediateCallback

Immediate callback to call when the path is complete.

Warning
This may be called from a separate thread. Usually you do not want to use this one.
See Also
callback
int [] internalTagPenalties
protected

The tag penalties that are actually used.

If manualTagPenalties is null, this will be ZeroTagPenalties

See Also
tagPenalties
int [] manualTagPenalties
protected

Tag penalties set by other scripts.

See Also
tagPenalties
float maxFrameTime
protected

The max number of milliseconds per iteration (frame, in case of non-multithreading)

Path next
package

Internal linked list implementation.

Warning
This is used internally by the system. You should never change this.

Constraint for how to search for nodes.

List<GraphNode> path

Holds the path as a Node array.

All nodes the path traverses. This might not be the same as all nodes the smoothed path traverses.

PathCompleteState pathCompleteState
private

Current state of the path.

See Also
CompleteState
bool pooled
package

True if the path is currently pooled.

Do not set this value. Only read. It is used internally.

See Also
PathPool
Version
Was named 'recycled' in 3.7.5 and earlier.
bool releasedNotSilent
private

True if the path has been released with a non-silent call yet.

See Also
Release
Claim
int searchedNodes

Number of nodes this path has searched.

int searchIterations

The number of frames/iterations this path has executed.

This is the number of frames when not using multithreading. When using multithreading, this value is quite irrelevant

PathState state
private
System.Object stateLock = new object()
private
List<Vector3> vectorPath

Holds the (perhaps post processed) path as a Vector3 list.

readonly int [] ZeroTagPenalties = new int[32]
staticprivate

List of zeroes to use as default tag penalties.

Property Documentation

System.DateTime callTime
getset

When the call was made to start the pathfinding for this path.

PathCompleteState CompleteState
getset

Current state of the path.

bool error
get

If the path failed, this is true.

See Also
errorLog
string errorLog
get

Log messages with info about eventual errors.

virtual bool FloodingPath
get

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.

PathHandler pathHandler
getset

Data for the thread calculating this path.

ushort pathID
getset

ID of this path.

Used to distinguish between different paths

bool recycled
getsetpackage

True if the path is currently recycled (i.e in the path pool).

Do not set this value. Only read. It is used internally.

Deprecated:
Has been renamed to 'pooled' to use more widely underestood terminology
int [] tagPenalties
getset

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.

Note
This array will never be null. If you try to set it to null or with a lenght which is not 32. It will be set to "new int[0]".
If you are using a Seeker. The Seeker will set this value to what is set in the inspector field on StartPath. So you need to change the Seeker value via script, not set this value if you want to change it via script.
See Also
Seeker.tagPenalties

The documentation for this class was generated from the following file: