DI-Guy API Version 12.5.1

This file was automatically generated from diguyCharacterGuide.h. Do not edit this file directly; the changes will be lost.

Contents:

• Guide Algorithms
• Exact
• Follow1
• Follow2
• Drift1
• General Functions

diguyCharacterGuide Overview

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:

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:

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:

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

class BDI_DECLSPEC_diguy diguyCharacterGuide { public:     const char* get_name();     int set_name(const char* name);     int set_enabled(int enabled);     int get_enabled();     int get_position_acquired();     void set_position_acquired(int acquired);     int get_orientation_acquired();     void set_orientation_acquired(int acquired);     int set_guide_algorithm_float_parameter(const char* parameter,         float value);     float get_guide_algorithm_float_parameter(const char* parameter);     int set_guide_algorithm_string_parameter(const char* parameter,         const char * value);     const char * get_guide_algorithm_string_parameter(const char* parameter);

• C++
• Script

Prototype:

const char* get_name();

Returns:

name of the guide

Prototype:

int set_name(const char* name);

Description:

This function sets the name of this object.

Returns:

0 on success, -1 on failure

Prototype:

int set_enabled(int enabled);

Description:

This function enables or disables this guide.

Arguments:

enabled

pass 1 to enable to guide, 0 to disable

Returns:

0 on success, -1 on failure

Prototype:

int get_enabled();

Returns:

whether this guide is enabled; see set_enabled()

Prototype:

int get_position_acquired();

Description:

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

Returns:

1 if position reached, 0 if not

Prototype:

void set_position_acquired(int acquired);

Description:

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.

Arguments:

acquired

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

Prototype:

int get_orientation_acquired();

Description:

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

Returns:

1 if orientation reached, 0 if not

Prototype:

void set_orientation_acquired(int acquired);

Description:

Similar to set_position_acquired(), but for orientation.

Arguments:

acquired

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

Prototype:

int set_guide_algorithm_float_parameter(const char* parameter,
    float value);

Description:

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

Arguments:

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

Returns:

0 on success, -1 on failure

Prototype:

float get_guide_algorithm_float_parameter(const char* parameter);

Description:

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

Arguments:

parameter

name of the parameter to get

Returns:

current value of parameter

Prototype:

int set_guide_algorithm_string_parameter(const char* parameter,
    const char * value);

Description:

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

Arguments:

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

Returns:

0 on success, -1 on failure

Prototype:

const char * get_guide_algorithm_string_parameter(const char* parameter);

Description:

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

Arguments:

parameter

name of the parameter to get

Returns:

current value of parameter

Alphabetical Index

• diguyCharacterGuide
• get_enabled (diguyCharacterGuide)
• get_guide_algorithm_float_parameter (diguyCharacterGuide)
• get_guide_algorithm_string_parameter (diguyCharacterGuide)
• get_name (diguyCharacterGuide)
• get_orientation_acquired (diguyCharacterGuide)
• get_position_acquired (diguyCharacterGuide)
• set_enabled (diguyCharacterGuide)
• set_guide_algorithm_float_parameter (diguyCharacterGuide)
• set_guide_algorithm_string_parameter (diguyCharacterGuide)
• set_name (diguyCharacterGuide)
• set_orientation_acquired (diguyCharacterGuide)
• set_position_acquired (diguyCharacterGuide)