diguyCharacterGuide Class Reference

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. The desired velocity or desired angular velocity might also come into play.

  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).

Distance zones:

These might be used differently in specific guide algorithms, or not used. The general idea is this:

If the character is within distance zone 0 (relative to target/destination), it will stop moving. Otherwise, if it is within zone 1, it will move at a default speed. Otherwise, if it is within zone 2, it will move at a scaled-up speed. And so on. The maximum scaling factor is represented by max_speed_scale.

Azimuth zones:

The idea is similar to that of distance zones, except that it concerns a target orientation. If the delta between current orientation and target is less than azimuth_zone_0, the character is considered to have reached the target orientation. If the delta is greater than azimuth_zone_1, the character will have a faster angular velocity.

Common Parameters:

max_speed_scale distance_zone_0 distance_zone_1 distance_zone_2 distance_zone_3

Parameters

distance_xyz_zone_0

same idea as distance_zone_0, but in three dimensions, not merely horizontal distance distance_xyz_zone_1 azimuth_zone_0 azimuth_zone_1 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	see Common Parameters section
distance_zone_0	see Common Parameters section
distance_zone_1	see Common Parameters section

---

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 is meant to be used in situations where one character is closely following another. The other character might be local, but it's more likely to be a remote character, which this character is reflecting. The algorithm helps "smooth out" the infrequent position updates.

 The last known position, orientation, and velocity of the remote character

are stored as this character's desired position, orientation, and velocity. It is the job of the guide to catch the character up to them. It does so by "sliding" the character some part of the remaining distance between its current and desired settings. There's also some dead-reckoning, which gradually shifts the desired position forward by the desired velocity, at least until an outside source provides a new desired position. The same idea applies with orientation.

This guide is not very intelligent about trying to choose an appropriate action for the character, or about allowing the character to neatly complete an action that's already underway. The Adaptive1 guide, while tailored to human bipedal characters, may be a better bet for that.

How quickly the character "slides" towards its desired position/orientation is determined by the slide-in multiplier. This is derived from the character's current speed. A fast-moving character will slide in more quickly, a slow-moving one more slowly. The idea is to maintain a balance between getting the character to where it needs to be and making its movement look somewhat natural.

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 determined by 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.

Explanation of stationary drift ratio

The SDR is the minimum allowed slide-in multiplier (see explanation above). If the ratio is greater than zero, the current slide-in multiplier will be shifted up so as to make the SDR the lowest possible value. Thus, even when the current speed of the character is small, it will continue to slide until it reaches the point it's supposed to be at. This is important when the remote character stops moving.

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	Determines how much of remaining distance to target should be closed per second. The effect is inversely proportional, so that higher numbers lead to a slower servoing. 1.0 is the default.
orientation_time_constant	same idea as position_time_constant, but for the orientation.
stationary_drift_ratio	see explanation above
sync_gain	another multiplier for servoing towards goal orientation. This one is proportional to remaining angle offset.

---

Adaptive1

Overview:

    This guide is derived from the Drift1 guide and performs a similar role, but is

smarter about trying to choose appropriate actions at the right time, in order to prevent the "foot-sliding" effect that's visible with that guide.

Be sure to visit the guide_example in programming examples for a demonstration of this and other guides.

Parameters:

Parameters

position_time_constant	Determines how much of remaining distance to target should be closed per second. The effect is inversely proportional, so that higher numbers lead to a slower servoing. 1.0 is the default.
orientation_time_constant	same idea as position_time_constant, but for the orientation.
stationary_drift_ratio	see explanation with Drift1 guide documentation Gaze1

Overview:

This guide helps the character turn towards the thing being gazed at. The guide attempts to choose appropriate turning motions.

---

Crowd1

Overview:

This guide is used for characters that are part of a crowd. It makes sure that the behavior set in the crowd profile is run. It has no parameters besides the standard ones.

---

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()

• Call diguyCharacter::set_desired_orientation() [DIRECTIONAL mode only]

  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
• DIRECTIONAL: the aircraft will change its heading to match the desired
• orientation of the character.
• 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
approach_vector	vector along which to arrive at target point. Meaningful only in goto mode, and when not pursuing anything
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:

• E:/nightly/2532/include/diguyCharacterGuide.h