An interface for manipulating a character's spline path. A path is typically authored in DI-Guy Scenario, but can be manipulated via the sdk. More...

#include <diguyCharacterPath.h>

Public Member Functions
General Functions
Unless otherwise specified, all functions callable from: C++ Script
const char *	get_name ()
	Returns the name of the path. More...

int	set_name (const char *name)
	This function sets the name of this object. More...

long	get_uid ()
	All character paths are assigned a unique identifier, or uid. More...

diguyCharacter *	get_character ()
	Returns: character that owns this path. More...

int	update ()
	This function should be called after all modifications have been made to the path and it is time to re-derive the overall path shape and when actions happen. More...

float	get_length ()
	This function returns the total length of the path, in meters. More...

float	get_duration ()
	This function returns how long this path is. More...

int	get_point_at_distance (float distance_into_path, float x, float y, float z, float rz, float rx, float ry)
	This function returns, via the passed variable pointers, the position and orientation of the point on the path at the specified distance. More...

diguyPathShape *	get_path_shape ()
	This function returns the underlying path shape of the path. More...

Waypoint Functions
Unless otherwise specified, all functions callable from: C++ Script
int	get_num_waypoints ()
	Returns: More...

diguyWaypoint *	get_waypoint_at_index (int index)
	This function gets the waypoint at the specified index and returns a pointer to it. More...

diguyWaypoint *	find_waypoint (const char *name)
	This function returns a pointer to the specified waypoint. More...

diguyWaypoint *	create_waypoint (float x=0.0f, float y=0.0f, float z=0.0f, float yaw=0.0f, float roll=0.0f, float pitch=0.0f, float weight=1.0f, int index=-1)
	This function creates a new waypoint that is added to the path. More...

int	add_waypoint (diguyWaypoint *waypoint)
	This function adds a waypoint to the path. More...

int	destroy_waypoint (diguyWaypoint *waypoint)
	This function destroys a waypoint on the path. More...

Action Bead Functions
Unless otherwise specified, all functions callable from: C++ Script
int	get_num_action_beads ()
	Returns: More...

diguyCharacterPathActionBead *	get_action_bead_at_index (int index)
	This function gets the action bead at the specified index and returns a pointer to it. More...

diguyCharacterPathActionBead *	find_action_bead (const char *name)
	This function returns a pointer to the specified bead. More...

diguyCharacterPathActionBead *	get_final_action_bead ()
	This function returns a pointer to the last action bead of the path. More...

diguyCharacterPathActionBead *	create_action_bead (const char *action, int index=-1)
	This function inserts a new action bead at the specified index and returns a pointer to it. More...

int	destroy_action_bead (diguyCharacterPathActionBead *action_bead)
	This function removes the passed action bead from the path and destroys it. More...

Script Bead Functions
Unless otherwise specified, all functions callable from: C++ Script
int	get_num_script_beads ()
	Returns: More...

diguyCharacterPathScriptBead *	get_script_bead_at_index (int index)
	This function gets the script bead at the specified index and returns a pointer to it. More...

diguyCharacterPathScriptBead *	find_script_bead (const char *name)
	This function returns a pointer to the specified bead. More...

diguyCharacterPathScriptBead *	create_script_bead (const char script, int index=-1, const char script_type="lua")
	This function inserts a new script bead at the specified index and returns a pointer to it. More...

int	destroy_script_bead (diguyCharacterPathScriptBead *script_bead)
	This function removes the passed script bead from the path and destroys it. More...

Decision Bead Functions
Unless otherwise specified, all functions callable from: C++ Script
int	get_num_decision_beads ()
	Returns: More...

diguyCharacterPathDecisionBead *	get_decision_bead_at_index (int index)
	This function gets the decision bead at the specified index and returns a pointer to it. More...

diguyCharacterPathDecisionBead *	find_decision_bead (const char *name)
	This function returns a pointer to the specified bead. More...

Gaze Bead Functions
Unless otherwise specified, all functions callable from: C++ Script
int	get_num_gaze_beads ()
	Returns: More...

diguyCharacterPathGazeBead *	get_gaze_bead_at_index (int index)
	This function gets the gaze bead at the specified index and returns a pointer to it. More...

diguyCharacterPathGazeBead *	find_gaze_bead (const char *name)
	This function returns a pointer to the specified bead. More...

Aim Bead Functions
Unless otherwise specified, all functions callable from: C++ Script
int	get_num_aim_beads ()
	Returns: More...

diguyCharacterPathAimBead *	get_aim_bead_at_index (int index)
	This function gets the aim bead at the specified index and returns a pointer to it. More...

diguyCharacterPathAimBead *	find_aim_bead (const char *name)
	This function returns a pointer to the specified bead. More...

Experimental Functions
The following functions are experimental and may change or disappear with no warning.
int	translate (float tx, float ty, float tz)

int	rotate_about_point (float rz, float rx, float ry, float rotation_pt_x, float rotation_pt_y, float rotation_pt_z)

int	set_ground_clamp_when_on_path (int ground_clamp_when_on_path)

int	get_ground_clamp_when_on_path ()

int	get_position_at_distance (float distance, float tx, float ty, float tz, float rz=NULL, float rx=NULL, float ry=NULL)

int	get_position_at_distance_double (float distance, double tx, double ty, double tz, float rz=NULL, float rx=NULL, float ry=NULL)

int	get_position_at_t (float t, float tx, float ty, float tz, float rz=NULL, float rx=NULL, float ry=NULL)

int	get_position_at_t_double (float t, double tx, double ty, double tz, float rz=NULL, float rx=NULL, float ry=NULL)

Private Functions
The functions and variables past this point are for internal use only. No external access to them is expected or necessary.
bdiScenarioPath *	m_scripted_object
	A pointer to internal data. More...

class	bdiScenarioPath

class	diguyCharacter

bdiScenarioPath *	get_scripted_object ()

	diguyCharacterPath (bdiScenarioPath *path)
	A private constructor. More...

	~diguyCharacterPath ()
	A private destructor. More...

Detailed Description

An interface for manipulating a character's spline path. A path is typically authored in DI-Guy Scenario, but can be manipulated via the sdk.

Constructor & Destructor Documentation

diguyCharacterPath::diguyCharacterPath ( bdiScenarioPath * path )

private

A private constructor.

diguyCharacterPath::~diguyCharacterPath ( )

private

A private destructor.

Member Function Documentation

const char* diguyCharacterPath::get_name ( )

Returns the name of the path.

This pointer will never be NULL.

Returns:

name of the path

int diguyCharacterPath::set_name ( const char * name )

This function sets the name of this object.

Returns:

0 on success, -1 on failure

long diguyCharacterPath::get_uid ( )

All character paths are assigned a unique identifier, or uid.

This function returns this path's uid.

Note: unique identifiers will change between DI-Guy runs!

Returns:

unique identifier of object

diguyCharacter* diguyCharacterPath::get_character ( )

Returns: character that owns this path.

int diguyCharacterPath::update ( )

This function should be called after all modifications have been made to the path and it is time to re-derive the overall path shape and when actions happen.

This update is deferred for reasons of performance; if there are a lot of modifications to be made to the path they can all be done in a group with only a single final update.

A call to update() is typically required after certain calls are made on objects owned by the path, such as a diguyWaypoint or a diguyCharacterPathActionBead. The documentation for function calls of these objects will state whether a subsequent update() call is necessary.

Returns:

0 on success, -1 on failure

float diguyCharacterPath::get_length ( )

This function returns the total length of the path, in meters.

Returns:

length of path in meters

float diguyCharacterPath::get_duration ( )

This function returns how long this path is.

Returns:

duration of this path, in seconds

int diguyCharacterPath::get_point_at_distance	(	float	distance_into_path,
		float *	x,
		float *	y,
		float *	z,
		float *	rz,
		float *	rx,
		float *	ry
	)

This function returns, via the passed variable pointers, the position and orientation of the point on the path at the specified distance.

Parameters

distance_into_path	distance in meters into path of the desired point
x,y,z	position of point in meters from the origin
rz,rx,ry	orientation of point in degrees counter-clockwise from the positive X axis

Returns:

0 on success, -1 on failure

diguyPathShape* diguyCharacterPath::get_path_shape ( )

This function returns the underlying path shape of the path.

The path shape defines only the waypoints and associated spline shape of the path; it doesn't not contain any beads or other information.

The returned path shape should be considered READ ONLY. DO NOT edit the path shape using diguyPathShape member functions!

Returns:

pointer to object of type diguyPathShape

int diguyCharacterPath::get_num_waypoints ( )

Returns:

the number of waypoints belonging to this path

diguyWaypoint* diguyCharacterPath::get_waypoint_at_index ( int index )

This function gets the waypoint at the specified index and returns a pointer to it.

The returned waypoint can then be queried for information or modified.

Note that if the waypoint is modified, the update() function must be called to update the path's shape and other information.

Parameters

index index of the waypoint; indices start at 0

Returns:

pointer of type diguyWaypoint; NULL if no waypoint at the specified index

Lua Example:

This example gets the first waypoint of the first character's first path. It then changes the x coordinate of the waypoint and updates the path to reflect the change.

local character = this_scenario:get_character_at_index(0);
local path0 = character:get_path_at_index(0);
local wp0 = path0:get_waypoint_at_index(0);
local wp0_x = wp0:get_x();
wp0:set_x(wp0_x + 1.0);
path0:update();

diguyWaypoint* diguyCharacterPath::find_waypoint ( const char * name )

This function returns a pointer to the specified waypoint.

Parameters

name	name of waypoint to be found

Returns:

pointer of type diguyWaypoint; NULL if not found

diguyWaypoint* diguyCharacterPath::create_waypoint	(	float	x = `0.0f`,
		float	y = `0.0f`,
		float	z = `0.0f`,
		float	yaw = `0.0f`,
		float	roll = `0.0f`,
		float	pitch = `0.0f`,
		float	weight = `1.0f`,
		int	index = `-1`
	)

This function creates a new waypoint that is added to the path.

Do not call diguyScenario::destroy_waypoint() on the returned waypoint; it will be destroyed automatically with the path.

Parameters

tx,ty,tz	position in meters from the origin
rz,rx,ry	orientations in degrees counter-clockwise from the positive X axis
weight	how much influence this waypoint exerts over the path curve
index	where the waypoint should be inserted in
the	path; indices start at 0; pass 1 to add to end of path

Returns:

pointer to type diguyWaypoint

int diguyCharacterPath::add_waypoint ( diguyWaypoint * waypoint )

This function adds a waypoint to the path.

The waypoint should be created using the function diguyScenario::create_waypoint(), and destroyed using the function diguyScenario::destroy_waypoint().

An internal copy of the waypoint is made, so it can be destroyed right after this function call or used for other path shapes.

Parameters

waypoint waypoint to be appended to end of path

Returns:

0 on success, -1 on failure

int diguyCharacterPath::destroy_waypoint ( diguyWaypoint * waypoint )

This function destroys a waypoint on the path.

Parameters

waypoint waypoint to be deleted

Returns:

0 on success, -1 on failure

int diguyCharacterPath::get_num_action_beads ( )

Returns:

the number of action beads belonging to this path

diguyCharacterPathActionBead* diguyCharacterPath::get_action_bead_at_index ( int index )

This function gets the action bead at the specified index and returns a pointer to it.

The returned action bead can then be queried for information or modified.

Note that if the action bead is modified, the update() function must be called to update the path's information.

Returns:

pointer of type diguyCharacterPathActionBead; NULL if no action bead at the specified index

Parameters

index index of the action bead; indices start at 0

diguyCharacterPathActionBead* diguyCharacterPath::find_action_bead ( const char * name )

This function returns a pointer to the specified bead.

Parameters

name	name of bead to be found

Returns:

pointer of type diguyCharacterPathActionBead; NULL if not found

diguyCharacterPathActionBead* diguyCharacterPath::get_final_action_bead ( )

This function returns a pointer to the last action bead of the path.

The last action bead is slightly different than the rest. It has no inherent duration or length; instead, it effectively specifies what the character should do once this path has completed.

Calling this function is the same as the following:

int num_action_beads = path->get_num_action_beads();
diguyCharacterPathActionBead* ab;
ab = path->get_action_bead_at_index(num_action_beads-1);

Do not call delete or destroy_action_bead() on the returned pointer. All paths must have a final action bead.

Returns:

pointer of type diguyCharacterPathActionBead; this pointer should never be NULL

diguyCharacterPathActionBead* diguyCharacterPath::create_action_bead	(	const char *	action,
		int	index = `-1`
	)

This function inserts a new action bead at the specified index and returns a pointer to it.

The returned action bead can then be queried for information or modified.

Note that the update() function must be called after this function.

Do not call delete on the returned pointer. Use destroy_action_bead() instead.

Returns:

pointer of type diguyCharacterPathActionBead; NULL if insertion failed

Parameters

action	action new bead should perform
index	index of the action bead; indices start at 0;
pass	1 to append the action bead to the end of the path

int diguyCharacterPath::destroy_action_bead ( diguyCharacterPathActionBead * action_bead )

This function removes the passed action bead from the path and destroys it.

Note that the update() function must be called after this function.

Returns:

0 on success, -1 on failure

Parameters

action_bead object to destroy; must be part of this path

int diguyCharacterPath::get_num_script_beads ( )

Returns:

the number of script beads belonging to this path

diguyCharacterPathScriptBead* diguyCharacterPath::get_script_bead_at_index ( int index )

This function gets the script bead at the specified index and returns a pointer to it.

The returned script bead can then be queried for information or modified.

Note that if the script bead is modified, the update() function must be called to update the path's information.

Returns:

pointer of type diguyCharacterPathScriptBead; NULL if no script bead at the specified index

Parameters

index index of the script bead; indices start at 0

diguyCharacterPathScriptBead* diguyCharacterPath::find_script_bead ( const char * name )

This function returns a pointer to the specified bead.

Parameters

name	name of bead to be found

Returns:

pointer of type diguyCharacterPathScriptBead; NULL if not found

diguyCharacterPathScriptBead* diguyCharacterPath::create_script_bead	(	const char *	script,
		int	index = `-1`,
		const char *	script_type = `"lua"`
	)

This function inserts a new script bead at the specified index and returns a pointer to it.

The returned script bead can then be queried for information or modified.

Note that the update() function must be called after this function.

Do not call delete on the returned pointer. Use destroy_script_bead() instead.

Returns:

pointer of type diguyCharacterPathScriptBead; NULL if insertion failed

Parameters

script	script new bead should perform
index	index of the script bead; indices start at 0;
pass	1 to create the bead at the last index
script_type	defaults to "lua"

int diguyCharacterPath::destroy_script_bead ( diguyCharacterPathScriptBead * script_bead )

This function removes the passed script bead from the path and destroys it.

Note that the update() function must be called after this function.

Returns:

0 on success, -1 on failure

Parameters

script_bead object to destroy; must be part of this path

int diguyCharacterPath::get_num_decision_beads ( )

Returns:

the number of decision beads belonging to this path

diguyCharacterPathDecisionBead* diguyCharacterPath::get_decision_bead_at_index ( int index )

This function gets the decision bead at the specified index and returns a pointer to it.

The returned decision bead can then be queried for information.

Note that if the decision bead is modified, the update() function must be called to update the path's information.

Returns:

pointer of type diguyCharacterPathDecisionBead; NULL if no script bead at the specified index

Parameters

index index of the decision bead; indices start at 0

diguyCharacterPathDecisionBead* diguyCharacterPath::find_decision_bead ( const char * name )

This function returns a pointer to the specified bead.

Parameters

name	name of bead to be found

Returns:

pointer of type diguyCharacterPathDecisionBead; NULL if not found

int diguyCharacterPath::get_num_gaze_beads ( )

Returns:

the number of gaze beads belonging to this path

diguyCharacterPathGazeBead* diguyCharacterPath::get_gaze_bead_at_index ( int index )

This function gets the gaze bead at the specified index and returns a pointer to it.

The returned gaze bead can then be queried for information.

Note that if the gaze bead is modified, the update() function must be called to update the path's information.

Returns:

pointer of type diguyCharacterPathDecisionBead; NULL if no script bead at the specified index

Parameters

index index of the gaze bead; indices start at 0

diguyCharacterPathGazeBead* diguyCharacterPath::find_gaze_bead ( const char * name )

This function returns a pointer to the specified bead.

Parameters

name	name of bead to be found

Returns:

pointer of type diguyCharacterPathGazeBead; NULL if not found

int diguyCharacterPath::get_num_aim_beads ( )

Returns:

the number of aim beads belonging to this path

diguyCharacterPathAimBead* diguyCharacterPath::get_aim_bead_at_index ( int index )

This function gets the aim bead at the specified index and returns a pointer to it.

The returned aim bead can then be queried for information.

Note that if the aim bead is modified, the update() function must be called to update the path's information.

Returns:

pointer of type diguyCharacterPathDecisionBead; NULL if no script bead at the specified index

Parameters

index index of the aim bead; indices start at 0

diguyCharacterPathAimBead* diguyCharacterPath::find_aim_bead ( const char * name )

This function returns a pointer to the specified bead.

Parameters

name	name of bead to be found

Returns:

pointer of type diguyCharacterPathAimBead; NULL if not found

int diguyCharacterPath::translate	(	float	tx,
		float	ty,
		float	tz
	)

int diguyCharacterPath::rotate_about_point	(	float	rz,
		float	rx,
		float	ry,
		float	rotation_pt_x,
		float	rotation_pt_y,
		float	rotation_pt_z
	)

int diguyCharacterPath::set_ground_clamp_when_on_path ( int ground_clamp_when_on_path )

int diguyCharacterPath::get_ground_clamp_when_on_path ( )

int diguyCharacterPath::get_position_at_distance	(	float	distance,
		float *	tx,
		float *	ty,
		float *	tz,
		float *	rz = `NULL`,
		float *	rx = `NULL`,
		float *	ry = `NULL`
	)

int diguyCharacterPath::get_position_at_distance_double	(	float	distance,
		double *	tx,
		double *	ty,
		double *	tz,
		float *	rz = `NULL`,
		float *	rx = `NULL`,
		float *	ry = `NULL`
	)

int diguyCharacterPath::get_position_at_t	(	float	t,
		float *	tx,
		float *	ty,
		float *	tz,
		float *	rz = `NULL`,
		float *	rx = `NULL`,
		float *	ry = `NULL`
	)

int diguyCharacterPath::get_position_at_t_double	(	float	t,
		double *	tx,
		double *	ty,
		double *	tz,
		float *	rz = `NULL`,
		float *	rx = `NULL`,
		float *	ry = `NULL`
	)

bdiScenarioPath* diguyCharacterPath::get_scripted_object ( )

inline

Friends And Related Function Documentation

friend class bdiScenarioPath

friend

friend class diguyCharacter

friend

Member Data Documentation

bdiScenarioPath* diguyCharacterPath::m_scripted_object

private

A pointer to internal data.

The documentation for this class was generated from the following file:

E:/nightly/2751/include/diguyCharacterPath.h

Public Member Functions

Private Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation