A* Pathfinding Project  4.1.17
The A* Pathfinding Project for Unity 3D
IAstarAI Interface Reference

Common interface for all movement scripts in the A* Pathfinding Project. More...

Detailed Description

Common interface for all movement scripts in the A* Pathfinding Project.

See also
Pathfinding.AIPath
Pathfinding.RichAI
Pathfinding.AILerp

Public Member Functions

void FinalizeMovement (Vector3 nextPosition, Quaternion nextRotation)
 Move the agent. More...
 
void Move (Vector3 deltaPosition)
 Move the agent. More...
 
void MovementUpdate (float deltaTime, out Vector3 nextPosition, out Quaternion nextRotation)
 Calculate how the character wants to move during this frame. More...
 
void SearchPath ()
 Recalculate the current path. More...
 
void SetPath (Path path)
 Make the AI follow the specified path. More...
 
void Teleport (Vector3 newPosition, bool clearPath=true)
 Instantly move the agent to a new position. More...
 

Properties

bool canMove [get, set]
 Enables or disables movement completely. More...
 
bool canSearch [get, set]
 Enables or disables recalculating the path at regular intervals. More...
 
Vector3 desiredVelocity [get]
 Velocity that this agent wants to move with. More...
 
Vector3 destination [get, set]
 Position in the world that this agent should move to. More...
 
bool hasPath [get]
 True if this agent currently has a path that it follows. More...
 
bool isStopped [get, set]
 Gets or sets if the agent should stop moving. More...
 
float maxSpeed [get, set]
 Max speed in world units per second. More...
 
System.Action onSearchPath [get, set]
 Called when the agent recalculates its path. More...
 
bool pathPending [get]
 True if a path is currently being calculated. More...
 
Vector3 position [get]
 Position of the agent. More...
 
bool reachedEndOfPath [get]
 True if the agent has reached the end of the current path. More...
 
float remainingDistance [get]
 Remaining distance along the current path to the end of the path. More...
 
Quaternion rotation [get]
 Rotation of the agent. More...
 
Vector3 steeringTarget [get]
 Point on the path which the agent is currently moving towards. More...
 
Vector3 velocity [get]
 Actual velocity that the agent is moving with. More...
 

Member Function Documentation

◆ FinalizeMovement()

void FinalizeMovement ( Vector3  nextPosition,
Quaternion  nextRotation 
)

Move the agent.

To be called as the last step when you are handling movement manually.

The movement will be clamped to the navmesh if applicable (this is done for the RichAI movement script).

See also
MovementUpdate for a code example.

Implemented in AILerp.

◆ Move()

void Move ( Vector3  deltaPosition)

Move the agent.

Parameters
deltaPositionDirection and distance to move the agent in world space.

This is intended for external movement forces such as those applied by wind, conveyor belts, knockbacks etc.

Some movement scripts may ignore this completely (notably the AILerp script) if it does not have any concept of being moved externally.

The agent will not be moved immediately when calling this method. Instead this offset will be stored and then applied the next time the agent runs its movement calculations (which is usually later this frame or the next frame). If you want to move the agent immediately then call:

ai.Move(someVector);
ai.FinalizeMovement(ai.position, ai.rotation);

Implemented in AILerp.

◆ MovementUpdate()

void MovementUpdate ( float  deltaTime,
out Vector3  nextPosition,
out Quaternion  nextRotation 
)

Calculate how the character wants to move during this frame.

Parameters
deltaTimetime to simulate movement for. Usually set to Time.deltaTime.
nextPositionthe position that the agent wants to move to during this frame.
nextRotationthe rotation that the agent wants to rotate to during this frame.

Note that this does not actually move the character. You need to call FinalizeMovement for that. This is called automatically unless canMove is false.

To handle movement yourself you can disable canMove and call this method manually. This code will replicate the normal behavior of the component:

void Update () {
// Disable the AIs own movement code
ai.canMove = false;
Vector3 nextPosition;
Quaternion nextRotation;
// Calculate how the AI wants to move
ai.MovementUpdate(Time.deltaTime, out nextPosition, out nextRotation);
// Modify nextPosition and nextRotation in any way you wish
// Actually move the AI
ai.FinalizeMovement(nextPosition, nextRotation);
}

Implemented in AILerp.

◆ SearchPath()

void SearchPath ( )

Recalculate the current path.

You can for example use this if you want very quick reaction times when you have changed the destination so that the agent does not have to wait until the next automatic path recalculation (see canSearch).

If there is an ongoing path calculation, it will be canceled, so make sure you leave time for the paths to get calculated before calling this function again. A canceled path will show up in the log with the message "Canceled by script" (see #Seeker.CancelCurrentPathRequest()).

If no destination has been set yet then nothing will be done.

Note
The path result may not become available until after a few frames. During the calculation time the pathPending property will return true.
See also
pathPending

Implemented in AILerp, and RichAI.

◆ SetPath()

void SetPath ( Path  path)

Make the AI follow the specified path.

In case the path has not been calculated, the script will call seeker.StartPath to calculate it. This means the AI may not actually start to follow the path until in a few frames when the path has been calculated. The pathPending field will as usual return true while the path is being calculated.

In case the path has already been calculated it will immediately replace the current path the AI is following. This is useful if you want to replace how the AI calculates its paths. Note that if you calculate the path using seeker.StartPath then this script will already pick it up because it is listening for all paths that the Seeker finishes calculating. In that case you do not need to call this function.

You can disable the automatic path recalculation by setting the canSearch field to false.

// Disable the automatic path recalculation
ai.canSearch = false;
var pointToAvoid = enemy.position;
// Make the AI flee from the enemy.
// The path will be about 20 world units long (the default cost of moving 1 world unit is 1000).
var path = FleePath.Construct(ai.position, pointToAvoid, 1000 * 20);
ai.SetPath(path);

Implemented in AILerp.

◆ Teleport()

void Teleport ( Vector3  newPosition,
bool  clearPath = true 
)

Instantly move the agent to a new position.

This will trigger a path recalculation (if clearPath is true, which is the default) so if you want to teleport the agent and change its destination it is recommended that you set the destination before calling this method.

The current path will be cleared by default.

See also
Works similarly to Unity's NavmeshAgent.Warp.
SearchPath

Implemented in AILerp, RichAI, and AIPath.

Property Documentation

◆ canMove

bool canMove
getset

Enables or disables movement completely.

If you want the agent to stand still, but still react to local avoidance and use gravity: use isStopped instead.

This is also useful if you want to have full control over when the movement calculations run. Take a look at MovementUpdate

See also
canSearch
isStopped

◆ canSearch

bool canSearch
getset

Enables or disables recalculating the path at regular intervals.

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

Note that this only disables automatic path recalculations. If you call the SearchPath() method a path will still be calculated.

See also
canMove
isStopped

◆ desiredVelocity

Vector3 desiredVelocity
get

Velocity that this agent wants to move with.

Includes gravity and local avoidance if applicable. In world units per second.

See also
velocity

◆ destination

Vector3 destination
getset

Position in the world that this agent should move to.

If no destination has been set yet, then (+infinity, +infinity, +infinity) will be returned.

Note that setting this property does not immediately cause the agent to recalculate its path. So it may take some time before the agent starts to move towards this point. Most movement scripts have a repathRate field which indicates how often the agent looks for a new path. You can also call the SearchPath method to immediately start to search for a new path. Paths are calculated asynchronously so when an agent starts to search for path it may take a few frames (usually 1 or 2) until the result is available. During this time the pathPending property will return true.

If you are setting a destination and then want to know when the agent has reached that destination then you should check both pathPending and reachedEndOfPath:

IEnumerator Start () {
ai.destination = somePoint;
// Start to search for a path to the destination immediately
// Note that the result may not become available until after a few frames
// ai.pathPending will be true while the path is being calculated
ai.SearchPath();
// Wait until we know for sure that the agent has calculated a path to the destination we set above
while (ai.pathPending || !ai.reachedEndOfPath) {
yield return null;
}
// The agent has reached the destination now
}

◆ hasPath

bool hasPath
get

True if this agent currently has a path that it follows.

◆ isStopped

bool isStopped
getset

Gets or sets if the agent should stop moving.

If this is set to true the agent will immediately start to slow down as quickly as it can to come to a full stop. The agent will still react to local avoidance and gravity (if applicable), but it will not try to move in any particular direction.

The current path of the agent will not be cleared, so when this is set to false again the agent will continue moving along the previous path.

This is a purely user-controlled parameter, so for example it is not set automatically when the agent stops moving because it has reached the target. Use reachedEndOfPath for that.

If this property is set to true while the agent is traversing an off-mesh link (RichAI script only), then the agent will continue traversing the link and stop once it has completed it.

Note
This is not the same as the canMove setting which some movement scripts have. The canMove setting disables movement calculations completely (which among other things makes it not be affected by local avoidance or gravity). For the AILerp movement script which doesn't use gravity or local avoidance anyway changing this property is very similar to changing canMove.

The steeringTarget property will continue to indicate the point which the agent would move towards if it would not be stopped.

◆ maxSpeed

float maxSpeed
getset

Max speed in world units per second.

◆ onSearchPath

System.Action onSearchPath
getset

Called when the agent recalculates its path.

This is called both for automatic path recalculations (see canSearch) and manual ones (see SearchPath).

See also
Take a look at the Pathfinding.AIDestinationSetter source code for an example of how it can be used.

◆ pathPending

bool pathPending
get

True if a path is currently being calculated.

◆ position

Vector3 position
get

Position of the agent.

In world space.

See also
rotation

◆ reachedEndOfPath

bool reachedEndOfPath
get

True if the agent has reached the end of the current path.

This is the approximate distance the AI has to move to reach the end of the path it is currently traversing.

Note that setting the destination does not immediately update the path, nor is there any guarantee that the AI will actually be able to reach the destination that you set. The AI will try to get as close as possible.

It is very hard to provide a method for detecting if the AI has reached the destination that works across all different games because the destination may not even lie on the navmesh and how that is handled differs from game to game (see also the code snippet in the docs for destination).

See also
remainingDistance

◆ remainingDistance

float remainingDistance
get

Remaining distance along the current path to the end of the path.

For the RichAI movement script this may not always be precisely known, especially when far away from the destination. In those cases an approximate distance will be returned.

If the agent does not currently have a path, then positive infinity will be returned.

See also
reachedEndOfPath

◆ rotation

Quaternion rotation
get

Rotation of the agent.

In world space.

See also
position

◆ steeringTarget

Vector3 steeringTarget
get

Point on the path which the agent is currently moving towards.

This is usually a point a small distance ahead of the agent or the end of the path.

If the agent does not have a path at the moment, then the agent's current position will be returned.

◆ velocity

Vector3 velocity
get

Actual velocity that the agent is moving with.

In world units per second.

See also
desiredVelocity

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