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

deltaPosition Direction 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

deltaTime	time to simulate movement for. Usually set to Time.deltaTime.
nextPosition	the position that the agent wants to move to during this frame.
nextRotation	the 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 () {
        ai.canMove = false;
        Vector3 nextPosition;
        Quaternion nextRotation;
        ai.MovementUpdate(Time.deltaTime, out nextPosition, out nextRotation);
        // Modify nextPosition and nextRotation in any way you wish
        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.

◆ 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:

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

Detailed Description

Public Member Functions

Properties

Member Function Documentation

◆ FinalizeMovement()

◆ Move()

◆ MovementUpdate()

◆ SearchPath()

◆ Teleport()

Property Documentation

◆ canMove

◆ canSearch

◆ desiredVelocity

◆ destination

◆ hasPath

◆ isStopped

◆ maxSpeed

◆ onSearchPath

◆ pathPending

◆ position

◆ reachedEndOfPath

◆ remainingDistance

◆ rotation

◆ steeringTarget

◆ velocity