using UnityEngine;
using System.Collections.Generic;
using Pathfinding.Util;
namespace Pathfinding {
///
/// Common interface for all movement scripts in the A* Pathfinding Project.
/// See:
/// See:
/// See:
///
public interface IAstarAI {
///
/// Radius of the agent in world units.
/// This is visualized in the scene view as a yellow cylinder around the character.
///
/// Note that this does not affect pathfinding in any way.
/// The graph used completely determines where the agent can move.
///
/// Note: The script doesn't really have any use of knowing the radius or the height of the character, so this property will always return 0 in that script.
///
float radius { get; set; }
///
/// Height of the agent in world units.
/// This is visualized in the scene view as a yellow cylinder around the character.
///
/// This value is currently only used if an RVOController is attached to the same GameObject, otherwise it is only used for drawing nice gizmos in the scene view.
/// However since the height value is used for some things, the radius field is always visible for consistency and easier visualization of the character.
/// That said, it may be used for something in a future release.
///
/// Note: The script doesn't really have any use of knowing the radius or the height of the character, so this property will always return 0 in that script.
///
float height { get; set; }
///
/// Position of the agent.
/// In world space.
/// See:
///
/// If you want to move the agent you may use or .
///
Vector3 position { get; }
///
/// Rotation of the agent.
/// In world space.
/// See:
///
Quaternion rotation { get; set; }
/// Max speed in world units per second
float maxSpeed { get; set; }
///
/// Actual velocity that the agent is moving with.
/// In world units per second.
///
/// See:
///
Vector3 velocity { get; }
///
/// Velocity that this agent wants to move with.
/// Includes gravity and local avoidance if applicable.
/// In world units per second.
///
/// See:
///
/// Note: The movement script doesn't use local avoidance or gravity so this property will always be identical to on that component.
///
Vector3 desiredVelocity { get; }
///
/// Velocity that this agent wants to move with before taking local avoidance into account.
///
/// Includes gravity.
/// In world units per second.
///
/// Setting this property will set the current velocity that the agent is trying to move with, including gravity.
/// This can be useful if you want to make the agent come to a complete stop in a single frame or if you want to modify the velocity in some way.
///
///
/// // Set the velocity to zero, but keep the current gravity
/// var newVelocity = new Vector3(0, ai.desiredVelocityWithoutLocalAvoidance.y, 0);
///
/// ai.desiredVelocityWithoutLocalAvoidance = newVelocity;
///
///
/// Note: The movement script doesn't use local avoidance so this property will always be identical to on that component.
///
/// Warning: Trying to set this property on an AILerp component will throw an exception since its velocity cannot meaningfully be changed abitrarily.
///
/// If you are not using local avoidance then this property will in almost all cases be identical to plus some noise due to floating point math.
///
/// See:
/// See:
/// See:
/// See:
///
Vector3 desiredVelocityWithoutLocalAvoidance { get; set; }
///
/// Approximate remaining distance along the current path to the end of the path.
/// The RichAI movement script approximates this distance since it is quite expensive to calculate the real distance.
/// However it will be accurate when the agent is within 1 corner of the destination.
/// You can use to calculate the actual remaining path more precisely.
///
/// The AIPath and AILerp scripts use a more accurate distance calculation at all times.
///
/// If the agent does not currently have a path, then positive infinity will be returned.
///
/// Note: This is the distance to the end of the path, which may or may not be at the . If the character cannot reach the destination it will try to move as close as possible to it.
///
/// Warning: Since path requests are asynchronous, there is a small delay between a path request being sent and this value being updated with the new calculated path.
///
/// See:
/// See:
/// See:
///
float remainingDistance { get; }
///
/// True if the ai has reached the .
/// This is a best effort calculation to see if the has been reached.
/// For the AIPath/RichAI scripts, this is when the character is within world units from the .
/// For the AILerp script it is when the character is at the destination (±a very small margin).
///
/// This value will be updated immediately when the is changed (in contrast to , however since path requests are asynchronous
/// it will use an approximation until it sees the real path result. What this property does is to check the distance to the end of the current path, and add to that the distance
/// from the end of the path to the (i.e. is assumes it is possible to move in a straight line between the end of the current path to the destination) and then checks if that total
/// distance is less than . This property is therefore only a best effort, but it will work well for almost all use cases.
///
/// Furthermore it will not report that the destination is reached if the destination is above the head of the character or more than half the of the character below its feet
/// (so if you have a multilevel building, it is important that you configure the of the character correctly).
///
/// The cases which could be problematic are if an agent is standing next to a very thin wall and the destination suddenly changes to the other side of that thin wall.
/// During the time that it takes for the path to be calculated the agent may see itself as alredy having reached the destination because the destination only moved a very small distance (the wall was thin),
/// even though it may actually be quite a long way around the wall to the other side.
///
/// In contrast to , this property is immediately updated when the is changed.
///
///
/// IEnumerator Start () {
/// ai.destination = somePoint;
/// // Start to search for a path to the destination immediately
/// ai.SearchPath();
/// // Wait until the agent has reached the destination
/// while (!ai.reachedDestination) {
/// yield return null;
/// }
/// // The agent has reached the destination now
/// }
///
///
/// See:
/// See:
/// See:
///
bool reachedDestination { get; }
///
/// True if the agent has reached the end of the current path.
///
/// Note that setting the 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.
/// Often you want to use instead which is easier to work with.
///
/// It is very hard to provide a method for detecting if the AI has reached the 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 ).
///
/// See:
/// See:
///
bool reachedEndOfPath { get; }
///
/// End point of path the agent is currently following.
/// If the agent has no path (or it might not be calculated yet), this will return the instead.
/// If the agent has no destination it will return the agent's current position.
///
/// The end of the path is usually identical or very close to the , but it may differ
/// if the path for example was blocked by a wall so that the agent couldn't get any closer.
///
/// This is only updated when the path is recalculated.
///
Vector3 endOfPath { get; }
///
/// 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 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 property will return true.
///
/// If you are setting a destination and then want to know when the agent has reached that destination
/// then you could either use (recommended) or check both and .
/// Check the documentation for the respective fields to learn about their differences.
///
///
/// IEnumerator Start () {
/// ai.destination = somePoint;
/// // Start to search for a path to the destination immediately
/// ai.SearchPath();
/// // Wait until the agent has reached the destination
/// while (!ai.reachedDestination) {
/// yield return null;
/// }
/// // The agent has reached the destination now
/// }
///
///
/// 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
/// }
///
///
Vector3 destination { get; set; }
///
/// 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 method a path will still be calculated.
///
/// See:
/// See:
///
bool canSearch { get; set; }
///
/// Enables or disables movement completely.
/// If you want the agent to stand still, but still react to local avoidance and use gravity: use instead.
///
/// This is also useful if you want to have full control over when the movement calculations run.
/// Take a look at
///
/// See:
/// See:
///
bool canMove { get; set; }
/// True if this agent currently has a path that it follows
bool hasPath { get; }
/// True if a path is currently being calculated
bool pathPending { get; }
///
/// 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 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 setting which some movement scripts have. The 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 .
///
/// The property will continue to indicate the point which the agent would move towards if it would not be stopped.
///
bool isStopped { get; set; }
///
/// 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.
///
Vector3 steeringTarget { get; }
///
/// Called when the agent recalculates its path.
/// This is called both for automatic path recalculations (see and manual ones (see .
///
/// See: Take a look at the source code for an example of how it can be used.
///
System.Action onSearchPath { get; set; }
///
/// The plane the agent is moving in.
///
/// This is typically the ground plane, which will be the XZ plane in a 3D game, and the XY plane in a 2D game.
/// Ultimately it depends on the graph orientation.
///
/// If you are doing pathfinding on a spherical world (see spherical) (view in online documentation for working links), the the movement plane will be the tangent plane of the sphere at the agent's position.
///
NativeMovementPlane movementPlane { get; }
///
/// Fills buffer with the remaining path.
///
///
/// var buffer = new List();
///
/// ai.GetRemainingPath(buffer, out bool stale);
/// for (int i = 0; i < buffer.Count - 1; i++) {
/// Debug.DrawLine(buffer[i], buffer[i+1], Color.red);
/// }
///
/// [Open online documentation to see images]
///
/// The buffer will be cleared and replaced with the path. The first point is the current position of the agent.
/// May be true if the path is invalid in some way. For example if the agent has no path or (for the RichAI/FollowerEntity components only) if the agent has detected that some nodes in the path have been destroyed.
void GetRemainingPath(List buffer, out bool stale);
///
/// Fills buffer with the remaining path.
///
///
/// var buffer = new List();
/// var parts = new List();
///
/// ai.GetRemainingPath(buffer, parts, out bool stale);
/// foreach (var part in parts) {
/// for (int i = part.startIndex; i < part.endIndex; i++) {
/// Debug.DrawLine(buffer[i], buffer[i+1], part.type == Funnel.PartType.NodeSequence ? Color.red : Color.green);
/// }
/// }
///
/// [Open online documentation to see images]
///
/// Note: The and movement scripts do not know about off-mesh links, so the partsBuffer will always be filled with a single node-sequence part.
///
/// The buffer will be cleared and replaced with the path. The first point is the current position of the agent.
/// If not null, this list will be cleared and filled with information about the different parts of the path. A part is a sequence of nodes or an off-mesh link.
/// May be true if the path is invalid in some way. For example if the agent has no path or (for the RichAI/FollowerEntity components only) if the agent has detected that some nodes in the path have been destroyed.
void GetRemainingPath(List buffer, List partsBuffer, out bool stale);
///
/// Recalculate the current path.
/// You can for example use this if you want very quick reaction times when you have changed the
/// so that the agent does not have to wait until the next automatic path recalculation (see .
///
/// 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 ).
///
/// If no 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 property will return true.
///
/// See:
///
void SearchPath();
///
/// 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 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.
///
/// If you pass null as a parameter then the current path will be cleared and the agent will stop moving.
/// Note than unless you have also disabled then the agent will soon recalculate its path and start moving again.
///
/// You can disable the automatic path recalculation by setting the field to false.
///
/// Note: This call will be ignored if the agent is currently traversing an off-mesh link. Furthermore, if the agent starts traversing an off-mesh link, the current path request will be canceled (if one is currently in progress).
///
///
/// // 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);
///
///
/// The path to follow.
/// If true, the \reflink{destination} property will be set to the end point of the path. If false, the previous destination value will be kept.
void SetPath(Path path, bool updateDestinationFromPath = 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
/// it is recommended that you set the before calling this method.
///
/// The current path will be cleared by default.
///
/// This method is preferred for long distance teleports. If you only move the agent a very small distance (so that it is reasonable that it can keep its current path),
/// then setting the property is preferred.
/// When using the movement script, setting the property when using a long distance teleport could cause the agent to fail to move the full distance, as it can get blocked by the navmesh.
///
/// See: Works similarly to Unity's NavmeshAgent.Warp.
/// See:
///
void Teleport(Vector3 newPosition, bool clearPath = true);
///
/// Move the agent.
///
/// 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 script) if it does not have
/// any concept of being moved externally.
///
/// For the and movement scripts, 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);
///
///
/// The movement script will, on the other hand, move the agent immediately.
///
/// Direction and distance to move the agent in world space.
void Move(Vector3 deltaPosition);
///
/// Calculate how the character wants to move during this frame.
///
/// Note that this does not actually move the character. You need to call for that.
/// This is called automatically unless is false.
///
/// To handle movement yourself you can disable 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);
/// }
///
///
/// time to simulate movement for. Usually set to Time.deltaTime.
/// the position that the agent wants to move to during this frame.
/// the rotation that the agent wants to rotate to during this frame.
void MovementUpdate(float deltaTime, out Vector3 nextPosition, out 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: for a code example.
///
void FinalizeMovement(Vector3 nextPosition, Quaternion nextRotation);
}
}