PathSystem Plugin API
|
The PathSystem plug-in is a system which allows for several different implementations of path finding. Because the plug-in is loaded on the physics server, the API has changed to make all requests asynchronous, and new HSL External functions are used to access the new functionality.
New Concepts
This new API includes a concept known as a parameter set. These sets define how a given path request is processed. To use a parameter set with a path request, it must first be defined. The parameter sets collect the settings used for similar types of path requests, and limit the amount of data transferred with each path request. Because the parameter set field and value pairs are not defined in the GOM or C++ code, they can be used by clients who implement their own path finding plug-in.
Parameter sets are created using the Key Value Spec API.
Parameters Supported by the C++ API
- step_value
- (float) Distance between smoothed data points
- tightness
- (float) Distance between control points
- check_above
- (float) Height above to start grounding
- walk_slope
- (float) Walk slope for the character
- char_width
- (float) The character width
- char_height
- (float) The character height
- collision_group
- (string) Specifies the collision group flags to use
- debug_visualize
- (boolean) True to debug visualize the smoothed path
- string_pulling
- (boolean)
- terrain
- (boolean)
- non_terrain
- (boolean)
- water
- (boolean)
- underwater
- (boolean)
- path_avoid1
- (boolean)
- path_avoid2
- (boolean)
- path_avoid3
- (boolean)
- path_avoid4
- (boolean)
- path_prefer1
- (boolean)
- path_prefer2
- (boolean)
- path_prefer3
- (boolean)
- path_prefer4
- (boolean)
- dive_down
- (boolean)
- swim_up
- (boolean)
- swim_up_cost
- (float)
- terrain_cost
- (float)
- non_terrain_cost
- (float)
- underwater_cost
- (float)
- path_avoid1_cost
- (float)
- path_avoid2_cost
- (float)
- path_avoid3_cost
- (float)
- path_avoid4_cost
- (float)
- path_prefer1_cost
- (float)
- path_prefer2_cost
- (float)
- path_prefer3_cost
- (float)
- path_prefer4_cost
- (float)
- time_out
- (float)
- priority
- (integer)
HSL External Function API
While your systems can technically call these external functions directly, it is intended you instead call them through the $PATHSYSTEM system node which wraps the C++ API.
The following external functions are available at the Area Server only. They will return false until the area server is registered as a scene on the physics server.
Get a Path Between Two Points
This function requests a path be found, using the given parameter set. An asynchronous callback is made to the specified callback node unless the function returns false, which indicates the server has not yet set up a scene on the physics server.
external function _PathSystem_GetPath( callbackNode as NodeRef, pathRequestID as ID, parameterSetHandle as ID, fromPos as Vector3, toPos as Vector3 ) as Boolean // callbackNode - Node the implements the interface defined in _abstractPathHandlerClassMethods, this node will // receive a callback from the system as asynchronous responses come in for its requests // parameterSetHandle - ID of the parameter set to use for the pathfinding request. Parameter sets include // parameters for whether or not swimming/flying paths are allowed, should string pulling be used // whether or not to ground the path and so on. // fromPos - Starting position for the path // toPos - Ending position for the path
The specified callbackNode
will receive a call to the method _PathSystem_PathComplete
in response to the request for a path.
method _PathSystem_PathComplete(path as NodeRef of Class _PathSystemResponse) // Parameters: // path - a noderef of class _PathSystemResponse containing fields for the request id and points for // the generated path // Field _psrRequestID - id of the path request // Field _psrPointList - list of vector3s representing the points of the generated path
Get a Random Point
Asynchronous request for a random point located anywhere in an area's nav mesh. The function call will return false if the physics server does not yet have a scene for the area server or if the area server has lost connection to its physics server.
The usefulness of this particular function is questionable as the more specific requests constrained to volumes tend to be more useful in practice.
external function _PathSystem_GetRandomPoint( callbackNode as NodeRef, pathRequestID as ID, parameterSetHandle as ID) as Boolean
The specified callbackNode will receive a call to the method _PathSystem_GotRandomPoint
in response to the request for a random point.
method _PathSystem_GotRandomPoint(pathRequestID as ID, point as Vector3) // Parameters: // pathRequestID - Request ID for this request, used internally by the $PATHSYSTEM to map requests to callback nodes // point - the random point selected by the C++ .
Constrained to the Volume of a Pathfinding Node
Asynchronous request for a random point located in an area's nav mesh constrained to the volume of a pathfinding node. The function call will return false if the physics server does not yet have a scene for the area server or if the area server has lost connection to its physics server.
external function _PathSystem_GetRandomPointInPathFindingNode( callbackNode as NodeRef, pathRequestID as ID, parameterSetHandle as ID, pathfindingNode as NodeRef ) as Boolean
The specified callbackNode will receive a call to the method _PathSystem_GotRandomPointInPathFindingNode
in response to the request for a random point constrained to a particular pathfinding node.
method _PathSystem_GotRandomPointInPathFindingNode( requestID as ID, point as Vector3,found as Boolean) // Parameters: // pathRequestID - Request ID for this request, used internally by the $PATHSYSTEM to map requests to callback nodes // point - the nearest point to the point specified when the request was made. // found - boolean indicating whether or not a point was found .
Constrained to the Volume of a Region Node
Asynchronous request for a random point located in an area's nav mesh constrained to the volume of a region node. The function call will return false if the physics server does not yet have a scene for the area server or if the area server has lost connection to its physics server.
external function _PathSystem_GetRandomPointInRegionNode( callbackNode as NodeRef, pathRequestID as ID, parameterSetHandle as ID, regionNode as NodeRef ) as Boolean
The specified callbackNode will receive a call to the method _PathSystem_GotRandomPointInRegionNode
in response to the request for a random point constrained to a particular region node.
method _PathSystem_GotRandomPointInRegionNode( requestId as ID, point as Vector3,found as Boolean ) // Parameters: // pathRequestID - Request ID for this request, used internally by the $PATHSYSTEM to map requests to callback nodes // point - the nearest point to the point specified when the request was made. // found - boolean indicating whether or not a point was found .
Constrained to the Volume of a Sphere
Asynchronous request for a random point located in an area's nav mesh constrained to the volume of a sphere. The function call will return false if the physics server does not yet have a scene for the area server or if the area server has lost connection to its physics server.
external function _PathSystem_GetRandomPointInSphere( callbackNode as NodeRef, requestID as ID, parameterSetHandle as ID, center as Vector3, radius as Float ) as Boolean
The specified callbackNode will receive a call to the method _PathSystem_GotRandomPointInSphere
in response to the request for a random point constrained to a specified sphere.
method _PathSystem_GotRandomPointInSphere( requestId as ID, point as Vector3,found as Boolean ) // Parameters: // pathRequestID - Request ID for this request, used internally by the $PATHSYSTEM to map requests to callback nodes // point - the nearest point to the point specified when the request was made. // found - boolean indicating whether or not a point was found .
Constrained to a Volume
Asynchronous request for a random point located in an area's nav mesh constrained to a volume. The function call will return false if the physics server does not yet have a scene for the area server or if the area server has lost connection to its physics server.
external function _PathSystem_GetRandomPointInVolume( callbackNode as NodeRef, requestId as ID, parameterSetHandle as ID,bmin as Vector3,bmax as Vector3) as Boolean
The specified callbackNode will receive a call to the method _PathSystem_GotRandomPointInVolume
in response to the request for a random point constrained to a specified volume.
method _PathSystem_GotRandomPointInVolume( requestID as ID, point as Vector3,found as Boolean ) // Parameters: // pathRequestID - Request ID for this request, used internally by the $PATHSYSTEM to map requests to callback nodes // point - the nearest point to the point specified when the request was made. // found - boolean indicating whether or not a point was found .
Get Nearest Point
Asynchronous request for the nearest point located in an area's nav mesh to a specified point. The function call will return false if the physics server does not yet have a scene for the area server or if the area server has lost connection to its physics server.
external function _PathSystem_GetNearestPoint( callbackNode as NodeRef, pathRequestID as ID, parameterSetHandle as ID, nearPoint as Vector3 ) as Boolean
The specified callbackNode will receive a call to the method _PathSystem_GotNearestPoint
in response to the request for the nearest point.
method _PathSystem_GotNearestPoint(pathRequestID as ID, point as Vector3) // Parameters: // pathRequestID - Request ID for this request, used internally by the $PATHSYSTEM to map requests to callback nodes // point - the nearest point to the point specified when the request was made. .
Get Nodes Containing a Point
Pathfinding Nodes Containing a Point
Asynchronous request for a list of pathfinding nodes containing a specified point. The function call will return false if the physics server does not yet have a scene for the area server or if the area server has lost connection to its physics server.
external function _PathSystem_GetPathFindingNodesContainingPoint( callbackNode as NodeRef, requestID as ID, point as Vector3 ) as Boolean
The specified callbackNode will receive a call to the method _PathSystem_GotPathFindingNodesContainingPoint
in response to the request for a list of pathfinding nodes containing a specified point.
method _PathSystem_GotPathFindingNodesContainingPoint( requestID as ID, containingNodes as List of NodeRef ) // Parameters: // pathRequestID - Request ID for this request, used internally by the $PATHSYSTEM to map requests to callback nodes // containingNodes - list of pathfinding nodes that contain the specified point .
Region Nodes Containing a Point
Asynchronous request for a list of pathfinding nodes containing a specified point. The function call will return false if the physics server does not yet have a scene for the area server or if the area server has lost connection to its physics server.
external function _PathSystem_GetRegionNodesContainingPoint( callbackNode as NodeRef, requestID as ID, point as Vector3 ) as Boolean
The specified callbackNode will receive a call to the method _PathSystem_GotRegionNodesContainingPoint
in response to the request for a list of region nodes containing a specified point.
method _PathSystem_GotRegionNodesContainingPoint( requestID as ID, containingNodes as List of NodeRef ) // Parameters: // pathRequestID - Request ID for this request, used internally by the $PATHSYSTEM to map requests to callback nodes // containingNodes - list of region nodes that contain the specified point .
C++ Plug-in Interface API
For reference purposes, I've included a listing of the HBPathSystem C++ plug-in interface.
class HBPathSystem : public MemoryServices { public: virtual void test(void) = 0; virtual void setServerBase(SERVERBASE::ServerBase *sbase)=0; virtual void setRenderDebug(RENDER_DEBUG::RenderDebug *r) = 0; virtual void setResourceInterface(FIRE_STORM_RESOURCE::ResourceInterface *iface) =0; virtual PATHSYSTEMGUID createPathSystem(const char *fqn,NxScene *scene) = 0; virtual PATHSYSTEMGUID createPathSystem(const void *mem,unsigned int len,NxScene *scene,unsigned int &ncount,unsigned int &ccount) = 0; virtual bool releasePathSystem(PATHSYSTEMGUID guid) = 0; virtual unsigned int render(PATHSYSTEMGUID guid,const float *eyePos,float showDistance)=0; virtual PATH_WEIGHT_GUID createPathWeightSystem(const char *fqn) = 0; virtual bool releasePathWeightSystem(PATH_WEIGHT_GUID guid) = 0; virtual void pump(float dtime) = 0; virtual PATHGUID solvePath(PATHSYSTEMGUID guid,const PathRequestDesc &desc) = 0; virtual bool cancelPath(PATHSYSTEMGUID guid,PATHGUID path) = 0; virtual unsigned int cancelPaths(PATHSYSTEMGUID guid,PathNodeInterface *callback) = 0; virtual bool setPathState(PATHSYSTEMGUID guid,PathState state,bool bstate=true,unsigned int v=0,const float *fv=0,PathStateDesc *desc=0) = 0; virtual bool getPathState(PATHSYSTEMGUID guid,PathState state,bool &bstate,unsigned int &v,float *fv,PathStateDesc *desc) = 0; };
Reference
- See also: Path Planning Technical Information