Class FollowerEntity Extends VersionedMonoBehaviour, IAstarAI, ISerializationCallbackReceiver

ECS.AutoRepathPolicy autoRepath

Policy for when the agent recalculates its path.

bool canMove

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.

Disabling this will remove the SimulateMovement component from the entity, which prevents most systems from running for this entity.

When disabled, the velocity property will no longer update.

GraphNode currentNode

Node which the agent is currently traversing.

You can, for example, use this to make the agent use a different animation when traversing nodes with a specific tag.

When traversing an off-mesh link, this will return the final non-link node in the path before the agent started traversing the link.

PIDMovement.DebugFlags debugFlags

Enables or disables debug drawing for this agent.

This is a bitmask with multiple flags so that you can choose exactly what you want to debug.

Vector3 desiredVelocity

Velocity that this agent wants to move with.

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

Vector3 desiredVelocityWithoutLocalAvoidance

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;


If you are not using local avoidance then this property will in almost all cases be identical to desiredVelocity plus some noise due to floating point math.

Vector3? destination

Position in the world that this agent should move to.

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

Setting this property will immediately try to repair the path if the agent already has a path. This will also immediately update properties like reachedDestination, reachedEndOfPath and remainingDistance.

The agent may do a full path recalculation if the local repair was not sufficient, but this will at earliest happen in the next simulation step.

IEnumerator Start () {
ai.destination = somePoint;
// Wait until the AI has reached the destination
while (!ai.reachedEndOfPath) {
yield return null;
}
// The agent has reached the destination now
}


bool enableGravity

Enables or disables gravity.

If gravity is enabled, the agent will accelerate downwards, and use a raycast to check if it should stop falling.

This has no effect if the agent's orientation is set to YAxisForward (2D mode). Gravity does not really make sense for top-down 2D games. The gravity setting is also hidden from the inspector in this mode.

bool enableLocalAvoidance

True if local avoidance is enabled for this agent.

Enabling this will automatically add a Pathfinding.ECS.RVO.RVOAgent component to the entity.

Vector3 endOfPath

End point of path the agent is currently following.

If the agent has no path (or if it's not calculated yet), this will return the destination 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 destination, but it may differ if the path for example was blocked by a wall, so that the agent couldn't get any closer.

Entity entity

Entity which this movement script represents.

An entity will be created when this script is enabled, and destroyed when this script is disabled.

Check the class documentation to see which components it usually has, and what systems typically affect it.

bool entityExists

True if this component's entity exists.

This is typically true if the component is active and enabled and the game is running.

LayerMask groundMask

Determines which layers the agent will stand on.

The agent will use a raycast each frame to check if it should stop falling.

This layer mask should ideally not contain the agent's own layer, if the agent has a collider, as this may cause it to try to stand on top of itself.

bool hasPath

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

This is true if the agent has a path and the path is not stale.

A path may become stale if the graph is updated close to the agent and it hasn't had time to recalculate its path yet.

float height

Height of the agent in world units.

This is visualized in the scene view as a yellow cylinder around the character.

This value is used for various heuristics, and for visualization purposes. For example, the destination is only considered reached if the destination is not above the agent's head, and it's not more than half the agent's height below its feet.

If local lavoidance is enabled, this is also used to filter out collisions with agents and obstacles that are too far above or below the agent.

bool isStopped

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.

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

bool isTraversingOffMeshLink

True if the agent is currently traversing an off-mesh link.

float maxRotationSpeed

Maximum rotation speed in degrees per second.

If the agent would have to rotate faster than this, it will instead slow down to get more time to rotate.

The agent may want to rotate faster than rotationSpeed if there's not enough space, so that it has to move in a more narrow arc. It may also want to rotate faster if it is very close to its destination and it wants to make sure it ends up on the right spot without any circling.

It is recommended to keep this at a value slightly larger than rotationSpeed.

float maxSpeed

Max speed in world units per second.

ManagedMovementOverrides movementOverrides

Provides callbacks during various parts of the movement calculations.

With this property you can register callbacks that will be called during various parts of the movement calculations. These can be used to modify movement of the agent.

The following example demonstrates how one can hook into one of the available phases and modify the agent's movement. In this case, the movement is modified to become wavy.

using Pathfinding;
using Pathfinding.ECS;
using Unity.Entities;
using Unity.Mathematics;
using Unity.Transforms;
using UnityEngine;

public class MovementModifierNoise : MonoBehaviour {
public float strength = 1;
public float frequency = 1;
float phase;

public void Start () {
// Register a callback to modify the movement.
// This will be called during every simulation step for the agent.
// This may be called multiple times per frame if the time scale is high or fps is low,
// or less than once per frame, if the fps is very high.
GetComponent<FollowerEntity>().movementOverrides.AddBeforeControlCallback(MovementOverride);

// Randomize a phase, to make different agents behave differently
phase = UnityEngine.Random.value * 1000;
}

public void OnDisable () {
// Remove the callback when the component is disabled
GetComponent<FollowerEntity>().movementOverrides.RemoveBeforeControlCallback(MovementOverride);
}

public void MovementOverride (Entity entity, float dt, ref LocalTransform localTransform, ref AgentCylinderShape shape, ref AgentMovementPlane movementPlane, ref DestinationPoint destination, ref MovementState movementState, ref MovementSettings movementSettings) {
// Rotate the next corner the agent is moving towards around the agent by a random angle.
// This will make the agent appear to move in a drunken fashion.

// Don't modify the movement as much if we are very close to the end of the path
var strengthMultiplier = Mathf.Min(1, movementState.remainingDistanceToEndOfPart / Mathf.Max(shape.radius, movementSettings.follower.slowdownTime * movementSettings.follower.speed));
strengthMultiplier *= strengthMultiplier;

// Generate a smoothly varying rotation angle
var rotationAngleRad = strength * strengthMultiplier * (Mathf.PerlinNoise1D(Time.time * frequency + phase) - 0.5f);
// Clamp it to at most plus or minus 90 degrees
rotationAngleRad = Mathf.Clamp(rotationAngleRad, -math.PI*0.5f, math.PI*0.5f);

// Convert the rotation angle to a world-space quaternion.
// We use the movement plane to rotate around the agent's up axis,
// making this code work in both 2D and 3D games.
var rotation = movementPlane.value.ToWorldRotation(rotationAngleRad);

// Rotate the direction to the next corner around the agent
movementState.nextCorner = localTransform.Position + math.mul(rotation, movementState.nextCorner - localTransform.Position);
}
}
There are a few different phases that you can register callbacks for:

• BeforeControl: Called before the agent's movement is calculated. At this point, the agent has a valid path, and the next corner that is moving towards has been calculated.

• AfterControl: Called after the agent's desired movement is calculated. The agent has stored its desired movement in the MovementControl component. Local avoidance has not yet run.

• BeforeMovement: Called right before the agent's movement is applied. At this point the agent's final movement (including local avoidance) is stored in the ResolvedMovement component, which you may modify.

The callbacks may be called multiple times per frame, if the fps is low, or if the time scale is high. It may also be called less than once per frame if the fps is very high. Each callback is provided with a dt parameter, which is the time in seconds since the last simulation step. You should prefer using this instead of Time.deltaTime.

NativeMovementPlane movementPlane

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 Worlds), the the movement plane will be the tangent plane of the sphere at the agent's position.

MovementPlaneSource movementPlaneSource

How to calculate which direction is "up" for the agent.

In almost all cases, you should use the Graph option. This will make the agent use the graph's natural "up" direction. However, if you are using a spherical world, or a world with some other strange shape, then you may want to use the NavmeshNormal or Raycast options.

MovementSettings movementSettings

Various movement settings.

Some of these settings are exposed on the FollowerEntity directly. For example maxSpeed.

OffMeshLinks.OffMeshLinkTracer offMeshLink

The off-mesh link that the agent is currently traversing.

This will be a default OffMeshLinks.OffMeshLinkTracer if the agent is not traversing an off-mesh link (the OffMeshLinks.OffMeshLinkTracer.link field will be null).

IOffMeshLinkHandler onTraverseOffMeshLink

Callback to be called when an agent starts traversing an off-mesh link.

The handler will be called when the agent starts traversing an off-mesh link. It allows you to to control the agent for the full duration of the link traversal.

Use the passed context struct to get information about the link and to control the agent.

using UnityEngine;
using Pathfinding;
using System.Collections;
using Pathfinding.ECS;

namespace Pathfinding.Examples {
public class FollowerJumpLink : MonoBehaviour, IOffMeshLinkHandler, IOffMeshLinkStateMachine {
// Register this class as the handler for off-mesh links when the component is enabled
void OnEnable() => GetComponent<NodeLink2>().onTraverseOffMeshLink = this;
void OnDisable() => GetComponent<NodeLink2>().onTraverseOffMeshLink = null;

IOffMeshLinkStateMachine IOffMeshLinkHandler.GetOffMeshLinkStateMachine(AgentOffMeshLinkTraversalContext context) => this;

void IOffMeshLinkStateMachine.OnFinishTraversingOffMeshLink (AgentOffMeshLinkTraversalContext context) {
Debug.Log("An agent finished traversing an off-mesh link");
}

void IOffMeshLinkStateMachine.OnAbortTraversingOffMeshLink () {
Debug.Log("An agent aborted traversing an off-mesh link");
}

IEnumerable IOffMeshLinkStateMachine.OnTraverseOffMeshLink (AgentOffMeshLinkTraversalContext ctx) {
var start = (Vector3)ctx.link.relativeStart;
var end = (Vector3)ctx.link.relativeEnd;
var dir = end - start;

// Disable local avoidance while traversing the off-mesh link.
// If it was enabled, it will be automatically re-enabled when the agent finishes traversing the link.
ctx.DisableLocalAvoidance();

// Move and rotate the agent to face the other side of the link.
// When reaching the off-mesh link, the agent may be facing the wrong direction.
while (!ctx.MoveTowards(
position: start,
rotation: Quaternion.LookRotation(dir, ctx.movementPlane.up),
gravity: true,
slowdown: true).reached) {
yield return null;
}

var bezierP0 = start;
var bezierP1 = start + Vector3.up*5;
var bezierP2 = end + Vector3.up*5;
var bezierP3 = end;
var jumpDuration = 1.0f;

// Animate the AI to jump from the start to the end of the link
for (float t = 0; t < jumpDuration; t += ctx.deltaTime) {
ctx.transform.Position = AstarSplines.CubicBezier(bezierP0, bezierP1, bezierP2, bezierP3, Mathf.SmoothStep(0, 1, t / jumpDuration));
yield return null;
}
}
}
}


You can alternatively set the corresponding property property on the off-mesh link ( NodeLink2.onTraverseOffMeshLink) to specify a callback for a specific off-mesh link.

OrientationMode orientation

Determines which direction the agent moves in.

For 3D games you most likely want the ZAxisIsForward option as that is the convention for 3D games.
For 2D games you most likely want the YAxisIsForward option as that is the convention for 2D games.

When using ZAxisForard, the +Z axis will be the forward direction of the agent, +Y will be upwards, and +X will be the right direction.
When using YAxisForward, the +Y axis will be the forward direction of the agent, +Z will be upwards, and +X will be the right direction.

bool pathPending

True if a path is currently being calculated.

refPathRequestSettings pathfindingSettings

Pathfinding settings.

The settings in this struct controls how the agent calculates paths to its destination.

This is analogous to the Seeker component used for other movement scripts.

Vector3 position

Position of the agent.

In world space.

If you want to move the agent you may use Teleport or Move.

float positionSmoothing

How much to smooth the visual position of the agent.

This does not affect movement, but smoothes out the position of the agent visually.

Recommended values are between 0.0 and 0.5. A value of zero will disable smoothing completely.

This will make the agent seem to lag slightly behind the internal position of the agent. It may also cut corners slightly.

The unit for this field is seconds.

float radius

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.

bool reachedDestination

True if the ai has reached the destination.

The agent considers the destination reached when it is within stopDistance world units from the destination. Additionally, the destination must not be above the agent's head, and it must not be more than half the agent's height below its feet.

If a facing direction was specified when setting the destination, this will only return true once the agent is approximately facing the correct orientation.

This value will be updated immediately when the destination 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
}


bool reachedEndOfPath

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

The agent considers the end of the path reached when it is within stopDistance world units from the end of the path. Additionally, the end of the path must not be above the agent's head, and it must not be more than half the agent's height below its feet.

If a facing direction was specified when setting the destination, this will only return true once the agent is approximately facing the correct orientation.

This value will be updated immediately when the destination is changed.

float remainingDistance

Approximate remaining distance along the current path to the end of the path.

The agent does not know the true distance at all times, so this is an approximation. It tends to be a bit lower than the true distance.

This value will update immediately if the destination property is changed, or if the agent is moved using the position property or the Teleport method.

If the agent has no path, or if the current path is stale (e.g. if the graph has been updated close to the agent, and it hasn't had time to recalculate its path), this will return positive infinity.

Quaternion rotation

Rotation of the agent.

In world space.

The entity internally always treats the Z axis as forward, but this property respects the orientation field. So it will return either a rotation with the Y axis as forward, or Z axis as forward, depending on the orientation field.

This will return the agent's rotation even if updateRotation is false.

float rotationSmoothing

How much to smooth the visual rotation of the agent.

This does not affect movement, but smoothes out how the agent rotates visually.

Recommended values are between 0.0 and 0.5. A value of zero will disable smoothing completely.

The smoothing is done primarily using an exponential moving average, but with a small linear term to make the rotation converge faster when the agent is almost facing the desired direction.

Adding smoothing will make the visual rotation of the agent lag a bit behind the actual rotation. Too much smoothing may make the agent seem sluggish, and appear to move sideways.

The unit for this field is seconds.

float rotationSpeed

Desired rotation speed in degrees per second.

If the agent is in an open area and gets a new destination directly behind itself, it will start to rotate around with exactly this rotation speed.

The agent will slow down its rotation speed as it approaches its desired facing direction. So for example, when it is only 90 degrees away from its desired facing direction, it will only rotate with about half this speed.

refRVOAgent rvoSettings

Local avoidance settings.

Vector3 steeringTarget

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.

float stopDistance

How far away from the destination should the agent aim to stop, in world units.

If the agent is within this distance from the destination point it will be considered to have reached the destination.

Even if you want the agent to stop precisely at a given point, it is recommended to keep this slightly above zero. If it is exactly zero, the agent may have a hard time deciding that it has actually reached the end of the path, due to floating point errors and such.

bool updatePosition

Determines if the character's position should be coupled to the Transform's position.

If false then all movement calculations will happen as usual, but the GameObject that this component is attached to will not move. Instead, only the position property and the internal entity's position will change.

This is useful if you want to control the movement of the character using some other means, such as root motion, but still want the AI to move freely.

bool updateRotation

Determines if the character's rotation should be coupled to the Transform's rotation.

If false then all movement calculations will happen as usual, but the GameObject that this component is attached to will not rotate. Instead, only the rotation property and the internal entity's rotation will change.

This is particularly useful for 2D games where you want the Transform to stay in the same orientation, and instead swap out the displayed sprite to indicate the direction the character is facing.

You can enable PIDMovement.DebugFlags.Rotation in debugFlags to draw a gizmos arrow in the scene view to indicate the agent's internal rotation.

Vector3? velocity

Actual velocity that the agent is moving with.

In world units per second.

This is useful for, for example, selecting which animations to play, and at what speeds.

FollowerEntityMigrations

NNConstraint ScratchNNConstraint = NNConstraint.Walkable

Cached NNConstraint, to avoid allocations.

Color ShapeGizmoColor = new Color(240/255f, 213/255f, 30/255f)

World achetypeWorld

EntityAccess<AgentCylinderShape> agentCylinderShapeAccessRO = new EntityAccess<AgentCylinderShape>(true)

EntityAccess<AgentCylinderShape> agentCylinderShapeAccessRW = new EntityAccess<AgentCylinderShape>(false)

EntityAccess<AgentOffMeshLinkTraversal> agentOffMeshLinkTraversalRO = new EntityAccess<AgentOffMeshLinkTraversal>(true)

EntityArchetype archetype

ECS.AutoRepathPolicy autoRepathBacking = ECS.AutoRepathPolicy.Default

EntityAccess<ECS.AutoRepathPolicy> autoRepathPolicyRW = new EntityAccess<ECS.AutoRepathPolicy>(false)

Vector3? destinationFacingDirection

Direction the agent will try to face when it reaches the destination.

If this is zero, the agent will not try to face any particular direction.

The following video shows three agents, one with no facing direction set, and then two agents with varying values of the lead in radius.

EntityAccess<DestinationPoint> destinationPointAccessRO = new EntityAccess<DestinationPoint>(true)

EntityAccess<DestinationPoint> destinationPointAccessRW = new EntityAccess<DestinationPoint>(false)

EntityStorageCache entityStorageCache

NativeArray<int> indicesScratch

EntityAccess<LocalTransform> localTransformAccessRO = new EntityAccess<LocalTransform>(true)

EntityAccess<LocalTransform> localTransformAccessRW = new EntityAccess<LocalTransform>(false)

ManagedState managedState = new ManagedState { enableLocalAvoidance = false, pathfindingSettings = PathRequestSettings.Default, }

ManagedEntityAccess<ManagedState> managedStateAccessRO = new ManagedEntityAccess<ManagedState>(true)

ManagedEntityAccess<ManagedState> managedStateAccessRW = new ManagedEntityAccess<ManagedState>(false)

MovementSettings movement = new MovementSettings { follower = new PIDMovement { rotationSpeed = 600, speed = 5, maxRotationSpeed = 720, maxOnSpotRotationSpeed = 720, slowdownTime = 0.5f, desiredWallDistance = 0.5f, allowRotatingOnSpot = true, leadInRadiusWhenApproachingDestination = 1f, }, stopDistance = 0.2f, rotationSmoothing = 0f, groundMask = -1, isStopped = false, }

EntityAccess<MovementControl> movementControlAccessRO = new EntityAccess<MovementControl>(true)

EntityAccess<MovementControl> movementControlAccessRW = new EntityAccess<MovementControl>(false)

EntityAccess<MovementStatistics> movementOutputAccessRW = new EntityAccess<MovementStatistics>(false)

EntityAccess<AgentMovementPlane> movementPlaneAccessRO = new EntityAccess<AgentMovementPlane>(false)

EntityAccess<AgentMovementPlane> movementPlaneAccessRW = new EntityAccess<AgentMovementPlane>(false)

MovementPlaneSource movementPlaneSourceBacking = MovementPlaneSource.Graph

EntityAccess<MovementSettings> movementSettingsAccessRO = new EntityAccess<MovementSettings>(true)

EntityAccess<MovementSettings> movementSettingsAccessRW = new EntityAccess<MovementSettings>(false)

EntityAccess<MovementState> movementStateAccessRO = new EntityAccess<MovementState>(true)

EntityAccess<MovementState> movementStateAccessRW = new EntityAccess<MovementState>(false)

EntityAccess<MovementStatistics> movementStatisticsAccessRW = new EntityAccess<MovementStatistics>(false)

NativeList<float3> nextCornersScratch

Action onSearchPath

Called when the agent recalculates its path.

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

OrientationMode orientationBacking

Determines which direction the agent moves in.

EntityAccess<ReadyToTraverseOffMeshLink> readyToTraverseOffMeshLinkRW = new EntityAccess<ReadyToTraverseOffMeshLink>(false)

EntityAccess<ResolvedMovement> resolvedMovementAccessRO = new EntityAccess<ResolvedMovement>(true)

EntityAccess<ResolvedMovement> resolvedMovementAccessRW = new EntityAccess<ResolvedMovement>(false)

int scratchReferenceCount = 0

AgentCylinderShape shape = new AgentCylinderShape { height = 2, radius = 0.5f, }

bool syncPosition = true

Determines if the character's position should be coupled to the Transform's position.

If false then all movement calculations will happen as usual, but the GameObject that this component is attached to will not move. Instead, only the position property and the internal entity's position will change.

This is useful if you want to control the movement of the character using some other means, such as root motion, but still want the AI to move freely.

bool syncRotation = true

Determines if the character's rotation should be coupled to the Transform's rotation.

If false then all movement calculations will happen as usual, but the GameObject that this component is attached to will not rotate. Instead, only the rotation property and the internal entity's rotation will change.

This is particularly useful for 2D games where you want the Transform to stay in the same orientation, and instead swap out the displayed sprite to indicate the direction the character is facing.

You can enable PIDMovement.DebugFlags.Rotation in debugFlags to draw a gizmos arrow in the scene view to indicate the agent's internal rotation.

Transform tr

Cached transform component.

bool canSearch

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.