Class Path Extends IPathInternals

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.

var path = seeker.StartPath(transform.position, transform.position + Vector3.forward * 10, OnPathComplete);
path.BlockUntilCalculated();

// The path is calculated now, and the OnPathComplete callback has been called


bool CanTraverse (

GraphNode

node

)

Returns if the node can be traversed.

This by default equals to if the node is walkable and if the node's tag is included in enabledTags.

bool CanTraverse (

GraphNode	from
GraphNode	to

)

Returns if the path can traverse a link between from and to and if to can be traversed itself.

This by default equals to if the to is walkable and if the to's tag is included in enabledTags.

void Claim (

System.Object

o

)

Increase the reference count on this path by 1 (for 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.

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 (

string

msg

)

Causes the path to fail and sets errorLog to msg.

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 (

GraphNode

node

)

Returns the cost of traversing the given node.

bool IsDone ()

True if this path is done calculating.

void OnVisitNode (

uint	pathNode
uint	hScore
uint	gScore

)

Called for every node that the path visits.

This is used by path types to check if the target node has been reached, to log debug data, etc.

void OpenCandidateConnection (

uint	parentPathNode	The node that is being opened.
uint	targetPathNode	A neighbour of the parent that is being considered.
uint	parentG	The G value of the parent node. This is the cost to reach the parent node from the start of the path.
uint	connectionCost	The cost of moving from the parent node to the target node.
uint	fractionAlongEdge	Internal value used by the TriangleMeshNode to store where on the shared edge between the nodes we say we cross over.
Int3	targetNodePosition	The position of the target node. This is used by the heuristic to estimate the cost to reach the end node.

)

Opens a connection between two nodes during the A* search.

When a node is "opened" (i.e. searched by the A* algorithm), it will open connections to all its neighbours. This function checks those connections to see if passing through the node to its neighbour is the best way to reach the neighbour that we have seen so far, and if so, it will push the neighbour onto the search heap.

void OpenCandidateConnectionsToEndNode (

Int3	position	Position of the path node that is being opened. This may be different from the node's position if PathNode.fractionAlongEdge is being used.
uint	parentPathNode	Index of the path node that is being opened. This is often the same as parentNodeIndex, but may be different if the node has multiple path node variants.
uint	parentNodeIndex	Index of the node that is being opened.
uint	parentG	G score of the parent node. The cost to reach the parent node from the start of the path.

)

Open a connection to the temporary end node if necessary.

The start and end nodes are temporary nodes and are not included in the graph itself. This means that we need to handle connections to and from those nodes as a special case. This function will open a connection from the given node to the end node, if such a connection exists.

It is called from the GraphNode.Open function.

void Release (

System.Object	o
bool	silent=false

)

Reduces the reference count on the path by 1 (pooling).

Removes the claim on the path by the specified object. When the reference 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 non-silent Release call 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.

bool ShouldConsiderPathNode (

uint

pathNodeIndex

)

True if this path node might be worth exploring.

This is used during a search to filter out nodes which have already been fully searched.

void SkipOverNode (

uint	pathNodeIndex
uint	parentNodeIndex
uint	fractionAlongEdge
uint	hScore
uint	gScore

)

Paths use this to skip adding nodes to the search heap.

This is used by triangle nodes if they find an edge which is identical (but reversed) to an edge in an adjacent node. This means that it cannot be better to visit the adjacent node's edge from any other way than what we are currently considering. Therefore, instead of adding the node to the heap, only to pop it in the next iteration, we can skip that step and save some processing time.

After calling this function, the skipped node should be immediately opened, so that it can be searched.

void UseSettings (

PathRequestSettings

settings

)

Copies the given settings into this path.

IEnumerator WaitForPath ()

Waits until this path has been calculated and returned.

Allows for very easy scripting.

IEnumerator Start () {
// Get the seeker component attached to this GameObject
var seeker = GetComponent<Seeker>();

var path = seeker.StartPath(transform.position, transform.position + Vector3.forward * 10, null);
// Wait... This may take a frame or two depending on how complex the path is
// The rest of the game will continue to run while we wait
yield return StartCoroutine(path.WaitForPath());
// The path is calculated now

// Draw the path in the scene view for 10 seconds
for (int i = 0; i < path.vectorPath.Count - 1; i++) {
Debug.DrawLine(path.vectorPath[i], path.vectorPath[i+1], Color.red, 10);
}
}


void OpenCandidateConnectionBurst (

refOpenCandidateParams	pars
refBinaryHeap	heap
refHeuristicObjective	heuristicObjective

)

Burst-compiled internal implementation of OpenCandidateConnection.

Compiling it using burst provides a decent 25% speedup. The function itself is much faster, but the overhead of calling it from C# is quite significant.

PathCompleteState CompleteState

Current state of the path.

PathState PipelineState

Returns the state of the path in the pathfinding pipeline.

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

float duration

How long it took to calculate this path in milliseconds.

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.

bool error

If the path failed, this is true.

This typically happens if there's no valid node close enough to the start point of the path, or if there's no node close enough to the target point that is reachable from the start point. The errorLog will have more information about what happened.

string errorLog

Additional info on why a path failed.

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

Constraint for how to search for nodes.

List<GraphNode> path

Holds the path as a GraphNode list.

These are all nodes that the path traversed, as calculated by the pathfinding algorithm. 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 get a penalty of tagPenalties[0]. These should only be non-negative values since the A* algorithm cannot handle negative penalties.

When assigning an array to this property it must have a length of 32.

ITraversalProvider traversalProvider

Provides additional traversal information to a path request.

List<Vector3> vectorPath

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

This list may be modified by path modifiers to be smoother or simpler compared to the raw path generated by the pathfinding algorithm.

Unity.Profiling.ProfilerMarker MarkerOpenCandidateConnectionsToEnd = new Unity.Profiling.ProfilerMarker("OpenCandidateConnectionsToEnd")

Unity.Profiling.ProfilerMarker MarkerTrace = new Unity.Profiling.ProfilerMarker("Trace")

void AddStartNodesToHeap ()

void IPathInternals. AdvanceState (

PathState

s

)

Threadsafe increment of the state.

void IPathInternals. CalculateStep (

long

targetTick

)

void CalculateStep (

long

targetTick

)

Calculates the path until completed or until the time has passed targetTick.

Usually a check is only done every 500 nodes if the time has passed targetTick. Time/Ticks are got from System.DateTime.UtcNow.Ticks.

Basic outline of what the function does for the standard path (Pathfinding.ABPath). while the end has not been found and no error has occurred
pop the next node of the heap and set it as current
check if we have reached the end
if so, exit and return the path

open the current node, i.e loop through its neighbours, mark them as visited and put them on a heap

check if there are still nodes left to process (or have we searched the whole graph)
if there are none, flag error and exit

check if the function has exceeded the time limit
if so, return and wait for the function to get called again


void IPathInternals. Cleanup ()

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 IPathInternals. DebugString (

PathLog

logMode

)

string DebugString (

PathLog

logMode

)

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 ErrorCheck ()

Performs some error checking.

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

Causes the path to fail if any errors are found.

int3 FirstTemporaryEndNode ()

NNInfo GetNearest (

Vector3

point

)

Closest point and node which is traversable by this path.

This takes both the NNConstraint and the ITraversalProvider into account.

void InitializeNNConstraint ()

void MarkNodesAdjacentToTemporaryEndNodes ()

void IPathInternals. OnEnterPool ()

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.

void OnFoundEndNode (

uint	pathNode
uint	hScore
uint	gScore

)

Called when a valid node has been found for the end of the path.

This function should trace the path back to the start node, and set CompleteState to Complete. If CompleteState is unchanged, the search will continue.

void OnHeapExhausted ()

Called when there are no more nodes to search.

This may be used to calculate a partial path as a fallback.

PathHandlerIPathInternals. PathHandler

bool IPathInternals. Pooled

True if the path is currently pooled.

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

void IPathInternals. Prepare ()

void Prepare ()

Called before the path is started.

Called right before Initialize

void IPathInternals. PrepareBase (

PathHandler

handler

)

void PrepareBase (

PathHandler

pathHandler

)

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 IPathInternals. Reset ()

void Reset ()

Reset all values to their default values.

void IPathInternals. ReturnPath ()

void ReturnPath ()

Calls callback to return the calculated path.

void TemporaryEndNodesBoundingBox (

out int3	mn
out int3	mx

)

void Trace (

uint

fromPathNodeIndex

)

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

int[] ZeroTagPenalties = new int[32]

List of zeroes to use as default tag penalties.

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

List of claims on this path with reference objects.

PathCompleteState completeState

Backing field for CompleteState.

GraphNode hTargetNode

Target to use for H score calculation.

bool hasBeenReset

True if the Reset function has been called.

Used to alert users when they are doing something wrong.

HeuristicObjective heuristicObjective

Target to use for H score calculations.

refHeuristicObjective heuristicObjectiveInternal

int[] internalTagPenalties

The tag penalties that are actually used.

PathHandler pathHandler

Data for the thread calculating this path.

bool releasedNotSilent

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