diguyCharacter Class Reference

The class that represents a DI-Guy Entity in the world. More...

#include <diguyCharacter.h>

Public Types
Callback Functions
enum	{   CALLBACK_ID_CREATE = 1, CALLBACK_ID_DESTROY, CALLBACK_ID_PRE_CREATE, CALLBACK_ID_CURRENT_APPEARANCE_CHANGED,   CALLBACK_ID_CURRENT_HEAD_APPEARANCE_CHANGED, CALLBACK_ID_CURRENT_HAND_ITEM_APPEARANCE_CHANGED, CALLBACK_ID_SHAPE_VISIBILITY_CHANGED, CALLBACK_ID_PRE_UPDATE,   CALLBACK_ID_POST_UPDATE, CALLBACK_ID_DONE_SPEAKING, CALLBACK_ID_GAZE_STATUS, CALLBACK_ID_LPOINT_STATUS,   CALLBACK_ID_SHOW, CALLBACK_ID_HIDE, CALLBACK_ID_PRE_DIE, CALLBACK_ID_POST_DIE,   CALLBACK_ID_PRE_FIRE_WEAPON, CALLBACK_ID_POST_FIRE_WEAPON, CALLBACK_ID_IMPACT, CALLBACK_ID_FIRE_WEAPON_SUCCESS,   CALLBACK_ID_CURRENT_ACTION_CHANGED, CALLBACK_ID_DESIRED_ACTION_CHANGED, CALLBACK_ID_DESIRED_ACTION_REACHED, CALLBACK_ID_MANUALLY_INVOKED,   CALLBACK_ID_USER_SELECTED, CALLBACK_ID_USER_UNSELECTED, CALLBACK_ID_IGUY_INTERACT, CALLBACK_ID_IGUY_INTERACT_WITH_SUBJECT,   CALLBACK_ID_GUIDE_POSITION_ACQUIRED, CALLBACK_ID_GUIDE_POSITION_UNACQUIRED, CALLBACK_ID_GUIDE_ORIENTATION_ACQUIRED, CALLBACK_ID_GUIDE_ORIENTATION_UNACQUIRED,   CALLBACK_ID_GUIDE_ALTITUDE_ACQUIRED, CALLBACK_ID_GUIDE_ALTITUDE_UNACQUIRED, CALLBACK_ID_GUIDE_TARGET_LOST, CALLBACK_ID_CURRENT_TOUT_REACHED,   CALLBACK_ID_POST_CREATE_GEOMETRY, CALLBACK_ID_PRE_DESTROY_GEOMETRY, CALLBACK_ID_END_OF_PATH_REACHED, CALLBACK_ID_CHARACTER_CLICKED,   CALLBACK_ID_UI_PRE_TRANSLATION, CALLBACK_ID_UI_POST_TRANSLATION, CALLBACK_ID_UI_MOUSE_DOWN, CALLBACK_ID_UI_MOUSE_UP,   CALLBACK_ID_UI_RIGHT_MOUSE_DOWN, CALLBACK_ID_UI_RIGHT_MOUSE_UP, CALLBACK_ID_UI_LEFT_CLICK, CALLBACK_ID_UI_RIGHT_CLICK,   CALLBACK_ID_UI_DOUBLE_CLICK, CALLBACK_ID_UI_MIDDLE_CLICK, CALLBACK_ID_UI_SCROLL_UP, CALLBACK_ID_UI_SCROLL_DOWN,   CALLBACK_ID_AGENT_NEW_BEHAVIOR, CALLBACK_ID_AGENT_NEW_PATH_SHAPE, CALLBACK_ID_AGENT_NEW_FOCUS_CHARACTER, CALLBACK_ID_AGENT_ATTACK_OUT_OF_TARGETS,   CALLBACK_ID_AGENT_ATTACK_NO_VISIBLE_TARGETS, CALLBACK_ID_AGENT_PURSUE_TARGET_REACHED, CALLBACK_ID_AGENT_PURSUE_TARGET_LOST, CALLBACK_ID_AGENT_MINGLE_TARGET_REACHED,   CALLBACK_ID_AGENT_MINGLE_TARGET_LOST, CALLBACK_ID_AGENT_WANDER_TARGET_REACHED, CALLBACK_ID_AGENT_WANDER_TARGET_LOST, CALLBACK_ID_AGENT_FLEE_AREA_LEFT,   CALLBACK_ID_AGENT_FLEE_AREA_ENTERED, CALLBACK_ID_AGENT_TRAVEL_WAYPOINT_REACHED, CALLBACK_ID_AGENT_TRAVEL_FORWARD_DEST_REACHED, CALLBACK_ID_AGENT_TRAVEL_BACKWARD_DEST_REACHED,   CALLBACK_ID_AGENT_TRAVEL_NEAR_FORWARD_DEST, CALLBACK_ID_AGENT_CROWD_MEMBER_KILLED, CALLBACK_ID_AGENT_CROWD_MEMBER_IMPACT, CALLBACK_ID_AGENT_NEARBY_SCENE_OBJECT_IMPACT,   CALLBACK_ID_AGENT_NEARBY_WEAPON_FIRED, CALLBACK_ID_AGENT_VEHICLE_COLLISION, CALLBACK_ID_AGENT_VEHICLE_NEAR_COLLISION, CALLBACK_ID_AGENT_PATH_PLAN_COMPLETED,   CALLBACK_ID_AGENT_MIND_CURRENT_STATE_CHANGED, CALLBACK_ID_AGENT_NON_ZERO_REPULSION, CALLBACK_ID_AGENT_ZERO_REPULSION }
	This is an enumeration of the different callbacks that can be registered with add_callback() and add_callback_script(). More...

Public Member Functions
General Functions
Unless otherwise specified, all functions callable from: C++ Script
const char *	get_name ()
	Returns the name of the object. More...
int	set_name (const char *name)
	This function sets the name of this object. More...
const char *	get_type_name ()
	Returns the type name of the object, should be 'character'. More...
long	get_uid ()
	All characters are assigned a unique identifier, or uid. More...
int	get_index ()
	Returns the index of the object. More...
int	update (float t, int full_update=1)
	This function updates the character. More...
void	set_character_type (const char *type)
	This function sets the current type of this character. More...
const char *	get_character_type_string ()
	Returns the type of the character (never NULL). More...
const char *	get_character_class ()
	Returns the class of the character (never NULL). More...
diguyCharacterClass	get_character_class_type ()
	returns enum describing the character class More...
diguyScenario *	get_scenario ()
	Returns the scenario that this character is a part of. More...
int	set_enabled (int enabled)
	This is the top-level on/off switch for the character. More...
int	get_enabled ()
	Returns whether the character is enabled, as set by the set_enabled() call. More...
int	set_drawn_by_scenario_flag (int flag)
	Sets whether this character is drawn automatically by the scenario. More...
int	get_drawn_by_scenario_flag ()
	Returns whether character drawing is done automatically by the scenario. More...
void	set_invisible_flag (int invisible_flag)
	This function makes the character invisible; i.e., draw() calls for the character will have no effect. More...
int	get_invisible_flag ()
	Returns: the character's invisible flag, as set by set_invisible_flag() More...
int	get_is_active ()
	Returns whether the character is active. More...
int	get_is_drawn ()
	Returns whether the character will be drawn during scenario and character draw() calls. More...
int	get_was_drawn_last_frame ()
	Was this character drawn last frame, will only be accurate if diguyScenario::pre_draw_cull_state_reset() is called before all render passes are begun. More...
int	set_was_drawn_last_frame (int drawn)
	This function is just included for completeness, it shouldn't be needed. More...
int	get_is_culled ()
	Was the character culled and never drawn. More...
int	set_is_culled (int culled)
	If diguyScenario::pre_draw_cull_state_reset() and diguyScenario::post_draw_cull_state_save() are used in a retained mode renderer it's very important to call this function with set_is_culled(0). More...
int	get_is_temporary ()
	Returns: 1 if the character is temporary (created by diguyScenario::create_temporary_character() call; 0 if not. More...
int	get_is_recycled ()
	This function returns 1 if the character has been recycled from the character recycle bin, 0 if not. More...
int	set_t_controlled_by_scenario_t (int t_controlled_by_scenario_t)
	This function sets how the character's t (time) is controlled. More...
int	get_t_controlled_by_scenario_t ()
	Returns: whether character's t is controlled by the scenario; see set_t_controlled_by_scenario_t() More...
int	set_initial_tin (float tin, int override_time_warning=0)
	This function sets the initial tin ("T In") time of the character. More...
int	set_initial_tout (float tout)
	This function sets the initial tout ("T Out") time of the character. More...
int	set_current_tin (float tin)
	This function sets the current tin ("T In") time of the character. More...
int	set_current_tin_to_now ()
	Same as set_current_tin(), but time is set to current scenario time. More...
float	get_current_tin ()
	This function returns the current tin time of the character. More...
int	set_current_tout (float tout, int disable_character_at_tout=0)
	This function sets the current tout ("T Out") time of the character. More...
int	set_current_tout_to_now ()
	Same as set_current_tout(), but time is set to current scenario time. More...
float	get_current_tout ()
	This function returns the current tout ("T Out") time of the character in seconds. More...
void	set_tout_enabled (int tout_enabled)
	This function sets what will happen when the character reaches its tout time. More...
int	get_tout_enabled ()
	This function returns the whether tout is enabled. More...
int	set_careful_interpolation_threshold (float threshold)
	When the motion data of a character is interpolated a quick interpolation method can be used which may yield incorrect results, or an expensive interpolation method can be used which will yield correct results at the expense of time. More...
float	get_careful_interpolation_threshold ()
	Returns: most recent setting of the careful interpolation threshold; see set_careful_interpolation_threshold() More...
int	set_motion_interpolation_flag (int flag)
	Sets whether the motion data of the character is interpolated. More...
int	get_motion_interpolation_flag ()
	Returns: most recent setting of the motion interpolation flag; see set_motion_interpolation_flag() More...
int	set_scale (float scale_x, float scale_y, float scale_z)
	Sets the scale of the character on each of the three major axes. More...
int	get_scale (float *scale_x, float *scale_y, float *scale_z)
	Returns the scale of the character. More...
int	set_parent (const char *parent_name, const char *parent_link_name="")
	Sets the parent of this character to be the passed character. More...
diguyCharacter *	get_parent ()
	Gets the parent of this character. More...
const char *	get_parent_link_name ()
	Gets the link name that the character is parented to, if any. More...
int	unset_parent ()
	Detaches a character from its parent and reattaches it to the world. More...
int	get_num_children ()
	Gets the number of children the character has. More...
diguyCharacter *	get_child_at_index (int index)
	This function returns a pointer to the nth child of the character. More...
int	get_is_scene_object ()
	Gets if a character is a static object, by default any blitzed . More...
int	set_is_scene_object (int is_scene_object)
	Sets if a character is a static object. More...
float	get_bounding_radius ()
	Gets the bounding radius currently used for this character for purposes of culling it from the draw operation. More...
float	get_default_bounding_radius ()
	Gets the default draw-culling bounding radius for this character, as specified in its actor cfg file. More...
void	set_bounding_radius (float f)
	Sets the current draw-culling bounding radius to be used for this character. More...
float	get_time_to_transition ()
	This function returns the number of seconds before the blend into the next motion begins. More...
diguyCharacterMode	get_action_mode ()
	Returns: the action mode of the character. More...
diguyCharacterMode	get_position_mode ()
	Returns: the position mode of the character. More...
int	set_t_scale_factor (float t_scale_factor)
	This function speeds up or slows down the character. More...
int	unset_t_scale_factor ()
	This function removes the manual setting of the time scale factor as set by set_t_scale_factor(). More...
int	is_within_distance_n_of_character (const char *character_name, float distance)
	This function determines whether this character is within the specified distance of another. More...
int	is_within_distance_n_of_member_of_group (const char *group_name, float distance)
	This function determines whether this character is within the specified distance of any members of the specified group. More...
int	is_group_member (const char *group_name)
	This function determines whether a character is a member of a particular group. More...
int	get_num_group_memberships ()
	This function returns the number of groups that a character is a member of. More...
diguyCharacterGroup *	get_group_membership_at_index (int index)
	This function returns a pointer to the nth group that this character is a member of. More...
diguyCharacter *	get_nearest_active_character (int check_visibility, int xy_distance=0, float max_distance_to_check=100000)
	This function will check all characters in the scenario and return the nearest character that is both alive and enabled. More...
diguyCharacter *	get_nearest_active_character_in_group (const char *group_name, int check_visibility=1, int xy_distance=0, float max_distance_to_check=100000)
	This function will check all characters in a group and return the nearest character that is both alive and enabled. More...
diguyCharacter *	get_random_active_character (float max_distance=10.0f, int check_visibility=1, int xy_distance=0)
	This function will check all characters in the scenario and return a random character within max_distance that is both alive and enabled. More...
diguyCharacter *	get_random_active_character_in_group (const char *group_name, float max_distance=10, int check_visibility=1, int xy_distance=0)
	This function will check all characters in a group and return a random character within max_distance that is both alive and enabled. More...
float	get_distance_to_character (diguyCharacter *character)
	This function returns the 3D distance from this character to the specified character, in meters. More...
float	get_distance_xy_to_character (diguyCharacter *character)
	This function returns the 2D distance in X and Y coordinates only from this character to the specified character, in meters. More...
float	get_distance_to_impact (diguyImpact *impact)
	This function returns the 3D distance from this character to the specified impact, in meters. More...
float	get_random_factor ()
	Each character has a "random factor" between 0 and 1. More...
C++ Only Functions
int	draw ()
	This function draws this character in immediate mode graphics environments (see below). More...
int	draw_pass1 ()
	This function, along with draw_pass2(), allows the drawing of opaque and transparent polygons to be separated. More...
int	draw_pass2 ()
	Same as draw_pass1(), but draws transparent character parts. More...
void *	get_graphics_ptr ()
	Returns: A pointer to the character's graphics. More...
int	set_graphics_ptr (void *graphics_ptr)
	Sets a graphics environment-specific pointer to graphics data. More...
void	set_graphics_api_node_ptr (void *node_ptr)
	This function sets a generic node pointer that can later be retrieved by the get_graphics_api_node_ptr() call. More...
void *	get_graphics_api_node_ptr ()
	Returns: pointer set by most recent call to set_graphics_api_node_ptr. More...
int	set_user_data (void *user_data)
	This function stores a pointer to user data. More...
void *	get_user_data ()
	Returns: The user data pointer set by set_user_data() More...
Action Functions
Unless otherwise specified, callable from: C++ Script
int	set_desired_action (const char *action_name, float speed=DIGUY_DEFAULT_FLOAT, int retain_path_shape=0)
	This function sets the desired action of the character. More...
const char *	get_desired_action ()
	Returns: name of desired action; see set_desired_action() Note at times this is preferable to the current action since the desired action changes when a transition starts but the current action only changes when a transition finishes. More...
int	get_desired_action_index ()
	Returns index of desired action being performed by the character. More...
const char *	get_current_action ()
	Returns name of current action being performed by the character. More...
int	get_current_action_index ()
	Returns index of current action being performed by the character. More...
diguyMotionDirection	get_current_action_direction ()
	Returns the overall travel direction that the current action is going. More...
int	get_is_in_action_transition ()
	This function returns the transition state of the action of a character. More...
int	force_action (const char *action_name, float speed=DIGUY_DEFAULT_FLOAT, int include_transition_arc=1, float max_rampdown_interval=0.5f, int retain_path_shape=0, float t_offset_into_new_action=0.0f)
	This function forces the current action of the character to be the action identified by action_name. More...
int	force_action_with_duration (const char *action_name, float duration, int include_transition_arc=1, float max_rampdown_interval=0.5f)
	This function is similar to force_action(), but allows the specification of how long the interruption should last. More...
int	force_action_and_path_shape (const char *action_name, const char *path_shape_name, const char *waypoint_name=NULL, float distance_into_path=0.0f)
	This function forces the current action of the character to be the action identified by action_name, to be executed along the path shape specified by path_shape_name. More...
const char *	get_most_recent_forced_action ()
	This function returns the most recently forced action as set by by force_action(), force_action_with_duration(), or force_action_and_path_shape(). More...
float	get_most_recent_forced_action_t ()
	This function returns the time at which the most recently forced action occurred. More...
float	get_most_recent_forced_action_t_offset ()
	This function returns the action time offset of the most recently forced action. More...
int	add_pending_desired_action (const char *action, float scenario_t, int remove_existing_pending_actions=0, float speed=DIGUY_DEFAULT_FLOAT, int retain_path_shape=1)
	This function adds a "pending action" to the character. More...
int	add_pending_force_action (const char *action, float scenario_t, int remove_existing_pending_actions=0, float speed=DIGUY_DEFAULT_FLOAT, int include_transition_arc=1, float max_rampdown_interval=0.5f, int retain_path_shape=1, float first_arc_time_shift=0.0f)
	Similar to add_pending_desired_action(), but will do a force_action() at the passed scenario_t instead of a set_desired_action(). More...
int	is_valid_action (const char *action)
	Returns: 1 if the passed action name is an action available to this character, 0 if not. More...
int	die_now (const char *preferred_dead_action_name="(default)")
	This function sends this character a signal to die as soon as possible. More...
int	revive_now (const char *preferred_revive_action_name="(default)")
	This function revives a dead character. More...
int	get_dead ()
	This function returns whether or not the character is dead. More...
int	set_speed (float speed)
	Sets the speed the character should attempt to move, in meters per second. More...
float	get_speed ()
	Returns: the approximate speed at which the character is moving, in meters per second. More...
float	get_desired_speed ()
	Returns: The desired speed of the character, in meters per second. More...
Animation Blend Tree Parameters
These function feed various parameters into the animation blend tree system, which allows synthesizing multiple animations into one action. The blend tree system can be used to make actions like stand procedurally turn into standing and aiming, or to blend in aiming on top of a walk animation, or to use one action to represent a multi-directional blending graph for locomotion. Unless otherwise specified, all functions callable from: C++ Script
int	set_animation_target_el (float elevation, float ramp_time=.25f)
	Sets a generic parameter that can be mapped to a blend tree driver. More...
float	get_animation_target_el ()
	Returns the current target elevation. More...
int	set_animation_target_az (float azimuth, float ramp_time=.25f)
	Sets a generic parameter that can be mapped to a blend tree driver. More...
float	get_animation_target_az ()
	Returns the current target azimuth. More...
void	set_animation_velocity (float vel_x, float vel_y, float vel_z, float ramp_time=.25f)
	Sets a generic parameter in world space that can be mapped to a blend tree driver. More...
void	get_animation_velocity (float *vel_x, float *vel_y, float *vel_z)
	Returns the world space x,y,z velocity that's driving the blend tree. More...
void	set_animation_local_velocity (float vel_x, float vel_y, float vel_z, float ramp_time=.25f)
	Sets a generic parameter in local space that can be mapped to a blend tree driver. More...
void	get_animation_local_velocity (float *vel_x, float *vel_y, float *vel_z)
	Returns the local space x,y,z velocity that's driving the blend tree. More...
void	set_animation_angular_velocity (float vel_rz, float ramp_time=.25f)
	Sets a generic parameter in that can be mapped to a blend tree driver. More...
float	get_animation_angular_velocity ()
	Returns the angular velocity that's driving the blend tree. More...
Position and Orientation Functions
Unless otherwise specified, callable from: C++ Script
int	set_position (float tx, float ty, float tz)
	Sets the position of the character relative to the origin of the DI-Guy global coordinate system. More...
int	set_position_double (double tx, double ty, double tz)
	Similar to set_position(), but using double-precision rather than single-precision numbers. More...
int	get_position (float *tx, float *ty, float *tz)
	Retrieves the position of the character in the DI-Guy global coordinate system. More...
int	get_position_double (double *tx, double *ty, double *tz)
	Retrieves the position of the character in the DI-Guy global coordinate system. More...
int	set_position_relative_to_parent (float tx, float ty, float tz)
	Sets the position of the character relative to its parent or the origin of the DI-Guy global coordinate system if this character is not parented. More...
int	get_position_relative_to_parent (float *tx, float *ty, float *tz)
	Retrieves the position of the character relative to its parent, or relative to the origin of the DI-Guy global coordinate system if this character is not parented. More...
int	set_position_to_other_character_position (const char *other_character_name, const char *other_link_name=NULL, float offset_x=0.0f, float offset_y=0.0f, float offset_z=0.0f, int also_set_orientation=1)
	Similar to set_position_relative_to_parent(), but the position is either from the other character's overall position (if other_link_name is NULL), or the position of the other character's link (if other_link_name specifies a link on the other character). More...
int	set_desired_position (float tx, float ty, float tz, int force_guide_unacquired=0)
	Sets the desired position of the character. More...
int	set_desired_position_double (double tx, double ty, double tz, int force_guide_unacquired=0)
int	set_desired_position_to_current_position (int also_set_orientation=1)
	Like set_desired_position(), but uses the character's current position as the desired position. More...
int	set_desired_position_to_waypoint (diguyWaypoint *waypoint, float offset_x=0.0f, float offset_y=0.0f, float offset_z=0.0f, int offset_in_world_coords=0)
	Like set_desired_position(), but sets the character's desired position to passed waypoint's position. More...
int	set_desired_position_to_path_waypoint (const char *path_name, const char *waypoint_name)
	Like set_desired_position(), but finds the specified waypoint on the specified path and sets the character's desired position to the waypoint's position. More...
int	set_desired_position_to_path_shape_waypoint (const char *path_shape_name, const char *waypoint_name)
	Like set_desired_position(), but finds the specified waypoint on the specified path shape and sets the character's desired position to the waypoint's position. More...
int	get_desired_position (float *tx, float *ty, float *tz)
	Retrieves the desired position of the character. More...
int	get_desired_position_double (double *tx, double *ty, double *tz)
int	get_delta_to_desired_position (float *tx, float *ty, float *tz)
	Retrieves the delta vector from current position to desired one. More...
int	set_initial_position (float tx, float ty, float tz)
	Sets the initial position the character should move to on a call to diguyScenario::reset(). More...
int	get_initial_position (float *tx, float *ty, float *tz)
	Retrieves the initial position of the character. More...
int	set_orientation (float rz, float rx, float ry)
	Sets the orientation of the character relative to the origin of the DI-Guy global coordinate system. More...
int	get_orientation (float *rz, float *rx, float *ry)
	Retrieves the orientation of the character in the DI-Guy global coordinate system. More...
int	set_orientation_relative_to_parent (float rz, float rx, float ry)
	Sets the orientation of the character relative to its parent or the origin of the DI-Guy global coordinate system if this character is not parented. More...
int	get_orientation_relative_to_parent (float *rz, float *rx, float *ry)
	Retrieves the orientation of the character relative to its parent, or the origin of the DI-Guy global coordinate system if this character does not have a parent. More...
int	set_initial_up_vector_type (char axis)
	This function sets how the character should be oriented relative to its surroundings. More...
int	set_initial_up_vector (char axis)
	This function is being deprecated, but remains for backwards compatibility. More...
char	get_initial_up_vector_type ()
	Returns: current up vector type; see set_initial_up_vector_type() More...
char	get_initial_up_vector ()
	This function is being deprecated, but remains for backwards compatibility. More...
int	set_up_vector_type (char axis)
	This function sets how the character should be oriented relative to its surroundings. More...
int	set_up_vector (char axis)
	This function is being deprecated, but remains for backwards compatibility. More...
char	get_up_vector_type ()
	Returns: current up vector type; see set_up_vector_type() More...
char	get_up_vector ()
	This function is being deprecated, but remains for backwards compatibility. More...
int	set_custom_orientation_rx_and_ry (float rx, float ry)
	This function sets the rx and ry components of the character's orientation. More...
int	set_desired_orientation (float rz, float rx, float ry, int force_guide_unacquired=0)
	Sets the desired orientation of the character. More...
int	get_desired_orientation (float *rz, float *rx, float *ry)
	Retrieves the desired orientation of the character. More...
int	get_delta_to_desired_orientation (float *rz, float *rx, float *ry)
	Retrieves the delta from current orientation of the character to the desired one. More...
int	set_desired_orientation_to_current_orientation ()
	Like set_desired_orientation(), but uses the character's current orientation as the desired orientation. More...
int	set_desired_orientation_towards_position (float x, float y, float z, int force_guide_unacquired=0)
	Like set_desired_orientation(), but orients the character towards the position specified. More...
int	set_initial_orientation (float rz, float rx, float ry)
	Sets the initial orientation the character should move to on a call to diguyScenario::reset(). More...
int	get_initial_orientation (float *rz, float *rx, float *ry)
	Retrieves the initial orientation of the character. More...
int	get_link_position (const char *link_name, float *tx, float *ty, float *tz, float *rz, float *rx, float *ry)
	Returns the location and orientation of a specific link of the character. More...
int	get_link_position_double (const char *link_name, double *tx, double *ty, double *tz, double *rz, double *rx, double *ry)
	Returns the location and orientation of a specific link of the character. More...
int	get_link_position_with_offset (const char *link_name, float offset_tx, float offset_ty, float offset_tz, float *tx, float *ty, float *tz, float *rz, float *rx, float *ry)
	Similar to get_link_position(), but allows specification of offset into ending link. More...
int	get_link_position_with_offset_double (const char *link_name, double offset_tx, double offset_ty, double offset_tz, double *tx, double *ty, double *tz, double *rz, double *rx, double *ry)
	Similar to get_link_position(), but allows specification of offset into ending link. More...
int	get_link_relative_position (const char *beginning_link_name, const char *ending_link_name, float *tx, float *ty, float *tz, float *rz, float *rx, float *ry)
	Returns the location and orientation of a specific link of the character relative to the position of another link. More...
int	get_link_relative_position_with_offset (const char *beginning_link_name, const char *ending_link_name, float offset_tx, float offset_ty, float offset_tz, float *tx, float *ty, float *tz, float *rz, float *rx, float *ry)
	Similar to get_link_relative_position(), but allows specification of offset into ending link. More...
void	set_apply_actor_scale_to_action_bead_travel (int apply_scale_flag)
	By default characters on a path will scale their movement speed and velocity based on the scale of the actor the character is based on. More...
int	get_apply_actor_scale_to_action_bead_travel ()
	Returns: 1 if actor scale is being applied to travel, 0 if not. More...
int	local_to_global (float x, float y, float z, float *res_x, float *res_y, float *res_z)
	This function transforms a point that is in the local space of the character into a location in the world. More...
int	global_to_local (float x, float y, float z, float *res_x, float *res_y, float *res_z)
	This function transforms a point that is in world space into the local space of a character. More...
void	get_velocity (float *vel_x, float *vel_y, float *vel_z)
	Retrieves the current estimated velocity of the character. More...
void	set_desired_velocity (float vel_x, float vel_y, float vel_z, float ramp_time=0.0)
	Used by the Drift and Adaptive guide. More...
void	get_desired_velocity (float *vel_x, float *vel_y, float *vel_z)
void	get_angular_velocity (float *vel_rz)
	Retrieves the current estimated angular velocity of the character. More...
void	set_desired_angular_velocity (float vel_rz)
	Used by the Drift and Adaptive guide. More...
void	get_desired_angular_velocity (float *vel_rz)
Appearance Functions
const char *	get_appearance ()
	Returns the base appearance of the character, as passed to the function diguyScenario::create_character(). More...
int	set_appearance (const char *appearance)
	This function sets the base appearance of the character. More...
int	set_current_appearance (const char *appearance, int allow_actor_change=1)
	This function sets the current appearance of this character. More...
const char *	get_current_appearance ()
	Returns: current appearance; see set_current_appearance() More...
int	get_current_appearance_is (const char *appearance)
	This function can be used to see if the current appearance has the passed name. More...
int	set_current_head_appearance (const char *head_appearance)
	This function sets the current head appearance of this character. More...
int	set_head_appearance (const char *head_appearance)
	This function sets the head appearance of this character. More...
const char *	get_current_head_appearance ()
	Returns: current head appearance; see set_current_head_appearance() More...
int	get_current_head_appearance_is (const char *head_appearance)
	Similar to get_current_appearance_is(), but for head appearance. More...
int	set_hand_item (const char *hand_item_appearance)
const char *	get_hand_item ()
	Returns: Hand item appearance; see set_hand_item() More...
int	set_current_hand_item (const char *hand_item_appearance)
const char *	get_current_hand_item ()
	Returns: Current hand item appearance. More...
int	get_num_appearances_of_type (diguyCharacterAppearanceTypes appearance_type)
const char *	get_appearance_name_at_index (diguyCharacterAppearanceTypes appearance_type, int index)
	See description for get_num_supplementary_appearances_of_type() More...
Performance Functions
The functions is this section give control over various settings that can have a big impact on the performance of the character. In this case, better performance means less time to update and/or draw the character each frame. Better performance almost always comes at the expense of reduced functionality and/or degraded visual appearance. Many of the parameters below can be automatically managed by a diguyLoadManager, which is returned by diguyApp::create_load_manager(). Unless otherwise specified, all functions callable from: C++ Script
int	set_lod_ranges (float *lod_ranges)
	Sets the graphics level of detail (LOD) ranges for this character. More...
float *	get_lod_ranges ()
	returns float * list of lod ranges that's get_num_lods() long. More...
int	get_num_lods ()
	should always return 8 More...
int	set_graphics_lod (int lod)
	Set the desired graphics level of detail (LOD) for this character. More...
int	get_graphics_lod ()
	Returns current graphics LOD. More...
int	set_shader_lod (int lod)
	Set the desired shader level of detail (LOD) for this character. More...
int	get_shader_lod ()
	Returns: current shader LOD. More...
int	set_motion_lod (int motion_lod)
	** More...
int	get_motion_lod ()
	Returns: character's current motion LOD setting; see set_motion_lod() More...
int	get_current_motion_lod ()
	Returns: character's current motion LOD based on load manangement and culling; see set_motion_lod() More...
int	set_minimum_cpl (int minimum_cpl)
	** More...
int	get_minimum_cpl ()
	Returns: most recent setting of set_minimum_cpl() More...
int	get_maximum_possible_current_cpl ()
	This function returns that maximum possible CPL the character can attain based on what it is currently doing. More...
int	maximize_current_cpl ()
	This function puts the character into the maximum possible CPL that can be achieved based on what the character is currently doing. More...
int	set_automatic_cpl_switching_enabled (int enabled)
	This function sets a flag that determines whether the character should raise and lower its CPL automatically. More...
int	get_automatic_cpl_switching_enabled ()
	Returns: most recent setting of get_automatic_cpl_switching_enabled() More...
int	set_current_cpl (int current_cpl)
	This function sets the current CPL of the character. More...
int	get_current_cpl ()
	Returns: the current CPL the character is using. More...
int	set_position_update_rate (int update_rate)
	This function sets the position update rate of the character. More...
int	get_position_update_rate ()
	Returns: character's position update rate as set by set_position_update_rate() More...
int	set_pose_update_rate (int update_rate)
	This function is very similar to set_position_update_rate(), but sets the percentage of ticks for which the character's pose is updated. More...
int	get_pose_update_rate ()
	Returns: character's pose update rate as set by set_pose_update_rate() More...
int	set_minimum_full_update_period (float min_period)
	This function sets the minimum period for position or pose updates. More...
float	get_minimum_full_update_period ()
	Returns: character's minimum full update period, as set by set_minimum_full_update_period() More...
int	set_position_accumulation_disabled (int disabled_flag)
	This function disables position accumulation due to played actions. More...
int	get_position_accumulation_disabled ()
	Returns: most recent setting of set_position_accumulation_disabled() More...
int	set_all_blends_disabled (int disabled_flag)
	This function disables all blends between motions of the character. More...
int	get_all_blends_disabled ()
	Returns: most recent setting of set_all_blends_disabled() More...
int	set_shape_switches_disabled (int disabled_flag)
	** More...
int	get_shape_switches_disabled ()
	Returns: most recent setting of set_shape_switches_disabled() More...
int	set_shape_callbacks_disabled (int disabled_flag)
	** More...
int	get_shape_callbacks_disabled ()
	Returns: most recent setting of set_shape_callbacks_disabled() More...
int	set_graphics_api_shape_update_disabled (int disabled_flag)
	** More...
int	get_graphics_api_shape_update_disabled ()
	Returns: most recent setting of set_graphics_api_shape_update_disabled() More...
int	optimized_update (float t)
	This function is a stripped-down version of the normal update() function. More...
int	set_is_load_managed (int is_load_managed)
	This function sets whether many of the performance tuning functions above are automatically managed by a diguyLoadManager object, which can be obtained by calling diguyApp::create_load_manager(). More...
int	get_is_load_managed ()
	Returns: most recent setting of get_is_load_managed() More...
C++ Callback Functions
int	add_callback (int callback_id, diguyCharacterCallback *callback, void *callback_params=0, void *callback_user_data=0)
	This function adds a user callback. More...
int	remove_callback (int callback_id, diguyCharacterCallback *callback)
	This function removes a user callback. More...
int	remove_callback_with_user_data (int callback_id, void *callback_user_data)
	This function removes a user callback. More...
C++ and Script Callback Functions
int	add_callback_script (int callback_id, const char *callback_script, const char *callback_script_type=NULL)
	This function adds a user callback script. More...
int	remove_callback_script (int callback_id, const char *callback_script, const char *callback_script_type=NULL)
	This function removes a user callback script previously added with add_callback_script(). More...
Event Handler Functions
Unless otherwise specified, all functions callable from: C++ Script
int	map_event_handler_to_callback_id (int callback_id, const char *handler_name)
	This function maps the event handler with the given name to a callback id. More...
int	unmap_event_handler_from_callback_id (int callback_id, const char *handler_name, int unmap_all_matches=0)
	This function unmaps the event handler with the given name from a callback id. More...
diguyCallbackReturn	manually_invoke_event_handler (const char *handler_name)
	This function manually invokes the named character event handler. More...
Path Functions
diguyCharacterPath *	create_path (const char *name)
	This function creates a new path. More...
diguyCharacterPath *	create_simple_path (const char *name, diguyWaypoint *waypoint0, diguyWaypoint *waypoint1, const char *transition_from_action_name, const char *fill_action_name, const char *transition_to_action_name)
	This function creates a new simple path. More...
diguyCharacterPath *	create_path_from_path_shape (const char *name, diguyPathShape *source_path_shape, const char *transition_from_action_name, const char *fill_action_name, const char *transition_to_action_name)
	This function is similar to create_simple_path(), but creates its waypoints based on waypoints from the passed path shape. More...
int	create_and_force_bridge_path (const char *destination_path_name, const char *destination_path_action_bead_name, const char *via_action_name)
	This function creates a temporary path and immediately forces it as the character's current path. More...
int	create_and_force_bridge_path_to_point (float x, float y, float z, float path_offset, const char *via_action_name, const char *next_local_path=NULL, float orientation=0.0f)
	This function creates a temporary path and immediately forces it as the character's current path. More...
int	destroy_path (diguyCharacterPath *path)
	This function destroys a path created by create_path(), create_simple_path(), or a path from a loaded scenario. More...
int	get_num_paths ()
	Returns: the number of paths belonging to this character. More...
diguyCharacterPath *	get_path_at_index (int index)
	Returns: pointer of type diguyCharacterPath; NULL if no path at the specified index. More...
const char *	get_path_name_at_index (int index)
	Returns: the name of the path at the given index; NULL if no path at the specified index. More...
int	get_current_path_index ()
	This function returns the index of the path the character is currently following. More...
diguyCharacterPath *	get_current_traveled_path ()
	This function returns the path the character is currently traveling. More...
int	get_current_traveled_path_is (const char *path_name)
	This function can be used to see if the current traveled has the passed name. More...
int	push_path (const char *path_name)
	This function pushes the path with the specified name onto the queue of paths this character will follow. More...
int	force_path (const char *path_name, float max_rampdown_interval=0.5f)
	This function clears the queue of paths the character will follow and then pushes the path with the specified name. More...
int	force_partial_path (const char *path_name, const char *beginning_action_bead_name, float max_rampdown_interval=0.5f)
	Same as force_path(), but only motions at or after the specified action bead are added. More...
int	resume_interrupted_path (float max_rampdown_interval=0.5f)
	Resumes a path that was interrupted with a call such as set_desired_action() or force_action(). More...
diguyCharacterPath *	force_local_path (const char *path_name, int use_character_orientation, float rotation=0.0f, int clamp_path=1)
	This function creates a temporary path that is a copy of path_name but transformed so that the starting point is the same as where the character currently is. More...
int	set_initial_path (const char *name)
	This function sets which path the character will start on when the scenario is reset. More...
const char *	get_initial_path ()
	This function returns the name of the path the character will start on when the scenario is reset. More...
void	translate_all_paths (float tx, float ty, float tz, int reclamp_waypoints=1)
	This function translates all of the paths of this character. More...
int	rotate_all_paths_about_point (float rz, float rx, float ry, float rotation_pt_x, float rotation_pt_y, float rotation_pt_z, int reclamp_waypoints=1)
	This function rotates all of the paths of this character. More...
int	rotate_all_paths_about_current_waypoint (float rz, float rx, float ry, int reclamp_waypoints=1)
	This function is similar to rotate_all_paths_about_point(), but rotates around the character's current waypoint instead of an explicitly specified point. More...
int	jump_to_action_bead (const char *bead_name, float max_rampdown_interval=0.5f)
	This function causes the character to jump forward along its current path to the specified action bead. More...
diguyCharacterPath *	find_path (const char *path_name)
	This function finds and returns a pointer to the specified path. More...
int	apply_aim_bead (diguyCharacterPathAimBead *bead, float how_far=0.0f)
	This function causes the effects of the given aim bead to be applied to this character, regardless of whether the bead belongs to the character or whether character is within the bead's time interval. More...
int	apply_decision_bead (diguyCharacterPathDecisionBead *bead, float how_far=0.0f)
	This function causes the effects of the given decision bead to be applied to this character, regardless of whether the bead belongs to the character or whether character is within the bead's time interval. More...
int	apply_gaze_bead (diguyCharacterPathGazeBead *bead, float how_far=0.0f)
	This function causes the effects of the given gaze bead to be applied to this character, regardless of whether the bead belongs to the character or whether character is within the bead's time interval. More...
int	apply_script_bead (diguyCharacterPathScriptBead *bead, float how_far=0.0f)
	This function causes the effects of the given script bead to be applied to this character, regardless of whether the bead belongs to the character or whether character is within the bead's time interval. More...
int	set_distance_along_path (float distance)
	This function sets how far along the current path shape the character will be. More...
float	get_distance_along_path ()
	Returns: the distance in meters along the path shape; see set_distance_along_path() More...
int	leave_path ()
	This function takes the character off of its current path or path shape. More...
int	get_nearest_waypoint_index_in_path (const char *path_name)
	This function returns the index of the nearest waypoint in a path, the path argument is looked up in both the character's path list and the scenario's paths. More...
float	get_distance_to_path (const char *path_name, const char *action_bead_name=NULL)
	Returns: Distance to action bead or first waypoint, 100000000.0 on failure. More...
Link and Shape Functions
The following functions provide access to the links (bones) and shapes (visible geometry) of the character.
diguyGraphicsLink *	get_position_link ()
	This function gets the position link of the character skeleton. More...
int	get_num_links ()
	Returns: number of links on this character. More...
diguyGraphicsLink *	get_link_at_index (int index)
	Returns: pointer of type diguyGraphicsLink; NULL if no link at the specified index. More...
diguyGraphicsLink *	find_link (const char *name)
	This function returns a pointer to the specified link. More...
const char *	get_link_name_at_index (int link_index)
	Returns: the string identifying the link at the given index. More...
int	get_num_link_shapes (const char *link_name)
	Returns: the number of shapes on the specified link. More...
const char *	get_link_shape_name_at_index (const char *link_name, int shape_index)
	Returns: the name of the shape at the specified index on the link. More...
int	get_num_connection_points ()
	Returns the number of connection points (extra per appearance skeletal nodes) More...
const char *	get_connection_point_name_at_index (int index)
	The name of the connection point in the list. More...
int	get_num_connection_points_with_type (diguyConnectionPointType type)
	Returns the number of connection points that have been tagged with the metadata diguyConnectionPointType type. More...
const char *	get_connection_point_name_with_type (diguyConnectionPointType type, int index)
	Returns the name of the connection point in the list of connection with type metadata. More...
void	set_link_visibility (const char *link_or_connection_name, int visible, int shape_index=-1)
	This is for setting visibility of shapes attached to a character at a link. More...
Altitude Functions
While a character is in path position mode its altitude (position in z direction) is most often determined by the path. Characters in free position mode often need their altitude to be determined by another method. This can be done by either setting the position manually (e.g., via the set_position() call) or semi-automatically by registering an altitude function. An altitude function is a callback function that gets called once per character update. Based on the character's updated x and y position, the callback can calculate and return an appropriate z position. This is commonly done via some type of graphics intersection testing. Unless otherwise specified, all functions callable from: C++ Script
int	set_altitude_function (diguyAltitudeFunction *altitude_function)
	The following prototype should be used for the altitude function: More...
diguyAltitudeFunction *	get_altitude_function ()
	Returns: current altitude function; see set_altitude_function() More...
int	set_altitude_function_enabled_in_free_position_mode (int enabled)
	This function sets whether the character's altitude function is enabled in free position mode. More...
int	get_altitude_function_enabled_in_free_position_mode ()
	Returns: whether the character's altitude function is enabled in free position mode; see set_altitude_function_enabled_in_free_position_mode() More...
int	set_altitude_function_enabled_in_path_position_mode (int value)
	This function sets whether the character's altitude function is enabled in path position mode. More...
int	get_altitude_function_enabled_in_path_position_mode ()
	Returns: whether the character's altitude function is enabled in path position mode; see set_altitude_function_enabled_in_path_position_mode() More...
int	set_altitude_update_rate (int update_rate)
	This function sets the altitude update rate of the character. More...
int	get_altitude_update_rate ()
	Returns: character's altitude update rate as set by set_altitude_update_rate() More...
void	set_altitude_interpolation_rate (float interpolation_rate)
	This function sets the altitude interpolation rate of the character. More...
float	get_altitude_interpolation_rate ()
	Returns: character's altitude update rate as set by set_altitude_interpolation_rate() More...
Pose Functions
These functions are used to query a character's joint angles, and set them to the joint angles to arbitrary values. The DI-Guy motion engine applies pose overrides to the base motion of the character in stages. Overrides happening at later stages can overwrite those at earlier stages. The override stages are as follows: 0. reserved for user lpoint base gesture (see lpoint_at_angle()) gaze/lpoint: back, cervical, shoulder_l, elbow_l joints (see gaze_at_angle()) default of user pose overrides (see create_pose_override()) gestures (see create_gesture()) nodding and shaking of head (see nod_head()) motion texture (see add_motion_texture()) gaze: eyes (see gaze_at_angle()) (nothing) reserved for user Notice that eye gaze happens at a late stage, so that the eyes can still track a gaze target even when the character is nodding, has a motion texture, is gesturing, etc. Stages 0 and 9 are reserved for the user. Overrides happening at stage 9 will have precedent over every other pose override function. Unless otherwise specified, all functions callable from: C++ Script The following example shows how to use some of the pose functions. diguyScenario* scenario; diguyCharacter* soldier; diguyCharacterPoseOverride* pose_override; // ... (Create and initialize the scenario) // // Create a character. // soldier = scenario->create_character("joe", "soldier"); // // Create a pose override for that character. // pose_override = soldier->create_pose_override(); // // Allocate a list of joint angle names and fill it. // Print the joint angle names, then destroy the array. // char** varnames = pose_override->allocate_var_names(); pose_override->get_var_names(varnames); for (i = 0; i < soldier->get_pose_array_size(); i++) bdi_log_printf(BDI_LOG_INFO, "%s\n", varnames[i]); pose_override->free_var_names(varnames); // // Allocate a new array of pose angles. // Allocate a weights_array, and initialize it to all 0s. // pose_array = pose_override->allocate_pose_array(); weights_array = pose_override->allocate_pose_array(); for (i=0; i<soldier->get_pose_array_size(); i++) weights_array[i] = 0.0f; // // Find the indices of the character's back angles. Set the // weights for these angles in weights_array to 1. This // means that when we call set_pose_in_radians(), the values // in pose_array will completely override the original // data for the back. // back_rz_index = pose_override->get_var_index("q.back_rz"); back_rx_index = pose_override->get_var_index("q.back_rx"); back_ry_index = pose_override->get_var_index("q.back_ry"); pose_array[back_rz_index] = 0.57f; // angle measured in radians pose_array[back_rx_index] = 0.0f; // angle measured in radians pose_array[back_ry_index] = 0.0f; // angle measured in radians weights_array[back_rz_index] = 1.0f; weights_array[back_rx_index] = 1.0f; weights_array[back_ry_index] = 1.0f; pose_override->set_pose_in_radians(pose_array, weights_array, 0.0f); ... // (Rest of program runs) // // Destroy the pose override object and the arrays // it allocated. // pose_override->free_pose_array(pose_array); pose_override->free_pose_array(weights_array); soldier->destroy_pose_override(pose_override);
int	get_pose_array_size ()
	Returns the number of variables in this character's pose array. More...
int	get_pose_in_radians (float *pose_array)
	Fills an array of floats with the character's current joint angles. More...
diguyCharacterPoseOverride *	create_pose_override (int override_stage=3)
	Creates and returns a pose override object. More...
int	destroy_pose_override (diguyCharacterPoseOverride *po)
	Destroys a pose override object, ending its influence on the character. More...
int	get_num_pose_overrides ()
	Returns: the number of pose overrides belonging to this character. More...
diguyCharacterPoseOverride *	get_pose_override_at_index (int index)
	Returns: pointer of type diguyCharacterPoseOverride; NULL if no pose override at the specified index. More...
diguyCharacterPoseOverride *	create_complete_pose_override ()
	Creates and returns a pose override object that completely overrides all other character pose operations, including motions, aiming, gazing, gestures, other pose overrides, etc. More...
void	destroy_complete_pose_override ()
	Removes and destroys the complete pose override created by create_complete_pose_override(). More...
Gaze and Point Functions
int	gaze_at_angle (float azimuth, float elevation, float distance, int is_new_gaze=1)
	This function sets the current azimuth, elevation, and distance of the character's gaze. More...
int	gaze_at_angle_local (float azimuth, float elevation, float distance=10000.0f, int is_new_gaze=1)
	This function is identical to gaze_at_angle() except that it uses body local coordinates for the character. More...
int	gaze_at_point (float tx, float ty, float tz, int is_new_gaze=1)
	This function sets the current fixation point of the character's gaze. More...
int	gaze_at_point_local (float tx, float ty, float tz, int is_new_gaze=1)
	This function is identical to gaze_at_point() except that it uses body local coordinates for the character. More...
int	gaze_at_character (const char *target_character_name, const char *target_character_link_name=NULL, float offset_tx=0.0f, float offset_ty=0.0f, float offset_tz=0.0f)
	This function effectively does a gaze_at_point() each tick. More...
int	get_gaze_is_active ()
	Returns: 1 if the character is actively gazing, 0 if not. More...
int	get_gaze_point (float *x, float *y, float *z)
	Returns: the current gaze point relative to the DI-Guy global coordinate system. More...
int	get_gaze_is_acquired ()
	A gaze is acquired if the final link in the gaze link chain has fully oriented toward the gaze target, even if other links in the gaze chain are still moving. More...
int	get_gaze_is_steady ()
	A gaze is steady if it is acquired, and if all links involved in the gaze have reached a steady state. More...
int	end_gaze ()
	This function removes the fixation target of an ongoing gaze, allowing the character to return to a non-gaze posture and behavior. More...
int	lpoint_at_angle (float azimuth, float elevation, float distance, int is_new_lpoint=1, const char *base_gesture_name=0)
	This function is similar to gaze_at_angle(), but sets the target of left pointing rather than gaze. More...
int	lpoint_at_angle_local (float azimuth, float elevation, float distance=10000.0f, int is_new_lpoint=1, const char *base_gesture_name=0)
	This function is identical to gaze_at_local() except that it uses body local coordinates for the character. More...
int	lpoint_at_point (float tx, float ty, float tz, int is_new_lpoint=1, const char *base_gesture_name=0)
	This function sets the current fixation point for the character's left pointing. More...
int	lpoint_at_point_local (float tx, float ty, float tz, int is_new_lpoint=1, const char *base_gesture_name=0)
	This function is identical to lpoint_at_local() except that it uses body local coordinates for the character. More...
int	lpoint_at_character (const char *target_character_name, const char *target_character_link_name=NULL, float offset_tx=0.0f, float offset_ty=0.0f, float offset_tz=0.0f)
	This function is identical to gaze_at_character(), but sets the target of left pointing rather than gaze. More...
int	get_lpoint_point (float *x, float *y, float *z)
	Returns: the current lpoint target point relative to the DI-Guy global coordinate system. More...
const char *	get_lpoint_base_gesture_name ()
	Returns: the current base gesture of the lpoint. More...
int	get_lpoint_is_active ()
	Returns: 1 if the character is actively lpointing, 0 if not. More...
int	get_lpoint_is_acquired ()
	Returns: 1 if the final link in the lpoint can and has become oriented toward the lpoint target; 0 if not; -1 on error. More...
int	get_lpoint_is_steady ()
	Returns: 1 if all links participating in the lpoint have reached a relatively steady state; 0 if not; -1 on error. More...
int	end_lpoint ()
	This function removes the fixation target of an ongoing lpoint, allowing the character to return to a non-point posture and behavior. More...
int	set_gaze_params_to_defaults ()
	This function sets all gaze control parameters back to their default settings. More...
int	set_gaze_param_desired_locate_time (float t)
	This function sets the desired amount of time in seconds it will take for the gaze or point target to be acquired. More...
float	get_gaze_param_desired_locate_time ()
	Returns: the most recent setting of set_gaze_param_desired_locate_time() More...
int	set_gaze_link_uses_desired_locate_time (const char *link_name, int uses_desired_locate_time)
	This function sets whether the specified link will pay attention to the desired locate time (as set by set_gaze_param_desired_locate_time()), or whether the link turns as fast as its maximum angular velocity allows (as set by set_gaze_link_max_angular_vel()). More...
int	get_gaze_link_uses_desired_locate_time (const char *link_name)
	Returns: the most recent setting of set_gaze_link_uses_desired_locate_time() More...
int	set_gaze_link_azimuth_limits (const char *link_name, float min, float max)
	This function sets the maximum amount the character can turn the specified link horizontally in pursuit of a gaze or point target. More...
int	get_gaze_link_azimuth_limits (const char *link_name, float *min, float *max)
	Returns: the most recent setting of set_gaze_link_azimuth_max() More...
int	set_gaze_link_elevation_limits (const char *link_name, float min, float max)
	This function sets the maximum amount the character can turn the specified link vertically in pursuit of a gaze or point target. More...
int	get_gaze_link_elevation_limits (const char *link_name, float *min, float *max)
	Returns: the most recent setting of set_gaze_link_elevation_max() More...
int	set_gaze_link_azimuth_tolerance (const char *link_name, float min, float max)
	This function sets how much difference there can be between the link's current horizontal orientation and the gaze or point target before the link begins to turn to acquire the gaze or point target. More...
int	get_gaze_link_azimuth_tolerance (const char *link_name, float *min, float *max)
	Returns: the most recent setting of set_gaze_link_azimuth_max() More...
int	set_gaze_link_elevation_tolerance (const char *link_name, float min, float max)
	The elevation equivalent of set_gaze_link_azimuth_tolerance(),. More...
int	get_gaze_link_elevation_tolerance (const char *link_name, float *min, float *max)
	Returns: the most recent setting of set_gaze_link_elevation_max() More...
int	set_gaze_link_max_angular_vel (const char *link_name, float angular_vel)
	This function sets the maximum angular velocity that the back link angles may attain in pursuit of a gaze or point target. More...
int	get_gaze_link_max_angular_vel (const char *link_name, float *angular_vel)
	Returns: the most recent setting of set_gaze_link_max_angular_vel() More...
int	set_gaze_link_scale_factor (const char *link_name, float scale_factor)
	This function sets how much the link will make up the difference toward the gaze or point target. More...
int	get_gaze_link_scale_factor (const char *link_name, float *scale_factor)
	Returns: the most recent setting of set_gaze_link_scale_factor() More...
int	set_link_enabled_for_gaze (const char *link_name, int enabled)
	This function sets whether the character can turn the specified link in pursuit of the gaze target. More...
int	get_link_enabled_for_gaze (const char *link_name)
	Returns: the most recent setting of set_link_enabled_for_gaze() More...
int	set_gaze_can_change_posture (int enabled)
	This function sets whether the character can change its current posture in pursuit of the gaze target. More...
int	get_gaze_can_change_posture ()
	Returns: the most recent setting of set_gaze_can_change_posture() More...
int	set_gaze_can_change_variant (int enabled)
	This function sets whether the character can change its current variant in pursuit of the gaze target. More...
int	get_gaze_can_change_variant ()
	Returns: the most recent setting of set_gaze_can_change_variant() More...
int	set_link_enabled_for_lpoint (const char *link_name, int enabled)
	This function sets whether the character can move the specified link in pursuit of the lpoint target. More...
int	get_link_enabled_for_lpoint (const char *link_name)
	Returns: the most recent setting of set_link_enabled_for_lpoint() More...
int	set_nod (float azimuth, float elevation, float duration=0.5f)
	This function adjusts the current azimuth and elevation offsets of the character's head. More...
int	nod_head (float duration, float nod_count, float nod_elevation0=15.0f, float nod_elevation1=0.0f, float nod_elevation_out=0.0f)
	This function causes the character to nod its head for the specified number of times over the specified duration. More...
int	shake_head (float duration, float shake_count, float shake_azimuth0=-20.0f, float shake_azimuth1=20.0f, float shake_azimuth_out=0.0f)
	This function is similar to nod_head(), except the direction of head movement is side to side rather than up and down. More...
float	get_nod_azimuth ()
	Returns: current nod azimuth setting; see set_nod(), nod_head(), and shake_head() More...
float	get_nod_elevation ()
	Returns: current nod elevation setting; see set_nod(), nod_head(), and shake_head() More...
Aim Functions
The functions in this section generally only affect characters that have aim actions, such as soldiers or "suspects". Aiming characters can use one of two aim algorithms. Each algorithm uses a different approach for moving the aim toward the desired aim azimuth and elevation. Aim algorithm 8 was added in DI-Guy 8, it is the only option currently. It has a fair number of parameters that can be tweaked to achieve the desired balance of quick response and smooth movement. Unless otherwise specified, all functions callable from: C++ Script
int	set_aim (float azimuth, float elevation)
	This function sets the current desired azimuth and elevation of the character's aim. More...
int	aim_at_angle (float azimuth, float elevation, float distance, int is_new_aim=1)
	This function sets the current azimuth, elevation, and distance of the character's aim. More...
int	aim_at_angle_local (float azimuth, float elevation, float distance, int is_new_aim=1)
	This function is identical to aim_at_angle() except that it uses body local coordinates for the character. More...
int	aim_at_point (float x, float y, float z, int is_new_aim=1)
	This function sets the current fixation point of the character's aim. More...
int	aim_at_point_local (float x, float y, float z, int is_new_aim=1)
	This function is identical to aim_at_point() except that it uses body local coordinates for the character. More...
int	aim_at_character (const char *target_character_name, const char *target_character_link_name=NULL, float offset_tx=0.0f, float offset_ty=0.0f, float offset_tz=0.0f)
	This function effectively does an aim_at_point() each tick. More...
void	end_aim ()
	This function terminates aiming started by the set_aim(), aim_at_point(), aim_at_point_local(), aim_at_angle(), aim_at_angle_local(), and aim_at_character() functions. More...
const char *	get_aim_at_character ()
	See aim_at_character() More...
float	get_aim_azimuth ()
	Returns: current aim azimuth; see set_aim() More...
float	get_aim_elevation ()
	Returns: current aim elevation; see set_aim() More...
int	get_aim_trajectory (float *muzzle_x, float *muzzle_y, float *muzzle_z, float *far_x, float *far_y, float *far_z)
	Returns: 1 if the character is aiming 0 if not. More...
int	get_aim_is_possible ()
	Not all actions of a character will be affected by aim commands. More...
int	get_aim_is_acquired ()
	Returns: 1 if the aim is acquired, 0 if not. More...
int	get_aim_is_steady ()
	Returns: 1 if all links participating in the aim have reached a relatively steady state, 0 if not, -1 on error. More...
int	get_is_aiming ()
	Returns: 1 if character is currently aiming, 0 if not. More...
Aim Algorithm 8 Parameters
This aim algorithm works by adjusting the aiming character's pose such that the difference between the current aim angles and the desired aim angles is decreased each scenario tick. How much of that difference that is made up each frame is determined by the factor parameters. The difference between the desired aim angles and the current aim angles, multiplied by a calculated factor, is added to the current aim angles each frame. This causes the aim to "home in" on the desired aim angles. For example, if for each frame the calculated factor is 0.5, half of the difference between the desired and current aim angles is made up. Unless otherwise specified, all functions callable from: C++ Script
void	set_aim_param_acquire_factor (float factor)
	This function sets the steady-state factor that is used once an aim is no longer considered "new". More...
float	get_aim_param_acquire_factor ()
	Returns: the current aim acquire factor parameter. More...
void	set_aim_param_new_aim_factor (float factor)
	This function sets the factor that is used when an aim is considered new. More...
float	get_aim_param_new_aim_factor ()
	Returns: the current new aim factor parameter. More...
void	set_aim_param_new_aim_duration (float duration)
	This function sets how long an aim is considered "new". More...
float	get_aim_param_new_aim_duration ()
	Returns: how long, in seconds, a new aim is considered new. More...
void	set_aim_param_max_per_frame_adj_factor (float factor)
	This function sets the maximum factor that can be used for any single frame for aim convergence attempts. More...
float	get_aim_param_max_per_frame_adj_factor ()
	Returns: the maximum per-frame adjustment factor parameter. More...
void	set_aim_param_azimuth_acquired_range (float range)
	This function sets how close the current aim azimuth must be to the desired aim azimuth in order for the aim to be considered acquired. More...
float	get_aim_param_azimuth_acquired_range ()
	Returns: how close, in degrees, the azimuth must be for the aim to be acquired. More...
void	set_aim_param_elevation_acquired_range (float range)
	This function sets how close the current aim elevation must be to the desired aim elevation in order for the aim to be considered acquired. More...
float	get_aim_param_elevation_acquired_range ()
	Returns: how close, in degrees, the elevation must be for the aim to be acquired. More...
void	set_aim_converge_every_frame (int enabled)
	This function attempts to have the character reach its desired aim angles instantly, every frame. More...
int	get_aim_converge_every_frame ()
	Returns: 0 if instant convergence is disabled, 1 if enabled. More...
Aim and Gaze Target Helpers
const char *	get_aim_at_link ()
	Returns: Name of a reasonable link that other characters could aim at. More...
int	get_aim_at_link_offset (float *offset_x, float *offset_y, float *offset_z)
	Returns: xyz offset from link returned by get_aim_at_link() More...
const char *	get_gaze_at_link ()
	Returns: Name of a reasonable link that other characters could look at. More...
int	get_gaze_at_link_offset (float *offset_x, float *offset_y, float *offset_z)
	Returns: xyz offset from link returned by get_gaze_at_link() More...
Weapon Functions
Unless otherwise specified, all functions callable from: C++ Script
int	fire_weapon (diguyMuzzle muzzle=DIGUY_MUZZLE_DEFAULT)
	This function causes a character to fire his weapon. More...
int	fire_weapon_n_times (int count, float dt=0.2f, const char *override_sound_name=NULL, diguyMuzzle muzzle=DIGUY_MUZZLE_DEFAULT)
	This function causes a character to fire his weapon the specified number of times. More...
int	fire_screen_space_bullet (diguyView *view, float x, float y)
	Fires a bullet at point (x, y) from the camera, using this character as the attacker. More...
int	get_weapon_fire_count (diguyMuzzle muzzle=DIGUY_MUZZLE_DEFAULT)
	Returns: number of times weapon has been fired from specified muzzle. More...
int	set_default_weapon_muzzle (diguyMuzzle muzzle)
	This function sets the default muzzle that will flash when the character fires its weapon due to a call to fire_weapon() or fire_weapon_n_times(). More...
diguyMuzzle	get_default_weapon_muzzle ()
	Returns: current default weapon muzzle that flashes when the character's weapon is fired; see set_default_weapon_muzzle() More...
const char *	get_weapon_muzzle_munition_type (diguyMuzzle muzzle)
	When the character fires its weapon, the results depend on the munition type of the muzzle fired from. More...
const char *	get_default_muzzle_munition_type ()
	Returns: munition type of default muzzle, as set by set_default_weapon_muzzle() More...
int	set_weapon_munition_type_override (const char *munition_type)
	This function allows the default munition type to be overridden. More...
const char *	get_weapon_munition_type_override ()
	Returns: current munition type override in effect, or NULL if none;. More...
int	set_weapon_fires_live_rounds (int weapon_fires_live_rounds)
	This function sets whether the character's weapons fire live rounds. More...
int	get_weapon_fires_live_rounds ()
	Returns: current setting of whether weapon fires live rounds or blanks; see set_weapon_fires_live_rounds() More...
int	set_weapon_sound_override (const char *sound_name)
	A weapon sound is played when the character fires its weapon due to a call to fire_weapon() or fire_weapon_n_times(). More...
const char *	get_weapon_sound_override ()
	The function returns the current weapon sound override, if one is set; see set_weapon_sound_override(). More...
int	set_weapon_sound_gain_override (float gain)
	This function overrides the default gain on the sound played due to a call to fire_weapon() or fire_weapon_n_times(). More...
float	get_weapon_sound_gain_override ()
	Returns: current override gain for weapon sound. More...
void	set_weapon_spread (float spread)
	This function provides aiming assistance by making it possible for roughly-aimed weapons to hit targets. More...
void	set_weapon_near_range (float near_range)
	This function affects how targets are chosen when the character's weapon_spread is nonzero. More...
void	set_weapon_far_range (float far_range)
	This function sets the range of the character's weapon. More...
void	set_weapon_hit_ratio (float hit_ratio)
	This function sets a weapon's ratio of hits to fired rounds. More...
void	set_weapon_max_impacts (int val)
	This function sets the number of potential impacts a fired round can have. More...
int	get_accessory1_state ()
	Returns: state of accessory1. More...
int	get_rifle_state ()
	Returns: state of the character's rifle. More...
int	set_weapon_projectile_is_visible (diguyMuzzle muzzle, int is_visible)
	This function sets whether the projectiles of certain appearances' weapons (such as rocket launchers and RPGs) are visible. More...
int	get_weapon_projectile_is_visible (diguyMuzzle muzzle)
	This function returns the most recent setting of set_weapon_projectile_is_visible(). More...
int	get_weapon_aim_vector (float *muzzle_tx, float *muzzle_ty, float *muzzle_tz, float *end_pt_tx=NULL, float *end_pt_ty=NULL, float *end_pt_tz=NULL, float *muzzle_rz=NULL, float *muzzle_rx=NULL, float *muzzle_ry=NULL, int in_character_local_coordinates=0, diguyMuzzle muzzle=DIGUY_MUZZLE_DEFAULT)
	Retrieves the position and direction of the character's weapon. More...
const char *	get_muzzle_link (diguyMuzzle muzzle=DIGUY_MUZZLE_DEFAULT)
	This function returns the link the passed muzzle is associated with. More...
int	get_muzzle_offset (diguyMuzzle muzzle=DIGUY_MUZZLE_DEFAULT, float *offset_x=NULL, float *offset_y=NULL, float *offset_z=NULL)
	This function returns the offset of the muzzle from the link it is attached to as returned by get_muzzle_link(). More...
int	set_weapon_max_azimuth_error (float h_error)
	This function sets the highest horizontal error possible when the weapon is fired. More...
float	get_weapon_max_azimuth_error ()
	Returns: maximum horizontal aim error. More...
int	set_weapon_max_elevation_error (float v_error)
	Similar to set_weapon_max_azimuth_error(), but for vertical aim. More...
float	get_weapon_max_elevation_error ()
	Returns: maximum vertical aim error. More...
int	set_weapon_tracers_enabled (int enabled)
	This function sets whether tracer effects will be shown when the weapon is fired. More...
int	get_weapon_tracers_enabled ()
	Returns: 1 if tracer effect is enabled, 0 if not. More...
int	get_weapon_rounds_until_tracer (diguyMuzzle muzzle)
	Returns: number of rounds until next tracer. More...
int	set_weapon_shell_eject_enabled (int enabled)
	This function sets whether a shell eject effect will be shown when the weapon is fired. More...
int	get_weapon_shell_eject_enabled ()
	Returns: 1 if shell eject effect is enabled, 0 if not. More...
int	set_weapon_smoke_enabled (int enabled)
	This function sets whether a smoke effect will be shown when the weapon is fired. More...
int	get_weapon_smoke_enabled ()
	Returns: 1 if muzzle smoke effect is enabled, 0 if not. More...
int	trigger_detonation_on_character (const char *munition_name, const char *attacker_name=NULL, float radius_override=-1.0f, int broadcast_on_network=1)
	Similar to diguyScenario::trigger_detonation(), but detonation occurs at character's position. More...
Face Functions
The functions in this section are available only if diguy_facefx_initialize() has been called, and if the character's appearance or head appearance is a "facefx" appearance. All functions in this section are callable from both C++ and Script.
int	set_face_expression (const char *facex_name, float blend_duration, float strength=1.0f)
	This function changes the face of the character to reflect the specified user-defined named facial expression. More...
int	set_orientation_eyes (float azimuth, float elevation, float blend_time=0.0f)
	This function sets the current azimuth and elevation of the character's eyes. More...
int	get_orientation_eyes (float *azimuth, float *elevation)
	This function gets the current azimuth and elevation of the character's eyes. More...
int	set_eye_droop (float droop_amount, float blend_time=0.0f)
	Sets how open the eyes are. More...
float	get_eye_droop ()
	Returns: how open the eyes are as set by set_eye_droop(). More...
int	blink (float duration_in=0.1f, float duration_out=0.2f, float target_in=1.0f, float target_out=0.0f, float tin=DIGUY_DEFAULT_FLOAT)
	This function blinks the eyes. More...
int	set_automatic_blinks_enabled (int enabled, float period=6.0f, float period_variation=3.0f)
	This function enables automatic eye blinking, so that blinks will happen without further function calls. More...
int	get_automatic_blinks_enabled ()
	Returns: 1 if automatic eye blinks are enabled, 0 if not;. More...
void	set_automatic_blink_duration_in (float duration_in)
	This function sets how long it will take the eye to close during automatic eye blinks. More...
float	get_automatic_blink_duration_in ()
	Returns: most recent setting of set_automatic_blink_duration_in() More...
void	set_automatic_blink_duration_out (float duration_out)
	This function sets how long it will take the eye to open during automatic eye blinks. More...
float	get_automatic_blink_duration_out ()
	Returns: most recent setting of set_automatic_blink_duration_out() More...
void	set_automatic_blink_target_in (float target_in)
	This function sets how much the eye will close during automatic eye blinks. More...
float	get_automatic_blink_target_in ()
	Returns: most recent setting of set_automatic_blink_target_in() More...
void	set_automatic_blink_target_out (float target_out)
	This function sets how much the eye will open during automatic eye blinks. More...
float	get_automatic_blink_target_out ()
	Returns: most recent setting of set_automatic_blink_target_out() More...
int	is_speaking ()
	Returns: 1 if the character is speaking, 0 if not. More...
int	set_current_facefx_animation_group (const char *anim_group)
	FaceFX animations are referred to as a group/animation name. More...
const char *	get_current_facefx_animation_group ()
	Returns: the current FaceFX animation group set for this character. More...
const char *	get_facefx_actor ()
	Returns: the name of the FaceFX actor that goes with the current head appearance; returns NULL if there's no FaceFX actor. More...
int	facefx_mount_animset (const char *file_name)
	Mounts an animset on the current FaceFX actor. More...
int	play_facefx_animation (const char *animation, float magnitude_scale=1.0f, float duration_scale=1.0f, float blendin_time=0.1f, float blendout_time=0.1f, int loop=0)
	Plays a FaceFX animation. More...
int	stop_facefx_animations (float blend_time=0.25f, int stop_sounds=1)
	Stops all active FaceFX animations. More...
Lower level FaceFX control functions
int	get_num_facefx_nodes ()
	Returns: the number of nodes in the FaceFX actor's face graph. More...
const char *	get_facefx_node_name (int index)
	Returns: the name of the node with index 'index' in the FaceFX actor's face graph. More...
int	find_facefx_node_index (const char *node_name)
	Returns: the index of the node with name 'node_name'. More...
int	set_facefx_node_value (int node_index, float value, float blend_time=0.25f)
	Allows low level control of individual nodes of the characters face graph. More...
float	get_facefx_node_value (int node_index)
	Retrieves the current final value of a node. More...
Gesture Functions
A gesture is a motion a character can do that temporarily overrides a subset of the character's joints. Gestures are designed to supplement the stock set of character motions. Most gestures are available to all characters. Many gestures proceed in stages. Before stage 2 of the gesture is played, stage 1 must be played. Sometimes a stage is repeated multiple times before the gesture moves on to the next stage. An example of a three stage gesture could be a wave. In stage 1, the gesture raises the character's arm. In stage 2, the arm waves back and forth once. Stage 2 may be repeated multiple times to get the character to wave more than once. Stage 3 lowers the arm back to the character's side. Note that stages are numbered 1 to 3, not 0 to 2. Some gestures have more than one channel. Each channel in a multi-channel gesture contains a variation of the gesture. As the gesture progresses, the character may move from one channel to another. An example of a two channel gesture could be a chop beat gesture for emphasizing speech. Channel A is a small, tentative chop. Channel B is a strong, emphatic chop. If the weights of channels A and B are 1 and 0, respectively, the gesture will be the small chop. If the weights are 0 and 1, respectively, the gesture will be the emphatic chop. If the weights are 0.5 and 0.5, respectively, the gesture will be a combination – partly small, partly emphatic. Unless otherwise specified, all functions callable from: C++ Script
diguyCharacterGesture *	create_gesture (const char *gesture_name)
	This function creates (but does not begin) the specified gesture. More...
int	destroy_gesture (diguyCharacterGesture *gesture)
	This function destroys a gesture object created by create_gesture(). More...
int	execute_gesture (const char *gesture_name, int reps=DIGUY_DEFAULT_INT, float overall_duration=DIGUY_DEFAULT_FLOAT, float channel_A_weight=DIGUY_DEFAULT_FLOAT)
	This function executes the specified gesture. More...
int	execute_1stage_gesture (const char *gesture_name, int reps=DIGUY_DEFAULT_INT, float stage1_duration=DIGUY_DEFAULT_FLOAT, float channel_A_weight=DIGUY_DEFAULT_FLOAT)
	The gesture will automatically begin and end. More...
int	execute_2stage_gesture (const char *gesture_name, int reps=DIGUY_DEFAULT_INT, float stage1_duration=DIGUY_DEFAULT_FLOAT, float stage2_duration=DIGUY_DEFAULT_FLOAT, float channel_A_weight=DIGUY_DEFAULT_FLOAT)
	This function is similar to execute_1stage_gesture(). More...
int	execute_3stage_gesture (const char *gesture_name, int reps=DIGUY_DEFAULT_INT, float stage1_duration=DIGUY_DEFAULT_FLOAT, float stage2_duration=DIGUY_DEFAULT_FLOAT, float stage3_duration=DIGUY_DEFAULT_FLOAT, float channel_A_weight=DIGUY_DEFAULT_FLOAT)
	This function is similar to execute_1stage_gesture(). More...
int	execute_table_gesture (const char *gesture_name, int reps=DIGUY_DEFAULT_INT, const char *loop_action=NULL, const char *begin_action=NULL, const char *end_action=NULL)
	The gesture will automatically begin and end. More...
int	set_executing_table_gesture_desired_action (const char *gesture_name, const char *desired_action)
	Documentation Pending. More...
int	end_executing_gesture (const char *gesture_name)
	This function alerts the specified gesture that it should end. More...
int	abort_executing_gesture (const char *gesture_name, float max_rampdown_interval)
	This function aborts a gesture previously executed by one of the execute_*_gesture() calls, if it is currently executing. More...
int	end_all_gestures ()
	This function alerts all active gestures that they should end. More...
int	abort_all_gestures (float max_rampdown_interval)
	This function aborts all active gestures. More...
Sound Functions
These functions control the playback of diguySound objects owned by the scenario. A diguySoundInstance is a playing copy of a diguySound. Any given sound file (as encapsulated by diguySound) may be playing multiple times. For example, many soldiers firing their weapons may cause multiple instances the same gunshot sounds to be played simultaneously. It is possible for a characters to play a looping sound, but they are restricted to playing one instance of a looping sound at a time. Any time a sound is played a sound instance is being used, either implicitly or explicitly. If the function calls diguyCharacter::play_sound() or diguyCharacter::play_3d_sound() are used, the sound instance is managed internally by DI-Guy; the sound instance will play to completion and then be destroyed. If a sound instance is created by calling diguyCharacter::create_sound_instance(), more control is provided for sound playback. The sound can be started multiple times, stopped before it has completed, etc. Refer to the diguySoundInstance class for details. Unless otherwise specified, all functions callable from: C++ Script
int	play_sound (const char *sound_name, float sound_gain=1.0f, int sound_loops=0)
	This function will play the specified sound. More...
int	play_3d_sound (const char *sound_name, float sound_gain=1.0f, int sound_loops=0)
	This function will play the specified sound at the character's location. More...
diguySoundInstance *	create_sound_instance (const char *sound_name)
	This function creates (but does not start playing) an instance of the specified sound. More...
int	destroy_sound_instance (diguySoundInstance *sound_instance)
	This function destroys a sound instance object created by create_sound_instance(). More...
int	stop_all_sounds (float rampdown_time=0.0f)
	This function stops all active sound instances from this character. More...
int	stop_sound (const char *sound_name, float rampdown_time=0.0f)
	This function stops a named sound instance from this character. More...
int	is_playing_sound (const char *sound_name)
	Returns: 1 if the character is playing a the sound specified, 0 if not. More...
int	set_current_voice_actor (const char *voice_actor)
	Sets the "voice actor" for the character. More...
const char *	get_current_voice_actor ()
	Returns: name of current voice actor, as set by set_current_voice_actor() More...
Network Functions
The following functions get and set attributes that are used by the DI-Guy Networking module. In DI-Guy Networking, characters in a scenario can be divided into two groups: Characters that are "owned" by the scenario and are published to the network for other networking applications. These characters are usually called "local" or "published" characters. Characters that are created to represent network entities published by other networking applications. These characters are usually called "remote" or "reflected" characters. A character cannot be both published and reflected. Some functions are valid for published characters, some are valid for reflected characters, some are valid for both. Some functions are valid with the DIS networking protocol, some are valid with the HLA protocol. The "other networking applications" can be DI-Guy Scenario running on another computer, an application built against the DI-Guy SDK and DI-Guy Networking, or some other DIS or HLA compatible application such as various forms of SAF (semi-automated forces) programs. Unless otherwise specified, all functions callable from: C++ Script
int	get_DIS_lifeform_state ()
	This function returns the state of the character in the form required by DIS. More...
int	get_DIS_primary_weapon_position ()
	This function returns the position of the character's primary weapon, in the form required by DIS. More...
int	get_DIS_secondary_weapon_position ()
	This function returns the position of the character's secondary weapon, in the form required by DIS. More...
int	set_network_marking (const char *network_marking)
	This function sets the Marking Text for characters that are published to the network by DI-Guy Networking. More...
const char *	get_network_marking ()
	This function gets the Marking Text for characters. More...
int	set_is_network_published (int is_network_published)
	This function sets whether this character will be published by DI-Guy Networking. More...
int	get_is_network_published ()
	This function returns whether the character is published by DI-Guy Networking. More...
DtEntityStateRepository *	get_vrlink_entity_state_repository ()
	Experimental function that returns a vrlink entity state repository, useful for adding additional information to a diguy that we don't usually model. More...
int	get_is_network_reflected ()
	This function returns whether the character is a reflected character created by DI-Guy Networking. More...
int	get_is_network_paused ()
	This function returns whether this character is in a "paused" state. More...
int	set_is_network_paused (int paused)
	Overrides built-in logic for network pausing, becomes end user's responsibility to manage. More...
int	get_network_entity_number ()
	This function returns the character's "network entity number". More...
const char *	get_action_from_entity_state (int damage_state, int life_form_state, int primary_weapon_state, float speed, int forward)
	This function returns the name of an action for a character, given the DIS damage state, lifeform state, primary weapon state, speed of the character, and direction of travel. More...
void	set_DIS_damage_state (int state)
	Sets the damage state for the network published character. More...
int	get_DIS_damage_state ()
	Returns the damage state of a network published character. More...
const char *	get_damage_state_appearance_name (int state)
	Returns the name of damage state appearances based on the base appearance of the character. More...
void	set_DIS_smoke_state (int state)
	Sets the smoke state for a network published character. More...
int	get_DIS_smoke_state ()
	Returns the smoke state of a network published character. More...
void	set_DIS_flames_state (int state)
	Sets the flames state for a network published character. More...
int	get_DIS_flames_state ()
	Returns the flames state of a network published character. More...
void	set_DIS_power_plant_state (int state)
	Sets the power plant state for a network published character. More...
int	get_DIS_power_plant_state ()
	Returns the power plant state of a network published character. More...
void	set_emissivity (float r, float g, float b, float lerp_time=.25)
	sets the current emissivity color of the model, overridden by power_plant state in vehicles More...
void	get_emissivity (float **\return, float *g, float **< b >)
	gets the current emissivity color of the model, overridden by power_plant state in vehicles More...
</b > void	set_DIS_trailing_effect_state (int state)
	Sets the trailing effect state for a network published character. More...
int	get_DIS_trailing_effect_state ()
	Returns the trailing effect state of a network published character. More...
void	set_head_lights_state (int state)
	Sets the network headl ight bit to on or off, if a vehicle has head lights it turns them on. More...
int	get_head_lights_state () const
	Returns if the head light are on or off. More...
void	set_tail_lights_state (int state)
	Sets the network head light bit to on or off, if a vehicle has tail lights it turns them on. More...
int	get_tail_lights_state () const
	Returns if the tail lights are on or off. More...
Formation Functions
Unless otherwise specified, all functions callable from: C++ Script
int	call_formation (const char *formation_name, int snap_to_position_flag=0, int break_existing_formations_flag=1)
	This function will create a new active formation with this character as its leader. More...
int	break_formation (const char *formation_name=NULL)
	This function breaks up a formation initiated by call_formation(). More...
Guide Functions
See diguyCharacterGuide for an explanation of the various kinds of guides.
diguyCharacterGuide *	add_guide (const char *guide_name, int automatically_disable_when_acquired=0)
	This function adds a copy of the specified scenario guide to the character. More...
diguyCharacterGuide *	create_guide (const char *guide_name, const char *guide_algorithm, int automatically_disable_when_acquired=0)
	This function creates a new guide and adds it to the character. More...
diguyCharacterGuide *	find_or_create_guide (const char *guide_name, const char *guide_algorithm, int automatically_disable_when_acquired=0)
	Like create_guide(), but returns guide if it already exists. More...
diguyCharacterGuide *	find_guide (const char *guide_name)
	This function returns a pointer to the specified guide of the character, if is exists. More...
int	remove_guide_with_name (const char *guide_name)
	This function removes the specified guide from the character. More...
int	remove_guide (diguyCharacterGuide *guide)
	This function removes the specified guide from the character. More...
int	remove_all_guides ()
	This function removes all guides from the character. More...
int	remove_all_disabled_guides ()
	This function removes all guides that are disabled. More...
Motion Texture Functions
Unless otherwise specified, all functions callable from: C++ Script
int	add_motion_texture (const char *motex_name="default", float texture_gain=1.0f, int end_previous_motex=1, float rampup_interval=0.2f)
	This function adds a "motion texture" to the character. More...
int	end_motion_texture (float rampdown_interval=0.2f)
	This function gradually ends any active motion textures added by add_motion_texture(). More...
int	set_initial_motion_texture (const char *motex_name)
	This function sets an initial motion texture that should be used by the character whenever the character is loaded from a scenario or the character's scenario is reset. More...
const char *	get_initial_motion_texture ()
	This function returns the initial motion texture as set by a call to set_initial_motion_texture(). More...
int	set_initial_motion_texture_gain (float motex_gain)
	This function sets the gain of the initial motion texture of the character. More...
float	get_initial_motion_texture_gain ()
	This function returns the initial motion texture gain as set by a call to set_initial_motion_texture_gain(). More...
History Functions
Unless otherwise specified, all functions callable from: C++ Script
int	set_history_type (diguyHistoryType history_type)
	This function sets what type of "history" will be kept for the character. More...
diguyHistoryType	get_history_type ()
	Returns: the current history type of the character; see set_history_type() More...
int	set_history_size_t (float t)
	This function sets the size of the character's history buffer, in seconds. More...
float	get_history_size_t ()
	This function returns the current history buffer size. More...
int	set_history_size_increment_t (float t)
	This function sets the size of the character's history buffer increment, in seconds. More...
float	get_history_size_increment_t ()
	This function returns the current history buffer size increment. More...
Meta-Action Functions
Unless otherwise specified, all functions callable from: C++ Script
void	set_desired_posture (diguyMotionPosture desired_posture)
	This function sets the desired posture of the character. More...
diguyMotionPosture	get_desired_posture ()
	Returns: current desired posture of the character. More...
void	set_desired_variant (diguyMotionVariant desired_variant)
	This function sets the desired variant of the character. More...
diguyMotionVariant	get_desired_variant ()
	Returns: current desired variant of the character. More...
const char *	get_action_from_description (diguyMotionDirection direction, diguyMotionPosture posture, diguyMotionVariant variant, float speed, diguyParameterComparison comparison=DIGUY_PARAMETER_COMPARISON_NEAREST, float comparison_tolerance=DIGUY_DEFAULT_FLOAT, int match_posture_before_variant=1, diguyMotionPosture posture_alternate1=DIGUY_MOTION_POSTURE_UNKNOWN, diguyMotionPosture posture_alternate2=DIGUY_MOTION_POSTURE_UNKNOWN, diguyMotionVariant variant_alternate1=DIGUY_MOTION_VARIANT_UNKNOWN, diguyMotionVariant variant_alternate2=DIGUY_MOTION_VARIANT_UNKNOWN, int return_random_match=0)
	This function looks up the character action that most closely matches the given criteria. More...
const char *	get_turning_action_from_description (diguyMotionDirection direction, diguyMotionPosture posture, diguyMotionVariant variant, float turn_amount, diguyParameterComparison comparison=DIGUY_PARAMETER_COMPARISON_NEAREST, float comparison_tolerance=DIGUY_DEFAULT_FLOAT, int match_posture_before_variant=1, diguyMotionPosture posture_alternate1=DIGUY_MOTION_POSTURE_UNKNOWN, diguyMotionPosture posture_alternate2=DIGUY_MOTION_POSTURE_UNKNOWN, diguyMotionVariant variant_alternate1=DIGUY_MOTION_VARIANT_UNKNOWN, diguyMotionVariant variant_alternate2=DIGUY_MOTION_VARIANT_UNKNOWN)
	This function is very similar to get_action_from_description(), but substitutes turn amount per action iteration for speed. More...
Variable Functions
Unless otherwise specified, all functions callable from: C++ Script
int	get_num_variables ()
	Returns: number of variables the character has. More...
diguyVariable *	get_variable_at_index (int index)
	Returns: pointer of type diguyVariable; NULL if no variable at the specified index. More...
diguyVariable *	find_variable (const char *name)
	This function returns a pointer to the specified variable. More...
diguyVariable *	find_or_create_variable (const char *name)
	This function finds the variable with the given name or creates it if it doesn't exist. More...
int	destroy_variable (diguyVariable *variable)
	This function destroys the passed variable. More...
int	variable_equal_to_int (const char *varname, int value)
	Returns: 1 if variable is equal to passed value, 0 if not. More...
int	variable_greater_than_int (const char *varname, int value)
	Returns: 1 if variable is greater than passed value, 0 if not. More...
int	variable_less_than_int (const char *varname, int value)
	Returns: 1 if variable is less than passed value, 0 if not. More...
int	variable_equal_to_float (const char *varname, float value)
	Returns: 1 if variable is equal to passed value, 0 if not. More...
int	variable_greater_than_float (const char *varname, float value)
	Returns: 1 if variable is greater than passed value, 0 if not. More...
int	variable_less_than_float (const char *varname, float value)
	Returns: 1 if variable is less than passed value, 0 if not. More...
int	variable_equal_to_string (const char *varname, const char *value)
	Returns: 1 if variable is equal than passed value, 0 if not. More...
int	variable_greater_than_string (const char *varname, const char *value)
	Returns: 1 if variable is greater than passed value (comes later alphabetically), 0 if not. More...
int	variable_less_than_string (const char *varname, const char *value)
	Returns: 1 if variable is less than passed value (comes sooner alphabetically), 0 if not. More...
int	variable_decrement_value_as_int (const char *varname, int value=1)
	This function decrements the variable by the passed amount. More...
int	variable_increment_value_as_int (const char *varname, int value=1)
	This function increments the variable by the passed amount. More...
int	variable_set_value_as_int (const char *varname, int value, int create_if_doesnt_exist=1)
	This function is a convenience function for setting the variable to a new integer value without retrieving the diguyVariable object. More...
int	set_ivar (const char *varname, int value, int create_if_doesnt_exist=1)
	Short form of variable_set_value_as_int(). More...
int	get_ivar (const char *varname, int create_if_doesnt_exist=1)
	This function is a convenience function for retrieving the value of a variable without retrieving the diguyVariable object. More...
int	variable_set_value_as_float (const char *varname, float value, int create_if_doesnt_exist=1)
	Similar to variable_set_value_as_int(), for sets a floating point value instead. More...
int	set_fvar (const char *varname, float value, int create_if_doesnt_exist=1)
	Short form of variable_set_value_as_float(). More...
float	get_fvar (const char *varname, int create_if_doesnt_exist=1)
	Similar to variable_get_value_as_int(), for returns a floating point value instead. More...
int	variable_set_value_as_string (const char *varname, const char *value, int create_if_doesnt_exist=1)
	Similar to variable_set_value_as_int(), for sets a string value instead. More...
int	set_svar (const char *varname, const char *value, int create_if_doesnt_exist=1)
	Short form of variable_set_value_as_string(). More...
const char *	get_svar (const char *varname, int create_if_doesnt_exist=1)
	Similar to variable_get_value_as_int(), for returns a string value instead. More...
Label Functions
The functions in this section control the text, visibility, and colors of character labels. Currently character labels are only enabled in DI-Guy Scenario. Unless otherwise specified, all functions callable from: C++ Script
diguyViewLabel *	get_name_label ()
	This function returns a pointer to the label object of the character. More...
int	set_label_text (const char *label_text)
	This function sets the text of the character's label. More...
const char *	get_label_text ()
	This function returns the character's label text. More...
int	set_label_is_visible (int is_visible)
	This function sets whether the label of this character is visible. More...
int	get_label_is_visible ()
	This function returns the most recent setting of set_label_is_visible(). More...
int	set_label_text_color (float r, float g, float b, float a)
	This function sets the text color of the character's label. More...
int	set_label_text_color_vec4 (const diguyVec4f &color)
	Alternate version of set_label_text_color(). More...
int	get_label_text_color (float *r, float *g, float *b, float *a)
	This function returns, in the passed variable pointers, the most recent setting of set_label_text_color(). More...
diguyVec4f	get_label_text_color_vec4 ()
	Alternate version of get_label_text_color(). More...
int	set_label_text_shadow_color (float r, float g, float b, float a)
	This function sets the text shadow color of the character's label. More...
int	set_label_text_shadow_color_vec4 (const diguyVec4f &color)
	Alternate version of set_label_text_shadow_color(). More...
int	get_label_text_shadow_color (float *r, float *g, float *b, float *a)
	This function returns, in the passed variable pointers, the most recent setting of set_label_text_shadow_color(). More...
diguyVec4f	get_label_text_shadow_color_vec4 ()
	Alternate version of get_label_text_shadow_color(). More...
int	set_label_text_shadow_is_visible (int is_visible)
	This function sets the whether the text shadow is visible. More...
int	get_label_text_shadow_is_visible ()
	Returns: 1 if text shadow is visible, 0 if not. More...
int	set_label_background_color (float r, float g, float b, float a)
	This function sets the background color of the character's label. More...
int	set_label_background_color_vec4 (const diguyVec4f &color)
	Alternate version of set_label_background_color(). More...
int	get_label_background_color (float *r, float *g, float *b, float *a)
	This function returns, in the passed variable pointers, the most recent setting of set_label_background_color(). More...
diguyVec4f	get_label_background_color_vec4 ()
	Alternate version of get_label_background_color(). More...
void	set_label_link_offset_override (float offset)
	This function sets how high the label of the character will float above the character. More...
float	get_label_link_offset_override ()
	Returns: how high the label of the character will float above the character. More...
int	set_label_shows_character_state (int show_state)
	This function sets whether the label text should show some basic state information about the character instead of its name or the text set by set_label_text(). More...
int	get_label_shows_character_state ()
	Returns: whether character state information is shown instead of the character's name or other label text. More...
Impact Functions
Impact records are how DI-Guy records impact events. These events are typically the result of a character firing its weapon. Unless otherwise specified, all functions callable from: C++ Script
diguyImpact *	get_last_impact_record ()
	Returns: pointer of type diguyImpact; NULL if there has been no recent impact recorded; useful for finding out who or what was hit. More...
int	get_last_impact_number ()
	Returns: the last impact number. More...
int	get_last_impact_been_processed ()
	Returns: the processed flag on the diguyImpact class. More...
void	set_last_impact_been_processed ()
	Sets the processed flag on the diguyImpact object. More...
void	set_max_unprocessed_impacts (int max_unprocessed_impacts)
	Sets the maximum number of unprocessed impacts there can be. More...
int	get_max_unprocessed_impacts ()
	Returns: maximum number of unprocessed impacts. More...
const char *	get_last_impact_link ()
	Returns: the last impact link. More...
int	get_last_impact_link_is (const char *link_name)
	Returns: 1 if the last impact link is the link named. More...
int	get_last_impact_is_from_vehicle ()
	Returns: 1 if the last impact resulted from an impact with a vehicle, 0 if not. More...
int	get_last_impact_speed_is_greater_than (float impact_speed)
	Returns: 1 if the last impact speed is greater than the passed speed, 0 if not. More...
void	set_is_immune_to_impacts (int immune)
	Sets if impacts are ever processed on this character. More...
int	get_is_immune_to_impacts ()
	Returns: 1 if the character is immune to impacts 0 if not. More...
Appearance Effect Functions
Appearance effects are additions to a character's appearance that can be turned on and off. These are commonly effect-type additions, such as flashing lights, smoke, etc. Most appearance effects are implemented in some way for every character; for example, every character will respond to showing the "smoke" effect. Some appearance effects, however, don't make sense for certain characters; for example, emergency vehicles should usually be able to show "flashing_lights", but most humans cannot. Humans that are asked to show the "flashing_lights" effect will not do anything. Unless otherwise specified, all functions callable from: C++ Script
int	begin_appearance_effect (const char *effect, const char *override_link=NULL, float override_scale=DIGUY_DEFAULT_FLOAT, float override_offset_x=DIGUY_DEFAULT_FLOAT, float override_offset_y=DIGUY_DEFAULT_FLOAT, float override_offset_z=DIGUY_DEFAULT_FLOAT, float override_duration=DIGUY_DEFAULT_FLOAT)
	This function starts the specified appearance effect on the character. More...
int	end_appearance_effect (const char *effect, const char *override_link=NULL)
	This function ends the specified appearance effect on the character. More...
int	stop_appearance_effect (const char *effect, const char *override_link=NULL)
	This function stops the specified appearance effect on the character. More...
int	stop_all_appearance_effects ()
	Equivalent to stop_appearance_effect("all");. More...
int	appearance_effect_is_active (const char *effect, const char *override_link=NULL)
	This function checks to see if the specified appearance effect has been started with begin_appearance_effect(). More...
Chain Functions
These functions are for characters with character type "chain_simulation". Unless otherwise specified, all functions callable from: C++ Script
diguyChainSimulation *	get_chain_simulation ()
	This function returns a pointer to a diguyChainSimulation if the character is a chain_simulation type of character. More...
Vehicle Functions
These functions are for some vehicle characters whose speeds and accelerations can be controlled interactively. Unless otherwise specified, all functions callable from: C++ Script
diguyVehicleController *	get_vehicle_controller ()
	This function returns a pointer to a diguyVehicleController if the character has one. More...
int	get_vehicle_body_orientation (float *rz, float *rx, float *ry)
	For most characters playing a travel forward action, the character's facing direction matches the direction of travel. More...
Shader Functions
These functions set and return the shaders that are in use by characters. Note that care should be taken when changing the shader of characters with skinned appearances. A shader capable of properly transforming vertices must be used for such characters. Unless otherwise specified, all functions callable from: C++ Script
int	set_render_mode_shader (const char *shader_name, const char *render_mode=NULL)
	This function sets the name of the shader program that will be used by the character when the scenario is using the specified render mode. More...
void	reset_render_mode_shader_to_default (const char *render_mode=NULL)
	This function resets the shader program for the specified render mode to its default. More...
const char *	get_render_mode_shader (const char *render_mode=NULL)
	This function returns the name of the shader that will be used by the character when the scenario is using the specified render mode. More...
diguyGraphicsShaderProgram *	get_shader_program ()
	This function returns the shader program that is in use by the character. More...
int	set_temporary_current_shader (const char *shader_name)
	This function overrides the current shader with the specified temporary shader. More...
void	reset_current_shader_to_default ()
	This is a convenience function for resetting the current render mode shader to its default. More...
void	trigger_shader_refresh ()
	This is a convenience function for refreshing the shader of a character. More...
diguyGraphicsShaderInstance *	get_shader_instance ()
	This function returns the shader instance that is in use by the character. More...
void	reset_shader_instance_variables_to_initial_values ()
	This function resets current values of the variables of the shader back to their initial reset values. More...
void	reset_shader_instance_variables_to_program_defaults ()
	This function resets the current and initial values of variables of the shader to the built-in DI-Guy configuration defaults. More...
Attack Functions
int	agent_attack_character (const char *character_name)
	This function sets the named character as the attack target of this agent. More...
int	agent_attack_group (const char *group_name)
	This function is similar to agent_attack_character(), but instead will choose attack targets from the characters in the specified group. More...
int	agent_set_attack_zone_enabled (int use_attack_zone)
	See diguyAgentParams::set_attack_zone_enabled(). More...
int	agent_get_attack_zone_enabled ()
	See diguyAgentParams::get_attack_zone_enabled(). More...
int	agent_set_attack_zone (float x, float y, float z, float radius)
	See diguyAgentParams::set_attack_zone(). More...
int	agent_get_attack_zone (float *x, float *y, float *z, float *radius)
	See diguyAgentParams::get_attack_zone(). More...
Flee Functions
int	agent_flee_character (const char *character_name, float distance, int danger_level=50)
	This function adds a flee object to this agent. More...
int	agent_flee_group (const char *group_name, float distance, int danger_level=50)
	This function adds a flee object to this agent. More...
int	agent_flee_crowd (const char *crowd_name, float distance, int danger_level=50)
	This function is similar to agent_flee_group(), but the agent will instead flee the members of the specified crowd. More...
int	agent_flee_location (float x, float y, float z, float distance, int danger_level=50)
	This function adds a flee object to this agent. More...
void	agent_remove_all_flee_objects ()
	This function removes all flee objects. More...
Mingle Functions
Unless otherwise specified, all functions callable from: C++ Script
int	agent_mingle_in_region (const char *region_name="(current)", const char *subregion_name="base")
	This function puts this agent into the mingle behavior, in which it will choose semi-random points in the specified region and subregion to move to. More...
Wander Functions
Unless otherwise specified, all functions callable from: C++ Script
int	agent_wander_region (const char *region_name="(current)", const char *subregion_name="base")
	This function is similar to agent_mingle_in_region(), but agents will pick completely random points and not try to clump together in small groups. More...
Pursue Functions
Unless otherwise specified, all functions callable from: C++ Script
int	agent_pursue_character (const char *character_name)
	This function will cause this agent to pursue the specified character. More...
int	agent_pursue_character_with_offset (const char *character_name, float offset_x, float offset_y)
	This function is similar to agent_pursue_character(), but the point toward the agent will move will be offset from the pursued character by the passed offset. More...
int	agent_pursue_group (const char *group_name)
	This function is similar to agent_pursue_character(), but instead will choose pursue characters from the characters in the specified group. More...
int	agent_call_formation (const char *formation_name, float target_x, float target_y)
	Calls a formation with this character as a leader, oriented towards (target_x, target_y). More...
Travel Functions
Unless otherwise specified, all functions callable from: C++ Script
int	agent_travel_behavior_path (const char *direction=NULL, const char *at_end=NULL, int waypoint_index=-1, float offset_y=0.5f)
	This function has the character travel along its behavior path shape, typically to the end and then back to the beginning. More...
int	agent_travel_path_shape (const char *path_shape_name, const char *direction=NULL, const char *at_end=NULL, int waypoint_index=-1, float offset_y=0.5f)
	Similar to agent_travel_behavior_path(), but specific path can be set rather than using behavior path. More...
int	agent_travel_region_border (const char *region_name=NULL, const char *subregion_name="base")
	The agent will create a travel path around the border of the region specified. More...
int	agent_move_to_point (float x, float y, float z, const char *via_region=NULL, const char *subregion_name="base")
	Agent will attempt to create a navigation path on the via_region and then travel it. More...
int	agent_move_to_point_bg (float x, float y, float z, const char *via_region=NULL, const char *subregion_name="base")
	A multi-threaded version of agent_move_to_point(). More...
int	agent_move_to_point_via_subregions (float x, float y, float z, const char *via_region=NULL, int preferred_subregions_mask=DIGUY_SUBREGION_MASK_NONE, float cost_bias_for_preferred_regions=0.25f, float cost_bias_for_neutral_regions=1.1f, int repulsed_regions_mask=DIGUY_SUBREGION_MASK_NONE, float cost_bias_for_repulsed_regions=10.0f, int cost_rule=0)
	Agent will attempt to create a navigation path on the region via_region and then travel it. More...
int	agent_move_to_point_via_subregions_bg (float x, float y, float z, const char *via_region=NULL, int preferred_subregions_mask=DIGUY_SUBREGION_MASK_NONE, float cost_bias_for_preferred_regions=0.25f, float cost_bias_for_neutral_regions=1.1f, int repulsed_regions_mask=DIGUY_SUBREGION_MASK_NONE, float cost_bias_for_repulsed_regions=10.0f, int cost_rule=0)
	A multi-threaded version of agent_move_to_point_via_subregions(). More...
int	get_path_planning_result ()
	Returns: diguyNavPathSearchResults value after agent_move_to_point_bg() or agent_move_to_point_via_subregions_bg() has been called when the multi-threaded path planner has completed. More...
int	get_is_path_planning ()
	Returns: 1 if character is currently waiting for a result from the multi-threaded path planner, else 0. More...
int	agent_move_to_region (const char *region, const char *subregion_name="base", const char *via_region=NULL)
	Agent will attempt to create a navigation path on the via_region to a point in the target region, and then travel it. More...
int	agent_move_to_region_via_subregions (const char *region_name, const char *subregion_name="base", const char *via_region=NULL, float cost_bias_for_preferred_regions=0.25f, int preferred_subregions_mask=DIGUY_SUBREGION_MASK_NONE, float cost_bias_for_neutral_regions=1.1f, int repulsed_regions_mask=DIGUY_SUBREGION_MASK_NONE, float cost_bias_for_repulsed_regions=10.0f)
	Similar to agent_move_to_point_via_subregions(), but for moving to another region. More...
Path Follow Functions
Unless otherwise specified, all functions callable from: C++ Script
int	agent_path_follow (const char *path_name)
	The agent will begin following the specified path, using the path follow behavior (DIGUY_AGENT_BEHAVIOR_PATH_FOLLOW). More...
int	agent_resume_path_follow ()
	The agent will resume following the path specified by a previous call to agent_path_follow(). More...
diguyCharacterPath *	agent_get_path_follow_path ()
	Returns: the path being followed in path behavior mode. More...
float	agent_get_path_follow_path_t ()
	In path follow behavior the agent moves along the path specified in agent_path_follow(). More...
int	agent_get_path_follow_path_t_paused ()
	Returns: 1 if time along the path is not advancing, else 0. More...
Other Agent Functions
Unless otherwise specified, all functions callable from: C++ Script
diguyCrowd *	agent_get_crowd ()
	Returns: the crowd this agent is a part of, if any; returns NULL if not in a crowd. More...
int	agent_begin_behavior (const char *behavior_name)
	This function allows the end user to directly change an agent's current behavior. More...
int	agent_stop_behavior ()
	This function sets the behavior of the agent to "none". More...
int	agent_set_current_focus_character (const char *character_name)
	This function is a convenience function that changes the focus character of this agent's current crowd params. More...
diguyCharacter *	agent_get_current_focus_character ()
	This function returns the current character this agent is focused on. More...
int	agent_set_current_focus_group (const char *group_name)
	Similar to set_current_focus_character(), but sets the current focus group instead of character. More...
diguyAgentParams *	agent_get_initial_params ()
	This function returns the initial agent parameters of this agent. More...
diguyAgentParams *	agent_get_current_params ()
	This function returns the current agent parameters of this agent. More...
const char *	agent_get_current_params_profile_name ()
	This function gets the name of the agent's current profile. More...
int	agent_set_current_params_from_profile (const char *profile_name, int retain_focus_objects=1, int retain_navigation_values=1, int retain_behavior=0)
	This function sets this agent's current agent parameters from the specified crowd profile. More...
int	agent_set_initial_params_from_profile (const char *profile_name)
	Similar to agent_set_current_params_from_profile(), but initial parameters are changed. More...
void	agent_set_current_params_from_initial_params ()
	This function sets the current parameters from the agent's initial parameters. More...
void	agent_set_current_behavior_region_border_is_solid (int is_solid)
	This function sets whether the borders of the current behavior region of the agent is solid. More...
void	agent_move_on ()
	If the agent is in a behavior that stays in one place before moving to another, such as wander or mingle, this function will request that the agent move on to the next location. More...
int	agent_set_auto_variant_selection (int selection_enabled)
	This function controls if the AI will attempt to automatically change variants depending on the behavior. More...
int	agent_get_auto_variant_selection ()
	Returns if automatic variant selection is enabled, defaults to being on. More...
diguyPathShape *	agent_get_current_traveled_path ()
	Returns current travel path or nav path. More...
void	agent_set_use_speed_zones_on_paths (int enabled)
	Allows agent to determine speed zone based on distance to endpoint of current path. More...
int	agent_get_use_speed_zones_on_paths ()
	Returns the current value set by agent_set_use_speed_zones_on_paths(). More...
User-Defined Feelers
Feelers are effectively ray traces that an agent uses to detect intersections with obstacles in the environment. In DI-Guy Scenario, DI-Guy AI has a built-in feeler function that allows agents to detect collisions with the environment. In a DI-Guy SDK application, a user-defined feeler function must be supplied. User-defined functions can be added to individual characters by calling agent_set_feeler_function(), or to all characters by calling set_default_character_feeler_function(). The following prototype should be used for the feeler functions: int diguyFeelerFunction(diguyCharacter* character, float origin_x, float origin_y, float origin_z, float dir_x, float dir_y, float dir_z, float max_distance_to_test, float* intersection_x, float* intersection_y, float* intersection_z, float* normal_x, float* normal_y, float* normal_z); Parameters origin_x,origin_y,origin_z starting location of the feeler ray dir_x,dir_y,dir_z direction of feeler ray max_distance_to_test max distance feeler will test intersection_x,_y,and _z world location of intersection normal_x,normal_y,normal_z normal of intersection surface Smaller values for max_distance_to_test will result in better performance. The location of the intersection point is returned in the intersection x, y, and z pointers. The normal of the surface intersected is returned in the normal x, y, and z pointers. The normal is needed for agents using feelers to know how to move around and avoid the detected surface. Returns: 1 if intersection occurred, 0 if not
int	agent_set_feeler_function (diguyFeelerFunction *feeler_function)
	This function sets a feeler function that will be used by this character for environment collision detection. More...
diguyFeelerFunction *	agent_get_feeler_function ()
	Returns: current feeler function; see set_feeler_function() More...
Lua Mind Functions
int	create_lua_mind (const char *base_class, const char *init_arg1=NULL, const char *init_arg2=NULL)
	Creates a Lua mind object based off of the contents of base_class. More...
const char *	get_mind_name ()
	Returns the name of the mind, e.g. More...
const char *	get_mind_current_state_name ()
	Agent characters with minds will typically have the mind be in some state, such as "patrolling", "fleeing", "mobbing", etc. More...
void	do_mind_current_state_changed_callback ()
	This function causes callback functions with the callback id CALLBACK_ID_AGENT_MIND_CURRENT_STATE_CHANGED to be called. More...
int	set_sleep_timer (float sleep_length)
	How long until the character's main coroutine thread should be resumed. More...
float	get_sleep_timer ()
	Returns: How long until the character's main coroutine thread resumes, relative to the current time. More...
int	set_heartbeat_dt (float heartbeat_dt)
	The frequency at which the luaCharacter's heartbeat function should run. More...
int	add_secondary_heartbeat (const char *function_name, float heartbeat_dt)
	This function allows the addition of additional heartbeat functions. More...
int	remove_secondary_heartbeat (const char *function_name)
	This function removes an added heartbeat function. More...
int	set_secondary_heartbeat_dt (const char *function_name, float heartbeat_dt)
	The frequency at which a luaCharacter's secondary heartbeat function should run. More...
int	add_wakeup_callback (int callback)
	This function creates a request that whenever the specified callback is triggered, the character is woken up with a message. More...
int	remove_wakeup_callback (int callback)
	This function removes a request to trigger a message when a callback is triggered. More...
int	remove_all_wakeup_callbacks ()
	This function removes all requests to trigger a message when callbacks are triggered. More...
int	has_wakeup_callback (int callback)
	This function check for a requests to trigger a message when a given callback is triggered. More...
int	agent_accept_message (const char *sender, const char *message_type, const char *message, const char *message_params=NULL)
	This function wakes up a character and sends them a message. More...
int	agent_broadcast_message (float radius, const char *message_type, const char *message, const char *message_params=NULL)
	This function wakes up nearby characters and sends them a message. More...
int	agent_broadcast_message_to_group (const char *group_name, float radius, const char *message_type, const char *message, const char *message_params=NULL)
	This function wakes up nearby characters in the group specified and sends them a message. More...
const char *	get_lua_object_name ()
	Returns: name of character's lua mind object; typically this is the character's name with '-' replaced by '_'. More...
void	set_mind_field_as_string (const char *field_name, const char *field_value)
	Sets the specified field of the mind to the string field_value. More...
const char *	get_mind_field_as_string (const char *field_name, int warn_if_no_field=1)
	Queries the luaCharacter object for a specific field, and attempts to convert it into a string. More...
void	set_mind_field_as_float (const char *field_name, float field_value)
	Sets the specified field of the mind to the floating point number field_value. More...
float	get_mind_field_as_float (const char *field_name, int warn_if_no_field=1, int *found_field=NULL)
	Similar to get_mind_field_as_string(), but returns field as a float. More...
void	set_mind_field_as_int (const char *field_name, int field_value)
	Sets the specified field of the mind to the integer number field_value. More...
int	get_mind_field_as_int (const char *field_name, int warn_if_no_field=1, int *found_field=NULL)
	Similar to get_mind_field_as_int(), but returns field as an integer. More...
const char *	evaluate_mind_function (const char *function_name, const char *argument=NULL, int has_return_string=0)
	Attempts to run a luaCharacter member function, and can optionally return the function's result. More...
const char *	get_ai_state_string (int include_stack=1, int include_locals=1)
	This function produces a string with a long list of character information, including: current path, crowd, behavior, lua state, lua call stack, wakeup callbacks and lua object fields. More...
Visibility Tests
int	check_character_visibility (diguyCharacter *character, int los_check_type=0)
	This function tests whether this character can see the passed character. More...
int	check_point_visibility (float x, float y, float z)
	This function tests whether this character can see the x, y, z location specified. More...
AI Callback Functions
Agents use visibility tests to assess if they should path plan or attack. These functions should be filled out by SDK users who want intelligent behavior and decision making from agents. These functions require that end users have a fast static intersection test infrastructure. Unless otherwise specified, all functions callable from: C++ Script
int	set_point_los_function (diguyPointLOSFunction *point_los_function)
	When a character needs to check if it can see a location, DI-Guy calls this function with a pointer to the diguyCharacter in question, and the coordinates of the point that is being looked at. More...
diguyPointLOSFunction *	get_point_los_function ()
	Returns: current point line-of-sight function; see set_point_los_function() More...
int	set_character_los_function (diguyCharacterLOSFunction *character_los_function)
	When a character needs to check if it can see another character, DI-Guy calls this function with a pointer to the diguyCharacter in question. More...
diguyCharacterLOSFunction *	get_character_los_function ()
	Returns: current character line-of-sight function; see set_character_los_function() More...
Real Time IK Functions
The functions is this section control a real-time IK system that can be used to place the character's arms and legs in fixed locations in the world. By default characters that are near the camera will have their legs and feet adjusted to match the ground underneath them. Character's holding weapons can also use the system to keep the secondary hand locked in place on the weapon, this requires that the animation be properly tagged in the action table. Unless otherwise specified, all functions callable from: C++ Script
int	get_num_ik_chains ()
	Normally Returns 4. More...
const char *	get_ik_chain_name_at_index (int index)
	Should return one of the following: right_leg, left_leg, left_arm, right_arm. More...
int	set_ik_target_world (int ik_chain_target, float x, float y, float z, float ramp_time=.25f)
int	set_ik_target_local (int ik_chain_target, float x, float y, float z, float ramp_time=.25f)
int	disable_ik_target (int ik_chain_target, float ramp_time=.25f)
void	set_distance_to_primary_camera (float camera_dist)
float	get_distance_to_primary_camera ()
	Defaults to -1. see set_distance_to_primary_camera() for more info. More...
Simulation Functions
The functions is this section control physics simulator settings for characters. For many of the functions a DI-Guy physics module must be active. Unless otherwise specified, all functions callable from: C++ Script
int	set_initial_character_simulator (diguyCharacterSimulator character_simulator)
	This function sets the initial character simulator this character will use. More...
diguyCharacterSimulator	get_initial_character_simulator ()
	Returns: initial character simulator. More...
int	set_current_character_simulator (diguyCharacterSimulator character_simulator)
	This function sets the current character simulator this character will use. More...
diguyCharacterSimulator	get_current_character_simulator ()
	Returns: current character simulator. More...
int	set_initial_physics_simulation_mode (diguyPhysicsSimulationMode physics_simulation_mode)
	This function sets the initial physics simulation mode this character will use. More...
diguyPhysicsSimulationMode	get_initial_physics_simulation_mode ()
	Returns: initial physics simulation mode. More...
int	set_current_physics_simulation_mode (diguyPhysicsSimulationMode physics_simulation_mode)
	This function sets the current physics simulation mode this character will use. More...
diguyPhysicsSimulationMode	get_current_physics_simulation_mode ()
	Returns: initial physics simulation mode. More...
int	set_physics_collision_group (diguyPhysicsCollisionGroup collision_group)
	This function sets the physics collision group this character will be in when being simulated. More...
diguyPhysicsCollisionGroup	get_physics_collision_group ()
	Returns: physics collision group. More...
void	set_stop_physics_sim_at_t (float t)
	This function sets a time at which active simulation of a physics controlled character will stop. More...
void	set_stop_physics_sim_in_t_seconds (float relative_t)
	Similar to set_stop_physics_sim_at_t(), but the passed time will be relative to the current simulation time as returned by diguyScenario::get_t(). More...
float	get_stop_physics_sim_at_t ()
	Returns: time at which physics simulation will freeze. More...
void	apply_impulse_to_physics_sim (const char *link, float impulse_magnitude_x, float impulse_magnitude_y, float impulse_magnitude_z, float link_offset_x=0.0f, float link_offset_y=0.0f, float link_offset_z=0.0f, int set_simulation_drives_character=1)
	This function applied an impulse force to the character. More...
void	apply_impulse_to_physics_sim_from_world_position (const char *link, float impulse_magnitude_x, float impulse_magnitude_y, float impulse_magnitude_z, float impulse_generator_position_x, float impulse_generator_position_y, float impulse_generator_position_z, float max_distance=20.0f, float impulse_rolloff=0.0f, float link_offset_x=0.0f, float link_offset_y=0.0f, float link_offset_z=0.0f, int set_simulation_drives_character=1)
	Similar to apply_impulse_to_physics_sim(), but impulse can be calculated relative to a world position. More...
Experimental Functions
The following functions are experimental and may change or disappear with no warning.
int	set_animation_events_enabled (int enable)
	Documentation Pending. More...
int	get_animation_events_enabled ()
int	get_has_bump_maps ()
	Returns 1 if the current appearance has bump maps. More...
int	get_action_num_channels (const char *action_name)
	This function returns how many channels the specified action has. More...
int	set_action_channel_weight (const char *action_name, char channel, float weight)
	This function sets the weight one channel of a multi-channel action. More...
float	get_action_channel_weight (const char *action_name, char channel)
	This function returns the weight of one channel of a multi-channel action. More...
float	get_time_to_reach_desired_action ()
	This function returns the number of seconds before the transition to the desired action begins. More...
const char *	get_type_map_field (diguyCharacterTypeMapField field)
	Maps a character type map field to its value. More...
const char *	get_type_map_field_using_string (const char *field)
	Maps a character type map field to its value, using a string version (e.g. More...
int	merge_object (const char *object)
	This function performs a "micro merge", allowing a diguyCharacter to have objects added to it by parsing a .dss file fragment in the form of a string. More...
int	is_active_character_in_group_visible (const char *group_name, float max_distance_to_check=100000.0f)
	Returns 1 if any active character in the named group is visible, otherwise 0. More...
int	get_local_space_bounding_box (float *x1, float *y1, float *z1, float *x2, float *y2, float *z2)
	Gets local space bounding box, this function is currently expensive and should be used with care. More...
void	set_mind_always_updates (int force_update)
	This causes a character's mind to get an update call even if time isn't passing in the scenario. More...
int	get_mind_always_updates ()
	Returns value set by set_mind_always_updates() More...
float	get_angle_to_path (const char *path_name, const char *action_bead_name=NULL)
	Returns angle in degrees from character's "forward facing" vector to the specified action bead, on the specified path. More...
void	set_scene_graph_mask (unsigned int mask)
unsigned int	get_scene_graph_mask ()
int	set_use_texture_variations (int value)
	Turns on texture modulation system that tries to make all characters look unique. More...
int	get_use_texture_variations ()
	Returns: If texture variations have been enabled for this character. More...
diguyMotionEngineSnapshot	get_motion_engine_snapshot ()
	Returns a structure that attempts to encode all the major variables that the motion engine is currently using to manage the primary action, and related transition values. More...
int	apply_motion_engine_snapshot (const diguyMotionEngineSnapshot &action_info)
	Applies the snapshot created by get_motion_engine_snapshot() More...
int	set_local_to_world_orientation_matrix (float rz, float rx, float ry)
	documentation pending More...
int	set_local_to_world_orientation_matrix (float a0, float a1, float a2, float b0, float b1, float b2, float c0, float c1, float c2, int transpose=0)
int	set_final_position_double (double x, double y, double z)
int	set_final_matrix (float a0, float a1, float a2, float a3, float b0, float b1, float b2, float b3, float c0, float c1, float c2, float c3, float d0, float d1, float d2, float d3)
Deprecated Functions
The following functions are deprecated. As these functions may disappear in a future version of DI-Guy, it is recommended that you remove calls to these functions from your application.
int	aim_converge (int max_iterations=30)
void	set_aim_algorithm (int aim_algorithm)
	Currently, 8 is the only valid input for this function, makes DI-Guy use a version 8.0 style aim. More...
int	get_aim_algorithm ()
	Returns: current aim algorithm defaults to 8. More...
int	speak (const char *string)
	Deprecated as of 9.1.4. More...
int	set_viseme (const char *viseme_name, float weight)
	Deprecated as of 12.0.0. More...
float	get_viseme (const char *viseme_name)
	Deprecated as of 12.0.0. More...
int	set_orientation_eye_left (float azimuth, float elevation)
	Deprecated as of 12.0.0. More...
int	set_orientation_eye_right (float azimuth, float elevation)
	Deprecated as of 12.0.0. More...
float	get_azimuth_eye_left ()
	Deprecated as of 12.0.0. More...
float	get_elevation_eye_left ()
	Deprecated as of 12.0.0. More...
float	get_azimuth_eye_right ()
	Returns: the current azimuth of the right eye; see set_orientation_eyes() More...
float	get_elevation_eye_right ()
	Returns: the current elevation of the right eye; see set_orientation_eyes() More...

Static Public Member Functions
Static Rendering Control Functions
static int	set_texture_load_behavior (diguyGraphicsTextureLoadingBehavior mode)
	Sets texture load behavior to DIGUY_LOAD_INSTANTLY, DIGUY_LOAD_PRIORITY_ASYNC, or DIGUY_LOAD_ASYNC. More...
static diguyGraphicsTextureLoadingBehavior	get_texture_load_behavior ()
	Returns current behavior, as set in set_texture_load_behavior() More...
static int	set_max_shader_quality_level (int quality_level)
	Sets maximum quality of shader to use (actual quality varies by distance from camera). More...
static int	get_max_shader_quality_level ()
	Returns: max shader quality level, as set by set_max_shader_quality_level() More...

Private Functions
The functions and variables past this point are for internal use only. No external access to them is expected or necessary.
bdiScenarioCharacter *	m_scripted_object
	A pointer to internal data. More...
class	bdiPublishedCharacter
class	bdiScenarioCharacter
class	diguySensorRegion
class	diguyScenario
bdiScenarioCharacter *	get_scripted_object ()
	diguyCharacter (bdiScenarioCharacter *character)
	A private constructor. More...
	~diguyCharacter ()
	A private destructor. More...

Detailed Description

The class that represents a DI-Guy Entity in the world.

This class refers to a single DI-Guy entity, be it human, animal, vehicle, or prop. The diguyCharacters are generally the key points of interest in a scenario. A diguyScenario contains an array of all its diguyCharacters. A diguyCharacter can be referenced by index or by name from diguyScenario. A diguyCharacter has a rich interface for querying and specifying its behavior and appearance.

Member Enumeration Documentation

anonymous enum

This is an enumeration of the different callbacks that can be registered with add_callback() and add_callback_script().

Callbacks return a value of type diguyCallbackReturn, which will be DIGUY_CALLBACK_STOP or DIGUY_CALLBACK_CONTINUE. If the callback returns DIGUY_CALLBACK_STOP, in some cases the default handler of the function will not be called; the callback is asserting that it has done everything necessary for the function call. If the callback returns DIGUY_CALLBACK_CONTINUE, the default handler for the function will be called after the callback.

Usable From:

• C++
• Script

Callback Enums:

CALLBACK_ID_CREATE

 This callback will be called when a new character is created,
 *after* the character is fully initialized.

 Note that this callback can only be added by calling
 diguyScenario::add_default_character_callback(); adding it with
 diguyCharacter::add_callback() will have no effect, as by that
 time the character has already been created.

CALLBACK_ID_DESTROY

 This callback will be called when a character is
 destroyed.

CALLBACK_ID_PRE_CREATE

 Like CALLBACK_ID_CREATE, this callback will be called when a
 new character is created; however, it is called ** <b>efore* the </b>
 character is fully initialized.

NOTE: Care must be taken when using this callback! As mentioned above, the character is not fully initialized, meaning that most member functions of the diguyCharacter object should not be called. Those member functions that are safe to call will be mentioned in the documentation for the function; e.g., set_graphics_api_node_ptr().

Note that this callback can only be added by calling diguyScenario::add_default_character_callback(); adding it with diguyCharacter::add_callback() will have no effect, as by that time the character has already been created.

CALLBACK_ID_CURRENT_APPEARANCE_CHANGED

 This callback will be called when a character's current
 appearance is changed.

CALLBACK_ID_CURRENT_HEAD_APPEARANCE_CHANGED

 This callback will be called when a character's current head
 appearance is changed.

CALLBACK_ID_PRE_UPDATE

 This callback will be called before the character is updated as
 a result of the diguyScenario::update() function.

CALLBACK_ID_POST_UPDATE

 This callback will be called after the character is updated as a
 result of the diguyScenario::update() function.

CALLBACK_ID_DONE_SPEAKING

 This callback will be called when the character has finished
 speaking the contents of a speak() function call.

CALLBACK_ID_GAZE_STATUS

 This callback will be called after the character's gaze has
 experienced a status change.

CALLBACK_ID_LPOINT_STATUS

 This callback will be called after the character's lpoint (left
 arm pointing) has experienced a status change.

CALLBACK_ID_SHOW

 This callback will be called when the character is being shown
 for any reason.

CALLBACK_ID_HIDE

 This callback will be called when the character is being hidden
 for any reason.

CALLBACK_ID_PRE_DIE

 This callback will be called when the character has been told to
 die, before a die action has been selected and initiated.

 If the returned diguyCallbackReturn value is
 DIGUY_CALLBACK_STOP, the character will not die.

CALLBACK_ID_POST_DIE

 This callback will be called when the character has been told to
 die, after a die action has been selected and initiated.

CALLBACK_ID_PRE_FIRE_WEAPON

 This callback will be called when the character has been told to
 fire its weapon, before a final decision has been made to fire.

 If the returned diguyCallbackReturn value is
 DIGUY_CALLBACK_STOP, the character will not fire.

CALLBACK_ID_IMPACT

 This callback will be called when the character has been hit.
 diguyCharacter::get_last_impact_record() contains a pointer to
 the impact information. If a character has this callback the
 standard behavior (killing the character) is skipped and the
 system assumes the end user has handled the impact.

 Similar behavior results if
 diguyCrowd::CALLBACK_ID_CROWD_MEMBER_IMPACT is registered.

CALLBACK_ID_POST_FIRE_WEAPON

 This callback will be called when the character has been told to
 fire its weapon, after a final decision has been made to fire.

CALLBACK_ID_CURRENT_ACTION_CHANGED

 This callback will be called whenever the character's current
 action changes, typically after a call to set_desired_action()
 or force_action().

CALLBACK_ID_DESIRED_ACTION_CHANGED

 This callback will be called whenever the character's desired
 action changes, typically after a call to set_desired_action().

CALLBACK_ID_DESIRED_ACTION_REACHED

 This callback will be called when the character reaches its
 desired action as set by a call to set_desired_action().

CALLBACK_ID_MANUALLY_INVOKED

 This callback id will be supplied to event handlers invoked by a
 call to manually_invoke_event_handler().

CALLBACK_ID_USER_SELECTED

 This callback will be called when the character is selected in DI-Guy Scenario.

CALLBACK_ID_USER_UNSELECTED

 This callback will be called on a currently selected character when a different
 character is selected in DI-Guy Scenario.

CALLBACK_ID_IGUY_INTERACT

 This callback will be called when the character has been clicked
 on while DI-Guy Scenario is in I-Guy Input Mode.  Note that this
 is called on the character clicked, not the I-Guy character.

CALLBACK_ID_IGUY_INTERACT_WITH_SUBJECT

 This callback will be called when the character, as the I-Guy
 character, has clicked another character in I-Guy Input Mode.
 Note that this is called for the I-Guy character, not the
 clicked character.

CALLBACK_ID_GUIDE_POSITION_ACQUIRED

 This callback will be called when the character has reached its
 desired position as set by set_desired_position(). The
 diguyCharacterGuide is responsible for moving the character towards
 this position.

CALLBACK_ID_GUIDE_POSITION_UNACQUIRED

 This callback will be called if the character moves too far away
 from its desired position after it has been previously reached.

CALLBACK_ID_GUIDE_ORIENTATION_ACQUIRED

 This callback will be called when the character has reached its
 desired orientation as set by set_desired_orientation(). The
 diguyCharacterGuide is responsible for moving the character towards
 this orientation.

CALLBACK_ID_GUIDE_ORIENTATION_UNACQUIRED

 This callback will be called if the character turns too far away
 from its desired orientation after it has been previously
 reached.

CALLBACK_ID_GUIDE_ALTITUDE_ACQUIRED

 This callback will be called when the character has reached its
 desired altitude as set by set_desired_orientation() or other functions.
 The callback is most meaningful for vehicles that need to achieve
 some sort "cruising altitude" while moving to a destination.

CALLBACK_ID_GUIDE_ALTITUDE_UNACQUIRED

 This callback will be called if the character turns too far away
 from its desired orientation after it has been previously
 reached.

CALLBACK_ID_GUIDE_TARGET_LOST

 This callback will be called when the character guide has determined
 that the character can't reach its desired position/orientation. An
 example would be a missile that has flown past its target

CALLBACK_ID_CURRENT_TOUT_REACHED

 This callback will be called when scenario time reaches this
 character's tout time as set by set_current_tout().

CALLBACK_ID_POST_CREATE_GEOMETRY

 This callback will be called just after the character's geometry
 has been created.

CALLBACK_ID_PRE_DESTROY_GEOMETRY

 This callback will be called just before the character's
 geometry is broken down and destroyed.

CALLBACK_ID_END_OF_PATH_REACHED

 This callback will be called when a character reaches the end of
 their current path. Note the path must finish, forcing to other
 paths will not trigger this callback.

DI-Guy Scenario UI Callback enums:

CALLBACK_ID_UI_PRE_TRANSLATION

 This callback will be called when the user interface starts
 moving a character.

CALLBACK_ID_UI_POST_TRANSLATION

 This callback will be called when the user interface finishes
 moving a character.

CALLBACK_ID_UI_MOUSE_DOWN

 This callback will be called when the user interface gets a
 mouse click in the DIGUY_SCENARIO_INPUT_MODE_POINT_SELECT input
 mode.

CALLBACK_ID_UI_MOUSE_UP

 This callback will be called when the user interface gets a
 mouse release in the DIGUY_SCENARIO_INPUT_MODE_POINT_SELECT
 input mode.

DI-Guy AI Agent Callback enums:

CALLBACK_ID_AGENT_NEW_BEHAVIOR

 This callback will be called when an agent changes its current
 behavior.

CALLBACK_ID_AGENT_NEW_FOCUS_CHARACTER

 This callback will be called when an agent changes its current
 focus character; this happens most frequently when it is focused
 on a group.

CALLBACK_ID_AGENT_ATTACK_OUT_OF_TARGETS

 This callback will be called when an agent in attack behavior
 evaluates the group it's focused on and cannot find an
 appropriate target.  This can happen if all group members are
 dead.

CALLBACK_ID_AGENT_ATTACK_NO_VISIBLE_TARGETS

 This callback will be called when an agent in attack behavior
 can't see any potential members of the group it's focused on.

CALLBACK_ID_AGENT_PURSUE_TARGET_REACHED

 This callback will be called when an agent in pursue behavior
 has come within the pursuit distance of its pursuit target.

CALLBACK_ID_AGENT_PURSUE_TARGET_LOST

 This callback will be called when an agent in pursue behavior
 is no longer within the pursuit distance of its pursuit target.

CALLBACK_ID_AGENT_MINGLE_TARGET_REACHED

 This callback will be called when an agent in mingle behavior
 has reached its mingle target.

CALLBACK_ID_AGENT_MINGLE_TARGET_LOST

 This callback will be called when an agent in mingle behavior
 is no longer is range of its mingle target.

CALLBACK_ID_AGENT_WANDER_TARGET_REACHED

 This callback will be called when an agent in wander behavior
 has reached its wander target.

CALLBACK_ID_AGENT_WANDER_TARGET_LOST

 This callback will be called when an agent in wander behavior
 is no longer is range of its wander target.

CALLBACK_ID_AGENT_FLEE_AREA_LEFT

 This callback will be called when an agent in flee behavior has
 successfully moved out range of all fled characters or
 locations.  This will only be called when the agent is
 transitioning from inside the flee area to outside of it.

CALLBACK_ID_AGENT_FLEE_AREA_ENTERED

 This callback will be called when an agent in flee behavior has
 moved inside of the range of any fled characters or locations.
 This will only be called when the agent is transitioning from
 outside the flee area to inside of it.

CALLBACK_ID_AGENT_TRAVEL_WAYPOINT_REACHED

 This callback will be called when an agent in travel behavior
 has reached in intermediate waypoint and is about to move
 on to the next.

CALLBACK_ID_AGENT_TRAVEL_FORWARD_DEST_REACHED

 This callback will be called when an agent in travel behavior
 has reached the end of its travel path when moving forward
 along the path.

CALLBACK_ID_AGENT_TRAVEL_BACKWARD_DEST_REACHED

 This callback will be called when an agent in travel behavior
 has reached the beginning of its travel path when moving
 backward along the path.

CALLBACK_ID_AGENT_TRAVEL_NEAR_FORWARD_DEST

 This callback will be called when an agent gets within a specified
 distance of the end of the travel path

CALLBACK_ID_AGENT_CROWD_MEMBER_KILLED

 This callback will be called when fellow member of the crowd is
 killed.

- This is the character version of
    diguyCrowd::CALLBACK_ID_CROWD_MEMBER_KILLED
- The crowd's callback character is the crowd member that was
    killed.
- The crowd's callback impact contains the impact information.

CALLBACK_ID_AGENT_CROWD_MEMBER_IMPACT

 This callback will be called when a fellow member of the crowd
 is hit by a detonation.  This callback does not replace
 diguyCharacter::CALLBACK_ID_IMPACT, which still needs to be
 handled to implement damage models.

- The crowd's callback character is the crowd member that was
    hit.
- The crowd's callback impact contains the impact information.

CALLBACK_ID_AGENT_NEARBY_SCENE_OBJECT_IMPACT

 This callback will be called when a detonation occurs within the
 awareness radius (as set by set_awareness_radius()) of the
 crowd's current bounds.

- This is the character version of
    diguyCrowd::CALLBACK_ID_NEARBY_SCENE_OBJECT_IMPACT
- The crowd's callback character is the character that caused
    the detonation.
- The crowd's callback impact contains the impact information.

CALLBACK_ID_AGENT_NEARBY_WEAPON_FIRED

 This callback will be called when a weapon is fired within the
 awareness radius (as set by set_awareness_radius()) of the
 crowd's current bounds.

- The crowd's callback character is the character that fired the
    weapon.

CALLBACK_ID_AGENT_VEHICLE_COLLISION

 This callback will be called on a vehicle agent when it hits a
 member of a companion crowd.

CALLBACK_ID_AGENT_VEHICLE_NEAR_COLLISION

 This callback will be called on a vehicle agent when it
 approaches another vehicle.

CALLBACK_ID_AGENT_NON_ZERO_REPULSION

 This callback will be called when an agent character's repulsion
 forces become non-zero.

CALLBACK_ID_AGENT_ZERO_REPULSION

 This callback will be called when an agent character's repulsion
 forces become zero.

CALLBACK_ID_AGENT_PATH_PLAN_COMPLETED

 This callback will be called when a character who's requested a
 path plan via the background path planner
 (agent_move_to_point_bg) gets a path result. Call
 diguyCharacter::get_path_planning_result() to get the status of
 the result.

CALLBACK_ID_AGENT_MIND_CURRENT_STATE_CHANGED

 This callback will be called when the current state the agent's
 mind, if it has one, has changed.  Call
 diguyCharacter::get_mind_current_state_name() to get the new
 state name.

Enumerator
CALLBACK_ID_CREATE
CALLBACK_ID_DESTROY
CALLBACK_ID_PRE_CREATE
CALLBACK_ID_CURRENT_APPEARANCE_CHANGED
CALLBACK_ID_CURRENT_HEAD_APPEARANCE_CHANGED
CALLBACK_ID_CURRENT_HAND_ITEM_APPEARANCE_CHANGED
CALLBACK_ID_SHAPE_VISIBILITY_CHANGED
CALLBACK_ID_PRE_UPDATE
CALLBACK_ID_POST_UPDATE
CALLBACK_ID_DONE_SPEAKING
CALLBACK_ID_GAZE_STATUS
CALLBACK_ID_LPOINT_STATUS
CALLBACK_ID_SHOW
CALLBACK_ID_HIDE
CALLBACK_ID_PRE_DIE
CALLBACK_ID_POST_DIE
CALLBACK_ID_PRE_FIRE_WEAPON
CALLBACK_ID_POST_FIRE_WEAPON
CALLBACK_ID_IMPACT
CALLBACK_ID_FIRE_WEAPON_SUCCESS
CALLBACK_ID_CURRENT_ACTION_CHANGED
CALLBACK_ID_DESIRED_ACTION_CHANGED
CALLBACK_ID_DESIRED_ACTION_REACHED
CALLBACK_ID_MANUALLY_INVOKED
CALLBACK_ID_USER_SELECTED
CALLBACK_ID_USER_UNSELECTED
CALLBACK_ID_IGUY_INTERACT
CALLBACK_ID_IGUY_INTERACT_WITH_SUBJECT
CALLBACK_ID_GUIDE_POSITION_ACQUIRED
CALLBACK_ID_GUIDE_POSITION_UNACQUIRED
CALLBACK_ID_GUIDE_ORIENTATION_ACQUIRED
CALLBACK_ID_GUIDE_ORIENTATION_UNACQUIRED
CALLBACK_ID_GUIDE_ALTITUDE_ACQUIRED
CALLBACK_ID_GUIDE_ALTITUDE_UNACQUIRED
CALLBACK_ID_GUIDE_TARGET_LOST
CALLBACK_ID_CURRENT_TOUT_REACHED
CALLBACK_ID_POST_CREATE_GEOMETRY
CALLBACK_ID_PRE_DESTROY_GEOMETRY
CALLBACK_ID_END_OF_PATH_REACHED
CALLBACK_ID_CHARACTER_CLICKED
CALLBACK_ID_UI_PRE_TRANSLATION
CALLBACK_ID_UI_POST_TRANSLATION
CALLBACK_ID_UI_MOUSE_DOWN
CALLBACK_ID_UI_MOUSE_UP
CALLBACK_ID_UI_RIGHT_MOUSE_DOWN
CALLBACK_ID_UI_RIGHT_MOUSE_UP
CALLBACK_ID_UI_LEFT_CLICK
CALLBACK_ID_UI_RIGHT_CLICK
CALLBACK_ID_UI_DOUBLE_CLICK
CALLBACK_ID_UI_MIDDLE_CLICK
CALLBACK_ID_UI_SCROLL_UP
CALLBACK_ID_UI_SCROLL_DOWN
CALLBACK_ID_AGENT_NEW_BEHAVIOR
CALLBACK_ID_AGENT_NEW_PATH_SHAPE
CALLBACK_ID_AGENT_NEW_FOCUS_CHARACTER
CALLBACK_ID_AGENT_ATTACK_OUT_OF_TARGETS
CALLBACK_ID_AGENT_ATTACK_NO_VISIBLE_TARGETS
CALLBACK_ID_AGENT_PURSUE_TARGET_REACHED
CALLBACK_ID_AGENT_PURSUE_TARGET_LOST
CALLBACK_ID_AGENT_MINGLE_TARGET_REACHED
CALLBACK_ID_AGENT_MINGLE_TARGET_LOST
CALLBACK_ID_AGENT_WANDER_TARGET_REACHED
CALLBACK_ID_AGENT_WANDER_TARGET_LOST
CALLBACK_ID_AGENT_FLEE_AREA_LEFT
CALLBACK_ID_AGENT_FLEE_AREA_ENTERED
CALLBACK_ID_AGENT_TRAVEL_WAYPOINT_REACHED
CALLBACK_ID_AGENT_TRAVEL_FORWARD_DEST_REACHED
CALLBACK_ID_AGENT_TRAVEL_BACKWARD_DEST_REACHED
CALLBACK_ID_AGENT_TRAVEL_NEAR_FORWARD_DEST
CALLBACK_ID_AGENT_CROWD_MEMBER_KILLED
CALLBACK_ID_AGENT_CROWD_MEMBER_IMPACT
CALLBACK_ID_AGENT_NEARBY_SCENE_OBJECT_IMPACT
CALLBACK_ID_AGENT_NEARBY_WEAPON_FIRED
CALLBACK_ID_AGENT_VEHICLE_COLLISION
CALLBACK_ID_AGENT_VEHICLE_NEAR_COLLISION
CALLBACK_ID_AGENT_PATH_PLAN_COMPLETED
CALLBACK_ID_AGENT_MIND_CURRENT_STATE_CHANGED
CALLBACK_ID_AGENT_NON_ZERO_REPULSION
CALLBACK_ID_AGENT_ZERO_REPULSION

Constructor & Destructor Documentation

diguyCharacter::diguyCharacter ( bdiScenarioCharacter *  character )

private

A private constructor.

diguyCharacter::~diguyCharacter ( )

private

A private destructor.

Member Function Documentation

const char* diguyCharacter::get_name

(

)

Returns the name of the object.

This pointer will never be NULL.

int diguyCharacter::set_name

(

const char *

name

)

This function sets the name of this object.

Returns:

0 on success, -1 on failure

const char* diguyCharacter::get_type_name

(

)

Returns the type name of the object, should be 'character'.

This pointer will never be NULL.

long diguyCharacter::get_uid

(

)

All characters are assigned a unique identifier, or uid.

This function returns this character's uid.

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

int diguyCharacter::get_index

(

)

Returns the index of the object.

This index may change if characters are created or destroyed, so it should not be considered a unique identifier for the character. See get_uid().

int diguyCharacter::update	(	float	t,
		int	full_update = 1
	)

This function updates the character.

The character's position and pose will be set to be what it will be (or was) at the specified t.

If the scenario has control of t (return value of get_t_controlled_by_scenario_t() is 0), then this function's effects will be overridden the next time diguyScenario::update() is called with a new t.

**

Note

diguyScenario::update() must be called as or more frequently than diguyCharacter::update() for proper DI-Guy operation. diguyCharacter::update() is intended for load management use, where the user intends to update far away or out-of-frustum characters less frequently than the overall scenario. This is done in con- junction with set_t_controlled_by_scenario_t(0) for the character. diguyCharacter::update() is not intended as a replacement for diguyScenario::update().

Returns:

0 on success, -1 on failure

Parameters

t	new time for the character
full_update	set to 1 to cause full update of character

void diguyCharacter::set_character_type

(

const char *

type

)

This function sets the current type of this character.

Parameters

type	name of the new desired type

See Also:

get_character_type_string()

const char* diguyCharacter::get_character_type_string

(

)

Returns the type of the character (never NULL).

Character types specify the types of motions the character will be able to perform. Some characters can move like soldiers, others can move like civilians, still others can move like specific animals.

The character type is explicitly specified in the call to diguyScenario::create_character().

Examples of character types are:

• soldier
• male_pedestrian
• horse
• prop

const char* diguyCharacter::get_character_class

(

)

Returns the class of the character (never NULL).

Character classes are a higher level description than character types, and allow for more generalized logic. For example, instead of having something happen when one of a large set of specific character types enters a region, something can happen when any human enters the region.

Character classes are not specified directly, but are instead derived from the character type. (In DI-Guy, all soldiers are humans, for example.)

Examples of character classes are:

• human
• vehicle
• object
• animal

diguyCharacterClass diguyCharacter::get_character_class_type

(

)

returns enum describing the character class

diguyScenario* diguyCharacter::get_scenario

(

)

Returns the scenario that this character is a part of.

int diguyCharacter::set_enabled

(

int

enabled

)

This is the top-level on/off switch for the character.

A character that is not enabled has very little processing overhead: it is neither updated during an update() call, nor is it drawn during a draw() call. A disabled character will remain disabled until set_enabled(1) is called on it; nothing else implicitly re-enables the character.

There are several other diguyCharacter functions that have somewhat similar effects that may be more appropriate at times:

• set_current_tin() and set_current_tout(): These functions show and animate the character starting at time tin ("T In"), and ending at time tout ("T Out")

• set_invisible_flag(): This function disables drawing of the character, but the character still updates and changes position.

  Refer to the documentation of these functions for more information.

Returns:

always return 0

int diguyCharacter::get_enabled

(

)

Returns whether the character is enabled, as set by the set_enabled() call.

New characters are enabled by default.

Returns:

1 if the character is enabled, 0 if not

int diguyCharacter::set_drawn_by_scenario_flag

(

int

flag

)

Sets whether this character is drawn automatically by the scenario.

Note depending on the rendering environment if this flag is set to 0, it is up to the user to call the character draw_pass1() and draw_pass2() calls at the appropriate time.

Parameters

flag	pass 1 for character drawing to automatically be handled by scenario (this is the default); 0 for it not to be

Returns:

0 on success, -1 on failure

int diguyCharacter::get_drawn_by_scenario_flag

(

)

Returns whether character drawing is done automatically by the scenario.

Returns:

1 if character drawing is done by the scenario; 0 if not

See Also:

set_drawn_by_scenario_flag()

void diguyCharacter::set_invisible_flag

(

int

invisible_flag

)

This function makes the character invisible; i.e., draw() calls for the character will have no effect.

Note that the character will still update its position and pose during update() calls. To more thoroughly disable a character, consider the functions set_enabled() and set_current_tout().

Parameters

invisible_flag

pass 1 to make character invisible, 0 to make it visible

Available as Decision Bead/Event

int diguyCharacter::get_invisible_flag

(

)

Returns: the character's invisible flag, as set by set_invisible_flag()

int diguyCharacter::get_is_active

(

)

Returns whether the character is active.

A character is active if:

• it is enabled as per the set_enabled() call
• it is within its tin/tout interval as set by the set_current_tin() and set_current_tout() calls
• it is not "network paused" (get_is_network_paused() returns 0)

Returns:

1 if the character is active, 0 if not

Available as Decision Bead

int diguyCharacter::get_is_drawn

(

)

Returns whether the character will be drawn during scenario and character draw() calls.

A character will be drawn if:

• it is enabled as per the set_enabled() call
• it is within its tin/tout interval as set by the set_current_tin() and set_current_tout() calls
• its invisible flag is 0, as set by the set_invisible_flag() call

There is no corresponding set_is_drawn() function; use set_invisible_flag() to explicitly make a character not be drawn.

Returns:

1 if the character will be drawn, 0 if not

int diguyCharacter::get_was_drawn_last_frame

(

)

Was this character drawn last frame, will only be accurate if diguyScenario::pre_draw_cull_state_reset() is called before all render passes are begun.

Immediate mode renderers should automatically set to true when the character is drawn. In retained mode renders, calling set_is_culled() should change this.

int diguyCharacter::set_was_drawn_last_frame

(

int

drawn

)

This function is just included for completeness, it shouldn't be needed.

int diguyCharacter::get_is_culled

(

)

Was the character culled and never drawn.

int diguyCharacter::set_is_culled

(

int

culled

)

If diguyScenario::pre_draw_cull_state_reset() and diguyScenario::post_draw_cull_state_save() are used in a retained mode renderer it's very important to call this function with set_is_culled(0).

This will make sure that the character is part of the multi-threaded update loop the next frame, it will also trigger any updates to graphics that that didn't happen because we thought that the character was offscreen.

int diguyCharacter::get_is_temporary

(

)

Returns: 1 if the character is temporary (created by diguyScenario::create_temporary_character() call; 0 if not.

int diguyCharacter::get_is_recycled

(

)

This function returns 1 if the character has been recycled from the character recycle bin, 0 if not.

See diguyScenario::send_character_to_recycle_bin() and diguyScenario::retrieve_character_from_recycle_bin().

int diguyCharacter::set_t_controlled_by_scenario_t

(

int

t_controlled_by_scenario_t

)

This function sets how the character's t (time) is controlled.

If 1, the character's t will be set by the scenario on each call to diguyScenario::update(). If 0, the character should be updated by calls to update().

Parameters

t_controlled_by_scenario_t

1 for controlled by scenario, 0 for manual update

Returns:

0 on success, -1 on failure

int diguyCharacter::get_t_controlled_by_scenario_t

(

)

Returns: whether character's t is controlled by the scenario; see set_t_controlled_by_scenario_t()

int diguyCharacter::set_initial_tin	(	float	tin,
		int	override_time_warning = 0
	)

This function sets the initial tin ("T In") time of the character.

See set_current_tin() for a discussion of how tin and tout times affect the character.

When the scenario is reset or loaded from a .dss file, the current tin value will be set to this initial tin value.

Note that this function cannot be called once the scenario has begun running (diguyScenario::get_t() returns > 0).

Note that both tin and tout times are scenario-relative times, not character-relative.

This call makes an implicit call to set_current_tin() with the same value.

Parameters

tin	new value of initial tin in seconds

Returns:

0 on success, -1 on failure

int diguyCharacter::set_initial_tout

(

float

tout

)

This function sets the initial tout ("T Out") time of the character.

See set_current_tin() for a discussion of how tin and tout times affect the character.

When the scenario is reset or loaded from a .dss file, the current tout value will be set to this initial tout value.

Note that this function cannot be called once the scenario has begun running (diguyScenario::get_t() returns > 0).

Note that both tin and tout times are scenario-relative times, not character-relative.

This call makes an implicit call to set_current_tout() with the same value.

Parameters

tout	new value of initial tout in seconds

Returns:

0 on success, -1 on failure

int diguyCharacter::set_current_tin

(

float

tin

)

This function sets the current tin ("T In") time of the character.

The character will not be visible nor will it start moving or animating until the scenario reaches this time.

There are two ways the tin and tout times of the character can be used:

The first is to set them to their desired values when the scenario begins. If, for example, it is known that this character should only be visible and active from 60 seconds to 80 seconds, the tin and tout times can be set to 60 and 80, respectively. The scenario will then spend very little time for character updates and draws outside of these limits.

The second is to use them to quickly "trigger" a character to become visible and start moving. This is done by setting the initial values of tin and tout to very high values, and then changing them to lower values when the character should become active. Consider the following example: This character is waiting just inside a doorway, and should emerge when another character comes close. If the tin time of the character is very high, very little time will be taken for this character's updates and draws. When the other character does come close, this character's tin time can be set to "now" (the scenario's current t, as returned by diguyScenario::get_t()). This character will then become visible and start moving out of the doorway.

The default current tin time is the current time of the scenario when the character is created.

Note that both tin and tout times are scenario-relative times, not character-relative.

Parameters

tin	new value of current tin in seconds

Returns:

0 on success, -1 on failure

int diguyCharacter::set_current_tin_to_now

(

)

Same as set_current_tin(), but time is set to current scenario time.

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

float diguyCharacter::get_current_tin

(

)

This function returns the current tin time of the character.

See set_current_tin().

Returns:

Current tin time in seconds.

int diguyCharacter::set_current_tout	(	float	tout,
		int	disable_character_at_tout = 0
	)

This function sets the current tout ("T Out") time of the character.

If tout is enabled the character will become invisible and will stop moving and animating when the scenario reaches this time.

Note that both tin and tout times are scenario-relative times, not character-relative.

Default tout time is 60000 seconds.

Parameters

tout	new value of current tout in seconds
disable_character_at_tout	this argument is present to keep the function prototype will remain backward compatible; it has no effect

int diguyCharacter::set_current_tout_to_now

(

)

Same as set_current_tout(), but time is set to current scenario time.

Returns:

0 on success, -1 on failure

Available as Decision Bead

float diguyCharacter::get_current_tout

(

)

This function returns the current tout ("T Out") time of the character in seconds.

See set_current_tout().

void diguyCharacter::set_tout_enabled

(

int

tout_enabled

)

This function sets what will happen when the character reaches its tout time.

If set to 0, the character will ignore the tout time and continue indefinitely.

int diguyCharacter::get_tout_enabled

(

)

This function returns the whether tout is enabled.

See set_tout_enabled().

Returns:

1 if tout enabled, 0 if not

int diguyCharacter::set_careful_interpolation_threshold

(

float

threshold

)

When the motion data of a character is interpolated a quick interpolation method can be used which may yield incorrect results, or an expensive interpolation method can be used which will yield correct results at the expense of time.

The threshold at which the interpolation method changes is specified by this function.

Parameters

threshold

float between 0 (careful never) and 1 (careful always); default is 0.7

DI-Guy compares the careful interpolation threshold to the cosine of an angle. Both the threshold and the cosine are dimensionless and thus have no units.

Returns:

0 on success, -1 on failure

float diguyCharacter::get_careful_interpolation_threshold

(

)

Returns: most recent setting of the careful interpolation threshold; see set_careful_interpolation_threshold()

int diguyCharacter::set_motion_interpolation_flag

(

int

flag

)

Sets whether the motion data of the character is interpolated.

Interpolation is disabled by default for better performance. For applications achieving high frame rates, smoother motion may be achieved by turning interpolation on.

Parameters

flag	0 by default

Returns:

0 on success, -1 on failure

int diguyCharacter::get_motion_interpolation_flag

(

)

Returns: most recent setting of the motion interpolation flag; see set_motion_interpolation_flag()

int diguyCharacter::set_scale	(	float	scale_x,
		float	scale_y,
		float	scale_z
	)

Sets the scale of the character on each of the three major axes.

Parameters

scale_x,scale_y,scale_z

the factor by which to scale along the given axis

Returns:

0 on success, -1 on failure

int diguyCharacter::get_scale	(	float *	scale_x,
		float *	scale_y,
		float *	scale_z
	)

Returns the scale of the character.

Parameters

sx,sy,sz

scale of the character along each axis

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::set_parent	(	const char *	parent_name,
		const char *	parent_link_name = ""
	)

Sets the parent of this character to be the passed character.

This means that the coordinate system of this character will be local to the parent character rather than the world coordinate system.

Parameters

parent_name	character to which this character should be attached; pass NULL to have no parent and be attached to the world
parent_link_name	name of the link or connection point to which this character's position link should attach; pass "" to attach to the parent's position link

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

diguyCharacter* diguyCharacter::get_parent

(

)

Gets the parent of this character.

Returns:

pointer to type diguyCharacter; NULL if no parent

Available as Decision Bead/Event

const char* diguyCharacter::get_parent_link_name

(

)

Gets the link name that the character is parented to, if any.

Returns:

name of link, NULL if no parent

int diguyCharacter::unset_parent

(

)

Detaches a character from its parent and reattaches it to the world.

This is equivalent to diguyCharacter::set_parent(NULL).

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::get_num_children

(

)

Gets the number of children the character has.

diguyCharacter* diguyCharacter::get_child_at_index

(

int

index

)

This function returns a pointer to the nth child of the character.

Returns:

pointer of type diguyCharacter; NULL if no child at the specified index

Parameters

index

index of the child; indices start at 0

int diguyCharacter::get_is_scene_object

(

)

Gets if a character is a static object, by default any blitzed .

in props are.

Returns:

1 if true, 0 if false

int diguyCharacter::set_is_scene_object

(

int

is_scene_object

)

Sets if a character is a static object.

By default any blitzed in props are.

Parameters

is_scene_object

pass 1 to make the object a scene object, 0 to not

Returns:

0 on success, -1 on failure

float diguyCharacter::get_bounding_radius

(

)

Gets the bounding radius currently used for this character for purposes of culling it from the draw operation.

Returns:

The current draw-culling bounding radius for the character, in meters.

float diguyCharacter::get_default_bounding_radius

(

)

Gets the default draw-culling bounding radius for this character, as specified in its actor cfg file.

See actor_vehicle.cfg for an example.

Returns:

The default draw-culling bounding radius for the character.

void diguyCharacter::set_bounding_radius

(

float

f

)

Sets the current draw-culling bounding radius to be used for this character.

float diguyCharacter::get_time_to_transition

(

)

This function returns the number of seconds before the blend into the next motion begins.

If the character is already in a blend between motions the function returns 0.

Note that this function is of limited practical use; in most cases get_time_to_reach_desired_action() returns information that is more useful.

Returns:

time to next blend, in seconds

Mode Restrictions:

• This function can only be called in free action mode.

diguyCharacterMode diguyCharacter::get_action_mode

(

)

Returns: the action mode of the character.

diguyCharacterMode diguyCharacter::get_position_mode

(

)

Returns: the position mode of the character.

int diguyCharacter::set_t_scale_factor

(

float

t_scale_factor

)

This function speeds up or slows down the character.

Setting this value greater than 1 will cause character actions to be played back at a slower pace, setting to less that 1 will cause character actions to be played at a faster pace.

This will override other factors that may scale the time scale factor of a character. (For example, smaller scale characters will generally move faster.)

Call unset_t_scale_factor() to allow other factors such as scale or desired speed to determine the time scale factor.

Mode Restrictions:

• This function can only be called in free action mode.

Parameters

t_scale_factor

time scale factor

Returns:

0 on success, -1 on failure

int diguyCharacter::unset_t_scale_factor

(

)

This function removes the manual setting of the time scale factor as set by set_t_scale_factor().

Mode Restrictions:

• This function can only be called in free action mode.

Returns:

0 on success, -1 on failure

int diguyCharacter::is_within_distance_n_of_character	(	const char *	character_name,
		float	distance
	)

This function determines whether this character is within the specified distance of another.

Parameters

character	character to be checked
distance	distance to character in meters

Returns:

1 if within distance; 0 if not

int diguyCharacter::is_within_distance_n_of_member_of_group	(	const char *	group_name,
		float	distance
	)

This function determines whether this character is within the specified distance of any members of the specified group.

Parameters

group_name	name of group to be checked
distance	distance in meters

Returns:

1 if member of group is within distance; 0 if not

int diguyCharacter::is_group_member

(

const char *

group_name

)

This function determines whether a character is a member of a particular group.

Also see diguyCharacterGroup::is_member().

Parameters

group_name

name of group to be checked

Returns:

1 if character is in group, 0 if not

int diguyCharacter::get_num_group_memberships

(

)

This function returns the number of groups that a character is a member of.

Also see diguyCharacterGroup::is_member().

diguyCharacterGroup* diguyCharacter::get_group_membership_at_index

(

int

index

)

This function returns a pointer to the nth group that this character is a member of.

Also see diguyCharacterGroup::is_member().

Returns:

pointer of type diguyCharacterGroup; NULL if no group at the specified index

Parameters

index

index of the group; indices start at 0

diguyCharacter* diguyCharacter::get_nearest_active_character	(	int	check_visibility,
		int	xy_distance = 0,
		float	max_distance_to_check = 100000
	)

This function will check all characters in the scenario and return the nearest character that is both alive and enabled.

An optional argument specifies whether to skip characters that are invisible to the caller because a scene object is in the way. Checking visibility is only an option if an octtree is generated from scene objects. Typically only DI-Guy Scenario does this.

Parameters

check_visibility	whether to check that characters are visible to calling character; pass 1 to check, 0 to not check
xy_distance	whether to include the z component in distance calculations; pass 1 to check only XY distance, 0 to check XYZ distance

Returns:

pointer of type diguyCharacter; may be NULL

diguyCharacter* diguyCharacter::get_nearest_active_character_in_group	(	const char *	group_name,
		int	check_visibility = 1,
		int	xy_distance = 0,
		float	max_distance_to_check = 100000
	)

This function will check all characters in a group and return the nearest character that is both alive and enabled.

An optional argument specifies whether to skip characters that are invisible to the caller because a scene object is in the way. Checking visibility is only an option if an octtree is generated from scene objects. Typically only DI-Guy Scenario does this.

Parameters

group_name	name of group to check
check_visibility	whether to check that characters are visible to calling character; pass 1 to check, 0 to not check
xy_distance	whether to include the z component in distance calculations; pass 1 to check only XY distance, 0 to check XYZ distance

Returns:

pointer of type diguyCharacter; may be NULL

diguyCharacter* diguyCharacter::get_random_active_character	(	float	max_distance = 10.0f,
		int	check_visibility = 1,
		int	xy_distance = 0
	)

This function will check all characters in the scenario and return a random character within max_distance that is both alive and enabled.

An optional argument specifies whether to skip characters that are invisible to the caller because a scene object is in the way. Checking visibility is only an option if an octtree is generated from scene objects. Typically only DI-Guy Scenario does this.

Parameters

check_visibility	whether to check that characters are visible to calling character; pass 1 to check, 0 to not check
max_distance	how far away the search cut off should be pass
in	1.0f to use all characters
xy_distance	whether to include the z component in distance calculations; pass 1 to check only XY distance, 0 to check XYZ distance

Returns:

pointer of type diguyCharacter; may be NULL

diguyCharacter* diguyCharacter::get_random_active_character_in_group	(	const char *	group_name,
		float	max_distance = 10,
		int	check_visibility = 1,
		int	xy_distance = 0
	)

This function will check all characters in a group and return a random character within max_distance that is both alive and enabled.

An optional argument specifies whether to skip characters that are invisible to the caller because a scene object is in the way. Checking visibility is only an option if an octtree is generated from scene objects. Typically only DI-Guy Scenario does this.

Parameters

group_name	name of group to check
max_distance	how far away the search cut off should be, pass
in	1.0f to use all characters
check_visibility	whether to check that characters are visible to calling character; pass 1 to check, 0 to not check
xy_distance	whether to include the z component in distance calculations; pass 1 to check only XY distance, 0 to check XYZ distance

Returns:

pointer of type diguyCharacter; may be NULL

float diguyCharacter::get_distance_to_character

(

diguyCharacter *

character

)

This function returns the 3D distance from this character to the specified character, in meters.

The distance is calculated from the characters' idealized positions.

float diguyCharacter::get_distance_xy_to_character

(

diguyCharacter *

character

)

This function returns the 2D distance in X and Y coordinates only from this character to the specified character, in meters.

The distance is calculated from the characters' idealized positions.

float diguyCharacter::get_distance_to_impact

(

diguyImpact *

impact

)

This function returns the 3D distance from this character to the specified impact, in meters.

The distance is calculated from the characters' idealized positions.

float diguyCharacter::get_random_factor

(

)

Each character has a "random factor" between 0 and 1.

This value is persistent with the character; i.e., the random factor will stay constant for the entire lifetime of the character.

This random factor can be used to add some variability between different characters.

Though each character has a random factor that has a very good chance of being different from all other characters' in the scenario, this is not guaranteed and so should not be used as a unique identifier.

An example of use: Instead of all characters beginning an action or behavior at the same time, have each one begin (random_factor * 2.0) seconds from the current time. This will result in more natural looking behavior as characters one by one begin the new behavior in the next two seconds, rather than all beginning at once.

Returns:

the character's random factor, a value between 0 and 1

int diguyCharacter::draw

(

)

This function draws this character in immediate mode graphics environments (see below).

This is the equivalent of calling draw_pass1() immediately followed by draw_pass2().

Returns:

0 on success, -1 on failure

OpenGL Version:

This function immediately draws this character. Either this function or draw_pass1() and draw_pass2() should be called once per frame.

int diguyCharacter::draw_pass1

(

)

This function, along with draw_pass2(), allows the drawing of opaque and transparent polygons to be separated.

This function draws all opaque polygons of this character.

Returns:

0 on success, -1 on failure

OpenGL Version:

This function immediately draws the opaque character parts. Either this function or draw() should be called once per frame.

int diguyCharacter::draw_pass2

(

)

Same as draw_pass1(), but draws transparent character parts.

void* diguyCharacter::get_graphics_ptr

(

)

Returns: A pointer to the character's graphics.

Vega Prime Version:

The return pointer may be cast to point to a vpDiguyCharacter, which is derived from vpObject.

OpenGL Version:

This function returns NULL.

DI-Guy Graphics API:

This function returns the pointer set from the most recent set_graphics_ptr() call.

int diguyCharacter::set_graphics_ptr

(

void *

graphics_ptr

)

Sets a graphics environment-specific pointer to graphics data.

The pointer can be retrieved using get_graphics_ptr().

Parameters

graphics_ptr

pointer to graphics data

Returns:

0 on success, -1 on failure

OpenGL Version:

This function should not be called for these environments.

DI-Guy Graphics API Version:

This function allows graphics environment-specific data to be stored for later retrieval by get_graphics_ptr(). DI-Guy does not directly use the pointer, beyond returning it using the get_graphics_ptr() function.

void diguyCharacter::set_graphics_api_node_ptr

(

void *

node_ptr

)

This function sets a generic node pointer that can later be retrieved by the get_graphics_api_node_ptr() call.

The pointer is otherwise not used.

Callback Info:

This function can be safely be called in the CALLBACK_ID_SET_GRAPHICS_API_NODE_PTR callback.

Parameters

node_ptr

generic void* pointer

void* diguyCharacter::get_graphics_api_node_ptr

(

)

Returns: pointer set by most recent call to set_graphics_api_node_ptr.

int diguyCharacter::set_user_data

(

void *

user_data

)

This function stores a pointer to user data.

Parameters

user_data

pointer for user's own use; DI-Guy will do nothing to the contents of this pointer beyond passing it back when requested by get_user_data()

Returns:

0 on success, -1 on failure

void* diguyCharacter::get_user_data

(

)

Returns: The user data pointer set by set_user_data()

int diguyCharacter::set_desired_action	(	const char *	action_name,
		float	speed = DIGUY_DEFAULT_FLOAT,
		int	retain_path_shape = 0
	)

This function sets the desired action of the character.

This function will put the character into free action mode. If the character was in path action mode, actions will no longer be set by action beads on the path.

If the character is in path position mode and 1 is passed for retain_path_shape, the character will stay in path position mode. If 0 is passed for retain_path_shape, the character will be put into free position mode.

If the character is in free position mode the retain_path_shape argument will have no effect.

If this call is interrupting a character in path action mode and path position mode, the character will not be able to resume the interrupted path unless retain_path_shape is set to 1. See resume_interrupted_path().

This function will have no effect on a dead character (see die_now() and get_dead()).

Mode Effects:

• This function will put the character into free action mode.
• This function may change the position mode; see Description.

Parameters

action_name	name of the desired action to be performed by the character
speed	the speed at which the character should travel while performing the action; pass DIGUY_DEFAULT_FLOAT for the optimal speed to be used
retain_path_shape	pass 1 to remain in path position mode; pass 0 to change to free position mode

Returns:

0 on success, -1 on failure

const char* diguyCharacter::get_desired_action

(

)

Returns: name of desired action; see set_desired_action() Note at times this is preferable to the current action since the desired action changes when a transition starts but the current action only changes when a transition finishes.

int diguyCharacter::get_desired_action_index

(

)

Returns index of desired action being performed by the character.

const char* diguyCharacter::get_current_action

(

)

Returns name of current action being performed by the character.

int diguyCharacter::get_current_action_index

(

)

Returns index of current action being performed by the character.

diguyMotionDirection diguyCharacter::get_current_action_direction

(

)

Returns the overall travel direction that the current action is going.

int diguyCharacter::get_is_in_action_transition

(

)

This function returns the transition state of the action of a character.

When commanding an action, DI-Guy may transition the character through one or more intermediate actions to reach the final action. For example, a character with the action "walk" that is commanded to "prone" would transition through the intermediate action "stand".

Returns:

1 if the character is transitioning between actions 0 otherwise

int diguyCharacter::force_action	(	const char *	action_name,
		float	speed = DIGUY_DEFAULT_FLOAT,
		int	include_transition_arc = 1,
		float	max_rampdown_interval = 0.5f,
		int	retain_path_shape = 0,
		float	t_offset_into_new_action = 0.0f
	)

This function forces the current action of the character to be the action identified by action_name.

See set_desired_action() for a discussion of the effects on position mode.

This function will have no effect on a dead character (see die_now() and get_dead()).

By passing a value greater than 0 for t_offset_into_new_action, the character can be made to begin the action partway in. This is useful when forcing actions for a lot of characters at the same time; without the offset, the characters would move in lockstep.

The most recent forced action, the time at which it was forced, and any time offset can be queried using the functions get_most_recent_forced_action(), get_most_recent_forced_action_t(), and get_most_recent_forced_action_t_offset().

Mode Effects:

• This function will put the character into free action mode.
• This function may change the position mode; see Description.

Parameters

action_name	name of the action to be performed by the character
speed	the speed at which the character should travel while performing the action; pass DIGUY_DEFAULT_FLOAT for the optimal speed to be used
include_transition_arc	flag for whether the transition motion from the current action to the new action is included; pass 1 for best chance of good looking transition; pass 0 for fastest response
max_rampdown_interval	max amount of time spent trying to smooth over any motion seams; set to 0.5 for a smooth transition, set to 0 for a potentially rough transition
retain_path_shape	pass 1 to remain in path position mode; pass 0 to change to free position mode
t_offset_into_new_action	how much to shift time forward into new action; must be >= 0; see comment above for more info

Returns:

0 on success, -1 on failure

int diguyCharacter::force_action_with_duration	(	const char *	action_name,
		float	duration,
		int	include_transition_arc = 1,
		float	max_rampdown_interval = 0.5f
	)

This function is similar to force_action(), but allows the specification of how long the interruption should last.

This function will have no effect on a dead character (see die_now() and get_dead()).

Mode Restrictions:

• This function can only be called if the character is in path action mode and path position mode.

Mode Effects:

• This function will put the character into free action mode.
• This function will not change the position mode.

Parameters

duration

how long the action should be performed before an automatic resume_interrupted_path() call is made

Returns:

0 on success, -1 on failure

int diguyCharacter::force_action_and_path_shape	(	const char *	action_name,
		const char *	path_shape_name,
		const char *	waypoint_name = NULL,
		float	distance_into_path = 0.0f
	)

This function forces the current action of the character to be the action identified by action_name, to be executed along the path shape specified by path_shape_name.

This function will have no effect on a dead character (see die_now() and get_dead()).

Mode Effects:

• This function will put the character into free action mode.
• This function will put the character into path position mode.

Parameters

action_name	name of the action to be performed by the character
path_shape_name	name of the path shape on which action should be performed
waypoint_name	name of waypoint on path shape to begin at; default of NULL will start at first waypoint
distance_into_path	distance into path shape to start at, if waypoint_name isn't specified

Returns:

0 on success, -1 on failure

const char* diguyCharacter::get_most_recent_forced_action

(

)

This function returns the most recently forced action as set by by force_action(), force_action_with_duration(), or force_action_and_path_shape().

Returns:

the name of the most recent forced action, or NULL if no action has been forced

float diguyCharacter::get_most_recent_forced_action_t

(

)

This function returns the time at which the most recently forced action occurred.

Returns:

time at which force action occurred; -1.0 if no action has been forced

float diguyCharacter::get_most_recent_forced_action_t_offset

(

)

This function returns the action time offset of the most recently forced action.

This is typically value of the t_offset_into_new_action argument of the force_action() call.

Returns:

time at which force action occurred; -1.0 if no action has been forced

int diguyCharacter::add_pending_desired_action	(	const char *	action,
		float	scenario_t,
		int	remove_existing_pending_actions = 0,
		float	speed = DIGUY_DEFAULT_FLOAT,
		int	retain_path_shape = 1
	)

This function adds a "pending action" to the character.

This is essentially a delayed set_desired_action() call. The desired action will be set at the passed scenario t, just as if set_desired_action() is called at that time.

Note: Any call to set_desired_action() or force_action(), or their related variants, will clear any pending actions.

Parameters

action	name of pending desired action
scenario_t	time at which to set desired action
remove_existing_pending_actions	pass 1 to remove any previously added pending actions, 0 to leave them
speed	as passed to set_desired_action()
retain_path_shape	as passed to set_desired_action()

Returns:

0 on success, -1 on failure

int diguyCharacter::add_pending_force_action	(	const char *	action,
		float	scenario_t,
		int	remove_existing_pending_actions = 0,
		float	speed = DIGUY_DEFAULT_FLOAT,
		int	include_transition_arc = 1,
		float	max_rampdown_interval = 0.5f,
		int	retain_path_shape = 1,
		float	first_arc_time_shift = 0.0f
	)

Similar to add_pending_desired_action(), but will do a force_action() at the passed scenario_t instead of a set_desired_action().

Note: Any call to set_desired_action() or force_action(), or their related variants, will clear any pending actions.

Returns:

0 on success, -1 on failure

int diguyCharacter::is_valid_action

(

const char *

action

)

Returns: 1 if the passed action name is an action available to this character, 0 if not.

int diguyCharacter::die_now

(

const char *

preferred_dead_action_name = "(default)"

)

This function sends this character a signal to die as soon as possible.

The character will transition to a dead action.

The following side-effects will also happen:

• all aiming is ended
• all gazing is ended
• all pointing is ended
• head nodding and shaking are stopped
• all gestures are aborted
• all sounds originated by the character are stopped
• Destroyed appearance might be switched to.

Many function calls will have no effect on dead characters; see individual function descriptions for limitations.

Use the get_dead() call to retrieve the dead state of a character.

Mode Effects:

• This function will put the character into free action mode.
• This function will not change the position mode.

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::revive_now

(

const char *

preferred_revive_action_name = "(default)"

)

This function revives a dead character.

The limitations of dead characters will be lifted from the revived character; e.g., the character will be able to gaze, execute gestures, etc.

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::get_dead

(

)

This function returns whether or not the character is dead.

Characters can be killed by die_now() function calls, as well as by being hit by weapon fire.

Returns:

1 if character is dead (die_now() function has been called), 0 if not.

int diguyCharacter::set_speed

(

float

speed

)

Sets the speed the character should attempt to move, in meters per second.

This setting takes effect immediately. To set a desired action and a desired speed at the same time, use the speed argument of the set_desired_action() call.

This desired speed setting can be undone in a couple of ways:

1. by calling set_speed() with an argument of DIGUY_DEFAULT_FLOAT, or
2. by calling set_desired_action(), or
3. by calling one of the force_action() functions

Parameters

speed

desired speed in meters per second

Returns:

0 on success, -1 on failure

float diguyCharacter::get_speed

(

)

Returns: the approximate speed at which the character is moving, in meters per second.

float diguyCharacter::get_desired_speed

(

)

Returns: The desired speed of the character, in meters per second.

Calls to set_speed(), set_desired_action(), or force_action() assign the character a desired speed, to which it transitions over some amount of time. If the speed-setting was instantaneous, the current speed will be returned.

int diguyCharacter::set_animation_target_el	(	float	elevation,
		float	ramp_time = .25f
	)

Sets a generic parameter that can be mapped to a blend tree driver.

Useful for creating animations that can play back at different vertical angles.

float diguyCharacter::get_animation_target_el

(

)

Returns the current target elevation.

int diguyCharacter::set_animation_target_az	(	float	azimuth,
		float	ramp_time = .25f
	)

Sets a generic parameter that can be mapped to a blend tree driver.

Useful for creating animations that can play back at different horizontal angles.

float diguyCharacter::get_animation_target_az

(

)

Returns the current target azimuth.

void diguyCharacter::set_animation_velocity	(	float	vel_x,
		float	vel_y,
		float	vel_z,
		float	ramp_time = .25f
	)

Sets a generic parameter in world space that can be mapped to a blend tree driver.

The locomotion actions are driven by these values allowing one action to go many different direction. Internally this is mapped to local space.

In practical terms, this means that a character with the appropriate animation blend tree can be made to move at an arbitrary speed in an arbitrary direction, provided that the blend tree supports these motions. One example would be a soldier who can "strafe" from side to side while pointing his weapon in a certain direction. Another example would be a car that can travel forwards or backwards at a speed within a continuous range.

Users can see a demonstration of this feature in the character view by selecting an appropriate character type (e.g. vehicle_09), appearance (e.g. taxi_2013), and action ("movement"). The exercise blend tree widget will allow adjustments.

void diguyCharacter::get_animation_velocity	(	float *	vel_x,
		float *	vel_y,
		float *	vel_z
	)

Returns the world space x,y,z velocity that's driving the blend tree.

void diguyCharacter::set_animation_local_velocity	(	float	vel_x,
		float	vel_y,
		float	vel_z,
		float	ramp_time = .25f
	)

Sets a generic parameter in local space that can be mapped to a blend tree driver.

The locomotion actions are driven by these values allowing one action to go many different directions.

Similar to set_animation_velocity() in terms of overall practical details. Note that the local velocity setting will affect the character's world velocity.

void diguyCharacter::get_animation_local_velocity	(	float *	vel_x,
		float *	vel_y,
		float *	vel_z
	)

Returns the local space x,y,z velocity that's driving the blend tree.

void diguyCharacter::set_animation_angular_velocity	(	float	vel_rz,
		float	ramp_time = .25f
	)

Sets a generic parameter in that can be mapped to a blend tree driver.

The locomotion actions are driven by these values allowing one action to turn

float diguyCharacter::get_animation_angular_velocity

(

)

Returns the angular velocity that's driving the blend tree.

int diguyCharacter::set_position	(	float	tx,
		float	ty,
		float	tz
	)

Sets the position of the character relative to the origin of the DI-Guy global coordinate system.

The new settings will take effect immediately, possibly causing the character to "teleport" if the new values are significantly different than the old.

The DI-Guy global coordinate system is right-handed, with X forward, Z up, and Y to the left. Rotation directions follow standard right-handed coordinate system conventions:

• positive rotations about X cause a counter-clockwise roll
• position rotations about Y cause a forward pitch
• positive rotations about Z cause a yaw to the left

Note that if the character has an altitude function (see set_altitude_function()), the tz argument will effectively be ignored as the altitude function will override it.

If the magnitude of the numbers is large (say 32000 or higher), the function set_position_double() should be used instead.

Mode Effects:

• This function will put the character into free position mode.
• This function will put the character into free action mode.

Parameters

tx,ty,tz

position in meters from the origin

Returns:

0 on success, -1 on failure

int diguyCharacter::set_position_double	(	double	tx,
		double	ty,
		double	tz
	)

Similar to set_position(), but using double-precision rather than single-precision numbers.

If the magnitude of the numbers is large (say 32000 or higher), this function should be used.

Mode Effects:

• This function will put the character into free position mode.
• This function will put the character into free action mode.

Parameters

tx,ty,tz

position in meters from the origin

Returns:

0 on success, -1 on failure

int diguyCharacter::get_position	(	float *	tx,
		float *	ty,
		float *	tz
	)

Retrieves the position of the character in the DI-Guy global coordinate system.

See set_position() for a description of the coordinate system.

Parameters

tx,ty,tz

position in meters from the origin

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::get_position_double	(	double *	tx,
		double *	ty,
		double *	tz
	)

Retrieves the position of the character in the DI-Guy global coordinate system.

See set_position() for a description of the coordinate system.

Unlike get_position(), this function returns higher-precision values for the position, which is important when the character is far from the coordinate system origin.

Parameters

tx,ty,tz

position in meters from the origin

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::set_position_relative_to_parent	(	float	tx,
		float	ty,
		float	tz
	)

Sets the position of the character relative to its parent or the origin of the DI-Guy global coordinate system if this character is not parented.

See set_position() for a description of the coordinate system.

The new settings will take effect immediately, possibly causing the character to "teleport" if the new values are significantly different than the old.

Mode Effects:

• This function will put the character into free position mode.
• This function will put the character into free action mode.

Parameters

tx,ty,tz

position in meters from the origin

Returns:

0 on success, -1 on failure

int diguyCharacter::get_position_relative_to_parent	(	float *	tx,
		float *	ty,
		float *	tz
	)

Retrieves the position of the character relative to its parent, or relative to the origin of the DI-Guy global coordinate system if this character is not parented.

See set_position() for a description of the coordinate system.

Parameters

tx,ty,tz

position in meters from the origin

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::set_position_to_other_character_position	(	const char *	other_character_name,
		const char *	other_link_name = NULL,
		float	offset_x = 0.0f,
		float	offset_y = 0.0f,
		float	offset_z = 0.0f,
		int	also_set_orientation = 1
	)

Similar to set_position_relative_to_parent(), but the position is either from the other character's overall position (if other_link_name is NULL), or the position of the other character's link (if other_link_name specifies a link on the other character).

The position that is set is relative to this character's parent.

Mode Effects:

• This function will put the character into free position mode.
• This function will put the character into free action mode.

Parameters

other_character_name	other character from which to read position
other_link_name	optional link on other character; if NULL, other character's base position is used
offset_x,offset_y,offset_z	offset to apply to position read from other character
also_set_orientation	pass 1 to also set this character's orientation from the other character's orientation

Returns:

0 on success, -1 on failure

int diguyCharacter::set_desired_position	(	float	tx,
		float	ty,
		float	tz,
		int	force_guide_unacquired = 0
	)

Sets the desired position of the character.

How the character moves toward the desired position is determined by its current guides; see add_guide() and create_guide().

Mode Effects:

• This function will put the character into free position mode.
• This function will put the character into free action mode.

Parameters

tx,ty,tz	desired position in meters from the origin
force_guide_unacquired	this optional argument will set any guides the character has to be unacquired Returns:

0 on success, -1 on failure

int diguyCharacter::set_desired_position_double	(	double	tx,
		double	ty,
		double	tz,
		int	force_guide_unacquired = 0
	)

int diguyCharacter::set_desired_position_to_current_position

(

int

also_set_orientation = 1

)

Like set_desired_position(), but uses the character's current position as the desired position.

Mode Effects:

• This function will put the character into free position mode.
• This function will put the character into free action mode.

Parameters

also_set_orientation

pass 1 to also set this character's orientation to its current orientation

Returns:

0 on success, -1 on failure

int diguyCharacter::set_desired_position_to_waypoint	(	diguyWaypoint *	waypoint,
		float	offset_x = 0.0f,
		float	offset_y = 0.0f,
		float	offset_z = 0.0f,
		int	offset_in_world_coords = 0
	)

Like set_desired_position(), but sets the character's desired position to passed waypoint's position.

The passed waypoint can be one created by diguyScenario::create_waypoint, a waypoint from a character's diguyCharacterPath, or waypoint from a diguyPathShape.

Mode Effects:

• This function will put the character into free position mode.
• This function will put the character into free action mode.

Parameters

waypoint	pointer to diguyWaypoint object
offset_x,offset_y,offset_z	offset to apply to waypoint position
offset_in_world_coords	1 if offset is to be in world coordinates, 0 if it is to be
in	waypoint local coordinates

Returns:

0 on success, -1 on failure

int diguyCharacter::set_desired_position_to_path_waypoint	(	const char *	path_name,
		const char *	waypoint_name
	)

Like set_desired_position(), but finds the specified waypoint on the specified path and sets the character's desired position to the waypoint's position.

Mode Effects:

• This function will put the character into free position mode.
• This function will put the character into free action mode.

Parameters

path_name	name of path on which to find waypoint
waypoint_name	name of waypoint

Returns:

0 on success, -1 on failure

int diguyCharacter::set_desired_position_to_path_shape_waypoint	(	const char *	path_shape_name,
		const char *	waypoint_name
	)

Like set_desired_position(), but finds the specified waypoint on the specified path shape and sets the character's desired position to the waypoint's position.

Mode Effects:

• This function will put the character into free position mode.
• This function will put the character into free action mode.

Parameters

path_shape_name	name of path shape on which to find waypoint
waypoint_name	name of waypoint

Returns:

0 on success, -1 on failure

int diguyCharacter::get_desired_position	(	float *	tx,
		float *	ty,
		float *	tz
	)

Retrieves the desired position of the character.

Mode Restrictions:

• This function can only be called in free position mode.

Parameters

tx,ty,tz

desired position in meters from the origin

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::get_desired_position_double	(	double *	tx,
		double *	ty,
		double *	tz
	)

int diguyCharacter::get_delta_to_desired_position	(	float *	tx,
		float *	ty,
		float *	tz
	)

Retrieves the delta vector from current position to desired one.

Mode Restrictions:

• This function can only be called in free position mode.

Parameters

tx,ty,tz

delta in meters

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::set_initial_position	(	float	tx,
		float	ty,
		float	tz
	)

Sets the initial position the character should move to on a call to diguyScenario::reset().

If the character has an initial path, that path, not this function call, will determine its initial position.

Parameters

tx,ty,tz

initial position in meters from the origin

Returns:

0 on success, -1 on failure

int diguyCharacter::get_initial_position	(	float *	tx,
		float *	ty,
		float *	tz
	)

Retrieves the initial position of the character.

If the character is in free position mode or has no initial path, this will be the position set by set_initial_position().

Otherwise this will be the position of the first waypoint of the initial path.

Parameters

tx,ty,tz

initial position in meters from the origin

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::set_orientation	(	float	rz,
		float	rx,
		float	ry
	)

Sets the orientation of the character relative to the origin of the DI-Guy global coordinate system.

See set_position() for a description of the coordinate system.

The new settings will take effect immediately, possibly causing the character to "teleport" if the new values are significantly different than the old.

Note that if the character has an up vector type of 'z' or 'n' or even sometimes 'd' (as set by the set_up_vector_type() call) the rx and ry values will not have any effect. To be able to set rx and ry values, set the up vector type of the character to 'c', for "custom".

Mode Effects:

• This function will put the character into free position mode.
• This function will put the character into free action mode.

Parameters

rz,rx,ry

orientations in degrees

Returns:

0 on success, -1 on failure

int diguyCharacter::get_orientation	(	float *	rz,
		float *	rx,
		float *	ry
	)

Retrieves the orientation of the character in the DI-Guy global coordinate system.

See set_position() for a description of the coordinate system.

**

Note

For vehicles, you may want to use the function get_vehicle_body_orientation(). See that function for more information.

Parameters

rz,rx,ry

orientations in degrees counter-clockwise from the positive X axis

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::set_orientation_relative_to_parent	(	float	rz,
		float	rx,
		float	ry
	)

Sets the orientation of the character relative to its parent or the origin of the DI-Guy global coordinate system if this character is not parented.

See set_position() for a description of the coordinate system.

The new settings will take effect immediately, possibly causing the character to "teleport" if the new values are significantly different than the old.

Mode Effects:

• This function will put the character into free position mode.
• This function will put the character into free action mode.

Parameters

rz,rx,ry

orientations in degrees

Returns:

0 on success, -1 on failure

int diguyCharacter::get_orientation_relative_to_parent	(	float *	rz,
		float *	rx,
		float *	ry
	)

Retrieves the orientation of the character relative to its parent, or the origin of the DI-Guy global coordinate system if this character does not have a parent.

See set_position() for a description of the coordinate system.

Parameters

rz,rx,ry

orientations in degrees counter-clockwise from the positive X axis

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::set_initial_up_vector_type

(

char

axis

)

This function sets how the character should be oriented relative to its surroundings.

This function changes the current up vector type, and the up vector type that will be set when the character is reset. To change only the current up vector type (a temporary change that goes away on reset), call set_up_vector_type()).

Parameters

axis	the up vector type the character should use; legal values shown below:

• 'd' - use default settings; character will change up vector type depending on current action and path shape parameters
• 'z' - Z axis is up; character will be oriented so that positive Z in character coordinates is always oriented along the positive world Z axis
• 'n' - normal to path; character will be oriented so that positive Z in character coordinates is normal to the path shape the character is on
• 'g' - ground-clamped; the vehicle will attempt to cling to the terrain, in an approximation of real rigid body physics
• 'c' - custom; character's rx and ry orientation values will not be modified

Having an up vector type of 'z' effectively zeroes out the rx and ry values of the character's orientation.

Having an up vector type of 'n' may override rx and ry values of the character's orientation with values derived from the character's path shape.

Having an up vector type of 'c' allows the pitch and roll of the character to be changed without taking it off the path it in on by calling set_custom_orientation_rx_and_ry(). Calling set_orientation() has the side-effect of putting the character into free position mode, taking it off of any path it's on.

Returns:

0 on success, -1 on failure

int diguyCharacter::set_initial_up_vector

(

char

axis

)

This function is being deprecated, but remains for backwards compatibility.

It does the same thing as set_initial_up_vector_type()

char diguyCharacter::get_initial_up_vector_type

(

)

Returns: current up vector type; see set_initial_up_vector_type()

char diguyCharacter::get_initial_up_vector

(

)

This function is being deprecated, but remains for backwards compatibility.

It does the same thing as get_initial_up_vector_type()

int diguyCharacter::set_up_vector_type

(

char

axis

)

This function sets how the character should be oriented relative to its surroundings.

This function changes only the current up vector type. To change the up vector type that will be used when the character is reset, call set_initial_up_vector_type().

Parameters

axis	the up vector type the character should use; see set_initial_up_vector_type() for description

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::set_up_vector

(

char

axis

)

This function is being deprecated, but remains for backwards compatibility.

It does the same thing as set_up_vector_type()

char diguyCharacter::get_up_vector_type

(

)

Returns: current up vector type; see set_up_vector_type()

char diguyCharacter::get_up_vector

(

)

This function is being deprecated, but remains for backwards compatibility.

It does the same thing as get_up_vector_type()

int diguyCharacter::set_custom_orientation_rx_and_ry	(	float	rx,
		float	ry
	)

This function sets the rx and ry components of the character's orientation.

Unlike set_orientation(), this function does not put the character into free position mode if it is currently in path position mode.

Note that if the character has an up vector type of 'z' or 'n' or even sometimes 'd' (as set by the set_up_vector_type() call) this function will not have any effect. To be able to set rx and ry values, set the up vector type of the character to 'c', for "custom".

The passed rx and ry values are in character-local coordinates, not parent coordinates if the character has a parent.

Mode Effects:

• None.

Parameters

rx,ry

orientations in degrees

Returns:

0 on success, -1 on failure

int diguyCharacter::set_desired_orientation	(	float	rz,
		float	rx,
		float	ry,
		int	force_guide_unacquired = 0
	)

Sets the desired orientation of the character.

See set_desired_position().

Mode Effects:

• This function will put the character into free position mode.
• This function will put the character into free action mode.

Parameters

rz,rx,ry

orientations in degrees counter-clockwise from the positive X axis

Returns:

0 on success, -1 on failure

int diguyCharacter::get_desired_orientation	(	float *	rz,
		float *	rx,
		float *	ry
	)

Retrieves the desired orientation of the character.

Mode Restrictions:

• This function can only be called in free position mode.

Parameters

rz,rx,ry

orientations in degrees counter-clockwise from the positive X axis

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::get_delta_to_desired_orientation	(	float *	rz,
		float *	rx,
		float *	ry
	)

Retrieves the delta from current orientation of the character to the desired one.

Mode Restrictions:

• This function can only be called in free position mode.

Parameters

rz,rx,ry

orientation deltas in degrees counter-clockwise from the positive X axis

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::set_desired_orientation_to_current_orientation

(

)

Like set_desired_orientation(), but uses the character's current orientation as the desired orientation.

Mode Effects:

• This function will put the character into free position mode.
• This function will put the character into free action mode.

Returns:

0 on success, -1 on failure

int diguyCharacter::set_desired_orientation_towards_position	(	float	x,
		float	y,
		float	z,
		int	force_guide_unacquired = 0
	)

Like set_desired_orientation(), but orients the character towards the position specified.

Mode Effects:

• This function will put the character into free position mode.
• This function will put the character into free action mode.

Returns:

0 on success, -1 on failure

int diguyCharacter::set_initial_orientation	(	float	rz,
		float	rx,
		float	ry
	)

Sets the initial orientation the character should move to on a call to diguyScenario::reset().

If the character is on a path the path, not this function call, will determine its initial orientation.

Parameters

rz,rx,ry

orientations in degrees counter-clockwise from the positive X axis

Returns:

0 on success, -1 on failure

int diguyCharacter::get_initial_orientation	(	float *	rz,
		float *	rx,
		float *	ry
	)

Retrieves the initial orientation of the character.

If the character is in free position mode or has no initial path, this will be the orientation set by set_initial_orientation().

Otherwise this will be the orientation of the first waypoint of the initial path.

Parameters

rz,rx,ry

orientations in degrees counter-clockwise from the positive X axis

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::get_link_position	(	const char *	link_name,
		float *	tx,
		float *	ty,
		float *	tz,
		float *	rz,
		float *	rx,
		float *	ry
	)

Returns the location and orientation of a specific link of the character.

Parameters

link_name	name of the link or connection point; links are named after their inbound joint name
tx,ty,tz	position in meters from the origin of the world
rz,rx,ry	orientations in degrees counter-clockwise from the positive X axis

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::get_link_position_double	(	const char *	link_name,
		double *	tx,
		double *	ty,
		double *	tz,
		double *	rz,
		double *	rx,
		double *	ry
	)

Returns the location and orientation of a specific link of the character.

Parameters

link_name	name of the link or connection point; links are named after their inbound joint name
tx,ty,tz	position in meters from the origin of the world
rz,rx,ry	orientations in degrees counter-clockwise from the positive X axis

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::get_link_position_with_offset	(	const char *	link_name,
		float	offset_tx,
		float	offset_ty,
		float	offset_tz,
		float *	tx,
		float *	ty,
		float *	tz,
		float *	rz,
		float *	rx,
		float *	ry
	)

Similar to get_link_position(), but allows specification of offset into ending link.

Parameters

link_name	name of the link or connection point
offset_tx,offset_ty,offset_tz	offset in link
tx,ty,tz	position in meters from the origin
rz,rx,ry	orientations in degrees counter-clockwise from the positive X axis

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::get_link_position_with_offset_double	(	const char *	link_name,
		double	offset_tx,
		double	offset_ty,
		double	offset_tz,
		double *	tx,
		double *	ty,
		double *	tz,
		double *	rz,
		double *	rx,
		double *	ry
	)

Similar to get_link_position(), but allows specification of offset into ending link.

Parameters

link_name	name of the link or connection point
offset_tx,offset_ty,offset_tz	offset in link
tx,ty,tz	position in meters from the origin
rz,rx,ry	orientations in degrees counter-clockwise from the positive X axis

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::get_link_relative_position	(	const char *	beginning_link_name,
		const char *	ending_link_name,
		float *	tx,
		float *	ty,
		float *	tz,
		float *	rz,
		float *	rx,
		float *	ry
	)

Returns the location and orientation of a specific link of the character relative to the position of another link.

Parameters

beginning_link_name	name of the first link; send NULL to to specify the position link
ending_link_name	name of the last link; send NULL to to specify the position link
tx,ty,tz	position in meters from the origin
rz,rx,ry	orientations in degrees counter-clockwise from the positive X axis

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

int diguyCharacter::get_link_relative_position_with_offset	(	const char *	beginning_link_name,
		const char *	ending_link_name,
		float	offset_tx,
		float	offset_ty,
		float	offset_tz,
		float *	tx,
		float *	ty,
		float *	tz,
		float *	rz,
		float *	rx,
		float *	ry
	)

Similar to get_link_relative_position(), but allows specification of offset into ending link.

Parameters

beginning_link_name	name of the first link; send NULL to to specify the position link
ending_link_name	name of the last link; send NULL to to specify the position link
offset_tx,offset_ty,offset_tz	offset in ending link
tx,ty,tz	position in meters from the origin
rz,rx,ry	orientations in degrees counter-clockwise from the positive X axis

Pass NULL for any values that are not needed.

Returns:

0 on success, -1 on failure

void diguyCharacter::set_apply_actor_scale_to_action_bead_travel

(

int

apply_scale_flag

)

By default characters on a path will scale their movement speed and velocity based on the scale of the actor the character is based on.

For example, if a tall character and short character are both playing the exact same walk motion, the tall character will move further per motion repetition than the short character.

Scaling the travel in this way leads to more realistic looking motion, but can cause different characters using the same actions and underlying motions to move at different speeds. At times it is convenient to not scale the travel.

If actor scaling is disabled, characters of different sizes will all move the same distance, and at the same speed, if they have the same path shapes and action beads. Note that in cases of extreme differences between the actor the motion is based on and the actor the character's current appearance is based on, the characters feet may slip on the ground more than normal.

Parameters

apply_scale_flag

pass 1 to apply actor scale to travel; 0 to not

int diguyCharacter::get_apply_actor_scale_to_action_bead_travel

(

)

Returns: 1 if actor scale is being applied to travel, 0 if not.

int diguyCharacter::local_to_global	(	float	x,
		float	y,
		float	z,
		float *	res_x,
		float *	res_y,
		float *	res_z
	)

This function transforms a point that is in the local space of the character into a location in the world.

Useful for things like navigating AIs to a location near a prop. Or moving to a spot in front of someone else.

This code presumes up_axis is 'z' and that there is only rotation about that axis.

int diguyCharacter::global_to_local	(	float	x,
		float	y,
		float	z,
		float *	res_x,
		float *	res_y,
		float *	res_z
	)

This function transforms a point that is in world space into the local space of a character.

Useful for figuring out if something was seen.

This code presumes up_axis is 'z' and that there is only rotation about that axis.

void diguyCharacter::get_velocity	(	float *	vel_x,
		float *	vel_y,
		float *	vel_z
	)

Retrieves the current estimated velocity of the character.

Note this value may not be valid in environments where characters are transformed independent of DI-Guy function calls. Teleporting characters can also temporarily make this calculation incorrect.

Parameters

vel_x,vel_y,vel_z

meters/sec

Pass NULL for any values that are not needed.

void diguyCharacter::set_desired_velocity	(	float	vel_x,
		float	vel_y,
		float	vel_z,
		float	ramp_time = 0.0
	)

Used by the Drift and Adaptive guide.

Parameters

vel_x,vel_y,vel_z

meters/sec

void diguyCharacter::get_desired_velocity	(	float *	vel_x,
		float *	vel_y,
		float *	vel_z
	)

void diguyCharacter::get_angular_velocity

(

float *

vel_rz

)

Retrieves the current estimated angular velocity of the character.

As above, changes made to characters independent of DI-Guy function calls will temporarily make this value incorrect.

Currently only the angular velocity in yaw is measured.

Parameters

vel_rz

degrees/sec

void diguyCharacter::set_desired_angular_velocity

(

float

vel_rz

)

Used by the Drift and Adaptive guide.

Documentation Pending

void diguyCharacter::get_desired_angular_velocity

(

float *

vel_rz

)

const char* diguyCharacter::get_appearance

(

)

Returns the base appearance of the character, as passed to the function diguyScenario::create_character().

This pointer will never be NULL.

Note that the current appearance (as returned by get_current_appearance()) may be different than the base appearance. This base appearance is the starting appearance of the character before any calls to set_current_appearance() have been made.

Returns:

name of base appearance of the character

int diguyCharacter::set_appearance

(

const char *

appearance

)

This function sets the base appearance of the character.

The base appearance is the appearance the character will take if the scenario is reset, undoing any appearance changes made be calls to set_current_appearance().

Calling this function also makes an implicit call to set_current_appearance().

Parameters

appearance

name of new base appearance

Returns:

0 on success, -1 on failure

int diguyCharacter::set_current_appearance	(	const char *	appearance,
		int	allow_actor_change = 1
	)

This function sets the current appearance of this character.

Note that different appearances may be based on different actors. Different actors represent people of different sizes, so changing to an appearance that has a different actor can cause a pronounced change in character size.

Also, changing actors can take some time, as more internal character state needs to be updated to support the new size of the character.

Parameters

appearance	name of new desired appearance
allow_actor_change	pass 1 to allow the appearance change even if the actor changes, 0 to not

See Also:

get_current_appearance(), set_current_head_appearance()

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

const char* diguyCharacter::get_current_appearance

(

)

Returns: current appearance; see set_current_appearance()

int diguyCharacter::get_current_appearance_is

(

const char *

appearance

)

This function can be used to see if the current appearance has the passed name.

This is primarily useful for decisions and other limited logic applications.

Returns:

1 if current appearance has passed name; 0 if not

Available as Decision Bead/Event

int diguyCharacter::set_current_head_appearance

(

const char *

head_appearance

)

This function sets the current head appearance of this character.

On failure head appearance will be set to "default".

Parameters

head_appearance

name of the new desired head appearance

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::set_head_appearance

(

const char *

head_appearance

)

This function sets the head appearance of this character.

const char* diguyCharacter::get_current_head_appearance

(

)

Returns: current head appearance; see set_current_head_appearance()

int diguyCharacter::get_current_head_appearance_is

(

const char *

head_appearance

)

Similar to get_current_appearance_is(), but for head appearance.

Returns:

1 if current head appearance has passed name; 0 if not

Available as Decision Bead/Event

int diguyCharacter::set_hand_item

(

const char *

hand_item_appearance

)

const char* diguyCharacter::get_hand_item

(

)

Returns: Hand item appearance; see set_hand_item()

Might return "default"

int diguyCharacter::set_current_hand_item

(

const char *

hand_item_appearance

)

const char* diguyCharacter::get_current_hand_item

(

)

Returns: Current hand item appearance.

Will be the actual appearance displayed, not "default"

int diguyCharacter::get_num_appearances_of_type

(

diguyCharacterAppearanceTypes

appearance_type

)

Parameters

appearance_type

a value indicating the type of supplementary appearance of concern

Returns:

The number of available supplementary appearances of given type

const char* diguyCharacter::get_appearance_name_at_index	(	diguyCharacterAppearanceTypes	appearance_type,
		int	index
	)

See description for get_num_supplementary_appearances_of_type()

Parameters

appearance_type	a value indicating the type of appearance of concern
index	a value indicating the type of supplementary appearance of concern

Returns:

The name of the appearance or NULL

int diguyCharacter::set_lod_ranges

(

float *

lod_ranges

)

Sets the graphics level of detail (LOD) ranges for this character.

Compare with diguyScenario::set_default_lod_ranges(), which sets the LOD ranges for newly created characters of a particular type. In both cases, ranges must be a static array of 8 floats, each larger than the one before.

This function sets graphics LOD ranges only. Motion levels of detail can be set by calling set_motion_lod().

Parameters

lod_ranges

new lod ranges for this character;

See diguyScenario::set_default_lod_ranges() for a description of what to pass in lod_ranges.

Returns:

0 on success, -1 on failure

Callable From:

• C++

float* diguyCharacter::get_lod_ranges

(

)

returns float * list of lod ranges that's get_num_lods() long.

int diguyCharacter::get_num_lods

(

)

should always return 8

int diguyCharacter::set_graphics_lod

(

int

lod

)

Set the desired graphics level of detail (LOD) for this character.

This may be overridden if this character uses automatic LOD switching. See diguyScenario::set_automatic_graphics_lod_switching().

DI-Guy graphics LODs are numbered 1 (most detail) through 7 (least detail).

Parameters

lod	an integer between 1 and 7

Returns:

0 on success, -1 on failure

int diguyCharacter::get_graphics_lod

(

)

Returns current graphics LOD.

int diguyCharacter::set_shader_lod

(

int

lod

)

Set the desired shader level of detail (LOD) for this character.

By default this is -1 and the shader is automatically picked by distance.

DI-Guy shaders LODs are numbered 1 (most quality) through the number of shaders in the current technique.

Parameters

lod	an integer between 1 and the number of shaders in the current technique

Returns:

0 on success, -1 on failure

int diguyCharacter::get_shader_lod

(

)

Returns: current shader LOD.

int diguyCharacter::set_motion_lod

(

int

motion_lod

)

**

Note

As of DI-Guy 12.5 we strongly recommend using the multi-threaded pipeline for increasing performance.

Sets the motion level of detail (LOD) for this character. LOD 1 animates all joints of a character. Higher LODs animate fewer joints.

For LOD 6, nothing in the pose is updated. The character's pose will remain whatever it was the last time pose data was changed.

Parameters

LOD	Effect
1	animate all joints
2	stop animating wrists and ankles
3	stop animating elbows and knees
4	stop animating everything but pelvis and position
5	stop animating everything but position
6	stop animating everything but position

Note that characters that are load managed (get_is_load_managed() returns 1) have this parameter managed automatically. The corresponding function for load managed characters is diguyLoadManager::set_zone_motion_lod().

Parameters

motion_lod

an integer between 1 and 6

Returns:

0 on success, -1 on failure

int diguyCharacter::get_motion_lod

(

)

Returns: character's current motion LOD setting; see set_motion_lod()

int diguyCharacter::get_current_motion_lod

(

)

Returns: character's current motion LOD based on load manangement and culling; see set_motion_lod()

int diguyCharacter::set_minimum_cpl

(

int

minimum_cpl

)

**

Note

As of DI-Guy 12.5 we strongly recommend using the multi-threaded pipeline for increasing performance.

This function sets the minimum CPL (character performance level) of the character.

A higher CPL will limit the types of operations that the character can perform, but will allow for more optimized update() calls.

The following CPL limitations are cumulative:

• CPL 1: all character function calls are available
• CPL 2: the character cannot save history
• CPL 3: no advanced pose operations that alter the basic pose of the character, including:
  • gazing
  • pointing
  • aiming
  • gestures
  • head nodding and shaking
  • pose overrides
  • features relying on link matrices

  • wheel rolling and turning on vehicles

    Since link matrices are not computed, the DI-Guy Graphics API function diguyGraphicsLink::get_transformation_matrix() will not return valid results.

• CPL 4: no blends between motions

• CPL 5: (not currently implemented)

  Note that characters that are load managed (get_is_load_managed() returns 1) have this parameter managed automatically. The corresponding function for load managed characters is diguyLoadManager::set_zone_minimum_cpl().

  The passed minimum_cpl may not be achievable if the character is already in the process of doing something not allowed by the new CPL. For example, if the character is already gazing, trying to set the minimum CPL to 3 will fail, as CPL 3 would disable gazing. In this case the minimum CPL will be set to the current highest possible CPL based on what the character is already doing. In this example the minimum CPL would be set to 2, as gazing is allowed at that CPL.

  Conversely, if the minimum CPL has been successfully been set to 3 or higher, any gaze calls such as diguyCharacter::gaze_at_point() will fail.

Parameters

cpl	minimum CPL allowed for this character

Returns:

0 on success, -1 on failure

int diguyCharacter::get_minimum_cpl

(

)

Returns: most recent setting of set_minimum_cpl()

int diguyCharacter::get_maximum_possible_current_cpl

(

)

This function returns that maximum possible CPL the character can attain based on what it is currently doing.

Advanced pose operations like gazing and pose overrides will limit the maximum CPL that can be achieved.

See diguyCharacter::set_minimum_cpl() for a description of what is possible under the different CPL levels.

Returns:

maximum possible current CPL

int diguyCharacter::maximize_current_cpl

(

)

This function puts the character into the maximum possible CPL that can be achieved based on what the character is currently doing.

This current CPL does not prevent the character from starting operations that will potentially lower the CPL. e.g., if the character starts gazing, the CPL will potentially go down. Use set_minimum_cpl() to prevent that character from starting such operations.

See diguyCharacter::set_minimum_cpl() for a description of what is possible under the different CPL levels.

Returns:

0 on success, -1 on failure

int diguyCharacter::set_automatic_cpl_switching_enabled

(

int

enabled

)

This function sets a flag that determines whether the character should raise and lower its CPL automatically.

If automatic CPL switching is enabled then any time a potential CPL-changing operation is performed, the character will check the maximum possible current CPL (as per a call to maximize_current_cpl()) and set its current CPL to the maximum possible.

Parameters

enabled

pass 1 to enable automatic CPL switching, 0 to disable it

Returns:

0 on success, -1 on failure

int diguyCharacter::get_automatic_cpl_switching_enabled

(

)

Returns: most recent setting of get_automatic_cpl_switching_enabled()

int diguyCharacter::set_current_cpl

(

int

current_cpl

)

This function sets the current CPL of the character.

Trying to set the CPL lower than the minimum (as set by set_minimum_cpl()) of higher than the maximum (as returned by get_maximum_possible_current_cpl()) will fail.

Note that characters that have automatic CPL switching enabled (get_automatic_cpl_switching_enabled() returns 1) will override this value.

See diguyCharacter::set_minimum_cpl() for a description of what is possible under the different CPL levels.

Parameters

cpl	new current CPL

Returns:

0 on success, -1 on failure

int diguyCharacter::get_current_cpl

(

)

Returns: the current CPL the character is using.

int diguyCharacter::set_position_update_rate

(

int

update_rate

)

This function sets the position update rate of the character.

If the character's position is not updated on a particular update tick, its position will not change for that tick. This can result is a modest performance increase.

The default value for new characters is 100.

This value may be overridden by the minimum full update period, as set by set_minimum_full_update_period().

Note that if the character's pose is updated, (see diguyCharacter::set_pose_update_rate()) its position will be updated as well.

Note that characters that are load managed (get_is_load_managed() returns 1) have this parameter managed automatically. The corresponding function for load managed characters is diguyLoadManager::set_zone_position_update_rate().

Parameters

update_rate

percentage of scenario ticks for which position should update; can be between 1 and 100

Passing 100 means position will update every tick. Passing 50 means position will update every other tick.

Returns:

0 on success, -1 on failure

int diguyCharacter::get_position_update_rate

(

)

Returns: character's position update rate as set by set_position_update_rate()

int diguyCharacter::set_pose_update_rate

(

int

update_rate

)

This function is very similar to set_position_update_rate(), but sets the percentage of ticks for which the character's pose is updated.

The default value for new characters is 100.

This value may be overridden by the minimum full update period, as set by set_minimum_full_update_period().

Note that if the character's pose is updated, its position will be updated as well.

Note that characters that are load managed (get_is_load_managed() returns 1) have this parameter managed automatically. The corresponding function for load managed characters is diguyLoadManager::set_zone_pose_update_rate().

Parameters

update_rate

percentage of scenario ticks for which pose should update; can be between 1 and 100

Passing 100 means pose will update every tick. Passing 50 means pose will update every other tick.

Returns:

0 on success, -1 on failure

int diguyCharacter::get_pose_update_rate

(

)

Returns: character's pose update rate as set by set_pose_update_rate()

int diguyCharacter::set_minimum_full_update_period

(

float

min_period

)

This function sets the minimum period for position or pose updates.

If the passed amount of time passes with no position or pose update (see set_position_update_rate() and set_pose_update_rate()), the character's position and potentially pose will be updated.

Note that characters that are load managed (get_is_load_managed() returns 1) have this parameter managed automatically. The corresponding function for load managed characters is diguyLoadManager::set_minimum_full_update_period().

The default for new characters is 1.0 seconds.

Parameters

min_period

in seconds

Returns:

0 on success, -1 on failure

float diguyCharacter::get_minimum_full_update_period

(

)

Returns: character's minimum full update period, as set by set_minimum_full_update_period()

int diguyCharacter::set_position_accumulation_disabled

(

int

disabled_flag

)

This function disables position accumulation due to played actions.

The character will stay in whatever position has most recently been set by set_position(), regardless of action. Because of this the character will, for example, walk in place. It is up to the user application to correctly set and update the character's position.

This function can be used when a host application provides absolute control over character positions.

Disabling position accumulation will result in a modest performance increase.

Parameters

disabled_flag

pass 1 to disable position accumulation, 0 to enable it

Returns:

0 on success, -1 on failure

int diguyCharacter::get_position_accumulation_disabled

(

)

Returns: most recent setting of set_position_accumulation_disabled()

int diguyCharacter::set_all_blends_disabled

(

int

disabled_flag

)

This function disables all blends between motions of the character.

This will speed up performance at the expense of visual quality of the motions. If the character is far from the current camera position, however, the lack of blends may be visually acceptable.

Note that characters that are load managed (get_is_load_managed() returns 1) have this parameter managed automatically.

Parameters

disabled_flag

pass 1 to disable all blends, 0 to enable them

Returns:

0 on success, -1 on failure

int diguyCharacter::get_all_blends_disabled

(

)

Returns: most recent setting of set_all_blends_disabled()

int diguyCharacter::set_shape_switches_disabled

(

int

disabled_flag

)

**

Note

This function is not recommended. There is minimal perf gain. This function disables all update calls for shape switches.

Switches currently control:

• muzzle flashes

• hand switching for selected characters

  For DI-Guy Graphics API users this means that most calls to diguyGraphicsShape::show() and diguyGraphicsShape::hide() will not be made.

  Note that characters that are load managed (get_is_load_managed() returns 1) have this parameter managed automatically.

Parameters

disabled_flag

pass 1 to disable shape switches, 0 to enable them

Returns:

0 on success, -1 on failure

int diguyCharacter::get_shape_switches_disabled

(

)

Returns: most recent setting of set_shape_switches_disabled()

int diguyCharacter::set_shape_callbacks_disabled

(

int

disabled_flag

)

**

Note

This function is not recommended. There is minimal perf gain. This function disables all shape callbacks. Shape callbacks are used internally for updating some advanced visual effects.

Shape callbacks currently control:

• expressive faces

• particle systems

  Disabling shape callbacks will make these visual effects work incorrectly but will result in a performance increase for characters that do not use them.

  Note that characters that are load managed (get_is_load_managed() returns 1) have this parameter managed automatically.

Parameters

disabled_flag

pass 1 to disable shape callbacks, 0 to enable them

Returns:

0 on success, -1 on failure

int diguyCharacter::get_shape_callbacks_disabled

(

)

Returns: most recent setting of set_shape_callbacks_disabled()

int diguyCharacter::set_graphics_api_shape_update_disabled

(

int

disabled_flag

)

**

Note

This function is not recommend. There is minimal perf gain. This function disables all calls to the virtual diguyGraphicsShape::update() function.

Note that characters that are load managed (get_is_load_managed() returns 1) have this parameter managed automatically.

Parameters

disabled_flag

pass 1 to disable update calls, 0 to enable them

Returns:

0 on success, -1 on failure

int diguyCharacter::get_graphics_api_shape_update_disabled

(

)

Returns: most recent setting of set_graphics_api_shape_update_disabled()

int diguyCharacter::optimized_update

(

float

t

)

This function is a stripped-down version of the normal update() function.

This function is for high performance applications that are willing to sacrifice advanced character functionality in exchange for faster performance.

Characters using optimized_update() must not do any of the following:

• change character types (e.g., set_character_type())
• play sounds (e.g., play_sound())
• use history (e.g., set_history_type())
• use paths (e.g., push_path())
• weapon firing (e.g., fire_weapon())
• advanced pose operations (as per CPL 3)
• be a DI-Guy Network Module character
• need to use character callbacks

• use advanced visual effects, such as expressive faces and particle systems

  Like update(), the scenario must not call the character's update() function (return value of get_t_controlled_by_scenario_t() is 0) for this function to work properly.

  In some cases the regular update() call can be used for a time in place of optimized_update() if one of the above operations is desired.

Parameters

t	new time for the character

Returns:

0 on success, -1 on failure

int diguyCharacter::set_is_load_managed

(

int

is_load_managed

)

This function sets whether many of the performance tuning functions above are automatically managed by a diguyLoadManager object, which can be obtained by calling diguyApp::create_load_manager().

Note that this function will have no effect if a load manager has not been enabled.

The default for new characters is to be load managed if the load manager has been enabled.

Parameters

is_load_managed

pass 1 to have character automatically load managed, 0 for manual management

Returns:

0 on success, -1 on failure

int diguyCharacter::get_is_load_managed

(

)

Returns: most recent setting of get_is_load_managed()

int diguyCharacter::add_callback	(	int	callback_id,
		diguyCharacterCallback *	callback,
		void *	callback_params = 0,
		void *	callback_user_data = 0
	)

This function adds a user callback.

Callbacks can be removed with remove_callback() or remove_callback_with_user_data().

Parameters

callback	pointer to function with prototype diguyCharacterCallback (typedefed above)
callback_id	integer id of when this callback is to be called
callback_params	not currently used; pass NULL
callback_user_data	pointer for user's own use; DI-Guy will do nothing to the contents of this pointer beyond passing it back when the callback is invoked

Returns:

0 on success, -1 on failure

int diguyCharacter::remove_callback	(	int	callback_id,
		diguyCharacterCallback *	callback
	)

This function removes a user callback.

All callbacks matching the specified callback_id and callback function will be removed.

Parameters

callback_id	integer id of when this callback is to be called
callback	pointer to function with prototype diguyCharacterCallback (typedefed above)

Returns:

0 on success, -1 on failure

int diguyCharacter::remove_callback_with_user_data	(	int	callback_id,
		void *	callback_user_data
	)

This function removes a user callback.

All callbacks matching the specified callback_id and callback_user_data pointer will be removed.

Parameters

callback_id	integer id of when this callback is to be called
callback_user_data	pointer for user's own use

Returns:

0 on success, -1 on failure

int diguyCharacter::add_callback_script	(	int	callback_id,
		const char *	callback_script,
		const char *	callback_script_type = NULL
	)

This function adds a user callback script.

Callback scripts can be removed with remove_callback_script().

Parameters

callback_id	integer id of the callback
callback_script	script text of callback to be added
callback_script_type	the type of script contained in callback_script

If NULL is passed for callback_script_type, a default script type will be derived based on the default script interpreter of the scenario.

lua specific:

When the script is called, the object for which it is being called will be in the callback_object global.

To pass NULL when calling from a lua script, use nil.

Returns:

0 on success, -1 on failure

Lua Example:

-------------------------------------------------------------------
local pre_fire_weapon_callback = [[

    local ch_name = callback_object:get_name();
    bdi_log_print(BDI_LOG_WARN, "Calling pre_fire_weapon_callback for character ".. ch_name .. ".\n");

]]
-------------------------------------------------------------------

character:add_callback_script(diguyCharacter_CALLBACK_ID_PRE_FIRE_WEAPON,
    pre_fire_weapon_callback,
    "lua");

int diguyCharacter::remove_callback_script	(	int	callback_id,
		const char *	callback_script,
		const char *	callback_script_type = NULL
	)

This function removes a user callback script previously added with add_callback_script().

Parameters

callback_id	integer id of the callback
callback_script	script text of callback previously added
callback_script_type	the type of script contained in callback_script

If NULL is passed for callback_script, all callback scripts whose ids match callback_id and whose types match callback_script_type will be removed.

If NULL is passed for callback_script_type, a default script type will be derived based on the default script interpreter of the scenario.

lua specific:

To pass NULL when calling from a lua script, use nil.

Returns:

0 on success, -1 on failure

lua Example:

#
#  Remove all callback scripts with id
#  diguyCharacter_CALLBACK_ID_PRE_FIRE_WEAPON
#
character:remove_callback_script(diguyCharacter_CALLBACK_ID_PRE_FIRE_WEAPON,
    nil,
    "lua");

int diguyCharacter::map_event_handler_to_callback_id	(	int	callback_id,
		const char *	handler_name
	)

This function maps the event handler with the given name to a callback id.

This mapping will be saved in the .dss file and restored when the .dss file is loaded.

Mappings can also be made via the DI-Guy Scenario UI.

The event handler is one of the following:

• a character callback function registered by diguyScenario::register_character_event_handler() or diguyScenario::register_character_event_handler_from_library()
• a script registered by diguyScenario::register_character_event_handler_script()
• a Script, Decision, or Library Function in the scenario whose "Event Type" is "Character"

Parameters

callback_id	integer id of callback
handler_name	name of the event handler to map

Returns:

0 on success, -1 on failure

int diguyCharacter::unmap_event_handler_from_callback_id	(	int	callback_id,
		const char *	handler_name,
		int	unmap_all_matches = 0
	)

This function unmaps the event handler with the given name from a callback id.

Parameters

callback_id	integer id of callback
handler_name	name of the event handler to unmap
unmap_all_matches	pass 0 to unmap only the first match, pass 1 to unmap all matches

Returns:

0 on success, -1 on failure

diguyCallbackReturn diguyCharacter::manually_invoke_event_handler

(

const char *

handler_name

)

This function manually invokes the named character event handler.

The callback_id that will be passed to the event handler will be CALLBACK_ID_MANUALLY_INVOKED.

See diguyCharacter::map_event_handler_to_callback_id() for a description of what comprises a character event handler.

Note that care should be taken not to end up in an infinite loop of event calls. In general an event handler should not end up directly or indirectly invoking itself.

Parameters

handler_name

name of the event handler to invoke

Returns:

DIGUY_CALLBACK_CONTINUE or DIGUY_CALLBACK_STOP

Available as Decision Bead/Event

diguyCharacterPath* diguyCharacter::create_path

(

const char *

name

)

This function creates a new path.

The created path has no waypoints and no actions. Waypoints can be added using diguyCharacterPath::create_waypoint() or diguyCharacterPath::add_waypoint(). Action beads should be added using diguyCharacterPath::create_action_bead().

To create a simple path that has a few waypoints and actions, use create_simple_path().

The waypoints for the path should be created using the function diguyScenario::create_waypoint(). They should be deleted using the function diguyScenario::destroy_waypoint(). Copies of the waypoints are made during the function call, so it is safe to destroy them immediately after this function call returns, or use the waypoints again for another path.

The returned diguyCharacterPath pointer should be destroyed using destroy_path().

The path makes internal copies of all arguments.

Parameters

name	name of the new path

Returns:

pointer to type diguyCharacterPath

diguyCharacterPath* diguyCharacter::create_simple_path	(	const char *	name,
		diguyWaypoint *	waypoint0,
		diguyWaypoint *	waypoint1,
		const char *	transition_from_action_name,
		const char *	fill_action_name,
		const char *	transition_to_action_name
	)

This function creates a new simple path.

The path is simple because it has only two waypoints and three specified actions.

The waypoints for the path should be created using the function diguyScenario::create_waypoint(). They should be deleted using the function diguyScenario::destroy_waypoint(). Copies of the waypoints are made during the function call, so it is safe to destroy them immediately after this function call returns, or use the waypoints again for another path.

The returned diguyCharacterPath pointer should be destroyed using destroy_path().

The path makes internal copies of all arguments.

Parameters

name	name of the new path
waypoint0	beginning waypoint
waypoint1	ending waypoint
transition_from_action_name	name of the action the character should be transitioning from at the beginning of the path; can be NULL
fill_action_name	name of the action that should fill the majority of the path; can be NULL, but see below
transition_to_action_name	name of the action the character should transition into at the end of the path

If transition_from_action_name is NULL, an initial action bead that transitions to the fill action will not be created.

If fill_action_name is NULL, no action beads will be created for the path, even if transition_from_action_name and/or transition_to_action_name are non-NULL.

If transition_to_action_name is NULL, a final action bead that transitions from the fill action will not be created.

Returns:

pointer to type diguyCharacterPath

diguyCharacterPath* diguyCharacter::create_path_from_path_shape	(	const char *	name,
		diguyPathShape *	source_path_shape,
		const char *	transition_from_action_name,
		const char *	fill_action_name,
		const char *	transition_to_action_name
	)

This function is similar to create_simple_path(), but creates its waypoints based on waypoints from the passed path shape.

The path makes internal copies of all arguments.

Parameters

name	name of the new path
source_path_shape	path shape whose waypoints are used to define shape of new path
transition_from_action_name	same as for create_simple_path()
fill_action_name	same as for create_simple_path()
transition_to_action_name	same as for create_simple_path()

Returns:

pointer to type diguyCharacterPath

int diguyCharacter::create_and_force_bridge_path	(	const char *	destination_path_name,
		const char *	destination_path_action_bead_name,
		const char *	via_action_name
	)

This function creates a temporary path and immediately forces it as the character's current path.

Once it has been traversed it will be automatically deleted.

The beginning waypoint of this path is at the character's current position; the ending waypoint is at the specified action bead on the specified path (or the first action bead of the specified path if no action bead is specified). The character will use the specified action to move from the beginning waypoint to the ending waypoint.

This function is useful for getting a free position mode character back onto a path.

This function will have no effect on a dead character (see die_now() and get_dead()).

Mode Effects:

• This function will put the character into path position mode.
• This function will put the character into path action mode.

Parameters

destination_path_name	the path the character is trying to reach
via_action_name	the action used over the majority of the bridge path
destination_path_action_bead_name	the target action bead on the destination path; pass NULL to start at the beginning of the path

Returns:

0 on success, -1 on failure

int diguyCharacter::create_and_force_bridge_path_to_point	(	float	x,
		float	y,
		float	z,
		float	path_offset,
		const char *	via_action_name,
		const char *	next_local_path = NULL,
		float	orientation = 0.0f
	)

This function creates a temporary path and immediately forces it as the character's current path.

Once the path has been traversed it will be automatically deleted. The character then begins the local path specified by path_to_push.

The beginning waypoint of this path is at the character's current position; the ending waypoint is at the specified x, y, z. A path_offset is available to shorten the distance to the end point along the vector to the destination. The character will use the specified action to move from the beginning waypoint to the ending waypoint.

An optional follow-on path can be specified that the character will move onto once the end position is reached. This must be the name of an existing path for the character. A local path copy of the specified path will be created, and will be pushed to occur after this bridge path completes.

This function is useful for branching from one location to another in the world.

This function will have no effect on a dead character (see die_now() and get_dead()).

Mode Effects:

• This function will put the character into path position mode.
• This function will put the character into path action mode.

Parameters

x,y,z	location in world space the bridge path should aim for
path_offset	the amount to shorten the bridge path
via_action_name	the action used over the majority of the bridge path
next_local_path	local path to push when the character arrives at it's destination; pass NULL to not push a local path
orientation	amount to rotate the local path

Returns:

0 on success, -1 on failure

int diguyCharacter::destroy_path

(

diguyCharacterPath *

path

)

This function destroys a path created by create_path(), create_simple_path(), or a path from a loaded scenario.

The path the character is currently traveling, as returned by get_current_traveled_path(), cannot be destroyed. Attempting to destroy it will result in an error.

Parameters

path	path to be destroyed

Returns:

0 on success, -1 on failure

int diguyCharacter::get_num_paths

(

)

Returns: the number of paths belonging to this character.

diguyCharacterPath* diguyCharacter::get_path_at_index

(

int

index

)

Returns: pointer of type diguyCharacterPath; NULL if no path at the specified index.

Parameters

index

index of the path; indices start at 0

const char* diguyCharacter::get_path_name_at_index

(

int

index

)

Returns: the name of the path at the given index; NULL if no path at the specified index.

int diguyCharacter::get_current_path_index

(

)

This function returns the index of the path the character is currently following.

If the character is not following a path the returned index will be -1. (i.e., the character must be in path action mode and path position mode.)

Mode Restrictions:

• This function will only return a 0 or greater index if the character is in path action mode and path position mode.

Returns:

the index of the current path; -1 if not on a path

diguyCharacterPath* diguyCharacter::get_current_traveled_path

(

)

This function returns the path the character is currently traveling.

Mode Restrictions:

• This function can only be called in path position mode.

Returns:

pointer of type diguyCharacterPath; NULL if no path is currently being traveled

int diguyCharacter::get_current_traveled_path_is

(

const char *

path_name

)

This function can be used to see if the current traveled has the passed name.

This is primarily useful for decisions and other limited logic applications.

Returns:

1 if currently traveled path has the passed name; 0 if the name doesn't match, or no path is currently being traveled

Available as Decision Bead/Event

int diguyCharacter::push_path

(

const char *

path_name

)

This function pushes the path with the specified name onto the queue of paths this character will follow.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

name	name of the path to be pushed

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::force_path	(	const char *	path_name,
		float	max_rampdown_interval = 0.5f
	)

This function clears the queue of paths the character will follow and then pushes the path with the specified name.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

name	name of the path to be pushed
max_rampdown_interval	max amount of time spent trying to smooth over any motion seams; set to 0.5 for a smooth transition, set to 0 for a potentially rough transition

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::force_partial_path	(	const char *	path_name,
		const char *	beginning_action_bead_name,
		float	max_rampdown_interval = 0.5f
	)

Same as force_path(), but only motions at or after the specified action bead are added.

This function will have no effect on a dead character (see die_now() and get_dead()).

Available as Decision Bead/Event

int diguyCharacter::resume_interrupted_path

(

float

max_rampdown_interval = 0.5f

)

Resumes a path that was interrupted with a call such as set_desired_action() or force_action().

Note that the retain_path_shape argument to these functions must have been 1 for the path to be resumable.

This function will have no effect on a dead character (see die_now() and get_dead()).

Mode Restrictions:

• This function can only be called if the character is in free action mode and path position mode.

Mode Effects:

• This function will put the character into path position mode.
• This function will put the character into path action mode.

Parameters

max_rampdown_interval

max amount of time spent trying to smooth over any motion seams; set to 0.5 for a smooth transition, set to 0 for a potentially rough transition

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

diguyCharacterPath* diguyCharacter::force_local_path	(	const char *	path_name,
		int	use_character_orientation,
		float	rotation = 0.0f,
		int	clamp_path = 1
	)

This function creates a temporary path that is a copy of path_name but transformed so that the starting point is the same as where the character currently is.

It then forces it as the character's current path.

Parameters

path_name	path to copy
use_character_orientation	whether the character's orientation be incorporated into the transform of the path
rotation	additional amount to rotate the path, in degrees
clamp_path	whether the path be ground clamped

Returns:

pointer to type diguyCharacterPath

int diguyCharacter::set_initial_path

(

const char *

name

)

This function sets which path the character will start on when the scenario is reset.

Parameters

name	name of the path that will be the initial path

Returns:

0 on success, -1 on failure

const char* diguyCharacter::get_initial_path

(

)

This function returns the name of the path the character will start on when the scenario is reset.

See set_initial_path().

Returns:

name of initial path; NULL if there is none

void diguyCharacter::translate_all_paths	(	float	tx,
		float	ty,
		float	tz,
		int	reclamp_waypoints = 1
	)

This function translates all of the paths of this character.

Parameters

tx,ty,tz	distance in meters to move all waypoints
reclamp_waypoints	pass 1 to reclamp waypoints to ground

int diguyCharacter::rotate_all_paths_about_point	(	float	rz,
		float	rx,
		float	ry,
		float	rotation_pt_x,
		float	rotation_pt_y,
		float	rotation_pt_z,
		int	reclamp_waypoints = 1
	)

This function rotates all of the paths of this character.

The rotation will occur about the specified point.

Note: It is currently recommended that only rotations about the Z axis be done. (i.e., only rz should be non-zero.)

Parameters

rz,rx,ry	amount of rotation, in degrees
rotation_pt_x,rotation_pt_y,rotation_pt_z	point around which rotation should occur
reclamp_waypoints	pass 1 to reclamp waypoints to ground

int diguyCharacter::rotate_all_paths_about_current_waypoint	(	float	rz,
		float	rx,
		float	ry,
		int	reclamp_waypoints = 1
	)

This function is similar to rotate_all_paths_about_point(), but rotates around the character's current waypoint instead of an explicitly specified point.

Note: It is currently recommended that only rotations about the Z axis be done. (i.e., only rz should be non-zero.)

Parameters

rz,rx,ry	amount of rotation, in degrees
reclamp_waypoints	pass 1 to reclamp waypoints to ground

int diguyCharacter::jump_to_action_bead	(	const char *	bead_name,
		float	max_rampdown_interval = 0.5f
	)

This function causes the character to jump forward along its current path to the specified action bead.

Motions and beads that would have otherwise been played or processed will be skipped.

Parameters

bead_name	name of the bead to jump to
max_rampdown_interval	max amount of time spent trying to smooth over any motion seams; set to 0.5 for a smooth transition, set to 0 for a potentially rough transition

Returns:

0 on success, -1 on failure

diguyCharacterPath* diguyCharacter::find_path

(

const char *

path_name

)

This function finds and returns a pointer to the specified path.

Parameters

name	name of the path to be found

Returns:

Pointer to object of type diguyCharacterPath; NULL if path not found.

int diguyCharacter::apply_aim_bead	(	diguyCharacterPathAimBead *	bead,
		float	how_far = 0.0f
	)

This function causes the effects of the given aim bead to be applied to this character, regardless of whether the bead belongs to the character or whether character is within the bead's time interval.

Parameters

how_far

how far into the bead the call should be; should be between 0 (beginning of bead time interval) and 1 (end of bead time interval)

Returns:

0 on success, -1 on failure

int diguyCharacter::apply_decision_bead	(	diguyCharacterPathDecisionBead *	bead,
		float	how_far = 0.0f
	)

This function causes the effects of the given decision bead to be applied to this character, regardless of whether the bead belongs to the character or whether character is within the bead's time interval.

Parameters

how_far

how far into the bead the call should be; should be between 0 (beginning of bead time interval) and 1 (end of bead time interval)

Returns:

0 on success, -1 on failure

int diguyCharacter::apply_gaze_bead	(	diguyCharacterPathGazeBead *	bead,
		float	how_far = 0.0f
	)

This function causes the effects of the given gaze bead to be applied to this character, regardless of whether the bead belongs to the character or whether character is within the bead's time interval.

Parameters

how_far

how far into the bead the call should be; should be between 0 (beginning of bead time interval) and 1 (end of bead time interval)

Returns:

0 on success, -1 on failure

int diguyCharacter::apply_script_bead	(	diguyCharacterPathScriptBead *	bead,
		float	how_far = 0.0f
	)

This function causes the effects of the given script bead to be applied to this character, regardless of whether the bead belongs to the character or whether character is within the bead's time interval.

Parameters

how_far

how far into the bead the call should be; should be between 0 (beginning of bead time interval) and 1 (end of bead time interval)

Returns:

0 on success, -1 on failure

int diguyCharacter::set_distance_along_path

(

float

distance

)

This function sets how far along the current path shape the character will be.

Mode Restrictions:

• This function can only be called if the character is in free action mode and path position mode. i.e., the character is following a path shape, and is not on a diguyCharacterPath.

Parameters

distance

distance in meters; 0.0 is the beginning of the path shape

Returns:

0 on success, -1 on failure

float diguyCharacter::get_distance_along_path

(

)

Returns: the distance in meters along the path shape; see set_distance_along_path()

Mode Restrictions:

• This function can only be called in path position mode.

int diguyCharacter::leave_path

(

)

This function takes the character off of its current path or path shape.

Mode Restrictions:

• This function can only be called in path position mode.

Mode Effects:

• This function will put the character into free position mode.
• This function will put the character into free action mode.

Returns:

0 on success, -1 on failure

int diguyCharacter::get_nearest_waypoint_index_in_path

(

const char *

path_name

)

This function returns the index of the nearest waypoint in a path, the path argument is looked up in both the character's path list and the scenario's paths.

Returns:

waypoint index

float diguyCharacter::get_distance_to_path	(	const char *	path_name,
		const char *	action_bead_name = NULL
	)

Returns: Distance to action bead or first waypoint, 100000000.0 on failure.

diguyGraphicsLink* diguyCharacter::get_position_link

(

)

This function gets the position link of the character skeleton.

The rest of the skeleton can then be traversed by recursively calling the diguyGraphicsLink::get_num_child_links() and diguyGraphicsLink::get_child_link_at_index() functions.

Alternatively, the links of the character can be traversed by calling the get_num_links() and get_link_at_index() functions below.

Returns:

pointer of type diguyGraphicsLink; NULL if there is no position link

int diguyCharacter::get_num_links

(

)

Returns: number of links on this character.

diguyGraphicsLink* diguyCharacter::get_link_at_index

(

int

index

)

Returns: pointer of type diguyGraphicsLink; NULL if no link at the specified index.

Parameters

index

index of the link; indices start at 0

diguyGraphicsLink* diguyCharacter::find_link

(

const char *

name

)

This function returns a pointer to the specified link.

Parameters

name	name of link to be found

Returns:

pointer of type diguyGraphicsLink; NULL if not found

const char* diguyCharacter::get_link_name_at_index

(

int

link_index

)

Returns: the string identifying the link at the given index.

Parameters

link_index

index of the link; indices start at 0

int diguyCharacter::get_num_link_shapes

(

const char *

link_name

)

Returns: the number of shapes on the specified link.

Parameters

link_name

name of the link

const char* diguyCharacter::get_link_shape_name_at_index	(	const char *	link_name,
		int	shape_index
	)

Returns: the name of the shape at the specified index on the link.

Parameters

link_name	name of the link
shape_index	index of the shape on the link; indices start at 0

int diguyCharacter::get_num_connection_points

(

)

Returns the number of connection points (extra per appearance skeletal nodes)

const char* diguyCharacter::get_connection_point_name_at_index

(

int

index

)

The name of the connection point in the list.

This can be used in most functions that take a link name.

int diguyCharacter::get_num_connection_points_with_type

(

diguyConnectionPointType

type

)

Returns the number of connection points that have been tagged with the metadata diguyConnectionPointType type.

const char* diguyCharacter::get_connection_point_name_with_type	(	diguyConnectionPointType	type,
		int	index
	)

Returns the name of the connection point in the list of connection with type metadata.

This can be used in most functions that take a link name.

void diguyCharacter::set_link_visibility	(	const char *	link_or_connection_name,
		int	visible,
		int	shape_index = -1
	)

This is for setting visibility of shapes attached to a character at a link.

int diguyCharacter::set_altitude_function

(

diguyAltitudeFunction *

altitude_function

)

The following prototype should be used for the altitude function:

float altitude_func(diguyCharacter* character,
    float x,
    float y,
    float old_z);

When a character needs new altitude info, DI-Guy calls this function with a pointer to the diguyCharacter in question, the character's current (x, y) coordinates, and its previous altitude in old_z.

The altitude function should then compute and return the new altitude based on this information. This can be done in a number of ways; a typical approach is to do an intersection test with the visual scene. Some users might want to implement fairly complex behavior, such as attempting to make all four wheels of a vehicle touch the terrain, or causing a character to drift slowly towards the ground.

A default altitude function that should be set for all characters can be set by calling diguyScenario::set_default_character_altitude_function().

 This function is normally called for all characters if the flags

for enabling it in free movement or path-following mode are set (see below). Some character systems, such as certain kinds of vehicle control code, will also use the scenario altitude function.

Callable From:

• C++

diguyAltitudeFunction* diguyCharacter::get_altitude_function

(

)

Returns: current altitude function; see set_altitude_function()

Callable From:

• C++

int diguyCharacter::set_altitude_function_enabled_in_free_position_mode

(

int

enabled

)

This function sets whether the character's altitude function is enabled in free position mode.

Altitude functions are set by the functions set_altitude_function() or diguyScenario::set_default_character_altitude_function().

Parameters

enabled

pass 1 to enable, 0 to disable

Mode Effects:

• This function will not change the position mode.

Mode Restrictions:

• This function will only affect characters in free position mode.

Returns:

0 on success, -1 on failure

int diguyCharacter::get_altitude_function_enabled_in_free_position_mode

(

)

Returns: whether the character's altitude function is enabled in free position mode; see set_altitude_function_enabled_in_free_position_mode()

int diguyCharacter::set_altitude_function_enabled_in_path_position_mode

(

int

value

)

This function sets whether the character's altitude function is enabled in path position mode.

Altitude functions are set by the functions set_altitude_function() or diguyScenario::set_default_character_altitude_function().

Parameters

enabled

pass 1 to enable, 0 to disable

Mode Effects:

• This function will not change the position mode.

Mode Restrictions:

• This function will only affect characters in path position mode.

Returns:

0 on success, -1 on failure

int diguyCharacter::get_altitude_function_enabled_in_path_position_mode

(

)

Returns: whether the character's altitude function is enabled in path position mode; see set_altitude_function_enabled_in_path_position_mode()

int diguyCharacter::set_altitude_update_rate

(

int

update_rate

)

This function sets the altitude update rate of the character.

The default value for new characters is 100.

Note that characters that are load managed (get_is_load_managed() returns 1) have this parameter managed automatically. The corresponding function for load managed characters is diguyLoadManager::set_zone_altitude_update_rate().

Parameters

update_rate

percentage of scenario ticks for which altitude should update; can be between 1 and 100

Passing 100 means altitude will update every tick. Passing 50 means altitude will update every other tick.

Returns:

0 on success, -1 on failure

int diguyCharacter::get_altitude_update_rate

(

)

Returns: character's altitude update rate as set by set_altitude_update_rate()

void diguyCharacter::set_altitude_interpolation_rate

(

float

interpolation_rate

)

This function sets the altitude interpolation rate of the character.

This function only has an effect if the character's altitude function is enabled.

When the altitude function determines that the character's Z position should be updated to bring it closer to the ground, the altitude interpolation rate determines how quickly the Z height is adjusted.

The default value is 10.

Parameters

interpolation_rate

how much of the error will be made up each second

An interpolation_rate of 100 means that all error will be made up each frame.

float diguyCharacter::get_altitude_interpolation_rate

(

)

Returns: character's altitude update rate as set by set_altitude_interpolation_rate()

int diguyCharacter::get_pose_array_size

(

)

Returns the number of variables in this character's pose array.

See get_pose_in_radians() for an example of use.

Returns:

size of this character's pose array

int diguyCharacter::get_pose_in_radians

(

float *

pose_array

)

Fills an array of floats with the character's current joint angles.

Angles are expressed in radians. The size of the float array must be at least as large as that returned by get_pose_array_size().

Parameters

pose_array

an array of floats

Returns:

0 on success, -1 on failure

Callable From:

• C++

C++ Example:

diguyCharacter* ch = scenario->get_character_at_index(0);
float* pose_array;

// allocate a float array of the proper size
int n = ch->get_pose_array_size();
pose_array = new float[n];

// get the pose array
ch->get_pose_in_radians(pose_array);

diguyCharacterPoseOverride* diguyCharacter::create_pose_override

(

int

override_stage = 3

)

Creates and returns a pose override object.

The newly created pose override object is added to the character's previously created override objects, if any.

How the pose override interacts with other effects that affect the pose of the character depends on the override stage. See the section "Pose Override Stages" for a discussion of pose override stages.

Parameters

override_stage

the stage in the DI-Guy motion engine at which the override should be applied

Returns:

object of type diguyCharacterPoseOverride

int diguyCharacter::destroy_pose_override

(

diguyCharacterPoseOverride *

po

)

Destroys a pose override object, ending its influence on the character.

Parameters

po	pose override object to be destroyed

Returns:

0 on success, -1 on failure

int diguyCharacter::get_num_pose_overrides

(

)

Returns: the number of pose overrides belonging to this character.

diguyCharacterPoseOverride* diguyCharacter::get_pose_override_at_index

(

int

index

)

Returns: pointer of type diguyCharacterPoseOverride; NULL if no pose override at the specified index.

Parameters

index

index of the pose override; indices start at 0

diguyCharacterPoseOverride* diguyCharacter::create_complete_pose_override

(

)

Creates and returns a pose override object that completely overrides all other character pose operations, including motions, aiming, gazing, gestures, other pose overrides, etc.

The values set in the complete pose override object will be the values used to animate the character.

Having only one thing that affects a character's pose allows for much faster updating of the character.

There can only be one complete pose override object per character.

To remove the complete pose override, call destroy_complete_pose_override().

Returns:

object of type diguyCharacterPoseOverride

void diguyCharacter::destroy_complete_pose_override

(

)

Removes and destroys the complete pose override created by create_complete_pose_override().

int diguyCharacter::gaze_at_angle	(	float	azimuth,
		float	elevation,
		float	distance,
		int	is_new_gaze = 1
	)

This function sets the current azimuth, elevation, and distance of the character's gaze.

A fixed point in 3D space is then found using the two angles and the given distance from the DI-Guy coordinate system origin. Angles are given with respect to the DI-Guy coordinate system.

See set_position() for a description of the coordinate system.

Gazing will continue until end_gaze() is called.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

azimuth	rotation in degrees about up (vertical) axis; positive rotates to character's left
elevation	rotation in degrees about forward (horizontal) axis; positive rotates down
distance	distance in meters from the position of the character to the gaze target; positive values only, typically this is a large value (e.g. 10,000 meters)
is_new_gaze	set to 1 if this is a new gaze; set to 0 if this is continuing an already started gaze

Returns:

0 on success, -1 on failure

int diguyCharacter::gaze_at_angle_local	(	float	azimuth,
		float	elevation,
		float	distance = 10000.0f,
		int	is_new_gaze = 1
	)

This function is identical to gaze_at_angle() except that it uses body local coordinates for the character.

The angles are given with respect to the idealized position of the character. Use get_position() to learn the idealized position. The distance is between the idealized position of the character and the fixation point.

This function will have no effect on a dead character (see die_now() and get_dead()).

int diguyCharacter::gaze_at_point	(	float	tx,
		float	ty,
		float	tz,
		int	is_new_gaze = 1
	)

This function sets the current fixation point of the character's gaze.

Point coordinates are given in meters in the DI-Guy global coordinate system. The function uses default gaze behavior settings. Gazing will continue until end_gaze() is called.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

tx,ty,tz	position in meters from the DI-Guy global origin
is_new_gaze	set to 1 if this is a new gaze; set to 0 if this is continuing an already started gaze

Returns:

0 on success, -1 on failure

int diguyCharacter::gaze_at_point_local	(	float	tx,
		float	ty,
		float	tz,
		int	is_new_gaze = 1
	)

This function is identical to gaze_at_point() except that it uses body local coordinates for the character.

Use get_position() to learn the idealized position of the character if necessary.

This function will have no effect on a dead character (see die_now() and get_dead()).

int diguyCharacter::gaze_at_character	(	const char *	target_character_name,
		const char *	target_character_link_name = NULL,
		float	offset_tx = 0.0f,
		float	offset_ty = 0.0f,
		float	offset_tz = 0.0f
	)

This function effectively does a gaze_at_point() each tick.

The point to be gazed at is updated each tick to be the position of the specified link on the specified character.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

target_character_name	name of the character to be gazed at
target_character_link_name	link on the character that should be gazed at; pass NULL to gaze at the position link of the character
offset_tx,offset_ty,offset_tz	offset onto the link, in meters

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

C++ Example:

// gaze at the head of character "soldier-1".
ch->gaze_at_character("soldier-1",
    "cervical",
    0.0,
    0.0,
    0.0);

int diguyCharacter::get_gaze_is_active

(

)

Returns: 1 if the character is actively gazing, 0 if not.

int diguyCharacter::get_gaze_point	(	float *	x,
		float *	y,
		float *	z
	)

Returns: the current gaze point relative to the DI-Guy global coordinate system.

int diguyCharacter::get_gaze_is_acquired

(

)

A gaze is acquired if the final link in the gaze link chain has fully oriented toward the gaze target, even if other links in the gaze chain are still moving.

If the gaze is acquired, but any links in the gaze chain are still moving, the gaze is considered acquired but not steady (see get_gaze_is_steady().) If all links have reached a relatively steady state, the gaze is considered acquired and steady.

If either the acquired or steady status of a gaze has changed (e.g., was acquired but now is not, or was steady but now a link is moving), the diguyCharacter callback with callback_id CALLBACK_ID_GAZE_STATUS will be called.

Returns:

• 1 if the final link in the gaze can and has become oriented toward the gaze target
• 0 if not
• -1 on error

int diguyCharacter::get_gaze_is_steady

(

)

A gaze is steady if it is acquired, and if all links involved in the gaze have reached a steady state.

For example, since the eyes move faster than the neck, which moves faster than the back, it's possible for the gaze to be acquired (see get_gaze_is_acquired()) by the eyes as the neck and back are still moving. As the neck and back move into a more natural position, the eyes will not need to be turned as far to keep the gaze acquired.

If either the acquired or steady status of a gaze has changed (e.g., was acquired but now is not, or was steady but now a link is moving), the diguyCharacter callback with callback_id CALLBACK_ID_GAZE_STATUS will be called.

Returns:

• 1 if all links participating in the gaze have reached a relatively steady state
• 0 if not
• -1 on error

int diguyCharacter::end_gaze

(

)

This function removes the fixation target of an ongoing gaze, allowing the character to return to a non-gaze posture and behavior.

This effectively frees the character's posture to other influences.

int diguyCharacter::lpoint_at_angle	(	float	azimuth,
		float	elevation,
		float	distance,
		int	is_new_lpoint = 1,
		const char *	base_gesture_name = 0
	)

This function is similar to gaze_at_angle(), but sets the target of left pointing rather than gaze.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

azimuth	rotation in degrees about up (vertical) axis; positive rotates to character's left
elevation	rotation in degrees about forward (horizontal) axis; positive rotates down
distance	distance in meters from the position of the character to the lpoint target; positive values only
is_new_lpoint	set to 1 if this is a new lpoint; set to 0 if this is continuing an already started lpoint
base_gesture_name	the underlying gesture that should be used for motion of the arm; this is a placeholder argument for future functionality and should be set to NULL

int diguyCharacter::lpoint_at_angle_local	(	float	azimuth,
		float	elevation,
		float	distance = 10000.0f,
		int	is_new_lpoint = 1,
		const char *	base_gesture_name = 0
	)

This function is identical to gaze_at_local() except that it uses body local coordinates for the character.

Use get_position() to learn the idealized position of the character if necessary.

This function will have no effect on a dead character (see die_now() and get_dead()).

int diguyCharacter::lpoint_at_point	(	float	tx,
		float	ty,
		float	tz,
		int	is_new_lpoint = 1,
		const char *	base_gesture_name = 0
	)

This function sets the current fixation point for the character's left pointing.

Point coordinates are given in meters in the DI-Guy global coordinate system.

See set_position() for a description of the coordinate system.

Pointing will continue until end_lpoint() is called.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

tx,ty,tz	position in meters from the DI-Guy global origin of the lpoint target
is_new_gaze	set to 1 if this is a new lpoint; set to 0 if this is continuing an already started lpoint
base_gesture_name	the underlying gesture that should be used for motion of the arm; this is a placeholder argument for future functionality and should be set to NULL

Returns:

0 on success, -1 on failure

int diguyCharacter::lpoint_at_point_local	(	float	tx,
		float	ty,
		float	tz,
		int	is_new_lpoint = 1,
		const char *	base_gesture_name = 0
	)

This function is identical to lpoint_at_local() except that it uses body local coordinates for the character.

Use get_position() to learn the idealized position of the character if necessary.

This function will have no effect on a dead character (see die_now() and get_dead()).

int diguyCharacter::lpoint_at_character	(	const char *	target_character_name,
		const char *	target_character_link_name = NULL,
		float	offset_tx = 0.0f,
		float	offset_ty = 0.0f,
		float	offset_tz = 0.0f
	)

This function is identical to gaze_at_character(), but sets the target of left pointing rather than gaze.

This function will have no effect on a dead character (see die_now() and get_dead()).

int diguyCharacter::get_lpoint_point	(	float *	x,
		float *	y,
		float *	z
	)

Returns: the current lpoint target point relative to the DI-Guy global coordinate system.

const char* diguyCharacter::get_lpoint_base_gesture_name

(

)

Returns: the current base gesture of the lpoint.

int diguyCharacter::get_lpoint_is_active

(

)

Returns: 1 if the character is actively lpointing, 0 if not.

int diguyCharacter::get_lpoint_is_acquired

(

)

Returns: 1 if the final link in the lpoint can and has become oriented toward the lpoint target; 0 if not; -1 on error.

int diguyCharacter::get_lpoint_is_steady

(

)

Returns: 1 if all links participating in the lpoint have reached a relatively steady state; 0 if not; -1 on error.

int diguyCharacter::end_lpoint

(

)

This function removes the fixation target of an ongoing lpoint, allowing the character to return to a non-point posture and behavior.

This effectively frees the character's posture to other influences.

int diguyCharacter::set_gaze_params_to_defaults

(

)

This function sets all gaze control parameters back to their default settings.

This undoes modifications to gaze control parameters made by the following calls:

• set_gaze_param_desired_locate_time()
• set_gaze_link_uses_desired_locate_time()
• set_gaze_link_azimuth_limits()
• set_gaze_link_elevation_limits()
• set_gaze_link_azimuth_tolerance()
• set_gaze_link_elevation_tolerance()
• set_gaze_link_max_angular_vel()
• set_gaze_link_scale_factor()

Returns:

0 on success, -1 on failure

int diguyCharacter::set_gaze_param_desired_locate_time

(

float

t

)

This function sets the desired amount of time in seconds it will take for the gaze or point target to be acquired.

Having a desired locate time effectively limits how fast links in the gaze chain can turn; they will turn as fast as it takes for them to arrive at their proper values, or as fast as their maximum angular velocity, whichever is longer.

The use of desired locate time can be turned on and off on a link by link bases using the function set_gaze_link_uses_desired_locate_time().

This value is only a guideline and may be overridden on a link by link basis during the actual gaze, as links try not to exceed their maximum angular velocities.

The default locate time is 1.0 seconds.

Parameters

t	lower value results in faster turning rate

Returns:

0 on success, -1 on failure

float diguyCharacter::get_gaze_param_desired_locate_time

(

)

Returns: the most recent setting of set_gaze_param_desired_locate_time()

int diguyCharacter::set_gaze_link_uses_desired_locate_time	(	const char *	link_name,
		int	uses_desired_locate_time
	)

This function sets whether the specified link will pay attention to the desired locate time (as set by set_gaze_param_desired_locate_time()), or whether the link turns as fast as its maximum angular velocity allows (as set by set_gaze_link_max_angular_vel()).

Note that if this value is set to 1, the link still pays attention to its maximum angular velocity as an upper limit on how fast it can turn.

Valid link names and defaults:

Parameters

orientation	1
back	1
cervical	1
eye_l	0
shoulder_l	1
elbow_l	1
link_name	name of the link
uses_desired_locate_time	1 to use desired locate time, 0 to disregard

Returns:

0 on success, -1 on failure

int diguyCharacter::get_gaze_link_uses_desired_locate_time

(

const char *

link_name

)

Returns: the most recent setting of set_gaze_link_uses_desired_locate_time()

int diguyCharacter::set_gaze_link_azimuth_limits	(	const char *	link_name,
		float	min,
		float	max
	)

This function sets the maximum amount the character can turn the specified link horizontally in pursuit of a gaze or point target.

Valid link names and defaults:

Parameters

back	-45 to 45
cervical	-80 to 80
eye_l	-50 to 50
shoulder_l	-30 to 135
elbow_l	-30 to 10
link_name	name of the link
min	value <= 0; in degrees
max	value >= 0; in degrees

Returns:

0 on success, -1 on failure

int diguyCharacter::get_gaze_link_azimuth_limits	(	const char *	link_name,
		float *	min,
		float *	max
	)

Returns: the most recent setting of set_gaze_link_azimuth_max()

int diguyCharacter::set_gaze_link_elevation_limits	(	const char *	link_name,
		float	min,
		float	max
	)

This function sets the maximum amount the character can turn the specified link vertically in pursuit of a gaze or point target.

Valid link names and defaults:

Parameters

back	-15 to 45
cervical	-80 to 45
eye_l	-40 to 40
shoulder_l	-80 to 80
elbow_l	-170 to 0
link_name	name of the link
min	value <= 0; in degrees
max	value >= 0; in degrees

Returns:

0 on success, -1 on failure

int diguyCharacter::get_gaze_link_elevation_limits	(	const char *	link_name,
		float *	min,
		float *	max
	)

Returns: the most recent setting of set_gaze_link_elevation_max()

int diguyCharacter::set_gaze_link_azimuth_tolerance	(	const char *	link_name,
		float	min,
		float	max
	)

This function sets how much difference there can be between the link's current horizontal orientation and the gaze or point target before the link begins to turn to acquire the gaze or point target.

The combination of this function and set_gaze_link_scale_factor() determine how close the link will turn toward the gaze or point target.

With a looser (higher) tolerance the link will not turn as much toward the target. With a tighter (lower) tolerance the link will turn more toward the target.

Valid link names and defaults:

Parameters

orientation	-30 to 30
back	-45 to 45
cervical	-5 to 5
eye_l	-1 to 1
shoulder_l	-5 to 5
elbow_l	-5 to 5
link_name	name of the link
min	value <= 0; in degrees
max	value >= 0; in degrees

Returns:

0 on success, -1 on failure

int diguyCharacter::get_gaze_link_azimuth_tolerance	(	const char *	link_name,
		float *	min,
		float *	max
	)

Returns: the most recent setting of set_gaze_link_azimuth_max()

int diguyCharacter::set_gaze_link_elevation_tolerance	(	const char *	link_name,
		float	min,
		float	max
	)

The elevation equivalent of set_gaze_link_azimuth_tolerance(),.

Valid link names and defaults:

Parameters

orientation	-90 to 90
back	-45 to 45
cervical	-5 to 5
eye_l	-1 to 1
shoulder_l	-5 to 5
elbow_l	-5 to 5
link_name	name of the link
min	value <= 0; in degrees
max	value >= 0; in degrees

Returns:

0 on success, -1 on failure

int diguyCharacter::get_gaze_link_elevation_tolerance	(	const char *	link_name,
		float *	min,
		float *	max
	)

Returns: the most recent setting of set_gaze_link_elevation_max()

int diguyCharacter::set_gaze_link_max_angular_vel	(	const char *	link_name,
		float	angular_vel
	)

This function sets the maximum angular velocity that the back link angles may attain in pursuit of a gaze or point target.

Valid link names and defaults:

Parameters

back	30 deg/s
cervical	60 deg/s
eye_l	180 deg/s
shoulder_l	180 deg/s
elbow_l	180 deg/s
link_name	name of the link
angular_vel	angular velocity in degrees per second

Returns:

0 on success, -1 on failure

int diguyCharacter::get_gaze_link_max_angular_vel	(	const char *	link_name,
		float *	angular_vel
	)

Returns: the most recent setting of set_gaze_link_max_angular_vel()

int diguyCharacter::set_gaze_link_scale_factor	(	const char *	link_name,
		float	scale_factor
	)

This function sets how much the link will make up the difference toward the gaze or point target.

The combination of this function and the tolerances determine how close the link will turn toward the gaze or point target.

With a smaller scale factor the link will not turn as much toward the target. With a higher scale factor the link will turn more toward the target.

For example, if the gaze or point target is at 60 degrees yaw in back coordinates and the scale factor is 0.5, the back will turn 30 degrees in pursuit of the target.

Valid link names and defaults:

Parameters

back	0.75
cervical	0.5
eye_l	1.0
shoulder_l	0.9
elbow_l	1.0
link_name	name of the link
scale_factor	scale factor between 0 and 1

Returns:

0 on success, -1 on failure

int diguyCharacter::get_gaze_link_scale_factor	(	const char *	link_name,
		float *	scale_factor
	)

Returns: the most recent setting of set_gaze_link_scale_factor()

int diguyCharacter::set_link_enabled_for_gaze	(	const char *	link_name,
		int	enabled
	)

This function sets whether the character can turn the specified link in pursuit of the gaze target.

Valid link names and defaults:

Parameters

orientation	0
back	1
cervical	1
eye_l	1 if character has movable eyes, else 0
shoulder_l	0
elbow_l	0
link_name	name of the link
enabled	1 to enable, 0 to disable

Returns:

0 on success, -1 on failure

int diguyCharacter::get_link_enabled_for_gaze

(

const char *

link_name

)

Returns: the most recent setting of set_link_enabled_for_gaze()

int diguyCharacter::set_gaze_can_change_posture

(

int

enabled

)

This function sets whether the character can change its current posture in pursuit of the gaze target.

Gaze can change current posture by default.

Parameters

enabled

1 to enable, 0 to disable

Returns:

0 on success, -1 on failure

int diguyCharacter::get_gaze_can_change_posture

(

)

Returns: the most recent setting of set_gaze_can_change_posture()

int diguyCharacter::set_gaze_can_change_variant

(

int

enabled

)

This function sets whether the character can change its current variant in pursuit of the gaze target.

Gaze can change current variant by default.

Parameters

enabled

1 to enable, 0 to disable

Returns:

0 on success, -1 on failure

int diguyCharacter::get_gaze_can_change_variant

(

)

Returns: the most recent setting of set_gaze_can_change_variant()

int diguyCharacter::set_link_enabled_for_lpoint	(	const char *	link_name,
		int	enabled
	)

This function sets whether the character can move the specified link in pursuit of the lpoint target.

Valid link names and defaults:

Parameters

orientation	0
back	1
cervical	0
eye_l	0
shoulder_l	1
elbow_l	1
link_name	name of the link
enabled	1 to enable, 0 to disable

Returns:

0 on success, -1 on failure

int diguyCharacter::get_link_enabled_for_lpoint

(

const char *

link_name

)

Returns: the most recent setting of set_link_enabled_for_lpoint()

int diguyCharacter::set_nod	(	float	azimuth,
		float	elevation,
		float	duration = 0.5f
	)

This function adjusts the current azimuth and elevation offsets of the character's head.

If a gaze is ongoing, then the nod will be supplemented to the gazing, and the character will attempt to maintain its gaze.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

azimuth	rotation offset about z (vertical) axis, in degrees; positive rotates to character's left
elevation	rotation offset about y (horizontal) axis, in degrees; positive rotates down
duration	how long it should take to attain the new azimuth and elevation

Returns:

0 on success, -1 on failure

int diguyCharacter::nod_head	(	float	duration,
		float	nod_count,
		float	nod_elevation0 = 15.0f,
		float	nod_elevation1 = 0.0f,
		float	nod_elevation_out = 0.0f
	)

This function causes the character to nod its head for the specified number of times over the specified duration.

If nod_count is 0.5, the elevation of the head will move from its current elevation straight to nod_elevation_out. The arguments nod_elevation0 and nod_elevation1 will be ignored.

If nod_count is 1.0, the elevation of the head will move from its current elevation to nod_elevation0, then to nod_elevation_out. The argument nod_elevation1 will be ignored.

If nod_count is 1.5 or greater, the nod elevation will begin at its current elevation, move to nod_elevation0, then alternate between nod_elevation0 and nod_elevation1, before finally ending at nod_elevation_out.

The head will maintain an elevation offset of nod_elevation_out until a new call to nod_head() or set_nod() is made.

This function overrides any nod settings made by the set_nod() function.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

duration	for how long the nod should be executed
nod_count	how many nods the character should perform; this will be rounded to the nearest multiple of 0.5
nod_elevation0	elevation of initial nod in degrees
nod_elevation1	elevation of return nod in degrees
nod_elevation_out	ending elevation when nod is complete

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::shake_head	(	float	duration,
		float	shake_count,
		float	shake_azimuth0 = -20.0f,
		float	shake_azimuth1 = 20.0f,
		float	shake_azimuth_out = 0.0f
	)

This function is similar to nod_head(), except the direction of head movement is side to side rather than up and down.

See the nod_head() function for a detailed description of usage.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

duration	for how long the shake should be executed
shake_count	how shakes the character should perform; this will be rounded to the nearest multiple of 0.5
shake_azimuth0	azimuth of initial shake in degrees
shake_azimuth1	azimuth of return shake in degrees
shake_azimuth_out	ending azimuth when shake is complete

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

float diguyCharacter::get_nod_azimuth

(

)

Returns: current nod azimuth setting; see set_nod(), nod_head(), and shake_head()

float diguyCharacter::get_nod_elevation

(

)

Returns: current nod elevation setting; see set_nod(), nod_head(), and shake_head()

int diguyCharacter::set_aim	(	float	azimuth,
		float	elevation
	)

This function sets the current desired azimuth and elevation of the character's aim.

The angles are in character-local coordinates. Zero values mean straight ahead and level. Aiming will continue until end_aim() is called.

This function effectively calls aim_at_angle_local(), with a distance of 10000 meters, and is_new_aim set to 1.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

azimuth	rotation about z (vertical) axis, in degrees; positive rotates to character's left
elevation	rotation about y (horizontal) axis, in degrees; positive rotates down

Returns:

0 on success, -1 on failure

int diguyCharacter::aim_at_angle	(	float	azimuth,
		float	elevation,
		float	distance,
		int	is_new_aim = 1
	)

This function sets the current azimuth, elevation, and distance of the character's aim.

A fixed point in 3D space is then found using the two angles and the given distance from the character's idealized position. Angles are given with respect to the DI-Guy global coordinate system.

See set_position() for a description of the coordinate system.

Aiming will continue until end_aim() is called.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

azimuth	rotation in degrees about up (vertical) axis; positive rotates to the character's left; zero means in the direction of the positive X axis of the Boston Dynamics coordinate system
elevation	rotation in degrees about horizontal axis; positive rotates down
distance	distance in meters from the idealized position of the character to the aim target; positive values only, typically this is a large value (e.g. 10,000 meters)
is_new_aim	set to 1 if this is a new aim, for jumping to a new target; set to 0 if this is continuing an already started aim, for tracking an existing target

Returns:

0 on success, -1 on failure

int diguyCharacter::aim_at_angle_local	(	float	azimuth,
		float	elevation,
		float	distance,
		int	is_new_aim = 1
	)

This function is identical to aim_at_angle() except that it uses body local coordinates for the character.

The angles are given with respect to the idealized position of the character. Use get_position() to learn the idealized position. The distance is between the idealized position of the character and the fixation point. Aiming will continue until end_aim() is called.

This function will have no effect on a dead character (see die_now() and get_dead()).

int diguyCharacter::aim_at_point	(	float	x,
		float	y,
		float	z,
		int	is_new_aim = 1
	)

This function sets the current fixation point of the character's aim.

Point coordinates are given in meters in the DI-Guy global coordinate system.

The function uses default aim behavior settings. Aiming will continue until end_aim() is called.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

tx,ty,tz	position in meters from the DI-Guy global origin
is_new_aim	set to 1 if this is a new aim; set to 0 if this is continuing an already started aim

Returns:

0 on success, -1 on failure

int diguyCharacter::aim_at_point_local	(	float	x,
		float	y,
		float	z,
		int	is_new_aim = 1
	)

This function is identical to aim_at_point() except that it uses body local coordinates for the character.

Use get_position() to learn the idealized position of the character if necessary.

This function will have no effect on a dead character (see die_now() and get_dead()).

int diguyCharacter::aim_at_character	(	const char *	target_character_name,
		const char *	target_character_link_name = NULL,
		float	offset_tx = 0.0f,
		float	offset_ty = 0.0f,
		float	offset_tz = 0.0f
	)

This function effectively does an aim_at_point() each tick.

The point to be aimed at is updated each tick to be the position of the specified link on the specified character.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

target_character_name	name of the character to be aimed at
target_character_link_name	link on the character that should be aimed at; pass NULL or "" to aim at the position link of the character. If NULL is passed, a function will make best effort to a choose a character-appropriate link a to target.
offset_tx,offset_ty,offset_tz	offset onto the link, in meters

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

C++ Example:

// aim at the head of character "soldier-1".
ch->aim_at_character("soldier-1",
    "cervical",
    0.0,
    0.0,
    0.0);

void diguyCharacter::end_aim

(

)

This function terminates aiming started by the set_aim(), aim_at_point(), aim_at_point_local(), aim_at_angle(), aim_at_angle_local(), and aim_at_character() functions.

const char* diguyCharacter::get_aim_at_character

(

)

See aim_at_character()

float diguyCharacter::get_aim_azimuth

(

)

Returns: current aim azimuth; see set_aim()

float diguyCharacter::get_aim_elevation

(

)

Returns: current aim elevation; see set_aim()

int diguyCharacter::get_aim_trajectory	(	float *	muzzle_x,
		float *	muzzle_y,
		float *	muzzle_z,
		float *	far_x,
		float *	far_y,
		float *	far_z
	)

Returns: 1 if the character is aiming 0 if not.

Parameters

muzzle_x,muzzle_y,muzzle_z	position of muzzle in meters from the origin
far_x,far_y,far_z	position of end target in meters from the origin

Pass NULL for any values that are not needed. **

Note

values will be zero if the character isn't currently aiming

int diguyCharacter::get_aim_is_possible

(

)

Not all actions of a character will be affected by aim commands.

This function returns 1 if this character is currently in an aim-able action.

Returns:

1 if current action is aim-able; 0 if not

int diguyCharacter::get_aim_is_acquired

(

)

Returns: 1 if the aim is acquired, 0 if not.

int diguyCharacter::get_aim_is_steady

(

)

Returns: 1 if all links participating in the aim have reached a relatively steady state, 0 if not, -1 on error.

int diguyCharacter::get_is_aiming

(

)

Returns: 1 if character is currently aiming, 0 if not.

void diguyCharacter::set_aim_param_acquire_factor

(

float

factor

)

This function sets the steady-state factor that is used once an aim is no longer considered "new".

See the function set_aim_param_new_aim_duration() for information on when an aim is considered new, and how the effective acquire is calculated from this steady-state acquire factor and the new aim factor.

Parameters

factor

unitless value between 0 and 1; default is 0.6

float diguyCharacter::get_aim_param_acquire_factor

(

)

Returns: the current aim acquire factor parameter.

void diguyCharacter::set_aim_param_new_aim_factor

(

float

factor

)

This function sets the factor that is used when an aim is considered new.

See the function set_aim_param_new_aim_duration() for information on when an aim is considered new, and how the effective acquire is calculated from this new aim factor and the steady-state acquire factor.

Parameters

factor

unitless value between 0 and 1; default is 0.05

float diguyCharacter::get_aim_param_new_aim_factor

(

)

Returns: the current new aim factor parameter.

void diguyCharacter::set_aim_param_new_aim_duration

(

float

duration

)

This function sets how long an aim is considered "new".

When an aim is brand-new, the effective acquire factor is equal to the new aim factor as set by set_aim_param_new_aim_factor(). When the new aim duration has expired, the effective acquire factor is equal to the steady-state acquire factor as set by set_aim_param_acquire_factor(). In between, the effective acquire factor moves smoothly between the two.

For example, say that the new aim factor is 0.1, the acquire factor is 0.5, and the new aim duration is 0.2 seconds. If a new aim is started, say by a call to aim_at_angle_local(), the effective acquire factor of the first frame will be 0.1. Over the next 0.2 seconds, the effective acquire factor will smoothly ramp up to 0.5, where it will stay until the aim is acquired.

Parameters

duration

how long, in seconds, a new aim should be considered new; default is 1 second

float diguyCharacter::get_aim_param_new_aim_duration

(

)

Returns: how long, in seconds, a new aim is considered new.

void diguyCharacter::set_aim_param_max_per_frame_adj_factor

(

float

factor

)

This function sets the maximum factor that can be used for any single frame for aim convergence attempts.

See set_aim_param_acquire_factor() for a discussion of why setting this too close to 1 is not recommended.

Parameters

factor

unitless value between 0 and 1; default is 0.95

float diguyCharacter::get_aim_param_max_per_frame_adj_factor

(

)

Returns: the maximum per-frame adjustment factor parameter.

void diguyCharacter::set_aim_param_azimuth_acquired_range

(

float

range

)

This function sets how close the current aim azimuth must be to the desired aim azimuth in order for the aim to be considered acquired.

Note that the aim isn't fully acquired until both azimuth and elevation are acquired.

Setting this value too close to 0 will result in the aim never being acquired.

Parameters

range

how close, in degrees, the azimuth must be for the aim to be acquired; default is 0.5 degrees

float diguyCharacter::get_aim_param_azimuth_acquired_range

(

)

Returns: how close, in degrees, the azimuth must be for the aim to be acquired.

void diguyCharacter::set_aim_param_elevation_acquired_range

(

float

range

)

This function sets how close the current aim elevation must be to the desired aim elevation in order for the aim to be considered acquired.

Note that the aim isn't fully acquired until both azimuth and elevation are acquired.

Setting this value too close to 0 will result in the aim never being acquired.

Parameters

range

how close, in degrees, the elevation must be for the aim to be acquired; default is 1.0 degrees

float diguyCharacter::get_aim_param_elevation_acquired_range

(

)

Returns: how close, in degrees, the elevation must be for the aim to be acquired.

void diguyCharacter::set_aim_converge_every_frame

(

int

enabled

)

This function attempts to have the character reach its desired aim angles instantly, every frame.

Set enabled to 0 to disable instant aim convergence.

int diguyCharacter::get_aim_converge_every_frame

(

)

Returns: 0 if instant convergence is disabled, 1 if enabled.

const char* diguyCharacter::get_aim_at_link

(

)

Returns: Name of a reasonable link that other characters could aim at.

int diguyCharacter::get_aim_at_link_offset	(	float *	offset_x,
		float *	offset_y,
		float *	offset_z
	)

Returns: xyz offset from link returned by get_aim_at_link()

const char* diguyCharacter::get_gaze_at_link

(

)

Returns: Name of a reasonable link that other characters could look at.

int diguyCharacter::get_gaze_at_link_offset	(	float *	offset_x,
		float *	offset_y,
		float *	offset_z
	)

Returns: xyz offset from link returned by get_gaze_at_link()

int diguyCharacter::fire_weapon

(

diguyMuzzle

muzzle = DIGUY_MUZZLE_DEFAULT

)

This function causes a character to fire his weapon.

Different weapons have different "munition types", which specify, among other things, the sound to be played, the network info to be sent, and muzzle flash effect. See get_weapon_muzzle_munition_type() for more information on munition types.

If the weapon fires live rounds (as set by set_weapon_fires_live_rounds()) this function also computes a bullet trajectory, perhaps hitting and killing another character.

This function will have no effect on a dead character (see die_now() and get_dead()).

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::fire_weapon_n_times	(	int	count,
		float	dt = 0.2f,
		const char *	override_sound_name = NULL,
		diguyMuzzle	muzzle = DIGUY_MUZZLE_DEFAULT
	)

This function causes a character to fire his weapon the specified number of times.

This causes a muzzle flash and the weapon's sound (if any) to be played.

The sound played will be one of, in order:

• the passed override_sound_name, or
• the sound set by set_weapon_sound_override(), or

• the default weapon sound based on the character's appearance

  If the weapon fires live rounds (as set by set_weapon_fires_live_rounds()), this function also computes a trajectory for each round, perhaps hitting and killing another character.

  This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

count	number of times weapon should be fired
override_sound_name	override sound to be played
dt	time between firings if count > 1
muzzle	muzzle on which flash should appear

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::fire_screen_space_bullet	(	diguyView *	view,
		float	x,
		float	y
	)

Fires a bullet at point (x, y) from the camera, using this character as the attacker.

Currently OpenGL only.

This function will have no effect on a dead character (see die_now() and get_dead()).

Returns:

number of hits

int diguyCharacter::get_weapon_fire_count

(

diguyMuzzle

muzzle = DIGUY_MUZZLE_DEFAULT

)

Returns: number of times weapon has been fired from specified muzzle.

Available as Decision Bead/Event

int diguyCharacter::set_default_weapon_muzzle

(

diguyMuzzle

muzzle

)

This function sets the default muzzle that will flash when the character fires its weapon due to a call to fire_weapon() or fire_weapon_n_times().

The default value is DIGUY_MUZZLE_DEFAULT.

Parameters

muzzle

the muzzle that will flash; muzzle 1 is common

Returns:

0 on success, -1 on failure

diguyMuzzle diguyCharacter::get_default_weapon_muzzle

(

)

Returns: current default weapon muzzle that flashes when the character's weapon is fired; see set_default_weapon_muzzle()

const char* diguyCharacter::get_weapon_muzzle_munition_type

(

diguyMuzzle

muzzle

)

When the character fires its weapon, the results depend on the munition type of the muzzle fired from.

Munition types specify, among other things:

• sound played
• muzzle flash effect
• network data sent (DIS septet)
• detonation effect
• detonation radius

• etc.

  Default munition types for the each muzzle are set automatically when the character's appearance is set. The munition type of the weapon can be overridden by calling set_weapon_munition_type_override().

  Current munition types include:

• m16
• m4
• m60
• m240
• m249
• m9
• hand_gun
• 50cal
• m256
• ak47
• pk74
• dragunov
• sa80
• rpg
• m203
• 40mm_hedp
• javelin
• stinger
• at4
• sa7
• molotov_cocktail
• 60mm_mortar
• 82mm_mortar
• 155mm_artillery
• IED_mortar
• VBIED
• m242
• 120mm
• 125mm
• ced
• pepper_spray

Returns:

munition type of specified muzzle

const char* diguyCharacter::get_default_muzzle_munition_type

(

)

Returns: munition type of default muzzle, as set by set_default_weapon_muzzle()

int diguyCharacter::set_weapon_munition_type_override

(

const char *

munition_type

)

This function allows the default munition type to be overridden.

The default value is NULL (don't override default munition type).

Parameters

munition_type

name of a munition type

Returns:

0 on success, -1 on failure

const char* diguyCharacter::get_weapon_munition_type_override

(

)

Returns: current munition type override in effect, or NULL if none;.

int diguyCharacter::set_weapon_fires_live_rounds

(

int

weapon_fires_live_rounds

)

This function sets whether the character's weapons fire live rounds.

If so, when fire_weapon() and fire_weapon_n_times() are called the trajectory of the bullet will be calculated and checked against characters in the scenario.

The default value is 1.

Parameters

weapon_fires_live_rounds

set to 1 for live rounds; set to 0 for "blanks"

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::get_weapon_fires_live_rounds

(

)

Returns: current setting of whether weapon fires live rounds or blanks; see set_weapon_fires_live_rounds()

Available as Decision Bead/Event

int diguyCharacter::set_weapon_sound_override

(

const char *

sound_name

)

A weapon sound is played when the character fires its weapon due to a call to fire_weapon() or fire_weapon_n_times().

The sound that is played is generally derived from the weapon's munition type, which can be different for each muzzle.

This function overrides the default sound that will be played. Note that this overrides the sound for all muzzles.

The default value is NULL (don't override default sound).

To not play a sound at all, set the weapon sound gain override to 0.

Parameters

sound

name of a sound defined in the scenario; pass NULL to specify that default should be played

Returns:

0 on success, -1 on failure

const char* diguyCharacter::get_weapon_sound_override

(

)

The function returns the current weapon sound override, if one is set; see set_weapon_sound_override().

This function will not return NULL. The empty string ("") is returned if a weapon sound override is not set.

Returns:

name of weapon sound override

int diguyCharacter::set_weapon_sound_gain_override

(

float

gain

)

This function overrides the default gain on the sound played due to a call to fire_weapon() or fire_weapon_n_times().

Pass 1.0 to use the sound's default amplitude. Lower numbers decrease volume, higher numbers increase volume.

Pass 0.0 to completely disable playing of weapon sound.

The default value is 3.0.

See set_weapon_sound_override().

Parameters

sound_gain

amount by which to change sound volume

Returns:

0 on success, -1 on failure

float diguyCharacter::get_weapon_sound_gain_override

(

)

Returns: current override gain for weapon sound.

void diguyCharacter::set_weapon_spread

(

float

spread

)

This function provides aiming assistance by making it possible for roughly-aimed weapons to hit targets.

When spread is nonzero, fire_weapon searches for a target within a conical space centered on the muzzle. Within this cone, the live character within weapon range, and with the smallest angular deviation from the weapon, is chosen, by default, as the target. Other function calls may alter this aiming behavior, making it aim only at enemy targets, for example, or making it prefer close targets to far ones.

Parameters

spread

angular deviation from weapon muzzle within which a target will be found

Spread values above 145 are suicidal (character can shoot himself). 90 is the highest sensible value, which covers everything ahead of the weapon muzzle. A value of 0 is the default, meaning that only targets in line with the muzzle are hit.

void diguyCharacter::set_weapon_near_range

(

float

near_range

)

This function affects how targets are chosen when the character's weapon_spread is nonzero.

Only characters more than near_range meters away from the muzzle will be fired upon. Characters which are closer than near_range meters will not be fired upon.

This value does not affect weapon behavior when weapon_spread is zero.

If this function is never called for a character, it is as if the function had been called with a value of zero.

Parameters

near_range

distance closer than which no character will be targeted

void diguyCharacter::set_weapon_far_range

(

float

far_range

)

This function sets the range of the character's weapon.

If this function is never called for a character, it is as if the function had been called with a value of 500.0.

Parameters

far_range

range of the weapon in meters

void diguyCharacter::set_weapon_hit_ratio

(

float

hit_ratio

)

This function sets a weapon's ratio of hits to fired rounds.

A value of 1.0 (the default) means the weapon will hit everything it is aimed at. Values less than 1.0 cause the weapon to probabilistically miss targets, even when perfectly aimed at them. A value of zero means the weapon doesn't hit anything, even if it is perfectly aimed. A value of 0.5 will hit half of the time.

void diguyCharacter::set_weapon_max_impacts

(

int

val

)

This function sets the number of potential impacts a fired round can have.

The default is 1. Specifying more than 1 means the round will completely go through objects, triggering a CALLBACK_ID_IMPACT callback each time, until the maximum number of impacts has been reached.

int diguyCharacter::get_accessory1_state

(

)

Returns: state of accessory1.

int diguyCharacter::get_rifle_state

(

)

Returns: state of the character's rifle.

int diguyCharacter::set_weapon_projectile_is_visible	(	diguyMuzzle	muzzle,
		int	is_visible
	)

This function sets whether the projectiles of certain appearances' weapons (such as rocket launchers and RPGs) are visible.

Note that most weapons do not have visible projectiles and this function will therefore have no effect.

Parameters

muzzle	which muzzle's projectile should be shown/hidden
is_visible	pass 1 to show, pass 0 to hide

Returns:

0 on success, -1 on failure

int diguyCharacter::get_weapon_projectile_is_visible

(

diguyMuzzle

muzzle

)

This function returns the most recent setting of set_weapon_projectile_is_visible().

Parameters

muzzle

which muzzle's projectile should be queried

Returns:

1 if visible, 0 if not

int diguyCharacter::get_weapon_aim_vector	(	float *	muzzle_tx,
		float *	muzzle_ty,
		float *	muzzle_tz,
		float *	end_pt_tx = NULL,
		float *	end_pt_ty = NULL,
		float *	end_pt_tz = NULL,
		float *	muzzle_rz = NULL,
		float *	muzzle_rx = NULL,
		float *	muzzle_ry = NULL,
		int	in_character_local_coordinates = 0,
		diguyMuzzle	muzzle = DIGUY_MUZZLE_DEFAULT
	)

Retrieves the position and direction of the character's weapon.

Parameters

muzzle_tx,muzzle_ty,muzzle_tz	muzzle position, and beginning of aim vector
end_pt_tx,end_pt_ty,end_pt_tz	end point of aim vector
muzzle_rz,muzzle_rx,muzzle_ry	orientation of muzzle in degrees
muzzle	the muzzle for which the aim vector is needed
in_character_local_coordinates	pass 0 for values in world
coordinates	(the default), 1 for values in character local coordinates

The muzzle position and end point are in meters from the origin (if using world coordinates) or in meters from the character's position (if using character-local coordinates).

The distance of the end point from the muzzle position should be the weapon's far range, set by set_weapon_far_range().

Pass NULL for any values that are not needed.

Note: The muzzle argument is currently not used, and is present for future implementation.

Returns:

0 on success, -1 on failure

const char* diguyCharacter::get_muzzle_link

(

diguyMuzzle

muzzle = DIGUY_MUZZLE_DEFAULT

)

This function returns the link the passed muzzle is associated with.

For example, soldier rifle muzzles are attached to the "rifle_joint" link.

Call get_muzzle_offset() to get the offset of the muzzle on this link.

Parameters

muzzle

muzzle of interest

Returns:

name of link, or NULL if the character doesn't have the specified muzzle

int diguyCharacter::get_muzzle_offset	(	diguyMuzzle	muzzle = DIGUY_MUZZLE_DEFAULT,
		float *	offset_x = NULL,
		float *	offset_y = NULL,
		float *	offset_z = NULL
	)

This function returns the offset of the muzzle from the link it is attached to as returned by get_muzzle_link().

Parameters

muzzle	muzzle of interest
offset_x,offset_y,offset_z	variables in which to return results

Returns:

0 on success, -1 on failure

int diguyCharacter::set_weapon_max_azimuth_error

(

float

h_error

)

This function sets the highest horizontal error possible when the weapon is fired.

If non-0, a random horizontal error angle will be computed and added to the weapon's horizontal aim angle.

Parameters

h_error

highest possible horizontal error

Returns:

0 on success, -1 on failure

float diguyCharacter::get_weapon_max_azimuth_error

(

)

Returns: maximum horizontal aim error.

int diguyCharacter::set_weapon_max_elevation_error

(

float

v_error

)

Similar to set_weapon_max_azimuth_error(), but for vertical aim.

float diguyCharacter::get_weapon_max_elevation_error

(

)

Returns: maximum vertical aim error.

int diguyCharacter::set_weapon_tracers_enabled

(

int

enabled

)

This function sets whether tracer effects will be shown when the weapon is fired.

Not all weapons will support this effect.

Parameters

enabled

pass 1 to enable, 0 to disable

Returns:

0 on success, -1 on failure

int diguyCharacter::get_weapon_tracers_enabled

(

)

Returns: 1 if tracer effect is enabled, 0 if not.

int diguyCharacter::get_weapon_rounds_until_tracer

(

diguyMuzzle

muzzle

)

Returns: number of rounds until next tracer.

int diguyCharacter::set_weapon_shell_eject_enabled

(

int

enabled

)

This function sets whether a shell eject effect will be shown when the weapon is fired.

Not all weapons will support this effect.

Parameters

enabled

pass 1 to enable, 0 to disable

Returns:

0 on success, -1 on failure

int diguyCharacter::get_weapon_shell_eject_enabled

(

)

Returns: 1 if shell eject effect is enabled, 0 if not.

int diguyCharacter::set_weapon_smoke_enabled

(

int

enabled

)

This function sets whether a smoke effect will be shown when the weapon is fired.

Not all weapons will support this effect.

Parameters

enabled

pass 1 to enable, 0 to disable

Returns:

0 on success, -1 on failure

int diguyCharacter::get_weapon_smoke_enabled

(

)

Returns: 1 if muzzle smoke effect is enabled, 0 if not.

int diguyCharacter::trigger_detonation_on_character	(	const char *	munition_name,
		const char *	attacker_name = NULL,
		float	radius_override = -1.0f,
		int	broadcast_on_network = 1
	)

Similar to diguyScenario::trigger_detonation(), but detonation occurs at character's position.

Parameters

munition_name	name of the munition to detonate
attacker_name	this MUST be specified if the detonation is being broadcast over the network
radius_override	defaults to the data in the munition config file
broadcast_on_network	pass 0 to not broadcast detonation on DIS network

**

Note

Overriding the detonation radius will NOT work on broadcast detonations since the override value is not transmitted.

int diguyCharacter::set_face_expression	(	const char *	facex_name,
		float	blend_duration,
		float	strength = 1.0f
	)

This function changes the face of the character to reflect the specified user-defined named facial expression.

Currently affects only "facefx" appearances.

Parameters

facex_name	name of face expression to be applied
blend_duration	how long (in seconds) to take to change the face
strength	a multiplier between 0 and 1 on the expression

Face expressions available by default in new scenarios are:

• Neutral
• Smile_cl
• Trust
• Sad
• Mad
• Distrust
• Conniving
• Smile
• BrowsDown
• BrowsUp

New face expressions can be added using the diguyScenario::create_face_expression() function.

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

C++ Example:

diguyCharacter* ch = scenario->get_character_at_index(0);

// take one second to get mad
ch->set_face_expression("Mad", 1.0);

int diguyCharacter::set_orientation_eyes	(	float	azimuth,
		float	elevation,
		float	blend_time = 0.0f
	)

This function sets the current azimuth and elevation of the character's eyes.

Currently affects only "facefx" appearances.

Parameters

azimuth	rotation about up (vertical) axis, in degrees; positive rotates to character's left
elevation	rotation about forward (horizontal) axis, in degrees; positive rotates down
blend_time	how long to take to reach new orientation

Returns:

0 on success, -1 on failure

int diguyCharacter::get_orientation_eyes	(	float *	azimuth,
		float *	elevation
	)

This function gets the current azimuth and elevation of the character's eyes.

It currently doesn't take blending into account.

Currently affects only "facefx" appearances.

int diguyCharacter::set_eye_droop	(	float	droop_amount,
		float	blend_time = 0.0f
	)

Sets how open the eyes are.

The eyes will stay at this level indefinitely. To get automatic blinking behavior, call blink().

Parameters

droop_amount

1 = eyes closed, 0 = eyes open, 0.5 = half open

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

float diguyCharacter::get_eye_droop

(

)

Returns: how open the eyes are as set by set_eye_droop().

int diguyCharacter::blink	(	float	duration_in = 0.1f,
		float	duration_out = 0.2f,
		float	target_in = 1.0f,
		float	target_out = 0.0f,
		float	tin = DIGUY_DEFAULT_FLOAT
	)

This function blinks the eyes.

To have the eyes close to a specific amount and stay there, call set_eye_droop().

Only characters with expressive face appearances can blink.

Parameters

duration_in	how long in seconds the first part of the blink (typically eyes closing) should take
duration_out	how long in seconds the second part of the blink (typically eyes opening) should take
target_in	how closed the eyes should be at duration_in
target_out	how open the eyes should be at duration_out and thereafter
tin	time at which blink should occur; default is now

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::set_automatic_blinks_enabled	(	int	enabled,
		float	period = 6.0f,
		float	period_variation = 3.0f
	)

This function enables automatic eye blinking, so that blinks will happen without further function calls.

The various controlling factors of blinks are set by the following functions:

• set_automatic_blink_duration_in()
• set_automatic_blink_duration_out()
• set_automatic_blink_target_in()

• set_automatic_blink_target_out()

  See blink() for information on what these factors mean.

  Only characters with expressive face appearances can blink.

Parameters

enabled	pass 1 to enable automatic blinks; 0 to disable
period	how many seconds between each blink
period_variation	variation on how many seconds between each blink

If blinks are enabled, the first blink will happen immediately. Successive blinks will happen between times (period - period_variation) and (period + period_variation) after the previous blink ends.

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::get_automatic_blinks_enabled

(

)

Returns: 1 if automatic eye blinks are enabled, 0 if not;.

void diguyCharacter::set_automatic_blink_duration_in

(

float

duration_in

)

This function sets how long it will take the eye to close during automatic eye blinks.

See set_automatic_blinks_enabled() and blink().

Parameters

duration_in

time in seconds for eye droop to go from droop target in to target out

Available as Decision Bead/Event

float diguyCharacter::get_automatic_blink_duration_in

(

)

Returns: most recent setting of set_automatic_blink_duration_in()

void diguyCharacter::set_automatic_blink_duration_out

(

float

duration_out

)

This function sets how long it will take the eye to open during automatic eye blinks.

See set_automatic_blinks_enabled() and blink().

Parameters

duration_out

time in seconds for eye droop to go from droop target out to target in

Available as Decision Bead/Event

float diguyCharacter::get_automatic_blink_duration_out

(

)

Returns: most recent setting of set_automatic_blink_duration_out()

void diguyCharacter::set_automatic_blink_target_in

(

float

target_in

)

This function sets how much the eye will close during automatic eye blinks.

See set_automatic_blinks_enabled() and blink().

Parameters

target_in

how far to close eye; 1.0 is all closed, 0.0 is all open

Available as Decision Bead/Event

float diguyCharacter::get_automatic_blink_target_in

(

)

Returns: most recent setting of set_automatic_blink_target_in()

void diguyCharacter::set_automatic_blink_target_out

(

float

target_out

)

This function sets how much the eye will open during automatic eye blinks.

See set_automatic_blinks_enabled() and blink().

Parameters

target_out

how far to open eye; 1.0 is all closed, 0.0 is all open

Available as Decision Bead/Event

float diguyCharacter::get_automatic_blink_target_out

(

)

Returns: most recent setting of set_automatic_blink_target_out()

int diguyCharacter::is_speaking

(

)

Returns: 1 if the character is speaking, 0 if not.

With a FaceFX character this is true if a character is actively playing a FaceFX animation

int diguyCharacter::set_current_facefx_animation_group

(

const char *

anim_group

)

FaceFX animations are referred to as a group/animation name.

This function allows you to set the current group once. See diguyScenario::facefx_mount_animset() for how to load a new animset on an actor.

const char* diguyCharacter::get_current_facefx_animation_group

(

)

Returns: the current FaceFX animation group set for this character.

const char* diguyCharacter::get_facefx_actor

(

)

Returns: the name of the FaceFX actor that goes with the current head appearance; returns NULL if there's no FaceFX actor.

int diguyCharacter::facefx_mount_animset

(

const char *

file_name

)

Mounts an animset on the current FaceFX actor.

See also diguyScenario::facefx_mount_animset()

int diguyCharacter::play_facefx_animation	(	const char *	animation,
		float	magnitude_scale = 1.0f,
		float	duration_scale = 1.0f,
		float	blendin_time = 0.1f,
		float	blendout_time = 0.1f,
		int	loop = 0
	)

Plays a FaceFX animation.

This is the main way a facial animation sequence is triggered. The animation can be named "group_name/animation" or just "animation" if the proper group has been set with set_current_facefx_animation_group().

int diguyCharacter::stop_facefx_animations	(	float	blend_time = 0.25f,
		int	stop_sounds = 1
	)

Stops all active FaceFX animations.

int diguyCharacter::get_num_facefx_nodes

(

)

Returns: the number of nodes in the FaceFX actor's face graph.

const char* diguyCharacter::get_facefx_node_name

(

int

index

)

Returns: the name of the node with index 'index' in the FaceFX actor's face graph.

int diguyCharacter::find_facefx_node_index

(

const char *

node_name

)

Returns: the index of the node with name 'node_name'.

int diguyCharacter::set_facefx_node_value	(	int	node_index,
		float	value,
		float	blend_time = 0.25f
	)

Allows low level control of individual nodes of the characters face graph.

End users can use this function to get finer grained control over eye direction and emotional state.

float diguyCharacter::get_facefx_node_value

(

int

node_index

)

Retrieves the current final value of a node.

diguyCharacterGesture* diguyCharacter::create_gesture

(

const char *

gesture_name

)

This function creates (but does not begin) the specified gesture.

Exact control over the gesture, such as number of repetitions, when the gesture should begin, when it should end, when it should reach specific points within the gestures, etc., is then possible by making calls through the returned diguyCharacterGesture object.

To begin execution of the gesture, call the begin_now() function of the diguyCharacterGesture object.

Do not call delete on the returned object. It should be destroyed either by calling destroy_gesture(), or by calling set_automatic_destroy_flag(1) on the diguyCharacterGesture object.

Parameters

gesture_name

name of the gesture of create

Returns:

pointer to object of type diguyCharacterGesture

int diguyCharacter::destroy_gesture

(

diguyCharacterGesture *

gesture

)

This function destroys a gesture object created by create_gesture().

Parameters

gesture

gesture to destroy

Returns:

0 on success, -1 on failure

int diguyCharacter::execute_gesture	(	const char *	gesture_name,
		int	reps = DIGUY_DEFAULT_INT,
		float	overall_duration = DIGUY_DEFAULT_FLOAT,
		float	channel_A_weight = DIGUY_DEFAULT_FLOAT
	)

This function executes the specified gesture.

The gesture will automatically begin and end. The only control over the executed gesture is whether is should be ended or aborted early. See end_executing_gesture() and abort_executing_gesture(). For full control of gesture attributes, use create_gesture() instead.

A gesture takes over control of a subset of a character's pose variables and can be overlaid on top of most base actions of the character.

Note that gestures should be preloaded at the beginning of a scenario to avoid a hitch in frame rate. See the function diguyScenario::preload_gesture().

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

gesture_name	name of the gesture of execute
reps	how many times the gesture should be repeated; default is 1 if no duration is specified, or best fit if there is a duration specified
overall_duration	for how long the gesture should be executed; default is such that no time scaling occurs
channel_A_weight	the weight given to channel A of the gesture; ignored if the gesture does not have multiple channels

If the gesture is a multi-stage gesture, the overall duration will be spread proportionately over each stage.

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::execute_1stage_gesture	(	const char *	gesture_name,
		int	reps = DIGUY_DEFAULT_INT,
		float	stage1_duration = DIGUY_DEFAULT_FLOAT,
		float	channel_A_weight = DIGUY_DEFAULT_FLOAT
	)

The gesture will automatically begin and end.

The only control over the executed gesture is whether is should be ended or aborted early. See end_executing_gesture() and abort_executing_gesture(). For full control of gesture attributes, use create_gesture() instead.

If the specified gesture is not a 1 stage gesture, no gesture is executed and an error value is returned.

The specified gesture can be a one or two channel 1 stage gesture, in which case the specified channel weight will be used over the course of the entire gesture.

A 1 stage gesture is a comprised of a single motion that begins and ends the gesture.

n repetitions of a 1 stage gesture will repeat the stage 1 motion n times.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

gesture_name	name of the gesture of execute
reps	how many times the gesture should be repeated; default is 1 if no duration is specified, or best fit if there is a duration specified
stage1_duration	how long stage 1 of the gesture should take; default is such that no time scaling occurs
channel_A_weight	the weight given to channel A of the gesture; ignored if the gesture does not have multiple channels

Returns:

0 on success, -1 on failure

int diguyCharacter::execute_2stage_gesture	(	const char *	gesture_name,
		int	reps = DIGUY_DEFAULT_INT,
		float	stage1_duration = DIGUY_DEFAULT_FLOAT,
		float	stage2_duration = DIGUY_DEFAULT_FLOAT,
		float	channel_A_weight = DIGUY_DEFAULT_FLOAT
	)

This function is similar to execute_1stage_gesture().

Stage 1 of a 2 stage gesture is a motion that begins the gesture and leads to the "peak" of the gesture.

Stage 2 of a 2 stage gesture is the motion that returns the gesture from the "peak" to the starting position.

n repetitions of a 2 stage gesture will repeat the stage 1 motion followed by the stage 2 motion n times.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

gesture_name	name of the gesture of execute
reps	how many times the gesture should be repeated; default is 1 if no duration is specified, or best fit if there is a duration specified
stage1_duration	how long stage 1 of the gesture should take, i.e., how far into the gesture the "peak" will occur; default is such that no time scaling occurs
stage2_duration	how long stage 2 of the gesture should take; default is such that no time scaling occurs
channel_A_weight	the weight given to channel A of the gesture; ignored if the gesture does not have multiple channels

Returns:

0 on success, -1 on failure

int diguyCharacter::execute_3stage_gesture	(	const char *	gesture_name,
		int	reps = DIGUY_DEFAULT_INT,
		float	stage1_duration = DIGUY_DEFAULT_FLOAT,
		float	stage2_duration = DIGUY_DEFAULT_FLOAT,
		float	stage3_duration = DIGUY_DEFAULT_FLOAT,
		float	channel_A_weight = DIGUY_DEFAULT_FLOAT
	)

This function is similar to execute_1stage_gesture().

Stage 1 of a 3 stage gesture is a motion that begins the gesture and leads to stage 2; e.g., raising the right arm in preparation for waving.

Stage 2 of a 3 stage gesture is a motion that can loop indefinitely; e.g., waving the right arm back and forth.

Stage 3 of a 3 stage gesture is the motion that ends the gesture; e.g., returning the right arm to the side of the body to complete the wave.

n repetitions of a 3 stage gesture will play the stage 1 motion once, followed by n reps of the stage 2 motion, followed by 1 stage 3 motion.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

gesture_name	name of the gesture of execute
reps	how many times the gesture should be repeated; default is 1 if no duration is specified, or best fit if there is a duration specified
stage1_duration	how long stage 1 of the gesture should take; default is such that no time scaling occurs
stage2_duration	how long each repetition of stage 2 of the gesture should take; default is such that no time scaling occurs
stage3_duration	how long stage 3 of the gesture should take; default is such that no time scaling occurs
channel_A_weight	the weight given to channel A of the gesture; ignored if the gesture does not have multiple channels

Returns:

0 on success, -1 on failure

int diguyCharacter::execute_table_gesture	(	const char *	gesture_name,
		int	reps = DIGUY_DEFAULT_INT,
		const char *	loop_action = NULL,
		const char *	begin_action = NULL,
		const char *	end_action = NULL
	)

The gesture will automatically begin and end.

The only control over the executed gesture is whether is should be ended or aborted early. See end_executing_gesture() and abort_executing_gesture(). For full control of gesture attributes, use create_gesture() instead.

This function serves as a quick way of executing a table gesture. There are many capabilities of table gestures that are accessible only through the full diguyCharacterGesture object.

If the specified gesture is not a table gesture, no gesture is executed and an error value is returned.

A table stage gesture is a comprised of a table of gesture actions that can be transitioned between without going through a neutral position.

n repetitions of a table gesture will repeat the loop action n times.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

gesture_name	name of the gesture of execute
reps	how many times the gesture should be repeated; default is 1
loop_action	which action in the gesture should be looped; default is action at index 1 of table
begin_action	which action the gesture should begin from; default is action at index 0
end_action	which action the gesture should end at; default is action at index 0

Returns:

0 on success, -1 on failure

int diguyCharacter::set_executing_table_gesture_desired_action	(	const char *	gesture_name,
		const char *	desired_action
	)

Documentation Pending.

int diguyCharacter::end_executing_gesture

(

const char *

gesture_name

)

This function alerts the specified gesture that it should end.

The gesture will stop repeating and play its "out" motions as soon as possible.

In order to immediately stop the gesture, use the abort_executing_gesture() function.

Parameters

gesture_name

name of executing gesture to end

Returns:

0 on success, -1 on failure

See Also:

abort_executing_gesture()

int diguyCharacter::abort_executing_gesture	(	const char *	gesture_name,
		float	max_rampdown_interval
	)

This function aborts a gesture previously executed by one of the execute_*_gesture() calls, if it is currently executing.

If a gesture with the given name is not executing, this function will have no effect.

This call won't cause the gesture to switch to its "out" motion; it is a straight-forward blend out of whatever the gesture is currently doing. Use the end_executing_gesture() call to make the gesture play its "out" motion as soon as possible, therefore ending the gesture in a smoother way.

Parameters

gesture_name	name of executing gesture to abort
max_rampdown_interval	max amount of time spent trying to smooth over any motion seams; set to 0.5 for a smooth transition, set to 0 for an immediate abort

Returns:

0 on success, -1 on failure

See Also:

end_executing_gesture(), abort_all_gestures()

int diguyCharacter::end_all_gestures

(

)

This function alerts all active gestures that they should end.

The gestures will stop repeating and play their "out" motions as soon as possible.

In order to immediately stop all gestures, use the abort_all_gestures() function.

Returns:

0 on success, -1 on failure

See Also:

abort_all_gestures(), diguyCharacterGesture::end_gesture()

int diguyCharacter::abort_all_gestures

(

float

max_rampdown_interval

)

This function aborts all active gestures.

All gestures will immediately begin to lose their effect on the character's pose.

This won't cause the gestures to switch to their "out" motions; it is a straight-forward blend out of whatever the gesture is currently doing. Use the end_all_gestures() call to make all active gestures play their "out" motions as soon as possible, therefore ending the gestures in a smoother way.

Parameters

max_rampdown_interval

max amount of time spent trying to smooth over any motion seams; set to 0.5 for a smooth transition, set to 0 for an immediate abort

Returns:

0 on success, -1 on failure

See Also:

end_all_gestures(), diguyCharacterGesture::abort_now()

int diguyCharacter::play_sound	(	const char *	sound_name,
		float	sound_gain = 1.0f,
		int	sound_loops = 0
	)

This function will play the specified sound.

The sound will be "ambient"; i.e., it will be equally audible from everywhere within the world. Use the function play_3d_sound() to play a sound that moves with the character.

This function will have no effect on a dead character (see die_now() and get_dead()).

Unless the sound loops, the sound will play to completion and then stop. To stop the sound early or stop a looping sound call diguyCharacter::stop_all_sounds() or diguyCharacter::stop_sound().

Parameters

sound_name	name of sound to play
sound_gain	by how much sound's amplitude should be multiplied
sound_loop	indicates that sound should loop indefinitely

There must be a diguySound in the scenario with the passed sound_name. See diguyScenario::create_sound().

See set_current_voice_actor() for information on how a voice actor can change which sound in the scenario is selected.

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::play_3d_sound	(	const char *	sound_name,
		float	sound_gain = 1.0f,
		int	sound_loops = 0
	)

This function will play the specified sound at the character's location.

As the character moves, the sound will move with it. Use the function play_sound() to play a sound that is ambient and does not move with the character.

Note that not all sound modules support 3D sounds.

This function will have no effect on a dead character (see die_now() and get_dead()).

Unless the sound loops, the sound will play to completion and then stop. To stop the sound early or stop a looping sound call diguyCharacter::stop_all_sounds() or diguyCharacter::stop_sound().

Parameters

sound_name	the name of the sound to play
sound_gain	by how much the sound's amplitude should be multiplied
sound_loop	indicates that the sound should loop indefinitely

There must be a diguySound in the scenario with the passed sound_name. See diguyScenario::create_sound().

See set_current_voice_actor() for information on how a voice actor can change which sound in the scenario is selected.

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

diguySoundInstance* diguyCharacter::create_sound_instance

(

const char *

sound_name

)

This function creates (but does not start playing) an instance of the specified sound.

Exact control over the sound instance is possible by making calls through the returned diguySoundInstance object.

To begin playing the sound, call diguySoundInstance::begin_now().

Do not call delete on the returned object. It should be destroyed either by calling diguyCharacter::destroy_sound_instance() or by calling diguySoundInstance::set_automatic_destroy_flag(1) on the returned object.

Parameters

sound_name

name of the sound for which to create an instance

There must be a diguySound in the scenario with the passed sound_name. See diguyScenario::create_sound().

Returns:

pointer to object of type diguySoundInstance

int diguyCharacter::destroy_sound_instance

(

diguySoundInstance *

sound_instance

)

This function destroys a sound instance object created by create_sound_instance().

Do not destroy a sound for which the diguySoundInstance::set_automatic_destroy_flag(1) has been called.

Parameters

sound_instance

sound instance to destroy

Returns:

0 on success, -1 on failure

int diguyCharacter::stop_all_sounds

(

float

rampdown_time = 0.0f

)

This function stops all active sound instances from this character.

All sounds being played by this character will fade out and stop after rampdown_time, by default fade out is instant.

Sound instances that are automatically managed will be destroyed. This includes sound started by a call to diguyCharacter::play_sound() or a sound instance whose set_automatic_destroy_flag() function has been called.

diguySoundInstance pointers returned by a call to diguyCharacter::create_sound_instance(), which have not been set to be automatically destroyed, will still be valid.

Parameters

rampdown_time

how long to fade out the sound

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::stop_sound	(	const char *	sound_name,
		float	rampdown_time = 0.0f
	)

This function stops a named sound instance from this character.

Sound instances that are automatically managed will be destroyed. This includes sound started by a call to diguyCharacter::play_sound() or a sound instance whose set_automatic_destroy_flag() function has been called.

diguySoundInstance pointers returned by a call to diguyCharacter::create_sound_instance(), which have not been set to be automatically destroyed, will still be valid.

Parameters

sound_name	the name of the sound to stop
rampdown_time	how long to fade out the sound

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::is_playing_sound

(

const char *

sound_name

)

Returns: 1 if the character is playing a the sound specified, 0 if not.

int diguyCharacter::set_current_voice_actor

(

const char *

voice_actor

)

Sets the "voice actor" for the character.

Having a voice actor can change which sounds from the scenario a character selects when the diguyCharacter::play_sound() or diguyCharacter::play_3d_sound().

When play_sound() is called the character asks the scenario for the sound with the specified name. If a voice actor has been set the character will first ask the scenario for the sound name prepended with the voice actor and a slash ("/"). If there isn't a sound with that modified name, it will ask the scenario for a sound with the exact specified name.

For example, if the character has the voice actor "carl" and is told to play the sound "run_away", the character will first look for a sound named "carl/run_away". If that isn't found, it will look for a sound named "run_away". (If that isn't found no sound is played.)

Lua Example:

A more specific example: say that various characters in the scenario need to say "hello". Some of the characters are male, some are female. There are two ways this can be set up.

The first way, not using a voice actor, is to have two sounds specified in the scenario: "male_hello" and "female_hello". These sounds specify the sound files "male_hello.wav" and "female_hello.wav", respectively. A male character would then do the following to say hello:

male_character:play_sound("male_hello")

A female character would do:

female_character:play_sound("female_hello")

This is fine, except when one script or character mind needs to be shared by a range of characters, some male and some female.

In this case it's better to use a voice actor. Say that the sounds specified above have the names "male/hello" and "female/hello"; they still have the separate sound files specified. If the character has its voice actor specified as "male" and is told to play the sound "hello", it will select the sound "male/hello" as the sound to play. If its voice actor is "female" and is told to play the sound "hello", it will select the sound "female/hello".

-- called earlier: character:set_voice_actor("male")
character:play_sound("hello")  -- plays sound "male/hello"

-- called earlier: character:set_voice_actor("female")
character:play_sound("hello")  -- plays sound "female/hello"

Parameters

voice_actor

name of voice actor

voice_actor can be an arbitrary string. It doesn't need to match any character name, but should have matching sounds specified in the scenario.

Returns:

0 on success, -1 on failure

const char* diguyCharacter::get_current_voice_actor

(

)

Returns: name of current voice actor, as set by set_current_voice_actor()

int diguyCharacter::get_DIS_lifeform_state

(

)

This function returns the state of the character in the form required by DIS.

Note that there is no corresponding set_DIS_lifeform_state() function. The lifeform state is derived from the character's action, posture, and variant information.

Returns:

one of the following values defined in diguy_dis_constants.h:

 DIGUY_DIS_LIFEFORM_UNUSED                 (0)
 DIGUY_DIS_LIFEFORM_UPRIGHT_STANDING_STILL (1)
 DIGUY_DIS_LIFEFORM_UPRIGHT_WALKING        (2)
 DIGUY_DIS_LIFEFORM_UPRIGHT_RUNNING        (3)
 DIGUY_DIS_LIFEFORM_KNEELING               (4)
 DIGUY_DIS_LIFEFORM_PRONE                  (5)
 DIGUY_DIS_LIFEFORM_CRAWLING               (6)
 DIGUY_DIS_LIFEFORM_SWIMMING               (7)
 DIGUY_DIS_LIFEFORM_PARACHUTING            (8)
 DIGUY_DIS_LIFEFORM_JUMPING                (9)
 DIGUY_DIS_LIFEFORM_SITTING                (10)
 DIGUY_DIS_LIFEFORM_SQUATTING              (11)
 DIGUY_DIS_LIFEFORM_CROUCHING              (12)
 DIGUY_DIS_LIFEFORM_WADING                 (13)

Callable For Networked Entities That Are:

• DIS published and reflected

int diguyCharacter::get_DIS_primary_weapon_position

(

)

This function returns the position of the character's primary weapon, in the form required by DIS.

Returns:

one of the following values defined in diguy_dis_constants.h:

 DIGUY_DIS_PRIMARY_WEAPON_NOT_PRESENT        (0)
 DIGUY_DIS_PRIMARY_WEAPON_STOWED             (1)
 DIGUY_DIS_PRIMARY_WEAPON_DEPLOYED           (2)
 DIGUY_DIS_PRIMARY_WEAPON_IN_FIRING_POSITION (3)

Callable For Networked Entities That Are:

• DIS published

int diguyCharacter::get_DIS_secondary_weapon_position

(

)

This function returns the position of the character's secondary weapon, in the form required by DIS.

Returns:

one of the following values defined in diguy_dis_constants.h:

 DIGUY_DIS_SECONDARY_WEAPON_NOT_PRESENT        (0)
 DIGUY_DIS_SECONDARY_WEAPON_STOWED             (1)
 DIGUY_DIS_SECONDARY_WEAPON_DEPLOYED           (2)
 DIGUY_DIS_SECONDARY_WEAPON_IN_FIRING_POSITION (3)

Callable For Networked Entities That Are:

• DIS published

int diguyCharacter::set_network_marking

(

const char *

network_marking

)

This function sets the Marking Text for characters that are published to the network by DI-Guy Networking.

The default network marking is the empty string "".

This function should only be called for published characters. The Marking Text is set internally for reflected characters.

Returns:

0 on success, -1 on failure

Callable For Networked Entities That Are:

• DIS published
• HLA published

const char* diguyCharacter::get_network_marking

(

)

This function gets the Marking Text for characters.

For published characters this value will be what was most recently set by set_network_marking().

For reflected characters this value will be read from the reflected characters' entity state information.

Returns:

character's Marking Text; will never be NULL

Callable For Networked Entities That Are:

• DIS published and reflected
• HLA published and reflected

int diguyCharacter::set_is_network_published

(

int

is_network_published

)

This function sets whether this character will be published by DI-Guy Networking.

This value is persistent, and does not depend on whether there actually is currently a network connection.

The default is 1, the character is published.

This function should not be called for reflected characters. It affects to both DIS and HLA networking.

Returns:

0 on success, -1 on failure

Callable For Networked Entities That Are:

• DIS published
• HLA published

int diguyCharacter::get_is_network_published

(

)

This function returns whether the character is published by DI-Guy Networking.

It will always return 0 for reflected characters.

This function can be called for any character.

Returns:

1 if published, 0 if not

Available as Decision Bead/Event

Callable For Networked Entities That Are:

• DIS published and reflected
• HLA published and reflected

DtEntityStateRepository* diguyCharacter::get_vrlink_entity_state_repository

(

)

Experimental function that returns a vrlink entity state repository, useful for adding additional information to a diguy that we don't usually model.

int diguyCharacter::get_is_network_reflected

(

)

This function returns whether the character is a reflected character created by DI-Guy Networking.

This function can be called for any character.

Returns:

1 if reflected, 0 if not

Available as Decision Bead/Event

Callable For Networked Entities That Are:

• DIS published and reflected
• HLA published and reflected

int diguyCharacter::get_is_network_paused

(

)

This function returns whether this character is in a "paused" state.

This will only be true for reflected characters.

A reflected character will be paused if the network entity it is representing is paused; i.e., its personal timeline is not advancing. The most common case of this is when this character is reflecting a published character of a DI-Guy Scenario application that is in a paused or stopped state.

If DI-Guy Scenario, paused characters will remain frozen in their current postures.

Returns:

1 if paused, 0 if not

Available as Decision Bead/Event

int diguyCharacter::set_is_network_paused

(

int

paused

)

Overrides built-in logic for network pausing, becomes end user's responsibility to manage.

int diguyCharacter::get_network_entity_number

(

)

This function returns the character's "network entity number".

This number is valid and persistent regardless of whether the character is currently published.

This number is primarily used internally by DI-Guy Networking for creating entity IDs.

Returns:

character's network entity number

Callable For Networked Entities That Are:

• DIS published and reflected
• HLA published and reflected

const char* diguyCharacter::get_action_from_entity_state	(	int	damage_state,
		int	life_form_state,
		int	primary_weapon_state,
		float	speed,
		int	forward
	)

This function returns the name of an action for a character, given the DIS damage state, lifeform state, primary weapon state, speed of the character, and direction of travel.

Constants are all defined in diguy_dis_constants.h:

Parameters

damage_state	one of the values listed below
life_form_state	one of the values listed below
primary_weapon_state	one of the values listed below
speed	in meters/second
forward	whether the action should move forward (pass 1), or backward (pass 0)

Valid values for damage_state:

• DIGUY_DIS_DAMAGE_NONE (0)
• DIGUY_DIS_DAMAGE_SLIGHT (1)
• DIGUY_DIS_DAMAGE_MODERATE (2)
• DIGUY_DIS_DAMAGE_DESTROYED (3)

Valid values for life_form_state:

• DIGUY_DIS_LIFEFORM_UNUSED (0)
• DIGUY_DIS_LIFEFORM_UPRIGHT_STANDING_STILL (1)
• DIGUY_DIS_LIFEFORM_UPRIGHT_WALKING (2)
• DIGUY_DIS_LIFEFORM_UPRIGHT_RUNNING (3)
• DIGUY_DIS_LIFEFORM_KNEELING (4)
• DIGUY_DIS_LIFEFORM_PRONE (5)
• DIGUY_DIS_LIFEFORM_CRAWLING (6)
• DIGUY_DIS_LIFEFORM_SWIMMING (7)
• DIGUY_DIS_LIFEFORM_PARACHUTING (8)
• DIGUY_DIS_LIFEFORM_JUMPING (9)
• DIGUY_DIS_LIFEFORM_SITTING (10)
• DIGUY_DIS_LIFEFORM_SQUATTING (11)
• DIGUY_DIS_LIFEFORM_CROUCHING (12)
• DIGUY_DIS_LIFEFORM_WADING (13)

Valid values for primary_weapon_state:

• DIGUY_DIS_PRIMARY_WEAPON_NOT_PRESENT (0)
• DIGUY_DIS_PRIMARY_WEAPON_STOWED (1)
• DIGUY_DIS_PRIMARY_WEAPON_DEPLOYED (2)
• DIGUY_DIS_PRIMARY_WEAPON_IN_FIRING_POSITION (3)

Note that a backward motion can be requested in a couple of ways: either by passing a negative speed, or by passing 0 for the forward argument, or both.

Returns:

name of an action if a match is found, NULL if not

Callable For Networked Entities That Are:

• DIS published

void diguyCharacter::set_DIS_damage_state

(

int

state

)

Sets the damage state for the network published character.

Depending on the appearance configuration info the character may automatically switch to a new appearance.

Parameters

state

one of the values listed below

Valid values for state (defined in diguy_dis_constants.h):

• DIGUY_DIS_DAMAGE_NONE (0)
• DIGUY_DIS_DAMAGE_SLIGHT (1)
• DIGUY_DIS_DAMAGE_MODERATE (2)
• DIGUY_DIS_DAMAGE_DESTROYED (3)

Callable For Networked Entities That Are:

• DIS published

int diguyCharacter::get_DIS_damage_state

(

)

Returns the damage state of a network published character.

Returns:

one of the values shown in set_DIS_damage_state()

const char* diguyCharacter::get_damage_state_appearance_name

(

int

state

)

Returns the name of damage state appearances based on the base appearance of the character.

NULL if the state isn't available.

void diguyCharacter::set_DIS_smoke_state

(

int

state

)

Sets the smoke state for a network published character.

Starts or stops the "smoke" and "engine_smoke" appearance effects as appropriate.

Parameters

state

one of the values listed below

Valid values for state (defined in diguy_dis_constants.h):

• DIGUY_DIS_SMOKE_NOT_SMOKING (0)
• DIGUY_DIS_SMOKE_SMOKE_PLUME (1)
• DIGUY_DIS_SMOKE_ENGINE_SMOKE (2)
• DIGUY_DIS_SMOKE_ENGINE_SMOKE_AND_SMOKE_PLUME (3)

Callable For Networked Entities That Are:

• DIS published

int diguyCharacter::get_DIS_smoke_state

(

)

Returns the smoke state of a network published character.

Returns:

one of the values shown in set_DIS_smoke_state()

void diguyCharacter::set_DIS_flames_state

(

int

state

)

Sets the flames state for a network published character.

Starts or stops the "flames" appearance effect as appropriate.

state - one of the values listed below

Valid values for state (defined in diguy_dis_constants.h):

• DIGUY_DIS_FLAMES_NONE (0)
• DIGUY_DIS_FLAMES_PRESENT (1)

Callable For Networked Entities That Are:

• DIS published

int diguyCharacter::get_DIS_flames_state

(

)

Returns the flames state of a network published character.

Returns:

one of the values shown in set_DIS_flames_state()

void diguyCharacter::set_DIS_power_plant_state

(

int

state

)

Sets the power plant state for a network published character.

Vehicle power plants default to being on.

state - one of the values listed below

Valid values for state (defined in diguy_dis_constants.h):

• DIGUY_DIS_POWER_PLANT_OFF (0)
• DIGUY_DIS_POWER_PLANT_ON (1)

Callable For Networked Entities That Are:

• DIS published

int diguyCharacter::get_DIS_power_plant_state

(

)

Returns the power plant state of a network published character.

Returns:

one of the values shown in set_DIS_power_plant_state()

void diguyCharacter::set_emissivity	(	float	r,
		float	g,
		float	b,
		float	lerp_time = .25
	)

sets the current emissivity color of the model, overridden by power_plant state in vehicles

void diguyCharacter::get_emissivity	(	float **\	return,
		float *	g,
		float **< b >
	)

gets the current emissivity color of the model, overridden by power_plant state in vehicles

</b> void diguyCharacter::set_DIS_trailing_effect_state

(

int

state

)

Sets the trailing effect state for a network published character.

state - one of the values listed below

Valid values for state (defined in diguy_dis_constants.h):

• DIGUY_DIS_TRAILING_EFFECT_NONE (0)
• DIGUY_DIS_TRAILING_EFFECT_SMALL (1)
• DIGUY_DIS_TRAILING_EFFECT_MEDIUM (2)
• DIGUY_DIS_TRAILING_EFFECT_LARGE (3)

Callable For Networked Entities That Are:

• DIS published

int diguyCharacter::get_DIS_trailing_effect_state

(

)

Returns the trailing effect state of a network published character.

Returns:

one of the values shown in set_DIS_smoke_trail_state()

void diguyCharacter::set_head_lights_state

(

int

state

)

Sets the network headl ight bit to on or off, if a vehicle has head lights it turns them on.

int diguyCharacter::get_head_lights_state

(

)

const

Returns if the head light are on or off.

void diguyCharacter::set_tail_lights_state

(

int

state

)

Sets the network head light bit to on or off, if a vehicle has tail lights it turns them on.

int diguyCharacter::get_tail_lights_state

(

)

const

Returns if the tail lights are on or off.

int diguyCharacter::call_formation	(	const char *	formation_name,
		int	snap_to_position_flag = 0,
		int	break_existing_formations_flag = 1
	)

This function will create a new active formation with this character as its leader.

The formation followers will fall into the formation given by the formation name.

The formation is broken up, or disbanded, by calling break_formation().

Parameters

formation_name	the name of the formation
snap_to_position_flag	if 1, following characters will immediately snap to their assigned positions; otherwise following characters will move toward their assigned positions from their current positions
break_existing_formations_flag	if 1, any formations this character is leading with be broken as if the break_formation() call were made

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::break_formation

(

const char *

formation_name = NULL

)

This function breaks up a formation initiated by call_formation().

Parameters

formation_name

the name of the formation to break; passing NULL or "(all)" will break all formations this character is leading

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

diguyCharacterGuide* diguyCharacter::add_guide	(	const char *	guide_name,
		int	automatically_disable_when_acquired = 0
	)

This function adds a copy of the specified scenario guide to the character.

Any changes that are subsequently made to the added guide – for example by a call to diguyCharacterGuide::set_algorithm_float_parameter() – are private to this copy of the guide and will not affect others.

The guide will be enabled by default. Guides can be disabled by calling diguyCharacterGuide::set_guide_enabled(0), or by passing 1 for the argument automatically_disable_when_acquired.

Note that disabling a guide is not the same as removing it. Disabled guides are still a part of the character and can later be re-enabled by calling diguyCharacterGuide::set_enabled().

Parameters

guide_name	name of guide to find and copy
automatically_disable_when_acquired	set to 1 to have the guide be automatically disabled when it has acquired its target

Returns:

object of type diguyCharacterGuide; if a guide with guide_name is not found, returns NULL

diguyCharacterGuide* diguyCharacter::create_guide	(	const char *	guide_name,
		const char *	guide_algorithm,
		int	automatically_disable_when_acquired = 0
	)

This function creates a new guide and adds it to the character.

The guide will be enabled by default. Guides can be disabled by calling diguyCharacterGuide::set_guide_enabled(), or by passing 1 for the argument automatically_disable_when_acquired.

Important note: a new guide will always be created, even if one with the same name already exists

Parameters

guide_name	name of guide to find and copy
guide_algorithm	name of guide algorithm to be used
automatically_disable_when_acquired	set to 1 to have the guide be automatically disabled when it has acquired its target

Returns:

object of type diguyCharacterGuide; if a guide with guide_name is not found, returns NULL

diguyCharacterGuide* diguyCharacter::find_or_create_guide	(	const char *	guide_name,
		const char *	guide_algorithm,
		int	automatically_disable_when_acquired = 0
	)

Like create_guide(), but returns guide if it already exists.

Parameters

guide_name	name of guide to find and copy
guide_algorithm	name of guide algorithm to be used
automatically_disable_when_acquired	set to 1 to have the guide be automatically disabled when it has acquired its target

Returns:

object of type diguyCharacterGuide; if a guide with guide_name is not found, returns NULL

diguyCharacterGuide* diguyCharacter::find_guide

(

const char *

guide_name

)

This function returns a pointer to the specified guide of the character, if is exists.

Parameters

guide_name

name of guide to find

Returns:

object of type diguyCharacterGuide; if a guide with guide_name is not found, returns NULL

int diguyCharacter::remove_guide_with_name

(

const char *

guide_name

)

This function removes the specified guide from the character.

Parameters

guide_name

name of the guide to remove; must match name used by add_guide() or create_guide() call

Returns:

0 on success, -1 on failure

int diguyCharacter::remove_guide

(

diguyCharacterGuide *

guide

)

This function removes the specified guide from the character.

Parameters

guide

object returned by add_guide() call

Returns:

0 on success, -1 on failure

int diguyCharacter::remove_all_guides

(

)

This function removes all guides from the character.

Returns:

0 on success, -1 on failure

int diguyCharacter::remove_all_disabled_guides

(

)

This function removes all guides that are disabled.

Returns:

0 on success, -1 on failure

int diguyCharacter::add_motion_texture	(	const char *	motex_name = "default",
		float	texture_gain = 1.0f,
		int	end_previous_motex = 1,
		float	rampup_interval = 0.2f
	)

This function adds a "motion texture" to the character.

A motion texture is a relatively long (usually 10 seconds or more) loop that will add natural-looking, low amplitude joint angle adjustments.

This function will have no effect on a dead character (see die_now() and get_dead()).

Parameters

motex_name	name of the motion texture to add; see below
texture_gain	the relative amplitude of the motion texture; higher numbers result in more pronounced movements
end_previous_motex	flag denoting whether this motion texture replaces all previously added motion textures; pass 1 to end existing textures
rampup_interval	how long, in seconds, to take ramping up into the motion texture

List of currently available motion textures:

• "default"

• "motex_stand_casual"

  If 1 is passed for the argument end_previous_motex, the rampup_interval argument will be used as the interval for ending existing motion textures.

Returns:

0 on success, -1 on failure

int diguyCharacter::end_motion_texture

(

float

rampdown_interval = 0.2f

)

This function gradually ends any active motion textures added by add_motion_texture().

Parameters

rampdown_interval

how long, in seconds, to take ending the motion texture

Returns:

0 on success, -1 on failure

int diguyCharacter::set_initial_motion_texture

(

const char *

motex_name

)

This function sets an initial motion texture that should be used by the character whenever the character is loaded from a scenario or the character's scenario is reset.

The gain of the motion texture can be set by calling set_initial_motion_texture_gain(). The initial motion texture gain is 1.0 by default.

See Also:

add_motion_texture(), set_initial_motion_texture_gain()

Parameters

motex_name

name of the motion texture

Returns:

0 on success, -1 on failure

const char* diguyCharacter::get_initial_motion_texture

(

)

This function returns the initial motion texture as set by a call to set_initial_motion_texture().

Returns:

name of initial motion texture

int diguyCharacter::set_initial_motion_texture_gain

(

float

motex_gain

)

This function sets the gain of the initial motion texture of the character.

The initial motion texture can be set by calling set_initial_motion_texture().

Parameters

motex_gain

gain of the motion texture; higher gains result in more pronounced motion

Returns:

0 on success, -1 on failure

float diguyCharacter::get_initial_motion_texture_gain

(

)

This function returns the initial motion texture gain as set by a call to set_initial_motion_texture_gain().

Returns:

gain of initial motion texture

int diguyCharacter::set_history_type

(

diguyHistoryType

history_type

)

This function sets what type of "history" will be kept for the character.

If time is run backwards in a scenario, characters with history will replay the motions they performed at that time. Characters without history will stay frozen in place until time advances past the point from which it was run backwards.

The default is DIGUY_HISTORY_TYPE_NONE for characters created using the diguyScenario::create_character() function. Characters loaded from a .dss file will retain their history settings from the DI-Guy Scenario editing session.

Parameters

history_type

history type to be used for the character

history_type should be one of the following values:

DIGUY_HISTORY_TYPE_NONE

 This history type saves no history.

DIGUY_HISTORY_TYPE_COMPLETE

 This history type saves all of a character's history.

 The initial amount of history to be saved, before memory buffers
 need to be resized, can be set by the function
 set_history_size_t().  The size by which memory buffers grow each
 time they do need to get resized by be set by
 set_history_size_increment_t().

DIGUY_HISTORY_TYPE_FIRST

 This history type is no longer supported.  Characters from
 a .dss that have this history type will have their history
 type set to DIGUY_HISTORY_TYPE_COMPLETE.

DIGUY_HISTORY_TYPE_LAST

 This history type is no longer supported.  Characters from
 a .dss that have this history type will have their history
 type set to DIGUY_HISTORY_TYPE_COMPLETE.

Returns:

0 on success, -1 on failure

diguyHistoryType diguyCharacter::get_history_type

(

)

Returns: the current history type of the character; see set_history_type()

int diguyCharacter::set_history_size_t

(

float

t

)

This function sets the size of the character's history buffer, in seconds.

Parameters

t	length of history buffer, in seconds

Returns:

0 on success, -1 on failure

float diguyCharacter::get_history_size_t

(

)

This function returns the current history buffer size.

See set_history_size_t().

Returns:

current history size

int diguyCharacter::set_history_size_increment_t

(

float

t

)

This function sets the size of the character's history buffer increment, in seconds.

Parameters

t	length of history buffer increment, in seconds

Returns:

0 on success, -1 on failure

float diguyCharacter::get_history_size_increment_t

(

)

This function returns the current history buffer size increment.

See set_history_size_increment_t().

Returns:

current history size increment

void diguyCharacter::set_desired_posture

(

diguyMotionPosture

desired_posture

)

This function sets the desired posture of the character.

This, along with the desired variant, is used primarily by some guides. Specifically, to help choose which actions are used to reach the desired position and orientation of the character.

Pass DIGUY_MOTION_POSTURE_ANY for there to be no desired posture.

Parameters

posture

new desired posture

diguyMotionPosture diguyCharacter::get_desired_posture

(

)

Returns: current desired posture of the character.

void diguyCharacter::set_desired_variant

(

diguyMotionVariant

desired_variant

)

This function sets the desired variant of the character.

This, along with the desired posture, is used primarily by some guides. Specifically, to help choose which actions are used to reach the desired position and orientation of the character.

Pass DIGUY_MOTION_VARIANT_ANY for there to be no desired variant.

Parameters

variant

new desired variant

diguyMotionVariant diguyCharacter::get_desired_variant

(

)

Returns: current desired variant of the character.

const char* diguyCharacter::get_action_from_description	(	diguyMotionDirection	direction,
		diguyMotionPosture	posture,
		diguyMotionVariant	variant,
		float	speed,
		diguyParameterComparison	comparison = DIGUY_PARAMETER_COMPARISON_NEAREST,
		float	comparison_tolerance = DIGUY_DEFAULT_FLOAT,
		int	match_posture_before_variant = 1,
		diguyMotionPosture	posture_alternate1 = DIGUY_MOTION_POSTURE_UNKNOWN,
		diguyMotionPosture	posture_alternate2 = DIGUY_MOTION_POSTURE_UNKNOWN,
		diguyMotionVariant	variant_alternate1 = DIGUY_MOTION_VARIANT_UNKNOWN,
		diguyMotionVariant	variant_alternate2 = DIGUY_MOTION_VARIANT_UNKNOWN,
		int	return_random_match = 0
	)

This function looks up the character action that most closely matches the given criteria.

Parameters

direction	the direction of travel relative to the character's facing direction
posture	overall desired posture; pass DIGUY_MOTION_POSTURE_ANY to specify that any posture will do
variant	overall desired variant; pass DIGUY_MOTION_VARIANT_ANY to specify that any variant will do
speed	speed in meters per second
comparison	how the passed speed should compare to the action's speed
comparison_tolerance	tolerance of comparison
match_posture_before_variant	pass 1 if posture should be matched before variant if an exact match is not found; pass 0 if variant should be matched before posture
posture_alternate1	if an exact match is not found, use this as the first alternate posture; pass DIGUY_MOTION_POSTURE_UNKNOWN to specify that no alternate should be used
posture_alternate2	if an exact match is not found, use this as the second alternate posture; pass DIGUY_MOTION_POSTURE_UNKNOWN to specify that no alternate should be used
variant_alternate1	if an exact match is not found, use this as the first alternate variant; pass DIGUY_MOTION_VARIANT_UNKNOWN to specify that no alternate should be used
variant_alternate2	if an exact match is not found, use this as the second alternate variant; pass DIGUY_MOTION_VARIANT_UNKNOWN to specify that no alternate should be used
return_random_match	(Experimental) if multiple actions match the specified criteria randomly return one of them. Typically only used for still motions and restricted to EQUAL and NEAREST comparisons

The direction argument should be one of the following:

• DIGUY_MOTION_DIRECTION_NONE - does not move character
• DIGUY_MOTION_DIRECTION_FORWARD - moves character forward
• DIGUY_MOTION_DIRECTION_BACKWARD - moves character backward
• DIGUY_MOTION_DIRECTION_LEFT - moves character left
• DIGUY_MOTION_DIRECTION_RIGHT - moves character right
• DIGUY_MOTION_DIRECTION_UP - moves character up
• DIGUY_MOTION_DIRECTION_DOWN - moves character down
• DIGUY_MOTION_DIRECTION_TURN_LEFT - turns character left
• DIGUY_MOTION_DIRECTION_TURN_RIGHT - turns character right
• DIGUY_MOTION_DIRECTION_NONLINEAR - moves character in multiple directions
• DIGUY_MOTION_DIRECTION_LINEAR_OFFAXIS - moves character in a line, but not on any of the principle axes

Not every direction is supported by every character. If the character does not have any actions that move in the specified direction, the returned action will be NULL.

Use the calls diguyScenario::get_character_type_num_directions() and diguyScenario::get_character_type_direction_at_index() to enumerate which directions a character can travel.

The posture arguments should be one of the following:

• DIGUY_MOTION_POSTURE_UNKNOWN - unknown posture
• DIGUY_MOTION_POSTURE_ANY - any posture; a wildcard
• DIGUY_MOTION_POSTURE_UPRIGHT - upright posture; e.g., standing or walking
• DIGUY_MOTION_POSTURE_CROUCHED - crouched posture; e.g., kneeling or walking low
• DIGUY_MOTION_POSTURE_PRONE - prone posture; e.g., lying prone or crawling
• DIGUY_MOTION_POSTURE_SITTING - sitting posture

The posture arguments specify the overall posture the action should have. Most characters have an upright posture. The other postures a character has is dependent on character type. Passing DIGUY_MOTION_POSTURE_ANY for the arguments posture, posture_alternate1, or posture_alternate2 means that the posture of the action should not be used to determine a match.

Use the calls diguyScenario::get_character_type_num_postures() and diguyScenario::get_character_type_posture_at_index() to enumerate which postures a specific character type has.

The variant arguments specify the overall mood the action should convey. Most characters have a "normal" variant. The other variants a character has is dependent on character type. Passing DIGUY_MOTION_VARIANT_ANY for the arguments variant, variant_alternate1, or variant_alternate2 means that the variant of the action should not be used to determine a match.

Use the calls diguyScenario::get_character_type_num_variants() and diguyScenario::get_character_type_variant_at_index() to enumerate which variants a specific character type has.

The comparison argument should be one of the following:

• DIGUY_PARAMETER_COMPARISON_EQUAL - matched action's speed must be within comparison_tolerance of passed speed
• DIGUY_PARAMETER_COMPARISON_NEAREST - matched action's speed is closer than any other potential match's, but still within comparison_tolerance
• DIGUY_PARAMETER_COMPARISON_GREATER - matched action's speed faster than passed speed, but still within comparison_tolerance
• DIGUY_PARAMETER_COMPARISON_LESS - matched action's speed slower than passed speed, but still within comparison_tolerance

The difference between DIGUY_PARAMETER_COMPARISON_EQUAL and DIGUY_PARAMETER_COMPARISON_NEAREST is largely in the value used for comparison_tolerance if DIGUY_DEFAULT_FLOAT is passed; the comparison_tolerance argument defaults to 0.001 for DIGUY_PARAMETER_COMPARISON_EQUAL, and 16384.0 for all other comparison types. Otherwise these two comparison types operate the same.

Returns:

name of an action if a match is found, NULL if not

C++ Example:

diguyCharacter* ch = scenario->get_character_at_index(0);
const char* new_action;

//
//  Get an action that moves forward in an upright posture,
//  whose speed move at least 2.0 meters per second:
//
new_action = ch->get_action_from_description(
    DIGUY_MOTION_DIRECTION_FORWARD,
    DIGUY_MOTION_POSTURE_UPRIGHT,
    DIGUY_MOTION_VARIANT_ANY,
    2.0,
    DIGUY_PARAMETER_COMPARISON_GREATER, DIGUY_DEFAULT_FLOAT);

//
//  Get an action that is standing still, with the variant
//  DIGUY_MOTION_VARIANT_READY.  If no action has that variant,
//  try DIGUY_MOTION_VARIANT_AIM as variant_alternate1,
//  and DIGUY_MOTION_VARIANT_ANY as variant_alternate2:
//
new_action = ch->get_action_from_description(
    DIGUY_MOTION_DIRECTION_NONE,
    DIGUY_MOTION_POSTURE_ANY,
    DIGUY_MOTION_VARIANT_READY,
    0.0,
    DIGUY_PARAMETER_COMPARISON_NEAREST, DIGUY_DEFAULT_FLOAT,
    0,
    DIGUY_MOTION_POSTURE_UNKNOWN,
    DIGUY_MOTION_POSTURE_UNKNOWN,
    DIGUY_MOTION_VARIANT_AIM,
    DIGUY_MOTION_VARIANT_ANY);

const char* diguyCharacter::get_turning_action_from_description	(	diguyMotionDirection	direction,
		diguyMotionPosture	posture,
		diguyMotionVariant	variant,
		float	turn_amount,
		diguyParameterComparison	comparison = DIGUY_PARAMETER_COMPARISON_NEAREST,
		float	comparison_tolerance = DIGUY_DEFAULT_FLOAT,
		int	match_posture_before_variant = 1,
		diguyMotionPosture	posture_alternate1 = DIGUY_MOTION_POSTURE_UNKNOWN,
		diguyMotionPosture	posture_alternate2 = DIGUY_MOTION_POSTURE_UNKNOWN,
		diguyMotionVariant	variant_alternate1 = DIGUY_MOTION_VARIANT_UNKNOWN,
		diguyMotionVariant	variant_alternate2 = DIGUY_MOTION_VARIANT_UNKNOWN
	)

This function is very similar to get_action_from_description(), but substitutes turn amount per action iteration for speed.

Parameters

direction	the direction of travel relative to the character's facing direction
posture	overall desired posture; pass DIGUY_MOTION_POSTURE_ANY to specify that any posture will do
variant	overall desired variant; pass DIGUY_MOTION_VARIANT_ANY to specify that any variant will do
turn_amount	how many degrees each iteration of the action should turn the character
comparison	how the passed turn amount should compare to the action's turn amount
comparison_tolerance	tolerance of comparison
match_posture_before_variant	pass 1 if posture should be matched before variant if an exact match is not found; pass 0 if variant should be matched before posture
posture_alternate1	if an exact match is not found, use this as the first alternate posture; pass DIGUY_MOTION_POSTURE_UNKNOWN to specify that no alternate should be used
posture_alternate2	if an exact match is not found, use this as the second alternate posture; pass DIGUY_MOTION_POSTURE_UNKNOWN to specify that no alternate should be used
variant_alternate1	if an exact match is not found, use this as the first alternate variant; pass DIGUY_MOTION_VARIANT_UNKNOWN to specify that no alternate should be used
variant_alternate2	if an exact match is not found, use this as the second alternate variant; pass DIGUY_MOTION_VARIANT_UNKNOWN to specify that no alternate should be used

The direction argument should be one of the following:

• DIGUY_MOTION_DIRECTION_TURN_LEFT - turns character left
• DIGUY_MOTION_DIRECTION_TURN_RIGHT - turns character right

Not every direction is supported by every character. If the character does not have any actions that move in the specified direction, the returned action will be NULL.

The turn amount argument should be a positive number.

Refer to get_action_from_description() for more information on other arguments.

Returns:

name of an action if a match is found, NULL if not

int diguyCharacter::get_num_variables

(

)

Returns: number of variables the character has.

diguyVariable* diguyCharacter::get_variable_at_index

(

int

index

)

Returns: pointer of type diguyVariable; NULL if no variable at the specified index.

Parameters

index

index of the variable; indices start at 0

diguyVariable* diguyCharacter::find_variable

(

const char *

name

)

This function returns a pointer to the specified variable.

Parameters

name	name of variable to be found

Returns:

pointer of type diguyVariable; NULL if not found

diguyVariable* diguyCharacter::find_or_create_variable

(

const char *

name

)

This function finds the variable with the given name or creates it if it doesn't exist.

Parameters

name	name of the variable to find or create

Returns:

pointer of type diguyVariable; should never be NULL

int diguyCharacter::destroy_variable

(

diguyVariable *

variable

)

This function destroys the passed variable.

Parameters

variable

pointer to a diguyVariable

Returns:

0 on success, -1 on failure

int diguyCharacter::variable_equal_to_int	(	const char *	varname,
		int	value
	)

Returns: 1 if variable is equal to passed value, 0 if not.

Parameters

varname	name of variable to compare
value	value to compare against

Available as Decision Bead/Event

int diguyCharacter::variable_greater_than_int	(	const char *	varname,
		int	value
	)

Returns: 1 if variable is greater than passed value, 0 if not.

Parameters

varname	name of variable to compare
value	value to compare against

Available as Decision Bead/Event

int diguyCharacter::variable_less_than_int	(	const char *	varname,
		int	value
	)

Returns: 1 if variable is less than passed value, 0 if not.

Parameters

varname	name of variable to compare
value	value to compare against

Available as Decision Bead/Event

int diguyCharacter::variable_equal_to_float	(	const char *	varname,
		float	value
	)

Returns: 1 if variable is equal to passed value, 0 if not.

Parameters

varname	name of variable to compare
value	value to compare against

Available as Decision Bead/Event

int diguyCharacter::variable_greater_than_float	(	const char *	varname,
		float	value
	)

Returns: 1 if variable is greater than passed value, 0 if not.

Parameters

varname	name of variable to compare
value	value to compare against

Available as Decision Bead/Event

int diguyCharacter::variable_less_than_float	(	const char *	varname,
		float	value
	)

Returns: 1 if variable is less than passed value, 0 if not.

Parameters

varname	name of variable to compare
value	value to compare against

Available as Decision Bead/Event

int diguyCharacter::variable_equal_to_string	(	const char *	varname,
		const char *	value
	)

Returns: 1 if variable is equal than passed value, 0 if not.

Parameters

varname	name of variable to compare
value	value to compare against

Available as Decision Bead/Event

int diguyCharacter::variable_greater_than_string	(	const char *	varname,
		const char *	value
	)

Returns: 1 if variable is greater than passed value (comes later alphabetically), 0 if not.

Parameters

varname	name of variable to compare
value	value to compare against

Available as Decision Bead/Event

int diguyCharacter::variable_less_than_string	(	const char *	varname,
		const char *	value
	)

Returns: 1 if variable is less than passed value (comes sooner alphabetically), 0 if not.

Parameters

varname	name of variable to compare
value	value to compare against

Available as Decision Bead/Event

int diguyCharacter::variable_decrement_value_as_int	(	const char *	varname,
		int	value = 1
	)

This function decrements the variable by the passed amount.

Parameters

varname	name of variable to modify
value	amount to decrement

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::variable_increment_value_as_int	(	const char *	varname,
		int	value = 1
	)

This function increments the variable by the passed amount.

Parameters

varname	name of variable to modify
value	amount to increment

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::variable_set_value_as_int	(	const char *	varname,
		int	value,
		int	create_if_doesnt_exist = 1
	)

This function is a convenience function for setting the variable to a new integer value without retrieving the diguyVariable object.

Parameters

varname	name of variable to modify
value	new value
create_if_doesnt_exist	pass 1 to create the variable if it doesn't exist

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::set_ivar	(	const char *	varname,
		int	value,
		int	create_if_doesnt_exist = 1
	)

Short form of variable_set_value_as_int().

int diguyCharacter::get_ivar	(	const char *	varname,
		int	create_if_doesnt_exist = 1
	)

This function is a convenience function for retrieving the value of a variable without retrieving the diguyVariable object.

If the variable doesn't exist and create_if_doesnt_exist is 0, the returned value will be 0.

Parameters

varname	name of variable to query
create_if_doesnt_exist	pass 1 to create the variable if it doesn't exist

Returns:

value of variable as int

int diguyCharacter::variable_set_value_as_float	(	const char *	varname,
		float	value,
		int	create_if_doesnt_exist = 1
	)

Similar to variable_set_value_as_int(), for sets a floating point value instead.

int diguyCharacter::set_fvar	(	const char *	varname,
		float	value,
		int	create_if_doesnt_exist = 1
	)

Short form of variable_set_value_as_float().

float diguyCharacter::get_fvar	(	const char *	varname,
		int	create_if_doesnt_exist = 1
	)

Similar to variable_get_value_as_int(), for returns a floating point value instead.

If the variable doesn't exist and create_if_doesnt_exist is 0, the returned value will be 0.0.

int diguyCharacter::variable_set_value_as_string	(	const char *	varname,
		const char *	value,
		int	create_if_doesnt_exist = 1
	)

Similar to variable_set_value_as_int(), for sets a string value instead.

int diguyCharacter::set_svar	(	const char *	varname,
		const char *	value,
		int	create_if_doesnt_exist = 1
	)

Short form of variable_set_value_as_string().

const char* diguyCharacter::get_svar	(	const char *	varname,
		int	create_if_doesnt_exist = 1
	)

Similar to variable_get_value_as_int(), for returns a string value instead.

If the variable doesn't exist and create_if_doesnt_exist is 0, the returned value will be "".

diguyViewLabel* diguyCharacter::get_name_label

(

)

This function returns a pointer to the label object of the character.

Currently character labels are only enabled in DI-Guy Scenario.

Returns:

pointer to the character's label

int diguyCharacter::set_label_text

(

const char *

label_text

)

This function sets the text of the character's label.

By default the label text matches the character's name.

Currently character labels are only enabled in DI-Guy Scenario.

Parameters

label_text

new text for the label

Returns:

0 on success, -1 on failure

const char* diguyCharacter::get_label_text

(

)

This function returns the character's label text.

See set_label_text().

Returns:

current label text; the returned pointer will never be NULL

int diguyCharacter::set_label_is_visible

(

int

is_visible

)

This function sets whether the label of this character is visible.

This setting will only be taken into account if the visibility flag for Character Labels is set to "Per Object".

Currently character labels are only enabled in DI-Guy Scenario.

Parameters

is_visible

pass 1 to show, pass 0 to hide

Returns:

0 on success, -1 on failure

int diguyCharacter::get_label_is_visible

(

)

This function returns the most recent setting of set_label_is_visible().

Returns:

1 if visible, 0 if not

int diguyCharacter::set_label_text_color	(	float	r,
		float	g,
		float	b,
		float	a
	)

This function sets the text color of the character's label.

By default the label text color is opaque white.

Currently character labels are only enabled in DI-Guy Scenario.

Parameters

r,g,b,a

the red, green, blue, and alpha components of the text color

An alpha component of 0 makes the text completely transparent. An alpha component of 1 makes the text completely opaque. Values in between result in varying levels of transparency.

Returns:

0 on success, -1 on failure

int diguyCharacter::set_label_text_color_vec4

(

const diguyVec4f &

color

)

Alternate version of set_label_text_color().

int diguyCharacter::get_label_text_color	(	float *	r,
		float *	g,
		float *	b,
		float *	a
	)

This function returns, in the passed variable pointers, the most recent setting of set_label_text_color().

Returns:

0 on success, -1 on failure

diguyVec4f diguyCharacter::get_label_text_color_vec4

(

)

Alternate version of get_label_text_color().

int diguyCharacter::set_label_text_shadow_color	(	float	r,
		float	g,
		float	b,
		float	a
	)

This function sets the text shadow color of the character's label.

By default the label text shadow color is gray.

Currently character labels are only enabled in DI-Guy Scenario.

Parameters

r,g,b,a

the red, green, blue, and alpha components of the text shadow color

An alpha component of 0 makes the text completely transparent. An alpha component of 1 makes the text completely opaque. Values in between result in varying levels of transparency.

Returns:

0 on success, -1 on failure

int diguyCharacter::set_label_text_shadow_color_vec4

(

const diguyVec4f &

color

)

Alternate version of set_label_text_shadow_color().

int diguyCharacter::get_label_text_shadow_color	(	float *	r,
		float *	g,
		float *	b,
		float *	a
	)

This function returns, in the passed variable pointers, the most recent setting of set_label_text_shadow_color().

Returns:

0 on success, -1 on failure

diguyVec4f diguyCharacter::get_label_text_shadow_color_vec4

(

)

Alternate version of get_label_text_shadow_color().

int diguyCharacter::set_label_text_shadow_is_visible

(

int

is_visible

)

This function sets the whether the text shadow is visible.

Parameters

visible

pass 1 to make shadow visible, 0 to make it invisible

Returns:

0 on success, -1 on failure

int diguyCharacter::get_label_text_shadow_is_visible

(

)

Returns: 1 if text shadow is visible, 0 if not.

int diguyCharacter::set_label_background_color	(	float	r,
		float	g,
		float	b,
		float	a
	)

This function sets the background color of the character's label.

By default the label background color is transparent blue.

Currently character labels are only enabled in DI-Guy Scenario.

Parameters

r,g,b,a

the red, green, blue, and alpha components of the text color

An alpha component of 0 makes the text completely transparent. An alpha component of 1 makes the text completely opaque. Values in between result in varying levels of transparency.

Returns:

0 on success, -1 on failure

int diguyCharacter::set_label_background_color_vec4

(

const diguyVec4f &

color

)

Alternate version of set_label_background_color().

int diguyCharacter::get_label_background_color	(	float *	r,
		float *	g,
		float *	b,
		float *	a
	)

This function returns, in the passed variable pointers, the most recent setting of set_label_background_color().

Returns:

0 on success, -1 on failure

diguyVec4f diguyCharacter::get_label_background_color_vec4

(

)

Alternate version of get_label_background_color().

void diguyCharacter::set_label_link_offset_override

(

float

offset

)

This function sets how high the label of the character will float above the character.

Parameters

offset

offset, in meters, of label above character

float diguyCharacter::get_label_link_offset_override

(

)

Returns: how high the label of the character will float above the character.

int diguyCharacter::set_label_shows_character_state

(

int

show_state

)

This function sets whether the label text should show some basic state information about the character instead of its name or the text set by set_label_text().

The state shown is: Character name, current path, current action. The current path and current action will change as the character moves through paths and actions.

Parameters

show_state

pass 1 to show state, 0 to show original text

int diguyCharacter::get_label_shows_character_state

(

)

Returns: whether character state information is shown instead of the character's name or other label text.

diguyImpact* diguyCharacter::get_last_impact_record

(

)

Returns: pointer of type diguyImpact; NULL if there has been no recent impact recorded; useful for finding out who or what was hit.

int diguyCharacter::get_last_impact_number

(

)

Returns: the last impact number.

int diguyCharacter::get_last_impact_been_processed

(

)

Returns: the processed flag on the diguyImpact class.

void diguyCharacter::set_last_impact_been_processed

(

)

Sets the processed flag on the diguyImpact object.

void diguyCharacter::set_max_unprocessed_impacts

(

int

max_unprocessed_impacts

)

Sets the maximum number of unprocessed impacts there can be.

The unprocessed impact array is a first-in-first-out queue. If an impact occurs that pushes the number of unprocessed impacts past this maximum number, earlier impacts will be dropped from the array.

The initial value is 10.

int diguyCharacter::get_max_unprocessed_impacts

(

)

Returns: maximum number of unprocessed impacts.

const char* diguyCharacter::get_last_impact_link

(

)

Returns: the last impact link.

int diguyCharacter::get_last_impact_link_is

(

const char *

link_name

)

Returns: 1 if the last impact link is the link named.

int diguyCharacter::get_last_impact_is_from_vehicle

(

)

Returns: 1 if the last impact resulted from an impact with a vehicle, 0 if not.

int diguyCharacter::get_last_impact_speed_is_greater_than

(

float

impact_speed

)

Returns: 1 if the last impact speed is greater than the passed speed, 0 if not.

void diguyCharacter::set_is_immune_to_impacts

(

int

immune

)

Sets if impacts are ever processed on this character.

Useful for temporary effects and the like.

int diguyCharacter::get_is_immune_to_impacts

(

)

Returns: 1 if the character is immune to impacts 0 if not.

int diguyCharacter::begin_appearance_effect	(	const char *	effect,
		const char *	override_link = NULL,
		float	override_scale = DIGUY_DEFAULT_FLOAT,
		float	override_offset_x = DIGUY_DEFAULT_FLOAT,
		float	override_offset_y = DIGUY_DEFAULT_FLOAT,
		float	override_offset_z = DIGUY_DEFAULT_FLOAT,
		float	override_duration = DIGUY_DEFAULT_FLOAT
	)

This function starts the specified appearance effect on the character.

The following appearance effects are available:

• "brake_lights"
• "debris"
• "debris_dark"
• "dust"
• "engine_smoke"
• "explosion"
• "explosion_dark"
• "flames"
• "flashing_lights"
• "ground_dust_burst"
• "headlights"
• "rotor_wash"
• "smoke"
• "smoke_dark"
• "smoke_trail"

Parameters

effect	name of appearance effect to be started
override_link	link to attach to; overrides default
override_scale	scale to use for effect; overrides default
override_offset_x	x offset to use for effect; overrides default
override_offset_y	y offset to use for effect; overrides default
override_offset_z	z offset to use for effect; overrides default
override_duration	overrides how long the effect should show before automatically ending

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::end_appearance_effect	(	const char *	effect,
		const char *	override_link = NULL
	)

This function ends the specified appearance effect on the character.

The active particles of the effect will go to completion. Use stop_all_appearance_effects() to immediately stop effects, including their active particles.

If the effect hasn't been started, nothing happens.

Parameters

effect	name of appearance effect to be ended
override_link	optional override link effect is attached to

Pass "all" for the effect argument to end all of this character's appearance effects.

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::stop_appearance_effect	(	const char *	effect,
		const char *	override_link = NULL
	)

This function stops the specified appearance effect on the character.

The active particle systems of the effect will immediately be removed. Use end_appearance_effect() to gradually stop effects; that function lets active particles move to completion.

If the effect hasn't been started, nothing happens.

Parameters

effect	name of appearance effect to be ended
override_link	optional override link effect is attached to

Pass "all" for the effect argument to stop all of this character's appearance effects.

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::stop_all_appearance_effects

(

)

Equivalent to stop_appearance_effect("all");.

int diguyCharacter::appearance_effect_is_active	(	const char *	effect,
		const char *	override_link = NULL
	)

This function checks to see if the specified appearance effect has been started with begin_appearance_effect().

Parameters

effect	name of appearance effect to check
override_link	optional override link effect is attached to

Returns:

1 if appearance is active, 0 if not

diguyChainSimulation* diguyCharacter::get_chain_simulation

(

)

This function returns a pointer to a diguyChainSimulation if the character is a chain_simulation type of character.

Returns:

pointer to a diguyChainSimulation

diguyVehicleController* diguyCharacter::get_vehicle_controller

(

)

This function returns a pointer to a diguyVehicleController if the character has one.

Returns:

pointer to a diguyVehicleController; may return NULL if character does not have a vehicle controller object

int diguyCharacter::get_vehicle_body_orientation	(	float *	rz,
		float *	rx,
		float *	ry
	)

For most characters playing a travel forward action, the character's facing direction matches the direction of travel.

For example, when humans walk forward their pelvis is generally aligned in the direction of travel.

Some vehicle characters behave differently. For vehicles whose front wheels steer, when turning the vehicle body will pivot around the rear axle. Only gradually will the rear of the vehicle swing in behind the direction of travel. Think of a car making a very sharp turn, and how the rear of the car swings in behind the front as the turn is completed.

This function will return the orientation of the body of the vehicle; i.e., the orientation of the forward vector along the vehicle's long axis. As mentioned above this may be different than the orientation of the direction of travel.

This function will return valid results for all characters, though the returned values from this function and that of get_orientation() will be the same for non-vehicle characters.

Returns:

0 on success, -1 on failure

int diguyCharacter::set_render_mode_shader	(	const char *	shader_name,
		const char *	render_mode = NULL
	)

This function sets the name of the shader program that will be used by the character when the scenario is using the specified render mode.

See diguyScenario::set_current_render_mode().

Note that care should be taken when changing the shader of characters with skinned appearances. A shader capable of properly transforming vertices must be used for such characters.

The shader with the given name should be loaded first. If the shader program is not one of DI-Guy's stock shaders, a custom shader program can be loaded explicitly by calling the diguyApp::load_shader_program() function.

NOTE:

The specified shader program may not take effect immediately, if the scenario's current render mode is different than the passed render mode. See diguyScenario::set_current_render_mode().

Parameters

shader_name	shader program name; can be NULL
render_mode	render mode to modify; passing NULL will modify shader "normal" render mode

Returns:

0 on success, -1 on failure

void diguyCharacter::reset_render_mode_shader_to_default

(

const char *

render_mode = NULL

)

This function resets the shader program for the specified render mode to its default.

This will be the shader program name returned by diguyScenario::get_default_character_shader_program_name().

If the specified render mode is the current scenario render mode, the current shader will change immediately. If not, the change will not take effect until the specified render mode becomes the current scenario render mode. See diguyScenario::set_current_render_mode().

Parameters

render_mode

render mode to modify; passing NULL will modify shader of "normal" render mode

const char* diguyCharacter::get_render_mode_shader

(

const char *

render_mode = NULL

)

This function returns the name of the shader that will be used by the character when the scenario is using the specified render mode.

Parameters

render_mode

render mode for which to get program name; pass NULL for "normal" render mode

Returns:

name of shader program; NULL if none or error

diguyGraphicsShaderProgram* diguyCharacter::get_shader_program

(

)

This function returns the shader program that is in use by the character.

Shader programs are shared objects that can be used by multiple characters.

Returns:

object of type diguyGraphicsShaderProgram; NULL if none

int diguyCharacter::set_temporary_current_shader

(

const char *

shader_name

)

This function overrides the current shader with the specified temporary shader.

This temporary shader will remain in effect until:

• the scenario is reset
• reset_current_shader_to_default() is called
• set_temporary_current_shader() is called with NULL

Parameters

shader_name

shader name; can be NULL

Passing NULL for the shader name will un-set the temporary shader, resetting the render mode shader to its default.

Returns:

0 on success, -1 on failure

void diguyCharacter::reset_current_shader_to_default

(

)

This is a convenience function for resetting the current render mode shader to its default.

It is equivalent to retrieving the current render mode using diguyScenario::get_current_render_mode(), and calling reset_render_mode_shader_to_default() with that render mode.

void diguyCharacter::trigger_shader_refresh

(

)

This is a convenience function for refreshing the shader of a character.

Usually used in conjunction with logic provided by the user with the graphics API.

diguyGraphicsShaderInstance* diguyCharacter::get_shader_instance

(

)

This function returns the shader instance that is in use by the character.

Each character has its own shader instance.

Note that the shader instance of a character can change over the lifetime of the character. For example, it will change if the appearance of the character changes. Therefore the returned pointer should not be stored, but should be re-read each time it is needed.

Returns:

object of type diguyGraphicsShaderInstance; NULL if none

void diguyCharacter::reset_shader_instance_variables_to_initial_values

(

)

This function resets current values of the variables of the shader back to their initial reset values.

void diguyCharacter::reset_shader_instance_variables_to_program_defaults

(

)

This function resets the current and initial values of variables of the shader to the built-in DI-Guy configuration defaults.

int diguyCharacter::agent_attack_character

(

const char *

character_name

)

This function sets the named character as the attack target of this agent.

This agent will pursue the target until it is within range, and then will fire its weapon in an attempt to kill the target.

This function will implicitly put this agent into the attack behavior.

The current focus character will be set the specified character. Pass NULL or the empty string ("") to not change the focus character, but still change to the pursue behavior.

The current focus group will be un-set.

Parameters

character_name

character to attack

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::agent_attack_group

(

const char *

group_name

)

This function is similar to agent_attack_character(), but instead will choose attack targets from the characters in the specified group.

This function will implicitly put this agent into the attack behavior.

The current focus group will be set to the specified group. Pass NULL or the empty string ("") to not change the focus group, but still change to the attack behavior.

The current focus character will be un-set.

Parameters

group_name

name of group from which attack targets should be chosen

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::agent_set_attack_zone_enabled

(

int

use_attack_zone

)

See diguyAgentParams::set_attack_zone_enabled().

int diguyCharacter::agent_get_attack_zone_enabled

(

)

See diguyAgentParams::get_attack_zone_enabled().

int diguyCharacter::agent_set_attack_zone	(	float	x,
		float	y,
		float	z,
		float	radius
	)

See diguyAgentParams::set_attack_zone().

int diguyCharacter::agent_get_attack_zone	(	float *	x,
		float *	y,
		float *	z,
		float *	radius
	)

See diguyAgentParams::get_attack_zone().

int diguyCharacter::agent_flee_character	(	const char *	character_name,
		float	distance,
		int	danger_level = 50
	)

This function adds a flee object to this agent.

This agent will attempt to move away from the specified character until it is beyond the specified flee distance.

**

Note

Currently there can only be one flee object. This restriction will be lifted in a future version.

This function will implicitly put this agent into the flee behavior.

Neither the current focus character nor group will be changed by this function.

Parameters

character_name	character from which to flee
distance	minimum distance to move away from character
danger_level	how "strong" the flee should be; set from 0 to 100

The danger_level argument is not currently used, but will be in a future version.

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::agent_flee_group	(	const char *	group_name,
		float	distance,
		int	danger_level = 50
	)

This function adds a flee object to this agent.

This agent will attempt to move away from the specified group until it is beyond the specified flee distance.

This function will implicitly put this agent into the flee behavior.

Neither the current focus character nor group will be changed by this function.

Parameters

group_name	group from which to flee
distance	minimum distance to move away from character
danger_level	how "strong" the flee should be; set from 0 to 100

The danger_level argument is not currently used, but will be in a future version.

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::agent_flee_crowd	(	const char *	crowd_name,
		float	distance,
		int	danger_level = 50
	)

This function is similar to agent_flee_group(), but the agent will instead flee the members of the specified crowd.

int diguyCharacter::agent_flee_location	(	float	x,
		float	y,
		float	z,
		float	distance,
		int	danger_level = 50
	)

This function adds a flee object to this agent.

This agent will attempt to move away from the specified location until it is beyond the specified flee distance.

**

Note

Currently there can only be one flee object. This restriction will be lifted in a future version.

This function will implicitly put this agent into the flee behavior.

Neither the current focus character nor group will be changed by this function.

Parameters

x,y,z	location from which to flee
distance	minimum distance to move away from character
danger_level	how "strong" the flee should be; set from 0 to 100

The danger_level argument is not currently used, but will be in a future version.

Returns:

0 on success, -1 on failure

void diguyCharacter::agent_remove_all_flee_objects

(

)

This function removes all flee objects.

This function has no effect on current behavior.

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::agent_mingle_in_region	(	const char *	region_name = "(current)",
		const char *	subregion_name = "base"
	)

This function puts this agent into the mingle behavior, in which it will choose semi-random points in the specified region and subregion to move to.

The agent will remain at the selected points for some amount of time, and the select a new point.

If all members of a crowd have this behavior they will tend to get together in small groups.

Use diguyAgentParams::set_move_on_t_min() and diguyAgentParams::set_move_on_t_max() for setting how long the agent will remain at the selected mingle points.

Parameters

region_name	region in which to mingle
subregion_name	subregion in which to mingle

The behavior region will be set the specified region. Pass NULL or "(current)" to not change the current behavior region.

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::agent_wander_region	(	const char *	region_name = "(current)",
		const char *	subregion_name = "base"
	)

This function is similar to agent_mingle_in_region(), but agents will pick completely random points and not try to clump together in small groups.

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::agent_pursue_character

(

const char *

character_name

)

This function will cause this agent to pursue the specified character.

This agent will attempt to move toward the specified character until it is within its still distance as specified in its agent params.

This function will implicitly put this agent into the pursue behavior.

The current focus group will be set to the specified group. Pass NULL or the empty string ("") to not change the focus group, but still change to the attack behavior.

The current focus character will be un-set.

Parameters

character_name

character to pursue

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::agent_pursue_character_with_offset	(	const char *	character_name,
		float	offset_x,
		float	offset_y
	)

This function is similar to agent_pursue_character(), but the point toward the agent will move will be offset from the pursued character by the passed offset.

int diguyCharacter::agent_pursue_group

(

const char *

group_name

)

This function is similar to agent_pursue_character(), but instead will choose pursue characters from the characters in the specified group.

This function will implicitly put this agent into the pursue behavior.

The current focus group will be set to the specified group. Pass NULL or the empty string ("") to not change the focus group, but still change to the pursue behavior.

The current focus character will be un-set.

Parameters

group_name

name of group from which pursue characters should be chosen

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::agent_call_formation	(	const char *	formation_name,
		float	target_x,
		float	target_y
	)

Calls a formation with this character as a leader, oriented towards (target_x, target_y).

Returns:

0 on success, -1 on failure

int diguyCharacter::agent_travel_behavior_path	(	const char *	direction = NULL,
		const char *	at_end = NULL,
		int	waypoint_index = -1,
		float	offset_y = 0.5f
	)

This function has the character travel along its behavior path shape, typically to the end and then back to the beginning.

It will put the agent into the travel behavior.

Parameters

direction	should be either "forward" or "backward"; pass NULL for default forward
at_end	what to do when end of path reached
waypoint_index	index of waypoint to start at; -1 for nearest,
2	for random
offset_y	sideways offset from behavior path

Valid values for at_end are:

• "reverse"
• "loop"
• "stop"

• "teleport"

  See the documentation for diguyNavPathAtEnd for information on what each value means.

int diguyCharacter::agent_travel_path_shape	(	const char *	path_shape_name,
		const char *	direction = NULL,
		const char *	at_end = NULL,
		int	waypoint_index = -1,
		float	offset_y = 0.5f
	)

Similar to agent_travel_behavior_path(), but specific path can be set rather than using behavior path.

int diguyCharacter::agent_travel_region_border	(	const char *	region_name = NULL,
		const char *	subregion_name = "base"
	)

The agent will create a travel path around the border of the region specified.

A CALLBACK_ID_AGENT_TRAVEL_FORWARD_DEST_REACHED callback will be triggered every time a character completes a loop around the border.

Parameters

region_name	the name of the region to patrol; leaving blank or passing NULL will use the agent's current region
subregion	name of the subregion to use; defaults to the base subregion

Returns:

0 on success, -1 on failure

int diguyCharacter::agent_move_to_point	(	float	x,
		float	y,
		float	z,
		const char *	via_region = NULL,
		const char *	subregion_name = "base"
	)

Agent will attempt to create a navigation path on the via_region and then travel it.

An A* path planning algorithm is used to find the path, cost preferences from the character's current diguyAgentParams are used in the search.

**

Note

as of DI-Guy 12 there is a version of this function agent_move_to_point_bg() that uses a multi-threaded infrastructure. We strongly recommend using it for future developments.

Parameters

x,y,z	the target location
via_region	the name of the region to run A* on (pass in "*" to have the code attempt to find the nearest region automatically.)
subregion_name	the name of the subregion to restrict search to

Returns:

0 on success, -1 on failure

int diguyCharacter::agent_move_to_point_bg	(	float	x,
		float	y,
		float	z,
		const char *	via_region = NULL,
		const char *	subregion_name = "base"
	)

A multi-threaded version of agent_move_to_point().

See that function for more information.

We recommend switching to using this over the single threaded version. When the path result has been computed a callback with id CALLBACK_ID_AGENT_PATH_PLAN_COMPLETED is triggered and the result is stored in get_path_planning_result(). You can also poll for completion via get_is_path_planning().

Returns:

diguyNavPathSearchResults enum value

The return value is typically DIGUY_NAV_PATH_ERROR_NONE (0) on success, DIGUY_NAV_PATH_ERROR_SEARCH_QUEUED if this has been queued for multi-threading, or a negative value on failure.

int diguyCharacter::agent_move_to_point_via_subregions	(	float	x,
		float	y,
		float	z,
		const char *	via_region = NULL,
		int	preferred_subregions_mask = DIGUY_SUBREGION_MASK_NONE,
		float	cost_bias_for_preferred_regions = 0.25f,
		float	cost_bias_for_neutral_regions = 1.1f,
		int	repulsed_regions_mask = DIGUY_SUBREGION_MASK_NONE,
		float	cost_bias_for_repulsed_regions = 10.0f,
		int	cost_rule = 0
	)

Agent will attempt to create a navigation path on the region via_region and then travel it.

An A* path planning algorithm is used to find the path.

The subregion masks are used to specify which subregions to use or avoid. Cost bias values can be used to make tweak how strong the repulsion values are.

**

Note

As of DI-Guy 12 there is a version of this function agent_move_to_point_via_subregions_bg that uses a multi-threaded infrastructure. We strongly recommend using it for future developments.

This function will fail and return -1 if a path cannot be found.

Parameters

x,y,z	the target location
via_region	the name of the region to run A* on (pass in "*" to have the code attempt to find the nearest region automatically)
preferred_subregions_mask	diguySubregionMask value of regions preferred for travel
cost_bias_for_preferred_regions	how much cheaper it will be to cross spaces that are part of desired subregion; should be < 1.0
cost_bias_for_neutral_regions	how much more expensive it will be to cross spaces that are not part of desired subregion; see below for more information
repulsed_regions_mask	diguySubregionMask value of regions not preferred for travel
cost_bias_for_repulsed_regions	how much more expensive it will be to cross regions that are marked as repulsive; pass DIGUY_DEFAULT_FLOAT to avoid completely

Pass DIGUY_DEFAULT_FLOAT for cost_bias_for_neutral_regions and cost_bias_for_repulsed_regions to specify that they should be avoided completely.

The preferred_subregions_mask and repulsed_regions_mask use DI-Guy subregion mask values combined together. For example, DIGUY_SUBREGION_MASK_SIDEWALK | DIGUY_SUBREGION_MASK_CROSSWALK.

For cost_bias_for_neutral_regions, specifying a non-zero value for this lowers the likelihood that searches fail on disjointed subregions. A value < 1 will cause the planner to run faster but explore fewer points, possibly missing preferred regions. Values greater then 1 will explore more points but will be slower.

NOTE:

THIS API has changed for DI-GUY 11.

cost_bias_for_preferred_regions has been added and the neutral and repulsed default values have changed.

Returns:

0 on success, -1 on failure

int diguyCharacter::agent_move_to_point_via_subregions_bg	(	float	x,
		float	y,
		float	z,
		const char *	via_region = NULL,
		int	preferred_subregions_mask = DIGUY_SUBREGION_MASK_NONE,
		float	cost_bias_for_preferred_regions = 0.25f,
		float	cost_bias_for_neutral_regions = 1.1f,
		int	repulsed_regions_mask = DIGUY_SUBREGION_MASK_NONE,
		float	cost_bias_for_repulsed_regions = 10.0f,
		int	cost_rule = 0
	)

A multi-threaded version of agent_move_to_point_via_subregions().

We recommend switching to using this over the single threaded version. When the result is found a CALLBACK_ID_AGENT_PATH_PLAN_COMPLETED is triggered and the result is stored in get_path_planning_result(), you can also poll for completion via get_is_path_planning().

Returns:

diguyNavPathSearchResults enum value

The return value is typically DIGUY_NAV_PATH_ERROR_NONE (0) on success, DIGUY_NAV_PATH_ERROR_SEARCH_QUEUED if this has been queued for multi-threading, or a negative value on failure.

int diguyCharacter::get_path_planning_result

(

)

Returns: diguyNavPathSearchResults value after agent_move_to_point_bg() or agent_move_to_point_via_subregions_bg() has been called when the multi-threaded path planner has completed.

int diguyCharacter::get_is_path_planning

(

)

Returns: 1 if character is currently waiting for a result from the multi-threaded path planner, else 0.

int diguyCharacter::agent_move_to_region	(	const char *	region,
		const char *	subregion_name = "base",
		const char *	via_region = NULL
	)

Agent will attempt to create a navigation path on the via_region to a point in the target region, and then travel it.

An A* path planning algorithm is used to find the path. Cost preferences from the character's current diguyAgentParams are used in the search.

Parameters

region	target region
subregion_name	target subregion
via_region	name of the region travel in

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::agent_move_to_region_via_subregions	(	const char *	region_name,
		const char *	subregion_name = "base",
		const char *	via_region = NULL,
		float	cost_bias_for_preferred_regions = 0.25f,
		int	preferred_subregions_mask = DIGUY_SUBREGION_MASK_NONE,
		float	cost_bias_for_neutral_regions = 1.1f,
		int	repulsed_regions_mask = DIGUY_SUBREGION_MASK_NONE,
		float	cost_bias_for_repulsed_regions = 10.0f
	)

Similar to agent_move_to_point_via_subregions(), but for moving to another region.

NOTE:

THIS API has changed for DI-GUY 11.

cost_bias_for_preferred_regions has been added and the neutral and repulsed default values have changed.

See Also:

diguyScenario::set_max_distance_planning_multiplier(); diguyScenario::get_time_spent_path_planning_this_frame();

Returns:

0 on success, -1 on failure

int diguyCharacter::agent_path_follow

(

const char *

path_name

)

The agent will begin following the specified path, using the path follow behavior (DIGUY_AGENT_BEHAVIOR_PATH_FOLLOW).

The path follow behavior allows an agent to approximately follow a diguyCharacterPath without being in path position mode. The agent can respond to external stimuli (e.g., run away from gunfire), and later return to and resume the path.

Currently the path must be a path previously defined for the character, through either DI-Guy Scenario or via path API calls.

Parameters

path_name

name of a path of this character

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::agent_resume_path_follow

(

)

The agent will resume following the path specified by a previous call to agent_path_follow().

This will put the agent back into the path follow behavior.

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

diguyCharacterPath* diguyCharacter::agent_get_path_follow_path

(

)

Returns: the path being followed in path behavior mode.

float diguyCharacter::agent_get_path_follow_path_t

(

)

In path follow behavior the agent moves along the path specified in agent_path_follow().

How far along the agent is on the path is specified in seconds. This function returns that time.

Note that advancing along the path may be paused for some reason, typically because the agent is resuming path follow behavior after being in a different behavior, or the agent is too far away from the current desired position on the path. In this case the returned time may not advance for awhile until the agent is close enough to the path to resume advancing along it.

Call diguyAgentParams::set_path_follow_pause_t_when_off_path() to set whether time will be paused when off of the path.

Call diguyAgentParams::set_path_follow_unpause_t_at_radius() to set how close the agent must be to the last point on the path before time will resume.

Returns:

how far, in seconds, the agent is along its path follow path

int diguyCharacter::agent_get_path_follow_path_t_paused

(

)

Returns: 1 if time along the path is not advancing, else 0.

diguyCrowd* diguyCharacter::agent_get_crowd

(

)

Returns: the crowd this agent is a part of, if any; returns NULL if not in a crowd.

int diguyCharacter::agent_begin_behavior

(

const char *

behavior_name

)

This function allows the end user to directly change an agent's current behavior.

This function currently the only way to start an agent "idling".

int diguyCharacter::agent_stop_behavior

(

)

This function sets the behavior of the agent to "none".

int diguyCharacter::agent_set_current_focus_character

(

const char *

character_name

)

This function is a convenience function that changes the focus character of this agent's current crowd params.

This can also be done by getting the character's current params using get_agent_current_params(), and then calling set_focus_character() on that object. This function call, however, is available in decisions.

The agent currently need not be part of a crowd for this function to work.

Parameters

character_name	name of character to become new focus
character;	pass NULL or "" to un set the focus character

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

diguyCharacter* diguyCharacter::agent_get_current_focus_character

(

)

This function returns the current character this agent is focused on.

This will either be the character named by the focus character, or the character chosen from the focus group to be the current focus character.

The agent currently need not be part of a crowd for this function to work.

Returns:

pointer to type diguyCharacter

int diguyCharacter::agent_set_current_focus_group

(

const char *

group_name

)

Similar to set_current_focus_character(), but sets the current focus group instead of character.

The agent currently need not be part of a crowd for this function to work.

Parameters

group_name	name of group to become new focus
group;	pass NULL or "" to un set the focus group

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

diguyAgentParams* diguyCharacter::agent_get_initial_params

(

)

This function returns the initial agent parameters of this agent.

The initial parameters of this agent can then be edited through this object.

Changes to the initial parameters will have no effect until the scenario is reset.

The current agent parameters will be set to these initial parameters whenever the scenario is reset.

The agent currently need not be part of a crowd for this function to work.

Returns:

pointer to type diguyAgentParams

diguyAgentParams* diguyCharacter::agent_get_current_params

(

)

This function returns the current agent parameters of this agent.

The current parameters of this agent can then be edited through this object.

Changes to the current parameters should take effect immediately.

The current agent parameters will be reset to the initial parameters whenever the scenario is reset.

The agent currently need not be part of a crowd for this function to work.

Returns:

pointer to type diguyAgentParams

const char* diguyCharacter::agent_get_current_params_profile_name

(

)

This function gets the name of the agent's current profile.

Returns:

the name of the agent's current profile

int diguyCharacter::agent_set_current_params_from_profile	(	const char *	profile_name,
		int	retain_focus_objects = 1,
		int	retain_navigation_values = 1,
		int	retain_behavior = 0
	)

This function sets this agent's current agent parameters from the specified crowd profile.

The agent currently need not be part of a crowd for this function to work.

Parameters

profile_name	name of existing crowd profile
retain_focus_objects	pass 1 to not change focus object from current focus
retain_navigation_values	pass 1 to not change current navigation parameters
retain_behavior	pass 1 to not change current behavior

Navigation values are things like:

• behavior path
• behavior region and subregion
• region masks
• cost biases
• path planner settings

Returns:

0 on success, -1 on failure

Available as Decision Bead/Event

int diguyCharacter::agent_set_initial_params_from_profile

(

const char *

profile_name

)

Similar to agent_set_current_params_from_profile(), but initial parameters are changed.

void diguyCharacter::agent_set_current_params_from_initial_params

(

)

This function sets the current parameters from the agent's initial parameters.

void diguyCharacter::agent_set_current_behavior_region_border_is_solid

(

int

is_solid

)

This function sets whether the borders of the current behavior region of the agent is solid.

If they are, the agent will treat the walls as if they are solid walls in the environment. If not, the agent is free to walk through them.

The agent currently need not be part of a crowd for this function to work.

Parameters

is_solid

1 if region border should be solid, 0 if not

Available as Decision Bead/Event

void diguyCharacter::agent_move_on

(

)

If the agent is in a behavior that stays in one place before moving to another, such as wander or mingle, this function will request that the agent move on to the next location.

Available as Decision Bead/Event

int diguyCharacter::agent_set_auto_variant_selection

(

int

selection_enabled

)

This function controls if the AI will attempt to automatically change variants depending on the behavior.

This should only change how still motions are performed when the default variant is Normal. Characters in wander and idle will automatically shift to ambient still motions, mingle will alternate between socialize and ambient motions. Attack should automatically switch from aiming to ambient. defaults to being on.

int diguyCharacter::agent_get_auto_variant_selection

(

)

Returns if automatic variant selection is enabled, defaults to being on.

diguyPathShape* diguyCharacter::agent_get_current_traveled_path

(

)

Returns current travel path or nav path.

void diguyCharacter::agent_set_use_speed_zones_on_paths

(

int

enabled

)

Allows agent to determine speed zone based on distance to endpoint of current path.

With this off, speed zones are determined by "desired position", which when following a path is not the endpoint, but a point on the path a short distance ahead of the current position.

The default value is false.

Enable this if you want the character to automatically run when following a long path.

int diguyCharacter::agent_get_use_speed_zones_on_paths

(

)

Returns the current value set by agent_set_use_speed_zones_on_paths().

int diguyCharacter::agent_set_feeler_function

(

diguyFeelerFunction *

feeler_function

)

This function sets a feeler function that will be used by this character for environment collision detection.

The feeler will replace any existing feeler function (including the default function used in DI-Guy Scenario).

See the "User-Defined Feelers" information for more information.

Parameters

feeler_function

pointer to user-defined feeler function

Returns:

0 on success, -1 on failure

Callable From:

• C++

diguyFeelerFunction* diguyCharacter::agent_get_feeler_function

(

)

Returns: current feeler function; see set_feeler_function()

Callable From:

• C++

int diguyCharacter::create_lua_mind	(	const char *	base_class,
		const char *	init_arg1 = NULL,
		const char *	init_arg2 = NULL
	)

Creates a Lua mind object based off of the contents of base_class.

Parameters

base_class	the class to use as the basis for the character's mind
init_arg1	2 - experimental optional arguments passed to the init function; your lua init function will need to take arguments

const char* diguyCharacter::get_mind_name

(

)

Returns the name of the mind, e.g.

"luaPedestrian". This is, in other words, the mind's base class

const char* diguyCharacter::get_mind_current_state_name

(

)

Agent characters with minds will typically have the mind be in some state, such as "patrolling", "fleeing", "mobbing", etc.

This function returns the name of that state.

Currently this is only applicable to characters with Lua minds.

Returns:

the name of the agent's current mind state

void diguyCharacter::do_mind_current_state_changed_callback

(

)

This function causes callback functions with the callback id CALLBACK_ID_AGENT_MIND_CURRENT_STATE_CHANGED to be called.

It's intended use is for mind implementations that need to signal that the mind's current state has changed.

Currently this is only applicable to characters with Lua minds.

int diguyCharacter::set_sleep_timer

(

float

sleep_length

)

How long until the character's main coroutine thread should be resumed.

This function is typically used by various luaCharacter sleep functions.

Parameters

sleep_length

how long relative to the current time the character should sleep

float diguyCharacter::get_sleep_timer

(

)

Returns: How long until the character's main coroutine thread resumes, relative to the current time.

int diguyCharacter::set_heartbeat_dt

(

float

heartbeat_dt

)

The frequency at which the luaCharacter's heartbeat function should run.

This defaults to once per second. The character must have a Lua function named heartbeat.

Parameters

heartbeat_dt

frequency of heartbeat

int diguyCharacter::add_secondary_heartbeat	(	const char *	function_name,
		float	heartbeat_dt
	)

This function allows the addition of additional heartbeat functions.

Parameters

function_name	the name of the Lua function to treat as a heartbeat; the function_name should not include the name of the character object
heartbeat_dt	frequency of heartbeat

Returns:

0 on success, -1 on failure

int diguyCharacter::remove_secondary_heartbeat

(

const char *

function_name

)

This function removes an added heartbeat function.

Parameters

function_name

the name of the Lua function to treat as a heartbeat; the function_name should not include the name of the character object

Returns:

0 on success, -1 on failure

int diguyCharacter::set_secondary_heartbeat_dt	(	const char *	function_name,
		float	heartbeat_dt
	)

The frequency at which a luaCharacter's secondary heartbeat function should run.

The character must have a Lua function named function_name.

Parameters

function_name	heartbeat function to adjust
heartbeat_dt	frequency of heartbeat

Returns:

0 on success, -1 on failure

int diguyCharacter::add_wakeup_callback

(

int

callback

)

This function creates a request that whenever the specified callback is triggered, the character is woken up with a message.

The message will be of the form:

• message_type = "callback"

• message = the string representation of the callback

  A good example of the use for this is a flexible "move to" command:

Lua Example:

self.character:add_wakeup_callback(diguyCharacter_CALLBACK_ID_AGENT_TRAVEL_FORWARD_DEST_REACHED);
-- begin to move to a location
self.character:agent_move_to_region_via_subregions("navmesh", "green", "navmesh",
   DIGUY_SUBREGION_MASK_BASE, 12);
-- sleep till arrived
self:sleep(100);
self.character:remove_wakeup_callback(diguyCharacter_CALLBACK_ID_AGENT_TRAVEL_FORWARD_DEST_REACHED);

Effectively the character will wake up either after 100 seconds or when they arrive at their desired destination.

Parameters

callback

the callback id that should wake up the character

Returns:

0 on success, -1 on failure

int diguyCharacter::remove_wakeup_callback

(

int

callback

)

This function removes a request to trigger a message when a callback is triggered.

Parameters

callback

callback id that should no longer wake up the character

Returns:

0 on success, -1 on failure

int diguyCharacter::remove_all_wakeup_callbacks

(

)

This function removes all requests to trigger a message when callbacks are triggered.

Returns:

0 on success, -1 on failure

int diguyCharacter::has_wakeup_callback

(

int

callback

)

This function check for a requests to trigger a message when a given callback is triggered.

Returns:

0 on false, 1 on true

int diguyCharacter::agent_accept_message	(	const char *	sender,
		const char *	message_type,
		const char *	message,
		const char *	message_params = NULL
	)

This function wakes up a character and sends them a message.

Currently this is only applicable to characters with Lua minds.

Parameters

sender	who is sending the message
message_type	what type of message is being sent
message	the message string
message_params	optional parameter string

Returns:

number of times message was successfully parsed

int diguyCharacter::agent_broadcast_message	(	float	radius,
		const char *	message_type,
		const char *	message,
		const char *	message_params = NULL
	)

This function wakes up nearby characters and sends them a message.

The sender of the message is implicitly set to the individual calling the broadcast function

Currently this is only applicable to characters with Lua minds.

Parameters

radius	how far to broadcast the message
message_type	what type of message is being sent
message	the message string
message_params	optional parameter string

Returns:

number of times message was successfully parsed

int diguyCharacter::agent_broadcast_message_to_group	(	const char *	group_name,
		float	radius,
		const char *	message_type,
		const char *	message,
		const char *	message_params = NULL
	)

This function wakes up nearby characters in the group specified and sends them a message.

The sender of the message is implicitly set to the individual calling the broadcast function.

Currently this is only applicable to characters with Lua minds.

Parameters

group_name	group to broadcast message to
radius	how far to broadcast the message
message_type	what type of message is being sent
message	the message string
message_params	optional parameter string

Returns:

number of times message was successfully parsed, -1 on failure

const char* diguyCharacter::get_lua_object_name

(

)

Returns: name of character's lua mind object; typically this is the character's name with '-' replaced by '_'.

void diguyCharacter::set_mind_field_as_string	(	const char *	field_name,
		const char *	field_value
	)

Sets the specified field of the mind to the string field_value.

const char* diguyCharacter::get_mind_field_as_string	(	const char *	field_name,
		int	warn_if_no_field = 1
	)

Queries the luaCharacter object for a specific field, and attempts to convert it into a string.

This works for strings and numbers.

This returned pointer will stay valid until the next time this function is called, so if the results need to be saved they must be copied.

Returns:

field_name as string

void diguyCharacter::set_mind_field_as_float	(	const char *	field_name,
		float	field_value
	)

Sets the specified field of the mind to the floating point number field_value.

float diguyCharacter::get_mind_field_as_float	(	const char *	field_name,
		int	warn_if_no_field = 1,
		int *	found_field = NULL
	)

Similar to get_mind_field_as_string(), but returns field as a float.

Returns:

field_name as double

void diguyCharacter::set_mind_field_as_int	(	const char *	field_name,
		int	field_value
	)

Sets the specified field of the mind to the integer number field_value.

int diguyCharacter::get_mind_field_as_int	(	const char *	field_name,
		int	warn_if_no_field = 1,
		int *	found_field = NULL
	)

Similar to get_mind_field_as_int(), but returns field as an integer.

Returns:

field_name as int

const char* diguyCharacter::evaluate_mind_function	(	const char *	function_name,
		const char *	argument = NULL,
		int	has_return_string = 0
	)

Attempts to run a luaCharacter member function, and can optionally return the function's result.

Lua return values can be converted to strings and numbers – other data types will cause an error.

This returned pointer will stay valid until the next time this function is called, so if the results need to be saved they must be copied.

Note: This function should be considered experimental, as the API may change.

Parameters

function_name	luaCharacter function field to invoke
argument	optional string argument to the function
has_return_string	0 or 1; determines if lua interface should attempt to retrieve a string value

Returns:

Lua function return value

const char* diguyCharacter::get_ai_state_string	(	int	include_stack = 1,
		int	include_locals = 1
	)

This function produces a string with a long list of character information, including: current path, crowd, behavior, lua state, lua call stack, wakeup callbacks and lua object fields.

It is meant to help with debugging agents.

This returned pointer will stay valid until the next time this function is called, so if the results need to be saved they must be copied.

Parameters

include_stack	pass 1 to include callstack info, 0 to not
include_locals	pass 1 to include local variable info, 0 to not

Returns:

string containing character information

int diguyCharacter::check_character_visibility	(	diguyCharacter *	character,
		int	los_check_type = 0
	)

This function tests whether this character can see the passed character.

Currently this tests if the cervical link of this character has a clear line of sight to either the cervical or the position links of the target. Currently the orientation of this character isn't factored in.

This function does not fail if other characters are between the two characters in question.

Checking visibility is only an option if an octtree is generated from scene objects; typically only DI-Guy Scenario does this. Outside of DI-Guy Scenario set_character_los_function() should be used if no octtree is present.

Parameters

character	character to check
los_check_type	currently unused but passed to callback function if end users wish to pass an additional parameter

Returns:

1 if character is visible, 0 if not

int diguyCharacter::check_point_visibility	(	float	x,
		float	y,
		float	z
	)

This function tests whether this character can see the x, y, z location specified.

Currently this tests if the cervical link of this character has a clear line of sight to the x, y, z location. Currently the orientation of this character isn't factored in.

This function does not fail if other characters are between the character and the location in question.

Checking visibility is only an option if an octtree is generated from scene objects; typically only DI-Guy Scenario does this.

Parameters

x,y,z

location to check

Returns:

1 if location is visible, 0 if not

int diguyCharacter::set_point_los_function

(

diguyPointLOSFunction *

point_los_function

)

When a character needs to check if it can see a location, DI-Guy calls this function with a pointer to the diguyCharacter in question, and the coordinates of the point that is being looked at.

This currently happens when an agent is told to move to a new region.

The following prototype should be used for the point line-of-sight function:

int diguyPointLOSFunction(diguyCharacter* character,
    float x,
    float y,
    float z);

The function should then check if the desired location is visible. This can be done in a number of ways; a typical approach is to do an intersection test with the static scene.

The function should return 1 if the path to the target is clear, 0 if there is an obstruction.

A default point line-of-sight function can be set for all subsequently created characters by calling diguyScenario::set_default_point_los_function().

Callable From:

• C++

diguyPointLOSFunction* diguyCharacter::get_point_los_function

(

)

Returns: current point line-of-sight function; see set_point_los_function()

Callable From:

• C++

int diguyCharacter::set_character_los_function

(

diguyCharacterLOSFunction *

character_los_function

)

When a character needs to check if it can see another character, DI-Guy calls this function with a pointer to the diguyCharacter in question.

This can happen when check_character_visibility() is invoked or when AI attack code assesses if it should take a shot.

The following prototype should be used for the character line-of-sight function:

int diguyCharacterLOSFunction(diguyCharacter* character,
    diguyCharacter* target_character,
    int los_test_type) // (currently unused)

Currently the los_test_type argument defaults to 0 and is not used internally. It is, however, available in check_character_visibility() and will be passed to the callback. This can be useful if the end user wants to write scripting code that has alternative Line of Sight tests depending on agent conditions. (e.g. a test that factors in the character's field of view.)

The function then checks if the target character is visible. This can be done in a number of ways; a typical approach is to do an intersection test with the static scene. The default implementation tests the path from the characters head to the target's head and then to the target's feet.

The function should return 1 if the path to the target is clear, and 0 if there is an obstruction.

A default character line-of-sight function can be set for all subsequently created characters by calling diguyScenario::set_default_character_los_function().

Callable From:

• C++

diguyCharacterLOSFunction* diguyCharacter::get_character_los_function

(

)

Returns: current character line-of-sight function; see set_character_los_function()

Callable From:

• C++

int diguyCharacter::get_num_ik_chains

(

)

Normally Returns 4.

const char* diguyCharacter::get_ik_chain_name_at_index

(

int

index

)

Should return one of the following: right_leg, left_leg, left_arm, right_arm.

int diguyCharacter::set_ik_target_world	(	int	ik_chain_target,
		float	x,
		float	y,
		float	z,
		float	ramp_time = .25f
	)

int diguyCharacter::set_ik_target_local	(	int	ik_chain_target,
		float	x,
		float	y,
		float	z,
		float	ramp_time = .25f
	)

int diguyCharacter::disable_ik_target	(	int	ik_chain_target,
		float	ramp_time = .25f
	)

void diguyCharacter::set_distance_to_primary_camera

(

float

camera_dist

)

float diguyCharacter::get_distance_to_primary_camera

(

)

Defaults to -1. see set_distance_to_primary_camera() for more info.

int diguyCharacter::set_initial_character_simulator

(

diguyCharacterSimulator

character_simulator

)

This function sets the initial character simulator this character will use.

The current simulator will be set to this value on scenario reset.

The current simulator can be set by calling set_current_character_simulator().

The default simulator is DIGUY_CHARACTER_SIMULATOR_DIGUY_MOTION_ENGINE.

Requires active physics module if character simulator is set to DIGUY_CHARACTER_SIMULATOR_PHYSICS_SIM_MODULE.

Parameters

character_simulator

which simulator to use at reset

Returns:

0 on success, -1 on failure

diguyCharacterSimulator diguyCharacter::get_initial_character_simulator

(

)

Returns: initial character simulator.

int diguyCharacter::set_current_character_simulator

(

diguyCharacterSimulator

character_simulator

)

This function sets the current character simulator this character will use.

The current simulator will be reset to the initial character simulator on scenario reset.

The initial simulator can be set by calling set_initial_character_simulator().

Parameters

character_simulator

new current character simulator

Returns:

0 on success, -1 on failure

diguyCharacterSimulator diguyCharacter::get_current_character_simulator

(

)

Returns: current character simulator.

int diguyCharacter::set_initial_physics_simulation_mode

(

diguyPhysicsSimulationMode

physics_simulation_mode

)

This function sets the initial physics simulation mode this character will use.

The current simulation mode will be set to this value on scenario reset.

The current simulation mode can be set by calling set_current_physics_simulation_mode().

The default simulation mode is DIGUY_PHYSICS_SIMULATION_MODE_SIM_DRIVES_CHARACTER.

The physics simulation mode will have no effect unless the current character simulator is DIGUY_CHARACTER_SIMULATOR_PHYSICS_SIM_MODULE.

Parameters

physics_simulation_mode

which simulation mode to use at reset

Returns:

0 on success, -1 on failure

diguyPhysicsSimulationMode diguyCharacter::get_initial_physics_simulation_mode

(

)

Returns: initial physics simulation mode.

int diguyCharacter::set_current_physics_simulation_mode

(

diguyPhysicsSimulationMode

physics_simulation_mode

)

This function sets the current physics simulation mode this character will use.

The current simulation mode will be reset to the initial physics simulator mode on scenario reset.

The initial simulation mode can be set by calling set_initial_physics_simulation_mode().

The physics simulation mode will have no effect unless the current character simulator is DIGUY_CHARACTER_SIMULATOR_PHYSICS_SIM_MODULE.

Parameters

physics_simulation_mode

new current physics simulation mode

Returns:

0 on success, -1 on failure

diguyPhysicsSimulationMode diguyCharacter::get_current_physics_simulation_mode

(

)

Returns: initial physics simulation mode.

int diguyCharacter::set_physics_collision_group

(

diguyPhysicsCollisionGroup

collision_group

)

This function sets the physics collision group this character will be in when being simulated.

For improved performance, collision detection between various characters and scene objects will not be performed, based on which collision groups the objects are in.

By default:

• characters in character group n collide against props in prop group n and scene objects in scene object group n in group n
• characters in group ghost don't collide against any other characters, but do against scene objects and props
• characters in group everything collide against all characters, props, and scene objects
• all props collide against all other props and scene objects

Collision group relationships can be modified using diguyApp::set_collision_group_detection_flag().

Parameters

physics_simulation_mode

new current physics simulation mode

Returns:

0 on success, -1 on failure

diguyPhysicsCollisionGroup diguyCharacter::get_physics_collision_group

(

)

Returns: physics collision group.

void diguyCharacter::set_stop_physics_sim_at_t

(

float

t

)

This function sets a time at which active simulation of a physics controlled character will stop.

This is useful for:

• reducing simulation processing overhead

• freezing a simulation that is mostly in steady state, but some small part remains oscillating

  The physics controlled character will remain frozen in the last computed simulated pose.

Parameters

t	scenario t at which simulation will freeze

t should be large enough for the simulation to reach a reasonably steady state, such as a human lying on the ground. A value that is usually reasonable is around 5 seconds.

void diguyCharacter::set_stop_physics_sim_in_t_seconds

(

float

relative_t

)

Similar to set_stop_physics_sim_at_t(), but the passed time will be relative to the current simulation time as returned by diguyScenario::get_t().

float diguyCharacter::get_stop_physics_sim_at_t

(

)

Returns: time at which physics simulation will freeze.

void diguyCharacter::apply_impulse_to_physics_sim	(	const char *	link,
		float	impulse_magnitude_x,
		float	impulse_magnitude_y,
		float	impulse_magnitude_z,
		float	link_offset_x = 0.0f,
		float	link_offset_y = 0.0f,
		float	link_offset_z = 0.0f,
		int	set_simulation_drives_character = 1
	)

This function applied an impulse force to the character.

An impulse is a force that is applied all at one time, such as an explosion shock wave.

Parameters

link	link to which impulse should be applied
impulse_magnitude_[xyz]	magnitude of impulse in x direction
link_offset_[xyz]	offset on link at which to apply impulse
set_simulation_drives_character	pass 1 to automatically change the character's current simulation mode to DIGUY_PHYSICS_SIMULATION_MODE_SIM_DRIVES_CHARACTER

void diguyCharacter::apply_impulse_to_physics_sim_from_world_position	(	const char *	link,
		float	impulse_magnitude_x,
		float	impulse_magnitude_y,
		float	impulse_magnitude_z,
		float	impulse_generator_position_x,
		float	impulse_generator_position_y,
		float	impulse_generator_position_z,
		float	max_distance = 20.0f,
		float	impulse_rolloff = 0.0f,
		float	link_offset_x = 0.0f,
		float	link_offset_y = 0.0f,
		float	link_offset_z = 0.0f,
		int	set_simulation_drives_character = 1
	)

Similar to apply_impulse_to_physics_sim(), but impulse can be calculated relative to a world position.

This is useful if, for example, a character should react to a nearby explosion.

Parameters

link	link to which impulse should be applied
impulse_magnitude_[xyz]	magnitude of impulse
impulse_generator_position_[xyz]	world coordinates of impulse generating object
max_distance	maximum distance from above position at which the impulse can affect this character
impulse_rolloff	how much the impulse magnitude should decrease as distance from impulse source increases
link_offset_[xyz]	offset on link at which to apply impulse
set_simulation_drives_character	pass 1 to automatically change the character's current simulation mode to DIGUY_PHYSICS_SIMULATION_MODE_SIM_DRIVES_CHARACTER

static int diguyCharacter::set_texture_load_behavior ( diguyGraphicsTextureLoadingBehavior  mode )

static

Sets texture load behavior to DIGUY_LOAD_INSTANTLY, DIGUY_LOAD_PRIORITY_ASYNC, or DIGUY_LOAD_ASYNC.

static diguyGraphicsTextureLoadingBehavior diguyCharacter::get_texture_load_behavior ( )

static

Returns current behavior, as set in set_texture_load_behavior()

static int diguyCharacter::set_max_shader_quality_level ( int  quality_level )

static

Sets maximum quality of shader to use (actual quality varies by distance from camera).

See diguyGraphicsShaderQualityLevel for possible values.

Parameters

quality_level

a value between DIGUY_GRAPHICS_SHADER_QUALITY_UNLIT and DIGUY_GRAPHICS_SHADER_QUALITY_MAX

static int diguyCharacter::get_max_shader_quality_level ( )

static

Returns: max shader quality level, as set by set_max_shader_quality_level()

int diguyCharacter::set_animation_events_enabled

(

int

enable

)

Documentation Pending.

int diguyCharacter::get_animation_events_enabled

(

)

int diguyCharacter::get_has_bump_maps

(

)

Returns 1 if the current appearance has bump maps.

int diguyCharacter::get_action_num_channels

(

const char *

action_name

)

This function returns how many channels the specified action has.

If an action has more than one channel, the relative weights of its channels can be set using the set_action_channel_weight() function.

Parameters

action_name

name of action to be queried

Returns:

number of channels in specified action

int diguyCharacter::set_action_channel_weight	(	const char *	action_name,
		char	channel,
		float	weight
	)

This function sets the weight one channel of a multi-channel action.

The passed weight should be between 0 and 1. The weights of the other channels in the action will be adjusted so that the total weight of all channels is 1.

Parameters

action_name	name of action to be affected
channel	which channel's weight to set
weight	weight of the channel, between 0 and 1

Returns:

0 on success, -1 on failure

float diguyCharacter::get_action_channel_weight	(	const char *	action_name,
		char	channel
	)

This function returns the weight of one channel of a multi-channel action.

Parameters

action_name	name of action to be queried
channel	which channel's weight to return

Returns:

weight of a channel

float diguyCharacter::get_time_to_reach_desired_action

(

)

This function returns the number of seconds before the transition to the desired action begins.

If the character is already performing the desired action the function returns 0.

THIS FUNCTION DOES NOT YET RETURN VALID RESULTS.

Returns:

time to reach desired action, in seconds

const char* diguyCharacter::get_type_map_field

(

diguyCharacterTypeMapField

field

)

Maps a character type map field to its value.

See diguyCharacterTypeMap.

Returns:

The value, as a string.

const char* diguyCharacter::get_type_map_field_using_string

(

const char *

field

)

Maps a character type map field to its value, using a string version (e.g.

"age") of the field name. See diguyCharacterTypeMap.

Returns:

The value, as a string.

int diguyCharacter::merge_object

(

const char *

object

)

This function performs a "micro merge", allowing a diguyCharacter to have objects added to it by parsing a .dss file fragment in the form of a string.

This function can be used, for example, to add paths to dynamically created agents. A Lua Package can contain a number of text strings representing local paths for agents. On character creation these strings can be merged in and turned into per-character objects.

The DI-Guy Scenario path page has a "Display Asset" button for generating merge_object() compatible strings.

There is also a diguyScenario::merge_object() function that allows the merging of text blocks that represent sounds and particle systems.

**

Note

the parser is very sensitive to tabs and formatting!

int diguyCharacter::is_active_character_in_group_visible	(	const char *	group_name,
		float	max_distance_to_check = 100000.0f
	)

Returns 1 if any active character in the named group is visible, otherwise 0.

group_name max_distance_to_check

int diguyCharacter::get_local_space_bounding_box	(	float *	x1,
		float *	y1,
		float *	z1,
		float *	x2,
		float *	y2,
		float *	z2
	)

Gets local space bounding box, this function is currently expensive and should be used with care.

Parameters

x1,y1,z1,x2,y2,z2

output parameters

Returns:

0 on success, -1 on failure (float * arguments converted to return values in Lua)

void diguyCharacter::set_mind_always_updates

(

int

force_update

)

This causes a character's mind to get an update call even if time isn't passing in the scenario.

This is occasionally useful for characters that are managing the UI.

Note that there is now a luaUIStateMachine that might be a better solution.

int diguyCharacter::get_mind_always_updates

(

)

Returns value set by set_mind_always_updates()

float diguyCharacter::get_angle_to_path	(	const char *	path_name,
		const char *	action_bead_name = NULL
	)

Returns angle in degrees from character's "forward facing" vector to the specified action bead, on the specified path.

void diguyCharacter::set_scene_graph_mask

(

unsigned int

mask

)

unsigned int diguyCharacter::get_scene_graph_mask

(

)

int diguyCharacter::set_use_texture_variations

(

int

value

)

Turns on texture modulation system that tries to make all characters look unique.

Only supported by some appearances currently.

int diguyCharacter::get_use_texture_variations

(

)

Returns: If texture variations have been enabled for this character.

Note: some characters now have texture variation

diguyMotionEngineSnapshot diguyCharacter::get_motion_engine_snapshot

(

)

Returns a structure that attempts to encode all the major variables that the motion engine is currently using to manage the primary action, and related transition values.

This function can be very useful for syncing character state in a multi-channel environment.

int diguyCharacter::apply_motion_engine_snapshot

(

const diguyMotionEngineSnapshot &

action_info

)

Applies the snapshot created by get_motion_engine_snapshot()

int diguyCharacter::set_local_to_world_orientation_matrix	(	float	rz,
		float	rx,
		float	ry
	)

documentation pending

int diguyCharacter::set_local_to_world_orientation_matrix	(	float	a0,
		float	a1,
		float	a2,
		float	b0,
		float	b1,
		float	b2,
		float	c0,
		float	c1,
		float	c2,
		int	transpose = 0
	)

int diguyCharacter::set_final_position_double	(	double	x,
		double	y,
		double	z
	)

int diguyCharacter::set_final_matrix	(	float	a0,
		float	a1,
		float	a2,
		float	a3,
		float	b0,
		float	b1,
		float	b2,
		float	b3,
		float	c0,
		float	c1,
		float	c2,
		float	c3,
		float	d0,
		float	d1,
		float	d2,
		float	d3
	)

int diguyCharacter::aim_converge

(

int

max_iterations = 30

)

void diguyCharacter::set_aim_algorithm

(

int

aim_algorithm

)

Currently, 8 is the only valid input for this function, makes DI-Guy use a version 8.0 style aim.

int diguyCharacter::get_aim_algorithm

(

)

Returns: current aim algorithm defaults to 8.

int diguyCharacter::speak

(

const char *

string

)

Deprecated as of 9.1.4.

In general setting the weapon sound should no longer be necessary, as weapon sounds are now specified by the weapon's munition type. If this function is called, it will have the same effect as calling diguyCharacter::set_weapon_sound_override(). Deprecated as of 12.0.0. Not supported in FaceFX.

int diguyCharacter::set_viseme	(	const char *	viseme_name,
		float	weight
	)

Deprecated as of 12.0.0.

Not supported in FaceFX.

float diguyCharacter::get_viseme

(

const char *

viseme_name

)

Deprecated as of 12.0.0.

Not supported in FaceFX.

int diguyCharacter::set_orientation_eye_left	(	float	azimuth,
		float	elevation
	)

Deprecated as of 12.0.0.

Not supported in FaceFX.

int diguyCharacter::set_orientation_eye_right	(	float	azimuth,
		float	elevation
	)

Deprecated as of 12.0.0.

Not supported in FaceFX.

float diguyCharacter::get_azimuth_eye_left

(

)

Deprecated as of 12.0.0.

Not supported in FaceFX.

float diguyCharacter::get_elevation_eye_left

(

)

Deprecated as of 12.0.0.

Not supported in FaceFX.

float diguyCharacter::get_azimuth_eye_right

(

)

Returns: the current azimuth of the right eye; see set_orientation_eyes()

float diguyCharacter::get_elevation_eye_right

(

)

Returns: the current elevation of the right eye; see set_orientation_eyes()

bdiScenarioCharacter* diguyCharacter::get_scripted_object

(

)

Friends And Related Function Documentation

friend class bdiPublishedCharacter

friend

friend class bdiScenarioCharacter

friend

friend class diguySensorRegion

friend

friend class diguyScenario

friend

Member Data Documentation

bdiScenarioCharacter* diguyCharacter::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/diguyCharacter.h