diguyCharacterGuide Class Reference

diguyCharacterGuide Overview 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...
int	set_guide_algorithm_float_parameter (const char *parameter, float value)
	This function sets a 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 parameter of this guide's guide algorithm. More...
int	set_guide_algorithm_string_parameter (const char *parameter, const char *value)
	This function sets a 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 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)

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

diguyCharacterGuide Overview

An algorithm for getting a character to do autonomous action picking and steering based on a goal point.

A guide is something 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. 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.

  ---

  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.

  ---

  Exact

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

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

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

This function sets a 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 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 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 parameter of this guide's guide algorithm.

Parameters

parameter

name of the parameter to get

Returns:

current value of parameter

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

void diguyCharacterGuide::get_current_desired_orientation

(

float **\

returnz

)

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:/bdi/include/diguyCharacterGuide.h