A* Pathfinding Project  4.1.13
The A* Pathfinding Project for Unity 3D
AICooperative Class Reference

Movement script for cooperative pathfinding. More...

Detailed Description

Movement script for cooperative pathfinding.

See also
CooperativeContext
Todo:
Add path pooling

Public Member Functions

void FinalizeMovement (Vector3 nextPosition, Quaternion nextRotation)
 Move the agent. More...
 
void MovementUpdate (out Vector3 nextPosition, out Quaternion nextRotation)
 
virtual void SearchPath ()
 Starts a path request to the destination. More...
 

Public Attributes

CooperativeContext cooperativeContext
 Handles time and space reservations for cooperative pathfinding. More...
 
float pathSmoothing = 1f
 How much to smooth the path. More...
 
float repathInterval = 5
 Time in seconds between new path requests. More...
 
bool rotationIn2D
 If true, rotation will only be done along the Z axis so that the Y axis is the forward direction of the character. More...
 
Transform target
 

Protected Member Functions

 AICooperative ()
 
override int OnUpgradeSerializedData (int version, bool unityThread)
 Handle serialization backwards compatibility. More...
 
- Protected Member Functions inherited from VersionedMonoBehaviour
virtual void Awake ()
 

Properties

bool IAstarAI. canMove [get, set]
 
bool IAstarAI. canSearch [get, set]
 
Vector3 IAstarAI. desiredVelocity [get]
 
Vector3 destination [get, set]
 Position in the world that this agent should move to. More...
 
bool IAstarAI. hasPath [get]
 
bool IAstarAI. isStopped [get, set]
 
float IAstarAI. maxSpeed [get, set]
 
GraphNode node [get]
 
System.Action onSearchPath [get, set]
 Called when the agent recalculates its path. More...
 
bool pathPending [get]
 
Vector3 position [get]
 Position of the agent. More...
 
bool reachedEndOfPath [get]
 
float IAstarAI. remainingDistance [get]
 
Quaternion rotation [get]
 Rotation of the agent. More...
 
Vector3 IAstarAI. steeringTarget [get]
 
Vector3 velocity [get]
 Actual velocity that the agent is moving with. More...
 
- Properties inherited from IAstarAI
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...
 

Private Member Functions

void IAstarAI. Move (Vector3 deltaPosition)
 Move the agent. More...
 
void IAstarAI. MovementUpdate (float deltaTime, out Vector3 nextPosition, out Quaternion nextRotation)
 Calculate how the character wants to move during this frame. More...
 
void OnDisable ()
 Clear various fields when the component is disabled. More...
 
void OnEnable ()
 
void IAstarAI. SetPath (Path path)
 Make the AI follow the specified path. More...
 
void Start ()
 
void IAstarAI. Teleport (Vector3 newPosition, bool clearPath)
 Instantly move the agent to a new position. More...
 
void Update ()
 Update is called once per frame. More...
 
void UpdatePosition ()
 
void Upgrade ()
 

Private Attributes

CooperativeContext.IAgent agent
 
float lastRepath = float.NegativeInfinity
 Last time a path request was scheduled. More...
 
Seeker seeker
 Handles path requests for this agent. More...
 

Constructor & Destructor Documentation

◆ AICooperative()

AICooperative ( )
protected

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.

Implements IAstarAI.

◆ Move()

void IAstarAI. Move ( Vector3  deltaPosition)
private

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

Implements IAstarAI.

◆ MovementUpdate() [1/2]

void MovementUpdate ( out Vector3  nextPosition,
out Quaternion  nextRotation 
)

◆ MovementUpdate() [2/2]

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

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);
}

Implements IAstarAI.

◆ OnDisable()

void OnDisable ( )
private

Clear various fields when the component is disabled.

◆ OnEnable()

void OnEnable ( )
private

◆ OnUpgradeSerializedData()

override int OnUpgradeSerializedData ( int  version,
bool  unityThread 
)
protectedvirtual

Handle serialization backwards compatibility.

Reimplemented from VersionedMonoBehaviour.

◆ SearchPath()

virtual void SearchPath ( )
virtual

Starts a path request to the destination.

Implements IAstarAI.

◆ SetPath()

void IAstarAI. SetPath ( Path  path)
private

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

Implements IAstarAI.

◆ Start()

void Start ( )
private

◆ Teleport()

void IAstarAI. Teleport ( Vector3  newPosition,
bool  clearPath 
)
private

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

Implements IAstarAI.

◆ Update()

void Update ( )
private

Update is called once per frame.

◆ UpdatePosition()

void UpdatePosition ( )
private

◆ Upgrade()

void Upgrade ( )
private

Member Data Documentation

◆ agent

◆ cooperativeContext

CooperativeContext cooperativeContext

Handles time and space reservations for cooperative pathfinding.

◆ lastRepath

float lastRepath = float.NegativeInfinity
private

Last time a path request was scheduled.

◆ pathSmoothing

float pathSmoothing = 1f

How much to smooth the path.

The agents position will be calculated as the mean of the path during the last [value] ticks. So if for example this field is set to 2 then the position of the agent will be smoothed over 2 ticks. This necessarily introduces a small time delay as it needs to use the historical information to calculate the current position. The agent will be delayed by roughly pathSmoothing/2 ticks. Due to the time delay it is recommended that all agents use the same amount of path smoothing. Note that a too large value may cause agents to intersect.

See also
Pathfinding.CooperativeContext.tickLength

◆ repathInterval

float repathInterval = 5

Time in seconds between new path requests.

◆ rotationIn2D

bool rotationIn2D

If true, rotation will only be done along the Z axis so that the Y axis is the forward direction of the character.

This is useful for 2D games in which one often want to have the Y axis as the forward direction to get sprites and 2D colliders to work properly.

◆ seeker

Seeker seeker
private

Handles path requests for this agent.

◆ target

Transform target

Property Documentation

◆ canMove

bool IAstarAI. canMove
getsetprivate

◆ canSearch

bool IAstarAI. canSearch
getsetprivate

◆ desiredVelocity

Vector3 IAstarAI. desiredVelocity
getprivate

◆ 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 IAstarAI. hasPath
getprivate

◆ isStopped

bool IAstarAI. isStopped
getsetprivate

◆ maxSpeed

float IAstarAI. maxSpeed
getsetprivate

◆ node

GraphNode node
get

◆ 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

◆ position

Vector3 position
get

Position of the agent.

In world space.

See also
rotation

◆ reachedEndOfPath

bool reachedEndOfPath
get

◆ remainingDistance

float IAstarAI. remainingDistance
getprivate

◆ rotation

Quaternion rotation
get

Rotation of the agent.

In world space.

See also
position

◆ steeringTarget

Vector3 IAstarAI. steeringTarget
getprivate

◆ velocity

Vector3 velocity
get

Actual velocity that the agent is moving with.

In world units per second.

See also
desiredVelocity

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