diguyCharacter

Generated from diguyCharacter.h

DI-Guy API Version 12.5.1

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

Contents:

Alphabetical Index

Link against: libdiguy

class diguyCharacter

class BDI_DECLSPEC_diguy diguyCharacter
{
public:
    const char* get_name();
    int set_name(const char* name);
    const char* get_type_name();
    long get_uid();
    int get_index();
    int update(float t, int full_update = 1);
    void set_character_type(const char* type);
    const char* get_character_type_string();
    const char* get_character_class();
    diguyScenario* get_scenario();
    int set_enabled(int enabled);
    int get_enabled();
    int set_drawn_by_scenario_flag(int flag);
    int get_drawn_by_scenario_flag();
    void set_invisible_flag(int invisible_flag);
    int get_invisible_flag();
    int get_is_active();
    int get_is_drawn();
    int get_is_temporary();
    int get_is_recycled();
    int set_t_controlled_by_scenario_t(int t_controlled_by_scenario_t);
    int get_t_controlled_by_scenario_t();
    int set_initial_tin(float tin, int override_time_warning = 0);
    int set_initial_tout(float tout);
    int set_current_tin(float tin);
    int set_current_tin_to_now();
    float get_current_tin();
    int set_current_tout(float tout,
        int disable_character_at_tout = 0);
    int set_current_tout_to_now();
    float get_current_tout();
    void set_tout_enabled(int tout_enabled);
    int get_tout_enabled();
    int set_careful_interpolation_threshold(float threshold);
    float get_careful_interpolation_threshold();
    int set_motion_interpolation_flag(int flag);
    int get_motion_interpolation_flag();
    int set_scale(float scale_x,
        float scale_y,
        float scale_z);
    int get_scale(float* scale_x,
        float* scale_y,
        float* scale_z);
    int set_parent(const char* parent_name,
        const char* parent_link_name = "");
    diguyCharacter* get_parent();
    const char* get_parent_link_name();
    int unset_parent();
    int get_num_children();
    diguyCharacter* get_child_at_index(int index);
    int get_is_scene_object();
    int set_is_scene_object(int is_scene_object);
    float get_bounding_radius();
    float get_default_bounding_radius();
    void set_bounding_radius(float f);
    float get_time_to_transition();
    diguyCharacterMode get_action_mode();
    diguyCharacterMode get_position_mode();
    int set_t_scale_factor(float t_scale_factor);
    int unset_t_scale_factor();
    int is_within_distance_n_of_character(const char* character_name,
        float distance);
    int is_within_distance_n_of_member_of_group(const char* group_name,
        float distance);
    int is_group_member(const char* group_name);
    int get_num_group_memberships();
    diguyCharacterGroup* get_group_membership_at_index(int index);
    diguyCharacter* get_nearest_active_character(int check_visibility,
        int xy_distance = 0,
        float max_distance_to_check = 100000);
    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);
    diguyCharacter* get_random_active_character(float max_distance = 10.0f,
        int check_visibility = 1,
        int xy_distance = 0);
    diguyCharacter* get_random_active_character_in_group(const char* group_name,
        float max_distance = 10,
        int check_visibility = 1,
        int xy_distance = 0);
    float get_distance_to_character(diguyCharacter* character);
    float get_distance_xy_to_character(diguyCharacter* character);
    float get_distance_to_impact(diguyImpact* impact);
    float get_random_factor();
    int draw();
    int draw_pass1();
    int draw_pass2();
#ifdef CPLUSPLUS_ONLY
    void* get_graphics_ptr();
    int set_graphics_ptr(void* graphics_ptr);
    void set_graphics_api_node_ptr(void* node_ptr);
    void* get_graphics_api_node_ptr();
    int set_user_data(void* user_data);
    void* get_user_data();
#endif
    int set_desired_action(const char* action_name,
        float speed = DIGUY_DEFAULT_FLOAT,
        int retain_path_shape = 0);
    const char* get_desired_action();
    const char* get_current_action();
    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);
    int force_action_with_duration(const char* action_name,
        float duration,
        int include_transition_arc = 1,
        float max_rampdown_interval = 0.5f);
    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);
    const char* get_most_recent_forced_action();
    float get_most_recent_forced_action_t();
    float get_most_recent_forced_action_t_offset();
    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);
    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);
    int is_valid_action(const char* action);
    int die_now(const char* preferred_dead_action_name = "(default)");
    int revive_now(const char* preferred_revive_action_name = "(default)");
    int get_dead();
    int set_speed(float speed);
    float get_speed();
    int set_position(float tx, float ty, float tz);
    int set_position_double(double tx, double ty, double tz);
    int get_position(float* tx, float* ty, float* tz);
    int get_position_double(double* tx, double* ty, double* tz);
    int set_position_relative_to_parent(float tx, float ty, float tz);
    int get_position_relative_to_parent(float* tx, float* ty, float* tz);
    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);
    int set_desired_position(float tx, float ty, float tz,
        int force_guide_unacquired = 0);
    int set_desired_position_to_current_position(int also_set_orientation = 1);
    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);
    int set_desired_position_to_path_waypoint(const char* path_name,
        const char* waypoint_name);
    int set_desired_position_to_path_shape_waypoint(const char* path_shape_name,
        const char* waypoint_name);
    int get_desired_position(float* tx, float* ty, float* tz);
    int get_delta_to_desired_position(float* tx, float* ty, float* tz);
    int set_initial_position(float tx, float ty, float tz);
    int get_initial_position(float* tx, float* ty, float* tz);
    int set_orientation(float rz, float rx, float ry);
    int get_orientation(float* rz, float* rx, float* ry);
    int set_orientation_relative_to_parent(float rz, float rx, float ry);
    int get_orientation_relative_to_parent(float* rz, float* rx, float* ry);
    int set_initial_up_vector(char axis);
    char get_initial_up_vector();
    int set_up_vector(char axis);
    char get_up_vector();
    int set_custom_orientation_rx_and_ry(float rx,
        float ry);
    int set_desired_orientation(float rz, float rx, float ry,
        int force_guide_unacquired = 0);
    int get_desired_orientation(float* rz, float* rx, float* ry);
    int get_delta_to_desired_orientation(float* rz, float* rx, float* ry);
    int set_desired_orientation_to_current_orientation();
    int set_desired_orientation_towards_position(float x, float y, float z,
        int force_guide_unacquired = 0);
    int set_initial_orientation(float rz, float rx, float ry);
    int get_initial_orientation(float* rz, float* rx, float* ry);
    int get_link_position(const char* link_name,
        float* tx, float* ty, float* tz,
        float* rz, float* rx, float* ry);
    int get_link_position_double(const char* link_name,
        double* tx, double* ty, double* tz,
        double* rz, double* rx, double* ry);
    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);
    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);
    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);
    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);
    void set_apply_actor_scale_to_action_bead_travel(int apply_scale_flag);
    int get_apply_actor_scale_to_action_bead_travel();
    int local_to_global(float x, float y, float z,
        float* res_x, float* res_y, float* res_z);
    int global_to_local(float x, float y, float z,
        float* res_x, float* res_y, float* res_z);
    void get_velocity(float* vel_x, float* vel_y, float* vel_z);
    void set_desired_velocity(float vel_x, float vel_y, float vel_z);
    void get_angular_velocity(float* vel_rz);
    const char* get_appearance();
    int set_appearance(const char* appearance);
    int set_current_appearance(const char* appearance,
        int allow_actor_change = 1);
    const char* get_current_appearance();
    int get_current_appearance_is(const char* appearance);
    int set_current_head_appearance(const char* head_appearance);
    const char* get_current_head_appearance();
    int get_current_head_appearance_is(const char* head_appearance);
    int set_lod_ranges(float* lod_ranges);
    int set_graphics_lod(int lod);
    int get_graphics_lod();
    
    int set_shader_lod(int lod);
    int get_shader_lod();
    
    int set_motion_lod(int motion_lod);
    int get_motion_lod();
    int get_current_motion_lod();
    int set_minimum_cpl(int minimum_cpl);
    int get_minimum_cpl();
    int get_maximum_possible_current_cpl();
    int maximize_current_cpl();
    int set_automatic_cpl_switching_enabled(int enabled);
    int get_automatic_cpl_switching_enabled();
    int set_current_cpl(int current_cpl);
    int get_current_cpl();
    int set_position_update_rate(int update_rate);
    int get_position_update_rate();
    int set_pose_update_rate(int update_rate);
    int get_pose_update_rate();
    int set_minimum_full_update_period(float min_period);
    float get_minimum_full_update_period();
    int set_position_accumulation_disabled(int disabled_flag);
    int get_position_accumulation_disabled();
    int set_all_blends_disabled(int disabled_flag);
    int get_all_blends_disabled();
    int set_shape_switches_disabled(int disabled_flag);
    int get_shape_switches_disabled();
    int set_shape_callbacks_disabled(int disabled_flag);
    int get_shape_callbacks_disabled();
    int set_graphics_api_shape_update_disabled(int disabled_flag);
    int get_graphics_api_shape_update_disabled();
    int optimized_update(float t);
    int set_is_load_managed(int is_load_managed);
    int get_is_load_managed();
    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_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_CURRENT_TOUT_REACHED,
        CALLBACK_ID_POST_CREATE_GEOMETRY,
        CALLBACK_ID_PRE_DESTROY_GEOMETRY,
        CALLBACK_ID_END_OF_PATH_REACHED,
        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_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_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
    };
#ifdef CPLUSPLUS_ONLY
    int add_callback(int callback_id,
        diguyCharacterCallback* callback,
        void* callback_params = 0,
        void* callback_user_data = 0);
    int remove_callback(int callback_id,
        diguyCharacterCallback* callback);
    int remove_callback_with_user_data(int callback_id,
        void* callback_user_data);
#endif
    int add_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int remove_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int map_event_handler_to_callback_id(int callback_id,
        const char* handler_name);
    int unmap_event_handler_from_callback_id(int callback_id,
        const char* handler_name,
        int unmap_all_matches = 0);
    diguyCallbackReturn manually_invoke_event_handler(const char* handler_name);
    diguyCharacterPath* create_path(const char* name);
    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);
    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);
    int create_and_force_bridge_path(const char* destination_path_name,
        const char* destination_path_action_bead_name,
        const char* via_action_name);
    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);
    int destroy_path(diguyCharacterPath* path);
    int get_num_paths();
    diguyCharacterPath* get_path_at_index(int index);
    const char* get_path_name_at_index(int index);
    int get_current_path_index();
    diguyCharacterPath* get_current_traveled_path();
    int get_current_traveled_path_is(const char* path_name);
    int push_path(const char* path_name);
    int force_path(const char* path_name,
        float max_rampdown_interval = 0.5f);
    int force_partial_path(const char* path_name,
        const char* beginning_action_bead_name,
        float max_rampdown_interval = 0.5f);
    int resume_interrupted_path(float max_rampdown_interval = 0.5f);
    diguyCharacterPath* force_local_path(const char* path_name,
        int use_character_orientation,
        float rotation = 0.0f,
        int clamp_path = 1);
    int set_initial_path(const char* name);
    const char* get_initial_path();
    void translate_all_paths(float tx, float ty, float tz,
        int reclamp_waypoints = 1);
    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);
    int rotate_all_paths_about_current_waypoint(float rz, float rx, float ry,
        int reclamp_waypoints = 1);
    int jump_to_action_bead(const char* bead_name,
        float max_rampdown_interval = 0.5f);
    diguyCharacterPath* find_path(const char* path_name);
    int apply_aim_bead(diguyCharacterPathAimBead* bead,
        float how_far = 0.0f);
    int apply_decision_bead(diguyCharacterPathDecisionBead* bead,
        float how_far = 0.0f);
    int apply_gaze_bead(diguyCharacterPathGazeBead* bead,
        float how_far = 0.0f);
    int apply_script_bead(diguyCharacterPathScriptBead* bead,
        float how_far = 0.0f);
    int set_distance_along_path(float distance);
    float get_distance_along_path();
    int leave_path();
    int get_nearest_waypoint_index_in_path(const char* path_name);
    float get_distance_to_path(const char* path_name,
        const char* action_bead_name = NULL);
    diguyGraphicsLink* get_position_link();
    int get_num_links();
    diguyGraphicsLink* get_link_at_index(int index);
    diguyGraphicsLink* find_link(const char* name);
    const char* get_link_name_at_index(int link_index);
    int get_num_link_shapes(const char* link_name);
    const char* get_link_shape_name_at_index(const char* link_name,
        int shape_index);
#ifdef CPLUSPLUS_ONLY
    int set_altitude_function(diguyAltitudeFunction* altitude_function);
    diguyAltitudeFunction* get_altitude_function();
#endif
    int set_altitude_function_enabled_in_free_position_mode(int enabled);
    int get_altitude_function_enabled_in_free_position_mode();
    int set_altitude_function_enabled_in_path_position_mode(int value);
    int get_altitude_function_enabled_in_path_position_mode();
    int set_altitude_update_rate(int update_rate);
    int get_altitude_update_rate();
    void set_altitude_interpolation_rate(float interpolation_rate);
    float get_altitude_interpolation_rate();
    int get_pose_array_size();
#ifdef CPLUSPLUS_ONLY
    int get_pose_in_radians(float* pose_array);
#endif
    diguyCharacterPoseOverride* create_pose_override(int override_stage = 3);
    int destroy_pose_override(diguyCharacterPoseOverride* po);
    int get_num_pose_overrides();
    diguyCharacterPoseOverride* get_pose_override_at_index(int index);
    diguyCharacterPoseOverride* create_complete_pose_override();
    void destroy_complete_pose_override();
    int gaze_at_angle(float azimuth,
        float elevation,
        float distance,
        int is_new_gaze = 1);
    int gaze_at_angle_local(float azimuth,
        float elevation,
        float distance = 10000.0f,
        int is_new_gaze = 1);
    int gaze_at_point(float tx,
        float ty,
        float tz,
        int is_new_gaze = 1);
    int gaze_at_point_local(float tx,
        float ty,
        float tz,
        int is_new_gaze = 1);
    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);
    int get_gaze_is_active();
    int get_gaze_point(float* x, float* y, float* z);
    int get_gaze_is_acquired();
    int get_gaze_is_steady();
    int end_gaze();
    int lpoint_at_angle(float azimuth,
        float elevation,
        float distance,
        int is_new_lpoint = 1,
        const char* base_gesture_name = 0);
    int lpoint_at_angle_local(float azimuth,
        float elevation,
        float distance = 10000.0f,
        int is_new_lpoint = 1,
        const char* base_gesture_name = 0);
    int lpoint_at_point(float tx,
        float ty,
        float tz,
        int is_new_lpoint = 1,
        const char* base_gesture_name = 0);
    int lpoint_at_point_local(float tx,
        float ty,
        float tz,
        int is_new_lpoint = 1,
        const char* base_gesture_name = 0);
    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);
    int get_lpoint_point(float* x, float* y, float* z);
    const char* get_lpoint_base_gesture_name();
    int get_lpoint_is_active();
    int get_lpoint_is_acquired();
    int get_lpoint_is_steady();
    int end_lpoint();
    int set_gaze_params_to_defaults();
    int set_gaze_param_desired_locate_time(float t);
    float get_gaze_param_desired_locate_time();
    int set_gaze_link_uses_desired_locate_time(const char* link_name,
        int uses_desired_locate_time);
    int get_gaze_link_uses_desired_locate_time(const char* link_name);
    int set_gaze_link_azimuth_limits(const char* link_name, float min, float max);
    int get_gaze_link_azimuth_limits(const char* link_name,
        float* min,
        float* max);
    int set_gaze_link_elevation_limits(const char* link_name,
        float min,
        float max);
    int get_gaze_link_elevation_limits(const char* link_name,
        float* min,
        float* max);
    int set_gaze_link_azimuth_tolerance(const char* link_name,
        float min,
        float max);
    int get_gaze_link_azimuth_tolerance(const char* link_name,
        float* min,
        float* max);
    int set_gaze_link_elevation_tolerance(const char* link_name,
        float min,
        float max);
    int get_gaze_link_elevation_tolerance(const char* link_name,
        float* min,
        float* max);
    int set_gaze_link_max_angular_vel(const char* link_name, float angular_vel);
    int get_gaze_link_max_angular_vel(const char* link_name, float* angular_vel);
    int set_gaze_link_scale_factor(const char* link_name, float scale_factor);
    int get_gaze_link_scale_factor(const char* link_name, float* scale_factor);
    int set_link_enabled_for_gaze(const char* link_name, int enabled);
    int get_link_enabled_for_gaze(const char* link_name);
    int set_gaze_can_change_posture(int enabled);
    int get_gaze_can_change_posture();
    int set_gaze_can_change_variant(int enabled);
    int get_gaze_can_change_variant();
    int set_link_enabled_for_lpoint(const char* link_name, int enabled);
    int get_link_enabled_for_lpoint(const char* link_name);
    int set_nod(float azimuth,
        float elevation,
        float duration = 0.5f);
    int nod_head(float duration,
        float nod_count,
        float nod_elevation0 = 15.0f,
        float nod_elevation1 = 0.0f,
        float nod_elevation_out = 0.0f);
    int shake_head(float duration,
        float shake_count,
        float shake_azimuth0 = -20.0f,
        float shake_azimuth1 = 20.0f,
        float shake_azimuth_out = 0.0f);
    float get_nod_azimuth();
    float get_nod_elevation();
    int set_aim(float azimuth, float elevation);
    int aim_at_angle(float azimuth,
        float elevation,
        float distance,
        int is_new_aim = 1);
    int aim_at_angle_local(float azimuth,
        float elevation,
        float distance,
        int is_new_aim = 1);
    int aim_at_point(float x, float y, float z, int is_new_aim = 1);
    int aim_at_point_local(float x, float y, float z, int is_new_aim = 1);
    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);
    void end_aim();
    int aim_converge(int max_iterations = 30);
    float get_aim_azimuth();
    int get_aim_trajectory(float* muzzle_x, float* muzzle_y, float* muzzle_z,
        float* far_x, float* far_y, float* far_z);
    float get_aim_elevation();
    int get_aim_is_possible();
    int get_aim_is_acquired();
    int get_aim_is_steady();
    void set_aim_algorithm(int aim_algorithm);
    int get_aim_algorithm();
    int get_is_aiming();
    void set_aim_param_acquire_factor(float factor);
    float get_aim_param_acquire_factor();
    void set_aim_param_new_aim_factor(float factor);
    float get_aim_param_new_aim_factor();
    void set_aim_param_new_aim_duration(float duration);
    float get_aim_param_new_aim_duration();
    void set_aim_param_max_per_frame_adj_factor(float factor);
    float get_aim_param_max_per_frame_adj_factor();
    void set_aim_param_azimuth_acquired_range(float range);
    float get_aim_param_azimuth_acquired_range();
    void set_aim_param_elevation_acquired_range(float range);
    float get_aim_param_elevation_acquired_range();
    void set_aim_converge_every_frame(int max_iterations = 30);
    int get_aim_converge_every_frame();
    int fire_weapon(diguyMuzzle muzzle = DIGUY_MUZZLE_DEFAULT);
    int fire_weapon_n_times(int count,
        float dt = 0.2f,
        const char* override_sound_name = NULL,
        diguyMuzzle muzzle = DIGUY_MUZZLE_DEFAULT);
    int fire_screen_space_bullet(diguyView* view, float x, float y);
    int get_weapon_fire_count(diguyMuzzle muzzle = DIGUY_MUZZLE_DEFAULT);
    int set_default_weapon_muzzle(diguyMuzzle muzzle);
    diguyMuzzle get_default_weapon_muzzle();
    const char* get_weapon_muzzle_munition_type(diguyMuzzle muzzle);
    const char* get_default_muzzle_munition_type();
    int set_weapon_munition_type_override(const char* munition_type);
    const char* get_weapon_munition_type_override();
    int set_weapon_fires_live_rounds(int weapon_fires_live_rounds);
    int get_weapon_fires_live_rounds();
    int set_weapon_sound_override(const char* sound_name);
    const char* get_weapon_sound_override();
    int set_weapon_sound_gain_override(float gain);
    float get_weapon_sound_gain_override();
    void set_weapon_spread(float spread);
    void set_weapon_near_range(float near_range);
    void set_weapon_far_range(float far_range);
    void set_weapon_hit_ratio(float hit_ratio);
    void set_weapon_max_impacts(int val);
    int get_accessory1_state();
    int get_rifle_state();
    int set_weapon_projectile_is_visible(diguyMuzzle muzzle, int is_visible);
    int get_weapon_projectile_is_visible(diguyMuzzle muzzle);
    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);
    const char* get_muzzle_link(diguyMuzzle muzzle = DIGUY_MUZZLE_DEFAULT);
    int get_muzzle_offset(diguyMuzzle muzzle = DIGUY_MUZZLE_DEFAULT,
        float* offset_x = NULL,
        float* offset_y = NULL,
        float* offset_z = NULL);
    int set_weapon_max_azimuth_error(float h_error);
    float get_weapon_max_azimuth_error();
    int set_weapon_max_elevation_error(float v_error);
    float get_weapon_max_elevation_error();
    int set_weapon_tracers_enabled(int enabled);
    int get_weapon_tracers_enabled();
    int get_weapon_rounds_until_tracer(diguyMuzzle muzzle);
    int set_weapon_shell_eject_enabled(int enabled);
    int get_weapon_shell_eject_enabled();
    int set_weapon_smoke_enabled(int enabled);
    int get_weapon_smoke_enabled();
    int trigger_detonation_on_character(const char* munition_name,
        const char* attacker_name = NULL,
        float radius_override = -1.0f,
        int broadcast_on_network = 1);
    int set_face_expression(const char* facex_name, float blend_duration, float strength = 1.0f);
    int set_orientation_eyes(float azimuth,
        float elevation,
        float blend_time = 0.0f);
    int get_orientation_eyes(float* azimuth, float* elevation);
    int set_eye_droop(float droop_amount, float blend_time = 0.0f);
    float get_eye_droop();
    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);
    int set_automatic_blinks_enabled(int enabled,
        float period = 6.0f,
        float period_variation = 3.0f);
    int get_automatic_blinks_enabled();
    void set_automatic_blink_duration_in(float duration_in);
    float get_automatic_blink_duration_in();
    void set_automatic_blink_duration_out(float duration_out);
    float get_automatic_blink_duration_out();
    void set_automatic_blink_target_in(float target_in);
    float get_automatic_blink_target_in();
    void set_automatic_blink_target_out(float target_out);
    float get_automatic_blink_target_out();
    int is_speaking();
    int set_current_facefx_animation_group(const char* anim_group);
    const char* get_current_facefx_animation_group();
    const char* get_facefx_actor();
    int facefx_mount_animset(const char* file_name);
    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);
    int stop_facefx_animations(float blend_time = 0.25f, int stop_sounds = 1);
    int get_num_facefx_nodes();
    const char* get_facefx_node_name(int index);
    int find_facefx_node_index(const char* node_name);
    int set_facefx_node_value(int node_index,
        float value,
        float blend_time = 0.25f);
    float get_facefx_node_value(int node_index);
    diguyCharacterGesture* create_gesture(const char* gesture_name);
    int destroy_gesture(diguyCharacterGesture* gesture);
    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);
    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);
    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);
    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);
    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);
    int set_executing_table_gesture_desired_action(const char* gesture_name,
        const char* desired_action);
    int end_executing_gesture(const char* gesture_name);
    int abort_executing_gesture(const char* gesture_name,
        float max_rampdown_interval);
    int end_all_gestures();
    int abort_all_gestures(float max_rampdown_interval);
    int play_sound(const char* sound_name,
        float sound_gain = 1.0f,
        int sound_loops = 0);
    int play_3d_sound(const char* sound_name,
        float sound_gain = 1.0f,
        int sound_loops = 0);
    diguySoundInstance* create_sound_instance(const char* sound_name);
    int destroy_sound_instance(diguySoundInstance* sound_instance);
    int stop_all_sounds(float rampdown_time = 0.0f);
    int stop_sound(const char* sound_name, float rampdown_time = 0.0f);
    int is_playing_sound(const char* sound_name);
    int set_current_voice_actor(const char* voice_actor);
    const char* get_current_voice_actor();
    int get_DIS_lifeform_state();
    int get_DIS_primary_weapon_position();
    int get_DIS_secondary_weapon_position();
    int set_network_marking(const char* network_marking);
    const char* get_network_marking();
    int set_is_network_published(int is_network_published);
    int get_is_network_published();
    int get_is_network_reflected();
    int get_is_network_paused();
    int get_network_entity_number();
    const char* get_action_from_entity_state(int damage_state,
        int life_form_state,
        int primary_weapon_state,
        float speed,
        int forward);
    void set_DIS_damage_state(int state);
    int get_DIS_damage_state();
    void set_DIS_smoke_state(int state);
    int get_DIS_smoke_state();
    void set_DIS_flames_state(int state);
    int get_DIS_flames_state();
    void set_DIS_power_plant_state(int state);
    int get_DIS_power_plant_state();
    void set_DIS_trailing_effect_state(int state);
    int get_DIS_trailing_effect_state();
    int call_formation(const char* formation_name,
        int snap_to_position_flag = 0,
        int break_existing_formations_flag = 1);
    int break_formation(const char* formation_name = NULL);
    diguyCharacterGuide* add_guide(const char* guide_name,
        int automatically_disable_when_acquired = 0);
    diguyCharacterGuide* create_guide(const char* guide_name,
        const char* guide_algorithm,
        int automatically_disable_when_acquired = 0);
    diguyCharacterGuide* find_or_create_guide(const char* guide_name,
        const char* guide_algorithm,
        int automatically_disable_when_acquired = 0);
    diguyCharacterGuide* find_guide(const char* guide_name);
    int remove_guide_with_name(const char* guide_name);
    int remove_guide(diguyCharacterGuide* guide);
    int remove_all_guides();
    int remove_all_disabled_guides();
    int add_motion_texture(const char* motex_name = "default",
        float texture_gain = 1.0f,
        int end_previous_motex = 1,
        float rampup_interval = 0.2f);
    int end_motion_texture(float rampdown_interval = 0.2f);
    int set_initial_motion_texture(const char* motex_name);
    const char* get_initial_motion_texture();
    int set_initial_motion_texture_gain(float motex_gain);
    float get_initial_motion_texture_gain();
    int set_history_type(diguyHistoryType history_type);
    diguyHistoryType get_history_type();
    int set_history_size_t(float t);
    float get_history_size_t();
    int set_history_size_increment_t(float t);
    float get_history_size_increment_t();
    void set_desired_posture(diguyMotionPosture desired_posture);
    diguyMotionPosture get_desired_posture();
    void set_desired_variant(diguyMotionVariant desired_variant);
    diguyMotionVariant get_desired_variant();
    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);
    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);
    int	get_num_variables();
    diguyVariable* get_variable_at_index(int index);
    diguyVariable* find_variable(const char* name);
    diguyVariable* find_or_create_variable(const char* name);
    int destroy_variable(diguyVariable* variable);
    int variable_equal_to_int(const char* varname, int value);
    int variable_greater_than_int(const char* varname, int value);
    int variable_less_than_int(const char* varname, int value);
    int variable_equal_to_float(const char* varname, float value);
    int variable_greater_than_float(const char* varname, float value);
    int variable_less_than_float(const char* varname, float value);
    int variable_equal_to_string(const char* varname, const char* value);
    int variable_greater_than_string(const char* varname, const char* value);
    int variable_less_than_string(const char* varname, const char* value);
    int variable_decrement_value_as_int(const char* varname, int value = 1);
    int variable_increment_value_as_int(const char* varname, int value = 1);
    int variable_set_value_as_int(const char* varname,
        int value,
        int create_if_doesnt_exist = 1);
    int set_ivar(const char* varname,
        int value,
        int create_if_doesnt_exist = 1);
    int get_ivar(const char* varname,
        int create_if_doesnt_exist = 1);
    int variable_set_value_as_float(const char* varname,
        float value,
        int create_if_doesnt_exist = 1);
    int set_fvar(const char* varname,
        float value,
        int create_if_doesnt_exist = 1);
    float get_fvar(const char* varname,
        int create_if_doesnt_exist = 1);
    int variable_set_value_as_string(const char* varname,
        const char* value,
        int create_if_doesnt_exist = 1);
    int set_svar(const char* varname,
        const char* value,
        int create_if_doesnt_exist = 1);
    const char* get_svar(const char* varname,
        int create_if_doesnt_exist = 1);
    diguyViewLabel* get_name_label();
    int set_label_text(const char* label_text);
    const char* get_label_text();
    int set_label_is_visible(int is_visible);
    int get_label_is_visible();
    int set_label_text_color(float r, float g, float b, float a);
    int set_label_text_color_vec4(diguyVec4f color);
    int get_label_text_color(float* r, float* g, float* b, float* a);
    diguyVec4f get_label_text_color_vec4();
    int set_label_text_shadow_color(float r, float g, float b, float a);
    int set_label_text_shadow_color_vec4(diguyVec4f color);
    int get_label_text_shadow_color(float* r, float* g, float* b, float* a);
    diguyVec4f get_label_text_shadow_color_vec4();
    int set_label_text_shadow_is_visible(int is_visible);
    int get_label_text_shadow_is_visible();
    int set_label_background_color(float r, float g, float b, float a);
    int set_label_background_color_vec4(diguyVec4f color);
    int get_label_background_color(float* r, float* g, float* b, float* a);
    diguyVec4f get_label_background_color_vec4();
    void set_label_link_offset_override(float offset);
    float get_label_link_offset_override();
    int set_label_shows_character_state(int show_state);
    int get_label_shows_character_state();
    diguyImpact* get_last_impact_record();
    int get_last_impact_number();
    int get_last_impact_been_processed();
    void set_last_impact_been_processed();
    void set_max_unprocessed_impacts(int max_unprocessed_impacts);
    int get_max_unprocessed_impacts();
    const char* get_last_impact_link();
    int get_last_impact_link_is(const char* link_name);
    int get_last_impact_is_from_vehicle();
    int get_last_impact_speed_is_greater_than(float impact_speed);
    void set_is_immune_to_impacts(int immune);
    int get_is_immune_to_impacts();
    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);
    int end_appearance_effect(const char* effect,
        const char* override_link = NULL);
    int stop_appearance_effect(const char* effect,
        const char* override_link = NULL);
    int stop_all_appearance_effects();
    int appearance_effect_is_active(const char* effect,
        const char* override_link = NULL);
    diguyChainSimulation* get_chain_simulation();
    diguyVehicleController* get_vehicle_controller();
    int get_vehicle_body_orientation(float* rz, float* rx, float* ry);
    int set_render_mode_shader(const char* shader_name,
        const char* render_mode = NULL);
    void reset_render_mode_shader_to_default(const char* render_mode = NULL);
    const char* get_render_mode_shader(const char* render_mode = NULL);
    diguyGraphicsShaderProgram* get_shader_program();
    int set_temporary_current_shader(const char* shader_name);
    void reset_current_shader_to_default();
    void trigger_shader_refresh();
    diguyGraphicsShaderInstance* get_shader_instance();
    void reset_shader_instance_variables_to_initial_values();
    void reset_shader_instance_variables_to_program_defaults();
    int agent_attack_character(const char* character_name);
    int agent_attack_group(const char* group_name);
    int agent_set_attack_zone_enabled(int use_attack_zone);
    int agent_get_attack_zone_enabled();
    int agent_set_attack_zone(float x, float y, float z, float radius);
    int agent_get_attack_zone(float* x, float* y, float* z, float* radius);
    int agent_flee_character(const char* character_name,
        float distance,
        int danger_level = 50);
    int agent_flee_group(const char* group_name,
        float distance,
        int danger_level = 50);
    int agent_flee_crowd(const char* crowd_name,
        float distance,
        int danger_level = 50);
    int agent_flee_location(float x, float y, float z,
        float distance,
        int danger_level = 50);
    void agent_remove_all_flee_objects();
    int agent_mingle_in_region(const char* region_name = "(current)",
        const char* subregion_name = "base");
    int agent_wander_region(const char* region_name = "(current)",
        const char* subregion_name = "base");
    int agent_pursue_character(const char* character_name);
    int agent_pursue_character_with_offset(const char* character_name,
        float offset_x,
        float offset_y);
    int agent_pursue_group(const char* group_name);
    int agent_call_formation(const char* formation_name,
        float target_x,
        float target_y);
    int agent_travel_behavior_path(const char* direction = NULL,
        const char* at_end = NULL,
        int waypoint_index = -1,
        float offset_y = 0.5f);
    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);
    int agent_travel_region_border(const char* region_name = NULL,
        const char* subregion_name = "base");
    int agent_move_to_point(float x, float y, float z,
        const char* via_region = NULL,
        const char* subregion_name = "base");
    int agent_move_to_point_bg(float x, float y, float z,
        const char* via_region = NULL,
        const char* subregion_name = "base");
    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);
    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);
    int get_path_planning_result();
    int get_is_path_planning();
    int agent_move_to_region(const char* region,
        const char* subregion_name = "base",
        const char* via_region = NULL);
    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);
    int agent_path_follow(const char* path_name);
    int agent_resume_path_follow();
    diguyCharacterPath* agent_get_path_follow_path();
    float agent_get_path_follow_path_t();
    int agent_get_path_follow_path_t_paused();
    diguyCrowd* agent_get_crowd();
    int agent_begin_behavior(const char* behavior_name);
    int agent_stop_behavior();
    int agent_set_current_focus_character(const char* character_name);
    diguyCharacter* agent_get_current_focus_character();
    int agent_set_current_focus_group(const char* group_name);
    diguyAgentParams* agent_get_initial_params();
    diguyAgentParams* agent_get_current_params();
    const char* agent_get_current_params_profile_name();
    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);
    int agent_set_initial_params_from_profile(const char* profile_name);
    void agent_set_current_params_from_initial_params();
    void agent_set_current_behavior_region_border_is_solid(int is_solid);
    void agent_move_on();
    
    int agent_set_auto_variant_selection(int selection_enabled);
    int agent_get_auto_variant_selection();
#ifdef CPLUSPLUS_ONLY
    int agent_set_feeler_function(diguyFeelerFunction* feeler_function);
    diguyFeelerFunction* agent_get_feeler_function();
#endif
    int create_lua_mind(const char* base_class, const char* init_arg1 = NULL,
        const char* init_arg2 = NULL);
    const char *get_mind_name();
    const char* get_mind_current_state_name();
    void do_mind_current_state_changed_callback();
    int set_sleep_timer(float sleep_length);
    float get_sleep_timer();
    int set_heartbeat_dt(float heartbeat_dt);
    int add_secondary_heartbeat(const char* function_name,
        float heartbeat_dt);
    int remove_secondary_heartbeat(const char* function_name);
    int set_secondary_heartbeat_dt(const char* function_name, float heartbeat_dt);
    int add_wakeup_callback(int callback);
    int remove_wakeup_callback(int callback);
    int remove_all_wakeup_callbacks();
    int has_wakeup_callback(int callback);
    int agent_accept_message(const char* sender,
        const char* message_type,
        const char* message,
        const char* message_params = NULL);
    int agent_broadcast_message(float radius,
        const char* message_type,
        const char* message,
        const char* message_params = NULL);
    int agent_broadcast_message_to_group(const char* group_name,
        float radius,
        const char* message_type,
        const char* message,
        const char* message_params = NULL);
    const char* get_lua_object_name();
    void set_mind_field_as_string(const char* field_name,
        const char* field_value);
    const char* get_mind_field_as_string(const char* field_name,
        int warn_if_no_field = 1);
    void set_mind_field_as_float(const char* field_name, float field_value);
    float get_mind_field_as_float(const char* field_name,
        int warn_if_no_field = 1,
        int* found_field = NULL);
    void set_mind_field_as_int(const char* field_name, int field_value);
    int get_mind_field_as_int(const char* field_name,
        int warn_if_no_field = 1,
        int* found_field = NULL);
    const char* evaluate_mind_function(const char* function_name,
        const char* argument = NULL,
        int has_return_string = 0);
    const char* get_ai_state_string(int include_stack = 1, int include_locals = 1);
    int check_character_visibility(diguyCharacter* character,
        int los_check_type = 0);
    int check_point_visibility(float x, float y, float z);
#ifdef CPLUSPLUS_ONLY
    int set_point_los_function(diguyPointLOSFunction* point_los_function);
    diguyPointLOSFunction* get_point_los_function();
    int set_character_los_function(diguyCharacterLOSFunction* character_los_function);
    diguyCharacterLOSFunction* get_character_los_function();
#endif
    int set_initial_character_simulator(diguyCharacterSimulator character_simulator);
    diguyCharacterSimulator get_initial_character_simulator();
    int set_current_character_simulator(diguyCharacterSimulator character_simulator);
    diguyCharacterSimulator get_current_character_simulator();
    int set_initial_physics_simulation_mode(diguyPhysicsSimulationMode physics_simulation_mode);
    diguyPhysicsSimulationMode get_initial_physics_simulation_mode();
    int set_current_physics_simulation_mode(diguyPhysicsSimulationMode physics_simulation_mode);
    diguyPhysicsSimulationMode get_current_physics_simulation_mode();
    int set_physics_collision_group(diguyPhysicsCollisionGroup collision_group);
    diguyPhysicsCollisionGroup get_physics_collision_group();
    void set_stop_physics_sim_at_t(float t);
    void set_stop_physics_sim_in_t_seconds(float relative_t);
    float get_stop_physics_sim_at_t();
    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);
    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);
    static int set_texture_load_behavior(diguyGraphicsTextureLoadingBehavior mode);
    static diguyGraphicsTextureLoadingBehavior get_texture_load_behavior();
    int get_has_bump_maps();
    int get_action_num_channels(const char* action_name);
    int set_action_channel_weight(const char* action_name,
        char channel,
        float weight);
    float get_action_channel_weight(const char* action_name,
        char channel);
    float get_time_to_reach_desired_action();
    const char* get_type_map_field(diguyCharacterTypeMapField field);
    const char* get_type_map_field_using_string(const char* field);
    int merge_object(const char* object);
    int is_active_character_in_group_visible(const char* group_name,
        float max_distance_to_check = 100000.0f);
    int get_local_space_bounding_box(float* x1, float* y1, float* z1,
        float* x2, float* y2, float* z2);
    int get_geometry_tag(int tag,
        int world_space,
        float* x1, float* y1, float* z1, float* radius);
    void set_mind_always_updates(int force_update);
    int get_mind_always_updates();
    float get_angle_to_path(const char* path_name,
        const char* action_bead_name = NULL);
    const char* get_aim_at_link();
    int get_aim_at_link_offset(float* offset_x, float* offset_y, float* offset_z);
    const char* get_gaze_at_link();
    int get_gaze_at_link_offset(float* offset_x, float* offset_y, float* offset_z);
    void set_scene_graph_mask(unsigned int mask);
    unsigned int get_scene_graph_mask();
    int set_use_texture_variations(int value);
    int get_use_texture_variations();
    int set_emit_light(int emit_light);
    int get_emit_light();
    static int set_max_shader_quality_level(int quality_level);
    static int get_max_shader_quality_level();
    diguyGraphicsLink* get_base_link();
    
    void set_apply_actor_scale_to_action_bead_xy_travel(int apply_scale_flag);
    int get_apply_actor_scale_to_action_bead_xy_travel();
    int set_default_weapon_sound(const char* sound_name);
    const char* get_default_weapon_sound();
    int set_default_weapon_sound_gain(float gain);
    float get_default_weapon_sound_gain();
    int set_weapon_munition_type(const char* munition_type);
    const char* get_weapon_munition_type();
    int set_weapon_horizontal_error(float h_error);
    float get_weapon_horizontal_error();
    int set_weapon_vertical_error(float v_error);
    float get_weapon_vertical_error();
    int begin_legacy_appearance_effect(const char* effect,
        const char* override_link = "",
        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);
    int end_legacy_appearance_effect(const char* effect);
    int legacy_appearance_effect_is_active(const char* effect);
    int merge_asset(const char* asset);
    void set_DIS_smoke_trail_state(int state);
    int get_DIS_smoke_trail_state();
    int speak(const char* string);
    int set_viseme(const char* viseme_name, float weight);
    float get_viseme(const char* viseme_name);
    int set_orientation_eye_left(float azimuth, float elevation);
    int set_orientation_eye_right(float azimuth, float elevation);
    float get_azimuth_eye_left();
    float get_elevation_eye_left();
    float get_azimuth_eye_right();
    float get_elevation_eye_right();

General Functions

Unless otherwise specified, all functions callable from:

C++
Script

function diguyCharacter::get_name

Prototype:
const char* get_name();
Description:

Returns the name of the object. This pointer will never be NULL.

function diguyCharacter::set_name

Prototype:
int set_name(const char* name);
Description:

This function sets the name of this object.
Returns:

0 on success, -1 on failure

function diguyCharacter::get_type_name

Prototype:
const char* get_type_name();
Description:

Returns the type name of the object. This pointer will never be NULL.

function diguyCharacter::get_uid

Prototype:
long get_uid();
Description:

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!

function diguyCharacter::get_index

Prototype:
int get_index();
Description:

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

function diguyCharacter::update

Prototype:
int update(float t, int full_update = 1);
Description:

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
Arguments:

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

function diguyCharacter::set_character_type

Prototype:
void set_character_type(const char* type);
Description:

This function sets the current type of this character.
Arguments:

type name of the new desired type
See Also:

get_character_type_string()

function diguyCharacter::get_character_type_string

Prototype:
const char* get_character_type_string();
Description:

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

function diguyCharacter::get_character_class

Prototype:
const char* get_character_class();
Description:

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

function diguyCharacter::get_scenario

Prototype:
diguyScenario* get_scenario();
Description:

Returns the scenario that this character is a part of.

function diguyCharacter::set_enabled

Prototype:
int set_enabled(int enabled);
Description:

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

function diguyCharacter::get_enabled

Prototype:
int get_enabled();
Description:

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

function diguyCharacter::set_drawn_by_scenario_flag

Prototype:
int set_drawn_by_scenario_flag(int flag);
Description:

Sets whether this character is drawn automatically by the scenario.
OpenGL Version:
Direct3D Version:

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.
Arguments:

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

function diguyCharacter::get_drawn_by_scenario_flag

Prototype:
int get_drawn_by_scenario_flag();
Description:

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

function diguyCharacter::set_invisible_flag

Prototype:
void set_invisible_flag(int invisible_flag);
Description:

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().
Arguments:

invisible_flag pass 1 to make character invisible, 0 to make it visible
Callable from:

C++
Script
Decision

function diguyCharacter::get_invisible_flag

Prototype:
int get_invisible_flag();
Returns:

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

function diguyCharacter::get_is_active

Prototype:
int get_is_active();
Description:

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
Callable from:

C++
Script
Decision

function diguyCharacter::get_is_drawn

Prototype:
int get_is_drawn();
Description:

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

function diguyCharacter::get_is_temporary

Prototype:
int get_is_temporary();
Returns:

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

function diguyCharacter::get_is_recycled

Prototype:
int get_is_recycled();
Description:

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

function diguyCharacter::set_t_controlled_by_scenario_t

Prototype:
int set_t_controlled_by_scenario_t(int t_controlled_by_scenario_t);
Description:

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().
Arguments:

t_controlled_by_scenario_t 1 for controlled by scenario, 0 for manual update
Returns:

0 on success, -1 on failure

function diguyCharacter::get_t_controlled_by_scenario_t

Prototype:
int get_t_controlled_by_scenario_t();
Returns:

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

function diguyCharacter::set_initial_tin

Prototype:
int set_initial_tin(float tin, int override_time_warning = 0);
Description:

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.
Arguments:

tin new value of initial tin in seconds
Returns:

0 on success, -1 on failure

function diguyCharacter::set_initial_tout

Prototype:
int set_initial_tout(float tout);
Description:

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.
Arguments:

tout new value of initial tout in seconds
Returns:

0 on success, -1 on failure

function diguyCharacter::set_current_tin

Prototype:
int set_current_tin(float tin);
Description:

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.
Arguments:

tin new value of current tin in seconds
Returns:

0 on success, -1 on failure

function diguyCharacter::set_current_tin_to_now

Prototype:
int set_current_tin_to_now();
Description:

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

0 on success, -1 on failure
Callable from:

C++
Script
Decision

function diguyCharacter::get_current_tin

Prototype:
float get_current_tin();
Description:

This function returns the current tin time of the character. See set_current_tin().
Returns:

Current tin time in seconds.

function diguyCharacter::set_current_tout

Prototype:
int set_current_tout(float tout,
    int disable_character_at_tout = 0);
Description:

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.
Arguments:

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

function diguyCharacter::set_current_tout_to_now

Prototype:
int set_current_tout_to_now();
Description:

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

0 on success, -1 on failure
Callable From:

C++
Script
Decision

function diguyCharacter::get_current_tout

Prototype:
float get_current_tout();
Description:

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

function diguyCharacter::set_tout_enabled

Prototype:
void set_tout_enabled(int tout_enabled);
Description:

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.

function diguyCharacter::get_tout_enabled

Prototype:
int get_tout_enabled();
Description:

This function returns the whether tout is enabled.

See set_tout_enabled().
Returns:

1 if tout enabled, 0 if not

function diguyCharacter::set_careful_interpolation_threshold

Prototype:
int set_careful_interpolation_threshold(float threshold);
Description:

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.
Arguments:

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

function diguyCharacter::get_careful_interpolation_threshold

Prototype:
float get_careful_interpolation_threshold();
Returns:

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

function diguyCharacter::set_motion_interpolation_flag

Prototype:
int set_motion_interpolation_flag(int flag);
Description:

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.
Arguments:

flag 0 by default
Returns:

0 on success, -1 on failure

function diguyCharacter::get_motion_interpolation_flag

Prototype:
int get_motion_interpolation_flag();
Returns:

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

function diguyCharacter::set_scale

Prototype:
int set_scale(float scale_x,
    float scale_y,
    float scale_z);
Description:

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

scale_x, scale_y, scale_z the factor by which to scale along the given axis
Returns:

0 on success, -1 on failure

function diguyCharacter::get_scale

Prototype:
int get_scale(float* scale_x,
    float* scale_y,
    float* scale_z);
Description:

Returns the scale of the character.
Arguments:

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

function diguyCharacter::set_parent

Prototype:
int set_parent(const char* parent_name,
    const char* parent_link_name = "");
Description:

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.
Arguments:

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 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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::get_parent

Prototype:
diguyCharacter* get_parent();
Description:

Gets the parent of this character.
Returns:

pointer to type diguyCharacter; NULL if no parent
Callable From:

C++
Script
Decision Bead

function diguyCharacter::get_parent_link_name

Prototype:
const char* get_parent_link_name();
Description:

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

name of link, NULL if no parent

function diguyCharacter::unset_parent

Prototype:
int unset_parent();
Description:

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::get_num_children

Prototype:
int get_num_children();
Description:

Gets the number of children the character has.

function diguyCharacter::get_child_at_index

Prototype:
diguyCharacter* get_child_at_index(int index);
Description:

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
Arguments:

index index of the child; indices start at 0

function diguyCharacter::get_is_scene_object

Prototype:
int get_is_scene_object();
Description:

Gets if a character is a static object, by default any blitzed . in props are.
Returns:

1 if true, 0 if false

function diguyCharacter::set_is_scene_object

Prototype:
int set_is_scene_object(int is_scene_object);
Description:

Sets if a character is a static object. By default any blitzed in props are.
Arguments:

is_scene_object pass 1 to make the object a scene object, 0 to not
Returns:

0 on success, -1 on failure

function diguyCharacter::get_bounding_radius

Prototype:
float get_bounding_radius();
Description:

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.

function diguyCharacter::get_default_bounding_radius

Prototype:
float get_default_bounding_radius();
Description:

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.

function diguyCharacter::set_bounding_radius

Prototype:
void set_bounding_radius(float f);
Description:

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

function diguyCharacter::get_time_to_transition

Prototype:
float get_time_to_transition();
Description:

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.

function diguyCharacter::get_action_mode

Prototype:
diguyCharacterMode get_action_mode();
Returns:

the action mode of the character

function diguyCharacter::get_position_mode

Prototype:
diguyCharacterMode get_position_mode();
Returns:

the position mode of the character

function diguyCharacter::set_t_scale_factor

Prototype:
int set_t_scale_factor(float t_scale_factor);
Description:

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.
Arguments:

t_scale_factor time scale factor
Returns:

0 on success, -1 on failure

function diguyCharacter::unset_t_scale_factor

Prototype:
int unset_t_scale_factor();
Description:

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

function diguyCharacter::is_within_distance_n_of_character

Prototype:
int is_within_distance_n_of_character(const char* character_name,
    float distance);
Description:

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

character character to be checked
distance distance to character in meters
Returns:

1 if within distance; 0 if not

function diguyCharacter::is_within_distance_n_of_member_of_group

Prototype:
int is_within_distance_n_of_member_of_group(const char* group_name,
    float distance);
Description:

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

group_name name of group to be checked
distance distance in meters
Returns:

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

function diguyCharacter::is_group_member

Prototype:
int is_group_member(const char* group_name);
Description:

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

Also see diguyCharacterGroup::is_member().
Arguments:

group_name name of group to be checked
Returns:

1 if character is in group, 0 if not

function diguyCharacter::get_num_group_memberships

Prototype:
int get_num_group_memberships();
Description:

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

Also see diguyCharacterGroup::is_member().

function diguyCharacter::get_group_membership_at_index

Prototype:
diguyCharacterGroup* get_group_membership_at_index(int index);
Description:

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
Arguments:

index index of the group; indices start at 0

function diguyCharacter::get_nearest_active_character

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

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.
Arguments:

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

function diguyCharacter::get_nearest_active_character_in_group

Prototype:
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);
Description:

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.
Arguments:

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

function diguyCharacter::get_random_active_character

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

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.
Arguments:

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

function diguyCharacter::get_random_active_character_in_group

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

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.
Arguments:

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

function diguyCharacter::get_distance_to_character

Prototype:
float get_distance_to_character(diguyCharacter* character);
Description:

This function returns the 3D distance from this character to the specified character, in meters. The distance is calculated from the characters' idealized positions.

function diguyCharacter::get_distance_xy_to_character

Prototype:
float get_distance_xy_to_character(diguyCharacter* character);
Description:

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.

function diguyCharacter::get_distance_to_impact

Prototype:
float get_distance_to_impact(diguyImpact* impact);
Description:

This function returns the 3D distance from this character to the specified impact, in meters. The distance is calculated from the characters' idealized positions.

function diguyCharacter::get_random_factor

Prototype:
float get_random_factor();
Description:

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

C++ Only Functions

function diguyCharacter::draw

Prototype:
int draw();
Description:

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.
Callable From:

C++

function diguyCharacter::draw_pass1

Prototype:
int draw_pass1();
Description:

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.
Callable From:

C++

function diguyCharacter::draw_pass2

Prototype:
int draw_pass2();
Description:

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

C++

function diguyCharacter::get_graphics_ptr

Prototype:
void* 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.
DirectX 9 Version:

This function returns NULL.
DI-Guy Graphics API:

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

C++

function diguyCharacter::set_graphics_ptr

Prototype:
int set_graphics_ptr(void* graphics_ptr);
Description:

Sets a graphics environment-specific pointer to graphics data. The pointer can be retrieved using get_graphics_ptr().
Arguments:

graphics_ptr pointer to graphics data
Returns:

0 on success, -1 on failure
Vega Prime Version:
OpenGL Version:
DirectX 9 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.
Callable From:

C++

function diguyCharacter::set_graphics_api_node_ptr

Prototype:
void set_graphics_api_node_ptr(void* node_ptr);
Description:

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.
Arguments:

node_ptr generic void* pointer
Callable From:

C++
Script

function diguyCharacter::get_graphics_api_node_ptr

Prototype:
void* get_graphics_api_node_ptr();
Returns:

pointer set by most recent call to set_graphics_api_node_ptr
Callable From:

C++

function diguyCharacter::set_user_data

Prototype:
int set_user_data(void* user_data);
Description:

This function stores a pointer to user data.
Arguments:

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
Callable From:

C++

function diguyCharacter::get_user_data

Prototype:
void* get_user_data();
Returns:

The user data pointer set by set_user_data()
Callable From:

C++

Action Functions

Unless otherwise specified, callable from:

C++
Script

function diguyCharacter::set_desired_action

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

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.
Arguments:

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

function diguyCharacter::get_desired_action

Prototype:
const char* get_desired_action();
Returns:

name of desired action; see set_desired_action()
Mode Restrictions:

This function can only be called in free action mode.

function diguyCharacter::get_current_action

Prototype:
const char* get_current_action();
Returns:

name of current action being performed by the character

function diguyCharacter::force_action

Prototype:
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);
Description:

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.
Arguments:

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

function diguyCharacter::force_action_with_duration

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

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.
Arguments:

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

0 on success, -1 on failure

function diguyCharacter::force_action_and_path_shape

Prototype:
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);
Description:

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.
Arguments:

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

function diguyCharacter::get_most_recent_forced_action

Prototype:
const char* get_most_recent_forced_action();
Description:

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

function diguyCharacter::get_most_recent_forced_action_t

Prototype:
float get_most_recent_forced_action_t();
Description:

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

function diguyCharacter::get_most_recent_forced_action_t_offset

Prototype:
float get_most_recent_forced_action_t_offset();
Description:

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

function diguyCharacter::add_pending_desired_action

Prototype:
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);
Description:

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.
Arguments:

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

function diguyCharacter::add_pending_force_action

Prototype:
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);
Description:

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

function diguyCharacter::is_valid_action

Prototype:
int is_valid_action(const char* action);
Returns:

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

function diguyCharacter::die_now

Prototype:
int die_now(const char* preferred_dead_action_name = "(default)");
Description:

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

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::revive_now

Prototype:
int revive_now(const char* preferred_revive_action_name = "(default)");
Description:

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::get_dead

Prototype:
int get_dead();
Description:

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.

function diguyCharacter::set_speed

Prototype:
int set_speed(float speed);
Description:

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:

by calling set_speed() with an argument of DIGUY_DEFAULT_FLOAT, or
by calling set_desired_action(), or
by calling one of the force_action() functions
Arguments:

speed desired speed in meters per second
Returns:

0 on success, -1 on failure

function diguyCharacter::get_speed

Prototype:
float get_speed();
Returns:

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

Position and Orientation Functions

Unless otherwise specified, callable from:

C++
Script

function diguyCharacter::set_position

Prototype:
int set_position(float tx, float ty, float tz);
Description:

Sets the position of the character relative to the origin of the Boston Dynamics 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 Boston Dynamics 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.
Arguments:

tx, ty, tz position in meters from the origin
Returns:

0 on success, -1 on failure

function diguyCharacter::set_position_double

Prototype:
int set_position_double(double tx, double ty, double tz);
Description:

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.
Arguments:

tx, ty, tz position in meters from the origin
Returns:

0 on success, -1 on failure

function diguyCharacter::get_position

Prototype:
int get_position(float* tx, float* ty, float* tz);
Description:

Retrieves the position of the character in the Boston Dynamics global coordinate system.

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

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

function diguyCharacter::get_position_double

Prototype:
int get_position_double(double* tx, double* ty, double* tz);
Description:

Retrieves the position of the character in the Boston Dynamics 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.
Arguments:

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

function diguyCharacter::set_position_relative_to_parent

Prototype:
int set_position_relative_to_parent(float tx, float ty, float tz);
Description:

Sets the position of the character relative to its parent or the origin of the Boston Dynamics 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.
Arguments:

tx, ty, tz position in meters from the origin
Returns:

0 on success, -1 on failure

function diguyCharacter::get_position_relative_to_parent

Prototype:
int get_position_relative_to_parent(float* tx, float* ty, float* tz);
Description:

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

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

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

function diguyCharacter::set_position_to_other_character_position

Prototype:
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);
Description:

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.
Arguments:

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

function diguyCharacter::set_desired_position

Prototype:
int set_desired_position(float tx, float ty, float tz,
    int force_guide_unacquired = 0);
Description:

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.
Arguments:

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

function diguyCharacter::set_desired_position_to_current_position

Prototype:
int set_desired_position_to_current_position(int also_set_orientation = 1);
Description:

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.
Arguments:

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

0 on success, -1 on failure

function diguyCharacter::set_desired_position_to_waypoint

Prototype:
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);
Description:

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.
Arguments:

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

function diguyCharacter::set_desired_position_to_path_waypoint

Prototype:
int set_desired_position_to_path_waypoint(const char* path_name,
    const char* waypoint_name);
Description:

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.
Arguments:

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

0 on success, -1 on failure

function diguyCharacter::set_desired_position_to_path_shape_waypoint

Prototype:
int set_desired_position_to_path_shape_waypoint(const char* path_shape_name,
    const char* waypoint_name);
Description:

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.
Arguments:

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

0 on success, -1 on failure

function diguyCharacter::get_desired_position

Prototype:
int get_desired_position(float* tx, float* ty, float* tz);
Description:

Retrieves the desired position of the character.
Mode Restrictions:

This function can only be called in free position mode.
Arguments:

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

function diguyCharacter::get_delta_to_desired_position

Prototype:
int get_delta_to_desired_position(float* tx, float* ty, float* tz);
Description:

Retrieves the delta vector from current position to desired one.
Mode Restrictions:

This function can only be called in free position mode.
Arguments:

tx, ty, tz delta in meters

Pass NULL for any values that are not needed.
Returns:

0 on success, -1 on failure

function diguyCharacter::set_initial_position

Prototype:
int set_initial_position(float tx, float ty, float tz);
Description:

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.
Arguments:

tx, ty, tz initial position in meters from the origin
Returns:

0 on success, -1 on failure

function diguyCharacter::get_initial_position

Prototype:
int get_initial_position(float* tx, float* ty, float* tz);
Description:

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.
Arguments:

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

function diguyCharacter::set_orientation

Prototype:
int set_orientation(float rz, float rx, float ry);
Description:

Sets the orientation of the character relative to the origin of the Boston Dynamics 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 of 'z' or 'n' or even sometimes 'd' (as set by the set_up_vector() call) the rx and ry values will not have any effect. To be able to set rx and ry values, set the up vector 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.
Arguments:

rz, rx, ry orientations in degrees
Returns:

0 on success, -1 on failure

function diguyCharacter::get_orientation

Prototype:
int get_orientation(float* rz, float* rx, float* ry);
Description:

Retrieves the orientation of the character in the Boston Dynamics 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.
Arguments:

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

function diguyCharacter::set_orientation_relative_to_parent

Prototype:
int set_orientation_relative_to_parent(float rz, float rx, float ry);
Description:

Sets the orientation of the character relative to its parent or the origin of the Boston Dynamics 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.
Arguments:

rz, rx, ry orientations in degrees
Returns:

0 on success, -1 on failure

function diguyCharacter::get_orientation_relative_to_parent

Prototype:
int get_orientation_relative_to_parent(float* rz, float* rx, float* ry);
Description:

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

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

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

function diguyCharacter::set_initial_up_vector

Prototype:
int set_initial_up_vector(char axis);
Description:

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

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

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

'd' - use default settings; character will change up vector 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 of 'z' effectively zeroes out the rx and ry values of the character's orientation.

Having an up vector 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 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

function diguyCharacter::get_initial_up_vector

Prototype:
char get_initial_up_vector();
Returns:

current up vector; see set_initial_up_vector()

function diguyCharacter::set_up_vector

Prototype:
int set_up_vector(char axis);
Description:

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

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

axis the up vector the character should use; see set_initial_up_vector() for description
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision Bead

function diguyCharacter::get_up_vector

Prototype:
char get_up_vector();
Returns:

current up vector; see set_up_vector()

function diguyCharacter::set_custom_orientation_rx_and_ry

Prototype:
int set_custom_orientation_rx_and_ry(float rx,
    float ry);
Description:

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 of 'z' or 'n' or even sometimes 'd' (as set by the set_up_vector() call) this function will not have any effect. To be able to set rx and ry values, set the up vector 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.
Arguments:

rx, ry orientations in degrees
Returns:

0 on success, -1 on failure

function diguyCharacter::set_desired_orientation

Prototype:
int set_desired_orientation(float rz, float rx, float ry,
    int force_guide_unacquired = 0);
Description:

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.
Arguments:

rz, rx, ry orientations in degrees counter-clockwise from the positive X axis
Returns:

0 on success, -1 on failure

function diguyCharacter::get_desired_orientation

Prototype:
int get_desired_orientation(float* rz, float* rx, float* ry);
Description:

Retrieves the desired orientation of the character.
Mode Restrictions:

This function can only be called in free position mode.
Arguments:

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

function diguyCharacter::get_delta_to_desired_orientation

Prototype:
int get_delta_to_desired_orientation(float* rz, float* rx, float* ry);
Description:

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.
Arguments:

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

function diguyCharacter::set_desired_orientation_to_current_orientation

Prototype:
int set_desired_orientation_to_current_orientation();
Description:

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

function diguyCharacter::set_desired_orientation_towards_position

Prototype:
int set_desired_orientation_towards_position(float x, float y, float z,
    int force_guide_unacquired = 0);
Description:

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

function diguyCharacter::set_initial_orientation

Prototype:
int set_initial_orientation(float rz, float rx, float ry);
Description:

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.
Arguments:

rz, rx, ry orientations in degrees counter-clockwise from the positive X axis
Returns:

0 on success, -1 on failure

function diguyCharacter::get_initial_orientation

Prototype:
int get_initial_orientation(float* rz, float* rx, float* ry);
Description:

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.
Arguments:

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

function diguyCharacter::get_link_position

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

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

link_name name of the link; links are named after their inbound joint name
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

function diguyCharacter::get_link_position_double

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

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

link_name name of the link; links are named after their inbound joint name
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

function diguyCharacter::get_link_position_with_offset

Prototype:
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);
Description:

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

link_name name of the link
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

function diguyCharacter::get_link_position_with_offset_double

Prototype:
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);
Description:

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

link_name name of the link
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

function diguyCharacter::get_link_relative_position

Prototype:
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);
Description:

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

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

function diguyCharacter::get_link_relative_position_with_offset

Prototype:
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);
Description:

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

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

function diguyCharacter::set_apply_actor_scale_to_action_bead_travel

Prototype:
void set_apply_actor_scale_to_action_bead_travel(int apply_scale_flag);
Description:

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.
Arguments:

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

function diguyCharacter::get_apply_actor_scale_to_action_bead_travel

Prototype:
int get_apply_actor_scale_to_action_bead_travel();
Returns:

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

function diguyCharacter::local_to_global

Prototype:
int local_to_global(float x, float y, float z,
    float* res_x, float* res_y, float* res_z);
Description:

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.

function diguyCharacter::global_to_local

Prototype:
int global_to_local(float x, float y, float z,
    float* res_x, float* res_y, float* res_z);
Description:

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.

function diguyCharacter::get_velocity

Prototype:
void get_velocity(float* vel_x, float* vel_y, float* vel_z);
Description:

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.
Arguments:

vel_x, vel_y, vel_z meters/sec

Pass NULL for any values that are not needed.

function diguyCharacter::set_desired_velocity

Prototype:
void set_desired_velocity(float vel_x, float vel_y, float vel_z);
Description:

Currently only used by the Adaptive guide

Arguments:

vel_x, vel_y, vel_z meters/sec

function diguyCharacter::get_angular_velocity

Prototype:
void get_angular_velocity(float* vel_rz);
Description:

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.
Arguments:

vel_rz degrees/sec

Pass NULL for any values that are not needed.

Appearance Functions

function diguyCharacter::get_appearance

Prototype:
const char* get_appearance();
Description:

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

function diguyCharacter::set_appearance

Prototype:
int set_appearance(const char* appearance);
Description:

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().
Arguments:

appearance name of new base appearance
Returns:

0 on success, -1 on failure

function diguyCharacter::set_current_appearance

Prototype:
int set_current_appearance(const char* appearance,
    int allow_actor_change = 1);
Description:

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.
Arguments:

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::get_current_appearance

Prototype:
const char* get_current_appearance();
Returns:

current appearance; see set_current_appearance()

function diguyCharacter::get_current_appearance_is

Prototype:
int get_current_appearance_is(const char* appearance);
Description:

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
Callable From:

C++
Script
Decision

function diguyCharacter::set_current_head_appearance

Prototype:
int set_current_head_appearance(const char* head_appearance);
Description:

This function sets the current head appearance of this character.
Arguments:

head_appearance name of the new desired head appearance
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision Bead

function diguyCharacter::get_current_head_appearance

Prototype:
const char* get_current_head_appearance();
Returns:

current head appearance; see set_current_head_appearance()

function diguyCharacter::get_current_head_appearance_is

Prototype:
int get_current_head_appearance_is(const char* head_appearance);
Description:

Similar to get_current_appearance_is(), but for head appearance.
Returns:

1 if current head appearance has passed name; 0 if not
Callable From:

C++
Script
Decision

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

function diguyCharacter::set_lod_ranges

Prototype:
int set_lod_ranges(float* lod_ranges);
Description:

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().
Arguments:

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++

function diguyCharacter::set_graphics_lod

Prototype:
int set_graphics_lod(int lod);
Description:

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

lod an integer between 1 and 7
Returns:

0 on success, -1 on failure

function diguyCharacter::get_graphics_lod

Prototype:
int get_graphics_lod();
Returns:

current graphics LOD

function diguyCharacter::set_shader_lod

Prototype:
int set_shader_lod(int lod);
Description:

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.
Arguments:

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

0 on success, -1 on failure

function diguyCharacter::get_shader_lod

Prototype:
int get_shader_lod();
Returns:

current shader LOD

function diguyCharacter::set_motion_lod

Prototype:
int set_motion_lod(int motion_lod);
Description:
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.

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().
Arguments:

motion_lod an integer between 1 and 6
Returns:

0 on success, -1 on failure

function diguyCharacter::get_motion_lod

Prototype:
int get_motion_lod();
Returns:

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

function diguyCharacter::get_current_motion_lod

Prototype:
int get_current_motion_lod();
Returns:

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

function diguyCharacter::set_minimum_cpl

Prototype:
int set_minimum_cpl(int minimum_cpl);
Description:
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.
Arguments:

cpl minimum CPL allowed for this character
Returns:

0 on success, -1 on failure

function diguyCharacter::get_minimum_cpl

Prototype:
int get_minimum_cpl();
Returns:

most recent setting of set_minimum_cpl()

function diguyCharacter::get_maximum_possible_current_cpl

Prototype:
int get_maximum_possible_current_cpl();
Description:

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

function diguyCharacter::maximize_current_cpl

Prototype:
int maximize_current_cpl();
Description:

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

function diguyCharacter::set_automatic_cpl_switching_enabled

Prototype:
int set_automatic_cpl_switching_enabled(int enabled);
Description:

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.
Arguments:

enabled pass 1 to enable automatic CPL switching, 0 to disable it
Returns:

0 on success, -1 on failure

function diguyCharacter::get_automatic_cpl_switching_enabled

Prototype:
int get_automatic_cpl_switching_enabled();
Returns:

most recent setting of get_automatic_cpl_switching_enabled()

function diguyCharacter::set_current_cpl

Prototype:
int set_current_cpl(int current_cpl);
Description:

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.
Arguments:

cpl new current CPL
Returns:

0 on success, -1 on failure

function diguyCharacter::get_current_cpl

Prototype:
int get_current_cpl();
Returns:

the current CPL the character is using

function diguyCharacter::set_position_update_rate

Prototype:
int set_position_update_rate(int update_rate);
Description:

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().
Arguments:

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

function diguyCharacter::get_position_update_rate

Prototype:
int get_position_update_rate();
Returns:

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

function diguyCharacter::set_pose_update_rate

Prototype:
int set_pose_update_rate(int update_rate);
Description:

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().
Arguments:

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

function diguyCharacter::get_pose_update_rate

Prototype:
int get_pose_update_rate();
Returns:

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

function diguyCharacter::set_minimum_full_update_period

Prototype:
int set_minimum_full_update_period(float min_period);
Description:

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.
Arguments:

min_period in seconds
Returns:

0 on success, -1 on failure

function diguyCharacter::get_minimum_full_update_period

Prototype:
float get_minimum_full_update_period();
Returns:

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

function diguyCharacter::set_position_accumulation_disabled

Prototype:
int set_position_accumulation_disabled(int disabled_flag);
Description:

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.
Arguments:

disabled_flag pass 1 to disable position accumulation, 0 to enable it
Returns:

0 on success, -1 on failure

function diguyCharacter::get_position_accumulation_disabled

Prototype:
int get_position_accumulation_disabled();
Returns:

most recent setting of set_position_accumulation_disabled()

function diguyCharacter::set_all_blends_disabled

Prototype:
int set_all_blends_disabled(int disabled_flag);
Description:

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.
Arguments:

disabled_flag pass 1 to disable all blends, 0 to enable them
Returns:

0 on success, -1 on failure

function diguyCharacter::get_all_blends_disabled

Prototype:
int get_all_blends_disabled();
Returns:

most recent setting of set_all_blends_disabled()

function diguyCharacter::set_shape_switches_disabled

Prototype:
int set_shape_switches_disabled(int disabled_flag);
Description:
Note: This function is not recommend. 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.
Arguments:

disabled_flag pass 1 to disable shape switches, 0 to enable them
Returns:

0 on success, -1 on failure

function diguyCharacter::get_shape_switches_disabled

Prototype:
int get_shape_switches_disabled();
Returns:

most recent setting of set_shape_switches_disabled()

function diguyCharacter::set_shape_callbacks_disabled

Prototype:
int set_shape_callbacks_disabled(int disabled_flag);
Description:
Note: This function is not recommend. 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.
Arguments:

disabled_flag pass 1 to disable shape callbacks, 0 to enable them
Returns:

0 on success, -1 on failure

function diguyCharacter::get_shape_callbacks_disabled

Prototype:
int get_shape_callbacks_disabled();
Returns:

most recent setting of set_shape_callbacks_disabled()

function diguyCharacter::set_graphics_api_shape_update_disabled

Prototype:
int set_graphics_api_shape_update_disabled(int disabled_flag);
Description:
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.
Arguments:

disabled_flag pass 1 to disable update calls, 0 to enable them
Returns:

0 on success, -1 on failure

function diguyCharacter::get_graphics_api_shape_update_disabled

Prototype:
int get_graphics_api_shape_update_disabled();
Returns:

most recent setting of set_graphics_api_shape_update_disabled()

function diguyCharacter::optimized_update

Prototype:
int optimized_update(float t);
Description:

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.
Arguments:

t new time for the character
Returns:

0 on success, -1 on failure

function diguyCharacter::set_is_load_managed

Prototype:
int set_is_load_managed(int is_load_managed);
Description:

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.
Arguments:

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

0 on success, -1 on failure

function diguyCharacter::get_is_load_managed

Prototype:
int get_is_load_managed();
Returns:

most recent setting of set_graphics_api_shape_update_disabled()

Callback Functions

Unless otherwise specified, all functions callable from:

C++
Script

enumeration

	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_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_CURRENT_TOUT_REACHED,
		CALLBACK_ID_POST_CREATE_GEOMETRY,
		CALLBACK_ID_PRE_DESTROY_GEOMETRY,
		CALLBACK_ID_END_OF_PATH_REACHED,

		// DI-Guy Scenario UI callbacks:
		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,

		// DI-Guy AI agent callbacks:
		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_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
	};
Description:

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 before the 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().
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().
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.
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_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_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.

function diguyCharacter::add_callback

Prototype:
int add_callback(int callback_id,
    diguyCharacterCallback* callback,
    void* callback_params = 0,
    void* callback_user_data = 0);
Description:

This function adds a user callback. Callbacks can be removed with remove_callback() or remove_callback_with_user_data().
Arguments:

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
Callable From:

C++

function diguyCharacter::remove_callback

Prototype:
int remove_callback(int callback_id,
    diguyCharacterCallback* callback);
Description:

This function removes a user callback. All callbacks matching the specified callback_id and callback function will be removed.
Arguments:

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
Callable From:

C++

function diguyCharacter::remove_callback_with_user_data

Prototype:
int remove_callback_with_user_data(int callback_id,
    void* callback_user_data);
Description:

This function removes a user callback. All callbacks matching the specified callback_id and callback_user_data pointer will be removed.
Arguments:

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
Callable From:

C++

function diguyCharacter::add_callback_script

Prototype:
int add_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type = NULL);
Description:

This function adds a user callback script. Callback scripts can be removed with remove_callback_script().
Arguments:

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");

function diguyCharacter::remove_callback_script

Prototype:
int remove_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type = NULL);
Description:

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

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");

Event Handler Functions

Unless otherwise specified, all functions callable from:

C++
Script

function diguyCharacter::map_event_handler_to_callback_id

Prototype:
int map_event_handler_to_callback_id(int callback_id,
    const char* handler_name);
Description:

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"
Arguments:

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

0 on success, -1 on failure

function diguyCharacter::unmap_event_handler_from_callback_id

Prototype:
int unmap_event_handler_from_callback_id(int callback_id,
    const char* handler_name,
    int unmap_all_matches = 0);
Description:

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

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

function diguyCharacter::manually_invoke_event_handler

Prototype:
diguyCallbackReturn manually_invoke_event_handler(const char* handler_name);
Description:

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.
Arguments:

handler_name name of the event handler to invoke
Returns:

DIGUY_CALLBACK_CONTINUE or DIGUY_CALLBACK_STOP
Callable From:

C++
Script
Decision

Path Functions

function diguyCharacter::create_path

Prototype:
diguyCharacterPath* create_path(const char* name);
Description:

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().
Arguments:

The path makes internal copies of all arguments.

name name of the new path
Returns:

pointer to type diguyCharacterPath
Callable From:

C++

function diguyCharacter::create_simple_path

Prototype:
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);
Description:

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().
Arguments:

The path makes internal copies of all arguments.

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
Callable From:

C++

function diguyCharacter::create_path_from_path_shape

Prototype:
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);
Description:

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

The path makes internal copies of all arguments.

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
Callable From:

C++

function diguyCharacter::create_and_force_bridge_path

Prototype:
int create_and_force_bridge_path(const char* destination_path_name,
    const char* destination_path_action_bead_name,
    const char* via_action_name);
Description:

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.
Arguments:

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

function diguyCharacter::create_and_force_bridge_path_to_point

Prototype:
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);
Description:

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.
Arguments:

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

function diguyCharacter::destroy_path

Prototype:
int destroy_path(diguyCharacterPath* path);
Description:

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.
Arguments:

path path to be destroyed
Returns:

0 on success, -1 on failure

function diguyCharacter::get_num_paths

Prototype:
int get_num_paths();
Returns:

the number of paths belonging to this character

function diguyCharacter::get_path_at_index

Prototype:
diguyCharacterPath* get_path_at_index(int index);
Returns:

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

index index of the path; indices start at 0

function diguyCharacter::get_path_name_at_index

Prototype:
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

function diguyCharacter::get_current_path_index

Prototype:
int get_current_path_index();
Description:

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

function diguyCharacter::get_current_traveled_path

Prototype:
diguyCharacterPath* get_current_traveled_path();
Description:

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

function diguyCharacter::get_current_traveled_path_is

Prototype:
int get_current_traveled_path_is(const char* path_name);
Description:

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
Callable From:

C++
Script
Decision

function diguyCharacter::push_path

Prototype:
int push_path(const char* path_name);
Description:

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()).
Arguments:

name name of the path to be pushed
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision Bead

function diguyCharacter::force_path

Prototype:
int force_path(const char* path_name,
    float max_rampdown_interval = 0.5f);
Description:

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()).
Arguments:

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::force_partial_path

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

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()).
Callable From:

C++
Script
Decision Bead

function diguyCharacter::resume_interrupted_path

Prototype:
int resume_interrupted_path(float max_rampdown_interval = 0.5f);
Description:

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.
Arguments:

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::force_local_path

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

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.
Arguments:

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

function diguyCharacter::set_initial_path

Prototype:
int set_initial_path(const char* name);
Description:

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

name name of the path that will be the initial path
Returns:

0 on success, -1 on failure

function diguyCharacter::get_initial_path

Prototype:
const char* get_initial_path();
Description:

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

function diguyCharacter::translate_all_paths

Prototype:
void translate_all_paths(float tx, float ty, float tz,
    int reclamp_waypoints = 1);
Description:

This function translates all of the paths of this character.
Arguments:

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

function diguyCharacter::rotate_all_paths_about_point

Prototype:
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);
Description:

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

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

function diguyCharacter::rotate_all_paths_about_current_waypoint

Prototype:
int rotate_all_paths_about_current_waypoint(float rz, float rx, float ry,
    int reclamp_waypoints = 1);
Description:

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

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

function diguyCharacter::jump_to_action_bead

Prototype:
int jump_to_action_bead(const char* bead_name,
    float max_rampdown_interval = 0.5f);
Description:

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.
Arguments:

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

function diguyCharacter::find_path

Prototype:
diguyCharacterPath* find_path(const char* path_name);
Description:

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

name name of the path to be found
Returns:

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

function diguyCharacter::apply_aim_bead

Prototype:
int apply_aim_bead(diguyCharacterPathAimBead* bead,
    float how_far = 0.0f);
Description:

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.
Arguments:

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

function diguyCharacter::apply_decision_bead

Prototype:
int apply_decision_bead(diguyCharacterPathDecisionBead* bead,
    float how_far = 0.0f);
Description:

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.
Arguments:

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

function diguyCharacter::apply_gaze_bead

Prototype:
int apply_gaze_bead(diguyCharacterPathGazeBead* bead,
    float how_far = 0.0f);
Description:

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.
Arguments:

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

function diguyCharacter::apply_script_bead

Prototype:
int apply_script_bead(diguyCharacterPathScriptBead* bead,
    float how_far = 0.0f);
Description:

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.
Arguments:

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

function diguyCharacter::set_distance_along_path

Prototype:
int set_distance_along_path(float distance);
Description:

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.
Arguments:

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

0 on success, -1 on failure

function diguyCharacter::get_distance_along_path

Prototype:
float 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.

function diguyCharacter::leave_path

Prototype:
int leave_path();
Description:

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

function diguyCharacter::get_nearest_waypoint_index_in_path

Prototype:
int get_nearest_waypoint_index_in_path(const char* path_name);
Description:

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

function diguyCharacter::get_distance_to_path

Prototype:
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

Link and Shape Functions

The following functions provide access to the links (bones) and shapes (visible geometry) of the character.

function diguyCharacter::get_position_link

Prototype:
diguyGraphicsLink* get_position_link();
Description:

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

function diguyCharacter::get_num_links

Prototype:
int get_num_links();
Returns:

number of links on this character

function diguyCharacter::get_link_at_index

Prototype:
diguyGraphicsLink* get_link_at_index(int index);
Returns:

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

index index of the link; indices start at 0

function diguyCharacter::find_link

Prototype:
diguyGraphicsLink* find_link(const char* name);
Description:

This function returns a pointer to the specified link.
Arguments:

name name of link to be found
Returns:

pointer of type diguyGraphicsLink; NULL if not found

function diguyCharacter::get_link_name_at_index

Prototype:
const char* get_link_name_at_index(int link_index);
Returns:

the string identifying the link at the given index
Arguments:

link_index index of the link; indices start at 0

function diguyCharacter::get_num_link_shapes

Prototype:
int get_num_link_shapes(const char* link_name);
Returns:

the number of shapes on the specified link
Arguments:

link_name name of the link

function diguyCharacter::get_link_shape_name_at_index

Prototype:
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
Arguments:

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

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

function diguyCharacter::set_altitude_function

Prototype:
int set_altitude_function(diguyAltitudeFunction* altitude_function);
Description:

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.

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

C++

function diguyCharacter::get_altitude_function

Prototype:
diguyAltitudeFunction* get_altitude_function();
Returns:

current altitude function; see set_altitude_function()
Callable From:

C++

function diguyCharacter::set_altitude_function_enabled_in_free_position_mode

Prototype:
int set_altitude_function_enabled_in_free_position_mode(int enabled);
Description:

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().
Arguments:

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

function diguyCharacter::get_altitude_function_enabled_in_free_position_mode

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

function diguyCharacter::set_altitude_function_enabled_in_path_position_mode

Prototype:
int set_altitude_function_enabled_in_path_position_mode(int value);
Description:

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().
Arguments:

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

function diguyCharacter::get_altitude_function_enabled_in_path_position_mode

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

function diguyCharacter::set_altitude_update_rate

Prototype:
int set_altitude_update_rate(int update_rate);
Description

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().
Arguments:

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

function diguyCharacter::get_altitude_update_rate

Prototype:
int get_altitude_update_rate();
Returns:

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

function diguyCharacter::set_altitude_interpolation_rate

Prototype:
void set_altitude_interpolation_rate(float interpolation_rate);
Description

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.
Arguments:

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.

function diguyCharacter::get_altitude_interpolation_rate

Prototype:
float get_altitude_interpolation_rate();
Returns:

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

Pose Functions

These functions are used to query a character's joint angles, and set them to the joint angles to arbitrary values.

Pose Override Stages

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:

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

Pose Override C++ Example

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

function diguyCharacter::get_pose_array_size

Prototype:
int get_pose_array_size();
Description:

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

function diguyCharacter::get_pose_in_radians

Prototype:
int get_pose_in_radians(float* pose_array);
Description:

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().
Arguments:

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

function diguyCharacter::create_pose_override

Prototype:
diguyCharacterPoseOverride* create_pose_override(int override_stage = 3);
Description:

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.
Arguments:

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

object of type diguyCharacterPoseOverride

function diguyCharacter::destroy_pose_override

Prototype:
int destroy_pose_override(diguyCharacterPoseOverride* po);
Description:

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

po pose override object to be destroyed
Returns:

0 on success, -1 on failure

function diguyCharacter::get_num_pose_overrides

Prototype:
int get_num_pose_overrides();
Returns:

the number of pose overrides belonging to this character

function diguyCharacter::get_pose_override_at_index

Prototype:
diguyCharacterPoseOverride* get_pose_override_at_index(int index);
Returns:

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

index index of the pose override; indices start at 0

function diguyCharacter::create_complete_pose_override

Prototype:
diguyCharacterPoseOverride* create_complete_pose_override();
Description:

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

function diguyCharacter::destroy_complete_pose_override

Prototype:
void destroy_complete_pose_override();
Description:

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

Gaze and Point Functions

function diguyCharacter::gaze_at_angle

Prototype:
int gaze_at_angle(float azimuth,
    float elevation,
    float distance,
    int is_new_gaze = 1);
Description:

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 Boston Dynamics coordinate system origin. Angles are given with respect to the Boston Dynamics 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()).
Arguments:

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

function diguyCharacter::gaze_at_angle_local

Prototype:
int gaze_at_angle_local(float azimuth,
    float elevation,
    float distance = 10000.0f,
    int is_new_gaze = 1);
Description:

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

function diguyCharacter::gaze_at_point

Prototype:
int gaze_at_point(float tx,
    float ty,
    float tz,
    int is_new_gaze = 1);
Description:

This function sets the current fixation point of the character's gaze. Point coordinates are given in meters in the Boston Dynamics 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()).
Arguments:

tx, ty, tz position in meters from the Boston Dynamics 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

function diguyCharacter::gaze_at_point_local

Prototype:
int gaze_at_point_local(float tx,
    float ty,
    float tz,
    int is_new_gaze = 1);
Description:

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

function diguyCharacter::gaze_at_character

Prototype:
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);
Description:

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()).
Arguments:

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
Callable From:

C++
Script
Decision Bead
C++ Example:
// gaze at the head of character "soldier-1".
ch->gaze_at_character("soldier-1",
"cervical",
0.0,
0.0,
0.0);

function diguyCharacter::get_gaze_is_active

Prototype:
int get_gaze_is_active();
Returns:

1 if the character is actively gazing, 0 if not

function diguyCharacter::get_gaze_point

Prototype:
int get_gaze_point(float* x, float* y, float* z);
Returns:

the current gaze point relative to the Boston Dynamics global coordinate system

function diguyCharacter::get_gaze_is_acquired

Prototype:
int get_gaze_is_acquired();
Description:

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

function diguyCharacter::get_gaze_is_steady

Prototype:
int get_gaze_is_steady();
Description:

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

function diguyCharacter::end_gaze

Prototype:
int end_gaze();
Description:

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.

function diguyCharacter::lpoint_at_angle

Prototype:
int lpoint_at_angle(float azimuth,
    float elevation,
    float distance,
    int is_new_lpoint = 1,
    const char* base_gesture_name = 0);
Description:

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()).
Arguments:

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

function diguyCharacter::lpoint_at_angle_local

Prototype:
int lpoint_at_angle_local(float azimuth,
    float elevation,
    float distance = 10000.0f,
    int is_new_lpoint = 1,
    const char* base_gesture_name = 0);
Description:

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

function diguyCharacter::lpoint_at_point

Prototype:
int lpoint_at_point(float tx,
    float ty,
    float tz,
    int is_new_lpoint = 1,
    const char* base_gesture_name = 0);
Description:

This function sets the current fixation point for the character's left pointing. Point coordinates are given in meters in the Boston Dynamics 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()).
Arguments:

tx, ty, tz position in meters from the Boston Dynamics 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

function diguyCharacter::lpoint_at_point_local

Prototype:
int lpoint_at_point_local(float tx,
    float ty,
    float tz,
    int is_new_lpoint = 1,
    const char* base_gesture_name = 0);
Description:

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

function diguyCharacter::lpoint_at_character

Prototype:
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);
Description:

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

function diguyCharacter::get_lpoint_point

Prototype:
int get_lpoint_point(float* x, float* y, float* z);
Returns:

the current lpoint target point relative to the Boston Dynamics global coordinate system

function diguyCharacter::get_lpoint_base_gesture_name

Prototype:
const char* get_lpoint_base_gesture_name();
Returns:

the current base gesture of the lpoint

function diguyCharacter::get_lpoint_is_active

Prototype:
int get_lpoint_is_active();
Returns:

1 if the character is actively lpointing, 0 if not

function diguyCharacter::get_lpoint_is_acquired

Prototype:
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

function diguyCharacter::get_lpoint_is_steady

Prototype:
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

function diguyCharacter::end_lpoint

Prototype:
int end_lpoint();
Description:

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.

function diguyCharacter::set_gaze_params_to_defaults

Prototype:
int set_gaze_params_to_defaults();
Description:

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

function diguyCharacter::set_gaze_param_desired_locate_time

Prototype:
int set_gaze_param_desired_locate_time(float t);
Description:

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.
Arguments:

t lower value results in faster turning rate
Returns:

0 on success, -1 on failure

function diguyCharacter::get_gaze_param_desired_locate_time

Prototype:
float get_gaze_param_desired_locate_time();
Returns:

the most recent setting of set_gaze_param_desired_locate_time()

function diguyCharacter::set_gaze_link_uses_desired_locate_time

Prototype:
int set_gaze_link_uses_desired_locate_time(const char* link_name,
    int uses_desired_locate_time);
Description:

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:

orientation 1
back 1
cervical 1
eye_l 0
shoulder_l 1
elbow_l 1
Arguments:

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

function diguyCharacter::get_gaze_link_uses_desired_locate_time

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

function diguyCharacter::set_gaze_link_azimuth_limits

Prototype:
int set_gaze_link_azimuth_limits(const char* link_name, float min, float max);
Description:

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:

back -45 to 45
cervical -80 to 80
eye_l -50 to 50
shoulder_l -30 to 135
elbow_l -30 to 10
Arguments:

link_name name of the link
min value <= 0; in degrees
max value >= 0; in degrees
Returns:

0 on success, -1 on failure

function diguyCharacter::get_gaze_link_azimuth_limits

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

function diguyCharacter::set_gaze_link_elevation_limits

Prototype:
int set_gaze_link_elevation_limits(const char* link_name,
    float min,
    float max);
Description:

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:

back -15 to 45
cervical -80 to 45
eye_l -40 to 40
shoulder_l -80 to 80
elbow_l -170 to 0
Arguments:

link_name name of the link
min value <= 0; in degrees
max value >= 0; in degrees
Returns:

0 on success, -1 on failure

function diguyCharacter::get_gaze_link_elevation_limits

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

function diguyCharacter::set_gaze_link_azimuth_tolerance

Prototype:
int set_gaze_link_azimuth_tolerance(const char* link_name,
    float min,
    float max);
Description:

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:

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
Arguments:

link_name name of the link
min value <= 0; in degrees
max value >= 0; in degrees
Returns:

0 on success, -1 on failure

function diguyCharacter::get_gaze_link_azimuth_tolerance

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

function diguyCharacter::set_gaze_link_elevation_tolerance

Prototype:
int set_gaze_link_elevation_tolerance(const char* link_name,
    float min,
    float max);
Description:

The elevation equivalent of set_gaze_link_azimuth_tolerance(),

Valid link names and defaults:

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
Arguments:

link_name name of the link
min value <= 0; in degrees
max value >= 0; in degrees
Returns:

0 on success, -1 on failure

function diguyCharacter::get_gaze_link_elevation_tolerance

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

function diguyCharacter::set_gaze_link_max_angular_vel

Prototype:
int set_gaze_link_max_angular_vel(const char* link_name, float angular_vel);
Description:

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:

back 30 deg/s
cervical 60 deg/s
eye_l 180 deg/s
shoulder_l 180 deg/s
elbow_l 180 deg/s
Arguments:

link_name name of the link
angular_vel angular velocity in degrees per second
Returns:

0 on success, -1 on failure

function diguyCharacter::get_gaze_link_max_angular_vel

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

function diguyCharacter::set_gaze_link_scale_factor

Prototype:
int set_gaze_link_scale_factor(const char* link_name, float scale_factor);
Description:

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:

back 0.75
cervical 0.5
eye_l 1.0
shoulder_l 0.9
elbow_l 1.0
Arguments:

link_name name of the link
scale_factor scale factor between 0 and 1
Returns:

0 on success, -1 on failure

function diguyCharacter::get_gaze_link_scale_factor

Prototype:
int get_gaze_link_scale_factor(const char* link_name, float* scale_factor);
Returns:

the most recent setting of set_gaze_link_scale_factor()

function diguyCharacter::set_link_enabled_for_gaze

Prototype:
int set_link_enabled_for_gaze(const char* link_name, int enabled);
Description:

This function sets whether the character can turn the specified link in pursuit of the gaze target.

Valid link names and defaults:

orientation 0
back 1
cervical 1
eye_l 1 if character has movable eyes, else 0
shoulder_l 0
elbow_l 0
Arguments:

link_name name of the link
enabled 1 to enable, 0 to disable
Returns:

0 on success, -1 on failure

function diguyCharacter::get_link_enabled_for_gaze

Prototype:
int get_link_enabled_for_gaze(const char* link_name);
Returns:

the most recent setting of set_link_enabled_for_gaze()

function diguyCharacter::set_gaze_can_change_posture

Prototype:
int set_gaze_can_change_posture(int enabled);
Description:

This function sets whether the character can change its current posture in pursuit of the gaze target.

Gaze can change current posture by default.
Arguments:

enabled 1 to enable, 0 to disable
Returns:

0 on success, -1 on failure

function diguyCharacter::get_gaze_can_change_posture

Prototype:
int get_gaze_can_change_posture();
Returns:

the most recent setting of set_gaze_can_change_posture()

function diguyCharacter::set_gaze_can_change_variant

Prototype:
int set_gaze_can_change_variant(int enabled);
Description:

This function sets whether the character can change its current variant in pursuit of the gaze target.

Gaze can change current variant by default.
Arguments:

enabled 1 to enable, 0 to disable
Returns:

0 on success, -1 on failure

function diguyCharacter::get_gaze_can_change_variant

Prototype:
int get_gaze_can_change_variant();
Returns:

the most recent setting of set_gaze_can_change_variant()

function diguyCharacter::set_link_enabled_for_lpoint

Prototype:
int set_link_enabled_for_lpoint(const char* link_name, int enabled);
Description:

This function sets whether the character can move the specified link in pursuit of the lpoint target.

Valid link names and defaults:

orientation 0
back 1
cervical 0
eye_l 0
shoulder_l 1
elbow_l 1
Arguments:

link_name name of the link
enabled 1 to enable, 0 to disable
Returns:

0 on success, -1 on failure

function diguyCharacter::get_link_enabled_for_lpoint

Prototype:
int get_link_enabled_for_lpoint(const char* link_name);
Returns:

the most recent setting of set_link_enabled_for_lpoint()

function diguyCharacter::set_nod

Prototype:
int set_nod(float azimuth,
    float elevation,
    float duration = 0.5f);
Description:

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()).
Arguments:

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

function diguyCharacter::nod_head

Prototype:
int nod_head(float duration,
    float nod_count,
    float nod_elevation0 = 15.0f,
    float nod_elevation1 = 0.0f,
    float nod_elevation_out = 0.0f);
Description:

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()).
Arguments:

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::shake_head

Prototype:
int shake_head(float duration,
    float shake_count,
    float shake_azimuth0 = -20.0f,
    float shake_azimuth1 = 20.0f,
    float shake_azimuth_out = 0.0f);
Description:

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()).
Arguments:

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::get_nod_azimuth

Prototype:
float get_nod_azimuth();
Returns:

current nod azimuth setting; see set_nod(), nod_head(), and shake_head()

function diguyCharacter::get_nod_elevation

Prototype:
float get_nod_elevation();
Returns:

current nod elevation setting; see set_nod(), nod_head(), and shake_head()

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

function diguyCharacter::set_aim

Prototype:
int set_aim(float azimuth, float elevation);
Description:

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()).
Arguments:

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

function diguyCharacter::aim_at_angle

Prototype:
int aim_at_angle(float azimuth,
    float elevation,
    float distance,
    int is_new_aim = 1);
Description:

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 Boston Dynamics 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()).
Arguments:

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

function diguyCharacter::aim_at_angle_local

Prototype:
int aim_at_angle_local(float azimuth,
    float elevation,
    float distance,
    int is_new_aim = 1);
Description:

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

function diguyCharacter::aim_at_point

Prototype:
int aim_at_point(float x, float y, float z, int is_new_aim = 1);
Description:

This function sets the current fixation point of the character's aim. Point coordinates are given in meters in the Boston Dynamics 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()).
Arguments:

tx, ty, tz position in meters from the Boston Dynamics 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

function diguyCharacter::aim_at_point_local

Prototype:
int aim_at_point_local(float x, float y, float z, int is_new_aim = 1);
Description:

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

function diguyCharacter::aim_at_character

Prototype:
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);
Description:

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()).
Callable From:

C++
Script
Decision Bead
Arguments:

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
offset_tx, offset_ty, offset_tz offset onto the link, in meters
Returns:

0 on success, -1 on failure
C++ Example:
// aim at the head of character "soldier-1".
ch->aim_at_character("soldier-1",
"cervical",
0.0,
0.0,
0.0);

function diguyCharacter::end_aim

Prototype:
void end_aim();
Description:

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.

function diguyCharacter::aim_converge

Prototype:
int aim_converge(int max_iterations = 30);
Description:

This function attempts to have the character reach its desired aim angles instantly. Because of the algorithm used, this can take a number of iterations to achieve.

The max_iterations argument sets a maximum limit this function will use to try to acquire the aim. Setting this value too high can reduce performance.
Arguments:

max_iterations maximum number of internal iterations to use to acquire aim
Returns:

1 if aim converged to within tolerances; 0 if not

function diguyCharacter::get_aim_azimuth

Prototype:
float get_aim_azimuth();
Returns:

current aim azimuth; see set_aim()

function diguyCharacter::get_aim_trajectory

Prototype:
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
Arguments:

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

function diguyCharacter::get_aim_elevation

Prototype:
float get_aim_elevation();
Returns:

current aim elevation; see set_aim()

function diguyCharacter::get_aim_is_possible

Prototype:
int get_aim_is_possible();
Description:

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

function diguyCharacter::get_aim_is_acquired

Prototype:
int get_aim_is_acquired();
Returns:

1 if the aim is acquired, 0 if not

function diguyCharacter::get_aim_is_steady

Prototype:
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

function diguyCharacter::set_aim_algorithm

Prototype:
void set_aim_algorithm(int aim_algorithm);
Description:

Currently, 8 is the only valid input for this function, makes a DI-Guy 8 style aim.

function diguyCharacter::get_aim_algorithm

Prototype:
int get_aim_algorithm();
Returns:

current aim algorithm defaults to 8

function diguyCharacter::get_is_aiming

Prototype:
int get_is_aiming();
Returns:

1 if character is currently aiming, 0 if not

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

function diguyCharacter::set_aim_param_acquire_factor

Prototype:
void set_aim_param_acquire_factor(float factor);
Description:

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.

Setting the acquire factor to something very close to 1 (which would try to make up all of the difference in one frame) can result in an unstable, jittery convergence. The maximum recommended value is 0.95. If the aim is jittery, back off to 0.9 or lower.

To get "instant" convergence, call aim_converge() or set_aim_converge_every_frame().
Arguments:

factor unitless value between 0 and 1; default is 0.6

function diguyCharacter::get_aim_param_acquire_factor

Prototype:
float get_aim_param_acquire_factor();
Returns:

the current aim acquire factor parameter

function diguyCharacter::set_aim_param_new_aim_factor

Prototype:
void set_aim_param_new_aim_factor(float factor);
Description:

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.
Arguments:

factor unitless value between 0 and 1; default is 0.05

function diguyCharacter::get_aim_param_new_aim_factor

Prototype:
float get_aim_param_new_aim_factor();
Returns:

the current new aim factor parameter

function diguyCharacter::set_aim_param_new_aim_duration

Prototype:
void set_aim_param_new_aim_duration(float duration);
Description:

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.
Arguments:

duration how long, in seconds, a new aim should be considered new; default is 1 second

function diguyCharacter::get_aim_param_new_aim_duration

Prototype:
float get_aim_param_new_aim_duration();
Returns:

how long, in seconds, a new aim is considered new

function diguyCharacter::set_aim_param_max_per_frame_adj_factor

Prototype:
void set_aim_param_max_per_frame_adj_factor(float factor);
Description:

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.
Arguments:

factor unitless value between 0 and 1; default is 0.95

function diguyCharacter::get_aim_param_max_per_frame_adj_factor

Prototype:
float get_aim_param_max_per_frame_adj_factor();
Returns:

the maximum per-frame adjustment factor parameter

function diguyCharacter::set_aim_param_azimuth_acquired_range

Prototype:
void set_aim_param_azimuth_acquired_range(float range);
Description:

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.
Arguments:

range how close, in degrees, the azimuth must be for the aim to be acquired; default is 0.5 degrees

function diguyCharacter::get_aim_param_azimuth_acquired_range

Prototype:
float get_aim_param_azimuth_acquired_range();
Returns:

acquired

function diguyCharacter::set_aim_param_elevation_acquired_range

Prototype:
void set_aim_param_elevation_acquired_range(float range);
Description:

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.
Arguments:

range how close, in degrees, the elevation must be for the aim to be acquired; default is 1.0 degrees

function diguyCharacter::get_aim_param_elevation_acquired_range

Prototype:
float get_aim_param_elevation_acquired_range();
Returns:

acquired

function diguyCharacter::set_aim_converge_every_frame

Prototype:
void set_aim_converge_every_frame(int max_iterations = 30);
Description:

This function attempts to have the character reach its desired aim angles instantly, every frame. Because of the algorithm used, this can take a number of iterations to achieve.

The max_iterations argument sets a maximum limit this function will use to try to acquire the aim. Setting this value too high can reduce performance.

Set max_iterations to 0 to disable instant aim convergence.

For a one-time instant convergence, call aim_converge().
Arguments:

max_iterations maximum number of internal iterations to use to acquire aim

function diguyCharacter::get_aim_converge_every_frame

Prototype:
int get_aim_converge_every_frame();
Returns:

how many iterations will be used each frame for attempt at per-frame instant convergence; 0 if instant convergence is disabled

Weapon Functions

Unless otherwise specified, all functions callable from:

C++
Script

function diguyCharacter::fire_weapon

Prototype:
int fire_weapon(diguyMuzzle muzzle = DIGUY_MUZZLE_DEFAULT);
Description:

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::fire_weapon_n_times

Prototype:
int fire_weapon_n_times(int count,
    float dt = 0.2f,
    const char* override_sound_name = NULL,
    diguyMuzzle muzzle = DIGUY_MUZZLE_DEFAULT);
Description:

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()).
Arguments:

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::fire_screen_space_bullet

Prototype:
int fire_screen_space_bullet(diguyView* view, float x, float y);
Description:

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

function diguyCharacter::get_weapon_fire_count

Prototype:
int get_weapon_fire_count(diguyMuzzle muzzle = DIGUY_MUZZLE_DEFAULT);
Returns:

number of times weapon has been fired from specified muzzle
Callable From:

C++
Script
Decision Bead

function diguyCharacter::set_default_weapon_muzzle

Prototype:
int set_default_weapon_muzzle(diguyMuzzle muzzle);
Description:

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.
Arguments:

muzzle the muzzle that will flash; muzzle 1 is common
Returns:

0 on success, -1 on failure

function diguyCharacter::get_default_weapon_muzzle

Prototype:
diguyMuzzle get_default_weapon_muzzle();
Returns:

current default weapon muzzle that flashes when the character's weapon is fired; see set_default_weapon_muzzle()

function diguyCharacter::get_weapon_muzzle_munition_type

Prototype:
const char* get_weapon_muzzle_munition_type(diguyMuzzle muzzle);
Description:

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

function diguyCharacter::get_default_muzzle_munition_type

Prototype:
const char* get_default_muzzle_munition_type();
Returns:

munition type of default muzzle, as set by set_default_weapon_muzzle()

function diguyCharacter::set_weapon_munition_type_override

Prototype:
int set_weapon_munition_type_override(const char* munition_type);
Description:

This function allows the default munition type to be overridden. The default value is NULL (don't override default munition type).
Arguments:

munition_type name of a munition type
Returns:

0 on success, -1 on failure

function diguyCharacter::get_weapon_munition_type_override

Prototype:
const char* get_weapon_munition_type_override();
Returns:

current munition type override in effect, or NULL if none; set_weapon_munition_type_override()

function diguyCharacter::set_weapon_fires_live_rounds

Prototype:
int set_weapon_fires_live_rounds(int weapon_fires_live_rounds);
Description:

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.
Arguments:

weapon_fires_live_rounds set to 1 for live rounds; set to 0 for "blanks"
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision Bead

function diguyCharacter::get_weapon_fires_live_rounds

Prototype:
int get_weapon_fires_live_rounds();
Returns:

current setting of whether weapon fires live rounds or blanks; see set_weapon_fires_live_rounds()
Callable From:

C++
Script
Decision Bead

function diguyCharacter::set_weapon_sound_override

Prototype:
int set_weapon_sound_override(const char* sound_name);
Description:

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.
Arguments:

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

function diguyCharacter::get_weapon_sound_override

Prototype:
const char* get_weapon_sound_override();
Description:

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

function diguyCharacter::set_weapon_sound_gain_override

Prototype:
int set_weapon_sound_gain_override(float gain);
Description:

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().
Arguments:

sound_gain amount by which to change sound volume
Returns:

0 on success, -1 on failure

function diguyCharacter::get_weapon_sound_gain_override

Prototype:
float get_weapon_sound_gain_override();
Returns:

current override gain for weapon sound; see set_weapon_sound_gain_override()

function diguyCharacter::set_weapon_spread

Prototype:
void set_weapon_spread(float spread);
Description:

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.
Arguments:

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.

function diguyCharacter::set_weapon_near_range

Prototype:
void set_weapon_near_range(float near_range);
Description:

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.
Arguments:

near_range distance closer than which no character will be targeted

function diguyCharacter::set_weapon_far_range

Prototype:
void set_weapon_far_range(float far_range);
Description:

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.
Arguments:

far_range range of the weapon in meters

function diguyCharacter::set_weapon_hit_ratio

Prototype:
void set_weapon_hit_ratio(float hit_ratio);
Description:

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.

function diguyCharacter::set_weapon_max_impacts

Prototype:
void set_weapon_max_impacts(int val);
Description:

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.

function diguyCharacter::get_accessory1_state

Prototype:
int get_accessory1_state();
Returns:

state of accessory1

function diguyCharacter::get_rifle_state

Prototype:
int get_rifle_state();
Returns:

state of the character's rifle

function diguyCharacter::set_weapon_projectile_is_visible

Prototype:
int set_weapon_projectile_is_visible(diguyMuzzle muzzle, int is_visible);
Description

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.
Arguments:

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

function diguyCharacter::get_weapon_projectile_is_visible

Prototype:
int get_weapon_projectile_is_visible(diguyMuzzle muzzle);
Description

This function returns the most recent setting of set_weapon_projectile_is_visible().
Arguments:

muzzle which muzzle's projectile should be queried
Returns:

1 if visible, 0 if not

function diguyCharacter::get_weapon_aim_vector

Prototype:
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);
Description:

Retrieves the position and direction of the character's weapon.
Arguments:

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

function diguyCharacter::get_muzzle_link

Prototype:
const char* get_muzzle_link(diguyMuzzle muzzle = DIGUY_MUZZLE_DEFAULT);
Description

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.
Arguments:

muzzle muzzle of interest
Returns:

name of link, or NULL if the character doesn't have the specified muzzle

function diguyCharacter::get_muzzle_offset

Prototype:
int get_muzzle_offset(diguyMuzzle muzzle = DIGUY_MUZZLE_DEFAULT,
    float* offset_x = NULL,
    float* offset_y = NULL,
    float* offset_z = NULL);
Description

This function returns the offset of the muzzle from the link it is attached to as returned by get_muzzle_link().
Arguments:

muzzle muzzle of interest
offset_x, offset_y, offset_z variables in which to return results
Returns:

0 on success, -1 on failure

function diguyCharacter::set_weapon_max_azimuth_error

Prototype:
int set_weapon_max_azimuth_error(float h_error);
Description

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.
Arguments:

h_error highest possible horizontal error
Returns:

0 on success, -1 on failure

function diguyCharacter::get_weapon_max_azimuth_error

Prototype:
float get_weapon_max_azimuth_error();
Returns:

maximum horizontal aim error

function diguyCharacter::set_weapon_max_elevation_error

Prototype:
int set_weapon_max_elevation_error(float v_error);
Description

Similar to set_weapon_max_azimuth_error(), but for vertical aim.

function diguyCharacter::get_weapon_max_elevation_error

Prototype:
float get_weapon_max_elevation_error();
Description

Similar to get_weapon_max_azimuth_error(), but for vertical aim.

function diguyCharacter::set_weapon_tracers_enabled

Prototype:
int set_weapon_tracers_enabled(int enabled);
Description

This function sets whether tracer effects will be shown when the weapon is fired. Not all weapons will support this effect.
Arguments:

enabled pass 1 to enable, 0 to disable
Returns:

0 on success, -1 on failure

function diguyCharacter::get_weapon_tracers_enabled

Prototype:
int get_weapon_tracers_enabled();
Returns:

1 if tracer effect is enabled, 0 if not

function diguyCharacter::get_weapon_rounds_until_tracer

Prototype:
int get_weapon_rounds_until_tracer(diguyMuzzle muzzle);
Returns:

number of rounds until next tracer

function diguyCharacter::set_weapon_shell_eject_enabled

Prototype:
int set_weapon_shell_eject_enabled(int enabled);
Description

This function sets whether a shell eject effect will be shown when the weapon is fired. Not all weapons will support this effect.
Arguments:

enabled pass 1 to enable, 0 to disable
Returns:

0 on success, -1 on failure

function diguyCharacter::get_weapon_shell_eject_enabled

Prototype:
int get_weapon_shell_eject_enabled();
Returns:

1 if shell eject effect is enabled, 0 if not

function diguyCharacter::set_weapon_smoke_enabled

Prototype:
int set_weapon_smoke_enabled(int enabled);
Description

This function sets whether a smoke effect will be shown when the weapon is fired. Not all weapons will support this effect.
Arguments:

enabled pass 1 to enable, 0 to disable
Returns:

0 on success, -1 on failure

function diguyCharacter::get_weapon_smoke_enabled

Prototype:
int get_weapon_smoke_enabled();
Returns:

1 if muzzle smoke effect is enabled, 0 if not

function diguyCharacter::trigger_detonation_on_character

Prototype:
int trigger_detonation_on_character(const char* munition_name,
    const char* attacker_name = NULL,
    float radius_override = -1.0f,
    int broadcast_on_network = 1);
Description:

Similar to diguyScenario::trigger_detonation(), but detonation occurs at character's position.
Arguments:

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.

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.

function diguyCharacter::set_face_expression

Prototype:
int set_face_expression(const char* facex_name, float blend_duration, float strength = 1.0f);
Description:

This function changes the face of the character to reflect the specified user-defined named facial expression.

Currently affects only "facefx" appearances.
Arguments:

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
Callable From:

C++
Script
Decision Bead
C++ Example:
diguyCharacter* ch = scenario->get_character_at_index(0);

// take one second to get mad
ch->set_face_expression("Mad", 1.0);

function diguyCharacter::set_orientation_eyes

Prototype:
int set_orientation_eyes(float azimuth,
    float elevation,
    float blend_time = 0.0f);
Description:

This function sets the current azimuth and elevation of the character's eyes.

Currently affects only "facefx" appearances.
Arguments:

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

function diguyCharacter::get_orientation_eyes

Prototype:
int get_orientation_eyes(float* azimuth, float* elevation);
Description:

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.

function diguyCharacter::set_eye_droop

Prototype:
int set_eye_droop(float droop_amount, float blend_time = 0.0f);
Description:

Sets how open the eyes are. The eyes will stay at this level indefinitely. To get automatic blinking behavior, call blink().
Arguments:

droop_amount 1 = eyes closed, 0 = eyes open, 0.5 = half open
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision Bead

function diguyCharacter::get_eye_droop

Prototype:
float get_eye_droop();
Returns:

how open the eyes are as set by set_eye_droop().

function diguyCharacter::blink

Prototype:
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);
Description:

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.
Arguments:

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::set_automatic_blinks_enabled

Prototype:
int set_automatic_blinks_enabled(int enabled,
    float period = 6.0f,
    float period_variation = 3.0f);
Description:

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.
Arguments:

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::get_automatic_blinks_enabled

Prototype:
int get_automatic_blinks_enabled();
Returns:

1 if automatic eye blinks are enabled, 0 if not; see set_automatic_blinks_enabled()

function diguyCharacter::set_automatic_blink_duration_in

Prototype:
void set_automatic_blink_duration_in(float duration_in);
Description:

This function sets how long it will take the eye to close during automatic eye blinks. See set_automatic_blinks_enabled() and blink().
Arguments:

duration_in time in seconds for eye droop to go from droop target in to target out
Callable From:

C++
Script
Decision Bead

function diguyCharacter::get_automatic_blink_duration_in

Prototype:
float get_automatic_blink_duration_in();
Returns:

most recent setting of set_automatic_blink_duration_in()

function diguyCharacter::set_automatic_blink_duration_out

Prototype:
void set_automatic_blink_duration_out(float duration_out);
Description:

This function sets how long it will take the eye to open during automatic eye blinks. See set_automatic_blinks_enabled() and blink().
Arguments:

duration_out time in seconds for eye droop to go from droop target out to target in
Callable From:

C++
Script
Decision Bead

function diguyCharacter::get_automatic_blink_duration_out

Prototype:
float get_automatic_blink_duration_out();
Returns:

most recent setting of set_automatic_blink_duration_out()

function diguyCharacter::set_automatic_blink_target_in

Prototype:
void set_automatic_blink_target_in(float target_in);
Description:

This function sets how much the eye will close during automatic eye blinks. See set_automatic_blinks_enabled() and blink().
Arguments:

target_in how far to close eye; 1.0 is all closed, 0.0 is all open
Callable From:

C++
Script
Decision Bead

function diguyCharacter::get_automatic_blink_target_in

Prototype:
float get_automatic_blink_target_in();
Returns:

most recent setting of set_automatic_blink_target_in()

function diguyCharacter::set_automatic_blink_target_out

Prototype:
void set_automatic_blink_target_out(float target_out);
Description:

This function sets how much the eye will open during automatic eye blinks. See set_automatic_blinks_enabled() and blink().
Arguments:

target_out how far to open eye; 1.0 is all closed, 0.0 is all open
Callable From:

C++
Script
Decision Bead

function diguyCharacter::get_automatic_blink_target_out

Prototype:
float get_automatic_blink_target_out();
Returns:

most recent setting of set_automatic_blink_target_out()

function diguyCharacter::is_speaking

Prototype:
int 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

function diguyCharacter::set_current_facefx_animation_group

Prototype:
int set_current_facefx_animation_group(const char* anim_group);
Description:

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.

function diguyCharacter::get_current_facefx_animation_group

Prototype:
const char* get_current_facefx_animation_group();
Returns:

the current FaceFX animation group set for this character

function diguyCharacter::get_facefx_actor

Prototype:
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

function diguyCharacter::facefx_mount_animset

Prototype:
int facefx_mount_animset(const char* file_name);
Description:

Mounts an animset on the current FaceFX actor. See also diguyScenario::facefx_mount_animset()

function diguyCharacter::play_facefx_animation

Prototype:
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);
Description:

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

function diguyCharacter::stop_facefx_animations

Prototype:
int stop_facefx_animations(float blend_time = 0.25f, int stop_sounds = 1);
Description:

Stops all active FaceFX animation.

function diguyCharacter::get_num_facefx_nodes

Prototype:
int get_num_facefx_nodes();
Returns:

the number of nodes in the FaceFX actor's face graph

function diguyCharacter::get_facefx_node_name

Prototype:
const char* get_facefx_node_name(int index);
Returns:

the name of the node with index 'index' in the FaceFX actor's face graph

function diguyCharacter::find_facefx_node_index

Prototype:
int find_facefx_node_index(const char* node_name);
Returns:

the index of the node with name 'node_name'

function diguyCharacter::set_facefx_node_value

Prototype:
int set_facefx_node_value(int node_index,
    float value,
    float blend_time = 0.25f);
Description:

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.

function diguyCharacter::get_facefx_node_value

Prototype:
float get_facefx_node_value(int node_index);
Description:

Retreives the current final value of a node

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.

Gesture Stages

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.

Gesture Channels

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

function diguyCharacter::create_gesture

Prototype:
diguyCharacterGesture* create_gesture(const char* gesture_name);
Description:

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.
Arguments:

gesture_name name of the gesture of create
Returns:

pointer to object of type diguyCharacterGesture

function diguyCharacter::destroy_gesture

Prototype:
int destroy_gesture(diguyCharacterGesture* gesture);
Description:

This function destroys a gesture object created by create_gesture().
Arguments:

gesture gesture to destroy
Returns:

0 on success, -1 on failure

function diguyCharacter::execute_gesture

Prototype:
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);
Description:

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()).
Arguments:

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::execute_1stage_gesture

Prototype:
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);
Description:

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()).
Arguments:

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

function diguyCharacter::execute_2stage_gesture

Prototype:
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);
Description:

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()).
Arguments:

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

function diguyCharacter::execute_3stage_gesture

Prototype:
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);
Description:

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()).
Arguments:

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

function diguyCharacter::execute_table_gesture

Prototype:
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);
Description:

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()).
Arguments:

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

function diguyCharacter::set_executing_table_gesture_desired_action

Prototype:

int set_executing_table_gesture_desired_action(const char* gesture_name,
    const char* desired_action);

Description:

Documentation Pending

function diguyCharacter::end_executing_gesture

Prototype:
int end_executing_gesture(const char* gesture_name);
Description:

This function alerts all 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.
Arguments:

gesture_name name of executing gesture to end
Returns:

0 on success, -1 on failure
See Also:

abort_executing_gesture()

function diguyCharacter::abort_executing_gesture

Prototype:
int abort_executing_gesture(const char* gesture_name,
    float max_rampdown_interval);
Description:

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.
Arguments:

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

function diguyCharacter::end_all_gestures

Prototype:
int end_all_gestures();
Description:

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

function diguyCharacter::abort_all_gestures

Prototype:
int abort_all_gestures(float max_rampdown_interval);
Description:

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.
Arguments:

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

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

function diguyCharacter::play_sound

Prototype:
int play_sound(const char* sound_name,
    float sound_gain = 1.0f,
    int sound_loops = 0);
Description:

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

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::play_3d_sound

Prototype:
int play_3d_sound(const char* sound_name,
    float sound_gain = 1.0f,
    int sound_loops = 0);
Description:

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

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::create_sound_instance

Prototype:
diguySoundInstance* create_sound_instance(const char* sound_name);
Description:

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.
Arguments:

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

function diguyCharacter::destroy_sound_instance

Prototype:
int destroy_sound_instance(diguySoundInstance* sound_instance);
Description:

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.
Arguments:

sound_instance sound instance to destroy
Returns:

0 on success, -1 on failure

function diguyCharacter::stop_all_sounds

Prototype:
int stop_all_sounds(float rampdown_time = 0.0f);
Description:

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.
Arguments:

rampdown_time how long to fade out the sound
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision Bead

function diguyCharacter::stop_sound

Prototype:
int stop_sound(const char* sound_name, float rampdown_time = 0.0f);
Description:

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.
Arguments:

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::is_playing_sound

Prototype:
int is_playing_sound(const char* sound_name);
Returns:

1 if the character is playing a the sound specified, 0 if not

function diguyCharacter::set_current_voice_actor

Prototype:
int set_current_voice_actor(const char* voice_actor);
Description:

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"
Arguments:

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

function diguyCharacter::get_current_voice_actor

Prototype:
const char* get_current_voice_actor();
Returns:

name of current voice actor, as set by set_current_voice_actor()

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

function diguyCharacter::get_DIS_lifeform_state

Prototype:
int get_DIS_lifeform_state();
Description:

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:
Callable For Networked Entities That Are:

DIS published and reflected

function diguyCharacter::get_DIS_primary_weapon_position

Prototype:
int get_DIS_primary_weapon_position();
Description:

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:
Callable For Networked Entities That Are:

DIS published

function diguyCharacter::get_DIS_secondary_weapon_position

Prototype:
int get_DIS_secondary_weapon_position();
Description:

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:
Callable For Networked Entities That Are:

DIS published

function diguyCharacter::set_network_marking

Prototype:
int set_network_marking(const char* network_marking);
Description:

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

function diguyCharacter::get_network_marking

Prototype:
const char* get_network_marking();
Description:

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

function diguyCharacter::set_is_network_published

Prototype:
int set_is_network_published(int is_network_published);
Description:

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

function diguyCharacter::get_is_network_published

Prototype:
int get_is_network_published();
Description:

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
Callable From:

C++
Script
Decision
Callable For Networked Entities That Are:

DIS published and reflected
HLA published and reflected

function diguyCharacter::get_is_network_reflected

Prototype:
int get_is_network_reflected();
Description:

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
Callable From:

C++
Script
Decision
Callable For Networked Entities That Are:

DIS published and reflected
HLA published and reflected

function diguyCharacter::get_is_network_paused

Prototype:
int get_is_network_paused();
Description:

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
Callable From:

C++
Script
Decision

function diguyCharacter::get_network_entity_number

Prototype:
int get_network_entity_number();
Description:

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

function diguyCharacter::get_action_from_entity_state

Prototype:
const char* get_action_from_entity_state(int damage_state,
    int life_form_state,
    int primary_weapon_state,
    float speed,
    int forward);
Description:

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.
Arguments:

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

Valid values for life_form_state (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)

Valid values for primary_weapon_state (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)

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

function diguyCharacter::set_DIS_damage_state

Prototype:
void set_DIS_damage_state(int state);
Description:

Sets the damage state for the network published character. It's still up to the end user to change the appearance based on this information.
Arguments:

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

function diguyCharacter::get_DIS_damage_state

Prototype:
int get_DIS_damage_state();
Description:

Returns the damage state of a network published character. Note that it's still up to the end user to change the character appearance based on this information.

one of the values shown in set_DIS_damage_state()

function diguyCharacter::set_DIS_smoke_state

Prototype:
void set_DIS_smoke_state(int state);
Description:

Sets the smoke state for a network published character. Starts or stops the "smoke" and "engine_smoke" appearance effects as appropriate.
Arguments:

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

function diguyCharacter::get_DIS_smoke_state

Prototype:
int get_DIS_smoke_state();
Description:

Returns the smoke state of a network published character.

one of the values shown in set_DIS_smoke_state()

function diguyCharacter::set_DIS_flames_state

Prototype:
void set_DIS_flames_state(int state);
Description:

Sets the flames state for a network published character. Starts or stops the "flames" appearance effect as appropriate.
Arguments:

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

function diguyCharacter::get_DIS_flames_state

Prototype:
int get_DIS_flames_state();
Description:

Returns the flames state of a network published character.

one of the values shown in set_DIS_flames_state()

function diguyCharacter::set_DIS_power_plant_state

Prototype:
void set_DIS_power_plant_state(int state);
Description:

Sets the power plant state for a network published character. Vehicle power plants default to being on.
Arguments:

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

function diguyCharacter::get_DIS_power_plant_state

Prototype:
int get_DIS_power_plant_state();
Description:

Returns the power plant state of a network published character.

one of the values shown in set_DIS_power_plant_state()

function diguyCharacter::set_DIS_trailing_effect_state

Prototype:
void set_DIS_trailing_effect_state(int state);
Description:

Sets the trailing effect state for a network published character.
Arguments:

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

function diguyCharacter::get_DIS_trailing_effect_state

Prototype:
int get_DIS_trailing_effect_state();
Description:

Returns the trailing effect state of a network published character.

one of the values shown in set_DIS_smoke_trail_state()

Formation Functions

Unless otherwise specified, all functions callable from:

C++
Script

function diguyCharacter::call_formation

Prototype:
int call_formation(const char* formation_name,
    int snap_to_position_flag = 0,
    int break_existing_formations_flag = 1);
Description:

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().
Arguments:

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
Callable From:

C++
Script
Decision Bead

function diguyCharacter::break_formation

Prototype:
int break_formation(const char* formation_name = NULL);
Description:

This function breaks up a formation initiated by call_formation().
Arguments:

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
Callable From:

C++
Script
Decision Bead

Guide Functions

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

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

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

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

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

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

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

Unless otherwise specified, all functions callable from:

C++
Script

Guide Algorithms

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

Exact
Overview:

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

It can be used with or without a formation.
Effects on Action:

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

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

If the character is not in a formation, the action of the character is not affected.
Effects on Position and Orientation:

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

Parameters:

(none)

Follow1
Overview:

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

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

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

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

If the character is outside distance_zone_1 the character will scale its speed by up to max_speed_scale.
Effects on Position:

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

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

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

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

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

Follow2
Overview:

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

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

If following a formation leader:

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

If not in a formation:

In distance_zone_0: Character will stop using its default still action.
In distance_zone_1: Character will use an appropriate moving action.
Beyond distance_zone_1: Character will select a fast moving action, or speed up a slower action.
Effects on Position:

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

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

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

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

Drift1
Overview:

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

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

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

If the character is not in a formation, the action of the character is not affected.
Effects on Position:

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

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

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

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

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

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

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

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

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

function diguyCharacter::add_guide

Prototype:
diguyCharacterGuide* add_guide(const char* guide_name,
    int automatically_disable_when_acquired = 0);
Description:

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().
Arguments:

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

function diguyCharacter::create_guide

Prototype:
diguyCharacterGuide* create_guide(const char* guide_name,
    const char* guide_algorithm,
    int automatically_disable_when_acquired = 0);
Description:

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
Arguments:

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

function diguyCharacter::find_or_create_guide

Prototype:
diguyCharacterGuide* find_or_create_guide(const char* guide_name,
    const char* guide_algorithm,
    int automatically_disable_when_acquired = 0);
Description:

Like create_guide(), but returns guide if it already exists
Arguments:

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

function diguyCharacter::find_guide

Prototype:
diguyCharacterGuide* find_guide(const char* guide_name);
Description:

This function returns a pointer to the specified guide of the character, if is exists.
Arguments:

guide_name name of guide to find
Returns:

object of type diguyCharacterGuide; if a guide with guide_name is not found, returns NULL

function diguyCharacter::remove_guide_with_name

Prototype:
int remove_guide_with_name(const char* guide_name);
Description:

This function removes the specified guide from the character.
Arguments:

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

function diguyCharacter::remove_guide

Prototype:
int remove_guide(diguyCharacterGuide* guide);
Description:

This function removes the specified guide from the character.
Arguments:

guide object returned by add_guide() call
Returns:

0 on success, -1 on failure

function diguyCharacter::remove_all_guides

Prototype:
int remove_all_guides();
Description:

This function removes all guides from the character.
Returns:

0 on success, -1 on failure

function diguyCharacter::remove_all_disabled_guides

Prototype:
int remove_all_disabled_guides();
Description:

This function removes all guides that are disabled.
Returns:

0 on success, -1 on failure

Motion Texture Functions

Unless otherwise specified, all functions callable from:

C++
Script

function diguyCharacter::add_motion_texture

Prototype:
int add_motion_texture(const char* motex_name = "default",
    float texture_gain = 1.0f,
    int end_previous_motex = 1,
    float rampup_interval = 0.2f);
Description:

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()).
Arguments:

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

function diguyCharacter::end_motion_texture

Prototype:
int end_motion_texture(float rampdown_interval = 0.2f);
Description:

This function gradually ends any active motion textures added by add_motion_texture().
Arguments:

rampdown_interval how long, in seconds, to take ending the motion texture
Returns:

0 on success, -1 on failure

function diguyCharacter::set_initial_motion_texture

Prototype:
int set_initial_motion_texture(const char* motex_name);
Description:

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

motex_name name of the motion texture
Returns:

0 on success, -1 on failure

function diguyCharacter::get_initial_motion_texture

Prototype:
const char* get_initial_motion_texture();
Description:

This function returns the initial motion texture as set by a call to set_initial_motion_texture().
Returns:

name of initial motion texture

function diguyCharacter::set_initial_motion_texture_gain

Prototype:
int set_initial_motion_texture_gain(float motex_gain);
Description:

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().
Arguments:

motex_gain gain of the motion texture; higher gains result in more pronounced motion
Returns:

0 on success, -1 on failure

function diguyCharacter::get_initial_motion_texture_gain

Prototype:
float get_initial_motion_texture_gain();
Description:

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

History Functions

Unless otherwise specified, all functions callable from:

C++
Script

function diguyCharacter::set_history_type

Prototype:
int set_history_type(diguyHistoryType history_type);
Description:

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.
Arguments:

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

function diguyCharacter::get_history_type

Prototype:
diguyHistoryType get_history_type();
Returns:

the current history type of the character; see set_history_type()

function diguyCharacter::set_history_size_t

Prototype:
int set_history_size_t(float t);
Description:

This function sets the size of the character's history buffer, in seconds.
Arguments:

t length of history buffer, in seconds
Returns:

0 on success, -1 on failure

function diguyCharacter::get_history_size_t

Prototype:
float get_history_size_t();
Description:

This function returns the current history buffer size. See set_history_size_t().
Returns:

current history size

function diguyCharacter::set_history_size_increment_t

Prototype:
int set_history_size_increment_t(float t);
Description:

This function sets the size of the character's history buffer increment, in seconds.
Arguments:

t length of history buffer increment, in seconds
Returns:

0 on success, -1 on failure

function diguyCharacter::get_history_size_increment_t

Prototype:
float get_history_size_increment_t();
Description:

This function returns the current history buffer size increment. See set_history_size_increment_t().
Returns:

current history size increment

Meta-Action Functions

Unless otherwise specified, all functions callable from:

C++
Script

function diguyCharacter::set_desired_posture

Prototype:
void set_desired_posture(diguyMotionPosture desired_posture);
Description:

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.
Arguments:

posture new desired posture

function diguyCharacter::get_desired_posture

Prototype:
diguyMotionPosture get_desired_posture();
Returns:

current desired posture of the character

function diguyCharacter::set_desired_variant

Prototype:
void set_desired_variant(diguyMotionVariant desired_variant);
Description:

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.
Arguments:

variant new desired variant

function diguyCharacter::get_desired_variant

Prototype:
diguyMotionVariant get_desired_variant();
Returns:

current desired variant of the character

function diguyCharacter::get_action_from_description

Prototype:
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);
Description:

This function looks up the character action that most closely matches the given criteria.
Arguments:

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

function diguyCharacter::get_turning_action_from_description

Prototype:
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);
Description:

This function is very similar to get_action_from_description(), but substitutes turn amount per action iteration for speed.
Arguments:

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

Variable Functions

Unless otherwise specified, all functions callable from:

C++
Script

function diguyCharacter::get_num_variables

Prototype:
int    get_num_variables();
Returns:

number of variables the character has

function diguyCharacter::get_variable_at_index

Prototype:
diguyVariable* get_variable_at_index(int index);
Returns:

pointer of type diguyVariable; NULL if no variable at the specified index
Arguments:

index index of the variable; indices start at 0

function diguyCharacter::find_variable

Prototype:
diguyVariable* find_variable(const char* name);
Description:

This function returns a pointer to the specified variable.
Arguments:

name name of variable to be found
Returns:

pointer of type diguyVariable; NULL if not found

function diguyCharacter::find_or_create_variable

Prototype:
diguyVariable* find_or_create_variable(const char* name);
Description:

This function finds the variable with the given name or creates it if it doesn't exist.
Arguments:

name name of the variable to find or create
Returns:

pointer of type diguyVariable; should never be NULL

function diguyCharacter::destroy_variable

Prototype:
int destroy_variable(diguyVariable* variable);
Description:

This function destroys the passed variable.
Arguments:

variable pointer to a diguyVariable
Returns:

0 on success, -1 on failure

function diguyCharacter::variable_equal_to_int

Prototype:
int variable_equal_to_int(const char* varname, int value);
Returns:

1 if variable is equal to passed value, 0 if not
Arguments:

varname name of variable to compare
value value to compare against
Callable From:

C++
Script
Decision

function diguyCharacter::variable_greater_than_int

Prototype:
int variable_greater_than_int(const char* varname, int value);
Returns:

1 if variable is greater than passed value, 0 if not
Arguments:

varname name of variable to compare
value value to compare against
Callable From:

C++
Script
Decision

function diguyCharacter::variable_less_than_int

Prototype:
int variable_less_than_int(const char* varname, int value);
Returns:

1 if variable is less than passed value, 0 if not
Arguments:

varname name of variable to compare
value value to compare against
Callable From:

C++
Script
Decision

function diguyCharacter::variable_equal_to_float

Prototype:
int variable_equal_to_float(const char* varname, float value);
Returns:

1 if variable is equal to passed value, 0 if not
Arguments:

varname name of variable to compare
value value to compare against
Callable From:

C++
Script
Decision

function diguyCharacter::variable_greater_than_float

Prototype:
int variable_greater_than_float(const char* varname, float value);
Returns:

1 if variable is greater than passed value, 0 if not
Arguments:

varname name of variable to compare
value value to compare against
Callable From:

C++
Script
Decision

function diguyCharacter::variable_less_than_float

Prototype:
int variable_less_than_float(const char* varname, float value);
Returns:

1 if variable is less than passed value, 0 if not
Arguments:

varname name of variable to compare
value value to compare against
Callable From:

C++
Script
Decision

function diguyCharacter::variable_equal_to_string

Prototype:
int variable_equal_to_string(const char* varname, const char* value);
Returns:

1 if variable is equal than passed value, 0 if not
Arguments:

varname name of variable to compare
value value to compare against
Callable From:

C++
Script
Decision

function diguyCharacter::variable_greater_than_string

Prototype:
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
Arguments:

varname name of variable to compare
value value to compare against
Callable From:

C++
Script
Decision

function diguyCharacter::variable_less_than_string

Prototype:
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
Arguments:

varname name of variable to compare
value value to compare against
Callable From:

C++
Script
Decision

function diguyCharacter::variable_decrement_value_as_int

Prototype:
int variable_decrement_value_as_int(const char* varname, int value = 1);
Description:

This function decrements the variable by the passed amount.
Arguments:

varname name of variable to modify
value amount to decrement
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision

function diguyCharacter::variable_increment_value_as_int

Prototype:
int variable_increment_value_as_int(const char* varname, int value = 1);
Description:

This function increments the variable by the passed amount.
Arguments:

varname name of variable to modify
value amount to increment
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision

function diguyCharacter::variable_set_value_as_int

Prototype:
int variable_set_value_as_int(const char* varname,
    int value,
    int create_if_doesnt_exist = 1);
Description:

This function is a convenience function for setting the variable to a new integer value without retrieving the diguyVariable object.
Arguments:

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
Callable From:

C++
Script
Decision

function diguyCharacter::set_ivar

Prototype:
int set_ivar(const char* varname,
    int value,
    int create_if_doesnt_exist = 1);
Description:

Short form of variable_set_value_as_int().

function diguyCharacter::get_ivar

Prototype:
int get_ivar(const char* varname,
    int create_if_doesnt_exist = 1);
Description:

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.
Arguments:

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

function diguyCharacter::variable_set_value_as_float

Prototype:
int variable_set_value_as_float(const char* varname,
    float value,
    int create_if_doesnt_exist = 1);
Description:

Similar to variable_set_value_as_int(), for sets a floating point value instead.

function diguyCharacter::set_fvar

Prototype:
int set_fvar(const char* varname,
    float value,
    int create_if_doesnt_exist = 1);
Description:

Short form of variable_set_value_as_float().

function diguyCharacter::get_fvar

Prototype:
float get_fvar(const char* varname,
    int create_if_doesnt_exist = 1);
Description:

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.

function diguyCharacter::variable_set_value_as_string

Prototype:
int variable_set_value_as_string(const char* varname,
    const char* value,
    int create_if_doesnt_exist = 1);
Description:

Similar to variable_set_value_as_int(), for sets a string value instead.

function diguyCharacter::set_svar

Prototype:
int set_svar(const char* varname,
    const char* value,
    int create_if_doesnt_exist = 1);
Description:

Short form of variable_set_value_as_string().

function diguyCharacter::get_svar

Prototype:
const char* get_svar(const char* varname,
    int create_if_doesnt_exist = 1);
Description:

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

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

function diguyCharacter::get_name_label

Prototype:
diguyViewLabel* get_name_label();
Description:

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

function diguyCharacter::set_label_text

Prototype:
int set_label_text(const char* label_text);
Description:

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.
Arguments:

label_text new text for the label
Returns:

0 on success, -1 on failure

function diguyCharacter::get_label_text

Prototype:
const char* get_label_text();
Description:

This function returns the character's label text. See set_label_text().
Returns:

current label text; the returned pointer will never be NULL

function diguyCharacter::set_label_is_visible

Prototype:
int set_label_is_visible(int is_visible);
Description:

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.
Arguments:

is_visible pass 1 to show, pass 0 to hide
Returns:

0 on success, -1 on failure

function diguyCharacter::get_label_is_visible

Prototype:
int get_label_is_visible();
Description:

This function returns the most recent setting of set_label_is_visible().
Returns:

1 if visible, 0 if not

function diguyCharacter::set_label_text_color

Prototype:
int set_label_text_color(float r, float g, float b, float a);
Description:

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.
Arguments:

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

function diguyCharacter::set_label_text_color_vec4

Prototype:
int set_label_text_color_vec4(diguyVec4f color);
Description:

Alternate version of set_label_text_color().

function diguyCharacter::get_label_text_color

Prototype:
int get_label_text_color(float* r, float* g, float* b, float* a);
Description:

This function returns, in the passed variable pointers, the most recent setting of set_label_text_color().
Returns:

0 on success, -1 on failure

function diguyCharacter::get_label_text_color_vec4

Prototype:
diguyVec4f get_label_text_color_vec4();
Description:

Alternate version of get_label_text_color().

function diguyCharacter::set_label_text_shadow_color

Prototype:
int set_label_text_shadow_color(float r, float g, float b, float a);
Description:

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.
Arguments:

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

function diguyCharacter::set_label_text_shadow_color_vec4

Prototype:
int set_label_text_shadow_color_vec4(diguyVec4f color);
Description:

Alternate version of set_label_text_shadow_color().

function diguyCharacter::get_label_text_shadow_color

Prototype:
int get_label_text_shadow_color(float* r, float* g, float* b, float* a);
Description:

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

function diguyCharacter::get_label_text_shadow_color_vec4

Prototype:
diguyVec4f get_label_text_shadow_color_vec4();
Description:

Alternate version of get_label_text_shadow_color().

function diguyCharacter::set_label_text_shadow_is_visible

Prototype:
int set_label_text_shadow_is_visible(int is_visible);
Description:

This function sets the whether the text shadow is visible.
Arguments:

visible pass 1 to make shadow visible, 0 to make it invisible
Returns:

0 on success, -1 on failure

function diguyCharacter::get_label_text_shadow_is_visible

Prototype:
int get_label_text_shadow_is_visible();
Returns:

1 if text shadow is visible, 0 if not

function diguyCharacter::set_label_background_color

Prototype:
int set_label_background_color(float r, float g, float b, float a);
Description:

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.
Arguments:

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

function diguyCharacter::set_label_background_color_vec4

Prototype:
int set_label_background_color_vec4(diguyVec4f color);
Description:

Alternate version of set_label_background_color().

function diguyCharacter::get_label_background_color

Prototype:
int get_label_background_color(float* r, float* g, float* b, float* a);
Description:

This function returns, in the passed variable pointers, the most recent setting of set_label_background_color().
Returns:

0 on success, -1 on failure

function diguyCharacter::get_label_background_color_vec4

Prototype:
diguyVec4f get_label_background_color_vec4();
Description:

Alternate version of get_label_background_color().

function diguyCharacter::set_label_link_offset_override

Prototype:
void set_label_link_offset_override(float offset);
Description:

This function sets how high the label of the character will float above the character.
Arguments:

offset offset, in meters, of label above character

function diguyCharacter::get_label_link_offset_override

Prototype:
float get_label_link_offset_override();
Returns:

how high the label of the character will float above the character

function diguyCharacter::set_label_shows_character_state

Prototype:
int set_label_shows_character_state(int show_state);
Description:

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.
Arguments:

show_state pass 1 to show state, 0 to show original text

function diguyCharacter::get_label_shows_character_state

Prototype:
int get_label_shows_character_state();
Returns:

whether character state information is shown instead of the character's name or other label text

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

function diguyCharacter::get_last_impact_record

Prototype:
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

function diguyCharacter::get_last_impact_number

Prototype:
int get_last_impact_number();
Returns:

the last impact number

function diguyCharacter::get_last_impact_been_processed

Prototype:
int get_last_impact_been_processed();
Returns:

the processed flag on the diguyImpact class

function diguyCharacter::set_last_impact_been_processed

Prototype:
void set_last_impact_been_processed();
Description:

Sets the processed flag on the diguyImpact object.

function diguyCharacter::set_max_unprocessed_impacts

Prototype:
void set_max_unprocessed_impacts(int max_unprocessed_impacts);
Description:

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.

function diguyCharacter::get_max_unprocessed_impacts

Prototype:
int get_max_unprocessed_impacts();
Returns:

maximum number of unprocessed impacts

function diguyCharacter::get_last_impact_link

Prototype:
const char* get_last_impact_link();
Returns:

the last impact link

function diguyCharacter::get_last_impact_link_is

Prototype:
int get_last_impact_link_is(const char* link_name);
Returns:

1 if the last impact link is the link named

function diguyCharacter::get_last_impact_is_from_vehicle

Prototype:
int get_last_impact_is_from_vehicle();
Returns:

1 if the last impact resulted from an impact with a vehicle, 0 if not

function diguyCharacter::get_last_impact_speed_is_greater_than

Prototype:
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

function diguyCharacter::set_is_immune_to_impacts

Prototype:
void set_is_immune_to_impacts(int immune);
Description:

Sets if impacts are ever processed on this character. Useful for temporary effects and the like.

function diguyCharacter::get_is_immune_to_impacts

Prototype:
int get_is_immune_to_impacts();
Returns:

1 if the character is immune to impacts 0 if not

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

function diguyCharacter::begin_appearance_effect

Prototype:
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);
Description:

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"
Arguments:

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
Callable From:

C++
Script
Decision

function diguyCharacter::end_appearance_effect

Prototype:
int end_appearance_effect(const char* effect,
    const char* override_link = NULL);
Description:

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.
Arguments:

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
Callable From:

C++
Script
Decision

function diguyCharacter::stop_appearance_effect

Prototype:
int stop_appearance_effect(const char* effect,
    const char* override_link = NULL);
Description:

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.
Arguments:

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
Callable From:

C++
Script
Decision

function diguyCharacter::stop_all_appearance_effects

Prototype:
int stop_all_appearance_effects();
Description:

Equivalent to stop_appearance_effect("all");

function diguyCharacter::appearance_effect_is_active

Prototype:
int appearance_effect_is_active(const char* effect,
    const char* override_link = NULL);
Description:

This function checks to see if the specified appearance effect has been started with begin_appearance_effect().
Arguments:

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

Chain Functions

These functions are for characters with character type "chain_simulation".

Unless otherwise specified, all functions callable from:

C++
Script

function diguyCharacter::get_chain_simulation

Prototype:
diguyChainSimulation* get_chain_simulation();
Description:

This function returns a pointer to a diguyChainSimulation if the character is a chain_simulation type of character.
Returns:

pointer to a diguyChainSimulation

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

function diguyCharacter::get_vehicle_controller

Prototype:
diguyVehicleController* get_vehicle_controller();
Description:

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

function diguyCharacter::get_vehicle_body_orientation

Prototype:
int get_vehicle_body_orientation(float* rz, float* rx, float* ry);
Description:

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

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

function diguyCharacter::set_render_mode_shader

Prototype:
int set_render_mode_shader(const char* shader_name,
    const char* render_mode = NULL);
Description:

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().
Arguments:

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

function diguyCharacter::reset_render_mode_shader_to_default

Prototype:
void reset_render_mode_shader_to_default(const char* render_mode = NULL);
Description:

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().
Arguments:

render_mode render mode to modify; passing NULL will modify shader of "normal" render mode

function diguyCharacter::get_render_mode_shader

Prototype:
const char* get_render_mode_shader(const char* render_mode = NULL);
Description:

This function returns the name of the shader that will be used by the character when the scenario is using the specified render mode.
Arguments:

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

function diguyCharacter::get_shader_program

Prototype:
diguyGraphicsShaderProgram* get_shader_program();
Description:

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

function diguyCharacter::set_temporary_current_shader

Prototype:
int set_temporary_current_shader(const char* shader_name);
Description:

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
Arguments:

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

function diguyCharacter::reset_current_shader_to_default

Prototype:
void reset_current_shader_to_default();
Description:

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.

function diguyCharacter::trigger_shader_refresh

Prototype:
void trigger_shader_refresh();
Description:

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.

function diguyCharacter::get_shader_instance

Prototype:
diguyGraphicsShaderInstance* get_shader_instance();
Description:

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

function diguyCharacter::reset_shader_instance_variables_to_initial_values

Prototype:
void reset_shader_instance_variables_to_initial_values();
Description:

This function resets current values of the variables of the shader back to their initial reset values.

function diguyCharacter::reset_shader_instance_variables_to_program_defaults

Prototype:
void reset_shader_instance_variables_to_program_defaults();
Description:

This function resets the current and initial values of variables of the shader to the built-in DI-Guy configuration defaults.

DI-Guy AI and Agent Functions

The following functions are for characters that are controlled by DI-Guy AI. AI-controlled characters are referred to as agents.

Almost all functions in this section require that the agent character be part of a crowd.

A DI-Guy AI license must be present for these functions to work.

Unless otherwise specified, all functions callable from:

C++
Script

Attack Functions

function diguyCharacter::agent_attack_character

Prototype:
int agent_attack_character(const char* character_name);
Description:

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.
Arguments:

character_name character to attack
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision

function diguyCharacter::agent_attack_group

Prototype:
int agent_attack_group(const char* group_name);
Description:

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.
Arguments:

group_name name of group from which attack targets should be chosen
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision

function diguyCharacter::agent_set_attack_zone_enabled

Prototype:
int agent_set_attack_zone_enabled(int use_attack_zone);
Description:

See diguyAgentParams::set_attack_zone_enabled().

function diguyCharacter::agent_get_attack_zone_enabled

Prototype:
int agent_get_attack_zone_enabled();
Description:

See diguyAgentParams::get_attack_zone_enabled().

function diguyCharacter::agent_set_attack_zone

Prototype:
int agent_set_attack_zone(float x, float y, float z, float radius);
Description:

See diguyAgentParams::set_attack_zone().

function diguyCharacter::agent_get_attack_zone

Prototype:
int agent_get_attack_zone(float* x, float* y, float* z, float* radius);
Description:

See diguyAgentParams::get_attack_zone().

Flee Functions

function diguyCharacter::agent_flee_character

Prototype:
int agent_flee_character(const char* character_name,
    float distance,
    int danger_level = 50);
Description:

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.
Arguments:

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
Callable From:

C++
Script
Decision

function diguyCharacter::agent_flee_group

Prototype:
int agent_flee_group(const char* group_name,
    float distance,
    int danger_level = 50);
Description:

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.
Arguments:

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
Callable From:

C++
Script
Decision

function diguyCharacter::agent_flee_crowd

Prototype:
int agent_flee_crowd(const char* crowd_name,
    float distance,
    int danger_level = 50);
Description:

This function is similar to agent_flee_group(), but the agent will instead flee the members of the specified crowd.

function diguyCharacter::agent_flee_location

Prototype:
int agent_flee_location(float x, float y, float z,
    float distance,
    int danger_level = 50);
Description:

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.
Arguments:

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

function diguyCharacter::agent_remove_all_flee_objects

Prototype:
void agent_remove_all_flee_objects();
Description:

This function removes all flee objects.

This function has no effect on current behavior.
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision

Mingle Functions

Unless otherwise specified, all functions callable from:

C++
Script

function diguyCharacter::agent_mingle_in_region

Prototype:
int agent_mingle_in_region(const char* region_name = "(current)",
    const char* subregion_name = "base");
Description:

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.
Arguments:

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
Callable From:

C++
Script
Decision

Wander Functions

Unless otherwise specified, all functions callable from:

C++
Script

function diguyCharacter::agent_wander_region

Prototype:
int agent_wander_region(const char* region_name = "(current)",
    const char* subregion_name = "base");
Description:

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
Callable From:

C++
Script
Decision

Pursue Functions

Unless otherwise specified, all functions callable from:

C++
Script

function diguyCharacter::agent_pursue_character

Prototype:
int agent_pursue_character(const char* character_name);
Description:

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.
Arguments:

character_name character to pursue
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision

function diguyCharacter::agent_pursue_character_with_offset

Prototype:
int agent_pursue_character_with_offset(const char* character_name,
    float offset_x,
    float offset_y);
Description:

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.

function diguyCharacter::agent_pursue_group

Prototype:
int agent_pursue_group(const char* group_name);
Description:

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.
Arguments:

group_name name of group from which pursue characters should be chosen
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision

function diguyCharacter::agent_call_formation

Prototype:
int agent_call_formation(const char* formation_name,
    float target_x,
    float target_y);
Description:

Calls a formation with this character as a leader, oriented towards (target_x, target_y).
Returns:

0 on success, -1 on failure

Travel Functions

Unless otherwise specified, all functions callable from:

C++
Script

function diguyCharacter::agent_travel_behavior_path

Prototype:
int agent_travel_behavior_path(const char* direction = NULL,
    const char* at_end = NULL,
    int waypoint_index = -1,
    float offset_y = 0.5f);
Description:

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.
Arguments:

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.

function diguyCharacter::agent_travel_path_shape

Prototype:
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);
Description:

Similar to agent_travel_behavior_path(), but specific path can be set rather than using behavior path.

function diguyCharacter::agent_travel_region_border

Prototype:
int agent_travel_region_border(const char* region_name = NULL,
    const char* subregion_name = "base");
Description:

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.
Arguments:

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

function diguyCharacter::agent_move_to_point

Prototype:
int agent_move_to_point(float x, float y, float z,
    const char* via_region = NULL,
    const char* subregion_name = "base");
Description:

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.
Arguments:

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

function diguyCharacter::agent_move_to_point_bg

Prototype:
int agent_move_to_point_bg(float x, float y, float z,
    const char* via_region = NULL,
    const char* subregion_name = "base");
Description:

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.

function diguyCharacter::agent_move_to_point_via_subregions

Prototype:
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);
Description:

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.
Arguments:

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

function diguyCharacter::agent_move_to_point_via_subregions_bg

Prototype:
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);
Description:

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.

function diguyCharacter::get_path_planning_result

Prototype:
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.

function diguyCharacter::get_is_path_planning

Prototype:
int get_is_path_planning();
Returns:

1 if character is currently waiting for a result from the multi-threaded path planner, else 0

function diguyCharacter::agent_move_to_region

Prototype:
int agent_move_to_region(const char* region,
    const char* subregion_name = "base",
    const char* via_region = NULL);
Description:

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.
Arguments:

region target region
subregion_name target subregion
via_region name of the region travel in
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision

function diguyCharacter::agent_move_to_region_via_subregions

Prototype:
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);
Description:

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

Path Follow Functions

Unless otherwise specified, all functions callable from:

C++
Script

function diguyCharacter::agent_path_follow

Prototype:
int agent_path_follow(const char* path_name);
Description:

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.
Arguments:

path_name name of a path of this character
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision

function diguyCharacter::agent_resume_path_follow

Prototype:
int agent_resume_path_follow();
Description:

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
Callable From:

C++
Script
Decision

function diguyCharacter::agent_get_path_follow_path

Prototype:
diguyCharacterPath* agent_get_path_follow_path();
Returns:

the path being followed in path behavior mode

function diguyCharacter::agent_get_path_follow_path_t

Prototype:
float agent_get_path_follow_path_t();
Description:

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

function diguyCharacter::agent_get_path_follow_path_t_paused

Prototype:
int agent_get_path_follow_path_t_paused();
Returns:

1 if time along the path is not advancing, else 0

Other Agent Functions

Unless otherwise specified, all functions callable from:

C++
Script

function diguyCharacter::agent_get_crowd

Prototype:
diguyCrowd* agent_get_crowd();
Returns:

the crowd this agent is a part of, if any; returns NULL if not in a crowd

function diguyCharacter::agent_begin_behavior

Prototype:
int agent_begin_behavior(const char* behavior_name);
Description:

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

function diguyCharacter::agent_stop_behavior

Prototype:
int agent_stop_behavior();
Description:

This function sets the behavior of the agent to "none".

function diguyCharacter::agent_set_current_focus_character

Prototype:
int agent_set_current_focus_character(const char* character_name);
Description:

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.
Arguments:

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
Callable From:

C++
Script
Decision

function diguyCharacter::agent_get_current_focus_character

Prototype:
diguyCharacter* agent_get_current_focus_character();
Description:

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.

pointer to type diguyCharacter

function diguyCharacter::agent_set_current_focus_group

Prototype:
int agent_set_current_focus_group(const char* group_name);
Description:

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.
Arguments:

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
Callable From:

C++
Script
Decision

function diguyCharacter::agent_get_initial_params

Prototype:
diguyAgentParams* agent_get_initial_params();
Description:

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.

pointer to type diguyAgentParams

function diguyCharacter::agent_get_current_params

Prototype:
diguyAgentParams* agent_get_current_params();
Description:

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.

pointer to type diguyAgentParams

function diguyCharacter::agent_get_current_params_profile_name

Prototype:
const char* agent_get_current_params_profile_name();
Description:

This function gets the name of the agent's current profile.
Returns:

the name of the agent's current profile

function diguyCharacter::agent_set_current_params_from_profile

Prototype:
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);
Description:

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.
Arguments:

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
Callable From:

C++
Script
Decision

function diguyCharacter::agent_set_initial_params_from_profile

Prototype:
int agent_set_initial_params_from_profile(const char* profile_name);
Description:

Similar to agent_set_current_params_from_profile(), but initial parameters are changed.

function diguyCharacter::agent_set_current_params_from_initial_params

Prototype:
void agent_set_current_params_from_initial_params();
Description:

This function sets the current parameters from the agent's initial parameters.

function diguyCharacter::agent_set_current_behavior_region_border_is_solid

Prototype:
void agent_set_current_behavior_region_border_is_solid(int is_solid);
Description:

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.
Arguments:

is_solid 1 if region border should be solid, 0 if not
Callable From:

C++
Script
Decision

function diguyCharacter::agent_move_on

Prototype:
void agent_move_on();
Description:

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.
Callable From:

C++
Script
Decision

function diguyCharacter::agent_set_auto_variant_selection

Prototype:
int agent_set_auto_variant_selection(int selection_enabled);
Description:

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.

function diguyCharacter::agent_get_auto_variant_selection

Prototype:
int agent_get_auto_variant_selection();
Description:

Returns if automatic variant selection is enabled, defaults to being on.

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

Arguments:

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

function diguyCharacter::agent_set_feeler_function

Prototype:
int agent_set_feeler_function(diguyFeelerFunction* feeler_function);
Description:

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.
Arguments:

feeler_function pointer to user-defined feeler function
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguyCharacter::agent_get_feeler_function

Prototype:
diguyFeelerFunction* agent_get_feeler_function();
Returns:

current feeler function; see set_feeler_function()
Callable From:

C++

Lua Mind Functions

function diguyCharacter::create_lua_mind

Prototype:
int create_lua_mind(const char* base_class, const char* init_arg1 = NULL,
    const char* init_arg2 = NULL);
Description:

Creates a Lua mind object based off of the contents of base_class.
Arguments:

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

function diguyCharacter::get_mind_name

Prototype:
const char *get_mind_name();
Description:

Returns the name of the mind, e.g. "luaPedestrian". This is, in other words, the mind's base class

function diguyCharacter::get_mind_current_state_name

Prototype:
const char* get_mind_current_state_name();
Description:

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

function diguyCharacter::do_mind_current_state_changed_callback

Prototype:
void do_mind_current_state_changed_callback();
Description:

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.

function diguyCharacter::set_sleep_timer

Prototype:
int set_sleep_timer(float sleep_length);
Description:

How long until the character's main coroutine thread should be resumed. This function is typically used by various luaCharacter sleep functions.
Arguments:

sleep_length how long relative to the current time the character should sleep

function diguyCharacter::get_sleep_timer

Prototype:
float get_sleep_timer();
Returns:

How long until the character's main coroutine thread resumes, relative to the current time.

function diguyCharacter::set_heartbeat_dt

Prototype:
int set_heartbeat_dt(float heartbeat_dt);
Description:

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.
Arguments:

heartbeat_dt frequency of heartbeat

function diguyCharacter::add_secondary_heartbeat

Prototype:
int add_secondary_heartbeat(const char* function_name,
    float heartbeat_dt);
Description:

This function allows the addition of additional heartbeat functions.
Arguments:

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

function diguyCharacter::remove_secondary_heartbeat

Prototype:
int remove_secondary_heartbeat(const char* function_name);
Description:

This function removes an added heartbeat function.
Arguments:

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

function diguyCharacter::set_secondary_heartbeat_dt

Prototype:
int set_secondary_heartbeat_dt(const char* function_name, float heartbeat_dt);
Description:

The frequency at which a luaCharacter's secondary heartbeat function should run. The character must have a Lua function named function_name.
Arguments:

function_name heartbeat function to adjust
heartbeat_dt frequency of heartbeat
Returns:

0 on success, -1 on failure

function diguyCharacter::add_wakeup_callback

Prototype:
int add_wakeup_callback(int callback);
Description:

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.
Arguments:

callback the callback id that should wake up the character
Returns:

0 on success, -1 on failure

function diguyCharacter::remove_wakeup_callback

Prototype:
int remove_wakeup_callback(int callback);
Description:

This function removes a request to trigger a message when a callback is triggered.
Arguments:

callback callback id that should no longer wake up the character
Returns:

0 on success, -1 on failure

function diguyCharacter::remove_all_wakeup_callbacks

Prototype:
int remove_all_wakeup_callbacks();
Description:

This function removes all requests to trigger a message when callbacks are triggered.
Returns:

0 on success, -1 on failure

function diguyCharacter::has_wakeup_callback

Prototype:
int has_wakeup_callback(int callback);
Description:

This function check for a requests to trigger a message when a given callback is triggered.
Returns:

0 on false, 1 on true

function diguyCharacter::agent_accept_message

Prototype:
int agent_accept_message(const char* sender,
    const char* message_type,
    const char* message,
    const char* message_params = NULL);
Description:

This function wakes up a character and sends them a message. Currently this is only applicable to characters with Lua minds.
Arguments:

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

function diguyCharacter::agent_broadcast_message

Prototype:
int agent_broadcast_message(float radius,
    const char* message_type,
    const char* message,
    const char* message_params = NULL);
Description:

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.
Arguments:

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

function diguyCharacter::agent_broadcast_message_to_group

Prototype:
int agent_broadcast_message_to_group(const char* group_name,
    float radius,
    const char* message_type,
    const char* message,
    const char* message_params = NULL);
Description:

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.
Arguments:

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

function diguyCharacter::get_lua_object_name

Prototype:
const char* get_lua_object_name();
Returns:

name of character's lua mind object; typically this is the character's name with '-' replaced by '_'

function diguyCharacter::set_mind_field_as_string

Prototype:
void set_mind_field_as_string(const char* field_name,
    const char* field_value);
Description:

Sets the specified field of the mind to the string field_value.

function diguyCharacter::get_mind_field_as_string

Prototype:
const char* get_mind_field_as_string(const char* field_name,
    int warn_if_no_field = 1);
Description:

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

function diguyCharacter::set_mind_field_as_float

Prototype:
void set_mind_field_as_float(const char* field_name, float field_value);
Description:

Sets the specified field of the mind to the floating point number field_value.

function diguyCharacter::get_mind_field_as_float

Prototype:
float get_mind_field_as_float(const char* field_name,
    int warn_if_no_field = 1,
    int* found_field = NULL);
Description:

Similar to get_mind_field_as_string(), but returns field as a float.
Returns:

field_name as double

function diguyCharacter::set_mind_field_as_int

Prototype:
void set_mind_field_as_int(const char* field_name, int field_value);
Description:

Sets the specified field of the mind to the integer number field_value.

function diguyCharacter::get_mind_field_as_int

Prototype:
int get_mind_field_as_int(const char* field_name,
    int warn_if_no_field = 1,
    int* found_field = NULL);
Description:

Similar to get_mind_field_as_int(), but returns field as an integer.
Returns:

field_name as int

function diguyCharacter::evaluate_mind_function

Prototype:
const char* evaluate_mind_function(const char* function_name,
    const char* argument = NULL,
    int has_return_string = 0);
Description:

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.
Arguments:

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

function diguyCharacter::get_ai_state_string

Prototype:
const char* get_ai_state_string(int include_stack = 1, int include_locals = 1);
Description:

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.
Arguments:

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

Visibility Functions

Unless otherwise specified, all functions callable from:

C++
Script

Visibility Tests

function diguyCharacter::check_character_visibility

Prototype:
int check_character_visibility(diguyCharacter* character,
    int los_check_type = 0);
Description:

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.
Arguments:

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

function diguyCharacter::check_point_visibility

Prototype:
int check_point_visibility(float x, float y, float z);
Description:

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.
Arguments:

x, y, z location to check
Returns:

1 if location is visible, 0 if not

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

function diguyCharacter::set_point_los_function

Prototype:
int set_point_los_function(diguyPointLOSFunction* point_los_function);
Description:

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++

function diguyCharacter::get_point_los_function

Prototype:
diguyPointLOSFunction* get_point_los_function();
Returns:

current point line-of-sight function; see set_point_los_function()
Callable From:

C++

function diguyCharacter::set_character_los_function

Prototype:
int set_character_los_function(diguyCharacterLOSFunction* character_los_function);
Description:

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++

function diguyCharacter::get_character_los_function

Prototype:
diguyCharacterLOSFunction* get_character_los_function();
Returns:

current character line-of-sight function; see set_character_los_function()
Callable From:

C++

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

function diguyCharacter::set_initial_character_simulator

Prototype:
int set_initial_character_simulator(diguyCharacterSimulator character_simulator);
Description:

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.
Arguments:

character_simulator which simulator to use at reset
Returns:

0 on success, -1 on failure

function diguyCharacter::get_initial_character_simulator

Prototype:
diguyCharacterSimulator get_initial_character_simulator();
Returns:

initial character simulator

function diguyCharacter::set_current_character_simulator

Prototype:
int set_current_character_simulator(diguyCharacterSimulator character_simulator);
Description:

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().
Arguments:

character_simulator new current character simulator
Returns:

0 on success, -1 on failure

function diguyCharacter::get_current_character_simulator

Prototype:
diguyCharacterSimulator get_current_character_simulator();
Returns:

current character simulator

function diguyCharacter::set_initial_physics_simulation_mode

Prototype:
int set_initial_physics_simulation_mode(diguyPhysicsSimulationMode physics_simulation_mode);
Description:

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.
Arguments:

physics_simulation_mode which simulation mode to use at reset
Returns:

0 on success, -1 on failure

function diguyCharacter::get_initial_physics_simulation_mode

Prototype:
diguyPhysicsSimulationMode get_initial_physics_simulation_mode();
Returns:

initial physics simulation mode

function diguyCharacter::set_current_physics_simulation_mode

Prototype:
int set_current_physics_simulation_mode(diguyPhysicsSimulationMode physics_simulation_mode);
Description:

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.
Arguments:

physics_simulation_mode new current physics simulation mode
Returns:

0 on success, -1 on failure

function diguyCharacter::get_current_physics_simulation_mode

Prototype:
diguyPhysicsSimulationMode get_current_physics_simulation_mode();
Returns:

initial physics simulation mode

function diguyCharacter::set_physics_collision_group

Prototype:
int set_physics_collision_group(diguyPhysicsCollisionGroup collision_group);
Description:

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().
Arguments:

physics_simulation_mode new current physics simulation mode
Returns:

0 on success, -1 on failure

function diguyCharacter::get_physics_collision_group

Prototype:
diguyPhysicsCollisionGroup get_physics_collision_group();
Returns:

physics collision group

function diguyCharacter::set_stop_physics_sim_at_t

Prototype:
void set_stop_physics_sim_at_t(float t);
Description:

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.
Arguments:

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.

function diguyCharacter::set_stop_physics_sim_in_t_seconds

Prototype:
void set_stop_physics_sim_in_t_seconds(float relative_t);
Description:

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

function diguyCharacter::get_stop_physics_sim_at_t

Prototype:
float get_stop_physics_sim_at_t();
Returns:

time at which physics simulation will freeze

function diguyCharacter::apply_impulse_to_physics_sim

Prototype:
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);
Description:

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.
Arguments:

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

function diguyCharacter::apply_impulse_to_physics_sim_from_world_position

Prototype:
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);
Description:

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.
Arguments:

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

Experimental Functions

The following functions are experimental and may change or disappear with no warning.

function diguyCharacter::set_texture_load_behavior

Prototype:
static int set_texture_load_behavior(diguyGraphicsTextureLoadingBehavior mode);
Description:

Sets texture load behavior to DIGUY_LOAD_INSTANTLY, DIGUY_LOAD_PRIORITY_ASYNC, or DIGUY_LOAD_ASYNC

function diguyCharacter::get_texture_load_behavior

Prototype:
static diguyGraphicsTextureLoadingBehavior get_texture_load_behavior();
Returns current behavior, as set in set_texture_load_behavior()

function diguyCharacter::get_has_bump_maps

Prototype:
int get_has_bump_maps();
Returns 1 if the current appearance has bump maps

function diguyCharacter::get_action_num_channels

Prototype:
int get_action_num_channels(const char* action_name);
Description:

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.
Arguments:

action_name name of action to be queried
Returns:

number of channels in specified action

function diguyCharacter::set_action_channel_weight

Prototype:
int set_action_channel_weight(const char* action_name,
    char channel,
    float weight);
Description:

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.
Arguments:

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

function diguyCharacter::get_action_channel_weight

Prototype:
float get_action_channel_weight(const char* action_name,
    char channel);
Description:

This function returns the weight of one channel of a multi-channel action.
Arguments:

action_name name of action to be queried
channel which channel's weight to return
Returns:

weight of a channel

function diguyCharacter::get_time_to_reach_desired_action

Prototype:
float get_time_to_reach_desired_action();
Description:

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

function diguyCharacter::get_type_map_field

Prototype:
const char* get_type_map_field(diguyCharacterTypeMapField field);
Description:

Maps a character type map field to its value. See diguyCharacterTypeMap.

Returns:

The value, as a string.

function diguyCharacter::get_type_map_field_using_string

Prototype:
const char* get_type_map_field_using_string(const char* field);
Description:

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.

function diguyCharacter::merge_object

Prototype:
int merge_object(const char* object);
Description:

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!

function diguyCharacter::is_active_character_in_group_visible

Prototype:
int is_active_character_in_group_visible(const char* group_name,
    float max_distance_to_check = 100000.0f);
Description:

Returns 1 if any active character in the named group is visible, otherwise 0.

group_name max_distance_to_check

function diguyCharacter::get_local_space_bounding_box

Prototype:
int get_local_space_bounding_box(float* x1, float* y1, float* z1,
    float* x2, float* y2, float* z2);
Description:

Gets local space bounding box, this function is currently expensive and should be used with care.
Arguments:

x1,y1,z1,x2,y2,z2 output parameters
Returns:

0 on success, -1 on failure (float * arguments converted to return values in Lua)

function diguyCharacter::get_geometry_tag

Prototype:
int get_geometry_tag(int tag,
    int world_space,
    float* x1, float* y1, float* z1, float* radius);
Description:

Get a spherical area containing geometry with specified tag, in specified world space.
Arguments:

tag the tag
world_space the world space
x1,y1,z1,radius output parameters returning sphere definition
Returns:

0 on success, -1 on failure (float * arguments converted to return values in Lua)

function diguyCharacter::set_mind_always_updates

Prototype:
void set_mind_always_updates(int force_update);
Description:

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.

function diguyCharacter::get_mind_always_updates

Prototype:
int get_mind_always_updates();
Description:

Returns value set by set_mind_always_updates()

function diguyCharacter::get_angle_to_path

Prototype:
float get_angle_to_path(const char* path_name,
    const char* action_bead_name = NULL);
Description:

Returns angle in degrees from character's "forward facing" vector to the specified action bead, on the specified path

function diguyCharacter::get_aim_at_link

Prototype:
const char* get_aim_at_link();
Returns:

Name of a reasonable link that other characters could aim at.

function diguyCharacter::get_aim_at_link_offset

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

function diguyCharacter::get_gaze_at_link

Prototype:
const char* get_gaze_at_link();
Returns:

Name of a reasonable link that other characters could look at.

function diguyCharacter::get_gaze_at_link_offset

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

function diguyCharacter::set_scene_graph_mask

Prototype:

void set_scene_graph_mask(unsigned int mask);

function diguyCharacter::set_use_texture_variations

Prototype:
int set_use_texture_variations(int value);
Description:

Turns on texture modulation system that tries to make all character look unique only supported by some appearances currently.

function diguyCharacter::get_use_texture_variations

Prototype:
int get_use_texture_variations();
Returns:

If texture variations have been enabled for this character.

function diguyCharacter::set_emit_light

Prototype:
int set_emit_light(int emit_light);
Description:

Sets whether or not character emits light.
Arguments:

emit_light 0 or 1

function diguyCharacter::get_emit_light

Prototype:
int get_emit_light();
Returns:

0 or 1, depending on whether or not character emits light.

function diguyCharacter::set_max_shader_quality_level

Prototype:
static int set_max_shader_quality_level(int quality_level);
Description:

Sets maximum quality of shader to use (actual quality varies by distance from camera). See diguyGraphicsShaderQualityLevel for possible values.
Arguments:

quality_level a value between DIGUY_GRAPHICS_SHADER_QUALITY_UNLIT

function diguyCharacter::get_max_shader_quality_level

Prototype:
static int get_max_shader_quality_level();
Returns:

max shader quality level, as set by set_max_shader_quality_level()

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.

function diguyCharacter::get_base_link

Prototype:
diguyGraphicsLink* get_base_link();
Deprecated as of 9.1.3; use diguyCharacter::get_position_link() instead.

function diguyCharacter::set_apply_actor_scale_to_action_bead_xy_travel

Prototype:
void set_apply_actor_scale_to_action_bead_xy_travel(int apply_scale_flag);
Deprecated as of 9.0.1; use set_apply_actor_scale_to_action_bead_travel()
instead.

function diguyCharacter::get_apply_actor_scale_to_action_bead_xy_travel

Prototype:
int get_apply_actor_scale_to_action_bead_xy_travel();
Deprecated as of 9.0.1; use get_apply_actor_scale_to_action_bead_travel()
instead.

function diguyCharacter::set_default_weapon_sound

Prototype:
int set_default_weapon_sound(const char* sound_name);
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().

function diguyCharacter::get_default_weapon_sound

Prototype:
const char* get_default_weapon_sound();
Deprecated as of 9.1.4. See comments for set_default_weapon_sound().

function diguyCharacter::set_default_weapon_sound_gain

Prototype:
int set_default_weapon_sound_gain(float gain);
Deprecated as of 9.1.4. See comments for set_default_weapon_sound().

function diguyCharacter::get_default_weapon_sound_gain

Prototype:
float get_default_weapon_sound_gain();
Deprecated as of 9.1.4. See comments for set_default_weapon_sound().

function diguyCharacter::set_weapon_munition_type

Prototype:
int set_weapon_munition_type(const char* munition_type);
Deprecated as of 9.1.4. Call set_weapon_munition_type_override() instead.

function diguyCharacter::get_weapon_munition_type

Prototype:
const char* get_weapon_munition_type();
Deprecated as of 9.1.4. Call get_weapon_munition_type_override() instead.

function diguyCharacter::set_weapon_horizontal_error

Prototype:
int set_weapon_horizontal_error(float h_error);
Deprecated as of 10.5.2. Call set_weapon_max_azimuth_error() instead.

function diguyCharacter::get_weapon_horizontal_error

Prototype:
float get_weapon_horizontal_error();
Deprecated as of 10.5.2. Call get_weapon_max_azimuth_error() instead.

function diguyCharacter::set_weapon_vertical_error

Prototype:
int set_weapon_vertical_error(float v_error);
Deprecated as of 10.5.2. Call set_weapon_max_elevation_error() instead.

function diguyCharacter::get_weapon_vertical_error

Prototype:
float get_weapon_vertical_error();
Deprecated as of 10.5.2. Call get_weapon_max_elevation_error() instead.

function diguyCharacter::begin_legacy_appearance_effect

Prototype:

int begin_legacy_appearance_effect(const char* effect,
    const char* override_link = "",
    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);

Added as of 10.1.6. Invokes the old implementation of begin_appearance_effect().

function diguyCharacter::end_legacy_appearance_effect

Prototype:
int end_legacy_appearance_effect(const char* effect);
Added as of 10.1.6. Invokes the old implementation of end_appearance_effect().

function diguyCharacter::legacy_appearance_effect_is_active

Prototype:
int legacy_appearance_effect_is_active(const char* effect);
Added as of 10.1.6. Invokes the old implementation of appearance_effect_is_active().

function diguyCharacter::merge_asset

Prototype:
int merge_asset(const char* asset);
Deprecated as of 10.5.1. Use merge_object() instead.

function diguyCharacter::set_DIS_smoke_trail_state

Prototype:
void set_DIS_smoke_trail_state(int state);
Deprecated as of 10.5.2. Use get_DIS_trailing_effect_state() instead.

function diguyCharacter::get_DIS_smoke_trail_state

Prototype:
int get_DIS_smoke_trail_state();
Deprecated as of 10.5.2. Use get_DIS_trailing_effect_state() instead.

function diguyCharacter::speak

Prototype:
int speak(const char* string);
Deprecated as of 12.0.0. Not supported in FaceFX.

function diguyCharacter::set_viseme

Prototype:
int set_viseme(const char* viseme_name, float weight);
Deprecated as of 12.0.0. Not supported in FaceFX.

function diguyCharacter::get_viseme

Prototype:
float get_viseme(const char* viseme_name);
Deprecated as of 12.0.0. Not supported in FaceFX.

function diguyCharacter::set_orientation_eye_left

Prototype:
int set_orientation_eye_left(float azimuth, float elevation);
Deprecated as of 12.0.0. Not supported in FaceFX.

function diguyCharacter::set_orientation_eye_right

Prototype:
int set_orientation_eye_right(float azimuth, float elevation);
Deprecated as of 12.0.0. Not supported in FaceFX.

function diguyCharacter::get_azimuth_eye_left

Prototype:
float get_azimuth_eye_left();
Deprecated as of 12.0.0. Not supported in FaceFX.

function diguyCharacter::get_elevation_eye_left

Prototype:
float get_elevation_eye_left();
Deprecated as of 12.0.0. Not supported in FaceFX.

function diguyCharacter::get_azimuth_eye_right

Prototype:
float get_azimuth_eye_right();
Returns:

the current azimuth of the right eye; see set_orientation_eyes()

function diguyCharacter::get_elevation_eye_right

Prototype:
float get_elevation_eye_right();
Returns:

the current elevation of the right eye; see set_orientation_eyes()

Alphabetical Index

These coded instructions, statements, and computer programs contain unpublished proprietary information of Boston Dynamics and are protected by Copyright Laws of the United States. They may not be used, duplicated, or disclosed in any form, in whole or in part, without the prior written consent from Boston Dynamics.

RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the government is subject to restrictions as set forth in FAR 52.227.19(c)(2) or subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Sofware clause at DFARS 252.227-7013 and/or in similar or successor clauses in the FAR, or the DOD or NASA FAR Supplement, or to subparagraphs (c)(1) and (c)(2) of the Commercial Computer Software--Restricted Rights at 48 CFR 52.227-19, as applicable. Unpublished-rights reserved under the Copyright Laws of the United States.

Contractor/Manufacturer is:

Boston Dynamics/78 Fourth Avenue/Waltham MA 02451.

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

`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

`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 to which this character's position link should attach; pass "" to attach to the parent's position link

`character`	character to be checked
`distance`	distance to character in meters

`group_name`	name of group to be checked
`distance`	distance in meters

`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

`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

`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

`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

`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

`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

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

`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

`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

`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

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

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

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

`link_name`	name of the link
`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

`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

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

`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

`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

`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

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

`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

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

`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

`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

`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