Represents algorithm for steering and maneuvering a character towards a goal point. More...

#include <diguyCharacterGuide.h>

Public Member Functions
General Functions
All functions are Callable From: C++ Script
const char *	get_name ()
	Returns: name of the guide. More...

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

int	set_enabled (int enabled)
	This function enables or disables this guide. More...

int	get_enabled ()
	Returns: whether this guide is enabled; see set_enabled() More...

int	get_position_acquired ()
	This function returns whether the character controlled by this guide has reached its desired position. More...

void	set_position_acquired (int acquired)
	This function manually sets whether the character controlled by this guide has reached its desired position. More...

int	get_orientation_acquired ()
	This function returns whether the character controlled by this guide has reached its desired orientation. More...

void	set_orientation_acquired (int acquired)
	Similar to set_position_acquired(), but for orientation. More...

const char *	get_guide_algorithm ()
	Returns that name of the guide algorithm. More...

int	set_guide_algorithm_float_parameter (const char *parameter, float value)
	This function sets a float parameter for this guide's guide algorithm. More...

float	get_guide_algorithm_float_parameter (const char *parameter)
	This function gets the current setting for a float parameter of this guide's guide algorithm. More...

int	set_guide_algorithm_string_parameter (const char parameter, const char value)
	This function sets a string parameter for this guide's guide algorithm. More...

const char *	get_guide_algorithm_string_parameter (const char *parameter)
	This function gets the current setting for a string parameter of this guide's guide algorithm. More...

int	set_guide_algorithm_vector_parameter (const char *parameter, float x, float y, float z)
	This function sets a vector parameter for this guide's guide algorithm. More...

void	get_guide_algorithm_vector_parameter (const char parameter, float \note, float y, float *z)
	This function gets the current setting for a vector parameter of this guide's guide algorithm. More...

void	get_current_desired_position (float *\note, float y, float *z)

void	get_current_desired_orientation (float **\returnz)

void	get_current_desired_position_double (double *\note, double y, double *z)

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

class	bdiScenarioCharacterGuide

bdiScenarioCharacterGuide *	get_scripted_object ()

	diguyCharacterGuide (bdiScenarioCharacterGuide *scripted_object)
	A private constructor. More...

virtual	~diguyCharacterGuide ()
	A private destructor. More...

Detailed Description

Represents algorithm for steering and maneuvering a character towards a goal point.

diguyCharacterGuide Overview

A guide is a module that can influence the position, orientation, or action of a character that is in free position mode and free action mode.

Most guides will look at the desired position and orientation of the character and do what is necessary to get the character there (or at least closer). How a guide accomplishes this depends on:

the guide algorithm being used
the parameters set for that algorithm
the difference between current and desired settings

The desired position and orientation for a character can be explicitly set by the calls set_desired_position() and set_desired_orientation(). They may also be implicitly set if that character is in a formation.

Guides can be explicitly added to a character by calling add_guide() or create_guide(). They can also be implicitly added to a character if that character is called into a formation.

Guide parameters are set by calls to diguyCharacterGuide::set_guide_algorithm_float_parameter().

Once a guide has been added to a character it can potentially affect the position, orientation, and/or action of a character until the guide has been removed or disabled. Guides can be explicitly removed from a character by calling remove_guide() or remove_all_guides(). They can be implicitly removed by the break-up of a formation, or by an automatic removal guide acquiring the target destination. They can be disabled by set_enabled(0).

Guide Algorithms

Below are descriptions of each guide algorithm, including an overview, its effects (if any) on action, position, and orientation, and the parameters that can be set for the algorithm.

Overview:

This is a trivial guide algorithm that simply sets the current position and orientation of the character to be equal to the desired position and orientation.

It can be used with or without a formation.

Effects on Action:

If the character is following a formation leader, and the leader has the same character type as the character, the character will match its action to that of the leader.

If the character types do not match, the character will try to use a suitable alternative action.

If the character is not in a formation, the action of the character is not affected.

Effects on Position and Orientation:

The character's position and orientation will be set to exactly equal the desired values without delay. If there is a substantial difference between current and desired values, a large jump in will be evident.

Parameters:

(none)

Follow1

Overview:

The Follow1 guide algorithm attempts to reach the desired position by changing the character's action and orientation.

The Follow1 algorithm is commonly used by followers in formations. It can also be used by characters not in a formation.

Effects on Action:

If the character is in distance_zone_0 and is following a formation leader that is stopped, the character will match its action to that of the leader. Otherwise characters in distance_zone_0 will switch to their default still action (usually stand).

If the character is outside distance_zone_0 and is following a formation leader that is moving, the character will match its action to that of the leader. Otherwise characters outside distance_zone_0 will switch to their default moving action (usually walk).

If the character is outside distance_zone_1 the character will scale its speed by up to max_speed_scale.

Effects on Position:

There is no direct effect on position. The character attempts to reach its desired position by changing its current action and orientation.

Effects on Orientation:

If the character is in distance_zone_0 there is no effect on orientation.

If the character is beyond distance_zone_0 the character's orientation will be set to turn the character directly toward the desired position.

Note that currently the desired orientation is not used; instead the character orients toward the desired position.

Parameters:

Parameters

max_speed_scale	(description pending)
distance_zone_0	(description pending)
distance_zone_1	(description pending)

Follow2

Overview:

The Follow2 guide algorithm attempts to reach the desired position by changing the character's action and orientation.

The Follow2 algorithm is commonly used by followers in formations. It can also be used by characters not in a formation.

Effects on Action:

If following a formation leader:

In distance_zone_0, leader stopped: Character will stop and match its still action to that of the leader if they are the same character type, otherwise the character will pick a different still action.
In distance_zone_0, leader moving: Character will stop and use its default still action.
In distance_zone_1, leader stopped: Character will use an appropriate moving action.
In distance_zone_1, leader moving: Character will match its action to that of the leader.
Beyond distance_zone_1, leader stopped or moving: Character will select a fast moving action, or speed up a slower action.

If not in a formation:
In distance_zone_0: Character will stop using its default still action.
In distance_zone_1: Character will use an appropriate moving action.
Beyond distance_zone_1: Character will select a fast moving action, or speed up a slower action.

Effects on Position:

There is no direct effect on position. The character attempts to reach its desired position by changing its current action and orientation.

Effects on Orientation:

In general, if the character is moving it will turn toward its desired position. If stopped, the character will not turn.

Note that currently the desired orientation is not used; instead the character orients toward the desired position.

Parameters:

Parameters

distance_zone_0	distance zone 0 radius; default 0.5 meters
distance_zone_1	distance zone 1 radius; default 2.0 meters
max_speed_scale	determines how much character can speed up outside distance_zone_1

Drift1

Overview:

The Drift1 guide algorithm servos the character toward its desired position and orientation, effectively "scooting" the character toward where it should be.

The Drift1 algorithm can be used by formation followers, and can also be used for characters that are trying to match desired positions and orientations from outside sources.

Effects on Action:

If the character is following a formation leader, and the leader has the same character type as the character, the character will match its action to that of the leader.

If the character is not in a formation, the action of the character is not affected.

Effects on Position:

Drift 1 distance zones are spherical, centered on the character's current position.

If the character is in distance_zone_0, the character is considered "close enough", and no drifting occurs.

If the character is in distance_zone_1, the character will drift toward the desired position. The magnitude of the drift is proportional to the parameter position_time_constant.

If the character is in distance_zone_2 or higher, the character is considered to be too far away and will be teleported directly to the desired position and orientation.

Effects on Orientation:

Drift1 azimuth zones are symmetrical, extending from the character's forward direction symmetrically around to its left and right.

If the desired position is in azimuth_zone_0, the character is considered "close enough", and no drifting occurs.

If the desired position is in azimuth_zone_1, the character will drift toward the desired orientation. The magnitude of the drift is proportional to the parameter orientation_time_constant.

If the desired position is in azimuth_zone_2 or higher, the character is considered to be too far away and will be immediately reoriented directly toward the desired orientation.

Parameters:

Parameters

distance_zone_0	distance zone 0 radius; default 0.0 meters
distance_zone_1	distance zone 1 radius; default 4.0 meters
azimuth_zone_0	azimuth zone 0 extent; default 0.0 degrees
azimuth_zone_1	azimuth zone 1 extent; default 180.0 degrees
position_time_constant	higher value results in slower drift; default is 1.0
orientation_time_constant	higher value results in slower drift; default is 1.0

Adaptive1

Overview:

Documentation Pending

Gaze1

Overview:

Documentation Pending

Crowd1

Overview:

Documentation Pending

Aircraft

Overview:

Used for aircraft such as planes, helicopters, and missiles. The assumption is that the character is in the air and won't encounter obstacles such as buildings or trees.

An aircraft flies forward through space, and can vary its speed, yaw, and pitch to get to its target. The Helicopter guide, which derives from this one, adds vertical movement capabilities.

 There are several ways to set the target (in order of precedence):

Set the guide's target character explicitly
Call diguyCharacter::aim_at_character()
Call diguyCharacter::set_desired_position()

An aircraft can operate in one of several possible modes:
GO_TO: the character will attempt to steer its way directly to the target. If it can't get there (because the destination is inside turning radius), set_target_lost() will be called.
UNGUIDED: the aircraft just flies along its current heading
FLEE: the aircraft flees away from the target point or character
EVADE: the aircraft will try to get out of way the target character. Useful for dodging missiles.
PURSUE: the aircraft attempts to follow the target character, at a certain offset
ORBIT: the aircraft will fly around the destination point, at a certain radius.

Effects on Action:

None.

Effects on Position:

The guide changes the aircraft position as it flies forward. Unless the target character has been set, the aircraft character's desired position determines where to go.

Effects on Orientation:

The guide changes the aircraft's orientation as it yaws and pitches.

Parameters:

Parameters

max_delta_rz_per_sec	yaw rate in degrees
max_delta_ry_per_sec	pitch rate in degrees
max_ry	the highest possible pitch
max_speed	in meters per second. The speed that the aircraft will prefer to go at.
min_speed	in meters per second. The aircraft may drop down to this speed, when necessary.
acceleration	m/s^2. Also determines deceleration.
reached_distance	how close the aircraft needs to get to target to have "reached" it, when traveling at max speed.
reached_distance_slow	how close the aircraft needs to get to target to have reached it, when traveling at min speed.
slow_on_approach	if 1, aircraft will slow down when it gets near target
orbit_distance	if in orbit mode, this is how far away to stay. Use a positive
value	to orbit counter clockwise, a negative one to go clockwise.
floor	how low the character is allowed to fly. Only relevant in flee and evade modes.
ceiling	how high the character is allowed to fly. Only relevant in flee and evade modes.
target_character	name of character to pursue/flee/orbit
target_offset	in coordinate system of target character. Specifies point to fly to, orbit, or flee from
launch_character	the character that launched this aircraft. Helpful for missiles.
mode	string name of mode Missile

Overview:

The Missile guide is intended for guide missiles. It inherits its behavior from the Aircraft guide, so see the documentation that's there.

Helicopter

Overview:

Derives from the Aircraft guide and inherits its behaviors and properties, but modified for a helicopter. Like an Aircraft, a Helicopter will move forward through space, and will yaw and pitch. However, it can also move up, down, and sideways. If it enters the column of airspace above or below the target, the helicopter will switch to vertical and sideways movement only.

Effects on Action:

None.

Effects on Position:

Similar to Aircraft.

Effects on Orientation:

Similar to Aircraft.

Parameters:

Parameters

max_delta_z_per_sec

vertical movement rate, meters per second

Projectile

Overview:

For an unguided projectile that flies through the air, subject to gravity. To specify a particular target, set the character's desired position. The projectile won't necessarily go to that target, though. The initial velocity must be set properly.

See diguyCharacter::get_ballistic_arc_velocity() for how to work out that setting.

Effects on Action:

None.

Effects on Position:

The guide changes the position of the projectile character as it flies in a ballistic arc en route to its target.

Effects on Orientation:

The guide changes the orientation of the character to keep it pointed in the direction it's moving.

Parameters:

Parameters

gravity	gravitational constant, m/s^2
init_velocity	(x, y, z) vector specifying the projectile's starting velocity
expire_time	how many seconds the projectile will fly for
reached_distance	how close the projectile must come to its target

Constructor & Destructor Documentation

diguyCharacterGuide::diguyCharacterGuide ( bdiScenarioCharacterGuide * scripted_object )

private

A private constructor.

virtual diguyCharacterGuide::~diguyCharacterGuide ( )

privatevirtual

A private destructor.

Member Function Documentation

const char* diguyCharacterGuide::get_name ( )

Returns: name of the guide.

int diguyCharacterGuide::set_name ( const char * name )

This function sets the name of this object.

Returns:

0 on success, -1 on failure

int diguyCharacterGuide::set_enabled ( int enabled )

This function enables or disables this guide.

Parameters

enabled pass 1 to enable to guide, 0 to disable

Returns:

0 on success, -1 on failure

int diguyCharacterGuide::get_enabled ( )

Returns: whether this guide is enabled; see set_enabled()

int diguyCharacterGuide::get_position_acquired ( )

This function returns whether the character controlled by this guide has reached its desired position.

Returns:

1 if position reached, 0 if not

void diguyCharacterGuide::set_position_acquired ( int acquired )

This function manually sets whether the character controlled by this guide has reached its desired position.

Normally this is determined automatically by the guide.

Note that calling this function may trigger a callback of diguyCharacter::CALLBACK_ID_GUIDE_POSITION_ACQUIRED or diguyCharacter::CALLBACK_ID_GUIDE_POSITION_UNACQUIRED.

Parameters

acquired pass 1 to set the desired position as acquired, 0 as unacquired

int diguyCharacterGuide::get_orientation_acquired ( )

This function returns whether the character controlled by this guide has reached its desired orientation.

Returns:

1 if orientation reached, 0 if not

void diguyCharacterGuide::set_orientation_acquired ( int acquired )

Similar to set_position_acquired(), but for orientation.

Parameters

acquired pass 1 to set the desired orientation as acquired, 0 as unacquired

const char* diguyCharacterGuide::get_guide_algorithm ( )

Returns that name of the guide algorithm.

int diguyCharacterGuide::set_guide_algorithm_float_parameter	(	const char *	parameter,
		float	value
	)

This function sets a float parameter for this guide's guide algorithm.

Parameters

parameter	name of the parameter to set
value	new value of the parameter

Returns:

0 on success, -1 on failure

float diguyCharacterGuide::get_guide_algorithm_float_parameter ( const char * parameter )

This function gets the current setting for a float parameter of this guide's guide algorithm.

Parameters

parameter name of the parameter to get

Returns:

current value of parameter

int diguyCharacterGuide::set_guide_algorithm_string_parameter	(	const char *	parameter,
		const char *	value
	)

This function sets a string parameter for this guide's guide algorithm.

Parameters

parameter	name of the parameter to set
value	new value of the parameter

Returns:

0 on success, -1 on failure

const char* diguyCharacterGuide::get_guide_algorithm_string_parameter ( const char * parameter )

This function gets the current setting for a string parameter of this guide's guide algorithm.

Parameters

parameter name of the parameter to get

Returns:

current value of parameter

int diguyCharacterGuide::set_guide_algorithm_vector_parameter	(	const char *	parameter,
		float	x,
		float	y,
		float	z
	)

This function sets a vector parameter for this guide's guide algorithm.

Parameters

parameter	name of the parameter to set
x,y,z	new value of the parameter

Returns:

0 on success, -1 on failure

void diguyCharacterGuide::get_guide_algorithm_vector_parameter	(	const char *	parameter,
		float **\	note,
		float *	y,
		float *	z
	)

This function gets the current setting for a vector parameter of this guide's guide algorithm.

Parameters

parameter name of the parameter to get

Returns:

x, y, z values of vector

void diguyCharacterGuide::get_current_desired_position	(	float **\	note,
		float *	y,
		float *	z
	)

void diguyCharacterGuide::get_current_desired_orientation ( float **\ returnz )

void diguyCharacterGuide::get_current_desired_position_double	(	double **\	note,
		double *	y,
		double *	z
	)

bdiScenarioCharacterGuide* diguyCharacterGuide::get_scripted_object ( )

inline

Friends And Related Function Documentation

friend class bdiScenarioCharacterGuide

friend

Member Data Documentation

bdiScenarioCharacterGuide* diguyCharacterGuide::m_scripted_object

private

A pointer to internal data.

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

C:/Jenkins/jobs/diguy_apps_13.1_vc10_x64/workspace/include/diguyCharacterGuide.h

Public Member Functions

Private Functions

Detailed Description

Guide Algorithms

Follow1

Follow2

Drift1

Adaptive1

Gaze1

Crowd1

Aircraft

Missile

Helicopter

Projectile

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation