GraphUpdateScene Class Reference

Helper class for easily updating graphs. More...

Detailed Description

Helper class for easily updating graphs.

The GraphUpdateScene component is really easy to use. Create a new empty GameObject and add the component to it, it can be found in Components–>Pathfinding–>GraphUpdateScene.
When you have added the component, you should see something like the image below.

The region which the component will affect is defined by creating a polygon in the scene. If you make sure you have the Position tool enabled (top-left corner of the Unity window) you can shift+click in the scene view to add more points to the polygon. You can remove points using shift+alt+click. By clicking on the points you can bring up a positioning tool. You can also open the "points" array in the inspector to set each point's coordinates manually.

In the inspector there are a number of variables. The first one is named "Convex", it sets if the convex hull of the points should be calculated or if the polygon should be used as-is. Using the convex hull is faster when applying the changes to the graph, but with a non-convex polygon you can specify more complicated areas.
The next two variables, called "Apply On Start" and "Apply On Scan" determine when to apply the changes. If the object is in the scene from the beginning, both can be left on, it doesn't matter since the graph is also scanned at start. However if you instantiate it later in the game, you can make it apply it's setting directly, or wait until the next scan (if any). If the graph is rescanned, all GraphUpdateScene components which have the Apply On Scan variable toggled will apply their settings again to the graph since rescanning clears all previous changes.
You can also make it apply it's changes using scripting.

GetComponent<GraphUpdateScene>().Apply (); 

The above code will make it apply its changes to the graph (assuming a GraphUpdateScene component is attached to the same GameObject).

Next there is "Modify Walkability" and "Set Walkability" (which appears when "Modify Walkability" is toggled). If Modify Walkability is set, then all nodes inside the area will either be set to walkable or unwalkable depending on the value of the "Set Walkability" variable.

Penalty can also be applied to the nodes. A higher penalty (aka weight) makes the nodes harder to traverse so it will try to avoid those areas.

The tagging variables can be read more about on this page: Working with tags.

Note

The Y (up) axis of the transform that this component is attached to should be in the same direction as the up direction of the graph. So if you for example have a grid in the XY plane then the transform should have the rotation (-90,0,0).

Public Member Functions
void	Apply ()
	Updates graphs with a created GUO.
void	DisableLegacyMode ()
	Disables legacy mode if it is enabled.
Bounds	GetBounds ()
	Calculates the bounds for this component.
virtual void	InvertSettings ()
	Inverts all invertable settings for this GUS.
void	LockToY ()
	Lock all points to a specific Y value.
override void	OnPostScan ()
	Called right after all graphs have been scanned.
void	RecalcConvex ()
	Recalculate convex hull.
void	Start ()
	Do some stuff at start.
Public Member Functions inherited from GraphModifier
virtual void	OnGraphsPostUpdate ()
	Called after graphs have been updated using GraphUpdateObjects.
virtual void	OnGraphsPreUpdate ()
	Called before graphs are updated using GraphUpdateObjects.
virtual void	OnLatePostScan ()
	Called at the end of the scanning procedure.
virtual void	OnPostCacheLoad ()
	Called after cached graphs have been loaded.
virtual void	OnPreScan ()
	Called right before graphs are going to be scanned.

Public Attributes
bool	applyOnScan = true
	Apply this graph update object whenever a graph is rescanned.
bool	applyOnStart = true
	Apply this graph update object on start.
bool	convex = true
	Use the convex hull of the points instead of the original polygon.
bool	legacyMode = false
	Emulates behavior from before version 4.0.
float	minBoundsHeight = 1
	Minumum height of the bounds of the resulting Graph Update Object.
bool	modifyTag
	Should the tags of the nodes be modified.
bool	modifyWalkability
	If true, then all affected nodes will be made walkable or unwalkable according to setWalkability.
int	penaltyDelta
	Penalty to add to nodes.
Vector3[]	points
	Points which define the region to update.
bool	resetPenaltyOnPhysics = true
	Reset penalties to their initial values when updating grid graphs and updatePhysics is true.
int	setTag
	If modifyTag is enabled, set all nodes' tags to this value.
bool	setWalkability
	Nodes will be made walkable or unwalkable according to this value if modifyWalkability is true.
bool	updateErosion = true
	Update Erosion for GridGraphs.
bool	updatePhysics
	Update node's walkability and connectivity using physics functions.

Protected Member Functions
override void	Awake ()
Protected Member Functions inherited from GraphModifier
override void	Awake ()
virtual void	OnDestroy ()
virtual void	OnDisable ()
	Removes this modifier from list of active modifiers.
virtual void	OnEnable ()
	Adds this modifier to list of active modifiers.
Protected Member Functions inherited from VersionedMonoBehaviour
virtual int	OnUpgradeSerializedData (int version, bool unityThread)
	Handle serialization backwards compatibility.

Private Member Functions
void	OnDrawGizmos ()
	Draws some gizmos.
void	OnDrawGizmos (bool selected)
	Draws some gizmos.
void	OnDrawGizmosSelected ()
	Draws some gizmos.
void	ToggleUseWorldSpace ()
	Switches between using world space and using local space.

Private Attributes
Vector3[]	convexPoints
	Private cached convex hull of the points.
bool	firstApplied
	Has apply been called yet.
bool	legacyUseWorldSpace
	Use world space for coordinates.
int	serializedVersion = 0
int	setTagInvert
	Private cached inversion of setTag.

Additional Inherited Members
Public Types inherited from GraphModifier
enum	EventType {   PostScan = 1 << 0, PreScan = 1 << 1, LatePostScan = 1 << 2, PreUpdate = 1 << 3,   PostUpdate = 1 << 4, PostCacheLoad = 1 << 5 }
	GraphModifier event type. More...
Static Public Member Functions inherited from GraphModifier
static void	FindAllModifiers ()
static void	TriggerEvent (GraphModifier.EventType type)
	Triggers an event for all active graph modifiers.
Static Protected Member Functions inherited from GraphModifier
static List< T >	GetModifiersOfType< T > ()
Protected Attributes inherited from GraphModifier
ulong	uniqueID
	Unique persistent ID for this component, used for serialization.
Static Protected Attributes inherited from GraphModifier
static Dictionary< ulong, GraphModifier >	usedIDs = new Dictionary<ulong, GraphModifier>()
	Maps persistent IDs to the component that uses it.

Member Function Documentation

void Apply

(

)

Updates graphs with a created GUO.

Creates a Pathfinding.GraphUpdateObject with a Pathfinding.GraphUpdateShape representing the polygon of this object and update all graphs using AstarPath.UpdateGraphs. This will not update graphs immediately. See AstarPath.UpdateGraph for more info.

override void Awake ( )

protectedvirtual

Reimplemented from VersionedMonoBehaviour.

void DisableLegacyMode

(

)

Disables legacy mode if it is enabled.

Legacy mode is automatically enabled for components when upgrading from an earlier version than 3.8.6.

Bounds GetBounds

(

)

Calculates the bounds for this component.

This is a relatively expensive operation, it needs to go through all points and run matrix multiplications.

virtual void InvertSettings ( )

virtual

Inverts all invertable settings for this GUS.

Namely: penalty delta, walkability, tags.

Penalty delta will be changed to negative penalty delta.
setWalkability will be inverted.
setTag will be stored in a private variable, and the new value will be 0. When calling this function again, the saved value will be the new value.

Calling this function an even number of times without changing any settings in between will be identical to no change in settings.

void LockToY

(

)

Lock all points to a specific Y value.

Deprecated:

The Y coordinate is no longer important. Use the position of the object instead.

void OnDrawGizmos ( )

private

Draws some gizmos.

void OnDrawGizmos ( bool  selected )

private

Draws some gizmos.

void OnDrawGizmosSelected ( )

private

Draws some gizmos.

override void OnPostScan ( )

virtual

Called right after all graphs have been scanned.

FloodFill and other post processing has not been done.

Warning

Since OnEnable and Awake are called roughly in the same time, the only way to ensure that these scripts get this call when scanning in Awake is to set the Script Execution Order for AstarPath to some time later than default time (see Edit -> Project Settings -> Script Execution Order).

Todo:

Is this still relevant? A call to FindAllModifiers should have before this method is called so the above warning is probably not relevant anymore.

See Also

OnLatePostScan

Reimplemented from GraphModifier.

void RecalcConvex

(

)

Recalculate convex hull.

Will not do anything if convex is disabled.

void Start

(

)

Do some stuff at start.

void ToggleUseWorldSpace ( )

private

Switches between using world space and using local space.

Deprecated:

World space can no longer be used as it does not work well with rotated graphs. Use transform.InverseTransformPoint to transform points to local space.

Member Data Documentation

bool applyOnScan = true

Apply this graph update object whenever a graph is rescanned.

bool applyOnStart = true

Apply this graph update object on start.

bool convex = true

Use the convex hull of the points instead of the original polygon.

See Also

https://en.wikipedia.org/wiki/Convex_hull

Vector3 [] convexPoints

private

Private cached convex hull of the points.

bool firstApplied

private

Has apply been called yet.

Used to prevent applying twice when both applyOnScan and applyOnStart are enabled

bool legacyMode = false

Emulates behavior from before version 4.0.

bool legacyUseWorldSpace

private

Use world space for coordinates.

If true, the shape will not follow when moving around the transform.

See Also

ToggleUseWorldSpace

float minBoundsHeight = 1

Minumum height of the bounds of the resulting Graph Update Object.

Useful when all points are laid out on a plane but you still need a bounds with a height greater than zero since a zero height graph update object would usually result in no nodes being updated.

bool modifyTag

Should the tags of the nodes be modified.

If enabled, set all nodes' tags to setTag

bool modifyWalkability

If true, then all affected nodes will be made walkable or unwalkable according to setWalkability.

int penaltyDelta

Penalty to add to nodes.

Usually you need quite large values, at least 1000-10000. A higher penalty means that agents will try to avoid those nodes more.

Be careful when setting negative values since if a node gets a negative penalty it will underflow and instead get really large. In most cases a warning will be logged if that happens.

See Also

Working with tags for another way of applying penalties.

Vector3 [] points

Points which define the region to update.

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.

int serializedVersion = 0

private

int setTag

If modifyTag is enabled, set all nodes' tags to this value.

int setTagInvert

private

Private cached inversion of setTag.

Used for InvertSettings()

bool setWalkability

Nodes will be made walkable or unwalkable according to this value if modifyWalkability is true.

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

bool updatePhysics

Update node's walkability and connectivity using physics functions.

For grid graphs, this will update the node's position and walkability exactly like when doing a scan of the graph. If enabled for grid graphs, modifyWalkability will be ignored.

For Point Graphs, this will recalculate all connections which passes through the bounds of the resulting Graph Update Object using raycasts (if enabled).

---

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

• /Users/arong/Unity/a-pathfinding-project/Assets/AstarPathfindingProject/Core/GraphUpdateScene.cs