[This is preliminary documentation and is subject to change.]

Represents a dynamic polygon corridor used to plan client movement.

Namespace: org.critterai.nav
Assembly: cai-nav (in cai-nav.dll) Version: 0.4.0.0 (0.4.0.0)

Syntax

         
 C#  Visual Basic  Visual C++ 
public sealed class PathCorridor : IManagedObject
Public NotInheritable Class PathCorridor _
	Implements IManagedObject
public ref class PathCorridor sealed : IManagedObject

Members

            
 All Members  Constructors   Properties   Methods  
 Public

 Protected
 Instance

 Static 
 Declared

 Inherited
 XNA Framework Only 

 .NET Compact Framework Only 

 MemberDescription
PathCorridor(Int32, Int32, NavmeshQuery, NavmeshQueryFilter)
Constructor.
Corners
The straight path corners for the corridor. (The string-pulled path.)
Filter
The query filter used by the corridor.
Finalize()()()()
Destructor.
(Overrides Object..::..Finalize()()()().)
FindCorners(CornerData)
Finds the corners in the corridor from the position toward the target. (The straightened path.)
GetData(PathCorridorData)
Loads the corridor data into the provided PathCorridorData buffer.
GetPath(array<UInt32>[]()[][])
Obtains a copy of the corridor path.
GetPathCount()()()()
The number of polygons in the corridor path.
IsDisposed
True if the object has been disposed and should no longer be used.
IsValid(Int32)
Checks the corridor path to see if its polygon references remain valid.
Item[([( Int32])])
The corner point for the specified index.
LoadLocals(PathCorridor, NavmeshPoint, NavmeshQuery, NavmeshQueryFilter)
Sets the specified resources and resets the corridor.
MaxCorners
The maximum number of corners that the corner buffer can hold.
MaxPathSize
The maximum path size that can be handled by the corridor.
Move(Vector3, Vector3)
Moves the position and target from their curent locations to the desired locations.
MoveOverConnection(UInt32, array<UInt32>[]()[][], Vector3, Vector3)
Moves over an off-mesh connection.
MovePosition(Vector3)
Moves the position from its current location to the desired location, adjusting the corridor as needed to reflect the new position.
MoveTarget(Vector3)
Moves the target from its curent location to the desired location, adjusting the corridor as needed to reflect the change.
OptimizePathTopology(Boolean)
Attempts to optimize the path using a local area search. (Partial replanning.)
OptimizePathVisibility(Vector3, Single, Boolean)
Attempts to optimize the path if the specified point is visible from the current position.
Position
The position within the first polygon of the corridor.
Query
The query object used by the corridor.
ReleaseLocals(PathCorridor)
Released the references to the query and filter.
RequestDisposal()()()()
Immediately frees all unmanaged resources allocated by the object.
Reset(NavmeshPoint)
Resets the corridor to the specified position.
ResizeCornerBuffer(Int32)
Resizes the corner buffers.
ResourceType
The type of unmanaged resource used by the object.
SetCorridor(Vector3, array<UInt32>[]()[][], Int32)
Loads a new path and target into the corridor.
Target
The target within the last polygon of the corridor.

Remarks

The corridor is loaded with a path, usually obtained from a NavmeshQuery FindPath call. The corridor is then used to plan local movement, with the corridor automatically updating as needed to deal with inaccurate client locomotion.

Example of a common use case:

  1. Construct the corridor object using the NavmeshQuery and NavmeshQueryFilter objects in use by the navigation client.
  2. Obtain a path from a NavmeshQuery object.
  3. Use Reset(NavmeshPoint) to load the client's current position. (At the beginning of the path.)
  4. Use SetCorridor(Vector3, array<UInt32>[]()[][], Int32) to load the path and target.
  5. Use Corners to plan movement. (This is the straightend path.)
  6. Use the MovePosition(Vector3) to feed client movement back into the corridor. (Or Move(Vector3, Vector3) if the target is dynamic.) The corridor will automatically adjust as needed.
  7. Repeat the previous 2 steps to continue to move the client.

The corridor position and target are always constrained to the navigation mesh.

One of the difficulties in maintaining a path is that floating point errors, locomotion inaccuracies, and/or local steering can result in the client crossing the boundary of the path corridor, temporarily invalidating the path. This class uses local mesh queries to detect and update the corridor as needed to handle these types of issues.

The fact that local mesh queries are used to move the position and target locations results in two beahviors that need to be considered:

Every time a move method is used there is a chance that the path will become non-optimial. Basically, the further the target is moved from its original location, and the further the position is moved outside the original corridor, the more likely the path will become non-optimal. This issue can be addressed by periodically running the OptimizePathTopology(Boolean) and OptimizePathVisibility(Vector3, Single, Boolean) methods.

All local mesh queries have distance limitations. (Review the NavmeshQuery methods for details.) So the most accurate use case is to move the position and target in small increments. If a large increment is used, then the corridor may not be able to accurately find the new location. Because of this limiation, if a position is moved in a large increment, then compare the desired and resulting polygon references. If the two do not match, then path replanning may be needed. E.g. If you move the target, check the polygon reference of Target to see if it is as expected.

Inheritance Hierarchy

System..::..Object
  org.critterai.nav..::..PathCorridor

See Also