A* Pathfinding Project  4.2.4
The A* Pathfinding Project for Unity 3D
GraphUpdateObject Class Reference

Represents a collection of settings used to update nodes in a specific region of a graph. More...

Detailed Description

Represents a collection of settings used to update nodes in a specific region of a graph.

See also
AstarPath.UpdateGraphs
Graph Updates during Runtime

Public Member Functions

 GraphUpdateObject ()
 
 GraphUpdateObject (Bounds b)
 Creates a new GUO with the specified bounds. More...
 
virtual void Apply (GraphNode node)
 Updates the specified node using this GUO's settings. More...
 
virtual void RevertFromBackup ()
 Reverts penalties and flags (which includes walkability) on every node which was updated using this GUO. More...
 
virtual void WillUpdateNode (GraphNode node)
 Should be called on every node which is updated with this GUO before it is updated. More...
 

Public Attributes

int addPenalty
 Penalty to add to the nodes. More...
 
Bounds bounds
 The bounds to update nodes within. More...
 
List< GraphNodechangedNodes
 Nodes which were updated by this GraphUpdateObject. More...
 
bool modifyTag
 If true, all nodes' tag will be set to setTag. More...
 
bool modifyWalkability
 If true, all nodes' walkable variable will be set to setWalkability. More...
 
NNConstraint nnConstraint = NNConstraint.None
 NNConstraint to use. More...
 
bool resetPenaltyOnPhysics = true
 Reset penalties to their initial values when updating grid graphs and updatePhysics is true. More...
 
int setTag
 If modifyTag is true, all nodes' tag will be set to this value. More...
 
bool setWalkability
 If modifyWalkability is true, the nodes' walkable variable will be set to this value. More...
 
GraphUpdateShape shape
 A shape can be specified if a bounds object does not give enough precision. More...
 
bool trackChangedNodes
 Track which nodes are changed and save backup data. More...
 
bool updateErosion = true
 Update Erosion for GridGraphs. More...
 
bool updatePhysics = true
 Use physics checks to update nodes. More...
 

Properties

bool requiresFloodFill [set]
 Controlls if a flood fill will be carried out after this GUO has been applied. More...
 

Private Attributes

List< uint > backupData
 
List< Int3backupPositionData
 

Constructor & Destructor Documentation

◆ GraphUpdateObject() [1/2]

◆ GraphUpdateObject() [2/2]

GraphUpdateObject ( Bounds  b)

Creates a new GUO with the specified bounds.

Member Function Documentation

◆ Apply()

virtual void Apply ( GraphNode  node)
virtual

Updates the specified node using this GUO's settings.

◆ RevertFromBackup()

virtual void RevertFromBackup ( )
virtual

Reverts penalties and flags (which includes walkability) on every node which was updated using this GUO.

Data for reversion is only saved if trackChangedNodes is true.

Note
Not all data is saved. The saved data includes: penalties, walkability, tags, area, position and for grid graphs (not layered) it also includes connection data.

This method modifies the graph. So it must be called inside while it is safe to modify the graph, for example inside a work item as shown in the example below.

MiscSnippets.cs GraphUpdateObject.RevertFromBackup

See also
Check for blocking placements
#Pathfinding.PathUtilities.UpdateGraphsNoBlock

◆ WillUpdateNode()

virtual void WillUpdateNode ( GraphNode  node)
virtual

Should be called on every node which is updated with this GUO before it is updated.

Parameters
nodeThe node to save fields for. If null, nothing will be done
See also
trackChangedNodes

Member Data Documentation

◆ addPenalty

int addPenalty

Penalty to add to the nodes.

A penalty of 1000 is equivalent to the cost of moving 1 world unit.

◆ backupData

List<uint> backupData
private

◆ backupPositionData

List<Int3> backupPositionData
private

◆ bounds

Bounds bounds

The bounds to update nodes within.

Defined in world space.

◆ changedNodes

List<GraphNode> changedNodes

Nodes which were updated by this GraphUpdateObject.

Will only be filled if trackChangedNodes is true.

Note
It might take a few frames for graph update objects to be applied. If you need this info immediately, use AstarPath.FlushGraphUpdates.

◆ modifyTag

bool modifyTag

If true, all nodes' tag will be set to setTag.

◆ modifyWalkability

bool modifyWalkability

If true, all nodes' walkable variable will be set to setWalkability.

◆ nnConstraint

NNConstraint to use.

The Pathfinding.NNConstraint.SuitableGraph function will be called on the NNConstraint to enable filtering of which graphs to update.

Note
As the Pathfinding.NNConstraint.SuitableGraph function is A* Pathfinding Project Pro only, this variable doesn't really affect anything in the free version.

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

◆ resetPenaltyOnPhysics

bool resetPenaltyOnPhysics = true

Reset penalties to their initial values when updating grid graphs and updatePhysics is true.

If you want to keep old penalties even when you update the graph you may want to disable this option.

The images below shows two overlapping graph update objects, the right one happened to be applied before the left one. They both have updatePhysics = true and are set to increase the penalty of the nodes by some amount.

The first image shows the result when resetPenaltyOnPhysics is false. Both penalties are added correctly.

This second image shows when resetPenaltyOnPhysics is set to true. The first GUO is applied correctly, but then the second one (the left one) is applied and during its updating, it resets the penalties first and then adds penalty to the nodes. The result is that the penalties from both GUOs are not added together. The green patch in at the border is there because physics recalculation (recalculation of the position of the node, checking for obstacles etc.) affects a slightly larger area than the original GUO bounds because of the Grid Graph -> Collision Testing -> Diameter setting (it is enlarged by that value). So some extra nodes have their penalties reset.

◆ setTag

int setTag

If modifyTag is true, all nodes' tag will be set to this value.

◆ setWalkability

bool setWalkability

If modifyWalkability is true, the nodes' walkable variable will be set to this value.

◆ shape

A shape can be specified if a bounds object does not give enough precision.

Note that if you set this, you should set the bounds so that it encloses the shape because the bounds will be used as an initial fast check for which nodes that should be updated.

◆ trackChangedNodes

bool trackChangedNodes

Track which nodes are changed and save backup data.

Used internally to revert changes if needed.

◆ updateErosion

bool updateErosion = true

Update Erosion for GridGraphs.

When enabled, erosion will be recalculated for grid graphs after the GUO has been applied.

In the below image you can see the different effects you can get with the different values.
The first image shows the graph when no GUO has been applied. The blue box is not identified as an obstacle by the graph, the reason there are unwalkable nodes around it is because there is a height difference (nodes are placed on top of the box) so erosion will be applied (an erosion value of 2 is used in this graph). The orange box is identified as an obstacle, so the area of unwalkable nodes around it is a bit larger since both erosion and collision has made nodes unwalkable.
The GUO used simply sets walkability to true, i.e making all nodes walkable.

When updateErosion=True, the reason the blue box still has unwalkable nodes around it is because there is still a height difference so erosion will still be applied. The orange box on the other hand has no height difference and all nodes are set to walkable.

When updateErosion=False, all nodes walkability are simply set to be walkable in this example.

See also
Pathfinding.GridGraph

◆ updatePhysics

bool updatePhysics = true

Use physics checks to update nodes.

When updating a grid graph and this is true, the nodes' position and walkability will be updated using physics checks with settings from "Collision Testing" and "Height Testing".

When updating a PointGraph, setting this to true will make it re-evaluate all connections in the graph which passes through the bounds. This has no effect when updating GridGraphs if modifyWalkability is turned on.

On RecastGraphs, having this enabled will trigger a complete recalculation of all tiles intersecting the bounds. This is quite slow (but powerful). If you only want to update e.g penalty on existing nodes, leave it disabled.

Property Documentation

◆ requiresFloodFill

bool requiresFloodFill
set

Controlls if a flood fill will be carried out after this GUO has been applied.

Disabling this can be used to gain a performance boost, but use with care. If you are sure that a GUO will not modify walkability or connections. You can set this to false. For example when only updating penalty values it can save processing power when setting this to false. Especially on large graphs.

Note
If you set this to false, even though it does change e.g walkability, it can lead to paths returning that they failed even though there is a path, or the try to search the whole graph for a path even though there is none, and will in the processes use wast amounts of processing power.

If using the basic GraphUpdateObject (not a derived class), a quick way to check if it is going to need a flood fill is to check if modifyWalkability is true or updatePhysics is true.

Deprecated:
Not necessary anymore

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