addRunTimeOffMeshConnection

previous: iCollisionContext::addObstacleSet()

Contents, API Reference, Interfaces, iCollisionContext, addRunTimeOffMeshConnection

iCollisionContext::addRunTimeOffMeshConnection()

Description

Tells PathEngine about the possibility for agents to move 'off-mesh' between a pair of endpoints, with this movement possibility specified completely dynamically at run-time.

Syntax

int32_t addRunTimeOffMeshConnection(const cPosition& fromPosition, const cPosition& toPosition, int32_t forwardPenalty, int32_t backPenalty, int32_t forwardConnectionID, int32_t backConnectionID);

Parameters

	fromPosition		The start position for the off-mesh connection. This must be a valid cPosition on this mesh.
	toPosition		The end position for the off-mesh connection. This must be a valid cPosition on this mesh.
	forwardPenalty		A penalty value for traversing the off-mesh connection forward, so from fromPosition to toPosition. This value is added to the straight line cost of movement between the endpoints, and must be in the range 0 to 10000.
	backPenalty		A penalty value for traversing the off-mesh connection in reverse, so from toPosition to fromPosition. A special value of -1 may be specified for this parameter, to indicate that the connection may not be traversed in the reverse direction. Otherwise, this value is added to the straight line cost of movement between the endpoints, and must be in the range 0 to 10000.
	forwardConnectionID		Some application defined value to identify forward movement along this connection. Any value other than -1 may be specified here (but see the note about potential collisions with static off mesh connection indexes, below).
	backConnectionID		Some application defined value to identify backward movement along this connection. Any value other than -1 may be specified here (but see the note about potential collisions with static off mesh connection indexes, below).

Return Value

A run time off mesh connection 'handle', that can later be passed in to iCollisionContext::removeRunTimeOffMeshConnection().

Remarks

The values specified for forwardConnectionID and backConnectionID will be reported back for the connection by the iPath interface in the case where a path uses this run-time off mesh connection (in the relevant direction).

Note that connection ID values are distinct from the 'handle' value returned by this method to identify the connection for the removal.
There is no requirement, then, for these connection IDs to be unique. In some cases run-time connection IDs can be used just to specify a type of movement for the off-mesh connection.

When run-time off-mesh connections are used together with static off-mesh connections (i.e. off-mesh connections added through the iMesh interface) it is up to the application code to avoid ID collision between these different types of off-mesh connections (for example by offsetting all run-time connection IDs values by the total number of off-mesh connections on the base mesh, or by using negative values other than -1 for run-time connection IDs).

See Off‑Mesh Connections for an overview of the off-mesh connection functionality, and Working with Off‑Mesh Connections for information about other methods relating to this functionality.

C# Mapping

int addRunTimeOffMeshConnection(PathEngine.Position fromPosition, PathEngine.Position toPosition, int forwardPenalty, int backPenalty, int forwardConnectionID, int backConnectionID);

Java Mapping

int addRunTimeOffMeshConnection(Position fromPosition, Position toPosition, int forwardPenalty, int backPenalty, int forwardConnectionID, int backConnectionID);

next: iCollisionContext::clear()