diguyScenario

Generated from diguyScenario.h

DI-Guy API Version 12.5.1

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

Contents:

Alphabetical Index

Link against: libdiguy

class diguyScenario

class BDI_DECLSPEC_diguy diguyScenario
{
public:
    static diguyScenario* get_current_scenario();
    const char* get_name();
    const char* get_type_name();
    const char* get_description();
#ifdef CPLUSPLUS_ONLY
    int update(float t);
    int update2(float t, float realtime_t);
    int set_playback_loop(int playback_loop);
    int set_tick_dt(float tick_dt);
#endif
    float get_t();
    float get_realtime_t();
    float get_desired_t();
    int set_tout(float tout);
    float get_tout();
    void set_tout_enabled(int tout_enabled);
    int get_tout_enabled();
    int get_playback_loop();
    float get_tick_dt();
    int get_ticks_can_be_dropped();
    void set_ticks_can_be_dropped(int ticks_can_be_dropped);
    long get_max_ticks_behind_until_drop();
    void set_max_ticks_behind_until_drop(long max_ticks_behind_until_drop);
    int set_playback_mode(diguyScenarioPlaybackMode playback_mode);
    int set_playback_mode_stop();
    int set_playback_mode_play();
    diguyScenarioPlaybackMode get_playback_mode();
    float derive_playback_mode_dt(float dt_in);
    int reset();
#ifdef CPLUSPLUS_ONLY
    int load(const char* filename);
    int save();
    int save_as(const char* filename);
    const char* get_filename();
    const char* get_filename_without_directory();
    int get_unsaved();
    void set_unsaved(int unsaved);
#ifdef CPLUSPLUS_ONLY
    int draw();
    int draw_pass1();
    int draw_pass2(int also_call_post_draw = 1);
#endif // CPLUSPLUS_ONLY
    int post_draw(int call_plugins_post_draw = 1,
        int call_lua_packages_draw = 1,
        int call_post_draw_callback = 1);
    int set_graphics_attach_ptr(void* graphics_attach_ptr);
#endif // CPLUSPLUS_ONLY
    diguyScenarioMergeSettings* create_merge_settings(diguyScenarioMergeInitialSettings initial_settings = DIGUY_MERGE_INITIAL_SETTINGS_DEFAULT);
    void destroy_merge_settings(diguyScenarioMergeSettings* merge_settings);
    int merge(const char* filename,
        diguyScenarioMergeSettings* merge_settings = NULL);
    int merge_object(const char* string);
    int include_object_library(const char* library_name);
    int uninclude_object_library(const char* library_name);
    void set_base_datetime(int year = -1,
        int month  = -1,
        int day    = -1,
        int hour   = -1,
        int minute = -1,
        int second = -1,
        int msec   = -1);
    void set_base_datetime(const char* datetime_string,
        const char* format);
    void get_base_datetime(int* year = NULL,
        int* month  = NULL,
        int* day    = NULL,
        int* hour   = NULL,
        int* minute = NULL,
        int* second = NULL,
        int* msec   = NULL);
    void set_base_datetime_default_to_now(int to_now);
    int get_base_datetime_default_to_now();
    void set_base_datetime_default_to_today(int to_today);
    int get_base_datetime_default_to_today();
    void set_current_datetime(int year = -1,
        int month  = -1,
        int day    = -1,
        int hour   = -1,
        int minute = -1,
        int second = -1,
        int msec   = -1);
    void set_current_datetime(const char* datetime_string,
        const char* format);
    void get_current_datetime(int* year = NULL,
        int* month  = NULL,
        int* day    = NULL,
        int* hour   = NULL,
        int* minute = NULL,
        int* second = NULL,
        int* msec   = NULL);
    const char* get_current_datetime_string(const char* format);
    void set_datetimes_are_utc(int are_utc);
    int get_datetimes_are_utc();
    void set_utc_offset_hours(float utc_offset_hours);
    float get_utc_offset_hours();
    void set_use_local_tz_utc_offset_hours(int use_local_tz);
    int get_use_local_tz_utc_offset_hours();
    void set_current_datetime_advance_method(diguyDatetimeAdvanceMethod advance_method);
    diguyDatetimeAdvanceMethod get_current_datetime_advance_method();
    void set_current_datetime_advance_factor(float advance_factor);
    float get_current_datetime_advance_factor();
    void get_network_datetime(int* year = NULL,
        int* month  = NULL,
        int* day    = NULL,
        int* hour   = NULL,
        int* minute = NULL,
        int* second = NULL,
        int* msec   = NULL);
    int set_tin_time_of_day(float t);
    float get_tin_time_of_day();
    float get_time_of_day();
#ifdef CPLUSPLUS_ONLY
    int add_appearance(const char* appearance,
        char** equipment_list,
        char** character_types,
        const char* actor);
    int add_appearance_based_on_existing_appearance(const char* appearance,
        const char* existing_appearance,
        char** equipment_list);
    int remove_appearance(const char* appearance);
#endif // CPLUSPLUS_ONLY
    int get_num_character_types_with_appearance(const char* appearance_name);
    const char *get_character_type_from_appearance(const char* appearance_name, int index = 0);
    int preload_character_type(const char* character_type);
    int preload_appearance(const char* appearance);
    int preload_gesture(const char* character_type, const char* gesture_name);
    void set_character_culling_enabled(int character_culling);
    int get_character_culling_enabled();
    void set_scene_object_culling_enabled(int object_culling);
    int  get_scene_object_culling_enabled();
    void set_scene_object_sub_culling_enabled(int object_culling);
    int  get_scene_object_sub_culling_enabled();
    void set_character_visualize_bounds_enabled(int visualize_bounds);
    int  get_character_visualize_bounds_enabled();
    void set_scene_object_visualize_bounds_enabled(int val);
    int  get_scene_object_visualize_bounds_enabled();
    int get_num_character_types();
    const char* get_character_type_at_index(int index);
    const char* get_character_type_abbreviation(const char* character_type);
    const char* get_character_type_deprecated_at_version(const char* character_type);
    const char* get_character_type_deprecated_suggested_alternatives(const char* character_type);
    int get_character_type_quality_bias(const char* character_type);
    diguyCharacterTypeMap* get_character_type_map(const char* character_type);
    const char* get_character_type_default_appearance(const char* character_type);
    const char* get_character_type_default_skinned_appearance(const char* character_type);
    int get_character_type_num_appearances(const char* character_type);
    const char* get_character_type_appearance_at_index(const char* character_type,
        int index);
    int get_character_type_num_head_appearances(const char* character_type);
    const char* get_character_type_head_appearance_at_index(const char* character_type,
        int index);
    int get_character_type_num_actions(const char* character_type);
    const char* get_character_type_action_at_index(const char* character_type,
        int index);
    float get_character_type_action_speed(const char* character_type,
        const char* action_name);
    float get_character_type_action_duration(const char* character_type,
        const char* action_name);
    float get_character_type_action_distance(const char* character_type,
        const char* action_name);
    diguyMotionDirection get_character_type_action_direction(
        const char* character_type,
        const char* action_name);
    float get_character_type_action_facing_angle_in(const char* character_type,
        const char* action_name);
    float get_character_type_action_facing_angle_out(const char* character_type,
        const char* action_name);
    int get_character_type_num_gestures(const char* character_type);
    const char* get_character_type_gesture_at_index(const char* character_type,
        int index);
    diguyCharacter* create_character(const char* name,
        const char* character_type,
        const char* appearance = NULL);
    diguyCharacter* create_temporary_character(const char* name,
        const char* character_type,
        const char* appearance = NULL);
    int destroy_character(diguyCharacter* character);
    int send_character_to_recycle_bin(diguyCharacter* character);
    diguyCharacter* retrieve_character_from_recycle_bin(const char* name,
        const char* character_type,
        const char* appearance,
        int make_character_temporary = 0);
    int get_num_characters();
    diguyCharacter* get_character_at_index(int index);
    diguyCharacter* find_character(const char* name);
    void look_at_character(diguyCharacter* character);
    diguyCharacter* this_character();
    diguyCharacterPathEvent* this_event_bead();
    int get_num_path_shapes();
    diguyPathShape* get_path_shape_at_index(int index);
    diguyPathShape* get_current_path_shape();
    diguyPathShape* find_path_shape(const char* name);
    diguyPathShape* create_path_shape(const char* name);
    diguyPathShape* copy_path_shape(diguyPathShape* existing_path_shape,
        const char* name);
    int destroy_path_shape(diguyPathShape* path_shape);
    diguyWaypoint* create_waypoint(float x = 0.0f, float y = 0.0f, float z = 0.0f,
        float yaw = 0.0f, float roll = 0.0f, float pitch = 0.0f,
        float weight_in = DIGUY_DEFAULT_FLOAT,
        float weight_out = DIGUY_DEFAULT_FLOAT);
    int destroy_waypoint(diguyWaypoint* waypoint);
    diguyCharacterTypeMap* get_nearest_character_type_map(
        diguyCharacterTypeMapField field1, const char* field1_value, const char* field1_alternate_value,
        diguyCharacterTypeMapField field2 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field2_value = NULL, const char* field2_alternate_value = NULL,
        diguyCharacterTypeMapField field3 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field3_value = NULL, const char* field3_alternate_value = NULL,
        diguyCharacterTypeMapField field4 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field4_value = NULL, const char* field4_alternate_value = NULL,
        diguyCharacterTypeMapField field5 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field5_value = NULL, const char* field5_alternate_value = NULL,
        diguyCharacterTypeMapField field6 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field6_value = NULL, const char* field6_alternate_value = NULL,
        diguyCharacterTypeMapField field7 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field7_value = NULL, const char* field7_alternate_value = NULL,
        diguyCharacterTypeMapField field8 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field8_value = NULL, const char* field8_alternate_value = NULL);
    diguyCharacterTypeMap* get_nearest_character_type_map_using_field_strings(
        const char* field1_string, const char* field1_value, const char* field1_alternate_value,
        const char* field2_string = NULL, const char* field2_value = NULL, const char* field2_alternate_value = NULL,
        const char* field3_string = NULL, const char* field3_value = NULL, const char* field3_alternate_value = NULL,
        const char* field4_string = NULL, const char* field4_value = NULL, const char* field4_alternate_value = NULL,
        const char* field5_string = NULL, const char* field5_value = NULL, const char* field5_alternate_value = NULL,
        const char* field6_string = NULL, const char* field6_value = NULL, const char* field6_alternate_value = NULL,
        const char* field7_string = NULL, const char* field7_value = NULL, const char* field7_alternate_value = NULL,
        const char* field8_string = NULL, const char* field8_value = NULL, const char* field8_alternate_value = NULL);
    diguyCharacterTypeMap* get_nearest_character_type_map_id_match(const char* type_map_id);
    int get_num_character_type_map_entries();
    diguyCharacterTypeMap* get_character_type_map_entry_at_index(int index);
    int get_num_type_map_character_classes();
    const char* get_type_map_character_class_at_index(int index);
    int get_num_type_map_categories(const char* character_class);
    const char* get_type_map_category_at_index(const char* character_class,
        int index);
    int get_num_type_map_subcategories(const char* character_class,
        const char* category);
    const char* get_type_map_subcategory_at_index(const char* character_class,
        const char* category,
        int index);
    int get_num_signals();
    diguySignal* get_signal_at_index(int index);
    diguySignal* find_signal(const char* name);
    diguySignal* create_signal(const char* name);
    int destroy_signal(diguySignal* signal);
    void reset_signals();
    int signal_palette_hide_all(const char* filter = NULL);
    int signal_palette_show_all(const char* filter = NULL);
    int get_num_sounds();
    diguySound* get_sound_at_index(int index);
    diguySound* find_sound(const char* name);
    diguySound* create_sound(const char* name,
        const char* sound_filename = NULL,
        const char* phoneme_filename = NULL);
    int destroy_sound(diguySound* sound);
    int preload_sound(diguySound* sound);
    int stop_all_sounds(float rampdown_time = 0.0f);
    int play_3d_sound(const char* name,
        float x, float y, float z,
        float gain,
        int save_event);
    int get_num_groups();
    diguyCharacterGroup* get_group_at_index(int index);
    diguyCharacterGroup* find_group(const char* name);
    diguyCharacterGroup* create_group(const char* name);
    diguyCharacterGroup* find_or_create_group(const char* name);
    int destroy_group(diguyCharacterGroup* group);
    int get_num_sensor_regions();
    diguySensorRegion* get_sensor_region_at_index(int index);
    diguySensorRegion* find_sensor_region(const char* name);
    int get_num_scene_objects();
    diguySceneObject* get_scene_object_at_index(int index);
    diguySceneObject* find_scene_object(const char* name);
    void set_scene_objects_enabled(int scene_objects_enabled);
    int get_scene_objects_enabled();
    diguySceneObject* create_scene_object(const char* name,
        const char* filename);
    diguySceneObject* create_user_defined_scene_object(const char* name);
    int destroy_scene_object(diguySceneObject* scene_object);
    diguyView* get_primary_view();
    int get_num_secondary_views();
    diguyView* get_secondary_view_at_index(int index);
    diguyView* find_view(const char* name);
    diguyViewCamera* get_scenario_camera();
    diguyViewCamera* find_camera(const char* name);
    void set_scenario_camera_affected_by_script_events(int flag);
    int get_scenario_camera_affected_by_script_events();
    void set_scenario_camera_affected_by_script_events_when_iguy_active(int flag);
    int get_scenario_camera_affected_by_script_events_when_iguy_active();
    int get_num_camera_settings();
    diguyViewCameraSettings* get_camera_settings_at_index(int index);
    diguyViewCameraSettings* find_camera_settings(const char* settings_name);
    int load_camera_settings(const char* settings_name, int update_current_camera = 1);
    void set_render_camera(diguyViewCamera* camera);
    diguyViewFog* get_scenario_fog();
    diguyViewFog* find_fog(const char* name);
    diguyViewFog* find_or_create_fog(const char* name);
    void load_current_fog(const char* name);
    int get_num_fog_settings();
    diguyViewFogSettings* get_fog_settings_at_index(int index);
    diguyViewFogSettings* find_fog_settings(const char* settings_name);
    int load_fog_settings(const char* settings_name);
    diguyViewLight* get_scenario_light(int i = 0);
    diguyViewLight* find_light(const char* name);
    int get_num_light_settings();
    diguyViewLightSettings* get_light_settings_at_index(int index);
    diguyViewLightSettings* find_light_settings(const char* settings_name);
    int load_light_settings(const char* settings_name, int light_num = 0);
    int get_num_info_popups();
    diguyInfoPopup* get_info_popup_at_index(int index);
    diguyInfoPopup* find_info_popup(const char* name);
    int set_info_popup_default_encoding(const char* info_popup_default_encoding);
    const char* get_info_popup_default_encoding();
    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 get_num_face_expressions();
    diguyCharacterFaceExpression* get_face_expression_at_index(int index);
    diguyCharacterFaceExpression* find_face_expression(const char* name);
    diguyCharacterFaceExpression* create_face_expression(const char* name,
        const char* target_actor = "exface");
    int destroy_face_expression(diguyCharacterFaceExpression* face_expression);
    int get_num_chain_settings();
    diguyChainSettings* get_chain_settings_at_index(int index);
    diguyChainSettings* find_chain_settings(const char* name);
    diguyChainSettings* create_chain_settings(const char* name);
    int destroy_chain_settings(diguyChainSettings* chain_settings);
    enum {
        CALLBACK_ID_CREATE = 1,
        CALLBACK_ID_DESTROY,
        CALLBACK_ID_RESET,
        CALLBACK_ID_WAIT_CURSOR_SHOW,
        CALLBACK_ID_WAIT_CURSOR_HIDE,
        CALLBACK_ID_LOAD,
        CALLBACK_ID_SAVE,
        CALLBACK_ID_LOAD_SCENARIO_FILE,
        CALLBACK_ID_SAVE_SCENARIO_FILE,
        CALLBACK_ID_SCENE_OBJECT_IMPACT,
        CALLBACK_ID_TIMED_EVENT,
        CALLBACK_ID_MANUALLY_INVOKED,
        CALLBACK_ID_POST_DRAW,
        CALLBACK_ID_PLAYBACK_MODE_CHANGED,
        CALLBACK_ID_INPUT_MODE_CHANGED,
        CALLBACK_ID_RENDER_MODE_CHANGED,
        CALLBACK_ID_PRE_REINITIALIZE,
        CALLBACK_ID_POST_REINITIALIZE,
        CALLBACK_ID_POST_LOAD_CHECKPOINT
    };
#ifdef CPLUSPLUS_ONLY
    int add_callback(int callback_id,
        diguyScenarioCallback* callback,
        void* callback_params = 0,
        void* callback_user_data = 0,
        int remove_on_scenario_load = 1);
    int remove_callback(int callback_id,
        diguyScenarioCallback* callback);
    int remove_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int add_default_character_callback(int callback_id,
        diguyCharacterCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 0,
        int remove_on_scenario_load = 1);
    int remove_default_character_callback(int callback_id,
        diguyCharacterCallback* callback);
    int remove_default_character_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int add_default_path_callback(int callback_id,
        diguyCharacterPathCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 0,
        int remove_on_scenario_load = 1);
    int remove_default_path_callback(int callback_id,
        diguyCharacterPathCallback* callback);
    int remove_default_path_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int add_default_sensor_region_callback(int callback_id,
        diguySensorRegionCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 0,
        int remove_on_scenario_load = 1);
    int remove_default_sensor_region_callback(int callback_id,
        diguySensorRegionCallback* callback);
    int remove_default_sensor_region_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int add_default_signal_callback(int callback_id,
        diguySignalCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 0,
        int remove_on_scenario_load = 1);
    int remove_default_signal_callback(int callback_id,
        diguySignalCallback* callback);
    int remove_default_signal_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int add_default_variable_callback(int callback_id,
        diguyVariableCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 0,
        int remove_on_scenario_load = 1);
    int remove_default_variable_callback(int callback_id,
        diguyVariableCallback* callback);
    int remove_default_variable_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int add_default_view_callback(int callback_id,
        diguyViewCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 1,
        int remove_on_scenario_load = 1);
    int remove_default_view_callback(int callback_id,
        diguyViewCallback* callback);
    int remove_default_view_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int add_default_camera_callback(int callback_id,
        diguyViewCameraCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 0,
        int remove_on_scenario_load = 1);
    int remove_default_camera_callback(int callback_id,
        diguyViewCameraCallback* callback);
    int remove_default_camera_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int add_default_fog_callback(int callback_id,
        diguyViewFogCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 0,
        int remove_on_scenario_load = 1);
    int remove_default_fog_callback(int callback_id,
        diguyViewFogCallback* callback);
    int remove_default_fog_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int add_default_light_callback(int callback_id,
        diguyViewLightCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 0,
        int remove_on_scenario_load = 1);
    int remove_default_light_callback(int callback_id,
        diguyViewLightCallback* callback);
    int remove_default_light_callback_with_user_data(int callback_id,
        void* callback_user_data);
#endif
    void manually_invoke_callbacks_now(int callback_id);
    int add_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL,
        int remove_on_scenario_load = 1);
    int remove_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int add_default_character_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL,
        int add_to_existing_objects_flag = 0,
        int remove_on_scenario_load = 1);
    int remove_default_character_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int add_default_sensor_region_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL,
        int add_to_existing_objects_flag = 0,
        int remove_on_scenario_load = 1);
    int remove_default_sensor_region_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int add_default_signal_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL,
        int add_to_existing_objects_flag = 0,
        int remove_on_scenario_load = 1);
    int remove_default_signal_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int add_default_variable_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL,
        int add_to_existing_objects_flag = 0,
        int remove_on_scenario_load = 1);
    int remove_default_variable_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int add_default_view_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL,
        int add_to_existing_objects_flag = 0,
        int remove_on_scenario_load = 1);
    int remove_default_view_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int add_default_camera_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL,
        int add_to_existing_objects_flag = 0,
        int remove_on_scenario_load = 1);
    int remove_default_camera_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int add_default_fog_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL,
        int add_to_existing_objects_flag = 0,
        int remove_on_scenario_load = 1);
    int remove_default_fog_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int add_default_light_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL,
        int add_to_existing_objects_flag = 0,
        int remove_on_scenario_load = 1);
    int remove_default_light_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);
#ifdef CPLUSPLUS_ONLY
    int register_character_event_handler(const char* handler_name,
        diguyCharacterCallback* callback,
        void* callback_user_data = 0);
#endif
    int register_character_event_handler_from_library(const char* handler_name,
        const char* library_name,
        const char* function_name,
        void* callback_user_data = 0);
    int register_character_event_handler_script(const char* handler_name,
        const char* handler_script,
        const char* handler_script_type = 0);
    int has_registered_character_event_handler(const char* handler_name);
    int unregister_character_event_handler(const char* handler_name);
#ifdef CPLUSPLUS_ONLY
    int register_signal_event_handler(const char* handler_name,
        diguySignalCallback* callback,
        void* callback_user_data = 0);
#endif
    int register_signal_event_handler_from_library(const char* handler_name,
        const char* library_name,
        const char* function_name,
        void* callback_user_data = 0);
    int register_signal_event_handler_script(const char* handler_name,
        const char* handler_script,
        const char* handler_script_type = 0);
    int has_registered_signal_event_handler(const char* handler_name);
    int unregister_signal_event_handler(const char* handler_name);
#ifdef CPLUSPLUS_ONLY
    int register_sensor_region_event_handler(const char* handler_name,
        diguySensorRegionCallback* callback,
        void* callback_user_data = 0);
#endif
    int register_sensor_region_event_handler_from_library(const char* handler_name,
        const char* library_name,
        const char* function_name,
        void* callback_user_data = 0);
    int register_sensor_region_event_handler_script(const char* handler_name,
        const char* handler_script,
        const char* handler_script_type = 0);
    int has_registered_sensor_region_event_handler(const char* handler_name);
    int unregister_sensor_region_event_handler(const char* handler_name);
#ifdef CPLUSPLUS_ONLY
    int register_variable_event_handler(const char* handler_name,
        diguyVariableCallback* callback,
        void* callback_user_data = 0);
#endif
    int register_variable_event_handler_from_library(const char* handler_name,
        const char* library_name,
        const char* function_name,
        void* callback_user_data = 0);
    int register_variable_event_handler_script(const char* handler_name,
        const char* handler_script,
        const char* handler_script_type = 0);
    int has_registered_variable_event_handler(const char* handler_name);
    int unregister_variable_event_handler(const char* handler_name);
    int save_review_data(const char* filename);
    int get_loaded_from_review_data();
    int set_history_type(diguyHistoryType history_type);
    diguyHistoryType get_history_type();
    void set_overall_history_type(diguyHistoryType overall_history_type);
    diguyHistoryType get_overall_history_type();
    int get_replaying_history();
    void set_history_max_sound_instances(int num_sound_instances);
    void set_automatic_graphics_lod_switching(int enable_graphics_lod_switching);
    int get_automatic_graphics_lod_switching();
#ifdef CPLUSPLUS_ONLY
    void set_default_lod_ranges(const char* character_type, float* ranges);
#endif
    void set_scale_graphics_lod_ranges_from_view_settings(int do_scale);
    int  get_scale_graphics_lod_ranges_from_view_settings();
    void set_automatic_motion_lod_switching(int enable_motion_lod_switching);
    int get_automatic_motion_lod_switching();
    int eval_script(const char* script_text,
        int save_as_transient = 0,
        const char* script_type = NULL,
        const char* script_source = NULL);
    int eval_script_file(const char* filename,
        const char* script_type = NULL);
    int trigger_script(const char* script_name);
    void trigger_script_delayed(const char* script_name, float t_delay);
    int trigger_decision(const char* decision_name);
    void trigger_decision_delayed(const char* decision_name, float t_delay);
    void push_transient_script_event(float t, const char* script_text, const char* script_type);
    void clear_transient_script_events();
    int save_transient_script_events(const char* filename);
    int load_transient_script_events(const char* filename);
    int load_package(const char* filename,
        const char* language = NULL,
        int warn_if_not_found = 1);
    int load_package_with_dependancy(const char* filename,
        const char* depends_on_package,
        const char* language = NULL,
        int warn_if_not_found = 1);
    int get_character_type_num_postures(const char* character_type);
    diguyMotionPosture get_character_type_posture_at_index(const char* character_type,
        int index);
    diguyMotionPosture get_character_type_action_posture(const char* character_type,
        const char* action_name);
    int get_character_type_num_variants(const char* character_type);
    diguyMotionVariant get_character_type_variant_at_index(const char* character_type,
        int index);
    diguyMotionVariant get_character_type_action_primary_variant(const char* character_type,
        const char* action_name);
    int get_character_type_action_num_variants(const char* character_type,
        const char* action_name);
    diguyMotionVariant get_character_type_action_variant_at_index(const char* character_type,
        const char* action_name,
        int index);
    int get_character_type_num_directions(const char* character_type);
    diguyMotionDirection get_character_type_direction_at_index(const char* character_type,
        int index);
    int get_num_interaction_machines();
    diguyInteractionMachine* create_interaction_machine(const char* name);
    void destroy_interaction_machine(diguyInteractionMachine* interaction_machine);
    diguyInteractionMachine* get_interaction_machine_at_index(int index);
    diguyInteractionMachine* find_interaction_machine(const char* name);
    diguyInteractionMachine* get_active_interaction_machine();
    diguyInteractionMachine* get_shared_interaction_machine();
    int show_notification_with_shared_interaction_machine(const char* heading,
        const char* info,
        int pause_scenario = 0,
        const char* input_text = NULL,
        int ui_appearance = diguyInteractionMachine::UI_APPEARANCE_NOTIFICATION);
    diguyIGuyController* get_iguy_controller();
    diguyViewLabel* find_or_create_label(const char* name);
    diguyViewLabel* find_label(const char* name);
    int destroy_label(diguyViewLabel* label);
    int	get_num_labels();
    diguyViewLabel* get_label_at_index(int index);
    void reset_labels();
    void send_label_to_front(diguyViewLabel* label);
    void send_label_to_back(diguyViewLabel* label);
    diguyViewButtonPanel* find_or_create_panel(const char* name,
        int horizontal = 0,
        int title = 1);
    diguyViewButtonPanel* find_panel(const char* name);
    int destroy_panel(diguyViewButtonPanel* panel);
    int	get_num_panels();
    diguyViewButtonPanel* get_panel_at_index(int index);
    int get_num_minds();
    const char* get_mind_name_at_index(int index);
    int is_valid_character_pointer(diguyCharacter* character);
    int is_valid_character_group_pointer(diguyCharacterGroup* character_group);
    diguyCrowd* create_crowd(const char* name,
        int make_companion_of_all = 1);
    int destroy_crowd(diguyCrowd* crowd,
        int also_destroy_crowd_members = 0,
        int also_destroy_path_shapes = 0,
        int delay_destruction = 0);
    int get_num_crowds();
    diguyCrowd* get_crowd_at_index(int index);
    const char* get_unique_crowd_name(const char* base_name);
    diguyCrowd* find_crowd(const char* crowd_name);
    diguyCrowd* find_or_create_crowd(const char* crowd_name,
        int make_companion_of_all = 1);
    void set_create_network_crowds(int do_create);
    int get_create_network_crowds();
    diguyCrowdProfile* create_crowd_profile(const char* name);
    int destroy_crowd_profile(diguyCrowdProfile* crowd_profile);
    int get_num_crowd_profiles();
    diguyCrowdProfile* get_crowd_profile_at_index(int index);
    diguyCrowdProfile* find_crowd_profile(const char* name);
    diguyLoadManager* get_character_load_manager();
    int force_octtree_generation();
    void add_character_to_octtree(diguyCharacter* character,
        int use_bounding_box_only = 0);
    void remove_character_from_octtree(diguyCharacter* character);
    int preload_octtree(const char* character_type, const char* appearance);
    int check_visibility(float x1, float y1, float z1,
        float x2, float y2, float z2);
#ifdef CPLUSPLUS_ONLY
    int set_default_character_altitude_function(diguyAltitudeFunction* altitude_function);
    void set_altitude_function(diguyScenarioAltitudeFunction* altitude_function);
    diguyScenarioAltitudeFunction* get_altitude_function();
#endif
    void set_altitude_max_climb(float altitude_max_climb);
    float get_altitude_max_climb();
    void set_altitude_max_drop(float altitude_max_drop);
    float get_altitude_max_drop();
    static void set_default_intersection_function(diguyScenarioIntersectionFunction* intersection_function);
    void set_intersection_function(diguyScenarioIntersectionFunction* intersection_function);
    int trigger_detonation(const char* munition_name,
        float x, float y, float z,
        const char* attacker_name = NULL,
        float radius_override = -1.0f,
        int broadcast_on_network = 1);
    diguyImpact* find_character_at_screen_coords(diguyView* view,
        float sx,
        float sy);
    diguyImpact* get_impact_at_screen_coords(diguyView* view,
        float sx,
        float sy,
        int use_octtree = 0);
    diguyImpact* get_intersection_at_screen_coords(diguyView* view,
        float sx,
        float sy,
        int use_octtree = 0);
    int intersect_static_geometry(
        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 = NULL, float* normal_y = NULL, float* normal_z = NULL,
        int use_callback = 1);
    float ground_clamp(float x, float y, float z,
        int* valid = NULL,
        int use_altitude_function = 1,
        int use_octtree = 0);
#ifdef CPLUSPLUS_ONLY
    int set_fire_weapon_intersection_function(diguyScenarioFindImpactOnLineFunction* impact_function);
    static void set_default_fire_weapon_intersection_function(diguyScenarioFindImpactOnLineFunction* impact_function);
#endif
    diguyImpact* map_color_to_impact(char r, char g, char b);
    diguyImpact* get_last_env_impact_info();
    void set_last_impact_been_processed();
    void set_last_env_impact_info(const diguyImpact& impact);
    void set_max_unprocessed_impacts(int max_unprocessed_impacts);
#ifdef CPLUSPLUS_ONLY
    int set_default_point_los_function(diguyPointLOSFunction* point_los_function);
    int set_default_character_los_function(diguyCharacterLOSFunction* character_los_function);
    int set_default_agent_feeler_function(diguyFeelerFunction* feeler_function);
#endif
    diguyIntersectionResult exp_intersect_geometry(
        float origin_x, float origin_y, float origin_z,
        float dir_x,    float dir_y,    float dir_z,
        float max_distance_to_test,
        int use_callback = 1);
    diguyRegion* find_or_create_region(const char* name);
    diguyRegion* find_region(const char* name);
    diguyRegion* create_region(const char* name);
    void destroy_region(diguyRegion* region);
    int get_num_regions();
    diguyRegion* get_region_at_index(int index);
    int find_navigation_path(float x1, float y1, float z1,
        float x2, float y2, float z2,
        const char* via_region,
        diguyPathShape* path_shape,
        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_repulsive_regions = 100.0f);
    void set_max_distance_planning_multiplier(float mul);
    float get_max_distance_planning_multiplier();
    float get_time_spent_path_planning_this_frame();
    void set_multithreaded_path_planning_enabled(int value);
    int get_multithreaded_path_planning_enabled();
    int get_num_formations();
    diguyFormation* get_formation_at_index(int index);
    diguyFormation* find_formation(const char* name);
    diguyFormation* find_formation_of_size(int size);
    diguyFormation* create_formation(const char* name);
    diguyFormation* find_or_create_formation(const char* name);
    int destroy_formation(diguyFormation* formation);
    void set_action_bead_labels_visible(diguyVisibleFlag vflag);
    void set_aim_trajectories_visible(diguyVisibleFlag vflag);
    void set_author_selection_handles_visible(diguyVisibleFlag vflag);
    void set_bead_array_visible(diguyVisibleFlag vflag);
    void set_character_labels_visible(diguyVisibleFlag vflag);
    void set_character_visible(diguyVisibleFlag vflag);
    void set_crowd_behavior_visible(diguyVisibleFlag flag);
    void set_crowd_feelers_visible(diguyVisibleFlag flag);
    void set_crowd_influence_visible(diguyVisibleFlag flag);
    void set_crowd_regions_visible(diguyVisibleFlag flag);
    void set_light_array_visible(diguyVisibleFlag vflag);
    void set_lua_objects_visible(diguyVisibleFlag flag);
    void set_mesh_region_array_visible(diguyVisibleFlag vflag);
    void set_sensor_region_array_visible(diguyVisibleFlag vflag);
    void set_spath_visible(diguyVisibleFlag vflag);
    void set_waypoint_array_visible(diguyVisibleFlag vflag);
    diguyVisibleFlag get_action_bead_labels_visible();
    diguyVisibleFlag get_aim_trajectories_visible();
    diguyVisibleFlag get_author_selection_handles_visible();
    diguyVisibleFlag get_bead_array_visible();
    diguyVisibleFlag get_character_labels_visible();
    diguyVisibleFlag get_character_visible();
    diguyVisibleFlag get_crowd_behavior_visible();
    diguyVisibleFlag get_crowd_feelers_visible();
    diguyVisibleFlag get_crowd_influence_visible();
    diguyVisibleFlag get_crowd_regions_visible();
    diguyVisibleFlag get_light_array_visible();
    diguyVisibleFlag get_lua_objects_visible();
    diguyVisibleFlag get_mesh_region_array_visible();
    diguyVisibleFlag get_sensor_region_array_visible();
    diguyVisibleFlag get_spath_visible();
    diguyVisibleFlag get_waypoint_array_visible();
    void set_hide_author_selection_handles_during_play(int visible);
    int get_hide_author_selection_handles_during_play();
    int get_weapon_fire_effects_enabled();
    
    int set_weapon_fire_effects_enabled(int enabled);
    
    int get_num_active_fire_effects();
    
    int get_weapon_fire_effect_data(int index, float * radius, 
        float * position_x, float * position_y, float * position_z, 
        float * color_r, float * color_g, float * color_b,
        float * falloff_r,
        float * falloff_rsq);
    int set_current_character(diguyCharacter* current_character);
    diguyCharacter* get_current_character();
    int set_current_crowd(diguyCrowd* current_crowd);
    diguyCrowd* get_current_crowd();
    int set_current_crowd_profile(diguyCrowdProfile* current_profile);
    int set_current_crowd_profile_by_name(const char* crowd_profile_name);
    diguyCrowdProfile* get_current_crowd_profile();
    int set_current_region(diguyRegion* current_region);
    diguyRegion* get_current_region();
    void set_particle_module_disabled(int disable_particle_module);
    int create_particle_system(const char* description_name,
        float x, float y, float z,
        int record_transient_event = 1,
        float duration = -1.0f);
    int create_particle_system_with_orientation(const char* description_name,
        float x, float y, float z,
        float rz, float rx, float ry,
        int record_transient_event = 1,
        float duration = -1.0f);
    int has_particle_description(const char* description_name);
    void set_global_wind(float x, float y, float z);
    const char* lua_get_object_field_as_string(const char* lua_object,
        const char* field_name);
    const char* lua_evaluate_object_function(const char* lua_object,
        const char* function_name,
        const char* argument = NULL,
        int has_return_string = 0);
    const char* lua_evaluate_object_function_2a(const char* lua_object,
        const char* function_name,
        const char* argument,
        const char* argument2,
        int has_return_string = 0);
    const char* lua_evaluate_object_function_3a(const char* lua_object,
        const char* function_name,
        const char* argument,
        const char* argument2,
        const char* argument3,
        int has_return_string = 0);
    const char* lua_evaluate_object_function_4a(const char* lua_object,
        const char* function_name,
        const char* argument,
        const char* argument2,
        const char* argument3,
        const char* argument4,
        int has_return_string = 0);
    int lua_send_message_to_object(const char* lua_object,
        const char* sender,
        const char* message_type,
        const char* message,
        const char* message_params = NULL);
#ifdef CPLUSPLUS_ONLY
    void* get_lua_state();
    int push_qt_pointer_to_lua(void* lua_state,
        const char* class_name,
        void* ptr);
    const char* lua_evaluate_object_function_4a_flex(const char* lua_object,
        const char* function_name,
        const char* arg1_type, void* argument1,
        const char* arg2_type, void* argument2,
        const char* arg3_type, void* argument3,
        const char* arg4_type, void* argument4,
        int has_return_string = 0);
    const char* lua_evaluate_global_function_4a_flex(const char* function_name,
        const char* arg_type, void* argument,
        const char* arg_type2, void* argument2,
        const char* arg_type3, void* argument3,
        const char* arg_type4, void* argument4,
        int has_return_string = 0);
#endif
    int lua_log_printf(int notify_level, const char* string);
    const char* dump_package_info(const char* package_name);
    int get_eval_decisions_as_scripts();
    void set_eval_decisions_as_scripts(int eval_decisions_as_scripts);
    diguyImpact* get_impact_on_line(float from_x,
        float from_y,
        float from_z,
        float to_x,
        float to_y,
        float to_z);
    void wait_cursor_push();
    void wait_cursor_pop();
#ifdef CPLUSPLUS_ONLY
    void set_graphics_api_node_ptr(void* node_ptr);
    void* get_graphics_api_node_ptr();
#endif
    void set_draw_character_shadow_disks(int draw_character_shadow_disks);
    int  get_draw_character_shadow_disks();
    int  get_shadow_map_size();
    int  set_shadow_map_size(int shadow_size);
    void          set_default_character_scene_graph_mask(unsigned long mask);
    unsigned long get_default_character_scene_graph_mask();
    void          set_default_scene_object_scene_graph_mask(unsigned long mask);
    unsigned long get_default_scene_object_scene_graph_mask();
    void set_internal_int(int var, int val);
    void set_internal_float(int var, float val);
    int set_num_active_point_lights(int active_lights);
    int get_num_active_point_lights();
    int optimized_update(float t);
    int set_world_bounds(float x_min, float y_min, float z_min,
        float x_max, float y_max, float z_max);
    int get_world_bounds(float* x_min, float* y_min, float* z_min,
        float* x_max, float* y_max, float* z_max);
    void set_checkpoint_frequency(float freq);
    float get_checkpoint_frequency();
    void set_checkpointing_enabled(int enable_checkpointing);
    int get_checkpointing_enabled();
    void set_initial_render_mode(const char* render_mode);
    const char* get_initial_render_mode();
    void set_current_render_mode(const char* render_mode);
    const char* derive_render_mode_from_light_settings(int set_current_to_derived = 1);
    const char* get_current_render_mode();
    void set_default_character_shader(const char* render_mode,
        const char* shader_name,
        int update_existing_characters = 1);
    const char* get_default_character_shader(const char* render_mode);
    void set_default_scene_object_shader(const char* render_mode,
        const char* shader_name,
        int update_existing_scene_objects = 1);
    const char* get_default_scene_object_shader(const char* render_mode);
    void set_default_particle_system_shader(const char* render_mode,
        const char* shader_name,
        int update_existing_particle_systems = 1);
    const char* get_default_particle_system_shader(const char* render_mode);
    int facefx_mount_animset(const char* actor_name, const char* file_name);
    int set_vehicle_smoothing_enabled(int enable_smoothing);
    int get_vehicle_smoothing_enabled();
    int set_character_culling_distance(float dist);
    float get_character_culling_distance();
    int set_vehicle_culling_distance(float dist);
    float get_vehicle_culling_distance();
    int set_prop_culling_distance(float dist);
    float get_prop_culling_distance();
#ifdef CPLUSPLUS_ONLY
    static int add_default_callback(int callback_id,
        diguyScenarioCallback* callback,
        void* callback_params = 0,
        void* callback_user_data = 0);
    static int remove_default_callback(int callback_id,
        diguyScenarioCallback* callback);
#endif
    static int remove_default_callback_with_user_data(int callback_id,
        void* callback_user_data);
    static int add_default_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type);
    static int remove_default_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type);
    const char* get_character_type_class(const char* character_type);
    int merge_asset(const char* string);
    void print_to_log(int notify_level, const char* string);
#ifdef CPLUSPLUS_ONLY
    diguyCharacter* create_pending_reflected_character(const char* name,
        const char* character_type,
        const char* appearance = NULL);
    int set_network_translation(float x, float y, float z);
    int get_network_translation(float* x, float* y, float* z);
    void set_project_filename(const char* project_filename);
    const char* get_project_filename();

General Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_current_scenario

Prototype:
static diguyScenario* get_current_scenario();
Description:

This static function returns a pointer to the current scenario object. All functions below can then be called through this pointer. This is the same pointer returned by the call diguy_create_scenario().

lua scripts get the current scenario through the variable this_scenario.
Returns:

a pointer of type diguyScenario
C++ Example:
diguyScenario* sc = diguyScenario::get_current_scenario();
sc->reset();
Lua Example:
this_scenario:reset();

function diguyScenario::get_name

Prototype:
const char* get_name();
Description:

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

name of the object

function diguyScenario::get_type_name

Prototype:
const char* get_type_name();
Description:

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

type name of the object

function diguyScenario::get_description

Prototype:
const char* get_description();
Returns:

the scenario description as specified in the scenario info page

Time Control and Playback Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::update

Prototype:
int update(float t);
Description:

Sets the desired simulation time of the scenario.

Some update operations will use the simulation desired time directly.

Many other scenario operations -- notably character position and pose updates -- will not happen until the desired t passes each subsequent tick dt threshold. See set_tick_dt().

This function sets both elapsed simulation time and elapsed realtime to the same value. This is usually desired in DI-Guy applications. To pass separate values for simulation time and realtime time, call update2().

Time can be run backwards. This happens if the passed t is lower than any t previously passed to the update() function; the scenario remembers the highest t it has reached. If t is set to less that the highest t reached, characters that have history data will replay what they were doing at the specified time. Characters that do not have history will remain motionless until t advances past the previous highest t.

Scenario time will never go below 0.

If t reaches the scenario tout ("T Out") time (as set by set_tout(), a number of things may happen. The scenario may:

simply stop at the tout time
continue past the tout time
rewind to time 0 and play back recorded history
reset and re-simulate the scenario from time 0

The default tout time is 60000 for DI-Guy applications. The tout can be enabled and disabled with set_tout_enabled().

This function cannot explicitly be called for DI-Guy Scenario, but the effects of t reaching tout during scenario simulation are outlined here anyway.
For a DI-Guy application:

If the scenario tout is enabled the scenario will stop.
If the scenario tout is disabled the scenario will continue indefinitely, regardless of scenario tout.

Note that no playback looping happens in a DI-Guy application if tout is reached. Only in DI-Guy Scenario does the loop flag have an effect.
For DI-Guy Scenario:

If the loop flag is not set (see set_playback_loop()) or a movie is being recorded, the scenario will stop.
If the loop flag is set, and any character in the scenario has history data (see the History Functions for diguyCharacter), the scenario will be rewound to 0 and play back history data.
If the loop flag is set, but no characters in the scenario have history data, the scenario will be reset to 0 and re-simulate from there.
Arguments:

t desired time in seconds
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguyScenario::update2

Prototype:
int update2(float t, float realtime_t);
Description:

Similar to update(), but the realtime time can be explicitly passed in.
Arguments:

t desired simulation time in seconds
realtime_t elapsed real time in seconds
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguyScenario::set_playback_loop

Prototype:
int set_playback_loop(int playback_loop);
Description:

This function sets whether the scenario is designed to loop at tout. The default is for scenarios to loop.

Note that this has an effect only in DI-Guy Scenario. DI-Guy applications do not use this flag.

See get_playback_loop().
Arguments:

playback_loop pass 1 to have scenario loop at tout, 0 to not
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguyScenario::set_tick_dt

Prototype:
int set_tick_dt(float tick_dt);
Description:

Scenarios progress at discrete time steps, called "ticks". Each tick is of the same duration. This function sets the amount of time each tick takes.

Because changing the tick interval of a scenario changes when event beads occur, any change may introduce subtle differences in scenario playback.

Note that loading a .dss file will change the tick dt, as tick dt is set on a per scenario basis.

The default tick dt of a new scenario is 0.03125 seconds, or 32 frames per second.
Arguments:

tick_dt duration, in seconds, of each scenario tick
Returns:

0 on success, -1 on failure
Callable From:

C++
C++ Example:
    diguyScenario* sc = diguy_create_scenario();
    if (sc)
    {
        sc->load("my_scenario.dss");
        sc->set_tick_dt(0.033333);   // 30 fps
    }

function diguyScenario::get_t

Prototype:
float get_t();
Description:

This function returns the time in seconds that the scenario is currently at. See update().

Note that this value will not necessarily track the t passed in the update() function. This t advances only when the scenario's current tick changes. See set_tick_dt() and update().
Returns:

current time in seconds

function diguyScenario::get_realtime_t

Prototype:
float get_realtime_t();
Description:

This function returns the realtime time in seconds that the scenario is currently at. This may be different than get_desired_t() if the scenario is stopped or the time passed in update() is not tracking realtime.
Returns:

current time in seconds

function diguyScenario::get_desired_t

Prototype:
float get_desired_t();
Description:

This function returns the desired time in seconds that the scenario is currently at. This may be different than get_t(), which advances only when the scenario's current tick changes.
Returns:

current time in seconds

function diguyScenario::set_tout

Prototype:
int set_tout(float tout);
Description:

This function sets the tout ("T Out") time of the scenario. What will happen when the scenario reaches this time depends on a number of factors. See update() for more information.
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguyScenario::get_tout

Prototype:
float get_tout();
Description:

This function returns the tout time of the scenario. This is the time at which a scenario is designed to end.

See set_tout() and update().
Returns:

tout of scenario

function diguyScenario::set_tout_enabled

Prototype:
void set_tout_enabled(int tout_enabled);
Description:

This function sets what will happen when the scenario reaches its tout time. If set to 0, the scenario will ignore the tout time and continue indefinitely.

See update() for more information.

function diguyScenario::get_tout_enabled

Prototype:
int get_tout_enabled();
Description:

This function returns the whether tout is enabled.

See set_tout_enabled() and update().
Returns:

1 if tout enabled, 0 if not

function diguyScenario::get_playback_loop

Prototype:
int get_playback_loop();
Description:

This function returns whether the scenario is designed to loop when the scenario's tout time is reached.

See update() for more information about looping.
Returns:

0 if no loop desired; 1 if loop desired

function diguyScenario::get_tick_dt

Prototype:
float get_tick_dt();
Description:

This function returns the most recent setting of set_tick_dt().

function diguyScenario::get_ticks_can_be_dropped

Prototype:
int get_ticks_can_be_dropped();
Returns:

This function returns the most recent setting of set_ticks_can_be_dropped().

function diguyScenario::set_ticks_can_be_dropped

Prototype:
void set_ticks_can_be_dropped(int ticks_can_be_dropped);
Description:

This function sets whether a scenario can "drop" ticks in order to catch up if it falls behind.

Scenario updates progress in discrete time steps called ticks (see set_tick_dt() and update()). If the difference in times specified in subsequent calls to update() is greater than the tick dt, which can happen if calls to update() are taking too long because the scenario is too complex or if the caller is attempting to "fast forward" to a particular time in the scenario, the scenario may skip processing of intermediate ticks in order to catch up.

The scenario will not consider itself behind until the number of ticks covered by a particular call to update() is equal to or greater than the value set by set_max_ticks_behind_until_drop().

Dropping ticks, while it improves performance, may have unintended side effects, including:

event beads of characters on paths that fall on the dropped ticks -- including aim beads, decision beads, gaze beads, and script beads -- will not be evaluated and will therefore have no effect on the scenario
review playback of characters (see diguyCharacter::set_history_type()) over the dropped intervals will be choppy

Not dropping ticks also has potential side effects:

if a scenario is falling behind more and more on each call to update(), it may never be able to catch up and performance of DI-Guy will increasingly degrade

The default setting is that ticks can be dropped.
Arguments:

ticks_can_be_dropped pass 1 for ticks to be dropped; else pass 0

function diguyScenario::get_max_ticks_behind_until_drop

Prototype:
long get_max_ticks_behind_until_drop();
Returns:

This function returns the most recent setting of set_max_ticks_behind_until_drop().

function diguyScenario::set_max_ticks_behind_until_drop

Prototype:
void set_max_ticks_behind_until_drop(long max_ticks_behind_until_drop);
Description:

This function sets how many ticks a scenario must be behind before it starts dropping ticks in order to catch up.

For a discussion of how a scenario may fall behind, see set_ticks_can_be_dropped().

Note that if ticks cannot be dropped, (e.g., 0 is passed to set_ticks_can_be_dropped()) this function will have no effect.

The default value is 2.
Arguments:

max_ticks_behind_until_drop how many ticks a scenario must be behind until it drops ticks

function diguyScenario::set_playback_mode

Prototype:
int set_playback_mode(diguyScenarioPlaybackMode playback_mode);
Description:

This function sets the current playback mode of DI-Guy Scenario. It currently will have no effect in applications using the DI-Guy API.
Arguments:

playback_mode new playback mode
Returns:

0 on success, -1 on failure

function diguyScenario::set_playback_mode_stop

Prototype:
int set_playback_mode_stop();
Description:

This function is shorthand for the function call set_playback_mode(DIGUY_SCENARIO_PLAYBACK_MODE_STOP). It is useful for pausing the scenario in decisions and decision beads.
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision

function diguyScenario::set_playback_mode_play

Prototype:
int set_playback_mode_play();
Description:

This function is shorthand for the function call set_playback_mode(DIGUY_SCENARIO_PLAYBACK_MODE_PLAY). It is useful for resuming a paused scenario in decisions and decision beads.
Returns:

0 on success, -1 on failure
Callable From:

C++
Script
Decision

function diguyScenario::get_playback_mode

Prototype:
diguyScenarioPlaybackMode get_playback_mode();
Returns:

current playback mode as set by set_playback_mode() or the DI-Guy Scenario user interface

function diguyScenario::derive_playback_mode_dt

Prototype:
float derive_playback_mode_dt(float dt_in);
Description:

This function derives a dt based on an input dt (usually derived from change in realtime from previous to current frame) and the scenario's current playback mode. The resulting dt can then be used to advance the time passed to diguyScenario::update() so that it emulates the effect of the VCR buttons in DI-Guy Scenario.

This function does not change the scenario's current time or playback mode.

Examples based on a dt_in of 0.03 seconds:

DIGUY_SCENARIO_PLAYBACK_MODE_STOP: derived_dt = 0.0
DIGUY_SCENARIO_PLAYBACK_MODE_PLAY: derived_dt = 0.03
DIGUY_SCENARIO_PLAYBACK_MODE_PLAY_REVERSE: derived_dt = -0.03
DIGUY_SCENARIO_PLAYBACK_MODE_FF: derived_dt = 0.12
DIGUY_SCENARIO_PLAYBACK_MODE_FF_REVERSE: derived_dt = -0.12
DIGUY_SCENARIO_PLAYBACK_MODE_SS: derived_dt = frame dt
DIGUY_SCENARIO_PLAYBACK_MODE_SS_REVERSE: derived_dt = - frame dt
DIGUY_SCENARIO_PLAYBACK_MODE_REWIND: derived_dt = - scenario t

Note that the playback mode should be set to DIGUY_SCENARIO_PLAYBACK_MODE_STOP after time advances in either of the single step ("SS") modes or the rewind mode.
Arguments:

dt_in delta time in seconds from advancing simulation time

function diguyScenario::reset

Prototype:
int reset();
Description:

This function resets all scenario characters, signals, variables, and all other scenario objects to their original state. Scenario time will be set to 0.
Returns:

0 on success, -1 on failure

Load and Save Functions

function diguyScenario::load

Prototype:
int load(const char* filename);
Description:

This function loads the specified scenario. Any previously loaded scenario objects will be deleted. To merge a scenario into the existing scenario (load without deleting existing objects), use the call merge().

The passed filename can be either a ".dss" file, which is a DI-Guy Scenario file, or a ".dsr" file, which is a DI-Guy Review file.

Once the file has been loaded an implicit reset() will occur.
Arguments:

filename filename of scenario to be loaded
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguyScenario::save

Prototype:
int save();
Description:

Saves the scenario into its current filename. This filename will be the most recent of:

the filename used in a load() function call
the filename used in a save_as() function call

The filename that will be used can be retrieved using the get_filename() or get_filename_without_directory() functions.

Once saved the "unsaved" flag (as returned by get_unsaved()) will be set to 0.
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguyScenario::save_as

Prototype:
int save_as(const char* filename);
Description:

Similar to save(), but new filename is specified by the filename argument.
Arguments:

filename new filename of scenario
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguyScenario::get_filename

Prototype:
const char* get_filename();
Description:

Returns the most recent of:

the filename used in a load() function call
the filename used in a save_as() function call
Returns:

filename of saved scenario
Callable From:

C++

function diguyScenario::get_filename_without_directory

Prototype:
const char* get_filename_without_directory();
Description:

Similar to get_filename(), but with any leading directories removed.
Callable From:

C++

function diguyScenario::get_unsaved

Prototype:
int get_unsaved();
Returns:

1 if scenario has been modified since save or load, else 0
Callable From:

C++

function diguyScenario::set_unsaved

Prototype:
void set_unsaved(int unsaved);
Description:

Manually sets the "unsaved" flag to the passed value.
Arguments:

unsaved new unsaved status; 1 for unsaved, 0 for saved
Callable From:

C++

Draw Functions

function diguyScenario::draw

Prototype:
int draw();
Description:

This function draws all visible elements of the loaded scenario in immediate mode graphics environments (see below). This is the equivalent of calling draw_pass1(), immediately followed by draw_pass2(), immediately followed by post_draw().

Note that any character graphics culling, far position rendering, etc., depend on the render camera set by the set_render_camera() function. A render camera does not always need to be set; see set_render_camera() for more details.
Returns:

0 on success, -1 on failure
OpenGL Version:
Direct3D Version:

This function immediately draws all scenario elements. Either this function, or draw_pass1(), draw_pass2(), and post_draw(), should be called once per frame.
Callable From:

C++

function diguyScenario::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.
Returns:

0 on success, -1 on failure
OpenGL Version:
Direct3D Version:

This function immediately draws the opaque scenario elements. Either this function or draw() should be called once per frame.
Callable From:

C++

function diguyScenario::draw_pass2

Prototype:
int draw_pass2(int also_call_post_draw = 1);
Description:

Same as draw_pass1(), but draws transparent scenario elements. The also_call_post_draw argument is set to 1 for backwards compatiblity.
Callable From:

C++

function diguyScenario::post_draw

Prototype:
int post_draw(int call_plugins_post_draw = 1,
    int call_lua_packages_draw = 1,
    int call_post_draw_callback = 1);
Description:

This function draws visual elements that must be drawn after the main render has been done.

Note that this function is called automatically by the draw() call. Only call this function if draw() is not called; e.g., if draw_pass1() and draw_pass2() are used.

This function can be called from scene graph type renderers which typically don't need or want to have the draw() function called.
Arguments:

call_plugins_post_draw pass 1 to call plugin post_draw() functions
call_lua_packages_draw pass 1 to call lua package draw functions
call_post_draw_callback pass 1 to invoke callbacks with callback id CALLBACK_ID_POST_DRAW
Returns:

0 on success, -1 on failure

function diguyScenario::set_graphics_attach_ptr

Prototype:
int set_graphics_attach_ptr(void* graphics_attach_ptr);
Description:

This function sets the attachment point that to be used for graphics created by the library.
Arguments:

graphics_attach_ptr this is a pointer to a group-type object; the specific type is dependent on graphics environment
Returns:

0 on success, -1 on failure
OpenGL Version:

This function does not have any effect.
Direct3D Version:

The passed pointer should be a LPDIRECT3DRMFRAME2.
LPDIRECT3DRMFRAME2 attach_frame = get_scene_frame();
scenario->set_graphics_attach_ptr(attach_frame);
Callable From:

C++

Merge Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::create_merge_settings

Prototype:
diguyScenarioMergeSettings* create_merge_settings(diguyScenarioMergeInitialSettings initial_settings = DIGUY_MERGE_INITIAL_SETTINGS_DEFAULT);
Description:

This function creates a merge settings object. This object can allow for fine control over which elements in a scenario are merged during a merge() call, and what to do if there is a collision with an existing element.

Once the initial settings are made based on the initial_settings argument, the settings can be fine-tuned by calling member functions of the diguyScenarioMergeSettings object.

Destroy the object with a call to destroy_merge_settings().
Arguments:

initial_settings what the initial settings should be when the object is created
DIGUY_MERGE_INITIAL_SETTINGS_DEFAULT

scenario settings DIGUY_MERGE_FLAG_DONT_MERGE
current view settings DIGUY_MERGE_FLAG_OVERWRITE_EXISTING
character DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
decision DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
formation DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
group DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
guide DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
info popup DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
library function DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
script DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
sensor region DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
signal DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
variables DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
camera settings DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
face exp DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
fog settings DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
light settings DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
particle system DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
path shape DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
scene object DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
scene object grid DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
sound DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
DIGUY_MERGE_INITIAL_SETTINGS_MERGE_EVERYTHING

scenario settings DIGUY_MERGE_FLAG_OVERWRITE_EXISTING
current view settings DIGUY_MERGE_FLAG_OVERWRITE_EXISTING
character DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
decision DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
formation DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
group DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
guide DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
info popup DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
library function DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
script DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
sensor region DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
signal DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
variables DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
camera settings DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
face exp DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
fog settings DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
light settings DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
particle system DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
path shape DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
scene object DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
scene object grid DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
sound DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
DIGUY_MERGE_INITIAL_SETTINGS_MERGE_NOTHING

scenario settings DIGUY_MERGE_FLAG_DONT_MERGE
current view settings DIGUY_MERGE_FLAG_DONT_MERGE
character DIGUY_MERGE_FLAG_DONT_MERGE
decision DIGUY_MERGE_FLAG_DONT_MERGE
formation DIGUY_MERGE_FLAG_DONT_MERGE
group DIGUY_MERGE_FLAG_DONT_MERGE
guide DIGUY_MERGE_FLAG_DONT_MERGE
info popup DIGUY_MERGE_FLAG_DONT_MERGE
library function DIGUY_MERGE_FLAG_DONT_MERGE
script DIGUY_MERGE_FLAG_DONT_MERGE
sensor region DIGUY_MERGE_FLAG_DONT_MERGE
signal DIGUY_MERGE_FLAG_DONT_MERGE
variables DIGUY_MERGE_FLAG_DONT_MERGE
camera settings DIGUY_MERGE_FLAG_DONT_MERGE
face exp DIGUY_MERGE_FLAG_DONT_MERGE
fog settings DIGUY_MERGE_FLAG_DONT_MERGE
light settings DIGUY_MERGE_FLAG_DONT_MERGE
particle system DIGUY_MERGE_FLAG_DONT_MERGE
path shape DIGUY_MERGE_FLAG_DONT_MERGE
scene object DIGUY_MERGE_FLAG_DONT_MERGE
scene object grid DIGUY_MERGE_FLAG_DONT_MERGE
sound DIGUY_MERGE_FLAG_DONT_MERGE
DIGUY_MERGE_INITIAL_SETTINGS_DIGUY6_COMPATIBLE

scenario settings DIGUY_MERGE_FLAG_OVERWRITE_EXISTING
current view settings DIGUY_MERGE_FLAG_OVERWRITE_EXISTING
character DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
decision DIGUY_MERGE_FLAG_KEEP_BOTH
formation DIGUY_MERGE_FLAG_KEEP_BOTH
group DIGUY_MERGE_FLAG_KEEP_BOTH
guide DIGUY_MERGE_FLAG_KEEP_BOTH
info popup DIGUY_MERGE_FLAG_KEEP_BOTH
library function DIGUY_MERGE_FLAG_KEEP_BOTH
script DIGUY_MERGE_FLAG_KEEP_BOTH
sensor region DIGUY_MERGE_FLAG_KEEP_BOTH
signal DIGUY_MERGE_FLAG_KEEP_BOTH
variables DIGUY_MERGE_FLAG_KEEP_BOTH
camera settings DIGUY_MERGE_FLAG_KEEP_BOTH
face exp DIGUY_MERGE_FLAG_KEEP_BOTH
fog settings DIGUY_MERGE_FLAG_KEEP_BOTH
light settings DIGUY_MERGE_FLAG_KEEP_BOTH
particle system DIGUY_MERGE_FLAG_KEEP_EXISTING_ONLY_AND_WARN
path shape DIGUY_MERGE_FLAG_KEEP_BOTH
scene object DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
scene object grid DIGUY_MERGE_FLAG_KEEP_BOTH
sound DIGUY_MERGE_FLAG_KEEP_BOTH
Returns:

object of type diguyScenarioMergeSettings

function diguyScenario::destroy_merge_settings

Prototype:
void destroy_merge_settings(diguyScenarioMergeSettings* merge_settings);
Description:

This function destroys a merge settings object created by a call to create_merge_settings().

function diguyScenario::merge

Prototype:
int merge(const char* filename,
    diguyScenarioMergeSettings* merge_settings = NULL);
Description:

This function merges the specified scenario. Any previously loaded scenario elements will be retained, depending on settings in the merge_settings argument.
Arguments:

filename filename of scenario to be merged
merge_settings object that controls how elements are merged; pass NULL for default merge handling
Returns:

0 on success, -1 on failure

function diguyScenario::merge_object

Prototype:
int merge_object(const char* string);
Description:

This function performs a "micro merge", allowing a scenario to merge in the contents of a text string representing a single object.

On example of use is for a Lua Package to contain a number of text strings representing particle systems or sounds that an agent need will need. When needed objects in text form can be merged into the scenario using this function.

The DI-Guy Scenario Particle System page has a "Display Object Text" button that can display the object text of a particle system that is appropriate for use by this function. Other object pages that have this button are Sound, Formation, and Crowd Profile.

Text can also be taken directly from .dss files.

See also the diguyCharacter::merge_object() function.

Note: the parser is very sensitive to tabs and formatting!

function diguyScenario::include_object_library

Prototype:
int include_object_library(const char* library_name);
Description:

This function makes the objects in the specified library available for use in the scenario.

Object libraries allow new content to be created in one scenario and automatically shared to other scenarios. When including a library, objects that are already in the scenario are preserved.

A library with specified name must be available for inclusion. Object libraries are located in the $(DIGUY)configdiguy/object_libraries and $(DIGUY)customconfigdiguyobject_libraries directories. The filename for the library must be "library_[libname].cfg".

Available object libraries in these directories will automatically be detected by the scenario, but objects in the libraries will not be included in the scenario until this function is called.

For example, if the objects in the file "library_crowd_sounds.cfg" should be made available in the scenario, the library name "crowd_sounds" should be passed into this function.

Currently the following object types can be in libraries:

particle system
formation
crowd profile
sound
Arguments:

library_name name of library
Returns:

0 on success, -1 on failure

function diguyScenario::uninclude_object_library

Prototype:
int uninclude_object_library(const char* library_name);
Description:

This function is the opposite of include_object_library(). Objects in the named library are made unavailable to the scenario.
Arguments:

library_name name of library
Returns:

0 on success, -1 on failure

Time and Date Functions

Unless otherwise specified, callable from:

C++
Script

Datetime Functions

function diguyScenario::set_base_datetime

Prototype:
void set_base_datetime(int year = -1,
    int month  = -1,
    int day    = -1,
    int hour   = -1,
    int minute = -1,
    int second = -1,
    int msec   = -1);
Description:

This function will set what the current datetime will be when the scanario is reset.

Pass -1 for values that should be set based on current datetime.

Note that if set_base_datetime_default_to_now() and set_base_datetime_default_to_today() can override these values.

function diguyScenario::set_base_datetime

Prototype:
void set_base_datetime(const char* datetime_string,
    const char* format);
Description:

Similar to set_base_datetime(), but datetime is stored in the passed string, formatted in the passed format string.

function diguyScenario::get_base_datetime

Prototype:
void get_base_datetime(int* year = NULL,
    int* month  = NULL,
    int* day    = NULL,
    int* hour   = NULL,
    int* minute = NULL,
    int* second = NULL,
    int* msec   = NULL);
Description:

Retrieves the base datetime. Pass NULL for arguments that aren't needed.

function diguyScenario::set_base_datetime_default_to_now

Prototype:
void set_base_datetime_default_to_now(int to_now);
Description:

Setting this value to 1 will cause the time part of the datetime to be set to whatever "real" time it is when reset() is called, instead of the time stored in the base datetime as set by set_base_datetime(). For example, if it is 10:30 AM in "real time" when the scenario is reset, the current time will be set to 10:30:00:000 on reset.

Setting this value to 0 will restore the default behavior.

function diguyScenario::get_base_datetime_default_to_now

Prototype:
int get_base_datetime_default_to_now();
Returns:

1 if the current time will be set to the "real time" on reset, 0 is not

function diguyScenario::set_base_datetime_default_to_today

Prototype:
void set_base_datetime_default_to_today(int to_today);
Description:

Similar to set_base_datetime_default_to_now(), but for the date part of the datetime.

function diguyScenario::get_base_datetime_default_to_today

Prototype:
int get_base_datetime_default_to_today();
Returns:

1 if the current date will be set to the "real date" on reset, 0 is not

function diguyScenario::set_current_datetime

Prototype:
void set_current_datetime(int year = -1,
    int month  = -1,
    int day    = -1,
    int hour   = -1,
    int minute = -1,
    int second = -1,
    int msec   = -1);
Description:

Allows current datetime to be explicitly set. Note that in most cases the current datetime should be set by the base datetime plus how much time has advanced in the scenario.

This function can be useful if the datetime needs to be syncronized with that from another source, say, from network exercise data.

function diguyScenario::set_current_datetime

Prototype:
void set_current_datetime(const char* datetime_string,
    const char* format);
Description:

Similar to set_current_datetime(), but datetime is stored in the passed string, formatted in the passed format string.

function diguyScenario::get_current_datetime

Prototype:
void get_current_datetime(int* year = NULL,
    int* month  = NULL,
    int* day    = NULL,
    int* hour   = NULL,
    int* minute = NULL,
    int* second = NULL,
    int* msec   = NULL);
Description:

Retrieves the current datetime. Pass NULL for arguments that aren't needed.

function diguyScenario::get_current_datetime_string

Prototype:
const char* get_current_datetime_string(const char* format);
Description:

Retrieves the current datetime in string format.
Arguments:

format format returned string should be in; pass NULL for default "Mdyyyy h:mm:ss AP" format

function diguyScenario::set_datetimes_are_utc

Prototype:
void set_datetimes_are_utc(int are_utc);
Description:

Pass 1 to specify that datetimes use UTC time, 0 to specify they are local time.

function diguyScenario::get_datetimes_are_utc

Prototype:
int get_datetimes_are_utc();
Returns:

1 if datetimes use UTC time, 0 if not

function diguyScenario::set_utc_offset_hours

Prototype:
void set_utc_offset_hours(float utc_offset_hours);
Description:

If datetimes use UTC time, this function sets the offset hours of the current time from UTC.

function diguyScenario::get_utc_offset_hours

Prototype:
float get_utc_offset_hours();
Returns:

offset in hours of datetimes from UTC

function diguyScenario::set_use_local_tz_utc_offset_hours

Prototype:
void set_use_local_tz_utc_offset_hours(int use_local_tz);
Description:

Documentation Pending

function diguyScenario::get_use_local_tz_utc_offset_hours

Prototype:
int get_use_local_tz_utc_offset_hours();
Description:

Documentation Pending

function diguyScenario::set_current_datetime_advance_method

Prototype:
void set_current_datetime_advance_method(diguyDatetimeAdvanceMethod advance_method);
Description:

Documentation Pending

function diguyScenario::get_current_datetime_advance_method

Prototype:
diguyDatetimeAdvanceMethod get_current_datetime_advance_method();
Description:

Documentation Pending

function diguyScenario::set_current_datetime_advance_factor

Prototype:
void set_current_datetime_advance_factor(float advance_factor);
Description:

Documentation Pending

function diguyScenario::get_current_datetime_advance_factor

Prototype:
float get_current_datetime_advance_factor();
Description:

Documentation Pending

function diguyScenario::get_network_datetime

Prototype:

void get_network_datetime(int* year = NULL,
    int* month  = NULL,
    int* day    = NULL,
    int* hour   = NULL,
    int* minute = NULL,
    int* second = NULL,
    int* msec   = NULL);

Description:

Documentation Pending

Simple Time Functions

function diguyScenario::set_tin_time_of_day

Prototype:
int set_tin_time_of_day(float t);
Description:

This function sets the time of day which corresponds to scenario tin. It is a wall-clock time, and has no date content.

Note that if more detailed time and date information is needed refer to the "datetime" functions.
Arguments:

t number of seconds after midnight; zero means midnight; 86399.0 means 11:59:59 pm
Returns:

0 on success, -1 on failure

function diguyScenario::get_tin_time_of_day

Prototype:
float get_tin_time_of_day();
Description:

This function returns what time of day corresponds to scenario tin. It is a wall-clock time, and has no date content.

See set_tin_time_of_day().

Note that if more detailed time and date information is needed refer to the "datetime" functions.
Returns:

number of seconds after midnight

function diguyScenario::get_time_of_day

Prototype:
float get_time_of_day();
Description:

This function returns what the simulated time of day is right now. It is computed by adding (scenario t - tin) to the value passed to set_tin_time_of_day();

See set_tin_time_of_day().

Note that if more detailed time and date information is needed refer to the "datetime" functions.
Returns:

number of seconds after midnight (simulated time of day)

Appearance Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::add_appearance

Prototype:
int add_appearance(const char* appearance,
    char** equipment_list,
    char** character_types,
    const char* actor);
Description:

This function adds an appearance with the given name to the list of available appearances. If an appearance with the given name already exists the operation will fail and a message will be printed at debug level to the output log.

Internal copies are made of the passed strings.
Arguments:

appearance name of the appearance
equipment_list NULL-terminated list of equipment that makes up the appearance
character_types NULL-terminated list of character types that this appearance will be available to
actor name of the actor this appearance fits

If NULL is passed for the actor argument the actor will be set to match the actor of the first character type in the character_types array.
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguyScenario::add_appearance_based_on_existing_appearance

Prototype:
int add_appearance_based_on_existing_appearance(const char* appearance,
    const char* existing_appearance,
    char** equipment_list);
Description:

This function is similar to add_appearance(), but adds equipment_list shapes to an existing appearance.

The character types that the new appearance will be available to will match that of the specified existing appearance.
Arguments:

appearance name of the new appearance
existing_appearance name of the existing appearance on which to base new appearance
equipment_list NULL-terminated list of equipment to add to

the existing appearance
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguyScenario::remove_appearance

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

This function removes an appearance with the given name from the list of available appearances. If an appearance with the given name does not exist the operation will fail and a message will be printed at debug level to the output log.
NOTE:

Currently no check is made for whether the appearance is in use by a character. Removing an in-use appearance will result in undefined behavior.
Arguments:

appearance name of the appearance
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguyScenario::get_num_character_types_with_appearance

Prototype:
int get_num_character_types_with_appearance(const char* appearance_name);
Description:

This function returns the number of character types associated with the given appearance, if any.
Arguments:

appearance name of the appearance
Returns:

the number of character types, or 0

function diguyScenario::get_character_type_from_appearance

Prototype:
const char *get_character_type_from_appearance(const char* appearance_name, int index = 0);
Description:

This function returns one of the character types associated with the appearance, if any exists
Arguments:

appearance name of the appearance
index which character type of the set to return
Returns:

a character type name on success, "none" on failure

Preload Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::preload_character_type

Prototype:
int preload_character_type(const char* character_type);
Description:

This function preloads all base motions and the default appearance for the specified character type.

This can be done during initialization to preload characters that will be needed later in a scenario, to avoid a hitch in frame rate when the characters are loaded.
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
Returns:

0 on success, -1 on failure

function diguyScenario::preload_appearance

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

This function preloads all geometry for the specified appearance. This can be done during initialization to preload geometry that will be needed later in a scenario, to avoid a hitch in frame rate when the geometry is loaded.
Arguments:

appearance name of the appearance whose geometry is to be preloaded
Returns:

0 on success, -1 on failure

function diguyScenario::preload_gesture

Prototype:
int preload_gesture(const char* character_type, const char* gesture_name);
Description:

This function preloads all motions for the specified gesture for the specified character type.

This can be done during initialization to preload gestures that will be needed later in a scenario, to avoid a hitch in frame rate when the motions are loaded.
Arguments:

character_type character's type
gesture_name name of the gesture to preload
Returns:

0 on success, -1 on failure

Culling Functions

These functions control culling of various object types.

Note that these functions only work only in the OpenGL version, when a valid render camera is set. See set_render_camera().

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::set_character_culling_enabled

Prototype:
void set_character_culling_enabled(int character_culling);
Description:

This function enables character culling.

This function works only in the OpenGL version when a valid render camera is set.

function diguyScenario::get_character_culling_enabled

Prototype:
int get_character_culling_enabled();
Description:

This function gets the state of character culling.

This function works only in the OpenGL version when a valid render camera is set.
Returns:

1 if enabled, 0 if disabled.

function diguyScenario::set_scene_object_culling_enabled

Prototype:
void set_scene_object_culling_enabled(int object_culling);
Description:

This function enables scene object culling.

This function works only in the OpenGL version when a valid render camera is set.

function diguyScenario::get_scene_object_culling_enabled

Prototype:
int  get_scene_object_culling_enabled();
Description:

This function get the state of scene object culling.

This function works only in the OpenGL version when a valid render camera is set.
Returns:

1 if enabled, 0 if disabled

function diguyScenario::set_scene_object_sub_culling_enabled

Prototype:
void set_scene_object_sub_culling_enabled(int object_culling);
Description:

This function enables scene object sub object culling.

This function works only in the OpenGL version when a valid render camera is set.

function diguyScenario::get_scene_object_sub_culling_enabled

Prototype:
int  get_scene_object_sub_culling_enabled();
Description:

This function get the state of scene object sub culling.

This function works only in the OpenGL version when a valid render camera is set.
Returns:

1 if enabled, 0 if disabled

function diguyScenario::set_character_visualize_bounds_enabled

Prototype:
void set_character_visualize_bounds_enabled(int visualize_bounds);
Description:

This function enables visualizing a character's bounding volume.

This function works only in the OpenGL version when a valid render camera is set.

function diguyScenario::get_character_visualize_bounds_enabled

Prototype:
int  get_character_visualize_bounds_enabled();
Description:

This function get the state of character bounding volume visualization.

This function works only in the OpenGL version when a valid render camera is set.
Returns:

1 if enabled, 0 if disabled

function diguyScenario::set_scene_object_visualize_bounds_enabled

Prototype:
void set_scene_object_visualize_bounds_enabled(int val);
Description:

This function enables visualizing a scene object's bounding volume.

This function works only in the OpenGL version when a valid render camera is set.

function diguyScenario::get_scene_object_visualize_bounds_enabled

Prototype:
int  get_scene_object_visualize_bounds_enabled();
Description:

This function gets the state of scene objects bounding volume visualization.

This function works only in the OpenGL version when a valid render camera is set.
Returns:

1 if enabled, 0 if disabled

Query Functions

These functions query the scenario for what specific types of scenario elements are available. This includes:

character types
appearances
actions

Unless otherwise specified, callable from:

C++
Script

C++ Example:

int num_character_types = diguy_scenario->get_num_character_types();
int character_type_index;
for (character_type_index = 0;
    character_type_index < num_character_types;
    character_type_index++)
{
    const char* character_type = diguy_scenario->get_character_type_at_index(character_type_index);
    bdi_log_printf(BDI_LOG_INFO, "Character type at index %d: %s\n",
        character_type_index,
        character_type);

    int num_appearances = diguy_scenario->get_character_type_num_appearances(character_type);
    int appearance_index;
    for (appearance_index = 0;
        appearance_index < num_appearances;
        appearance_index++)
    {
        const char* appearance = diguy_scenario->get_character_type_appearance_at_index(character_type,
            appearance_index);
        bdi_log_printf(BDI_LOG_INFO, "\tAppearance at index %d: %s\n",
            appearance_index,
            appearance);
    }

    int num_actions = diguy_scenario->get_character_type_num_actions(character_type);
    int action_index;
    for (action_index = 0;
        action_index < num_actions;
        action_index++)
    {
        const char* action_name = diguy_scenario->get_character_type_action_at_index(character_type,
            action_index);
        bdi_log_printf(BDI_LOG_INFO, "\tAction at index %d: %s\n",
            action_index,
            action_name);
    }
}

function diguyScenario::get_num_character_types

Prototype:
int get_num_character_types();
Returns:

number of available character types

function diguyScenario::get_character_type_at_index

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

the string identifying the character type at the given index
Arguments:

index index of the character type; indices start at 0

function diguyScenario::get_character_type_abbreviation

Prototype:
const char* get_character_type_abbreviation(const char* character_type);
Returns:

abbreviation of the given character type, when a shorter identifier is needed
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example

function diguyScenario::get_character_type_deprecated_at_version

Prototype:
const char* get_character_type_deprecated_at_version(const char* character_type);
Description:

This function returns the version at which the specified character type was deprecated.

If the character type has not been deprecated, the empty string ("") is returned.
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
Returns:

version at which character became deprecated; empty string ("") if it hasn't been
C++ Example:
const char* version = scenario->get_character_type_deprecated_at_version();
if (strlen(version) > 0)
{
    // do something
}

function diguyScenario::get_character_type_deprecated_suggested_alternatives

Prototype:
const char* get_character_type_deprecated_suggested_alternatives(const char* character_type);
Description:

This function returns the suggested character type(s) that are recommended for deprecated character types.

If the character type has not been deprecated, the empty string ("") is returned.

If there is more than one suggested alternative, they will be separated by spaces.
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
Returns:

suggested replacement character type(s)
C++ Example:
const char* alternatives = scenario->get_character_type_deprecated_suggested_alternatives();
if (strlen(version) > 0)
{
    // do something
}

function diguyScenario::get_character_type_quality_bias

Prototype:
int get_character_type_quality_bias(const char* character_type);
Description:

As the number of character types DI-Guy provides has grown, newer character types tend to be better than older ones. This can be because of a greater selection of actions, better quality motions, and other factors.

This function returns a value representing a qualitative "bias" of this character they relative to other character types. The higher the bias, the more recommended the character type is. A bias of 1 means strongly not recommended, 5 means average, 10 means highly recommended.
Returns:

quality bias, a unitless value from 1 to 10
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example

function diguyScenario::get_character_type_map

Prototype:
diguyCharacterTypeMap* get_character_type_map(const char* character_type);
Description:

This function returns the type map of the specified character type. See the documentation for diguyCharacterTypeMap for what this information means.

Only the character type fields will have useful information; the appearance fields will contain default wildcard values.
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
Returns:

pointer to type diguyCharacterTypeMap; will never be NULL

function diguyScenario::get_character_type_default_appearance

Prototype:
const char* get_character_type_default_appearance(const char* character_type);
Returns:

default appearance of the specified character type
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example

function diguyScenario::get_character_type_default_skinned_appearance

Prototype:
const char* get_character_type_default_skinned_appearance(const char* character_type);
Returns:

default skinned appearance of the specified character type
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example

function diguyScenario::get_character_type_num_appearances

Prototype:
int get_character_type_num_appearances(const char* character_type);
Returns:

number of available appearances for the given character type
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example

function diguyScenario::get_character_type_appearance_at_index

Prototype:
const char* get_character_type_appearance_at_index(const char* character_type,
    int index);
Returns:

the string identifying the appearance at the given index for the specified character type
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
index index of the appearance; indices start at 0

function diguyScenario::get_character_type_num_head_appearances

Prototype:
int get_character_type_num_head_appearances(const char* character_type);
Similar to get_character_type_num_appearances(), but for head appearances.

function diguyScenario::get_character_type_head_appearance_at_index

Prototype:
const char* get_character_type_head_appearance_at_index(const char* character_type,
    int index);
Similar to get_character_type_appearance_at_index(), but for head appearances.

function diguyScenario::get_character_type_num_actions

Prototype:
int get_character_type_num_actions(const char* character_type);
Returns:

number of available actions for the given character type
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example

function diguyScenario::get_character_type_action_at_index

Prototype:
const char* get_character_type_action_at_index(const char* character_type,
    int index);
Returns:

the string identifying the action at the given index for the specified character type
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
index index of the action name; indices start at 0

function diguyScenario::get_character_type_action_speed

Prototype:
float get_character_type_action_speed(const char* character_type,
    const char* action_name);
Returns:

the average speed of the specified action for the specified character type
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
action_name the action to query

function diguyScenario::get_character_type_action_duration

Prototype:
float get_character_type_action_duration(const char* character_type,
    const char* action_name);
Returns:

the duration of one rep of the specified action for the specified character type
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
action_name the action to query

function diguyScenario::get_character_type_action_distance

Prototype:
float get_character_type_action_distance(const char* character_type,
    const char* action_name);
Returns:

the distance covered by one rep of the specified action for the specified character type
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
action_name the action to query

function diguyScenario::get_character_type_action_direction

Prototype:
diguyMotionDirection get_character_type_action_direction(
    const char* character_type,
    const char* action_name);
Returns:

the diguyMotionDirection identifying the direction of travel of the specified action for the specified character type
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
action_name the action to query

function diguyScenario::get_character_type_action_facing_angle_in

Prototype:
float get_character_type_action_facing_angle_in(const char* character_type,
    const char* action_name);
Returns:

the facing angle at the start of each repetition of the specified action for the specified character type, in degrees
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
action_name the action to query

function diguyScenario::get_character_type_action_facing_angle_out

Prototype:
float get_character_type_action_facing_angle_out(const char* character_type,
    const char* action_name);
Returns:

the facing angle at the end of each repetition of the specified action for the specified character type, in degrees
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
action_name the action to query

function diguyScenario::get_character_type_num_gestures

Prototype:
int get_character_type_num_gestures(const char* character_type);
Returns:

the number of gestures available to the specified character type
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example; pass "all" to get all gestures available, regardless of character type

function diguyScenario::get_character_type_gesture_at_index

Prototype:
const char* get_character_type_gesture_at_index(const char* character_type,
    int index);
Returns:

the name of the gesture available to the specified character type at the specified index
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example; pass "all" to get all gestures available, regardless of character type
index index of the gesture; indices start at 0

Character Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::create_character

Prototype:
diguyCharacter* create_character(const char* name,
    const char* character_type,
    const char* appearance = NULL);
Description:

This function creates a new character and returns a pointer to it.

The function preload_character_type() should be called at the beginning of a scenario in which this call will be made to avoid a hitch in frame rate.

See also retrieve_character_from_recycle_bin() for a potentially faster way of creating a character.
Arguments:

name name of the new character
character_type character's type
appearance base appearance of character; pass NULL to use default appearance
Returns:

pointer of type diguyCharacter; NULL if creation failed

function diguyScenario::create_temporary_character

Prototype:
diguyCharacter* create_temporary_character(const char* name,
    const char* character_type,
    const char* appearance = NULL);
Description:

This function is very similar to create_character(), but the character created is temporary.

Temporary characters will be destroyed automatically when the scenario is reset, and are not saved in .dss files. They are commonly used for projectiles, effects, and other objects that can come and go multiple times.

Temporary characters can be destroyed before scenario reset by calling destroy_character(), and can be sent to the character recycle bin by calling send_character_to_recycle_bin().
Arguments:

name name of the new character
character_type character's type
appearance base appearance of character; pass NULL to use default appearance
Returns:

pointer of type diguyCharacter; NULL if creation failed

function diguyScenario::destroy_character

Prototype:
int destroy_character(diguyCharacter* character);
Description:

This function destroys a character.

If a character of the same character type and appearance may be needed later in the scenario, consider using send_character_to_recycle_bin() instead. Characters can be retrieved from the recycle bin more quickly than creating them "from scratch" with create_character().
Arguments:

character pointer to a diguyCharacter
Returns:

0 on success, -1 on failure
DI-Guy Networking Notes:

This function should not be called on characters that are reflected network characters. Such characters are destroyed automatically by DI-Guy Networking.

function diguyScenario::send_character_to_recycle_bin

Prototype:
int send_character_to_recycle_bin(diguyCharacter* character);
Description

This function is an alternative way of removing a character from the scenario. When a character is recycled it is removed from the scenario's list of active characters, but the memory associated with it is not freed. Instead, the character is placed in a "character recycle bin" from which it may be later retrieved with a call to retrieve_character_from_recycle_bin().

For an application that is creating and destroying a lot of characters with the same character types and appearances, this can avoid performance hiccups that happen when memory is allocated for new characters.

If it is known ahead of time what types and appearances of characters will be needed in the future, the recycle bin can be "pre-stocked" at scenario load time by first creating and then recycling a large number of characters all at once.
Returns:

0 on success, -1 on failure

function diguyScenario::retrieve_character_from_recycle_bin

Prototype:
diguyCharacter* retrieve_character_from_recycle_bin(const char* name,
    const char* character_type,
    const char* appearance,
    int make_character_temporary = 0);
Description

This function is an alternative way of creating a character. The character recycle bin is checked for a recycled character whose character type and appearance match that requested by this call. Characters are sent to the recycle bin by a call to send_character_to_recycle_bin().

If a match is found the recycled character will be removed from the recycle bin, given the passed name, and placed in the scenario's list of characters, for the most part just as if the character had been created by a call to create_character(). Some things such as position, current action, etc., may need to be immediately set.

If a match is not found, this function returns NULL and a call to create_character() must be made instead.
Arguments:

name new name for the character retrieved from bin
character_type the character type to retrieve from the bin
appearance the appearance to retrieve from the bin, pass NULL or "default" to retrieve the default appearance
make_character_temporary pass 1 to make character temporary, 0 to leave permanent
Returns:

0 on success, -1 on failure

function diguyScenario::get_num_characters

Prototype:
int get_num_characters();
Returns:

number of characters in the scenario

function diguyScenario::get_character_at_index

Prototype:
diguyCharacter* get_character_at_index(int index);
Returns:

pointer of type diguyCharacter; NULL if no character at the specified index
Arguments:

index index of the character; indices start at 0

function diguyScenario::find_character

Prototype:
diguyCharacter* find_character(const char* name);
Description:

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

name name of character to be found
Returns:

pointer of type diguyCharacter; NULL if not found

function diguyScenario::look_at_character

Prototype:
void look_at_character(diguyCharacter* character);
Description:

This function changes the scenario camera's position and fix point so it will be looking at the specified character.

function diguyScenario::this_character

Prototype:
diguyCharacter* this_character();
Description:

This function returns a pointer to the target character of an event bead.
Returns:

pointer of type diguyCharacter; NULL if no current character

function diguyScenario::this_event_bead

Prototype:
diguyCharacterPathEvent* this_event_bead();
Description:

This function returns a pointer to the current event bead.
Returns:

pointer of type diguyCharacterPathEvent; NULL if no current event bead

Path Shape Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_num_path_shapes

Prototype:
int get_num_path_shapes();
Returns:

number of path shapes in the scenario

function diguyScenario::get_path_shape_at_index

Prototype:
diguyPathShape* get_path_shape_at_index(int index);
Returns:

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

index index of the path shape; indices start at 0

function diguyScenario::get_current_path_shape

Prototype:
diguyPathShape* get_current_path_shape();
Returns:

pointer of type diguyPathShape; NULL if no path shape at the specified index

function diguyScenario::find_path_shape

Prototype:
diguyPathShape* find_path_shape(const char* name);
Description:

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

name name of path shape to be found
Returns:

pointer of type diguyPathShape; NULL if not found

function diguyScenario::create_path_shape

Prototype:
diguyPathShape* create_path_shape(const char* name);
Description:

This function creates a new path shape and returns a pointer to it.
Arguments:

name name of the new path shape
Returns:

pointer of type diguyPathShape; NULL if creation failed

function diguyScenario::copy_path_shape

Prototype:
diguyPathShape* copy_path_shape(diguyPathShape* existing_path_shape,
    const char* name);
Description:

This function creates a new path shape based on an existing path shape and returns a pointer to it.
Arguments:

existing_path_shape pointer to diguyPathShape to be copied
name name of the new path shape
Returns:

pointer of type diguyPathShape; NULL if creation failed

function diguyScenario::destroy_path_shape

Prototype:
int destroy_path_shape(diguyPathShape* path_shape);
Description:

This function destroys a path shape.
Arguments:

path_shape pointer to a diguyPathShape
Returns:

0 on success, -1 on failure

Waypoint Functions

function diguyScenario::create_waypoint

Prototype:
diguyWaypoint* create_waypoint(float x = 0.0f, float y = 0.0f, float z = 0.0f,
    float yaw = 0.0f, float roll = 0.0f, float pitch = 0.0f,
    float weight_in = DIGUY_DEFAULT_FLOAT,
    float weight_out = DIGUY_DEFAULT_FLOAT);
Description:

This function creates a new waypoint that can be used for creating new paths and path shapes.

The returned pointer must be destroyed using destroy_waypoint(). The scenario keeps no record of waypoints created with this function.

The weights of the waypoint control how long the "control handles" of the waypoint are, in meters. The longer the control handle, the more the path will be stretched in the direction of the waypoint's orientation.

Unless otherwise specified, callable from:

C++
Script
Arguments:

tx, ty, tz position in meters from the origin
rz, rx, ry orientations in degrees counter-clockwise from the positive X axis
weight_in how much influence this waypoint exerts over the path curve entering this waypoint
weight_out how much influence this waypoint exerts over the path curve leaving this waypoint

By default, weight_in will be set to 1, and weight_out will be coupled to weight_in so that changes to one will affect the other. See diguyWaypoint::set_weight_in(). If a non-default value is passed for weight_out the weights of the waypoint will not be coupled.
Returns:

pointer to type diguyWaypoint

function diguyScenario::destroy_waypoint

Prototype:
int destroy_waypoint(diguyWaypoint* waypoint);
Description:

This function destroys a waypoint created by create_waypoint(). Path shapes created using this waypoint will not be affected; they make internal copies of the waypoints that are used to create them.

Do not call this function on waypoints not created by create_waypoint()! e.g., a waypoint returned by a call to diguyCharacterPath::get_waypoint_at_index().
Arguments:

waypoint waypoint to destroy
Returns:

0 on success, -1 on failure

Character Type Map Functions

See the top-level description of the diguyCharacterTypeMap for extensive information about character type maps.

See the DIGuyDigest programming example for examples on how to use these functions.

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_nearest_character_type_map

Prototype:

diguyCharacterTypeMap* get_nearest_character_type_map(
    diguyCharacterTypeMapField field1, const char* field1_value, const char* field1_alternate_value,
    diguyCharacterTypeMapField field2 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field2_value = NULL, const char* field2_alternate_value = NULL,
    diguyCharacterTypeMapField field3 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field3_value = NULL, const char* field3_alternate_value = NULL,
    diguyCharacterTypeMapField field4 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field4_value = NULL, const char* field4_alternate_value = NULL,
    diguyCharacterTypeMapField field5 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field5_value = NULL, const char* field5_alternate_value = NULL,
    diguyCharacterTypeMapField field6 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field6_value = NULL, const char* field6_alternate_value = NULL,
    diguyCharacterTypeMapField field7 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field7_value = NULL, const char* field7_alternate_value = NULL,
    diguyCharacterTypeMapField field8 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field8_value = NULL, const char* field8_alternate_value = NULL);

Description:

This function searches DI-Guy's available character types and appearances for the closest match to the specified fields and values. See the documentation for diguyCharacterTypeMap for information on what fields are available, and what values they may take.

Arguments:

field1 field in type map to check
field1_value value to check for
field1_alternate_value acceptable alternate value

(Arguments for fields 2 through 8 are the same.)

Returns:

pointer to type diguyCharacterTypeMap

function diguyScenario::get_nearest_character_type_map_using_field_strings

Prototype:

diguyCharacterTypeMap* get_nearest_character_type_map_using_field_strings(
    const char* field1_string, const char* field1_value, const char* field1_alternate_value,
    const char* field2_string = NULL, const char* field2_value = NULL, const char* field2_alternate_value = NULL,
    const char* field3_string = NULL, const char* field3_value = NULL, const char* field3_alternate_value = NULL,
    const char* field4_string = NULL, const char* field4_value = NULL, const char* field4_alternate_value = NULL,
    const char* field5_string = NULL, const char* field5_value = NULL, const char* field5_alternate_value = NULL,
    const char* field6_string = NULL, const char* field6_value = NULL, const char* field6_alternate_value = NULL,
    const char* field7_string = NULL, const char* field7_value = NULL, const char* field7_alternate_value = NULL,
    const char* field8_string = NULL, const char* field8_value = NULL, const char* field8_alternate_value = NULL);

Description:

Same as above, but fields to check are specified by string name instead of enumeration value.

function diguyScenario::get_nearest_character_type_map_id_match

Prototype:
diguyCharacterTypeMap* get_nearest_character_type_map_id_match(const char* type_map_id);
Description:

Same as above, but field values to match against are specified by the given type map id. No alternate values can be provided, though wildcards can be used by putting a "*" in for a field.

function diguyScenario::get_num_character_type_map_entries

Prototype:
int get_num_character_type_map_entries();
Description:

This function returns the total number of type map entries that are in DI-Guy. It is against these entries that matches will be made.

This function, along with get_character_type_map_entry_at_index(), enables all type map information to be queried.
Returns:

number of total type map entries against which matches will be made

function diguyScenario::get_character_type_map_entry_at_index

Prototype:
diguyCharacterTypeMap* get_character_type_map_entry_at_index(int index);
Returns:

type map entry at specified index; see get_num_character_type_map_entries()

function diguyScenario::get_num_type_map_character_classes

Prototype:
int get_num_type_map_character_classes();
Description:

This function returns the total number of values that may be specified or returned in the character class field.

This function, along with get_type_map_character_class_at_index(), enables all available character classes to be queried.
Returns:

number of character classes

function diguyScenario::get_type_map_character_class_at_index

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

character class field value at specified index; see get_num_type_map_character_classes()

function diguyScenario::get_num_type_map_categories

Prototype:
int get_num_type_map_categories(const char* character_class);
Description:

This function returns the total number of values that may be specified or returned in the category field of a type map with the given character class.

This function, along with get_type_map_category_at_index(), enables all available categories available to each character class to be queried.
Returns:

number of categories

function diguyScenario::get_type_map_category_at_index

Prototype:
const char* get_type_map_category_at_index(const char* character_class,
    int index);
Returns:

category field value at specified index; see get_num_type_map_categories()

function diguyScenario::get_num_type_map_subcategories

Prototype:
int get_num_type_map_subcategories(const char* character_class,
    const char* category);
Description:

This function returns the total number of values that may be specified or returned in the subcategory field of a type map with the given character class and category.

This function, along with get_type_map_subcategory_at_index(), enables all available subcategories available to each character class and category to be queried.
Returns:

number of subcategories

function diguyScenario::get_type_map_subcategory_at_index

Prototype:
const char* get_type_map_subcategory_at_index(const char* character_class,
    const char* category,
    int index);
Returns:

subcategory field value at specified index; see get_num_type_map_subcategories()

Signal Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_num_signals

Prototype:
int get_num_signals();
Returns:

number of signals in the scenario

function diguyScenario::get_signal_at_index

Prototype:
diguySignal* get_signal_at_index(int index);
Returns:

pointer of type diguySignal; NULL if no signal at the specified index
Arguments:

index index of the signal; indices start at 0

function diguyScenario::find_signal

Prototype:
diguySignal* find_signal(const char* name);
Description:

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

name name of signal to be found
Returns:

pointer of type diguySignal; NULL if not found

function diguyScenario::create_signal

Prototype:
diguySignal* create_signal(const char* name);
Description:

This function creates a new signal and returns a pointer to it.
Arguments:

name name of the new signal
Returns:

pointer of type diguySignal

function diguyScenario::destroy_signal

Prototype:
int destroy_signal(diguySignal* signal);
Description:

This function destroys a signal.
Arguments:

signal pointer to a diguySignal
Returns:

0 on success, -1 on failure

function diguyScenario::reset_signals

Prototype:
void reset_signals();
Description:

This function resets all signals in the scenario.

function diguyScenario::signal_palette_hide_all

Prototype:
int signal_palette_hide_all(const char* filter = NULL);
Description:

This function hides all signals in the signal palette.
Arguments:

filter optional filter, will only hide signals tagged with info_text equaling filter

function diguyScenario::signal_palette_show_all

Prototype:
int signal_palette_show_all(const char* filter = NULL);
Description:

This function shows all signals in the signal palette.
Arguments:

filter optional filter, will only show signals tagged with info_text filter

Sound Functions

Note that sounds are not played directly. Instead they are used as templates for sound instances. See diguyCharacter::play_sound() and diguyCharacter::create_sound_instance().

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_num_sounds

Prototype:
int get_num_sounds();
Returns:

number of sounds in the scenario

function diguyScenario::get_sound_at_index

Prototype:
diguySound* get_sound_at_index(int index);
Returns:

pointer of type diguySound; NULL if no sound at the specified index
Arguments:

index index of the sound; indices start at 0

function diguyScenario::find_sound

Prototype:
diguySound* find_sound(const char* name);
Description:

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

name name of sound to be found
Returns:

pointer of type diguySound; NULL if not found

function diguyScenario::create_sound

Prototype:
diguySound* create_sound(const char* name,
    const char* sound_filename = NULL,
    const char* phoneme_filename = NULL);
Description:

This function creates a new sound and returns a pointer to it.

Note that sounds are not played directly. Instead they are used as templates for sound instances. See diguyCharacter::play_sound() and diguyCharacter::create_sound_instance().
Arguments:

name name of the new sound
sound_filename filename of the sound
phoneme_filename optional phoneme file; see diguySound::set_phoneme_filename()

Note that name isn't the filename of the sound; it is the descriptive name that will show up in the UI and used in diguyCharacter calls that play sounds.

Pass the filename in the sound_filename argument or use the function diguySound::set_sound_filename() to set the filename of the sound.

See diguyCharacter::set_current_voice_actor() for information about naming sounds for different voice actors.
Returns:

pointer of type diguySound

function diguyScenario::destroy_sound

Prototype:
int destroy_sound(diguySound* sound);
Description:

This function destroys a sound.
Arguments:

sound pointer to diguySound to be destroyed
Returns:

0 on success, -1 on failure

function diguyScenario::preload_sound

Prototype:
int preload_sound(diguySound* sound);
Description:

This function preloads data for the sound.
Arguments:

sound pointer to diguySound
Returns:

0 on success, -1 on failure

function diguyScenario::stop_all_sounds

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

This function stops all sounds playing within the scenario.
Arguments:

rampdown_time how long to allow the sounds to fade out
Returns:

0 on success, -1 on failure

function diguyScenario::play_3d_sound

Prototype:
int play_3d_sound(const char* name,
    float x, float y, float z,
    float gain,
    int save_event);
Description:

This function plays a non looping sound.
Arguments:

name name of the sound
x, y, z location in the world the sound comes from
gain a volume multiplier
save_event if review data should record the creation of this sound
Returns:

0 on success, -1 on failure

Group Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_num_groups

Prototype:
int get_num_groups();
Returns:

number of groups in the scenario

function diguyScenario::get_group_at_index

Prototype:
diguyCharacterGroup* get_group_at_index(int index);
Returns:

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

index index of the group; indices start at 0

function diguyScenario::find_group

Prototype:
diguyCharacterGroup* find_group(const char* name);
Description:

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

name name of group to be found
Returns:

pointer of type diguyCharacterGroup; NULL if not found

function diguyScenario::create_group

Prototype:
diguyCharacterGroup* create_group(const char* name);
Description:

This function creates a new group and returns a pointer to it.
Arguments:

name name of the new group
Returns:

pointer of type diguyCharacterGroup

function diguyScenario::find_or_create_group

Prototype:
diguyCharacterGroup* find_or_create_group(const char* name);
Description:

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

name name of the group to find or create
Returns:

pointer of type diguyGroup; should never be NULL

function diguyScenario::destroy_group

Prototype:
int destroy_group(diguyCharacterGroup* group);
Description:

This function destroys a group.
Arguments:

group pointer to a diguyCharacterGroup
Returns:

0 on success, -1 on failure

Sensor Region Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_num_sensor_regions

Prototype:
int get_num_sensor_regions();
Returns:

number of sensor regions in the scenario

function diguyScenario::get_sensor_region_at_index

Prototype:
diguySensorRegion* get_sensor_region_at_index(int index);
Returns:

pointer of type diguySensorRegion; NULL if no sensor region at the specified index
Arguments:

index index of the sensor region; indices start at 0

function diguyScenario::find_sensor_region

Prototype:
diguySensorRegion* find_sensor_region(const char* name);
Description:

This function returns a pointer to the specified sensor region.
Arguments:

name name of sensor region to be found
Returns:

pointer of type diguySensorRegion; NULL if not found

Scene Object Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_num_scene_objects

Prototype:
int get_num_scene_objects();
Returns:

number of scene objects in the scenario

function diguyScenario::get_scene_object_at_index

Prototype:
diguySceneObject* get_scene_object_at_index(int index);
Returns:

pointer of type diguySceneObject; NULL if no scene object at the specified index
Arguments:

index index of the scene object; indices start at 0

function diguyScenario::find_scene_object

Prototype:
diguySceneObject* find_scene_object(const char* name);
Returns:

pointer of type diguySceneObject; NULL if no scene object with specified name

function diguyScenario::set_scene_objects_enabled

Prototype:
void set_scene_objects_enabled(int scene_objects_enabled);
Description:

This function sets whether scene objects defined in the scenario are enabled, and therefore potentially visible.

Scene objects are not enabled by default.
Arguments:

scene_objects_enabled flag determining whether scene objects are enabled; 1 for enabled, 0 for disabled

function diguyScenario::get_scene_objects_enabled

Prototype:
int get_scene_objects_enabled();
Returns:

the most recent setting made by a call to set_scene_objects_enabled()

function diguyScenario::create_scene_object

Prototype:
diguySceneObject* create_scene_object(const char* name,
    const char* filename);
Description:

This function creates a new scene object and returns a pointer to it.
Arguments:

name name of the new scene object
filename file the scene object should use
Returns:

pointer of type diguySceneObject; NULL if creation failed

function diguyScenario::create_user_defined_scene_object

Prototype:
diguySceneObject* create_user_defined_scene_object(const char* name);
Description:

This function creates a new user defined scene object and returns a pointer to it.
Arguments:

name name of the new scene object
Returns:

pointer of type diguySceneObject; NULL if creation failed

function diguyScenario::destroy_scene_object

Prototype:
int destroy_scene_object(diguySceneObject* scene_object);
Description:

This function destroys a scene object.
Arguments:

scene_object pointer to a diguySceneObject
Returns:

0 on success, -1 on failure

View Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_primary_view

Prototype:
diguyView* get_primary_view();
Returns:

pointer to the scenario's primary view; there is one and only one primary view in the scenario

function diguyScenario::get_num_secondary_views

Prototype:
int get_num_secondary_views();
Returns:

number of secondary views in the scenario

function diguyScenario::get_secondary_view_at_index

Prototype:
diguyView* get_secondary_view_at_index(int index);
Returns:

pointer of type diguyView; NULL if no secondary view at the specified index
Arguments:

index index of the secondary view; indices start at 0

function diguyScenario::find_view

Prototype:
diguyView* find_view(const char* name);
Description:

This function returns a pointer to the view with the given name. The primary view and all of the secondary views are checked for a name match.
Returns:

pointer of type diguyView; NULL if not found

Camera Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_scenario_camera

Prototype:
diguyViewCamera* get_scenario_camera();
Description:

This function returns a pointer to the primary view's camera. This is equivalent to:
diguyView* v = scenario->get_primary_view();
return v->get_camera();
Returns:

pointer of type diguyViewCamera; should never be NULL

function diguyScenario::find_camera

Prototype:
diguyViewCamera* find_camera(const char* name);
Description:

This function returns a pointer to the camera with the given name. The primary view's camera and all of the secondary views' cameras are checked for a name match.
Returns:

pointer of type diguyViewCamera; NULL if not found

function diguyScenario::set_scenario_camera_affected_by_script_events

Prototype:
void set_scenario_camera_affected_by_script_events(int flag);
Description:

This function sets a flag that determines whether script calls can set the primary view's camera settings. Specifically, if flag is 0, calls to diguyViewCamera::load() will have no effect; the camera should remain completely under user control.
Arguments:

flag 1 to enable, 0 to disable

function diguyScenario::get_scenario_camera_affected_by_script_events

Prototype:
int get_scenario_camera_affected_by_script_events();
Returns:

the most recent setting made by set_scenario_camera_affected_by_script_events()

function diguyScenario::set_scenario_camera_affected_by_script_events_when_iguy_active

Prototype:
void set_scenario_camera_affected_by_script_events_when_iguy_active(int flag);
Description:

This function, like set_scenario_camera_affected_by_script_events(), determines whether script calls can set the primary view's camera settings, but only disables camera changes if there is an active I-Guy character as set by the set_iguy_character() call.

If set_scenario_camera_affected_by_script_events() has been called with a value of 0, then this function has no effect.
Arguments:

flag 1 to enable, 0 to disable

function diguyScenario::get_scenario_camera_affected_by_script_events_when_iguy_active

Prototype:
int get_scenario_camera_affected_by_script_events_when_iguy_active();
Returns:

the most recent setting made by set_scenario_camera_affected_by_script_events()

function diguyScenario::get_num_camera_settings

Prototype:
int get_num_camera_settings();
Returns:

number of camera settings saved in the scenario

function diguyScenario::get_camera_settings_at_index

Prototype:
diguyViewCameraSettings* get_camera_settings_at_index(int index);
Returns:

pointer of type diguyViewCameraSettings; NULL if no camera settings at the specified index
Arguments:

index index of the camera settings; indices start at 0

function diguyScenario::find_camera_settings

Prototype:
diguyViewCameraSettings* find_camera_settings(const char* settings_name);
Description:

This function returns a pointer to the specified camera settings.
Arguments:

settings_name name of camera settings to be found
Returns:

pointer of type diguyViewCamera; NULL if not found

function diguyScenario::load_camera_settings

Prototype:
int load_camera_settings(const char* settings_name, int update_current_camera = 1);
Description:

This function loads the specified camera settings into the primary view's camera.
Arguments:

settings_name name of camera settings to be loaded
update_current_camera whether the current camera should be updated; defaults to 1

Not updating the current camera will cause the camera history to be lost.
Returns:

0 on success, -1 on failure

function diguyScenario::set_render_camera

Prototype:
void set_render_camera(diguyViewCamera* camera);
Description:

This function sets camera that will be used for down-stream camera-related operations. This includes:

far position rendering in the OpenGL renderer
various culling operations (e.g. set_character_culling_enabled())
graphics LOD range scaling; see set_scale_graphics_lod_ranges_from_view_settings()

Typically the passed camera should be the primary view's camera.

A render camera does not always need to be set. If one is not set, the above camera-related operations will not be performed.

If a render camera is set the actual rendering environment camera settings (e.g. as set by gluLookAt() in OpenGL) should match the settings in the render camera, or there may be unexpected visual results.
Arguments:

camera camera to use for camera-related operations

Fog Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_scenario_fog

Prototype:
diguyViewFog* get_scenario_fog();
Description:

This function returns a pointer to the scenario fog. This is the fog of the primary view.
Returns:

pointer of type diguyViewFog; should never be NULL

function diguyScenario::find_fog

Prototype:
diguyViewFog* find_fog(const char* name);
Description:

This function returns a pointer to the fog with the given name. The primary view's fog and all of the secondary views' fogs are checked for a name match.
Returns:

pointer of type diguyViewFog; NULL if not found

function diguyScenario::find_or_create_fog

Prototype:
diguyViewFog* find_or_create_fog(const char* name);
Description:

This function returns the fog object with the given name, or creates one if not found.
Returns:

pointer of type diguyViewFog

name

function diguyScenario::load_current_fog

Prototype:
void load_current_fog(const char* name);
Description:

This function loads the named fog settings the currently active one.

name

function diguyScenario::get_num_fog_settings

Prototype:
int get_num_fog_settings();
Returns:

number of fog settings in the scenario

function diguyScenario::get_fog_settings_at_index

Prototype:
diguyViewFogSettings* get_fog_settings_at_index(int index);
Returns:

pointer of type diguyViewFogSettings; NULL if no fog at the specified index
Arguments:

index index of the fog settings; indices start at 0

function diguyScenario::find_fog_settings

Prototype:
diguyViewFogSettings* find_fog_settings(const char* settings_name);
Description:

This function returns a pointer to the specified fog settings.
Arguments:

settings_name name of fog settings to be found
Returns:

pointer of type diguyViewFogSettings; NULL if not found

function diguyScenario::load_fog_settings

Prototype:
int load_fog_settings(const char* settings_name);
Description:

This function loads the specified fog settings into the scenario fog.
Arguments:

settings_name name of fog settings to be loaded
Returns:

pointer of type diguyViewFog; NULL if not found

Light Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_scenario_light

Prototype:
diguyViewLight* get_scenario_light(int i = 0);
Description:

This function returns a pointer to the scenario light. These are the lights of the primary view.
Arguments:

number number of light to be found
Returns:

pointer of type diguyViewLight; can be null if asked for a non-existent light

function diguyScenario::find_light

Prototype:
diguyViewLight* find_light(const char* name);
Description:

This function returns a pointer to the light with the given name. The primary view's light and all of the secondary views' lights are checked for a name match.
Returns:

pointer of type diguyViewLight; NULL if not found

function diguyScenario::get_num_light_settings

Prototype:
int get_num_light_settings();
Returns:

number of light settings in the scenario

function diguyScenario::get_light_settings_at_index

Prototype:
diguyViewLightSettings* get_light_settings_at_index(int index);
Returns:

pointer of type diguyViewLightSettings; NULL if no light settings at the specified index
Arguments:

index index of the light settings; indices start at 0

function diguyScenario::find_light_settings

Prototype:
diguyViewLightSettings* find_light_settings(const char* settings_name);
Description:

This function returns a pointer to the specified light settings.
Arguments:

name name of light settings to be found
Returns:

pointer of type diguyViewLightSettings; NULL if not found

function diguyScenario::load_light_settings

Prototype:
int load_light_settings(const char* settings_name, int light_num = 0);
Description:

This function loads the specified light settings into the scenario light.
Arguments:

settings_name name of light settings to be loaded
light_num which light to load into
Returns:

pointer of type diguyViewLight; NULL if not found

Info Popup Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_num_info_popups

Prototype:
int get_num_info_popups();
Returns:

number of info popups in the scenario

function diguyScenario::get_info_popup_at_index

Prototype:
diguyInfoPopup* get_info_popup_at_index(int index);
Returns:

pointer of type diguyInfoPopup; NULL if no info popup at the specified index
Arguments:

index index of the info popup; indices start at 0

function diguyScenario::find_info_popup

Prototype:
diguyInfoPopup* find_info_popup(const char* name);
Description:

This function returns a pointer to the specified info popup.
Arguments:

name name of info popup to be found
Returns:

pointer of type diguyInfoPopup; NULL if not found

function diguyScenario::set_info_popup_default_encoding

Prototype:
int set_info_popup_default_encoding(const char* info_popup_default_encoding);
Description:

This function sets the default encoding for info popups that do not have an encoding specified.
Arguments:

info_popup_default_encoding new default encoding
Returns:

0 on success, -1 on failure

function diguyScenario::get_info_popup_default_encoding

Prototype:
const char* get_info_popup_default_encoding();
Description:

This function returns the default encoding of info popups.
Returns:

default encoding; value will never be NULL, but may be the empty string ("") if no default encoding has been specified

Variable Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_num_variables

Prototype:
int get_num_variables();
Returns:

number of variables in the scenario

function diguyScenario::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 diguyScenario::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 diguyScenario::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 diguyScenario::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

Face Expression Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_num_face_expressions

Prototype:
int get_num_face_expressions();
Returns:

number of face_expressions in the scenario

function diguyScenario::get_face_expression_at_index

Prototype:
diguyCharacterFaceExpression* get_face_expression_at_index(int index);
Returns:

pointer of type diguyCharacterFaceExpression; NULL if no info popup at the specified index
Arguments:

index index of the face_expression; indices start at 0

function diguyScenario::find_face_expression

Prototype:
diguyCharacterFaceExpression* find_face_expression(const char* name);
Description:

This function returns a pointer to the specified face expression.
Arguments:

name name of face_expression to be found
Returns:

pointer of type diguyCharacterFaceExpression; NULL if not found

function diguyScenario::create_face_expression

Prototype:
diguyCharacterFaceExpression* create_face_expression(const char* name,
    const char* target_actor = "exface");
Description:

This function creates a new face expression with the given name.
Arguments:

name name of the new face expression
target_actor name of the actor to use as template; defaults to "exface" for backwards compatiblity
Returns:

pointer of type diguyCharacterFaceExpression

function diguyScenario::destroy_face_expression

Prototype:
int destroy_face_expression(diguyCharacterFaceExpression* face_expression);
Description:

This function destroys the passed face expression.
Arguments:

face_expression pointer to a diguyCharacterFaceExpression
Returns:

0 on success, -1 on failure

Chain Settings Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_num_chain_settings

Prototype:
int get_num_chain_settings();
Returns:

number of chain settings in the scenario

function diguyScenario::get_chain_settings_at_index

Prototype:
diguyChainSettings* get_chain_settings_at_index(int index);
Returns:

pointer of type diguyChainSettings; NULL if no chain settings at the specified index
Arguments:

index index of the chain settings; indices start at 0

function diguyScenario::find_chain_settings

Prototype:
diguyChainSettings* find_chain_settings(const char* name);
Description:

This function returns a pointer to the specified chain settings.
Arguments:

name name of chain settings to be found
Returns:

pointer of type diguyChainSettings; NULL if not found

function diguyScenario::create_chain_settings

Prototype:
diguyChainSettings* create_chain_settings(const char* name);
Description:

This function creates a new chain settings and returns a pointer to it.
Arguments:

name name of the new chain settings
Returns:

pointer of type diguyChainSettings

function diguyScenario::destroy_chain_settings

Prototype:
int destroy_chain_settings(diguyChainSettings* chain_settings);
Description:

This function destroys a chain settings.
Arguments:

chain settings pointer to a diguyChainSettings
Returns:

0 on success, -1 on failure

Callback Functions

Unless otherwise specified, callable from:

C++
Script

enumeration

	enum {
		CALLBACK_ID_CREATE = 1,
		CALLBACK_ID_DESTROY,
		CALLBACK_ID_RESET,
		CALLBACK_ID_WAIT_CURSOR_SHOW,
		CALLBACK_ID_WAIT_CURSOR_HIDE,
		CALLBACK_ID_LOAD,
		CALLBACK_ID_SAVE,
		CALLBACK_ID_LOAD_SCENARIO_FILE,
		CALLBACK_ID_SAVE_SCENARIO_FILE,
		CALLBACK_ID_SCENE_OBJECT_IMPACT,
		CALLBACK_ID_TIMED_EVENT,
		CALLBACK_ID_MANUALLY_INVOKED,
		CALLBACK_ID_POST_DRAW,
		CALLBACK_ID_PLAYBACK_MODE_CHANGED,
		CALLBACK_ID_INPUT_MODE_CHANGED,
		CALLBACK_ID_RENDER_MODE_CHANGED,
		CALLBACK_ID_PRE_REINITIALIZE,
		CALLBACK_ID_POST_REINITIALIZE,
		CALLBACK_ID_POST_LOAD_CHECKPOINT
	};
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, 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.

Callback Enums:
CALLBACK_ID_CREATE

This callback will be called when a new scenario is created. It should only be used by diguyApp::add_default_scenario_callback(). Using it in set_callback() will have no effect, as by that time the scenario has already been created.
CALLBACK_ID_RESET

This callback will be called when the scenario is reset.
CALLBACK_ID_WAIT_CURSOR_SHOW

This callback will be called when a diguy operation is likely to take some time, allowing an application to display a wait cursor.
CALLBACK_ID_WAIT_CURSOR_HIDE

This callback will be called when a diguy operation that caused a wait cursor to be shown has completed, allowing an application to hide the wait cursor.
CALLBACK_ID_LOAD

This callback will be called when a scenario is loaded, thereby giving a chance for custom code to read extra elements from the loaded file.
CALLBACK_ID_SAVE

This callback will be called when a scenario is saved, thereby giving a chance for custom code to insert extra elements into the saved file.
CALLBACK_ID_LOAD_SCENARIO_FILE

This callback will be called just before a scenario loads a new file.
CALLBACK_ID_SAVE_SCENARIO_FILE

This callback will be called just after a scenario saves a new file. With a char * pointer to the file name.
CALLBACK_ID_MANUALLY_INVOKED

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

The user's returned diguyCallbackReturn value will be ignored.
CALLBACK_ID_POST_DRAW

This callback will be called just after a scenario finishes it's draw commands. The diguyViewPainter class can be used to issue abstract draw commands in DI-Guy Scenario.
Lua Example:
local painter = this_app:get_view_painter();
painter:set_pen_color(1,1,0);
painter:draw_line(0,0,0, 1,1,1);
CALLBACK_ID_PLAYBACK_MODE_CHANGED

This callback will be called when the playback mode of the scenario has changed. For example, the Play or Stop buttons are pressed in DI-Guy Scenario, or set_playback_mode() is called.

The user's returned diguyCallbackReturn value will be ignored.
CALLBACK_ID_INPUT_MODE_CHANGED

This callback will be called when the input mode of the scenario has changed. For example, when an Input Mode button is pressed in DI-Guy Scenario, or diguyApp::set_base_input_mode() is called.

The user's returned diguyCallbackReturn value will be ignored.
CALLBACK_ID_RENDER_MODE_CHANGED

This callback will be called if the render mode of the scenario changes, typically due to a set_current_render_mode().

The user's returned diguyCallbackReturn value will be ignored.
CALLBACK_ID_POST_LOAD_CHECKPOINT

This callback will be called just after a scenario finishes loading a checkpoint file.

function diguyScenario::add_callback

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

This function adds a scenario callback.
Arguments:

callback pointer to function with prototype diguyScenarioCallback (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
remove_on_scenario_load pass 1 to remove the callback on a scenario load, 0 to not
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguyScenario::remove_callback

Prototype:
int remove_callback(int callback_id,
    diguyScenarioCallback* 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 callback
callback pointer to function with prototype diguyCharacterCallback (typedefed above)
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguyScenario::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 callback
callback_user_data pointer for user's own use
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguyScenario::add_default_character_callback

Prototype:
int add_default_character_callback(int callback_id,
    diguyCharacterCallback* callback,
    void* callback_params,
    void* callback_user_data,
    int add_to_existing_objects_flag = 0,
    int remove_on_scenario_load = 1);
Description:

This function sets a default user callback that will be added to all new characters. See diguyCharacter::add_callback() for details.
Callable From:

C++

function diguyScenario::remove_default_character_callback

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

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

callback_id integer id of callback
callback pointer to function with prototype diguyCharacterCallback (typedefed above)
Callable From:

C++

function diguyScenario::remove_default_character_callback_with_user_data

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

This function removes a default user callback previously added by add_default_character_callback(). See diguyCharacter::remove_callback_with_user_data() for details.
Callable From:

C++

function diguyScenario::add_default_path_callback

Prototype:
int add_default_path_callback(int callback_id,
    diguyCharacterPathCallback* callback,
    void* callback_params,
    void* callback_user_data,
    int add_to_existing_objects_flag = 0,
    int remove_on_scenario_load = 1);
Description:

This function add a default user callback that will be added to all new paths.
Callable From:

C++

function diguyScenario::remove_default_path_callback

Prototype:
int remove_default_path_callback(int callback_id,
    diguyCharacterPathCallback* callback);
Description:

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

callback_id integer id of callback
callback pointer to function with prototype diguyCharacterCallback (typedefed above)
Callable From:

C++

function diguyScenario::remove_default_path_callback_with_user_data

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

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

callback_id integer id of callback
callback_user_data pointer for user's own use
Callable From:

C++

function diguyScenario::add_default_sensor_region_callback

Prototype:
int add_default_sensor_region_callback(int callback_id,
    diguySensorRegionCallback* callback,
    void* callback_params,
    void* callback_user_data,
    int add_to_existing_objects_flag = 0,
    int remove_on_scenario_load = 1);
Description:

This function sets a default user callback that will be added to all new sensor regions. See diguySensorRegion::add_callback() for details.
Callable From:

C++

function diguyScenario::remove_default_sensor_region_callback

Prototype:
int remove_default_sensor_region_callback(int callback_id,
    diguySensorRegionCallback* callback);
Description:

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

callback_id integer id of callback
callback pointer to function with prototype diguyCharacterCallback (typedefed above)
Callable From:

C++

function diguyScenario::remove_default_sensor_region_callback_with_user_data

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

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

callback_id integer id of callback
callback_user_data pointer for user's own use
Callable From:

C++

function diguyScenario::add_default_signal_callback

Prototype:
int add_default_signal_callback(int callback_id,
    diguySignalCallback* callback,
    void* callback_params,
    void* callback_user_data,
    int add_to_existing_objects_flag = 0,
    int remove_on_scenario_load = 1);
Description:

This function adds a default user callback that will be added to all new signals.
Callable From:

C++

function diguyScenario::remove_default_signal_callback

Prototype:
int remove_default_signal_callback(int callback_id,
    diguySignalCallback* callback);
Description:

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

callback_id integer id of callback
callback pointer to function with prototype diguyCharacterCallback (typedefed above)
Callable From:

C++

function diguyScenario::remove_default_signal_callback_with_user_data

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

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

callback_id integer id of callback
callback_user_data pointer for user's own use
Callable From:

C++

function diguyScenario::add_default_variable_callback

Prototype:
int add_default_variable_callback(int callback_id,
    diguyVariableCallback* callback,
    void* callback_params,
    void* callback_user_data,
    int add_to_existing_objects_flag = 0,
    int remove_on_scenario_load = 1);
Description:

This function adds a default user callback that will be added to all new variables.
Callable From:

C++

function diguyScenario::remove_default_variable_callback

Prototype:
int remove_default_variable_callback(int callback_id,
    diguyVariableCallback* callback);
Description:

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

callback_id integer id of callback
callback pointer to function with prototype diguyCharacterCallback (typedefed above)
Callable From:

C++

function diguyScenario::remove_default_variable_callback_with_user_data

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

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

callback_id integer id of callback
callback_user_data pointer for user's own use
Callable From:

C++

function diguyScenario::add_default_view_callback

Prototype:
int add_default_view_callback(int callback_id,
    diguyViewCallback* callback,
    void* callback_params,
    void* callback_user_data,
    int add_to_existing_objects_flag = 1,
    int remove_on_scenario_load = 1);
Description:

This function adds a default user callback that will be added to all new views.

Note that unlike most of the other add default callback functions, this one's add_to_existing_objects_flag argument defaults to a value of 1, since views in scenarios always exist and are neither created nor destroyed.
Callable From:

C++

function diguyScenario::remove_default_view_callback

Prototype:
int remove_default_view_callback(int callback_id,
    diguyViewCallback* callback);
Description:

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

callback_id integer id of callback
callback pointer to function with prototype diguyCharacterCallback (typedefed above)
Callable From:

C++

function diguyScenario::remove_default_view_callback_with_user_data

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

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

callback_id integer id of callback
callback_user_data pointer for user's own use
Callable From:

C++

function diguyScenario::add_default_camera_callback

Prototype:
int add_default_camera_callback(int callback_id,
    diguyViewCameraCallback* callback,
    void* callback_params,
    void* callback_user_data,
    int add_to_existing_objects_flag = 0,
    int remove_on_scenario_load = 1);
Description:

This function adds a default user callback that will be added to all cameras.
Callable From:

C++

function diguyScenario::remove_default_camera_callback

Prototype:
int remove_default_camera_callback(int callback_id,
    diguyViewCameraCallback* callback);
Description:

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

callback_id integer id of callback
callback pointer to function with prototype diguyCharacterCallback (typedefed above)
Callable From:

C++

function diguyScenario::remove_default_camera_callback_with_user_data

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

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

callback_id integer id of callback
callback_user_data pointer for user's own use
Callable From:

C++

function diguyScenario::add_default_fog_callback

Prototype:
int add_default_fog_callback(int callback_id,
    diguyViewFogCallback* callback,
    void* callback_params,
    void* callback_user_data,
    int add_to_existing_objects_flag = 0,
    int remove_on_scenario_load = 1);
Description:

This function adds a default user callback that will be added to all new fogs.
Callable From:

C++

function diguyScenario::remove_default_fog_callback

Prototype:
int remove_default_fog_callback(int callback_id,
    diguyViewFogCallback* callback);
Description:

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

callback_id integer id of callback
callback pointer to function with prototype diguyCharacterCallback (typedefed above)
Callable From:

C++

function diguyScenario::remove_default_fog_callback_with_user_data

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

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

callback_id integer id of callback
callback_user_data pointer for user's own use
Callable From:

C++

function diguyScenario::add_default_light_callback

Prototype:
int add_default_light_callback(int callback_id,
    diguyViewLightCallback* callback,
    void* callback_params,
    void* callback_user_data,
    int add_to_existing_objects_flag = 0,
    int remove_on_scenario_load = 1);
Description:

This function adds a default user callback that will be added to all new lights.
Callable From:

C++

function diguyScenario::remove_default_light_callback

Prototype:
int remove_default_light_callback(int callback_id,
    diguyViewLightCallback* callback);
Description:

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

callback_id integer id of callback
callback pointer to function with prototype diguyCharacterCallback (typedefed above)
Callable From:

C++

function diguyScenario::remove_default_light_callback_with_user_data

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

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

callback_id integer id of callback
callback_user_data pointer for user's own use
Callable From:

C++

function diguyScenario::manually_invoke_callbacks_now

Prototype:
void manually_invoke_callbacks_now(int callback_id);
Description:

This function causes all of the scenario callbacks with the given callback_id to be called now.
Arguments:

callback_id integer id of callback

function diguyScenario::add_callback_script

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

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

See diguyCharacter::add_callback_script() for an example of use.
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
remove_on_scenario_load if the callback is removed when a new scenario is loaded

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

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

See diguyCharacter::remove_callback_script() for an example of use.
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

function diguyScenario::add_default_character_callback_script

Prototype:
int add_default_character_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type = NULL,
    int add_to_existing_objects_flag = 0,
    int remove_on_scenario_load = 1);
Description:

This function adds a default character callback script. The callback script will be added to all new characters. See diguyCharacter::add_callback_script() for more details.
Returns:

0 on success, -1 on failure

function diguyScenario::remove_default_character_callback_script

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

This function removes a default character callback script. See diguyCharacter::remove_callback_script() for more details.
Returns:

0 on success, -1 on failure

function diguyScenario::add_default_sensor_region_callback_script

Prototype:
int add_default_sensor_region_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type = NULL,
    int add_to_existing_objects_flag = 0,
    int remove_on_scenario_load = 1);
Description:

This function adds a default sensor region callback script. The callback script will be added to all new sensor regions. See diguySensorRegion::add_callback_script() for more details.
Returns:

0 on success, -1 on failure

function diguyScenario::remove_default_sensor_region_callback_script

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

This function removes a default sensor region callback script. See diguySensorRegion::remove_callback_script() for more details.
Returns:

0 on success, -1 on failure

function diguyScenario::add_default_signal_callback_script

Prototype:
int add_default_signal_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type = NULL,
    int add_to_existing_objects_flag = 0,
    int remove_on_scenario_load = 1);
Description:

This function adds a default signal callback script. The callback script will be added to all new signals. See diguySignal::add_callback_script() for more details.
Returns:

0 on success, -1 on failure

function diguyScenario::remove_default_signal_callback_script

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

This function removes a default signal callback script. See diguySignal::remove_callback_script() for more details.
Returns:

0 on success, -1 on failure

function diguyScenario::add_default_variable_callback_script

Prototype:
int add_default_variable_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type = NULL,
    int add_to_existing_objects_flag = 0,
    int remove_on_scenario_load = 1);
Description:

This function adds a default variable callback script. The callback script will be added to all new variables. See diguySignal::add_callback_script() for more details.
Returns:

0 on success, -1 on failure

function diguyScenario::remove_default_variable_callback_script

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

This function removes a default variable callback script. See diguySignal::remove_callback_script() for more details.
Returns:

0 on success, -1 on failure

function diguyScenario::add_default_view_callback_script

Prototype:
int add_default_view_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type = NULL,
    int add_to_existing_objects_flag = 0,
    int remove_on_scenario_load = 1);
Description:

This function adds a default view callback script. The callback script will be added to all new views. See diguyView::add_callback_script() for more details.
Returns:

0 on success, -1 on failure

function diguyScenario::remove_default_view_callback_script

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

This function removes a default character view script. See diguyView::remove_callback_script() for more details.
Returns:

0 on success, -1 on failure

function diguyScenario::add_default_camera_callback_script

Prototype:
int add_default_camera_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type = NULL,
    int add_to_existing_objects_flag = 0,
    int remove_on_scenario_load = 1);
Description:

This function adds a default camera callback script. The callback script will be added to all new cameras. See diguyViewCamera::add_callback_script() for more details.
Returns:

0 on success, -1 on failure

function diguyScenario::remove_default_camera_callback_script

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

This function removes a default camera callback script. See diguyViewCamera::remove_callback_script() for more details.
Returns:

0 on success, -1 on failure

function diguyScenario::add_default_fog_callback_script

Prototype:
int add_default_fog_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type = NULL,
    int add_to_existing_objects_flag = 0,
    int remove_on_scenario_load = 1);
Description:

This function adds a default fog callback script. The callback script will be added to all new fogs. See diguyViewFog::add_callback_script() for more details.
Returns:

0 on success, -1 on failure

function diguyScenario::remove_default_fog_callback_script

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

This function removes a default fog callback script. See diguyViewFog::remove_callback_script() for more details.
Returns:

0 on success, -1 on failure

function diguyScenario::add_default_light_callback_script

Prototype:
int add_default_light_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type = NULL,
    int add_to_existing_objects_flag = 0,
    int remove_on_scenario_load = 1);
Description:

This function adds a default light callback script. The callback script will be added to all new lights. See diguyViewLight::add_callback_script() for more details.
Returns:

0 on success, -1 on failure

function diguyScenario::remove_default_light_callback_script

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

This function removes a default light callback script. See diguyViewLight::remove_callback_script() for more details.
Returns:

0 on success, -1 on failure

Event Handler Functions

DI-Guy event handlers are similar to callbacks, but have a name with which they can be referenced. This name allows DI-Guy Scenario to map event handlers to callback ids using a UI, and allows for these mappings to be saved and restored as part of the scenario.

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::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 scenario callback function registered by diguyApp::register_scenario_event_handler() or diguyApp::register_scenario_event_handler_from_library()
a script registered by diguyApp::register_scenario_event_handler_script()
a Script, Decision, or Library Function in the scenario whose "Event Type" is "Scenario"
Arguments:

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

0 on success, -1 on failure

function diguyScenario::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 map
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 diguyScenario::manually_invoke_event_handler

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

This function manually invokes the named scenario event handler. The callback_id that will be passed to the event handler will be CALLBACK_ID_MANUALLY_INVOKED.

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.

The event handler is one of the following:

a scenario callback function registered by diguyApp::register_scenario_event_handler() or diguyApp::register_scenario_event_handler_from_library()
a script registered by diguyApp::register_scenario_event_handler_script()
a Script, Decision, or Library Function in the scenario whose "Event Type" is "Scenario"
Arguments:

handler_name name of the event handler to invoke
Returns:

DIGUY_CALLBACK_CONTINUE or DIGUY_CALLBACK_STOP
Callable From:

C++
Script
Decision

function diguyScenario::register_character_event_handler

Prototype:
int register_character_event_handler(const char* handler_name,
    diguyCharacterCallback* callback,
    void* callback_user_data = 0);
Description:

This function registers a character event handler function that can later be mapped via a call to diguyCharacter::map_event_handler_to_callback_id().

Call unregister_character_event_handler() to unregister the function.
Arguments:

handler_name name of the event handler
callback pointer to handler function
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 handler function is called
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguyScenario::register_character_event_handler_from_library

Prototype:
int register_character_event_handler_from_library(const char* handler_name,
    const char* library_name,
    const char* function_name,
    void* callback_user_data = 0);
Description:

This function registers a character event handler function that can later be mapped via a call to diguyCharacter::map_event_handler_to_callback_id().

Unlike register_character_event_handler(), which directly passes a function pointer, this function looks up the function pointer from a shared library (a .dll under Windows, a .so under Unix).

The passed library_name should not include the .dll or .so extension; these will be added automatically. This allows for cross-platform scenarios that don't have differing dynamic library extensions built into them.

Call unregister_character_event_handler() to unregister the function.
Arguments:

handler_name name of the event handler
library_name pointer to handler function
function_name pointer to handler function
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 handler function is called
Returns:

0 on success, -1 on failure

function diguyScenario::register_character_event_handler_script

Prototype:
int register_character_event_handler_script(const char* handler_name,
    const char* handler_script,
    const char* handler_script_type = 0);
Description:

This function registers a character event handler script that can later be mapped via a call to diguyCharacter::map_event_handler_to_callback_id().

Call unregister_character_event_handler() to unregister the script.
Arguments:

handler_name name of the event handler
handler_script Script text
handler_script_type type of script; pass NULL for scenario to use the default script interpreter
Returns:

0 on success, -1 on failure

function diguyScenario::has_registered_character_event_handler

Prototype:
int has_registered_character_event_handler(const char* handler_name);
Returns:

1 if there is a character event handler with the given name, 0 if not
Arguments:

handler_name name of the event handler

function diguyScenario::unregister_character_event_handler

Prototype:
int unregister_character_event_handler(const char* handler_name);
Description:

This function unregisters a character event handler. This will unmap the event handler from any mappings it is a part of.
Arguments:

handler_name name of the event handler
Returns:

0 on success, -1 on failure

function diguyScenario::register_signal_event_handler

Prototype:
int register_signal_event_handler(const char* handler_name,
    diguySignalCallback* callback,
    void* callback_user_data = 0);
Description:

This function is analogous to the register_character_event_handler() function, but is for signals rather than characters.
Callable From:

C++

function diguyScenario::register_signal_event_handler_from_library

Prototype:
int register_signal_event_handler_from_library(const char* handler_name,
    const char* library_name,
    const char* function_name,
    void* callback_user_data = 0);
Description:

This function is analogous to the register_character_event_handler_from_library() function, but is for signals rather than characters.

function diguyScenario::register_signal_event_handler_script

Prototype:
int register_signal_event_handler_script(const char* handler_name,
    const char* handler_script,
    const char* handler_script_type = 0);
Description:

This function is analogous to the register_character_event_handler_script() function, but is for signals rather than characters.

function diguyScenario::has_registered_signal_event_handler

Prototype:
int has_registered_signal_event_handler(const char* handler_name);
Description:

This function is analogous to the has_registered_character_event_handler() function, but is for signals rather than characters.

function diguyScenario::unregister_signal_event_handler

Prototype:
int unregister_signal_event_handler(const char* handler_name);
Description:

This function is analogous to the unregister_character_event_handler() function, but is for signals rather than characters.

function diguyScenario::register_sensor_region_event_handler

Prototype:
int register_sensor_region_event_handler(const char* handler_name,
    diguySensorRegionCallback* callback,
    void* callback_user_data = 0);
Description:

This function is analogous to the register_character_event_handler() function, but is for sensor regions rather than characters.
Callable From:

C++

function diguyScenario::register_sensor_region_event_handler_from_library

Prototype:
int register_sensor_region_event_handler_from_library(const char* handler_name,
    const char* library_name,
    const char* function_name,
    void* callback_user_data = 0);
Description:

This function is analogous to the register_character_event_handler_from_library() function, but is for sensor regions rather than characters.

function diguyScenario::register_sensor_region_event_handler_script

Prototype:
int register_sensor_region_event_handler_script(const char* handler_name,
    const char* handler_script,
    const char* handler_script_type = 0);
Description:

This function is analogous to the register_character_event_handler_script() function, but is for sensor regions rather than characters.

function diguyScenario::has_registered_sensor_region_event_handler

Prototype:
int has_registered_sensor_region_event_handler(const char* handler_name);
Description:

This function is analogous to the has_registered_character_event_handler() function, but is for sensor regions rather than characters.

function diguyScenario::unregister_sensor_region_event_handler

Prototype:
int unregister_sensor_region_event_handler(const char* handler_name);
Description:

This function is analogous to the unregister_character_event_handler() function, but is for sensor regions rather than characters.

function diguyScenario::register_variable_event_handler

Prototype:
int register_variable_event_handler(const char* handler_name,
    diguyVariableCallback* callback,
    void* callback_user_data = 0);
Description:

This function is analogous to the register_character_event_handler() function, but is for variables rather than characters.
Callable From:

C++

function diguyScenario::register_variable_event_handler_from_library

Prototype:
int register_variable_event_handler_from_library(const char* handler_name,
    const char* library_name,
    const char* function_name,
    void* callback_user_data = 0);
Description:

This function is analogous to the register_character_event_handler_from_library() function, but is for variables rather than characters.

function diguyScenario::register_variable_event_handler_script

Prototype:
int register_variable_event_handler_script(const char* handler_name,
    const char* handler_script,
    const char* handler_script_type = 0);
Description:

This function is analogous to the register_character_event_handler_script() function, but is for variables rather than characters.

function diguyScenario::has_registered_variable_event_handler

Prototype:
int has_registered_variable_event_handler(const char* handler_name);
Description:

This function is analogous to the has_registered_character_event_handler() function, but is for variables rather than characters.

function diguyScenario::unregister_variable_event_handler

Prototype:
int unregister_variable_event_handler(const char* handler_name);
Description:

This function is analogous to the unregister_character_event_handler() function, but is for variables rather than characters.

Review Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::save_review_data

Prototype:
int save_review_data(const char* filename);
Description:

This function saves the current run of the scenario to the specified file, and other files whose names are derived from the passed filename. The passed filename should end with the extension ".dsr" (DI-Guy Review).

The review data can be reloaded later by calling the load() function, and passing the same filename.

The following is saved for later review:

all character positions and poses
sounds played by characters due to play_sound() and

fire_weapon_n_times() calls

Note that Paths, Waypoints, and Event Beads per se are not saved, but rather their effects on the characters' positions and poses.
Arguments:

filename file in which to save review data
Returns:

0 on success, -1 on failure
C++ Example:
// when shutting down the current run:
scenario->save_review_data("review0.dsr");

// when after action review is needed:
scenario->load("review0.dsr");

function diguyScenario::get_loaded_from_review_data

Prototype:
int get_loaded_from_review_data();
Returns:

1 if scenario was loaded from review data (from a .dsr file); 0 if not (from a .dss file)

function diguyScenario::set_history_type

Prototype:
int set_history_type(diguyHistoryType history_type);
Description:

This function sets what type of "history" will be kept for the scenario.

If time is run backwards in a scenario with history, the following will be "remembered" and replayed:

camera settings currently in the primary view's camera
signal trigger counts
enabled/disabled status of scene objects
sounds

The default is DIGUY_HISTORY_TYPE_NONE for scenarios created using the DI-Guy API, and DIGUY_HISTORY_TYPE_COMPLETE for scenarios created using the DI-Guy Scenario editor.
Arguments:

history_type history type to be used for the scenario

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 a complete history.

DIGUY_HISTORY_TYPE_LAST and DIGUY_HISTORY_TYPE_FIRST are not supported for scenario history.
Returns:

0 on success, -1 on failure

function diguyScenario::get_history_type

Prototype:
diguyHistoryType get_history_type();
Returns:

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

function diguyScenario::set_overall_history_type

Prototype:
void set_overall_history_type(diguyHistoryType overall_history_type);
Description:

This function sets the history type for this scenario, as well as the history types of all characters.

See also diguyScenario::set_history_type() and diguyCharacter::set_history_type().
Arguments:

history_type history type to be used for the scenario and all characters

function diguyScenario::get_overall_history_type

Prototype:
diguyHistoryType get_overall_history_type();
Description:

This function returns the overall history type of the scenario.

The return value will be:

DIGUY_HISTORY_TYPE_COMPLETE if history is enabled for the scenario and all characters
DIGUY_HISTORY_TYPE_PARTIAL if history is enabled for at least one of the scenario or any character, but not all
DIGUY_HISTORY_TYPE_NONE if history is not enabled for the scenario or any character

See also diguyScenario::get_history_type() and diguyCharacter::get_history_type().

function diguyScenario::get_replaying_history

Prototype:
int get_replaying_history();
Returns:

whether the scenario is playing back stored history

function diguyScenario::set_history_max_sound_instances

Prototype:
void set_history_max_sound_instances(int num_sound_instances);
Description:

This function sets how many sound instances are kept in memory when history is enabled. By keeping them in memory, users can "scrub" backwards in time and hear sounds that were started earlier in time and will be resumed at the proper offset into the sound. This function lets users balance that need with memory management.
Arguments:

num_sound_instances override system default of 100
Returns:

none

LOD Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::set_automatic_graphics_lod_switching

Prototype:
void set_automatic_graphics_lod_switching(int enable_graphics_lod_switching);
Description:

This function sets whether automatic graphics LOD switching should be enabled for certain graphics environments (see below).

By default it is enabled in DI-Guy Scenario, and disabled in a DI-Guy API application.

There are two ways that DI-Guy calculates the proper graphics LOD. For some graphics environments the calculation is done "manually", using data from a diguyViewCamera. In other environments the calculation is done by the graphics environment itself. The method used in each graphics environment is noted below.
OpenGL Version:

This function enables or disables automatic LOD switching. In this graphics environment LOD calculations are done by the renderer; information from the diguyViewCamera is not used.
Direct3D Version:

This function enables or disables automatic LOD switching. In this graphics environment LOD calculations are done relative to a diguyViewCamera.
DI-Guy Graphics API Version:

This function enables or disables automatic LOD switching. In this graphics environment LOD calculations are done by the renderer; information from the diguyViewCamera is not used.

function diguyScenario::get_automatic_graphics_lod_switching

Prototype:
int get_automatic_graphics_lod_switching();
Returns:

most recent setting of set_automatic_graphics_lod_switching()

function diguyScenario::set_default_lod_ranges

Prototype:
void set_default_lod_ranges(const char* character_type, float* ranges);
Description:

Sets the distances at which level of detail switching occurs for characters of the specified type. Existing characters are not affected; only newly created characters will have the specified LOD switching ranges.

Characters will display with the highest level of detail when viewed from a distance between ranges[0] and ranges[1]. Characters will not display at all when viewed from further away than the highest switching range.

Note: ranges[0] should almost always be 0.0.
Arguments:

character_type character type name, as returned by get_character_type_at_index()
ranges an array of 8 non-negative floating point numbers, each larger than the one before, specifying the LOD switching ranges in meters

Pass "all" for character_type to set the default ranges of all character types.

The table below indicates the number of polygons for one of the default soldier models in each level of detail, and the LOD switching ranges in effect before this function is called.
lod   polys  min   max
--------------------------
1    2300    0     5
2     900    5    10
3     550   10    20
4     280   20    40
5     130   40    70
6      60   70   100
7      40  100  1000
Callable From:

C++

function diguyScenario::set_scale_graphics_lod_ranges_from_view_settings

Prototype:
void set_scale_graphics_lod_ranges_from_view_settings(int do_scale);
Description:

This function sets whether view and camera settings such as field-of-view (FOV) and window size should be taken into account when determining the graphics LOD from a character's LOD ranges.

The camera settings that are used are taken from the current render camera, as set by set_render_camera(). This happens automatically in DI-Guy Scenario, but must be set manually in the DI-Guy SDK.

DI-Guy graphics LODs are distance-based, but this approach can be problematic if the current camera's FOV is very narrow; a narrow FOV essentially acts like a telephoto lens. In this case a character that is far away, and would therefore be rendered with few polygons, can actually be quite large in the 3D view.

Setting this flag to 1 will cause the FOV to be taken into account when calculating the effective distance of a character from the camera.

Many DI-Guy LOD distances assume that the vertical FOV of the view is around 40. Smaller FOVs will scale the distances larger so that LOD changes happen further out. Likewise larger FOVs will scale the distances smaller; in this case even nearby characters will appear small and therefore need less resolution.
Arguments:

do_scale - pass 1 to enable scaling, 0 to disable

function diguyScenario::get_scale_graphics_lod_ranges_from_view_settings

Prototype:
int  get_scale_graphics_lod_ranges_from_view_settings();
Returns:

most recent setting of set_scale_graphics_lod_ranges_from_view_settings()

function diguyScenario::set_automatic_motion_lod_switching

Prototype:
void set_automatic_motion_lod_switching(int enable_motion_lod_switching);
Description:

This function sets whether automatic motion LOD switching should be enabled.

By default it is enabled in DI-Guy Scenario, and disabled in a DI-Guy API application.

When running in a user application that uses the DI-Guy API, the primary view's camera's position and orientation must be kept consistent with the application's perception of current camera settings. A pointer to the primary view's camera can be obtained by calling get_scenario_camera().

The following describes the algorithm used by automatic motion LOD switching:

if a character is in front of the primary view's camera, the motion LOD is set to 1 (animate all joints)
else set motion LOD to 5 (stop animating everything but base position)

Note that if there are multiple views open on the scenario, the character must be behind all cameras for the motion LOD to be set to 5.

Also, if the history type of the character (as set by diguyCharacter::set_history_type()) is anything but DIGUY_HISTORY_TYPE_NONE, motion LOD 1 will be used since during scenario playback the character might be in front of any camera.

function diguyScenario::get_automatic_motion_lod_switching

Prototype:
int get_automatic_motion_lod_switching();
Description:

This function returns whether automatic motion LOD switching is be enabled for characters in the scenario, as set by set_automatic_motion_lod_switching().
Returns:

1 if LODs enabled; 0 if not

Script Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::eval_script

Prototype:
int eval_script(const char* script_text,
    int save_as_transient = 0,
    const char* script_type = NULL,
    const char* script_source = NULL);
Description:

This function sends the passed string through the script interpreter.
Arguments:

script_text string to be evaluated
save_as_transient flag stating whether script_text should be remembered as a transient event at the current scenario t; see push_transient_script_event()
script_type type of script contained in script_text; pass NULL to use scenario's default interpreter
script_source string identifying the 'source' of the script; will be printed in error output if there are syntax errors in the script
Returns:

0 on success, -1 on failure
C++ Example:
scenario->eval_script("signal1:trigger();",
0,
"lua",
"User Script");

function diguyScenario::eval_script_file

Prototype:
int eval_script_file(const char* filename,
    const char* script_type = NULL);
Description:

This function sends the contents of the specified file through the script interpreter.
Arguments:

filename filename of script to be evaluated
script_type type of script contained in file; pass NULL to use the scenario's default interpreter
Returns:

0 on success, -1 on failure
C++ Example:
scenario->eval_script_file("my_scripts.pl");

function diguyScenario::trigger_script

Prototype:
int trigger_script(const char* script_name);
Description:

This function manually triggers a script.
Arguments:

script_name name of the script to be triggered
Returns:

return result of script; 0 if script not found
Callable From:

C++
Script
Decision

function diguyScenario::trigger_script_delayed

Prototype:
void trigger_script_delayed(const char* script_name, float t_delay);
Description:

This function is similar to trigger_script(), but delays the trigger by the specified time.
Arguments:

script_name name of the script to be triggered
t_delay how many seconds to delay trigger
Callable From:

C++
Script
Decision

function diguyScenario::trigger_decision

Prototype:
int trigger_decision(const char* decision_name);
Description:

This function manually triggers a decision.
Arguments:

decision_name name of the decision to be triggered
Returns:

return result of decision; 0 if decision not found
Callable From:

C++
Script
Decision

function diguyScenario::trigger_decision_delayed

Prototype:
void trigger_decision_delayed(const char* decision_name, float t_delay);
Description:

This function is similar to trigger_decision(), but delays the trigger by the specified time.
Arguments:

decision_name name of the decision to be triggered
t_delay how many seconds to delay trigger
Callable From:

C++
Script
Decision

function diguyScenario::push_transient_script_event

Prototype:
void push_transient_script_event(float t, const char* script_text, const char* script_type);
Description:

This function places the passed script text on a list of scripts that should be re-evaluated when the scenario is replayed from review data.

Note that the script is not evaluated at this time. This can be done by calling eval_script() and passing 1 for the save_as_transient argument.

If the scenario is reset (as in a call to reset()), all transient scripts will be deleted. The transient script events can be saved and restored by calling save_transient_script_events() and load_transient_script_events(), respectively.
Arguments:

t time at which script should be re-evaluated during scenario playback
script_text Script to be evaluated
script_type Scripting language to use (lua)

A copy of the passed script text is made.
Returns:

0 on success, -1 on failure

function diguyScenario::clear_transient_script_events

Prototype:
void clear_transient_script_events();
Description:

This function deletes all transient script events.

function diguyScenario::save_transient_script_events

Prototype:
int save_transient_script_events(const char* filename);
Description:

This function saves the transient script events to the specified file. They can be restored by calling load_transient_script_events() with the same filename.
Arguments:

filename file in which transient script events should be saved
Returns:

0 on success, -1 on failure

function diguyScenario::load_transient_script_events

Prototype:
int load_transient_script_events(const char* filename);
Description:

This function loads transient script events saved by a call to save_transient_script_events().
Arguments:

filename file from which transient script events should be loaded
Returns:

0 on success, -1 on failure

function diguyScenario::load_package

Prototype:
int load_package(const char* filename,
    const char* language = NULL,
    int warn_if_not_found = 1);
Description:

This function creates a package object that points to an external file. If the language is not specified it will be determined based on the filename's extension. DI-Guy will attempt to derive an appropriate name for the package. In DI-Guy Scenario package dependencies are also extracted and loaded; currently this must be done manually in the SDK.

function diguyScenario::load_package_with_dependancy

Prototype:

int load_package_with_dependancy(const char* filename,
    const char* depends_on_package,
    const char* language = NULL,
    int warn_if_not_found = 1);

Description:

Documentation Pending

Meta-Action Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_character_type_num_postures

Prototype:
int get_character_type_num_postures(const char* character_type);
Description:

This function returns the number of postures the specified character type's actions support.

Use this function along with get_character_type_posture_at_index() to enumerate the character's postures.
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
Returns:

the number of postures the specified character type's actions support

function diguyScenario::get_character_type_posture_at_index

Prototype:
diguyMotionPosture get_character_type_posture_at_index(const char* character_type,
    int index);
Description:

This function returns the posture at the specified index.

Use this function along with get_character_type_num_postures() to enumerate the character's postures.
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
index index of the posture; indices start at 0
Returns:

the posture at the specified index

function diguyScenario::get_character_type_action_posture

Prototype:
diguyMotionPosture get_character_type_action_posture(const char* character_type,
    const char* action_name);
Description:

This function returns the overall posture of the specified action.

The results of this function call can be useful in calls to the diguyCharacter::get_action_from_description() function, if for example an action with the same posture but a faster speed is desired.
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
action_name the action to query
Returns:

the overall posture of the specified action

function diguyScenario::get_character_type_num_variants

Prototype:
int get_character_type_num_variants(const char* character_type);
Description:

This function returns the number of variants the specified character type's actions support.

Use this function along with get_character_type_variant_at_index() to enumerate the character's variants.

This function differs from get_character_type_action_num_variants() in that this function returns the number of variants of all actions of the character. The other function returns the number of variants of a single action.
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
Returns:

the number of variants the specified character type's actions support

function diguyScenario::get_character_type_variant_at_index

Prototype:
diguyMotionVariant get_character_type_variant_at_index(const char* character_type,
    int index);
Description:

This function returns the variant at the specified index.

Use this function along with get_character_type_num_variants() to enumerate the character's variants.

This function differs from get_character_type_action_variant_at_index() in that this function returns one of the variants of all actions of the character. The other function returns one of the variants of a single action.
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
index index of the posture; indices start at 0
Returns:

the variant at the specified index

function diguyScenario::get_character_type_action_primary_variant

Prototype:
diguyMotionVariant get_character_type_action_primary_variant(const char* character_type,
    const char* action_name);
Description:

This function returns the primary variant of the specified action.
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
action_name the action to query
Returns:

the overall variant of the specified action

function diguyScenario::get_character_type_action_num_variants

Prototype:
int get_character_type_action_num_variants(const char* character_type,
    const char* action_name);
Description:

This function returns the number of variants the specified action of the specified character type has.

Use this function along with get_character_type_action_variant_at_index() to enumerate the character's variants.

This function differs from get_character_type_num_variants() in that this function returns the number of variants of a single action of the character. The other function returns the number of variants of all actions.
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
action_name the action to query
Returns:

the number of variants of the specified action of the specified character type

function diguyScenario::get_character_type_action_variant_at_index

Prototype:
diguyMotionVariant get_character_type_action_variant_at_index(const char* character_type,
    const char* action_name,
    int index);
Description:

This function returns the variant at the specified index.

Use this function along with get_character_type_action_num_variants() to enumerate the character's variants.

This function differs from get_character_type_variant_at_index() in that this function returns one of the variants of a single action of the character. The other function returns one of the variants of all actions.
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
index index of the posture; indices start at 0
Returns:

the variant at the specified index

function diguyScenario::get_character_type_num_directions

Prototype:
int get_character_type_num_directions(const char* character_type);
Description:

This function returns the number of directions the specified character type's actions can move.

Use the get_character_type_direction_at_index() function to enumerate the directions available to a character.

The results of this function call can be useful in calls to the diguyCharacter::get_action_from_description() function.
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
Returns:

the number of directions the specified character type's actions can move

function diguyScenario::get_character_type_direction_at_index

Prototype:
diguyMotionDirection get_character_type_direction_at_index(const char* character_type,
    int index);
Description:

Use the get_character_type_num_directions() function to get the number of directions available to a character.

The results of this function call can be useful in calls to the diguyCharacter::get_action_from_description() function.
Arguments:

character_type character type name, as returned by get_character_type_at_index(), for example
index index of the direction; indices start at 0
Returns:

the direction at the specified index

Interaction Machine Functions

Interaction machines are designed to provide "conversation tree" type interactions with the scenario user. Interactions occur in the form of information text and multiple choice responses shown to the user.

The interaction can be as simple as showing a quick notification to the user and waiting for them to acknowledge it, or as complex as having a full-fledged conversation with another character in the scenario.

The name "interaction machine" comes from the fact that the interactions are based on a straight-forward state machine approach.

Interaction machines are for use in DI-Guy Scenario only, not with the DI-Guy API.

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_num_interaction_machines

Prototype:
int get_num_interaction_machines();
Returns:

number of interaction machines in the scenario

function diguyScenario::create_interaction_machine

Prototype:
diguyInteractionMachine* create_interaction_machine(const char* name);
Description:

This function creates a new interaction machine and returns a pointer to it.

Note that there is a shared interaction machine that always exists; a pointer to it can be obtained by calling get_shared_interaction_machine(). See that function for more details.
Arguments:

name name of the new interaction machine
Returns:

pointer of type diguyInteractionMachine; NULL if creation failed

function diguyScenario::destroy_interaction_machine

Prototype:
void destroy_interaction_machine(diguyInteractionMachine* interaction_machine);
Description:

This function destroys the passed interaction machine.

NOTE: This function should not be called on the shared interaction machine returned by get_shared_interaction_machine().
Arguments:

interaction_machine pointer to a diguyInteractionMachine to be destroyed

function diguyScenario::get_interaction_machine_at_index

Prototype:
diguyInteractionMachine* get_interaction_machine_at_index(int index);
Returns:

pointer of type diguyInteractionMachine; NULL if no interaction machine at the specified index
Arguments:

index index of the interaction machine; indices start at 0

function diguyScenario::find_interaction_machine

Prototype:
diguyInteractionMachine* find_interaction_machine(const char* name);
Description:

This function returns a pointer to the specified interaction machine.
Arguments:

name name of interaction machine to be found
Returns:

pointer of type diguyInteractionMachine; NULL if not found

function diguyScenario::get_active_interaction_machine

Prototype:
diguyInteractionMachine* get_active_interaction_machine();
Description:

This function returns a pointer to the "active" interaction machine. Only one interaction machine can be showing and accepting input at a time.
Returns:

pointer of type diguyInteractionMachine; NULL if no interaction machine is active.

function diguyScenario::get_shared_interaction_machine

Prototype:
diguyInteractionMachine* get_shared_interaction_machine();
Description:

This function returns a pointer to the shared interaction machine that is always available.

This shared interaction machine is convenient for quick alerts, notifications, or questions. Because it is shared, however, most or all of its parameters need to be set each time it is to be shown.

Do not call destroy_interaction_machine() on the returned object. It is owned by the scenario.
Returns:

pointer of type diguyInteractionMachine; should never be NULL

function diguyScenario::show_notification_with_shared_interaction_machine

Prototype:
int show_notification_with_shared_interaction_machine(const char* heading,
    const char* info,
    int pause_scenario = 0,
    const char* input_text = NULL,
    int ui_appearance = diguyInteractionMachine::UI_APPEARANCE_NOTIFICATION);
Description:

This is a convenience function for using the shared interaction machine to show a notification to the user. It sets parameters of the shared interaction machine based on the passed info and shows/activates the machine.
Arguments:

heading text that will be at the top of the dialog
info informational text
pause_scenario pass 1 to pause the scenario while the interaction machine is active, 0 to leave the scenario running if it was when this function was called
input_text text that user will have to click to dismiss the interaction machine; something like "Ok" is typical
ui_appearance the color theme of the interaction machine

See the diguyInteractionMachine documentation for more information on what the various parameters mean.
Returns:

0 on success, -1 on failure
Lua Example:
this_scenario:show_notification_with_shared_interaction_machine(
"WARNING!",
"Moving any closer to the harmful gas is not advised.",
0,
"Ok",
diguyInteractionMachine_UI_APPEARANCE_NOTIFICATION);

I-Guy Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_iguy_controller

Prototype:
diguyIGuyController* get_iguy_controller();
Description:

This function returns a pointer to the I-Guy controller object of the scenario.
Returns:

pointer of type diguyIGuyController; should never be NULL

Label Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::find_or_create_label

Prototype:
diguyViewLabel* find_or_create_label(const char* name);
Description:

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

name name of the diguyViewLabel to find or create
Returns:

pointer of type diguyViewLabel; should never be NULL

function diguyScenario::find_label

Prototype:
diguyViewLabel* find_label(const char* name);
Description:

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

name name of diguyViewLabel to be found
Returns:

pointer of type diguyViewLabel; NULL if not found

function diguyScenario::destroy_label

Prototype:
int destroy_label(diguyViewLabel* label);
Description:

This function destroys the passed in diguyViewLabel.
Arguments:

label pointer to a diguyViewLabel
Returns:

0 on success, -1 on failure

function diguyScenario::get_num_labels

Prototype:
int    get_num_labels();
Returns:

The number of diguyViewLabel objects in the scenario.

function diguyScenario::get_label_at_index

Prototype:
diguyViewLabel* get_label_at_index(int index);
Returns:

The diguyViewLabel at the given index.
Arguments:

index index of the diguyViewLabel; indices start at 0

function diguyScenario::reset_labels

Prototype:
void reset_labels();
Description:

This function removes all diguyViewLabels in the scenario.

function diguyScenario::send_label_to_front

Prototype:
void send_label_to_front(diguyViewLabel* label);
Description:

This function moves the specified diguyViewLabel to the front of the drawing list. This is sometimes necessary if labels overlap.
Arguments:

label pointer to diguyViewLabel to move

function diguyScenario::send_label_to_back

Prototype:
void send_label_to_back(diguyViewLabel* label);
Description:

This function moves the specified diguyViewLabel to the back of the drawing list. This is sometimes necessary if labels overlap.
Arguments:

label pointer to diguyViewLabel to move

Button Panel Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::find_or_create_panel

Prototype:
diguyViewButtonPanel* find_or_create_panel(const char* name,
    int horizontal = 0,
    int title = 1);
Description:

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

name name of the diguyViewButtonPanel to find or create
Returns:

pointer of type diguyViewButtonPanel; should never be NULL

function diguyScenario::find_panel

Prototype:
diguyViewButtonPanel* find_panel(const char* name);
Description:

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

name name of diguyViewButtonPanel to be found
Returns:

pointer of type diguyViewButtonPanel; NULL if not found

function diguyScenario::destroy_panel

Prototype:
int destroy_panel(diguyViewButtonPanel* panel);
Description:

This function destroys the passed in diguyViewButtonPanel.
Arguments:

panel pointer to a diguyViewButtonPanel
Returns:

0 on success, -1 on failure

function diguyScenario::get_num_panels

Prototype:
int    get_num_panels();
Returns:

The number of diguyViewButtonPanel objects in the scenario.

function diguyScenario::get_panel_at_index

Prototype:
diguyViewButtonPanel* get_panel_at_index(int index);
Returns:

The diguyViewButtonPanel at the given index.
Arguments:

index index of the diguyViewButtonPanel; indices start at 0

Misc. DI-Guy AI Functions

Note that these functions require a DI-Guy AI license, and that DI-Guy AI has been initialized by a call to diguy_ai_initialize().

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_num_minds

Prototype:
int get_num_minds();
Description:

This function returns the number of AI minds that are available to AI agent characters.
Returns:

number of available minds

function diguyScenario::get_mind_name_at_index

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

name of the AI mind at the specified index

function diguyScenario::is_valid_character_pointer

Prototype:
int is_valid_character_pointer(diguyCharacter* character);
Description:

This function tests if a diguyCharacter pointer is a valid pointer. This is done by comparing the passed address to those of all characters in the scenario. The function is not exceedingly fast but can be useful when building AI that functions in a networked environment.
Returns:

0 if invalid, 1 if valid

function diguyScenario::is_valid_character_group_pointer

Prototype:
int is_valid_character_group_pointer(diguyCharacterGroup* character_group);
Description:

This function tests if a diguyCharacterGroup pointer is a valid pointer. This is done by comparing the passed address to those of all groups in the scenario. The function is not exceedingly fast but can be useful when building AI that functions in a networked environment.
Returns:

0 if invalid, 1 if valid

Crowd Functions

These functions control accessing diguyCrowd objects. Crowds are used by DI-Guy AI.

Note that these functions require a DI-Guy AI license, and that DI-Guy AI has been initialized by a call to diguy_ai_initialize().

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::create_crowd

Prototype:
diguyCrowd* create_crowd(const char* name,
    int make_companion_of_all = 1);
Description:

This function creates a new crowd and returns a pointer to it.

A Lua object is also created that has a pointer to this crowd. This object can be retrieved by calling find_lua_crowd(crowd_name) or find_lua_crowd(diguyCrowd* pointer) in lua.
Arguments:

name name of crowd to be created
make_companion_of_all pass 1 to make this crowd a companion of all existing crowds
Returns:

pointer of type diguyCrowd

function diguyScenario::destroy_crowd

Prototype:
int destroy_crowd(diguyCrowd* crowd,
    int also_destroy_crowd_members = 0,
    int also_destroy_path_shapes = 0,
    int delay_destruction = 0);
Description:

This function destroys a crowd. It can also optionally destroy the characters that are crowd members, and the path shape that is associated with the crowd.
Arguments:

crowd pointer to a diguyCrowd
also_destroy_crowd_members pass 1 to also destroy crowd member characters
also_destroy_path_shapes pass 1 to also destroy crowd- associated path shapes
delay_destruction pass 1 to wait till the next update call to destroy the crowd; can avoid crashes when AI's receive destruction messages
Returns:

0 on success, -1 on failure

function diguyScenario::get_num_crowds

Prototype:
int get_num_crowds();
Returns:

the number of crowds in the scenario

function diguyScenario::get_crowd_at_index

Prototype:
diguyCrowd* get_crowd_at_index(int index);
Returns:

pointer of type diguyCrowd; NULL if no crowd at the specified index
Arguments:

index index of the crowd; indices start at 0

function diguyScenario::get_unique_crowd_name

Prototype:
const char* get_unique_crowd_name(const char* base_name);
Returns:

A unique name based on base_name, e.g. "my_crowd7" from "my_crowd".
Arguments:

base_name base string from which to build a unique name

function diguyScenario::find_crowd

Prototype:
diguyCrowd* find_crowd(const char* crowd_name);
Description:

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

name name of crowd to be found
Returns:

pointer of type diguyCrowd; NULL if not found

function diguyScenario::find_or_create_crowd

Prototype:
diguyCrowd* find_or_create_crowd(const char* crowd_name,
    int make_companion_of_all = 1);
Description:

This function returns a pointer to the crowd with the given name. A new crowd with the given name will be created if it doesn't already exist.
Arguments:

name name of the crowd to find or create
make_companion_of_all pass 1 to make this crowd a companion of all existing crowds
Returns:

pointer of type diguyCrowd; should never be NULL

function diguyScenario::set_create_network_crowds

Prototype:
void set_create_network_crowds(int do_create);
Description:

This function sets whether crowds should be created for incoming network entities.
Arguments:

do_create pass 1 to create network crowds; 0 to not

function diguyScenario::get_create_network_crowds

Prototype:
int get_create_network_crowds();
1 if network crowds will be created; 0 if not

Crowd Profile Functions

These functions control accessing diguyCrowdProfile objects. Crowd profiles are used by DI-Guy AI.

Note that these functions require a DI-Guy AI license.

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::create_crowd_profile

Prototype:
diguyCrowdProfile* create_crowd_profile(const char* name);
Description:

This function creates a new crowd profile and returns a pointer to it.
Arguments:

name name of crowd profile to be created
Returns:

pointer of type diguyCrowdProfile

function diguyScenario::destroy_crowd_profile

Prototype:
int destroy_crowd_profile(diguyCrowdProfile* crowd_profile);
Description:

This function destroys a crowd profile.
Arguments:

crowd_profile pointer to a diguyCrowdProfile
Returns:

0 on success, -1 on failure

function diguyScenario::get_num_crowd_profiles

Prototype:
int get_num_crowd_profiles();
Returns:

The number of crowd profiles in the scenario.

function diguyScenario::get_crowd_profile_at_index

Prototype:
diguyCrowdProfile* get_crowd_profile_at_index(int index);
Returns:

pointer of type diguyCrowdProfile; NULL if no crowd profile at the specified index
Arguments:

index index of the crowd profile; indices start at 0

function diguyScenario::find_crowd_profile

Prototype:
diguyCrowdProfile* find_crowd_profile(const char* name);
Description:

This function returns a pointer to the specified crowd profile.
Arguments:

name name of crowd profile to be found
Returns:

pointer of type diguyCrowdProfile; NULL if not found

Load Manager Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_character_load_manager

Prototype:
diguyLoadManager* get_character_load_manager();
Returns:

pointer of type diguyLoadManager; this scenario's character load manager

Octtree Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::force_octtree_generation

Prototype:
int force_octtree_generation();
Description:

This function forces the octtree to rebuild if it's out of date.

function diguyScenario::add_character_to_octtree

Prototype:
void add_character_to_octtree(diguyCharacter* character,
    int use_bounding_box_only = 0);
Description:

Documentation Pending

function diguyScenario::remove_character_from_octtree

Prototype:
void remove_character_from_octtree(diguyCharacter* character);
Description:

Documentation Pending

function diguyScenario::preload_octtree

Prototype:
int preload_octtree(const char* character_type, const char* appearance);
Description:

Documentation Pending

function diguyScenario::check_visibility

Prototype:
int check_visibility(float x1, float y1, float z1,
    float x2, float y2, float z2);
Description:

This function uses the octtree to check if the path between x1, y1, z1 and x2, y2, z2 has any static obstructions.
Returns:

1 if the path is clear, 0 if static obstructions are present.

Altitude Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::set_default_character_altitude_function

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

This function sets a default altitude function that will be added to all new characters. It can be overridden on a per-character basis by a call to diguyCharacter::set_altitude_function(). See that function for details.
Callable From:

C++

function diguyScenario::set_altitude_function

Prototype:
void set_altitude_function(diguyScenarioAltitudeFunction* altitude_function);
Description:

This function sets a generic altitude function for the scenario that is used for local path clamping and other operations that require the altitude at specific x, y coordinates to be calculated.

The ground_clamp() function can also optionally use the registered function.

DI-Guy Scenario has a default altitude function; replacing the default function is not recommended.
Callable From:

C++

function diguyScenario::get_altitude_function

Prototype:
diguyScenarioAltitudeFunction* get_altitude_function();
Returns:

the altitude function for the scenario as set by set_altitude_function()
Callable From:

C++

function diguyScenario::set_altitude_max_climb

Prototype:

void set_altitude_max_climb(float altitude_max_climb);

function diguyScenario::get_altitude_max_climb

Prototype:

float get_altitude_max_climb();

function diguyScenario::set_altitude_max_drop

Prototype:

void set_altitude_max_drop(float altitude_max_drop);

function diguyScenario::get_altitude_max_drop

Prototype:

float get_altitude_max_drop();

Impact and Hit Detection Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::set_default_intersection_function

Prototype:
static void set_default_intersection_function(diguyScenarioIntersectionFunction* intersection_function);
Description:

Sets the default intersection function. This function will be used to determine whether there is an intersection between a specified ray and the world.

function diguyScenario::set_intersection_function

Prototype:

void set_intersection_function(diguyScenarioIntersectionFunction* intersection_function);

function diguyScenario::trigger_detonation

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

Creates a detonation using the specified munition name. If the DI-Guy networking module is enabled the detonation is broadcast over the network.
Arguments:

munition_name name of the munition to detonate; this will potentially trigger special effects depending on the munition
x, y, z location of the detonation
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.

function diguyScenario::find_character_at_screen_coords

Prototype:
diguyImpact* find_character_at_screen_coords(diguyView* view,
    float sx,
    float sy);
Description:

This function checks for intersection against characters in the specified view.

To check for intersections against both characters and scene objects, call get_intersection_at_screen_coords().

The returned diguyImpact pointer is owned by the scenario and should not be deleted. It will remain valid until the next call to any one of the following functions:

find_character_at_screen_coords()
get_impact_at_screen_coords()
get_intersection_at_screen_coords()
This function should only be called from a DI-Guy Scenario Plugin.
Arguments:

view view to check
sx, sy view coordinates to check
Returns:

pointer of type diguyImpact; NULL if no character intersected
Callable From:

DI-Guy Scenario Plugin

function diguyScenario::get_impact_at_screen_coords

Prototype:
diguyImpact* get_impact_at_screen_coords(diguyView* view,
    float sx,
    float sy,
    int use_octtree = 0);
Description:

This function creates an impact object based on the sx and sy in the specified view. This function will trigger an impact callback on individuals who are touched, (it will not however kill characters who don't have impact callbacks.

The returned diguyImpact pointer is owned by the scenario and should not be deleted. It will remain valid until the next call to any one of the following functions:

find_character_at_screen_coords()
get_impact_at_screen_coords()
get_intersection_at_screen_coords()
This function should only be called from a DI-Guy Scenario Plugin.
Arguments:

view view to check
sx, sy view coordinates to check
use_octtree use the octtree; will not test against all characters unless they are explicitly added, but much faster
Returns:

pointer of type diguyImpact;
Callable From:

DI-Guy Scenario Plugin

function diguyScenario::get_intersection_at_screen_coords

Prototype:
diguyImpact* get_intersection_at_screen_coords(diguyView* view,
    float sx,
    float sy,
    int use_octtree = 0);
Description:

This function checks for intersection against the world and characters in the specified view. Unlike the function get_impact_at_screen_coords(), this function doesn't trigger callbacks; instead, it just fills out the impact info.

The returned diguyImpact pointer is owned by the scenario and should not be deleted. It will remain valid until the next call to any one of the following functions:

find_character_at_screen_coords()
get_impact_at_screen_coords()
get_intersection_at_screen_coords()
This function should only be called from a DI-Guy Scenario Plugin.
Arguments:

view view to check
sx, sy view coordinates to check
use_octtree use the octtree; will not test against all characters unless they are explicitly added, but much faster
Returns:

diguyImpact with the xyz location of the intersection; NULL if there was nothing to intersect there
Callable From:

DI-Guy Scenario Plugin

function diguyScenario::intersect_static_geometry

Prototype:
int intersect_static_geometry(
    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 = NULL, float* normal_y = NULL, float* normal_z = NULL,
    int use_callback = 1);
Description:

This function checks for intersection against the world and returns basic collision results.

This function will only return valid results in environments where the DI-Guy geometry octtree is available; currently that is when using OpenGL and the DI-Guy flight geometry loader. DI-Guy Scenario is such a case.
Arguments:

origin_x, origin_y, origin_z starting location of the ray trace
dir_x, dir_y, dir_z direction of ray trace
max_distance_to_test max distance ray will travel; -1.0 will test an infinitely long ray
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.
Returns:

1 if intersection occurred, 0 if not.

function diguyScenario::ground_clamp

Prototype:
float ground_clamp(float x, float y, float z,
    int* valid = NULL,
    int use_altitude_function = 1,
    int use_octtree = 0);
Description:

This function returns the z height, or altitude, under the passed x, y, z point.

Two methods can be used to determine the altitude: using the scenario altitude function or using the internal octtree calculated from terrain geometry.

See set_altitude_function() for information on the scenario altitude function. In DI-Guy Scenario it defaults to using the octtree when it's available, and falls back on using a screen render and Z-buffer check when it's not.

Note that the octtree is not always available. In general it is available only in DI-Guy Scenario, or when the built-in OpenGL renderer and DI-Guy flight geometry loader are in use.
Arguments:

x, y, z world location to ground clamp
valid optional pointer to get an explicit result if anything was hit
use_altitude_function pass 1 to use scenario altitude function
use_octtree pass 1 to use internal octtree
Returns:

new_z if ground clamp was possible, original z if not

Impact Callback Functions:

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::set_fire_weapon_intersection_function

Prototype:
int set_fire_weapon_intersection_function(diguyScenarioFindImpactOnLineFunction* impact_function);
Description:

The following prototype should be used for the impact function:
int impact_func(diguyImpact* impact,
float from_x,
float from_y,
float from_z,
float to_x,
float to_y,
float to_z,
diguyScenario* s);
When a character fires their weapon, DI-Guy calls this function with a pointer to the diguyImpact that must be filled out, the x, y, z position of the shot, and the target x, y, z.

The impact function should then do an intersection test and return 1 if a hit occurred.

By default the impact should have both the attacker and the munition type already specified. The intersection function must at least call diguyImpact::set_valid_impact() for the system to consider the impact valid. See diguyImpact for a sample function.
Callable From:

C++

function diguyScenario::set_default_fire_weapon_intersection_function

Prototype:
static void set_default_fire_weapon_intersection_function(diguyScenarioFindImpactOnLineFunction* impact_function);
Description:

This function sets an impact function that will be added to all new scenarios. It can be overridden by an explicit call to diguyScenario::set_fire_weapon_intersection_function(). See that function for details.
Callable From:

C++

function diguyScenario::map_color_to_impact

Prototype:
diguyImpact* map_color_to_impact(char r, char g, char b);
Description:

Most DI-Guy visual objects (e.g., characters, path shapes, waypoints) have a unique identified, or UID. In many cases these UID values can be coded into 24-bit color values. This can be useful for implementing some types of intersection detection functions, in which each visual object is rendered with a different color.

This function will take the passed color values and update internal DI-Guy state of which objects objects have been hit.

It will also return an impact record containing information a subset of that information.

This can include:

the hit character, if one was hit
the hit link and shape of the character
the hit scene object, if one was hit

Note that the returned impact pointer is owned by DI-Guy and is temporary. The information you need from it should be immediately read, and the pointer should not be stored.

function diguyScenario::get_last_env_impact_info

Prototype:
diguyImpact* get_last_env_impact_info();
Description:

When the callback with id diguyScenario::CALLBACK_ID_SCENE_OBJECT_IMPACT is called, this function will return the impact object containing information about that impact.

There may be multiple impacts that result from some operations. In this case this function should be called multiple times, until it returns NULL. When processing of data from each successive impact is done, call set_last_impact_been_processed() to queue up the next impact object for processing.

The maximum number of unprocessed impacts is finite, and set by the function set_max_unprocessed_impacts().

Note that the returned impact pointers are owned by DI-Guy and are temporary. The information you need from them should be immediately read, and the pointers should not be stored.

function diguyScenario::set_last_impact_been_processed

Prototype:
void set_last_impact_been_processed();
Description:

Reading of data from the last impact information will be considered complete when this function is called.

function diguyScenario::set_last_env_impact_info

Prototype:
void set_last_env_impact_info(const diguyImpact& impact);
Description:

This function will add the passed impact object to the list of impact objects to be processed by calls to get_last_env_impact_info(). An internal copy of the impact object is made.

function diguyScenario::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.

AI Line of Sight, Intersection Callback Functions

diguyScenario has a number of number of replaceable functions that govern intersecting and detecting the world. See the following functions to identify the full set of functionality that's necessary to make DI-Guy characters interact with the environment.

function diguyScenario::set_default_point_los_function

Prototype:
int set_default_point_los_function(diguyPointLOSFunction* point_los_function);
Description:

This function sets a default point line of sight function that will be added to all new characters. It can be overridden by an explicit call to diguyCharacter::set_point_los_function(). See that function for details.
Callable From:

C++

function diguyScenario::set_default_character_los_function

Prototype:
int set_default_character_los_function(diguyCharacterLOSFunction* character_los_function);
Description:

This function sets a default character line of sight function that will be added to all new characters. It can be overridden by an explicit call to diguyCharacter::set_character_los_function(). See that function for details.
Callable From:

C++

function diguyScenario::set_default_agent_feeler_function

Prototype:
int set_default_agent_feeler_function(diguyFeelerFunction* feeler_function);
Description:

This function sets a default feeler function that will be added to all new DI-Guy AI agents. It can be overridden by an explicit call to diguyCharacter::agent_set_feeler_function().

See the "User-Defined Feelers" section in diguyCharacter.h for more information.
Arguments:

feeler_function pointer to user-defined feeler function
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguyScenario::exp_intersect_geometry

Prototype:
diguyIntersectionResult exp_intersect_geometry(
    float origin_x, float origin_y, float origin_z,
    float dir_x,    float dir_y,    float dir_z,
    float max_distance_to_test,
    int use_callback = 1);
Description:

Experimental intersection-detection function.
Arguments:

origin_x,origin_y,origin_z starting point
dir_x,dir_y,dir_z direction vector
max_distance_to_test distance to test to
use_callback 1 to use
Returns:

diguyIntersectionResult structure

Path Planning and Regions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::find_or_create_region

Prototype:
diguyRegion* find_or_create_region(const char* name);
Description:

This function returns a pointer to the region with the given name. A new region with the given name will be created if it doesn't already exist.
Arguments:

name name of the region to find or create
Returns:

pointer of type diguyRegion; should never be NULL

function diguyScenario::find_region

Prototype:
diguyRegion* find_region(const char* name);
Description:

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

name name of region to be found
Returns:

pointer of type diguyRegion; NULL if not found

function diguyScenario::create_region

Prototype:
diguyRegion* create_region(const char* name);
Description:

This function creates a new diguyRegion and returns a pointer to it.
Arguments:

name name of the new region object
Returns:

pointer of type diguyRegion

function diguyScenario::destroy_region

Prototype:
void destroy_region(diguyRegion* region);
Description:

This function destroys the passed region.
Arguments:

region region to destroy

function diguyScenario::get_num_regions

Prototype:
int get_num_regions();
Returns:

number of regions in the scenario

function diguyScenario::get_region_at_index

Prototype:
diguyRegion* get_region_at_index(int index);
Returns:

pointer of type diguyRegion; NULL if no region at the specified index
Arguments:

index index of the region; indices start at 0

function diguyScenario::find_navigation_path

Prototype:
int find_navigation_path(float x1, float y1, float z1,
    float x2, float y2, float z2,
    const char* via_region,
    diguyPathShape* path_shape,
    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_repulsive_regions = 100.0f);
Description:

The scenario will attempt to create a navigation path on the via_region. An A* path planning algorithm is used to find the path. See also diguyCharacter::agent_move_to_point() and diguyCharacter::agent_move_to_point_via_subregions().
Arguments:

x1, y1, z1 start location
x2, y2, z2 end location
via_region name of the region to run A* on
path_shape path shape that stores the created path
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.
Returns:

0 on success, -1 on failure

function diguyScenario::set_max_distance_planning_multiplier

Prototype:
void set_max_distance_planning_multiplier(float mul);
Description:

Sets an upper limit on how far a character is willing to travel as a multiple of the straight line distance between point A and point B before declaring that it can't get to a location.

Note that internally the straight line distance is forced to have a lower bound of 10 meters, so a character is always willing to travel a minimum of 10 * max_distance_planning_multiplier meters.

Defaults to -1, which means off.

function diguyScenario::get_max_distance_planning_multiplier

Prototype:
float get_max_distance_planning_multiplier();
Returns:

float constant that's used to decide if planner should give up; -1 means off

function diguyScenario::get_time_spent_path_planning_this_frame

Prototype:
float get_time_spent_path_planning_this_frame();
Description:

This function returns in seconds how much time has been spent path planning during the current frame. It can be used to avoid 100 characters simultaneously hitting the path planner.
Returns:

time in seconds

function diguyScenario::set_multithreaded_path_planning_enabled

Prototype:
void set_multithreaded_path_planning_enabled(int value);
Description:

This function enables the path planner to run in a background thread. Note this only occurs if the diguyCharacter::agent_move_to_point_bg() or diguyCharacter::agent_move_to_point_via_subregions_bg() api functions are used.

By default the multi-threaded path planner is on.

function diguyScenario::get_multithreaded_path_planning_enabled

Prototype:
int get_multithreaded_path_planning_enabled();
Returns:

Returns 1 if the path planner is enabled to run in a background thread. By default the multi-threaded path planner is on.

Formation Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_num_formations

Prototype:
int get_num_formations();
Returns:

number of formations in the scenario

function diguyScenario::get_formation_at_index

Prototype:
diguyFormation* get_formation_at_index(int index);
Returns:

pointer of type diguyFormation; NULL if no formation at the specified index
Arguments:

index index of the formation; indices start at 0

function diguyScenario::find_formation

Prototype:
diguyFormation* find_formation(const char* name);
Description:

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

name name of formation to be found
Returns:

pointer of type diguyFormation; NULL if not found

function diguyScenario::find_formation_of_size

Prototype:
diguyFormation* find_formation_of_size(int size);
Description:

This function returns a pointer to the first formation it finds of a given size.
Arguments:

size size of formation to be found
Returns:

pointer of type diguyFormation; NULL if not found

function diguyScenario::create_formation

Prototype:
diguyFormation* create_formation(const char* name);
Description:

This function creates a new formation and returns a pointer to it.
Arguments:

name name of the new formation
Returns:

pointer of type diguyFormation

function diguyScenario::find_or_create_formation

Prototype:
diguyFormation* find_or_create_formation(const char* name);
Description:

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

name name of the formation to find or create
Returns:

pointer of type diguyFormation; should never be NULL

function diguyScenario::destroy_formation

Prototype:
int destroy_formation(diguyFormation* formation);
Description:

This function destroys a formation.
Arguments:

formation pointer to a diguyFormation
Returns:

0 on success, -1 on failure

DI-Guy Scenario User Interface Functions

These functions show or hide various supplemental visuals in the DI-Guy Scenario 3D window. They will have no effect outside of DI-Guy Scenario.

They correspond to the UI in the DI-Guy Scenario page Scenario Objects | Scenario Objects | Visibility.

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::set_action_bead_labels_visible

Prototype:

void set_action_bead_labels_visible(diguyVisibleFlag vflag);

function diguyScenario::set_aim_trajectories_visible

Prototype:

void set_aim_trajectories_visible(diguyVisibleFlag vflag);

function diguyScenario::set_author_selection_handles_visible

Prototype:

void set_author_selection_handles_visible(diguyVisibleFlag vflag);

function diguyScenario::set_bead_array_visible

Prototype:

void set_bead_array_visible(diguyVisibleFlag vflag);

function diguyScenario::set_character_labels_visible

Prototype:

void set_character_labels_visible(diguyVisibleFlag vflag);

function diguyScenario::set_character_visible

Prototype:

void set_character_visible(diguyVisibleFlag vflag);

function diguyScenario::set_crowd_behavior_visible

Prototype:

void set_crowd_behavior_visible(diguyVisibleFlag flag);

function diguyScenario::set_crowd_feelers_visible

Prototype:

void set_crowd_feelers_visible(diguyVisibleFlag flag);

function diguyScenario::set_crowd_influence_visible

Prototype:

void set_crowd_influence_visible(diguyVisibleFlag flag);

function diguyScenario::set_crowd_regions_visible

Prototype:

void set_crowd_regions_visible(diguyVisibleFlag flag);

function diguyScenario::set_light_array_visible

Prototype:

void set_light_array_visible(diguyVisibleFlag vflag);

function diguyScenario::set_lua_objects_visible

Prototype:

void set_lua_objects_visible(diguyVisibleFlag flag);

function diguyScenario::set_mesh_region_array_visible

Prototype:

void set_mesh_region_array_visible(diguyVisibleFlag vflag);

function diguyScenario::set_sensor_region_array_visible

Prototype:

void set_sensor_region_array_visible(diguyVisibleFlag vflag);

function diguyScenario::set_spath_visible

Prototype:

void set_spath_visible(diguyVisibleFlag vflag);

function diguyScenario::set_waypoint_array_visible

Prototype:

void set_waypoint_array_visible(diguyVisibleFlag vflag);

function diguyScenario::get_action_bead_labels_visible

Prototype:

diguyVisibleFlag get_action_bead_labels_visible();

function diguyScenario::get_aim_trajectories_visible

Prototype:

diguyVisibleFlag get_aim_trajectories_visible();

function diguyScenario::get_author_selection_handles_visible

Prototype:

diguyVisibleFlag get_author_selection_handles_visible();

function diguyScenario::get_bead_array_visible

Prototype:

diguyVisibleFlag get_bead_array_visible();

function diguyScenario::get_character_labels_visible

Prototype:

diguyVisibleFlag get_character_labels_visible();

function diguyScenario::get_character_visible

Prototype:

diguyVisibleFlag get_character_visible();

function diguyScenario::get_crowd_behavior_visible

Prototype:

diguyVisibleFlag get_crowd_behavior_visible();

function diguyScenario::get_crowd_feelers_visible

Prototype:

diguyVisibleFlag get_crowd_feelers_visible();

function diguyScenario::get_crowd_influence_visible

Prototype:

diguyVisibleFlag get_crowd_influence_visible();

function diguyScenario::get_crowd_regions_visible

Prototype:

diguyVisibleFlag get_crowd_regions_visible();

function diguyScenario::get_light_array_visible

Prototype:

diguyVisibleFlag get_light_array_visible();

function diguyScenario::get_lua_objects_visible

Prototype:

diguyVisibleFlag get_lua_objects_visible();

function diguyScenario::get_mesh_region_array_visible

Prototype:

diguyVisibleFlag get_mesh_region_array_visible();

function diguyScenario::get_sensor_region_array_visible

Prototype:

diguyVisibleFlag get_sensor_region_array_visible();

function diguyScenario::get_spath_visible

Prototype:

diguyVisibleFlag get_spath_visible();

function diguyScenario::get_waypoint_array_visible

Prototype:

diguyVisibleFlag get_waypoint_array_visible();

function diguyScenario::set_hide_author_selection_handles_during_play

Prototype:

void set_hide_author_selection_handles_during_play(int visible);

function diguyScenario::get_hide_author_selection_handles_during_play

Prototype:

int get_hide_author_selection_handles_during_play();

DI-Guy Weapon Fire Effects Functions

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::get_weapon_fire_effects_enabled

Prototype:
int get_weapon_fire_effects_enabled();
Returns:

If weapon fire will create light flashes.

function diguyScenario::set_weapon_fire_effects_enabled

Prototype:
int set_weapon_fire_effects_enabled(int enabled);
Description:

Sets if weapon fire will create light flashes.

function diguyScenario::get_num_active_fire_effects

Prototype:
int get_num_active_fire_effects();
Returns:

The number of light flashes that are currently active

function diguyScenario::get_weapon_fire_effect_data

Prototype:
int get_weapon_fire_effect_data(int index, float * radius, 
    float * position_x, float * position_y, float * position_z, 
    float * color_r, float * color_g, float * color_b,
    float * falloff_r,
    float * falloff_rsq);
Description:

This function gets the data needed for producing a weapon flash light source in the world. See diguyOglGraphicsShaderProgram::update_light_uniforms() for an example of its use. In the default OpenGL renderer the convenience function diguy_ogl_apply_active_lights() does this work for you.

DI-Guy Scenario selection functions

These functions allow you to get and set the currently active item in the DI-Guy Scenario UI.

They correspond to the UI in the DI-Guy Scenario Scenario Objects page.

Unless otherwise specified, callable from:

C++
Script

function diguyScenario::set_current_character

Prototype:
int set_current_character(diguyCharacter* current_character);
Description:

Sets the current selected character in scenario
Returns:

0 on success, -1 on failure

function diguyScenario::get_current_character

Prototype:
diguyCharacter* get_current_character();
Returns:

The current selected character in scenario

function diguyScenario::set_current_crowd

Prototype:
int set_current_crowd(diguyCrowd* current_crowd);
Description:

Sets the current selected crowd in scenario
Returns:

0 on success, -1 on failure

function diguyScenario::get_current_crowd

Prototype:
diguyCrowd* get_current_crowd();
Returns:

The current selected crowd in scenario

function diguyScenario::set_current_crowd_profile

Prototype:
int set_current_crowd_profile(diguyCrowdProfile* current_profile);
Description:

Sets the active crowd profile, which determines the attributes of subsequently-created crowds. See diguyCrowdProfile.
Returns:

0 on success, -1 on failure

function diguyScenario::set_current_crowd_profile_by_name

Prototype:
int set_current_crowd_profile_by_name(const char* crowd_profile_name);
Description:

Sets the active crowd profile by name.
Returns:

0 on success, -1 on failure

function diguyScenario::get_current_crowd_profile

Prototype:
diguyCrowdProfile* get_current_crowd_profile();
Returns:

Active crowd profile

function diguyScenario::set_current_region

Prototype:
int set_current_region(diguyRegion* current_region);
Description:

Sets the current region. See diguyRegion.
Returns:

0 on success, -1 on failure

function diguyScenario::get_current_region

Prototype:
diguyRegion* get_current_region();
Returns:

Current region.

Particle System Functions

function diguyScenario::set_particle_module_disabled

Prototype:
void set_particle_module_disabled(int disable_particle_module);
Description:

This function enables or disables the particle module. By default the particle module is enabled.

function diguyScenario::create_particle_system

Prototype:
int create_particle_system(const char* description_name,
    float x, float y, float z,
    int record_transient_event = 1,
    float duration = -1.0f);
Description:

This function creates a particle system with type description_name at x, y, z. If duration is specified the system will automatically stop emitting after that amount of time.
Arguments:

description_name name of particle description to create
x, y, z the world space position of the system
record_transient_event pass 1 to have this particle system play in history playback
duration how long the emitter should emit; if -1 is specified then the description must have a lifetime specified

function diguyScenario::create_particle_system_with_orientation

Prototype:
int create_particle_system_with_orientation(const char* description_name,
    float x, float y, float z,
    float rz, float rx, float ry,
    int record_transient_event = 1,
    float duration = -1.0f);
Description:

Similar to create_particle_system(), but allows orientation to be set.
Arguments:

rz, rx, ry orientation axes

(See create_particle_system() for other parameters)

function diguyScenario::has_particle_description

Prototype:
int has_particle_description(const char* description_name);
Returns:

1 if the particle description named description_name exists, else 0

function diguyScenario::set_global_wind

Prototype:
void set_global_wind(float x, float y, float z);
Description:

Set wind velocity vector for particle system

Lua Scripting Module Functions

function diguyScenario::lua_get_object_field_as_string

Prototype:
const char* lua_get_object_field_as_string(const char* lua_object,
    const char* field_name);
Returns:

string representation of lua_object.field_name

Note that the returned string pointer will not remain valid, so the returned string should be copied.
Arguments:

lua_object a global lua object
field_name name of the field; field_name can include ".", allowing retrieval of fields in complex data structures
Callable From:

C++

function diguyScenario::lua_evaluate_object_function

Prototype:
const char* lua_evaluate_object_function(const char* lua_object,
    const char* function_name,
    const char* argument = NULL,
    int has_return_string = 0);
Description:

Runs a member function of a lua object.
Arguments:

lua_object a global lua object
function_name name of the function to call
argument optional string argument
has_return_string if set to 1 function will pop the top value of the lua stack and return it as a string
Returns:

NULL or string representation of lua_object:function_name(argument).

The returned string should be copied if it needs to be used later.
Callable From:

C++

function diguyScenario::lua_evaluate_object_function_2a

Prototype:
const char* lua_evaluate_object_function_2a(const char* lua_object,
    const char* function_name,
    const char* argument,
    const char* argument2,
    int has_return_string = 0);
Description:

A two argument version of lua_evaluate_object_function().
Callable From:

C++

function diguyScenario::lua_evaluate_object_function_3a

Prototype:
const char* lua_evaluate_object_function_3a(const char* lua_object,
    const char* function_name,
    const char* argument,
    const char* argument2,
    const char* argument3,
    int has_return_string = 0);
Description:

A three argument version of lua_evaluate_object_function().
Callable From:

C++

function diguyScenario::lua_evaluate_object_function_4a

Prototype:

const char* lua_evaluate_object_function_4a(const char* lua_object,
    const char* function_name,
    const char* argument,
    const char* argument2,
    const char* argument3,
    const char* argument4,
    int has_return_string = 0);

Description:

A four argument version of lua_evaluate_object_function().

Callable From:

C++

function diguyScenario::lua_send_message_to_object

Prototype:
int lua_send_message_to_object(const char* lua_object,
    const char* sender,
    const char* message_type,
    const char* message,
    const char* message_params = NULL);
Description:

Executes a lua_object:state_manager() function call. Useful for creating sleep-able coroutine based objects that aren't characters.
Callable From:

C++

function diguyScenario::get_lua_state

Prototype:
void* get_lua_state();
Description:

This function allows low level access to the lua_State pointer. This pointer can be used by a programmer to query and run functions on the Lua virtual machine. This object can also be used to register new C functions to lua, which allows you to instrument and create callbacks from script to your code. See luaL_register on-line.

For more information on how the Lua C api works see: http://www.lua.orgpil24.html
NOTE:

Currently all scenarios share the same underlying Lua state object. This may cause issues in applications with multiple scenarios.
Callable From:

C++

function diguyScenario::push_qt_pointer_to_lua

Prototype:
int push_qt_pointer_to_lua(void* lua_state,
    const char* class_name,
    void* ptr);
Description:

Mainly used to pass a qt pointer to lua so lqt can be used to modify/read from the widget. This requires the that the lqt package is loaded; see the lqt.lua utility package for more info.
Arguments:

lua_state a Lua_State pointer, might be the same as get_lua_state(); depends if the calling function is inside a coroutine
class_name class name should be a core class of qt with a star after it; i.e. "QWidget*" or "QLineEdit*"
ptr pointer to that is returned to the calling function in lua
Callable From:

C++
C++ Example:
    int push_graphics_view_to_lua(lua_State *L)
    {
        bdiQGraphicsView* graphics_view = get_primary_3d_window_graphics_view();
        if (m_scenario->push_qt_pointer_to_lua(L, "QGraphicsView*", graphics_view) == -1)
        {
            return 0;
        }
        return 1;
    }
Plug-in init code:
    lua_State* L = (lua_State*)scenario->get_lua_state();
    if (L)
    {
        lua_register(L, "get_graphics_view", push_graphics_view_to_lua);
    }
In lua:
    local graphics_view = get_graphics_view();

function diguyScenario::lua_evaluate_object_function_4a_flex

Prototype:
const char* lua_evaluate_object_function_4a_flex(const char* lua_object,
    const char* function_name,
    const char* arg1_type, void* argument1,
    const char* arg2_type, void* argument2,
    const char* arg3_type, void* argument3,
    const char* arg4_type, void* argument4,
    int has_return_string = 0);
Description:

The most open function calling function available, if this doesn't manage to accomplish what you need you probably want to start using the lua interpreter directly.

The type arguments are string versions of the type being sent to lua, options include:

'' - empty argument
'b' boolean - void* argument1 is assumed to be an int
'f' field - void* argument1 assumed to be character string of a field of a global lua object; supports nested fields like foo.bar.a
's' string - void* argument1 assumed to be character string
'd' double - void* argument is assumed to be a double
diguy... - void* argument assumed to be a diguy class pointer ie "diguyCharacter", "diguyCrowd" (no star used for diguy classes)
Q...* - void* argument is assumed to be a pointer to a child of QObject; the class name should be a core class of qt with a star after it, e.g. "QWidget*" or "QLineEdit*"

Arguments:

lua_object a global lua object
function_name name of the function to call
arg(1/2/3/4)_type is the data type
argument(1/2/3/4) void* pointers to data
has_return_string if set to 1 function will pop the top value of the lua stack and return it as a string
Returns:

NULL or string representation of lua_object:function_name(argument)

The returned string should be copied if it needs to be used later.
Callable From:

C++

function diguyScenario::lua_evaluate_global_function_4a_flex

Prototype:
const char* lua_evaluate_global_function_4a_flex(const char* function_name,
    const char* arg_type, void* argument,
    const char* arg_type2, void* argument2,
    const char* arg_type3, void* argument3,
    const char* arg_type4, void* argument4,
    int has_return_string = 0);
Description:

Effectively the same as diguyScenario::lua_evaluate_object_function_4a_flex() but works on global functions.
Callable From:

C++

function diguyScenario::lua_log_printf

Prototype:
int lua_log_printf(int notify_level, const char* string);
Description:

Prints a message to lua interpreter log object. In DI-Guy Scenario this is sent to the AI Mind Editor and used to fill out the error log. The Mind editor log parses debug.traceback() calls.

function diguyScenario::dump_package_info

Prototype:
const char* dump_package_info(const char* package_name);
Returns:

package meta data as a formatted string; useful for debugging, only valid inside DI-Guy Scenario

Experimental Functions

The following functions are experimental and may change or disappear with no warning.

function diguyScenario::get_eval_decisions_as_scripts

Prototype:
int get_eval_decisions_as_scripts();
Returns:

value set by last call to set_eval_decisions_as_scripts()

function diguyScenario::set_eval_decisions_as_scripts

Prototype:
void set_eval_decisions_as_scripts(int eval_decisions_as_scripts);
Description:

If called with an argument of 1, all decision beads and decision beads will be converted to scripts before being run.

function diguyScenario::get_impact_on_line

Prototype:
diguyImpact* get_impact_on_line(float from_x,
    float from_y,
    float from_z,
    float to_x,
    float to_y,
    float to_z);
Description:

Gets the point of impact with the world along specified line segment
Returns:

pointer to diguyImpact object or NULL

function diguyScenario::wait_cursor_push

Prototype:
void wait_cursor_push();
Description:

Increments wait cursor counter. If non-zero, then wait cursor is displayed in DI-GUY scenario.

function diguyScenario::wait_cursor_pop

Prototype:
void wait_cursor_pop();
Description:

Decrements wait cursor counter.

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

node_ptr generic void* pointer
Callable From:

C++

function diguyScenario::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 diguyScenario::set_draw_character_shadow_disks

Prototype:
void set_draw_character_shadow_disks(int draw_character_shadow_disks);
Description:

Sets whether shadow disks are drawn for characters. Call with 1 to turn on, 0 to turn off.

function diguyScenario::get_draw_character_shadow_disks

Prototype:
int  get_draw_character_shadow_disks();
Returns:

1 if shadow disks are drawn, 0 if not

function diguyScenario::get_shadow_map_size

Prototype:
int  get_shadow_map_size();
Returns:

size of texture map for shadows

function diguyScenario::set_shadow_map_size

Prototype:
int  set_shadow_map_size(int shadow_size);
Description:

Sets size of texture map for shadows. Defaults to 1024. Allowed values are powers of two up to 4096.

function diguyScenario::set_default_character_scene_graph_mask

Prototype:
void          set_default_character_scene_graph_mask(unsigned long mask);
Description:

Used for DI-Guy OSG Author Programming Example. Sets the default value used for characters. See also diguyCharacter::set_scene_graph_mask()

function diguyScenario::set_default_scene_object_scene_graph_mask

Prototype:
void          set_default_scene_object_scene_graph_mask(unsigned long mask);
Description:

Used for DI-Guy OSG Author Programming Example. Sets the default value used for characters. See also diguySceneObject::set_scene_graph_mask()

function diguyScenario::set_internal_int

Prototype:
void set_internal_int(int var, int val);
Description:

For internal use.

function diguyScenario::set_internal_float

Prototype:

void set_internal_float(int var, float val);

function diguyScenario::set_num_active_point_lights

Prototype:
int set_num_active_point_lights(int active_lights);
Description:

This sets the number of point lights that get handed down to diguyGraphicsShaderTechnique::pick_shader_program().

function diguyScenario::get_num_active_point_lights

Prototype:
int get_num_active_point_lights();
Description:

This gets the number of point lights that get handed down to diguyGraphicsShaderTechnique::pick_shader_program() the default is 0. diguy_ogl_apply_active_lights() automatically updates this value in the OpenGL renderer.

Experimental Performance Functions

function diguyScenario::optimized_update

Prototype:
int optimized_update(float t);
Description:

Experimental. For internal use.

function diguyScenario::set_world_bounds

Prototype:
int set_world_bounds(float x_min, float y_min, float z_min,
    float x_max, float y_max, float z_max);
Description:

Sets bounding box of world
Arguments:

x_min,y_min,z_min,x_max,y_max,z_max bounds
Returns:

0 on success, -1 on failure (float * arguments converted to return values in Lua)

function diguyScenario::get_world_bounds

Prototype:
int get_world_bounds(float* x_min, float* y_min, float* z_min,
    float* x_max, float* y_max, float* z_max);
Description:

Gets bounding box of world
Arguments:

x_min,y_min,z_min,x_max,y_max,z_max output parameters
Returns:

0 on success, -1 on failure (float * arguments converted to return values in Lua)

Experimental Checkpoint Functions

function diguyScenario::set_checkpoint_frequency

Prototype:
void set_checkpoint_frequency(float freq);
Description:

Internal use

function diguyScenario::get_checkpoint_frequency

Prototype:
float get_checkpoint_frequency();
Description:

Internal use

function diguyScenario::set_checkpointing_enabled

Prototype:
void set_checkpointing_enabled(int enable_checkpointing);
Description:

Internal use

function diguyScenario::get_checkpointing_enabled

Prototype:
int get_checkpointing_enabled();
Description:

Internal use

Experimental Shader Functions

function diguyScenario::set_initial_render_mode

Prototype:
void set_initial_render_mode(const char* render_mode);
Description:

Sets initial render mode
Arguments:

render_mode string containing render mode setting name

Built-in render modes:

function diguyScenario::get_initial_render_mode

Prototype:
const char* get_initial_render_mode();
Returns:

initial render mode, as string

function diguyScenario::set_current_render_mode

Prototype:
void set_current_render_mode(const char* render_mode);
Description:

Sets current render mode. See set_initial_render_mode()

function diguyScenario::derive_render_mode_from_light_settings

Prototype:
const char* derive_render_mode_from_light_settings(int set_current_to_derived = 1);
Returns:

render mode, as string, derived from current light settings
Arguments:

set_current_to_derived if 1, current render mode becomes derived

function diguyScenario::get_current_render_mode

Prototype:
const char* get_current_render_mode();
Returns:

current render mode, as string

function diguyScenario::set_default_character_shader

Prototype:
void set_default_character_shader(const char* render_mode,
    const char* shader_name,
    int update_existing_characters = 1);
Description:

Sets default shader for characters
Arguments:

render_mode string containing render mode name
shader_name string containing name of shader technique
update_existing_characters if 1, all existing characters will now

function diguyScenario::get_default_character_shader

Prototype:
const char* get_default_character_shader(const char* render_mode);
Description:

Returns name of shader technique used for specified render mode

function diguyScenario::set_default_scene_object_shader

Prototype:
void set_default_scene_object_shader(const char* render_mode,
    const char* shader_name,
    int update_existing_scene_objects = 1);
Description:

Sets default shader for scene objects
Arguments:

render_mode string containing render mode name
shader_name string containing name of shader technique
update_existing_scene_objects if 1, all existing scene objects will now

function diguyScenario::get_default_scene_object_shader

Prototype:
const char* get_default_scene_object_shader(const char* render_mode);
Description:

Returns name of shader technique used for specified render mode

function diguyScenario::set_default_particle_system_shader

Prototype:
void set_default_particle_system_shader(const char* render_mode,
    const char* shader_name,
    int update_existing_particle_systems = 1);
Description:

Sets default shader for particle systems
Arguments:

render_mode string containing render mode name
shader_name string containing name of shader technique
update_existing_particle_systems if 1, all existing particle systems will now

function diguyScenario::get_default_particle_system_shader

Prototype:
const char* get_default_particle_system_shader(const char* render_mode);
Description:

Returns name of shader technique used for specified render mode

function diguyScenario::facefx_mount_animset

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

Sets FaceFX animation set for a given actor.
Arguments:

actor_name actor's name
file_name fully qualified file name ending in ".animset_ingame"

function diguyScenario::set_vehicle_smoothing_enabled

Prototype:
int set_vehicle_smoothing_enabled(int enable_smoothing);
Description:

Sets vehicle smoothing on or off. If 1, vehicle will be updated at a higher rate than frame dt

Default is on.

function diguyScenario::get_vehicle_smoothing_enabled

Prototype:

int get_vehicle_smoothing_enabled();

function diguyScenario::set_character_culling_distance

Prototype:
int set_character_culling_distance(float dist);
Description:

Culling distance (from camera) for drawing

function diguyScenario::get_character_culling_distance

Prototype:

float get_character_culling_distance();

function diguyScenario::set_vehicle_culling_distance

Prototype:
int set_vehicle_culling_distance(float dist);
Description:

Culling distance (from camera)

function diguyScenario::get_vehicle_culling_distance

Prototype:

float get_vehicle_culling_distance();

function diguyScenario::set_prop_culling_distance

Prototype:
int set_prop_culling_distance(float dist);
Description:

Culling distance of props (from camera)

function diguyScenario::get_prop_culling_distance

Prototype:

float get_prop_culling_distance();

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 diguyScenario::add_default_callback

Prototype:
static int add_default_callback(int callback_id,
    diguyScenarioCallback* callback,
    void* callback_params = 0,
    void* callback_user_data = 0);
Description:

Deprecated; use diguyApp::add_default_scenario_callback() instead.

function diguyScenario::remove_default_callback

Prototype:
static int remove_default_callback(int callback_id,
    diguyScenarioCallback* callback);
Description:

Deprecated; use diguyApp::remove_default_scenario_callback() instead.

function diguyScenario::remove_default_callback_with_user_data

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

Deprecated; use diguyApp::remove_default_scenario_callback_with_User_data() instead.

function diguyScenario::add_default_callback_script

Prototype:
static int add_default_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type);
Description:

Deprecated; use diguyApp::add_default_scenario_callback_script() instead.

function diguyScenario::remove_default_callback_script

Prototype:
static int remove_default_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type);
Description:

Deprecated; use diguyApp::remove_default_scenario_callback_script() instead.

function diguyScenario::get_character_type_class

Prototype:
const char* get_character_type_class(const char* character_type);
Description:

Deprecated as of 10.0.0; use get_character_type_map() intead, and then call diguyCharacterTypeMap::get_field_value(DIGUY_CHARACTER_TYPE_MAP_FIELD_CHARACTER_CLASS)

function diguyScenario::merge_asset

Prototype:
int merge_asset(const char* string);
Description:

Deprecated as of 10.5.1; use merge_object() intead.

function diguyScenario::print_to_log

Prototype:
void print_to_log(int notify_level, const char* string);
Description:

Deprecated as of 12.0.0; use bdi_log_print() from libbdilog.h instead.

VegaPrime Helper Functions

function diguyScenario::create_pending_reflected_character

Prototype:

diguyCharacter* create_pending_reflected_character(const char* name,
    const char* character_type,
    const char* appearance = NULL);

function diguyScenario::set_network_translation

Prototype:

int set_network_translation(float x, float y, float z);

function diguyScenario::get_network_translation

Prototype:

int get_network_translation(float* x, float* y, float* z);

function diguyScenario::set_project_filename

Prototype:
void set_project_filename(const char* project_filename);
Description:

Deprecated as of 12.0.0; use save_as() instead.

function diguyScenario::get_project_filename

Prototype:
const char* get_project_filename();
Description:

Deprecated as of 12.0.0; use get_filename() or get_filename_without_directory() intead.

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`	desired simulation time in seconds
`realtime_t`	elapsed real time in seconds

`call_plugins_post_draw`	pass 1 to call plugin post_draw() functions
`call_lua_packages_draw`	pass 1 to call lua package draw functions
`call_post_draw_callback`	pass 1 to invoke callbacks with callback id CALLBACK_ID_POST_DRAW

`scenario settings`	DIGUY_MERGE_FLAG_DONT_MERGE
`current view settings`	DIGUY_MERGE_FLAG_OVERWRITE_EXISTING
`character`	DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
`decision`	DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
`formation`	DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
`group`	DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
`guide`	DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
`info popup`	DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
`library function`	DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
`script`	DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
`sensor region`	DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
`signal`	DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
`variables`	DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
`camera settings`	DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
`face exp`	DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
`fog settings`	DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
`light settings`	DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
`particle system`	DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
`path shape`	DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
`scene object`	DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
`scene object grid`	DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
`sound`	DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL

`filename`	filename of scenario to be merged
`merge_settings`	object that controls how elements are merged; pass NULL for default merge handling

`appearance`	name of the appearance
`equipment_list`	NULL-terminated list of equipment that makes up the appearance
`character_types`	NULL-terminated list of character types that this appearance will be available to
`actor`	name of the actor this appearance fits

`appearance`	name of the new appearance
`existing_appearance`	name of the existing appearance on which to base new appearance
`equipment_list`	NULL-terminated list of equipment to add to

`appearance`	name of the appearance
`index`	which character type of the set to return

`character_type`	character's type
`gesture_name`	name of the gesture to preload

`character_type`	character type name, as returned by get_character_type_at_index(), for example
`index`	index of the appearance; indices start at 0

`character_type`	character type name, as returned by get_character_type_at_index(), for example
`action_name`	the action to query

`name`	name of the new character
`character_type`	character's type
`appearance`	base appearance of character; pass NULL to use default appearance

`name`	new name for the character retrieved from bin
`character_type`	the character type to retrieve from the bin
`appearance`	the appearance to retrieve from the bin, pass NULL or "default" to retrieve the default appearance
`make_character_temporary`	pass 1 to make character temporary, 0 to leave permanent

`existing_path_shape`	pointer to `diguyPathShape` to be copied
`name`	name of the new path shape

`tx, ty, tz`	position in meters from the origin
`rz, rx, ry`	orientations in degrees counter-clockwise from the positive X axis
`weight_in`	how much influence this waypoint exerts over the path curve entering this waypoint
`weight_out`	how much influence this waypoint exerts over the path curve leaving this waypoint

`field1`	field in type map to check
`field1_value`	value to check for
`field1_alternate_value`	acceptable alternate value

`name`	name of the new sound
`sound_filename`	filename of the sound
`phoneme_filename`	optional phoneme file; see diguySound::set_phoneme_filename()

`name`	name of the sound
`x, y, z`	location in the world the sound comes from
`gain`	a volume multiplier
`save_event`	if review data should record the creation of this sound

`name`	name of the new scene object
`filename`	file the scene object should use

`settings_name`	name of camera settings to be loaded
`update_current_camera`	whether the current camera should be updated; defaults to 1

`settings_name`	name of light settings to be loaded
`light_num`	which light to load into

`name`	name of the new face expression
`target_actor`	name of the actor to use as template; defaults to "exface" for backwards compatiblity

`callback`	pointer to function with prototype diguyScenarioCallback (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
`remove_on_scenario_load`	pass 1 to remove the callback on a scenario load, 0 to not

`callback_id`	integer id of callback
`callback`	pointer to function with prototype diguyCharacterCallback (typedefed above)

`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
`remove_on_scenario_load`	if the callback is removed when a new scenario is loaded

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

`handler_name`	name of the event handler
`callback`	pointer to handler function
`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 handler function is called

`handler_name`	name of the event handler
`library_name`	pointer to handler function
`function_name`	pointer to handler function
`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 handler function is called

`handler_name`	name of the event handler
`handler_script`	Script text
`handler_script_type`	type of script; pass NULL for scenario to use the default script interpreter

`character_type`	character type name, as returned by get_character_type_at_index()
`ranges`	an array of 8 non-negative floating point numbers, each larger than the one before, specifying the LOD switching ranges in meters

`script_text`	string to be evaluated
`save_as_transient`	flag stating whether script_text should be remembered as a transient event at the current scenario t; see push_transient_script_event()
`script_type`	type of script contained in script_text; pass NULL to use scenario's default interpreter
`script_source`	string identifying the 'source' of the script; will be printed in error output if there are syntax errors in the script