PathSystem Plugin API

Contents 1 New Concepts 2 Parameters Supported by the C++ API 3 HSL External Function API 3.1 Get a Path Between Two Points 3.2 Get a Random Point 3.2.1 Constrained to the Volume of a Pathfinding Node 3.2.2 Constrained to the Volume of a Region Node 3.2.3 Constrained to the Volume of a Sphere 3.2.4 Constrained to a Volume 3.3 Get Nearest Point 3.4 Get Nodes Containing a Point 3.4.1 Pathfinding Nodes Containing a Point 3.4.2 Region Nodes Containing a Point 4 C++ Plug-in Interface API 5 Reference

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 system returns a noderef containing the requested path, if your callback node does not inherit the _abstractPathSystemHandler as a parent or you have overridden its clean-up mechanism you are responsible for cleaning up the node. Failure to clean up the node will result in a memory leak.

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

• This page was last modified on 20 June 2011, at 14:25.
• This page has been accessed 2,983 times.

• Privacy policy
• About HEWIKI
• Disclaimers

• Copyright (c) 2006-2013 Idea Fabrik Plc. All Rights Reserved.
• HeroCloud is a registered trademark of IdeaFabrik Plc, all rights reserved
• HeroEngine is a registered trademark of IdeaFabrik Plc, all rights reserved

•