Monitoring PathEvents

PathEvent Overview

The LivePath owned by each Bot maintains a list of various kinds of events along the path:

The lower bound of the LivePath. This is a position that lies roughly 20 meters behind the current position of the Bot, and that is moved forward along the path automatically as the Bot follows its path. Behind the lower bound, the validity of the path is not checked and kept up to date, since the Bot is assumed to be finished with that segment of its path.
Each transition to a different NavTag along the course of the path.
Each vertex in each NavGraph that is used as part of the path.
Each transition between the NavMesh and a path edge that crosses the outside boundary of the NavMesh.
The upper bound of the LivePath. This is the last position along the path that is known to be valid and accessible. Typically, the upper bound lies at the destination point of the path computation request, but not always: if the NavData changes, rendering the destination point inaccessible, the upper bound will automatically be moved back along the LivePath to the position of the last event that is valid and accessible.

Each of these events is represented by a PathEvent object. The LivePath maintains a PathEventList: an indexed list of these PathEvents, and an indexed list of the "intervals" that lie between the events. You can use the data members maintained by the PathEvent object to determine the type of event it represents, find its 3D position, get and set its check point status (see Using Check Points), etc.

Browsing the PathEventList

You can retrieve the full list of events on the LivePath by calling Bot::GetPathEventList(). You can then use the methods of the PathEventList class to iterate through all the events in the list.

Using the target point

The full list of PathEvents includes events that lie behind the current position and target point of the Bot: for example, the lower bound, and any events that the Bot has already passed by or chosen to shortcut past. You may want to know which events are upcoming, and which have been bypassed already. For example, you might only care about events that lie forward along the path within a certain distance.

You can use the current target point to determine which events lie in front of the Bot.

Call Bot::GetProgressOnLivePath() to get a PositionOnLivePath object that represents the current point along the path that the path following system considers the Bot to have reached.
Call the PositionOnLivePath::GetOnEventListStatus() method to determine whether the current progress point lies on an event (OnEventListStatus_OnEvent) or on an interval between two events (OnEventListStatus_OnInterval).
Call the PositionOnLivePath::GetOnEventListIndex() method to get the index of the event or interval within the overall PathEventList. Any events or intervals with indexes lower than this value are behind the Bot; any with higher indexes are upcoming on the path.
You can also call PositionOnLivePath::GetNextPathEventIdx() and PositionOnLivePath::GetPrevPathEventIdx(). However, see the descriptions in the API reference for details on interpreting the return values.

Getting the next NavTag

Often, the item of information that you really need to know is simply the NavTag associated with the next event. For example, if that NavTag is associated with a smart object, you might want your Bot to begin asking the smart object for instructions.

You can determine the NavTag of the next event without needing to interact directly with the PathEventList simply by calling Bot::GetUpcomingEventNavTag().

Registering for Notification of new PathEvents

Instead of actively checking the list of path events to test for certain conditions, you can register a custom event observer object when you initialize your Bot. The Bot invokes the methods of this observer whenever it creates, updates or destroys a PathEventList, allowing you to respond to events on the new path.

This may be useful in order to carry out custom initialization steps that need to be performed, such as registering and unregistering your Bots with custom smart objects. For example, if a new path uses a door that can become closed during gameplay, you might want to register the Bot with the object that controls the door. Then, when the door becomes closed, your door can inform the characters that had planned to use it. Your character could respond to this by triggering a path re-computation.

To use this approach:

Write a custom class that derives from IPathEventListObserver and that implements its virtual methods.
Write your own class that derives from either the BaseNavigationProfile or NavigationProfile class, and make your implementation of BaseNavigationProfile::GetSharedPathEventListObserver() return a pointer to an instance of your IPathEventListObserver class.
Set up your World and Bots to use your new NavigationProfile. For details, see Customizing Path Following.

For a code example, see the Tutorial_NavTag.cpp file.

For an example implementation, see the DefaultPathEventListObserver class. If you do not provide your own observer as described above, the default NavigationProfile class uses an instance of DefaultPathEventListObserver, which marks as check points each event that corresponds to a NavGraph vertex or a transition between the NavMesh and a path edge that crosses the outside boundary of the NavMesh. By default, this makes characters approach and follow NavGraph edges without shortcutting. If you want to keep this behavior in your own implementation, consider deriving your class from DefaultPathEventListObserver, and calling its implementations of the interface from the methods in your own class.

For more information about check points, see also Using Check Points.