AIPath Class Reference

AI for following paths. More...

Detailed Description

AI for following paths.

This AI is the default movement script which comes with the A* Pathfinding Project. It is in no way required by the rest of the system, so feel free to write your own. But I hope this script will make it easier to set up movement for the characters in your game. This script is not written for high performance, so I do not recommend using it for large groups of units.

This script will try to follow a target transform, in regular intervals, the path to that target will be recalculated. It will on FixedUpdate try to move towards the next point in the path. However it will only move in the forward direction, but it will rotate around it's Y-axis to make it reach the target.

Quick overview of the variables

In the inspector in Unity, you will see a bunch of variables. You can view detailed information further down, but here's a quick overview.
The repathRate determines how often it will search for new paths, if you have fast moving targets, you might want to set it to a lower value.
The target variable is where the AI will try to move, it can be a point on the ground where the player has clicked in an RTS for example. Or it can be the player object in a zombie game.
The speed is self-explanatory, so is turningSpeed, however slowdownDistance might require some explanation. It is the approximate distance from the target where the AI will start to slow down. Note that this doesn't only affect the end point of the path but also any intermediate points, so be sure to set forwardLook and pickNextWaypointDist to a higher value than this.
pickNextWaypointDist is simply determines within what range it will switch to target the next waypoint in the path.
forwardLook will try to calculate an interpolated target point on the current segment in the path so that it has a distance of forwardLook from the AI
Below is an image illustrating several variables as well as some internal ones, but which are relevant for understanding how it works. Note that the forwardLook range will not match up exactly with the target point practically, even though that's the goal.

This script has many movement fallbacks. If it finds a NavmeshController, it will use that, otherwise it will look for a character controller, then for a rigidbody and if it hasn't been able to find any it will use Transform.Translate which is guaranteed to always work.

Public Member Functions
virtual Vector3	GetFeetPosition ()
void	OnDisable ()
virtual void	OnPathComplete (Path _p)
	Called when a requested path has finished calculation.
virtual void	OnTargetReached ()
virtual void	SearchPath ()
	Requests a path to the target.
float	TrySearchPath ()
	Tries to search for a path.
virtual void	Update ()

Public Attributes
bool	canMove = true
	Enables or disables movement.
bool	canSearch = true
	Enables or disables searching for paths.
bool	closestOnPathCheck = true
	Do a closest point on path check when receiving path callback.
float	endReachedDistance = 0.2F
	Distance to the end point to consider the end of path to be reached.
float	forwardLook = 1
	Target point is Interpolated on the current segment in the path so that it has a distance of forwardLook from the AI.
float	pickNextWaypointDist = 2
	Determines within what range it will switch to target the next waypoint in the path.
float	repathRate = 0.5F
	Determines how often it will search for new paths.
float	slowdownDistance = 0.6F
	Distance from the target point where the AI will start to slow down.
float	speed = 3
	Maximum velocity.
Transform	target
	Target to move towards.
float	turningSpeed = 5
	Rotation speed.

Protected Member Functions
virtual void	Awake ()
	Initializes reference variables.
Vector3	CalculateTargetPoint (Vector3 p, Vector3 a, Vector3 b)
	Calculates target point from the current line segment.
Vector3	CalculateVelocity (Vector3 currentPosition)
	Calculates desired velocity.
virtual void	OnEnable ()
	Run at start and when reenabled.
IEnumerator	RepeatTrySearchPath ()
	Tries to search for a path every repathRate seconds.
virtual void	RotateTowards (Vector3 dir)
	Rotates in the specified direction.
virtual void	Start ()
	Starts searching for paths.
float	XZSqrMagnitude (Vector3 a, Vector3 b)

Protected Attributes
bool	canSearchAgain = true
	Only when the previous path has been returned should be search for a new path.
CharacterController	controller
	Cached CharacterController component.
int	currentWaypointIndex = 0
	Current index in the path which is current target.
Vector3	lastFoundWaypointPosition
float	lastFoundWaypointTime = -9999
float	lastRepath = -9999
	Time when the last path request was sent.
float	minMoveScale = 0.05F
Path	path
	Current path which is followed.
Rigidbody	rigid
	Cached Rigidbody component.
RVOController	rvoController
Seeker	seeker
	Cached Seeker component.
Vector3	targetDirection
	Relative direction to where the AI is heading.
Vector3	targetPoint
	Point to where the AI is heading.
bool	targetReached = false
	Holds if the end-of-path is reached.
Transform	tr
	Cached Transform component.

Properties
bool	TargetReached [get]
	Returns if the end-of-path has been reached.

Private Attributes
bool	startHasRun = false
	Holds if the Start function has been run.

Member Function Documentation

virtual void Awake ( )

protectedvirtual

Initializes reference variables.

If you override this function you should in most cases call base.Awake () at the start of it.

Vector3 CalculateTargetPoint ( Vector3  p, Vector3  a, Vector3  b  )

protected

Calculates target point from the current line segment.

Parameters

p	Current position
a	Line segment start
b	Line segment end The returned point will lie somewhere on the line segment.

See Also

forwardLook

Todo:

This function uses .magnitude quite a lot, can it be optimized?

Vector3 CalculateVelocity ( Vector3  currentPosition )

protected

Calculates desired velocity.

Finds the target path segment and returns the forward direction, scaled with speed. A whole bunch of restrictions on the velocity is applied to make sure it doesn't overshoot, does not look too far ahead, and slows down when close to the target. /see speed /see endReachedDistance /see slowdownDistance /see CalculateTargetPoint /see targetPoint /see targetDirection /see currentWaypointIndex

virtual Vector3 GetFeetPosition ( )

virtual

Reimplemented in MineBotAI.

void OnDisable

(

)

virtual void OnEnable ( )

protectedvirtual

Run at start and when reenabled.

Starts RepeatTrySearchPath.

See Also

Start

virtual void OnPathComplete ( Path  _p )

virtual

Called when a requested path has finished calculation.

A path is first requested by SearchPath, it is then calculated, probably in the same or the next frame. Finally it is returned to the seeker which forwards it to this function.

virtual void OnTargetReached ( )

virtual

Reimplemented in MineBotAI.

IEnumerator RepeatTrySearchPath ( )

protected

Tries to search for a path every repathRate seconds.

See Also

TrySearchPath

virtual void RotateTowards ( Vector3  dir )

protectedvirtual

Rotates in the specified direction.

Rotates around the Y-axis.

See Also

turningSpeed

virtual void SearchPath ( )

virtual

Requests a path to the target.

virtual void Start ( )

protectedvirtual

Starts searching for paths.

If you override this function you should in most cases call base.Start () at the start of it.

See Also

OnEnable

RepeatTrySearchPath

Reimplemented in MineBotAI.

float TrySearchPath

(

)

Tries to search for a path.

Will search for a new path if there was a sufficient time since the last repath and both canSearchAgain and canSearch are true and there is a target.

Returns

The time to wait until calling this function again (based on repathRate)

virtual void Update ( )

virtual

Reimplemented in MineBotAI.

float XZSqrMagnitude ( Vector3  a, Vector3  b  )

protected

Member Data Documentation

bool canMove = true

Enables or disables movement.

See Also

canSearch

bool canSearch = true

Enables or disables searching for paths.

Setting this to false does not stop any active path requests from being calculated or stop it from continuing to follow the current path.

See Also

canMove

bool canSearchAgain = true

protected

Only when the previous path has been returned should be search for a new path.

bool closestOnPathCheck = true

Do a closest point on path check when receiving path callback.

Usually the AI has moved a bit between requesting the path, and getting it back, and there is usually a small gap between the AI and the closest node. If this option is enabled, it will simulate, when the path callback is received, movement between the closest node and the current AI position. This helps to reduce the moments when the AI just get a new path back, and thinks it ought to move backwards to the start of the new path even though it really should just proceed forward.

CharacterController controller

protected

Cached CharacterController component.

int currentWaypointIndex = 0

protected

Current index in the path which is current target.

float endReachedDistance = 0.2F

Distance to the end point to consider the end of path to be reached.

When this has been reached, the AI will not move anymore until the target changes and OnTargetReached will be called.

float forwardLook = 1

Target point is Interpolated on the current segment in the path so that it has a distance of forwardLook from the AI.

See the detailed description of AIPath for an illustrative image

Vector3 lastFoundWaypointPosition

protected

float lastFoundWaypointTime = -9999

protected

float lastRepath = -9999

protected

Time when the last path request was sent.

float minMoveScale = 0.05F

protected

Path path

protected

Current path which is followed.

float pickNextWaypointDist = 2

Determines within what range it will switch to target the next waypoint in the path.

float repathRate = 0.5F

Determines how often it will search for new paths.

If you have fast moving targets or AIs, you might want to set it to a lower value. The value is in seconds between path requests.

Rigidbody rigid

protected

Cached Rigidbody component.

RVOController rvoController

protected

Seeker seeker

protected

Cached Seeker component.

float slowdownDistance = 0.6F

Distance from the target point where the AI will start to slow down.

Note that this doesn't only affect the end point of the path but also any intermediate points, so be sure to set forwardLook and pickNextWaypointDist to a higher value than this

float speed = 3

Maximum velocity.

This is the maximum speed in world units per second.

bool startHasRun = false

private

Holds if the Start function has been run.

Used to test if coroutines should be started in OnEnable to prevent calculating paths in the awake stage (or rather before start on frame 0).

Transform target

Target to move towards.

The AI will try to follow/move towards this target. It can be a point on the ground where the player has clicked in an RTS for example, or it can be the player object in a zombie game.

Vector3 targetDirection

protected

Relative direction to where the AI is heading.

Filled in by CalculateVelocity

Vector3 targetPoint

protected

Point to where the AI is heading.

Filled in by CalculateVelocity

bool targetReached = false

protected

Holds if the end-of-path is reached.

See Also

TargetReached

Transform tr

protected

Cached Transform component.

float turningSpeed = 5

Rotation speed.

Rotation is calculated using Quaternion.SLerp. This variable represents the damping, the higher, the faster it will be able to rotate.

Property Documentation

bool TargetReached

get

Returns if the end-of-path has been reached.

See Also

targetReached

---

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

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