Advancing Along Paths

Moving agents along paths involves interpolating positions along path sections, because this involves approximation this can be surprisingly tricky.
(Refer to Why Integer Coordinates? for a discussion of some issues relating to approximation.)

PathEngine provides built-in functionality for advancing agent's along paths robustly, in the form of iAgent::advanceAlongPath(), iAgent::advanceAlongPathWithPrecision(), iAgent::advanceAlongPathWithCollisionInfo(), iPath::advanceAlong() and iPath::advanceAlongWithCollisionInfo().

These methods ensure that an approximate position is found at which the agent can be placed at each step along the path, such that the agent is guaranteed not to enter obstructed space for the working context, or to move through any thin obstructions.

Each method works by modifying an existing path object, such that the agent position is always the first position in the path, and the path object then essentially represents remaining path to goal.
(The methods on the iAgent interface move the agent forward, as well as updating the path object.)

Agents are advanced smoothly around path corners and (in the versions with precision components) floating point precision components are maintained to ensure that agent movement renders smoothly.

Colliding with dynamic obstacles

The collision context passed in to the advance along path methods may differ from the collision context used to initially build the path, so it's possible for movement along the path to be blocked by dynamic obstacles.
In this case, you can use iAgent::advanceAlongPathWithCollisionInfo() to obtain some extra information about the collision (in the same way as the 'first collision' functionality).

Advancing along paths with off-mesh connections

(Refer to Off‑Mesh Connections for a description of the off-mesh connections feature.)

When advancing along paths with off-mesh connections PathEngine will stop the agent at each connection endpoint on the frame in which that endpoint is reached.
The client application is now expected to detect the fact that an off-mesh connection has been reached, and take appropriate action.
The client application is resonsible for managing the agent's actual position as they move off-mesh and for determining when the agent actually arrives at the target endpoint.
The next time an advance along path method is called for the path, the agent shape is moved directly to the target endpoint of the connection.

Managing obstructed target endpoints

If either of the endpoints for an off-mesh connection are obstructed by the collision context passed in to a pathfinding request then that connection won't be taken.
It is possible, however, for obstacles to be moved to obstruct endpoints while an agent is advancing along a path.
It is also possible to pass a different context into the advanceAlongPath() methods than was used to initally build the path.
It is important to note, then, that in cases where an agent is advanced across an off-mesh connection with destination endpoint blocked by a dynamic obstacle PathEngine will permit the advancing agent to 'land inside' the blocking agent.

In some cases this behaviour is desirable, and the client application can either ignore the fact that an agent may be inside a dynamic obstacle (because PathEngine will always enable agents to pathfind out of this kind of situation) or detect the collision on arrival and handle this appropriately.
In cases where other behaviour is desired it is straightforward for the client application to check the destination endpoint explicitly before advancing into the off-mesh connection.