Working with Off-Mesh Connections

Refer to Off‑Mesh Connections for an initial overview of the functionality provided for representing off-mesh movement possibilities for agents.

Static and dynamic off-mesh connections

In most cases off-mesh connection possibilities can be defined 'statically', e.g. at content generation time, before pathfinding preprocess has been generated for a mesh.
This enables the connection possibilities to be essentially compiled in to the pathfinding graph, for fastest possible treatment.
These kinds of connections are managed through the iMesh interface, with any connections added to a mesh then being saved out together with the ground mesh information.

PathEngine supports fast run-time modification of the penalty values associated with static off-mesh connections, which includes the possibility to turn individual off-mesh connections on and off.

In some cases it can also be desirable for off mesh possibilities to be added to a mesh completely dynamically, i.e. between endpoints that were not known at content time.
Examples might be to enable AI controlled characters to follow a player character after a jump, or to take something like a dynamically placed ladder or bridge into account.
This is then also supported through the 'run-time off mesh connection' functionality exposed through iCollisionContext.

Automating off-mesh connection generation

PathEngine provides a framework for automated generation of off-mesh connections, based on an application supplied callback for validation of generated connection candidates, through iMesh::autoGenerateConnections().

API details

Static off-mesh connections are added to a mesh with the following methods:

• iMesh::addEndPoint()
• iMesh::addOffMeshConnection()

Note that the start and end endpoint pair for each connection added to a mesh should be unique for that mesh, i.e. no two off mesh connections on a mesh should share

both

either

All static off-mesh connections and endpoints can be stripped from a mesh by calling iMesh::clearOffMeshConnectionsAndEndPoints().

The connections and endpoints associated with a mesh can be queried with the following methods:

• iMesh::getNumberOfEndPoints()
• iMesh::getEndPoint()
• iMesh::getNumberOfOffMeshConnections()
• iMesh::getOffMeshConnectionInfo()

Note that the set of off-mesh connections associated with a mesh cannot be changed after preprocess has been generated or loaded for that mesh.

Static connection penalty values can be modified, for a given pathfinding collision context, with iCollisionContext::setOverlayConnectionPenalty().
Use iCollisionContext::clearOverlayConnectionPenalties() to subsequently clear any overlay penalty values and return to the default set of connection costs.

Helper methods iCollisionContext::hasOverlayConnectionPenalties() and iCollisionContext::getOverlayConnectionPenalty() are available to check the current state of connection penalty overlays on a given pathfinding context, at any given moment.

Dynamic, or run-time, off-mesh connections can be added to a pathfinding collision context with iCollisionContext::addRunTimeOffMeshConnection(), and then removed individually with iCollisionContext::removeRunTimeOffMeshConnection() or all run-time connections on a context removed with iCollisionContext::clearRunTimeOffMeshConnections().

Working with paths that contain off-mesh connections

Paths containing off-mesh connections simply include the endpoints before and after the connection in sequence.
A method is provided to enable the application to check whether a given path segment corresponds to an off-mesh movement.
For details about using PathEngine's advance along path functionality with off-mesh connections, refer to this page.

Managing off-mesh connection IDs

Any off-mesh connections used for a path are identified through connection IDs.

For static off-mesh connections, connection IDs are returned by the addOffMeshConnection() method, and are essentially then simple indexes into the set of off-mesh connections added to the mesh.
On the application side, these indexes can then be used to reference a parallel array of application specific information relating to each connection.

IDs for dynamic off-mesh connections work differently.
These are determined by the application and passed as parameters in to iCollisionContext::addRunTimeOffMeshConnection(), with no requirement in this case for the connectionID values to be unique.

In many cases there may be no need for unique dynamic connection IDs, for example these ID values could be used to simply store codes for the type of movement required to traverse each connection.

If unique connection references are required for dynamic off-mesh connections then this is something that needs to be managed by application code, taking into account the fact that paths referencing run-time off-mesh connection ID values may persist after the corresponding connections have been removed.
(A simple approach, assuming a small number of run-time off-mesh connections at any one time, could be to just increment a counter each time a new connection is added, with a simple search through all current run-time connections for a matching ID, each time a run-time connection is encountered on a path.)

It is also up to application code to ensure that it is possible to distinguish between static and dynamic connection IDs, in case both types of connections are being used simultaneously.
(This can be done, for example, by offsetting dynamic connection IDs by the total number of static connections, or using negative values for dynamic connection IDs.)