diguyScenario Class Reference

Represents the scenario currently being portrayed. More...

#include <diguyScenario.h>

Public Member Functions
Time Control and Playback Functions
Unless otherwise specified, callable from: C++ Script
int	update (float t)
	Sets the desired simulation time of the scenario. More...
int	update2 (float t, float realtime_t)
	Similar to update(), but the realtime time can be explicitly passed in. More...
int	set_playback_loop (int playback_loop)
	This function sets whether the scenario is designed to loop at tout. More...
int	set_tick_dt (float tick_dt)
	Scenarios progress at discrete time steps, called "ticks". More...
float	get_t ()
	This function returns the time in seconds that the scenario is currently at. More...
float	get_realtime_t ()
	This function returns the realtime time in seconds that the scenario is currently at. More...
float	get_desired_t ()
	This function returns the desired time in seconds that the scenario is currently at. More...
int	set_tout (float tout)
	This function sets the tout ("T Out") time of the scenario. More...
float	get_tout ()
	This function returns the tout time of the scenario. More...
void	set_tout_enabled (int tout_enabled)
	This function sets what will happen when the scenario reaches its tout time. More...
int	get_tout_enabled ()
	This function returns the whether tout is enabled. More...
int	get_playback_loop ()
	This function returns whether the scenario is designed to loop when the scenario's tout time is reached. More...
float	get_tick_dt ()
	This function returns the most recent setting of set_tick_dt(). More...
int	get_ticks_can_be_dropped ()
	Returns: This function returns the most recent setting of set_ticks_can_be_dropped(). More...
void	set_ticks_can_be_dropped (int ticks_can_be_dropped)
	This function sets whether a scenario can "drop" ticks in order to catch up if it falls behind. More...
long	get_max_ticks_behind_until_drop ()
	Returns: This function returns the most recent setting of set_max_ticks_behind_until_drop(). More...
void	set_max_ticks_behind_until_drop (long max_ticks_behind_until_drop)
	This function sets how many ticks a scenario must be behind before it starts dropping ticks in order to catch up. More...
int	set_playback_mode (diguyScenarioPlaybackMode playback_mode)
	This function sets the current playback mode of DI-Guy Scenario. More...
int	set_playback_mode_stop ()
	This function is shorthand for the function call set_playback_mode(DIGUY_SCENARIO_PLAYBACK_MODE_STOP). More...
int	set_playback_mode_play ()
	This function is shorthand for the function call set_playback_mode(DIGUY_SCENARIO_PLAYBACK_MODE_PLAY). More...
diguyScenarioPlaybackMode	get_playback_mode ()
	Returns: current playback mode as set by set_playback_mode() or the DI-Guy Scenario user interface. More...
float	derive_playback_mode_dt (float dt_in)
	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. More...
int	reset ()
	This function resets all scenario characters, signals, variables, and all other scenario objects to their original state. More...
Load and Save Functions
int	load (const char *filename)
	This function loads the specified scenario. More...
int	save ()
	Saves the scenario into its current filename. More...
int	save_as (const char *filename)
	Similar to save(), but new filename is specified by the filename argument. More...
const char *	get_filename ()
	Returns the most recent of: More...
const char *	get_filename_without_directory ()
	Similar to get_filename(), but with any leading directories removed. More...
int	get_unsaved ()
	Returns: 1 if scenario has been modified since save or load, else 0. More...
void	set_unsaved (int unsaved)
	Manually sets the "unsaved" flag to the passed value. More...
Draw Functions
int	draw ()
	This function draws all visible elements of the loaded scenario in immediate mode graphics environments (see below). More...
int	draw_pass1 ()
	This function, along with draw_pass2(), allows the drawing of opaque and transparent polygons to be separated. More...
int	draw_pass2 (int also_call_post_draw=1)
	Same as draw_pass1(), but draws transparent scenario elements. More...
int	draw_particles ()
	Explicitly invokes particle drawing code, this can be useful for retained mode renderers that have chosen to hook up our immediate mode particle system as a post draw stage (osg) More...
void	pre_draw_cull_state_reset ()
	Clears all the culling bits state for various characters, this should be called before any drawing is done. More...
void	post_draw_cull_state_save ()
	Saves all the culling bits for various characters, should be called after all drawing is done so that the next call to update() has reasonable culling information to work with. More...
void	calculate_character_lods ()
	This function updates all character lods and updates the instancing system representation of the characters calling this is needed for the instancing system to work. More...
int	post_draw (int call_plugins_post_draw=1, int call_lua_packages_draw=1, int call_post_draw_callback=1)
	This function draws visual elements that must be drawn after the main render has been done. More...
int	set_graphics_attach_ptr (void *graphics_attach_ptr)
	This function sets the attachment point that to be used for graphics created by the library. More...
Merge Functions
Unless otherwise specified, callable from: C++ Script
diguyScenarioMergeSettings *	create_merge_settings (diguyScenarioMergeInitialSettings initial_settings=DIGUY_MERGE_INITIAL_SETTINGS_DEFAULT)
	This function creates a merge settings object. More...
void	destroy_merge_settings (diguyScenarioMergeSettings *merge_settings)
	This function destroys a merge settings object created by a call to create_merge_settings(). More...
int	merge (const char *filename, diguyScenarioMergeSettings *merge_settings=NULL)
	This function merges the specified scenario. More...
int	merge_object (const char *string)
	This function performs a "micro merge", allowing a scenario to merge in the contents of a text string representing a single object. More...
int	include_object_library (const char *library_name)
	This function makes the objects in the specified library available for use in the scenario. More...
int	uninclude_object_library (const char *library_name)
	This function is the opposite of include_object_library(). More...
Time and Date Functions
Unless otherwise specified, callable from: C++ Script
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)
	This function will set what the current datetime will be when the scanario is reset. More...
void	set_base_datetime (const char *datetime_string, const char *format)
	Similar to set_base_datetime(), but datetime is stored in the passed string, formatted in the passed format string. More...
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)
	Retrieves the base datetime. More...
void	set_base_datetime_default_to_now (int to_now)
	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(). More...
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. More...
void	set_base_datetime_default_to_today (int to_today)
	Similar to set_base_datetime_default_to_now(), but for the date part of the datetime. More...
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. More...
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)
	Allows current datetime to be explicitly set. More...
void	set_current_datetime (const char *datetime_string, const char *format)
	Similar to set_current_datetime(), but datetime is stored in the passed string, formatted in the passed format string. More...
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)
	Retrieves the current datetime. More...
const char *	get_current_datetime_string (const char *format)
	Retrieves the current datetime in string format. More...
void	set_datetimes_are_utc (int are_utc)
	Pass 1 to specify that datetimes use UTC time, 0 to specify they are local time. More...
int	get_datetimes_are_utc ()
	Returns: 1 if datetimes use UTC time, 0 if not. More...
void	set_utc_offset_hours (float utc_offset_hours)
	If datetimes use UTC time, this function sets the offset hours of the current time from UTC. More...
float	get_utc_offset_hours ()
	Returns: offset in hours of datetimes from UTC. More...
void	set_use_local_tz_utc_offset_hours (int use_local_tz)
	Causes the number of UTC offset hours to be derived from local system settings – an alternative to calling set_utc_offset_hours() More...
int	get_use_local_tz_utc_offset_hours ()
	Returns value set in set_use_local_tz_utc_offset_hours() More...
void	set_current_datetime_advance_method (diguyDatetimeAdvanceMethod advance_method)
	Sets the rate at which datetime can advance. More...
diguyDatetimeAdvanceMethod	get_current_datetime_advance_method ()
	Returns value set by set_current_datetime_advance_method() More...
void	set_current_datetime_advance_factor (float advance_factor)
	Sets a multiplier that affects the rate at which datetime advances. More...
float	get_current_datetime_advance_factor ()
	Returns value set by set_current_datetime_advance_factor() More...
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)
	Returns current exercise's datetime values. More...
int	set_tin_time_of_day (float t)
	This function sets the time of day which corresponds to scenario tin. More...
float	get_tin_time_of_day ()
	This function returns what time of day corresponds to scenario tin. More...
float	get_time_of_day ()
	This function returns what the simulated time of day is right now. More...
Appearance Functions
Unless otherwise specified, callable from: C++ Script
int	add_appearance (const char *appearance, char **equipment_list, char **character_types, const char *actor)
	This function adds an appearance with the given name to the list of available appearances. More...
int	add_appearance_based_on_existing_appearance (const char *appearance, const char *existing_appearance, char **equipment_list)
	This function is similar to add_appearance(), but adds equipment_list shapes to an existing appearance. More...
int	remove_appearance (const char *appearance)
	This function removes an appearance with the given name from the list of available appearances. More...
int	get_num_character_types_with_appearance (const char *appearance_name)
	This function returns the number of character types associated with the given appearance, if any. More...
const char *	get_character_type_from_appearance (const char *appearance_name, int index=0)
	This function returns one of the character types associated with the appearance, if any exists. More...
Hand Item Functions
Unless otherwise specified, callable from: C++ Script
int	get_num_hand_item_classes () const
	Gets the number of configured hand item classes. More...
const char *	get_hand_item_class_at_index (int index) const
	Gets the name of the hand item class at the given index. More...
int	get_item_class_num_character_types (const char *item_class_name) const
	Gets the number of character types a given hand item class is configured to be available to. More...
const char *	get_item_class_character_type_at_index (const char *item_class_name, int index) const
	Gets the character types configured for availability with the given hand item class at the given index. More...
const char *	get_hand_item_class (const char *char_type_name, const char *appearance_name=nullptr)
	Gets the primary hand item class associated with a character type. More...
int	get_num_hand_items_in_class (const char *hand_item_class)
	Gets the number of hand items in a particular hand item class. More...
const char *	get_hand_item_from_class (const char *hand_item_class, int index)
	Gets the name of a hand item within the set associated with a hand item class. More...
Preload Functions
Unless otherwise specified, callable from: C++ Script
int	preload_character_type (const char *character_type)
	This function preloads all base motions and the default appearance for the specified character type. More...
int	preload_appearance (const char *appearance)
	This function preloads all geometry for the specified appearance. More...
int	async_load_appearance (const char *appearance, const char *character_type="soldier_17", const bool **load_status=NULL)
	This function asynchronously starts loading appearance data in a background thread and sends textures to the async texture loader. More...
int	async_load_hand_item (const char *appearance_name, const bool **load_status=NULL)
int	preload_gesture (const char *character_type, const char *gesture_name)
	This function preloads all motions for the specified gesture for the specified character type. More...
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
void	set_character_culling_enabled (int character_culling)
	This function enables character culling. More...
int	get_character_culling_enabled ()
	This function gets the state of character culling. More...
void	set_scene_object_culling_enabled (int object_culling)
	This function enables scene object culling. More...
int	get_scene_object_culling_enabled ()
	This function get the state of scene object culling. More...
void	set_scene_object_sub_culling_enabled (int object_culling)
	This function enables scene object sub object culling. More...
int	get_scene_object_sub_culling_enabled ()
	This function get the state of scene object sub culling. More...
void	set_character_visualize_bounds_enabled (int visualize_bounds)
	This function enables visualizing a character's bounding volume. More...
int	get_character_visualize_bounds_enabled ()
	This function get the state of character bounding volume visualization. More...
void	set_scene_object_visualize_bounds_enabled (int val)
	This function enables visualizing a scene object's bounding volume. More...
int	get_scene_object_visualize_bounds_enabled ()
	This function gets the state of scene objects bounding volume visualization. More...
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); } }
int	get_num_character_types ()
	Returns: number of available character types. More...
const char *	get_character_type_at_index (int index)
	Returns: the string identifying the character type at the given index. More...
const char *	get_character_type_abbreviation (const char *character_type)
	Returns: abbreviation of the given character type, when a shorter identifier is needed. More...
const char *	get_character_type_deprecated_at_version (const char *character_type)
	This function returns the version at which the specified character type was deprecated. More...
const char *	get_character_type_deprecated_suggested_alternatives (const char *character_type)
	This function returns the suggested character type(s) that are recommended for deprecated character types. More...
int	get_character_type_quality_bias (const char *character_type)
	As the number of character types DI-Guy provides has grown, newer character types tend to be better than older ones. More...
diguyCharacterTypeMap *	get_character_type_map (const char *character_type)
	This function returns the type map of the specified character type. More...
const char *	get_character_type_default_appearance (const char *character_type)
	Returns: default appearance of the specified character type. More...
const char *	get_character_type_default_skinned_appearance (const char *character_type)
	Returns: default skinned appearance of the specified character type. More...
int	get_character_type_num_appearances (const char *character_type)
	Returns: number of available appearances for the given character type. More...
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. More...
int	get_appearance_quality_bias (const char *appearance)
	As the number of appearances DI-Guy provides has grown, newer appearances tend to be better than older ones. More...
int	get_num_appearances_of_appearance_type (const char *character_type, const char *base_appearance, diguyCharacterAppearanceTypes appearance_type)
const char *	get_appearance_name_at_index (const char *character_type, const char *base_appearance, diguyCharacterAppearanceTypes appearance_type, int index)
	Returns: The name of the supplementary appearance (body, head, expressive head, hand item) or NULL. More...
int	get_num_patches_for_appearance (const char *base_appearance, diguyTextureUniformPatchLocations patch_location)
	returns the number of texture patches for a given appearance, supports unit or rank More...
int	get_appearance_default_patch_index (const char *base_appearance, diguyTextureUniformPatchLocations patch_location) const
	returns the index of the default texture patch for the given appearance, supports unit or rank More...
const diguyPatchIdentifier &	get_appearance_default_patch_id (const char *base_appearance, diguyTextureUniformPatchLocations patch_location) const
	returns the id of the default texture patch for the given appearance, supports unit or rank More...
const char *	get_appearance_patch_name_at_index (const char *base_appearance, diguyTextureUniformPatchLocations patch_location, int index) const
	returns the name of a texture patch for the given appearance, supports unit or rank More...
const diguyPatchIdentifier &	get_appearance_patch_id_at_index (const char *base_appearance, diguyTextureUniformPatchLocations patch_type, int index) const
	Get the patch id for the given texture patch. More...
int	get_num_actors ()
	returns num actor typically broad skeleton type More...
const char *	get_actor_name_at_index (int index)
	returns name of actor (broad skeleton type ) More...
const char *	get_actor_name (const char *base_appearance)
	returns actor that this appearance is based off of, typically broad skeleton type More...
int	get_num_equipment_for_actor (const char *actor_name)
	returns number of equipment appearances available for this actor More...
const char *	get_equipment_name_for_actor (const char *actor_name, int index)
	returns number of equipment appearances available for this actor More...
const char *	get_equipment_type_for_actor (const char *actor_name, int index)
	returns class_type of equipment appearance available for this appearance, usually based on actor More...
int	get_num_equipment_for_appearance (const char *base_appearance)
	returns number of equipment appearances available for this appearance, usually based on actor More...
const char *	get_equipment_name_for_appearance (const char *base_appearance, int index)
	returns name of equipment appearance available for this appearance, usually based on actor More...
const char *	get_equipment_type_for_appearance (const char *base_appearance, int index)
	returns class_type of equipment appearance available for this appearance, usually based on actor More...
int	get_character_type_num_actions (const char *character_type)
	Returns: number of available actions for the given character type. More...
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. More...
const char *	get_character_type_action_display_name (const char *character_type, const char *action_name)
	Returns: the display name for the specified action for the specified character type. More...
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. More...
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. More...
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. More...
int	get_character_type_action_displacement (const char *character_type, const char *action_name, float *x, float *y, float *z)
	Returns: the displacement covered by one rep of the specified action for the specified character type. More...
bool	get_character_type_transition_info (const char *character_type, const char *from_action_name, const char *to_action_name, diguyTransitionInfo &info)
	Looks up the transition used between the given two actions, and returns information about the transition. More...
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. More...
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. More...
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. More...
int	get_character_type_num_gestures (const char *character_type)
	Returns: the number of gestures available to the specified character type. More...
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. More...
diguyGestureMetadata *	get_character_type_gesture_meta_data_at_index (const char *character_type, int index)
	Returns: the metadata of the gesture available to the specified character type at the specified index see get_character_type_gesture_at_index() for args. More...
Character Functions
Unless otherwise specified, callable from: C++ Script
diguyCharacter *	create_character (const char *name, const char *character_type, const char *appearance=NULL, const char *head_appearance=NULL, const char *hand_item=NULL)
	This function creates a new character and returns a pointer to it. More...
diguyCharacter *	create_temporary_character (const char *name, const char *character_type, const char *appearance=NULL)
	This function is very similar to create_character(), but the character created is temporary. More...
int	destroy_character (diguyCharacter *character)
	This function destroys a character. More...
int	destroy_character_later (diguyCharacter *)
int	send_character_to_recycle_bin (diguyCharacter *character)
	This function is an alternative way of removing a character from the scenario. More...
diguyCharacter *	retrieve_character_from_recycle_bin (const char *name, const char *character_type, const char *appearance, int make_character_temporary=0)
	This function is an alternative way of creating a character. More...
int	get_num_characters ()
	Returns: number of characters in the scenario. More...
diguyCharacter *	get_character_at_index (int index)
	Returns: pointer of type diguyCharacter; NULL if no character at the specified index. More...
diguyCharacter *	find_character (const char *name)
	This function returns a pointer to the specified character. More...
void	look_at_character (diguyCharacter *character)
	This function changes the scenario camera's position and fix point so it will be looking at the specified character. More...
diguyCharacter *	this_character ()
	This function returns a pointer to the target character of an event bead. More...
diguyCharacterPathEvent *	this_event_bead ()
	This function returns a pointer to the current event bead. More...
Path Shape Functions
Unless otherwise specified, callable from: C++ Script
int	get_num_path_shapes ()
	Returns: number of path shapes in the scenario. More...
diguyPathShape *	get_path_shape_at_index (int index)
	Returns: pointer of type diguyPathShape; NULL if no path shape at the specified index. More...
diguyPathShape *	get_current_path_shape ()
	Returns: pointer of type diguyPathShape; NULL if no path shape at the specified index. More...
diguyPathShape *	find_path_shape (const char *name)
	This function returns a pointer to the specified path shape. More...
diguyPathShape *	create_path_shape (const char *name)
	This function creates a new path shape and returns a pointer to it. More...
diguyPathShape *	copy_path_shape (diguyPathShape *existing_path_shape, const char *name)
	This function creates a new path shape based on an existing path shape and returns a pointer to it. More...
int	destroy_path_shape (diguyPathShape *path_shape)
	This function destroys a path shape. More...
Waypoint Functions
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)
	This function creates a new waypoint that can be used for creating new paths and path shapes. More...
int	destroy_waypoint (diguyWaypoint *waypoint)
	This function destroys a waypoint created by create_waypoint(). More...
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
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)
	This function searches DI-Guy's available character types and appearances for the closest match to the specified fields and values. More...
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)
	Same as above, but fields to check are specified by string name instead of enumeration value. More...
int	get_num_matching_type_maps (const diguyCharacterTypeMapFieldValues *field_values, const char *character_type=NULL, const diguyCharacterTypeMapFieldValues *alternate_values=NULL)
	Get the number of type maps matching the given fields and (optional) character type. More...
diguyCharacterTypeMap *	get_matching_type_map_at_index (int index)
	Get the type map at the given index in the array of matches. More...
diguyCharacterTypeMap *	get_nearest_character_type_map_id_match (const char *type_map_id)
	Same as above, but field values to match against are specified by the given type map id. More...
int	get_num_character_type_map_entries ()
	This function returns the total number of type map entries that are in DI-Guy. More...
diguyCharacterTypeMap *	get_character_type_map_entry_at_index (int index)
	Returns: type map entry at specified index; see get_num_character_type_map_entries() More...
int	get_num_type_map_character_classes ()
	This function returns the total number of values that may be specified or returned in the character class field. More...
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() More...
int	get_num_type_map_categories (const char *character_class)
	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. More...
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() More...
int	get_num_type_map_subcategories (const char *character_class, const char *category)
	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. More...
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() More...
Signal Functions
Unless otherwise specified, callable from: C++ Script
int	get_num_signals ()
	Returns: number of signals in the scenario. More...
diguySignal *	get_signal_at_index (int index)
	Returns: pointer of type diguySignal; NULL if no signal at the specified index. More...
diguySignal *	find_signal (const char *name)
	This function returns a pointer to the specified signal. More...
diguySignal *	create_signal (const char *name)
	This function creates a new signal and returns a pointer to it. More...
int	destroy_signal (diguySignal *signal)
	This function destroys a signal. More...
void	reset_signals ()
	This function resets all signals in the scenario. More...
int	signal_palette_hide_all (const char *filter=NULL)
	This function hides all signals in the signal palette. More...
int	signal_palette_show_all (const char *filter=NULL)
	This function shows all signals in the signal palette. More...
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
int	get_num_sounds ()
	Returns: number of sounds in the scenario. More...
diguySound *	get_sound_at_index (int index)
	Returns: pointer of type diguySound; NULL if no sound at the specified index. More...
diguySound *	find_sound (const char *name)
	This function returns a pointer to the specified sound. More...
diguySound *	create_sound (const char *name, const char *sound_filename=NULL)
	This function creates a new sound and returns a pointer to it. More...
int	destroy_sound (diguySound *sound)
	This function destroys a sound. More...
int	preload_sound (diguySound *sound)
	This function preloads data for the sound. More...
int	stop_all_sounds (float rampdown_time=0.0f)
	This function stops all sounds playing within the scenario. More...
int	play_3d_sound (const char *name, float x, float y, float z, float gain, int save_event)
	This function plays a non looping sound. More...
Group Functions
Unless otherwise specified, callable from: C++ Script
int	get_num_groups ()
	Returns: number of groups in the scenario. More...
diguyCharacterGroup *	get_group_at_index (int index)
	Returns: pointer of type diguyCharacterGroup; NULL if no group at the specified index. More...
diguyCharacterGroup *	find_group (const char *name)
	This function returns a pointer to the specified group. More...
diguyCharacterGroup *	create_group (const char *name)
	This function creates a new group and returns a pointer to it. More...
diguyCharacterGroup *	find_or_create_group (const char *name)
	This function finds the group with the given name or creates it if it doesn't exist. More...
int	destroy_group (diguyCharacterGroup *group)
	This function destroys a group. More...
Sensor Region Functions
Unless otherwise specified, callable from: C++ Script
int	get_num_sensor_regions ()
	Returns the number of sensor regions in the scenario. More...
diguySensorRegion *	get_sensor_region_at_index (int index)
	Returns: pointer of type diguySensorRegion; NULL if no sensor region at the specified index. More...
diguySensorRegion *	find_sensor_region (const char *name)
	Returns a pointer to the specified sensor region, NULL if not found. More...
diguySensorRegion *	find_or_create_sensor_region (const char *name)
	finds or creates a sensor region with specified name More...
Scene Object Functions
Unless otherwise specified, callable from: C++ Script
int	get_num_scene_objects ()
	Returns: number of scene objects in the scenario. More...
diguySceneObject *	get_scene_object_at_index (int index)
	Returns: pointer of type diguySceneObject; NULL if no scene object at the specified index. More...
diguySceneObject *	find_scene_object (const char *name)
	Returns: pointer of type diguySceneObject; NULL if no scene object with specified name. More...
void	set_scene_objects_enabled (int scene_objects_enabled)
	This function sets whether scene objects defined in the scenario are enabled, and therefore potentially visible. More...
int	get_scene_objects_enabled ()
	Returns: the most recent setting made by a call to set_scene_objects_enabled() More...
diguySceneObject *	create_scene_object (const char *name, const char *filename)
	This function creates a new scene object and returns a pointer to it. More...
diguySceneObject *	create_user_defined_scene_object (const char *name)
	This function creates a new user defined scene object and returns a pointer to it. More...
int	destroy_scene_object (diguySceneObject *scene_object)
	This function destroys a scene object. More...
View Functions
Unless otherwise specified, callable from: C++ Script
diguyView *	get_primary_view ()
	Returns: pointer to the scenario's primary view; there is one and only one primary view in the scenario. More...
bool	create_new_secondary_view ()
	Creates a new secondary view for the scenario. More...
int	get_num_secondary_views ()
	Returns: number of secondary views in the scenario. More...
diguyView *	get_secondary_view_at_index (int index)
	Returns: pointer of type diguyView; NULL if no secondary view at the specified index. More...
diguyView *	find_view (const char *name)
	This function returns a pointer to the view with the given name. More...
Camera Functions
Unless otherwise specified, callable from: C++ Script
diguyViewCamera *	get_scenario_camera ()
	This function returns a pointer to the primary view's camera. More...
diguyViewCamera *	find_camera (const char *name)
	This function returns a pointer to the camera with the given name. More...
void	set_scenario_camera_affected_by_script_events (int flag)
	This function sets a flag that determines whether script calls can set the primary view's camera settings. More...
int	get_scenario_camera_affected_by_script_events ()
	Returns: the most recent setting made by set_scenario_camera_affected_by_script_events() More...
void	set_scenario_camera_affected_by_script_events_when_iguy_active (int flag)
	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. More...
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() More...
int	get_num_camera_settings ()
	Returns: number of camera settings saved in the scenario. More...
diguyViewCameraSettings *	get_camera_settings_at_index (int index)
	Returns: pointer of type diguyViewCameraSettings; NULL if no camera settings at the specified index. More...
diguyViewCameraSettings *	find_camera_settings (const char *settings_name)
	This function returns a pointer to the specified camera settings. More...
int	load_camera_settings (const char *settings_name, int update_current_camera=1)
	This function loads the specified camera settings into the primary view's camera. More...
void	set_render_camera (diguyViewCamera *camera)
	This function sets camera that will be used for down-stream camera-related operations. More...
diguyViewCamera *	get_render_camera ()
Fog Functions
Unless otherwise specified, callable from: C++ Script
diguyViewFog *	get_scenario_fog ()
	This function returns a pointer to the scenario fog. More...
diguyViewFog *	find_fog (const char *name)
	This function returns a pointer to the fog with the given name. More...
diguyViewFog *	find_or_create_fog (const char *name)
	This function returns the fog object with the given name, or creates one if not found. More...
void	load_current_fog (const char *name)
	This function loads the named fog settings the currently active one. More...
int	get_num_fog_settings ()
	Returns: number of fog settings in the scenario. More...
diguyViewFogSettings *	get_fog_settings_at_index (int index)
	Returns: pointer of type diguyViewFogSettings; NULL if no fog at the specified index. More...
diguyViewFogSettings *	find_fog_settings (const char *settings_name)
	This function returns a pointer to the specified fog settings. More...
int	load_fog_settings (const char *settings_name)
	This function loads the specified fog settings into the scenario fog. More...
Light Functions
Unless otherwise specified, callable from: C++ Script
diguyViewLight *	get_scenario_light (int i=0)
	This function returns a pointer to the scenario light. More...
diguyViewLight *	find_light (const char *name)
	This function returns a pointer to the light with the given name. More...
int	get_num_light_settings ()
	Returns: number of light settings in the scenario. More...
diguyViewLightSettings *	get_light_settings_at_index (int index)
	Returns: pointer of type diguyViewLightSettings; NULL if no light settings at the specified index. More...
diguyViewLightSettings *	find_light_settings (const char *settings_name)
	This function returns a pointer to the specified light settings. More...
int	load_light_settings (const char *settings_name, int light_num=0)
	This function loads the specified light settings into the scenario light. More...
void	set_use_override_ambient_material (int enabled)
	DI-Guy content has come from many sources over the years. More...
int	get_use_override_ambient_material ()
	Should this scenario override the ambient values on all materials. More...
void	set_global_ambient_material (float value)
	The value used to replace the ambient material's (expands to rgb) More...
float	get_global_ambient_material ()
	Returns the value used to replace the ambient material's (expands to rgb) More...
Info Popup Functions
Unless otherwise specified, callable from: C++ Script
int	get_num_info_popups ()
	Returns: number of info popups in the scenario. More...
diguyInfoPopup *	get_info_popup_at_index (int index)
	Returns: pointer of type diguyInfoPopup; NULL if no info popup at the specified index. More...
diguyInfoPopup *	find_info_popup (const char *name)
	This function returns a pointer to the specified info popup. More...
int	set_info_popup_default_encoding (const char *info_popup_default_encoding)
	This function sets the default encoding for info popups that do not have an encoding specified. More...
const char *	get_info_popup_default_encoding ()
	This function returns the default encoding of info popups. More...
Variable Functions
Unless otherwise specified, callable from: C++ Script
int	get_num_variables ()
	Returns: number of variables in the scenario. More...
diguyVariable *	get_variable_at_index (int index)
	Returns: pointer of type diguyVariable; NULL if no variable at the specified index. More...
diguyVariable *	find_variable (const char *name)
	This function returns a pointer to the specified variable. More...
diguyVariable *	find_or_create_variable (const char *name)
	This function finds the variable with the given name or creates it if it doesn't exist. More...
int	destroy_variable (diguyVariable *variable)
	This function destroys the passed variable. More...
Face Expression Functions
Unless otherwise specified, callable from: C++ Script
int	get_num_face_expressions ()
	Returns: number of face_expressions in the scenario. More...
diguyCharacterFaceExpression *	get_face_expression_at_index (int index)
	Returns: pointer of type diguyCharacterFaceExpression; NULL if no info popup at the specified index. More...
diguyCharacterFaceExpression *	find_face_expression (const char *name)
	This function returns a pointer to the specified face expression. More...
diguyCharacterFaceExpression *	create_face_expression (const char *name, const char *target_actor="exface")
	This function creates a new face expression with the given name. More...
int	destroy_face_expression (diguyCharacterFaceExpression *face_expression)
	This function destroys the passed face expression. More...
Chain Settings Functions
Unless otherwise specified, callable from: C++ Script
int	get_num_chain_settings ()
	Returns: number of chain settings in the scenario. More...
diguyChainSettings *	get_chain_settings_at_index (int index)
	Returns: pointer of type diguyChainSettings; NULL if no chain settings at the specified index. More...
diguyChainSettings *	find_chain_settings (const char *name)
	This function returns a pointer to the specified chain settings. More...
diguyChainSettings *	create_chain_settings (const char *name)
	This function creates a new chain settings and returns a pointer to it. More...
int	destroy_chain_settings (diguyChainSettings *chain_settings)
	This function destroys a chain settings. More...
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
int	map_event_handler_to_callback_id (int callback_id, const char *handler_name)
	This function maps the event handler with the given name to a callback id. More...
int	unmap_event_handler_from_callback_id (int callback_id, const char *handler_name, int unmap_all_matches=0)
	This function unmaps the event handler with the given name from a callback id. More...
diguyCallbackReturn	manually_invoke_event_handler (const char *handler_name)
	This function manually invokes the named scenario event handler. More...
int	register_character_event_handler (const char *handler_name, diguyCharacterCallback *callback, void *callback_user_data=0)
	This function registers a character event handler function that can later be mapped via a call to diguyCharacter::map_event_handler_to_callback_id(). More...
int	register_character_event_handler_from_library (const char *handler_name, const char *library_name, const char *function_name, void *callback_user_data=0)
	This function registers a character event handler function that can later be mapped via a call to diguyCharacter::map_event_handler_to_callback_id(). More...
int	register_character_event_handler_script (const char *handler_name, const char *handler_script, const char *handler_script_type=0)
	This function registers a character event handler script that can later be mapped via a call to diguyCharacter::map_event_handler_to_callback_id(). More...
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. More...
int	unregister_character_event_handler (const char *handler_name)
	This function unregisters a character event handler. More...
int	register_signal_event_handler (const char *handler_name, diguySignalCallback *callback, void *callback_user_data=0)
	This function is analogous to the register_character_event_handler() function, but is for signals rather than characters. More...
int	register_signal_event_handler_from_library (const char *handler_name, const char *library_name, const char *function_name, void *callback_user_data=0)
	This function is analogous to the register_character_event_handler_from_library() function, but is for signals rather than characters. More...
int	register_signal_event_handler_script (const char *handler_name, const char *handler_script, const char *handler_script_type=0)
	This function is analogous to the register_character_event_handler_script() function, but is for signals rather than characters. More...
int	has_registered_signal_event_handler (const char *handler_name)
	This function is analogous to the has_registered_character_event_handler() function, but is for signals rather than characters. More...
int	unregister_signal_event_handler (const char *handler_name)
	This function is analogous to the unregister_character_event_handler() function, but is for signals rather than characters. More...
int	register_sensor_region_event_handler (const char *handler_name, diguySensorRegionCallback *callback, void *callback_user_data=0)
	This function is analogous to the register_character_event_handler() function, but is for sensor regions rather than characters. More...
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)
	This function is analogous to the register_character_event_handler_from_library() function, but is for sensor regions rather than characters. More...
int	register_sensor_region_event_handler_script (const char *handler_name, const char *handler_script, const char *handler_script_type=0)
	This function is analogous to the register_character_event_handler_script() function, but is for sensor regions rather than characters. More...
int	has_registered_sensor_region_event_handler (const char *handler_name)
	This function is analogous to the has_registered_character_event_handler() function, but is for sensor regions rather than characters. More...
int	unregister_sensor_region_event_handler (const char *handler_name)
	This function is analogous to the unregister_character_event_handler() function, but is for sensor regions rather than characters. More...
int	register_variable_event_handler (const char *handler_name, diguyVariableCallback *callback, void *callback_user_data=0)
	This function is analogous to the register_character_event_handler() function, but is for variables rather than characters. More...
int	register_variable_event_handler_from_library (const char *handler_name, const char *library_name, const char *function_name, void *callback_user_data=0)
	This function is analogous to the register_character_event_handler_from_library() function, but is for variables rather than characters. More...
int	register_variable_event_handler_script (const char *handler_name, const char *handler_script, const char *handler_script_type=0)
	This function is analogous to the register_character_event_handler_script() function, but is for variables rather than characters. More...
int	has_registered_variable_event_handler (const char *handler_name)
	This function is analogous to the has_registered_character_event_handler() function, but is for variables rather than characters. More...
int	unregister_variable_event_handler (const char *handler_name)
	This function is analogous to the unregister_character_event_handler() function, but is for variables rather than characters. More...
Review Functions
Unless otherwise specified, callable from: C++ Script
int	save_review_data (const char *filename)
	This function saves the current run of the scenario to the specified file, and other files whose names are derived from the passed filename. More...
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) More...
int	set_history_type (diguyHistoryType history_type)
	This function sets what type of "history" will be kept for the scenario. More...
diguyHistoryType	get_history_type ()
	Returns: the current history type of the scenario; see set_history_type() More...
void	set_overall_history_type (diguyHistoryType overall_history_type)
	This function sets the history type for this scenario, as well as the history types of all characters. More...
diguyHistoryType	get_overall_history_type ()
	This function returns the overall history type of the scenario. More...
int	get_replaying_history ()
	Returns: whether the scenario is playing back stored history. More...
void	set_history_max_sound_instances (int num_sound_instances)
	This function sets how many sound instances are kept in memory when history is enabled. More...
LOD Functions and Instancing Functions
Unless otherwise specified, callable from: C++ Script
void	set_automatic_graphics_lod_switching (int enable_graphics_lod_switching)
	This function sets whether automatic graphics LOD switching should be enabled for certain graphics environments (see below). More...
int	get_automatic_graphics_lod_switching ()
	Returns: most recent setting of set_automatic_graphics_lod_switching() More...
int	set_character_culling_distance (float dist)
	Sets the maximum distance a character should draw from the camera. More...
float	get_character_culling_distance ()
	Returns the maximum distance a character should draw from the camera. More...
void	set_cull_bounds_scale_factor (float size)
	Sets a scale factor to use on the bounding sphere when determining if the character should draw. More...
float	get_cull_bounds_scale_factor ()
	gets a scale factor to use on the bounding sphere when determining if the character should draw. More...
int	set_vehicle_culling_distance (float dist)
	Sets the maximum distance a vehicle should draw from the camera. More...
float	get_vehicle_culling_distance ()
	Returns the maximum distance a vehicle should draw from the camera. More...
int	set_prop_culling_distance (float dist)
	Sets the maximum distance a prop should draw from the camera. More...
float	get_prop_culling_distance ()
	Returns the maximum distance a prop should draw from the camera. More...
void	set_instancing_enabled (int val)
	Turns on instancing system. More...
int	get_instancing_enabled () const
	Returns: if the instancing system is enabled. More...
void	set_instancing_min_lod (int val)
	Sets the minimum LOD that the instancing system turns on this defaults to LOD 4. More...
int	get_instancing_min_lod () const
	Returns: the minimum LOD that instancing activates. More...
void	set_visualize_instance_groups (int val)
	Sets visualization for instancing groups. More...
int	get_visualize_instance_groups () const
	Returns: the minimum LOD that instancing activates. More...
void	set_instancing_tbo_patching_enabled (int enable_patching)
	For scene graph renderers, it can be necessary to patch the texture buffer object after the scene graph finishes updating various post processes (ground clamping for instance), or modifying the TBO with a local space camera. More...
int	get_instancing_tbo_patching_enabled () const
void	set_instancing_position_callback_enabled (int use_user_position_matrices)
	trigger a callback on links fill out the transform data that belongs in the texture buffer object This will call diguyGraphicsLink::fill_out_tbo_position_matrix() for every instanced shape in the character. More...
int	get_instancing_position_callback_enabled () const
void	set_num_extra_per_instance_data_floats (int number)
	Allows the end user to set extra per instance data that will go to the video card and can be sampled. More...
int	get_num_extra_per_instance_data_floats () const
void	build_instance_groups ()
	Creates instancing groups, automatically done in diguyScenario::draw() for immediate mode renderers. More...
void	update_instancing_data ()
	Updates instancing data and sends to the video card. More...
void	get_tbo_instance_data (int &num_floats, const float *&data)
	gets the instancing data and allows you to send it to the video card. More...
void	set_default_lod_ranges (const char *character_type, float *ranges)
	Sets the distances at which level of detail switching occurs for characters of the specified type. More...
void	set_scale_graphics_lod_ranges_from_view_settings (int do_scale)
	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. More...
int	get_scale_graphics_lod_ranges_from_view_settings ()
	Returns: most recent setting of set_scale_graphics_lod_ranges_from_view_settings() More...
void	set_automatic_motion_lod_switching (int enable_motion_lod_switching)
	This function sets whether automatic motion LOD switching should be enabled. More...
int	get_automatic_motion_lod_switching ()
	This function returns whether automatic motion LOD switching is be enabled for characters in the scenario, as set by set_automatic_motion_lod_switching(). More...
Script Functions
Unless otherwise specified, callable from: C++ Script
int	eval_script (const char *script_text, int save_as_transient=0, const char *script_type=NULL, const char *script_source=NULL)
	This function sends the passed string through the script interpreter. More...
int	eval_script_file (const char *filename, const char *script_type=NULL)
	This function sends the contents of the specified file through the script interpreter. More...
int	trigger_script (const char *script_name)
	This function manually triggers a script. More...
void	trigger_script_delayed (const char *script_name, float t_delay)
	This function is similar to trigger_script(), but delays the trigger by the specified time. More...
int	trigger_decision (const char *decision_name)
	This function manually triggers a decision. More...
void	trigger_decision_delayed (const char *decision_name, float t_delay)
	This function is similar to trigger_decision(), but delays the trigger by the specified time. More...
void	push_transient_script_event (float t, const char *script_text, const char *script_type)
	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. More...
void	clear_transient_script_events ()
	This function deletes all transient script events. More...
int	save_transient_script_events (const char *filename)
	This function saves the transient script events to the specified file. More...
int	load_transient_script_events (const char *filename)
	This function loads transient script events saved by a call to save_transient_script_events(). More...
int	load_package (const char *filename, const char *language=NULL, int warn_if_not_found=1)
	This function creates a package object that points to an external file. More...
int	load_package_with_dependency (const char *filename, const char *depends_on_package, const char *language=NULL, int warn_if_not_found=1)
	This function creates a package object that points to an external file. More...
Meta-Action Functions
Unless otherwise specified, callable from: C++ Script
int	get_character_type_num_postures (const char *character_type)
	This function returns the number of postures the specified character type's actions support. More...
diguyMotionPosture	get_character_type_posture_at_index (const char *character_type, int index)
	This function returns the posture at the specified index. More...
diguyMotionPosture	get_character_type_action_posture (const char *character_type, const char *action_name)
	This function returns the overall posture of the specified action. More...
int	get_character_type_num_variants (const char *character_type)
	This function returns the number of variants the specified character type's actions support. More...
diguyMotionVariant	get_character_type_variant_at_index (const char *character_type, int index)
	This function returns the variant at the specified index. More...
diguyMotionVariant	get_character_type_action_primary_variant (const char *character_type, const char *action_name)
	This function returns the primary variant of the specified action. More...
int	get_character_type_action_num_variants (const char *character_type, const char *action_name)
	This function returns the number of variants the specified action of the specified character type has. More...
diguyMotionVariant	get_character_type_action_variant_at_index (const char *character_type, const char *action_name, int index)
	This function returns the variant at the specified index. More...
int	get_character_type_num_action_compatibility_names (const char *character_type, const char *action_name)
	This function returns the number of action compatibility names the specified action of the specified character type has. More...
const char *	get_character_type_action_compatibility_name_at_index (const char *character_type, const char *action_name, int index)
	This function returns the action compatibility name at the specified index. More...
int	get_character_type_num_directions (const char *character_type)
	This function returns the number of directions the specified character type's actions can move. More...
diguyMotionDirection	get_character_type_direction_at_index (const char *character_type, int index)
	Use the get_character_type_num_directions() function to get the number of directions available to a character. More...
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
int	get_num_interaction_machines ()
	Returns: number of interaction machines in the scenario. More...
diguyInteractionMachine *	create_interaction_machine (const char *name)
	This function creates a new interaction machine and returns a pointer to it. More...
void	destroy_interaction_machine (diguyInteractionMachine *interaction_machine)
	This function destroys the passed interaction machine. More...
diguyInteractionMachine *	get_interaction_machine_at_index (int index)
	Returns: pointer of type diguyInteractionMachine; NULL if no interaction machine at the specified index. More...
diguyInteractionMachine *	find_interaction_machine (const char *name)
	This function returns a pointer to the specified interaction machine. More...
diguyInteractionMachine *	get_active_interaction_machine ()
	This function returns a pointer to the "active" interaction machine. More...
diguyInteractionMachine *	get_shared_interaction_machine ()
	This function returns a pointer to the shared interaction machine that is always available. More...
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)
	This is a convenience function for using the shared interaction machine to show a notification to the user. More...
I-Guy Functions
Unless otherwise specified, callable from: C++ Script
diguyIGuyController *	get_iguy_controller ()
	This function returns a pointer to the I-Guy controller object of the scenario. More...
Label Functions
Unless otherwise specified, callable from: C++ Script
diguyViewLabel *	find_or_create_label (const char *name)
	This function finds the diguyViewLabel with the given name or creates it if it doesn't exist. More...
diguyViewLabel *	find_label (const char *name)
	This function returns a pointer to the specified diguyViewLabel. More...
int	destroy_label (diguyViewLabel *label)
	This function destroys the passed in diguyViewLabel. More...
int	get_num_labels ()
	Returns: The number of diguyViewLabel objects in the scenario. More...
diguyViewLabel *	get_label_at_index (int index)
	Returns: The diguyViewLabel at the given index. More...
void	reset_labels ()
	This function removes all diguyViewLabels in the scenario. More...
void	send_label_to_front (diguyViewLabel *label)
	This function moves the specified diguyViewLabel to the front of the drawing list. More...
void	send_label_to_back (diguyViewLabel *label)
	This function moves the specified diguyViewLabel to the back of the drawing list. More...
int	draw_character_labels ()
	Functions that allow the built-in OGL renderer to draw labels on screen for debugging use, update_character_labels must be called first. More...
void	update_character_labels ()
	See draw_character_labels. More...
Button Panel Functions
Unless otherwise specified, callable from: C++ Script
diguyViewButtonPanel *	find_or_create_panel (const char *name, int horizontal=0, int title=1)
	This function finds the diguyViewButtonPanel with the given name or creates it if it doesn't exist. More...
diguyViewButtonPanel *	find_panel (const char *name)
	This function returns a pointer to the specified diguyViewButtonPanel. More...
int	destroy_panel (diguyViewButtonPanel *panel)
	This function destroys the passed in diguyViewButtonPanel. More...
int	get_num_panels ()
	Returns: The number of diguyViewButtonPanel objects in the scenario. More...
diguyViewButtonPanel *	get_panel_at_index (int index)
	Returns: The diguyViewButtonPanel at the given index. More...
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
int	get_num_minds ()
	This function returns the number of AI minds that are available to AI agent characters. More...
const char *	get_mind_name_at_index (int index)
	Returns: name of the AI mind at the specified index. More...
int	is_valid_character_pointer (diguyCharacter *character)
	This function tests if a diguyCharacter pointer is a valid pointer. More...
int	is_valid_character_group_pointer (diguyCharacterGroup *character_group)
	This function tests if a diguyCharacterGroup pointer is a valid pointer. More...
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
diguyCrowd *	create_crowd (const char *name, int make_companion_of_all=1)
	This function creates a new crowd and returns a pointer to it. More...
int	destroy_crowd (diguyCrowd *crowd, int also_destroy_crowd_members=0, int also_destroy_path_shapes=0, int delay_destruction=0)
	This function destroys a crowd. More...
int	get_num_crowds ()
	Returns: the number of crowds in the scenario. More...
diguyCrowd *	get_crowd_at_index (int index)
	Returns: pointer of type diguyCrowd; NULL if no crowd at the specified index. More...
const char *	get_unique_crowd_name (const char *base_name)
	Returns: A unique name based on base_name, e.g. More...
diguyCrowd *	find_crowd (const char *crowd_name)
	This function returns a pointer to the specified crowd. More...
diguyCrowd *	find_or_create_crowd (const char *crowd_name, int make_companion_of_all=1)
	This function returns a pointer to the crowd with the given name. More...
void	set_create_network_crowds (int do_create)
	This function sets whether crowds should be created for incoming network entities. More...
int	get_create_network_crowds ()
	Returns: 1 if network crowds will be created; 0 if not. More...
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
diguyCrowdProfile *	create_crowd_profile (const char *name)
	This function creates a new crowd profile and returns a pointer to it. More...
int	destroy_crowd_profile (diguyCrowdProfile *crowd_profile)
	This function destroys a crowd profile. More...
int	get_num_crowd_profiles ()
	Returns: The number of crowd profiles in the scenario. More...
diguyCrowdProfile *	get_crowd_profile_at_index (int index)
	Returns: pointer of type diguyCrowdProfile; NULL if no crowd profile at the specified index. More...
diguyCrowdProfile *	find_crowd_profile (const char *name)
	This function returns a pointer to the specified crowd profile. More...
Load Manager Functions
Unless otherwise specified, callable from: C++ Script
diguyLoadManager *	get_character_load_manager ()
	Returns: pointer of type diguyLoadManager; this scenario's character load manager. More...
Octtree Functions
Unless otherwise specified, callable from: C++ Script
int	force_octtree_generation ()
	This function forces the octtree to rebuild if it's out of date. More...
void	add_character_to_octtree (diguyCharacter *character, int use_bounding_box_only=0)
	Adds the given character to the octtree. More...
void	remove_character_from_octtree (diguyCharacter *character)
	Removes the given character from the octtree. More...
int	preload_octtree (const char *character_type, const char *appearance)
	Preloads the given appearance for the character with octtree data. More...
int	check_visibility (float x1, float y1, float z1, float x2, float y2, float z2)
	This function uses the octtree to check if the path between x1, y1, z1 and x2, y2, z2 has any static obstructions. More...
Altitude Functions
Unless otherwise specified, callable from: C++ Script
int	set_default_character_altitude_function (diguyAltitudeFunction *altitude_function)
	This function sets a default altitude function that will be added to all characters that are subsequently created. More...
void	set_altitude_function (diguyScenarioAltitudeFunction *altitude_function)
	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. More...
diguyScenarioAltitudeFunction *	get_altitude_function ()
	Returns: the altitude function for the scenario as set by set_altitude_function() More...
void	set_altitude_max_climb (float altitude_max_climb)
	Sets the height above the current altitude the ground clamp vector will begin. More...
float	get_altitude_max_climb ()
void	set_altitude_max_drop (float altitude_max_drop)
	The maximum amount below the current altitude that a character can drop via the altitude function. More...
float	get_altitude_max_drop ()
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. diguyScenario::set_default_point_los_function() diguyScenario::set_default_character_los_function() diguyScenario::set_default_agent_feeler_function() diguyScenario::set_default_character_altitude_function() diguyScenario::set_altitude_function() diguyScenario::get_altitude_function() diguyScenario::set_fire_weapon_intersection_function() diguyScenario::set_default_fire_weapon_intersection_function()
int	set_default_point_los_function (diguyPointLOSFunction *point_los_function)
	This function sets a default point line of sight function that will be added to all new characters. More...
int	set_default_character_los_function (diguyCharacterLOSFunction *character_los_function)
	This function sets a default character line of sight function that will be added to all new characters. More...
int	set_default_agent_feeler_function (diguyFeelerFunction *feeler_function)
	This function sets a default feeler function that will be added to all new DI-Guy AI agents. More...
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)
	Experimental intersection-detection function. More...
Path Planning and Regions
Unless otherwise specified, callable from: C++ Script
diguyRegion *	find_or_create_region (const char *name)
	This function returns a pointer to the region with the given name. More...
diguyRegion *	find_region (const char *name)
	This function returns a pointer to the specified region. More...
diguyRegion *	create_region (const char *name)
	This function creates a new diguyRegion and returns a pointer to it. More...
void	destroy_region (diguyRegion *region)
	This function destroys the passed region. More...
int	get_num_regions ()
	Returns: number of regions in the scenario. More...
diguyRegion *	get_region_at_index (int index)
	Returns: pointer of type diguyRegion; NULL if no region at the specified index. More...
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)
	The scenario will attempt to create a navigation path on the via_region. More...
void	set_max_distance_planning_multiplier (float mul)
	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. More...
float	get_max_distance_planning_multiplier ()
	Returns: float constant that's used to decide if planner should give up; -1 means off. More...
float	get_time_spent_path_planning_this_frame ()
	This function returns in seconds how much time has been spent path planning during the current frame. More...
void	set_multithreaded_path_planning_enabled (int value)
	This function enables the path planner to run in a background thread. More...
int	get_multithreaded_path_planning_enabled ()
	Returns: Returns 1 if the path planner is enabled to run in a background thread. More...
Formation Functions
Unless otherwise specified, callable from: C++ Script
int	get_num_formations ()
	Returns: number of formations in the scenario. More...
diguyFormation *	get_formation_at_index (int index)
	Returns: pointer of type diguyFormation; NULL if no formation at the specified index. More...
diguyFormation *	find_formation (const char *name)
	This function returns a pointer to the specified formation. More...
diguyFormation *	find_formation_of_size (int size)
	This function returns a pointer to the first formation it finds of a given size. More...
diguyFormation *	create_formation (const char *name)
	This function creates a new formation and returns a pointer to it. More...
diguyFormation *	find_or_create_formation (const char *name)
	This function finds the formation with the given name or creates it if it doesn't exist. More...
int	destroy_formation (diguyFormation *formation)
	This function destroys a formation. More...
DI-Guy Supplemental Graphics Functions
These functions show or hide various 3D supplemental visuals in OpenGL. There use is limited to the DI-Guy Scenario application and examples that use the non-graphics api DI-Guy OpenGL renderer. They correspond to the UI in the DI-Guy Scenario page Scenario Objects | Scenario Objects | Visibility. Unless otherwise specified, callable from: C++ Script
void	set_draw_authoring_visuals (int visible)
	Required to turn on visual aids in programming examples. More...
int	get_draw_authoring_visuals ()
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_gaze_vector_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_gaze_vectors_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 ()
DI-Guy Weapon Fire Effects Functions
Unless otherwise specified, callable from: C++ Script
int	get_weapon_flash_enabled ()
	Returns: If weapon fire will show flash geometry, (depending on munition configuration) More...
int	set_weapon_flash_enabled (int enabled)
	Sets if weapon fire will create weapon geometry, (depending on munition configuration) More...
int	get_weapon_fire_effects_enabled ()
	Returns: If weapon fire will create light flashes, smoke and shell ejections, (depending on munition configuration) More...
int	set_weapon_fire_effects_enabled (int enabled)
	Sets if weapon fire will create light flashes, smoke and shell ejections, (depending on munition configuration) More...
int	get_num_active_fire_effects ()
	Returns: The number of light flashes that are currently active. More...
int	get_weapon_fire_effect_data (int index, float *radius, double *position_x, double *position_y, double *position_z, float *color_r, float *color_g, float *color_b, float *falloff_r, float *falloff_rsq)
	This function gets the data needed for producing a weapon flash light source in the world. More...
int	get_num_active_lights ()
	Returns: The number of lights that are currently active, should be valid after update is called. More...
int	sort_active_lights ()
	sorts the list of active lights for this frame More...
int	get_active_light_data (int index, diguyLightRenderDesc *light_desc)
	This function gets the data needed for producing a particle system or vehicle light. More...
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
int	set_current_character (diguyCharacter *current_character)
	Sets the current selected character in scenario. More...
diguyCharacter *	get_current_character ()
	Returns: The current selected character in scenario. More...
int	get_current_character_index ()
	The current selected character's index. More...
int	set_current_crowd (diguyCrowd *current_crowd)
	Sets the current selected crowd in scenario. More...
diguyCrowd *	get_current_crowd ()
	Returns: The current selected crowd in scenario. More...
int	set_current_crowd_profile (diguyCrowdProfile *current_profile)
	Sets the active crowd profile, which determines the attributes of subsequently-created crowds. More...
int	set_current_crowd_profile_by_name (const char *crowd_profile_name)
	Sets the active crowd profile by name. More...
diguyCrowdProfile *	get_current_crowd_profile ()
	Returns: Active crowd profile. More...
int	set_current_region (diguyRegion *current_region)
	Sets the current region. More...
diguyRegion *	get_current_region ()
	Returns: Current region. More...
Particle System Functions
void	set_particle_module_disabled (int disable_particle_module)
	This function enables or disables the particle module. More...
int	create_particle_system (const char *description_name, float x, float y, float z, int record_transient_event=1, float duration=-1.0f)
	This function creates a particle system with type description_name at x, y, z. More...
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)
	Similar to create_particle_system(), but allows orientation to be set. More...
int	has_particle_description (const char *description_name)
	Returns: 1 if the particle description named description_name exists, else 0. More...
void	set_global_wind (float x, float y, float z)
	Set wind velocity vector for particle system. More...
Lua Scripting Module Functions
const char *	lua_get_object_field_as_string (const char *lua_object, const char *field_name)
	Returns: string representation of lua_object.field_name. More...
const char *	lua_evaluate_object_function (const char *lua_object, const char *function_name, const char *argument=NULL, int has_return_string=0)
	Runs a member function of a lua object. More...
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)
	A two argument version of lua_evaluate_object_function(). More...
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)
	A three argument version of lua_evaluate_object_function(). More...
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)
	A four argument version of lua_evaluate_object_function(). More...
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)
	Executes a lua_object:state_manager() function call. More...
void *	get_lua_state ()
	This function allows low level access to the lua_State pointer. More...
int	push_qt_pointer_to_lua (void *lua_state, const char *class_name, void *ptr)
	Mainly used to pass a qt pointer to lua so lqt can be used to modify/read from the widget. More...
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)
	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. More...
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)
	Effectively the same as diguyScenario::lua_evaluate_object_function_4a_flex() but works on global functions. More...
int	lua_log_printf (int notify_level, const char *string)
	Prints a message to lua interpreter log object. More...
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. More...
Messaging Functions
int	send_message (diguyCharacter *to_character, diguyCharacter *from_character, const char *message_type, const char *message, const char *message_params=NULL)
	Sends a message to specified diguyCharacter. More...
int	broadcast_message (diguyCharacter *from_character, float radius, const char *message_type, const char *message, const char *message_params=NULL)
	Broadcasts a message to all other diguyCharacters within a certain radius of the from_character. More...
int	broadcast_message_to_group (diguyCharacter *from_character, const char *group_name, float radius, const char *message_type, const char *message, const char *message_params=NULL)
	Broadcasts a message to all diguyCharacters within named group, who are within given radius of the from_character. More...
Experimental Functions
The following functions are experimental and may change or disappear with no warning.
int	get_eval_decisions_as_scripts ()
	Returns: value set by last call to set_eval_decisions_as_scripts() More...
void	set_eval_decisions_as_scripts (int eval_decisions_as_scripts)
	If called with an argument of 1, all decision beads and decision beads will be converted to scripts before being run. More...
diguyImpact *	get_impact_on_line (float from_x, float from_y, float from_z, float to_x, float to_y, float to_z)
	Gets the point of impact with the world along specified line segment. More...
void	wait_cursor_push ()
	Increments wait cursor counter. More...
void	wait_cursor_pop ()
	Decrements wait cursor counter. More...
diguyParticleSystemRenderer *	get_particle_renderer ()
	returns pointer to current particle renderer implementation More...
void	set_character_sorting_enabled (int enabled)
	turns off the sorting of characters for drawing, practical for retained mode renderers More...
int	get_character_sorting_enabled ()
void	set_graphics_api_node_ptr (void *node_ptr)
	This function sets a generic node pointer that can later be retrieved by the get_graphics_api_node_ptr() call. More...
void *	get_graphics_api_node_ptr ()
	Returns: pointer set by most recent call to set_graphics_api_node_ptr. More...
void	set_draw_character_shadow_disks (int draw_character_shadow_disks)
	Sets whether shadow disks are drawn for characters. More...
int	get_draw_character_shadow_disks ()
	Returns: 1 if shadow disks are drawn, 0 if not. More...
int	get_shadow_map_size ()
	Returns: size of texture map for shadows. More...
int	set_shadow_map_size (int shadow_size)
	Sets size of texture map for shadows. More...
void	set_default_character_scene_graph_mask (unsigned long mask)
	Used for DI-Guy OSG Author Programming Example. More...
unsigned long	get_default_character_scene_graph_mask ()
void	set_default_scene_object_scene_graph_mask (unsigned long mask)
	Used for DI-Guy OSG Author Programming Example. More...
unsigned long	get_default_scene_object_scene_graph_mask ()
void	set_internal_int (int var, int val)
	For internal use. More...
void	set_internal_float (int var, float val)
int	set_num_active_point_lights (int active_lights)
	This sets the number of point lights that get handed down to diguyGraphicsShaderTechnique::pick_shader_program(). More...
int	get_num_active_point_lights ()
	This gets the number of point lights that get handed down to diguyGraphicsShaderTechnique::pick_shader_program() the default is 0. More...
Experimental Performance Functions
int	set_world_bounds (float x_min, float y_min, float z_min, float x_max, float y_max, float z_max)
	Sets bounding box of world. More...
int	get_world_bounds (float *x_min, float *y_min, float *z_min, float *x_max, float *y_max, float *z_max)
	Gets bounding box of world. More...
Experimental Checkpoint Functions
void	set_checkpoint_frequency (float freq)
	Internal use. More...
float	get_checkpoint_frequency ()
	Internal use. More...
void	set_checkpointing_enabled (int enable_checkpointing)
	Internal use. More...
int	get_checkpointing_enabled ()
	Internal use. More...
Experimental Shader Functions
void	set_initial_render_mode (const char *render_mode)
	Sets initial render mode. More...
const char *	get_initial_render_mode ()
	Returns: initial render mode, as string. More...
void	set_current_render_mode (const char *render_mode)
	Sets current render mode. More...
const char *	derive_render_mode_from_light_settings (int set_current_to_derived=1)
	Returns: render mode, as string, derived from current light settings. More...
const char *	get_current_render_mode ()
	Returns current render mode, as string. More...
void	set_default_character_shader (const char *render_mode, const char *shader_name, int update_existing_characters=1)
	Sets default shader for characters. More...
const char *	get_default_character_shader (const char *render_mode)
	Returns name of shader technique used for specified render mode. More...
void	set_default_scene_object_shader (const char *render_mode, const char *shader_name, int update_existing_scene_objects=1)
	Sets default shader for scene objects. More...
const char *	get_default_scene_object_shader (const char *render_mode)
	Returns name of shader technique used for specified render mode. More...
void	set_default_particle_system_shader (const char *render_mode, const char *shader_name, int update_existing_particle_systems=1)
	Sets default shader for particle systems. More...
const char *	get_default_particle_system_shader (const char *render_mode)
	Returns name of shader technique used for specified render mode. More...
int	facefx_mount_animset (const char *actor_name, const char *file_name)
	Sets FaceFX animation set for a given actor. More...
int	set_vehicle_smoothing_enabled (int enable_smoothing)
	Sets vehicle smoothing on or off. More...
int	get_vehicle_smoothing_enabled ()
int	set_realtime_ik_enabled (int val)
	Sets realtime IK on or off. More...
int	get_realtime_ik_enabled ()
int	set_draw_ik_visuals (int val)
int	get_draw_ik_visuals ()
int	set_draw_skeletons (int val)
int	get_draw_skeletons ()
float	get_last_update_time ()
void	set_disable_profiler ()
const char *	get_lua_field_as_string (const char *lua_object, const char *field_name, int warn_if_no_field=1)
float	get_lua_field_as_float (const char *lua_object, const char *field_name, int warn_if_no_field=1, int *found_field=NULL)
void	update_particle_preview (float time)

General Functions
Unless otherwise specified, callable from: C++ Script
static diguyScenario *	get_current_scenario ()
	This static function returns a pointer to the current scenario object. More...
const char *	get_name ()
	Returns the name of the object. More...
const char *	get_type_name ()
	Returns the type name of the object. More...
const char *	get_description ()
	Returns: the scenario description as specified in the scenario info page. More...

Callback Functions
Unless otherwise specified, callable from: C++ Script
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_LEFT_CLICK_SCENE, CALLBACK_ID_RIGHT_CLICK_SCENE,   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 }
	This is an enumeration of the different callbacks that can be registered with add_callback() and add_callback_script(). More...
int	add_callback (int callback_id, diguyScenarioCallback *callback, void *callback_params=0, void *callback_user_data=0, int remove_on_scenario_load=1)
	This function adds a scenario callback. More...
int	remove_callback (int callback_id, diguyScenarioCallback *callback)
	This function removes a user callback. More...
int	remove_callback_with_user_data (int callback_id, void *callback_user_data)
	This function removes a user callback. More...
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)
	This function sets a default user callback that will be added to all new characters. More...
int	remove_default_character_callback (int callback_id, diguyCharacterCallback *callback)
	This function removes a user callback. More...
int	remove_default_character_callback_with_user_data (int callback_id, void *callback_user_data)
	This function removes a default user callback previously added by add_default_character_callback(). More...
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)
	This function sets a default user callback that will be added to all new sensor regions. More...
int	remove_default_sensor_region_callback (int callback_id, diguySensorRegionCallback *callback)
	This function removes a user callback. More...
int	remove_default_sensor_region_callback_with_user_data (int callback_id, void *callback_user_data)
	This function removes a default user callback. More...
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)
	This function adds a default user callback that will be added to all new signals. More...
int	remove_default_signal_callback (int callback_id, diguySignalCallback *callback)
	This function removes a user callback. More...
int	remove_default_signal_callback_with_user_data (int callback_id, void *callback_user_data)
	This function removes a default user callback. More...
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)
	This function adds a default user callback that will be added to all new variables. More...
int	remove_default_variable_callback (int callback_id, diguyVariableCallback *callback)
	This function removes a user callback. More...
int	remove_default_variable_callback_with_user_data (int callback_id, void *callback_user_data)
	This function removes a default user callback. More...
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)
	This function adds a default user callback that will be added to all new views. More...
int	remove_default_view_callback (int callback_id, diguyViewCallback *callback)
	This function removes a user callback. More...
int	remove_default_view_callback_with_user_data (int callback_id, void *callback_user_data)
	This function removes a default user callback. More...
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)
	This function adds a default user callback that will be added to all cameras. More...
int	remove_default_camera_callback (int callback_id, diguyViewCameraCallback *callback)
	This function removes a user callback. More...
int	remove_default_camera_callback_with_user_data (int callback_id, void *callback_user_data)
	This function removes a default user callback. More...
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)
	This function adds a default user callback that will be added to all new fogs. More...
int	remove_default_fog_callback (int callback_id, diguyViewFogCallback *callback)
	This function removes a user callback. More...
int	remove_default_fog_callback_with_user_data (int callback_id, void *callback_user_data)
	This function removes a default user callback. More...
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)
	This function adds a default user callback that will be added to all new lights. More...
int	remove_default_light_callback (int callback_id, diguyViewLightCallback *callback)
	This function removes a user callback. More...
int	remove_default_light_callback_with_user_data (int callback_id, void *callback_user_data)
	This function removes a default user callback. More...
void	manually_invoke_callbacks_now (int callback_id)
	This function causes all of the scenario callbacks with the given callback_id to be called now. More...
int	add_callback_script (int callback_id, const char *callback_script, const char *callback_script_type=NULL, int remove_on_scenario_load=1)
	This function adds a user callback script. More...
int	remove_callback_script (int callback_id, const char *callback_script, const char *callback_script_type=NULL)
	This function removes a user callback script previously added with add_callback_script(). More...
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)
	This function adds a default character callback script. More...
int	remove_default_character_callback_script (int callback_id, const char *callback_script, const char *callback_script_type=NULL)
	This function removes a default character callback script. More...
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)
	This function adds a default sensor region callback script. More...
int	remove_default_sensor_region_callback_script (int callback_id, const char *callback_script, const char *callback_script_type=NULL)
	This function removes a default sensor region callback script. More...
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)
	This function adds a default signal callback script. More...
int	remove_default_signal_callback_script (int callback_id, const char *callback_script, const char *callback_script_type=NULL)
	This function removes a default signal callback script. More...
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)
	This function adds a default variable callback script. More...
int	remove_default_variable_callback_script (int callback_id, const char *callback_script, const char *callback_script_type=NULL)
	This function removes a default variable callback script. More...
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)
	This function adds a default view callback script. More...
int	remove_default_view_callback_script (int callback_id, const char *callback_script, const char *callback_script_type=NULL)
	This function removes a default character view script. More...
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)
	This function adds a default camera callback script. More...
int	remove_default_camera_callback_script (int callback_id, const char *callback_script, const char *callback_script_type=NULL)
	This function removes a default camera callback script. More...
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)
	This function adds a default fog callback script. More...
int	remove_default_fog_callback_script (int callback_id, const char *callback_script, const char *callback_script_type=NULL)
	This function removes a default fog callback script. More...
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)
	This function adds a default light callback script. More...
int	remove_default_light_callback_script (int callback_id, const char *callback_script, const char *callback_script_type=NULL)
	This function removes a default light callback script. More...

Impact and Hit Detection Functions
Unless otherwise specified, callable from: C++ Script
static void	set_default_intersection_function (diguyScenarioIntersectionFunction *intersection_function)
	Sets the default intersection function. More...
static void	set_default_fire_weapon_intersection_function (diguyScenarioFindImpactOnLineFunction *impact_function)
	This function sets an impact function that will be added to all new scenarios. More...
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, int ground_clamp_impact=1)
	Creates a detonation using the specified munition name. More...
diguyImpact *	find_character_at_screen_coords (diguyView *view, float sx, float sy)
	This function checks for intersection against characters in the specified view. More...
diguyImpact *	get_impact_at_screen_coords (diguyView *view, float sx, float sy, int use_octtree=0)
	This function creates an impact object based on the sx and sy in the specified view. More...
diguyImpact *	get_intersection_at_screen_coords (diguyView *view, float sx, float sy, int use_octtree=0)
	This function checks for intersection against the world and characters in the specified view. More...
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)
	This function checks for intersection against the world and returns basic collision results. More...
float	ground_clamp (float x, float y, float z, int *valid=NULL, int use_altitude_function=1, int use_octtree=0)
	This function returns the z height, or altitude, of the uppermost piece of terrain under the passed x, y, z point. More...
int	set_fire_weapon_intersection_function (diguyScenarioFindImpactOnLineFunction *impact_function)
	The following prototype should be used for the impact function: More...
diguyImpact *	map_color_to_impact (char r, char g, char b)
	Most DI-Guy visual objects (e.g., characters, path shapes, waypoints) have a unique identified, or UID. More...
diguyImpact *	get_last_env_impact_info ()
	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. More...
void	set_last_impact_been_processed ()
	Reading of data from the last impact information will be considered complete when this function is called. More...
void	set_last_env_impact_info (const diguyImpact &impact)
	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(). More...
void	set_max_unprocessed_impacts (int max_unprocessed_impacts)
	Sets the maximum number of unprocessed impacts there can be. More...

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.
static int	add_default_callback (int callback_id, diguyScenarioCallback *callback, void *callback_params=0, void *callback_user_data=0)
	Deprecated; use diguyApp::add_default_scenario_callback() instead. More...
static int	remove_default_callback (int callback_id, diguyScenarioCallback *callback)
	Deprecated; use diguyApp::remove_default_scenario_callback() instead. More...
static int	remove_default_callback_with_user_data (int callback_id, void *callback_user_data)
	Deprecated; use diguyApp::remove_default_scenario_callback_with_User_data() instead. More...
static int	add_default_callback_script (int callback_id, const char *callback_script, const char *callback_script_type)
	Deprecated; use diguyApp::add_default_scenario_callback_script() instead. More...
static int	remove_default_callback_script (int callback_id, const char *callback_script, const char *callback_script_type)
	Deprecated; use diguyApp::remove_default_scenario_callback_script() instead. More...
int	get_character_type_num_head_appearances (const char *character_type)
	Similar to get_character_type_num_appearances(), but for head appearances. More...
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. More...
const char *	get_character_type_class (const char *character_type)
	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) More...
int	merge_asset (const char *string)
	Deprecated as of 10.5.1; use merge_object() intead. More...
void	print_to_log (int notify_level, const char *string)
	Deprecated as of 12.0.0; use bdi_log_print() from libbdilog.h instead. More...
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)
	Deprecated as of 12.0.0; use save_as() instead. More...
const char *	get_project_filename ()
	Deprecated as of 12.0.0; use get_filename() or get_filename_without_directory() intead. More...

Private Functions
The functions and variables past this point are for internal use only. No external access to them is expected or necessary.
bdiScenario *	m_scenario
	A pointer to internal data. More...
float	m_last_update_time
class	bdiScenario
bdiScenario *	get_scripted_object ()
	diguyScenario (bdiScenario *scenario)
	A private constructor. More...
virtual	~diguyScenario ()
	A private destructor. More...

Detailed Description

Represents the scenario currently being portrayed.

A scenario is loaded from disc and contains characters, geometry, appearances, scripts, minds, paths, waypoints, scripts, signals, sounds, groups, crowds, regions, cameras, fog, lights, variables, callbacks, and the octtree.

All these items and their interactions are the raison d'être for DI-Guy, so diguyScenario is an important class to understand. It provides facilities for loading, adding, removing, and configuring the objects mentioned above, and for managing the flow of time, sending messages, triggering scripts, and testing for collisions with the geometry. There are many other features, as well.

Member Enumeration Documentation

anonymous enum

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

Callbacks return a value of type diguyCallbackReturn, which will be DIGUY_CALLBACK_STOP or DIGUY_CALLBACK_CONTINUE. If the callback returns DIGUY_CALLBACK_STOP, 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.

Enumerator
CALLBACK_ID_CREATE
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_LEFT_CLICK_SCENE
CALLBACK_ID_RIGHT_CLICK_SCENE
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

Constructor & Destructor Documentation

diguyScenario::diguyScenario ( bdiScenario *  scenario )

private

A private constructor.

Use the DI-Guy function diguy_create_scenario() to obtain a diguyScenario object pointer.

virtual diguyScenario::~diguyScenario ( )

privatevirtual

A private destructor.

Use the DI-Guy function diguy_destroy_scenario() to delete a diguyScenario object pointer.

Member Function Documentation

static diguyScenario* diguyScenario::get_current_scenario ( )

static

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

const char* diguyScenario::get_name

(

)

Returns the name of the object.

This pointer will never be NULL.

Returns:

name of the object

const char* diguyScenario::get_type_name

(

)

Returns the type name of the object.

This pointer will never be NULL.

Returns:

type name of the object

const char* diguyScenario::get_description

(

)

Returns: the scenario description as specified in the scenario info page.

int diguyScenario::update

(

float

t

)

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.

Parameters

t	desired time in seconds

Returns:

0 on success, -1 on failure

Callable From:

• C++

int diguyScenario::update2	(	float	t,
		float	realtime_t
	)

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

Parameters

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

Returns:

0 on success, -1 on failure

Callable From:

• C++

int diguyScenario::set_playback_loop

(

int

playback_loop

)

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

Parameters

playback_loop

pass 1 to have scenario loop at tout, 0 to not

Returns:

0 on success, -1 on failure

Callable From:

• C++

int diguyScenario::set_tick_dt

(

float

tick_dt

)

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.

Parameters

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
}

float diguyScenario::get_t

(

)

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

float diguyScenario::get_realtime_t

(

)

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

float diguyScenario::get_desired_t

(

)

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

int diguyScenario::set_tout

(

float

tout

)

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

float diguyScenario::get_tout

(

)

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

void diguyScenario::set_tout_enabled

(

int

tout_enabled

)

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.

int diguyScenario::get_tout_enabled

(

)

This function returns the whether tout is enabled.

See set_tout_enabled() and update().

Returns:

1 if tout enabled, 0 if not

int diguyScenario::get_playback_loop

(

)

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

float diguyScenario::get_tick_dt

(

)

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

int diguyScenario::get_ticks_can_be_dropped

(

)

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

void diguyScenario::set_ticks_can_be_dropped

(

int

ticks_can_be_dropped

)

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.

Parameters

ticks_can_be_dropped

pass 1 for ticks to be dropped; else pass 0

long diguyScenario::get_max_ticks_behind_until_drop

(

)

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

void diguyScenario::set_max_ticks_behind_until_drop

(

long

max_ticks_behind_until_drop

)

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 0 in the DI-Guy SDK, In DI-Guy Scenario it is 2.

Parameters

max_ticks_behind_until_drop

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

int diguyScenario::set_playback_mode

(

diguyScenarioPlaybackMode

playback_mode

)

This function sets the current playback mode of DI-Guy Scenario.

It currently will have no effect in applications using the DI-Guy API.

Parameters

playback_mode

new playback mode

Returns:

0 on success, -1 on failure

int diguyScenario::set_playback_mode_stop

(

)

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

int diguyScenario::set_playback_mode_play

(

)

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

diguyScenarioPlaybackMode diguyScenario::get_playback_mode

(

)

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

float diguyScenario::derive_playback_mode_dt

(

float

dt_in

)

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.

Parameters

dt_in

delta time in seconds from advancing simulation time

int diguyScenario::reset

(

)

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

int diguyScenario::load

(

const char *

filename

)

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.

Parameters

filename

filename of scenario to be loaded

Returns:

0 on success, -1 on failure

Callable From:

• C++

int diguyScenario::save

(

)

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

int diguyScenario::save_as

(

const char *

filename

)

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

Parameters

filename

new filename of scenario

Returns:

0 on success, -1 on failure

Callable From:

• C++

const char* diguyScenario::get_filename

(

)

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

const char* diguyScenario::get_filename_without_directory

(

)

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

Callable From:

• C++

int diguyScenario::get_unsaved

(

)

Returns: 1 if scenario has been modified since save or load, else 0.

Callable From:

• C++

void diguyScenario::set_unsaved

(

int

unsaved

)

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

Parameters

unsaved

new unsaved status; 1 for unsaved, 0 for saved

Callable From:

• C++

int diguyScenario::draw

(

)

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:

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

int diguyScenario::draw_pass1

(

)

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

This function draws all opaque polygons.

Returns:

0 on success, -1 on failure

OpenGL Version:

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

int diguyScenario::draw_pass2

(

int

also_call_post_draw = 1

)

Same as draw_pass1(), but draws transparent scenario elements.

The also_call_post_draw argument is set to 1 for backwards compatibility.

int diguyScenario::draw_particles

(

)

Explicitly invokes particle drawing code, this can be useful for retained mode renderers that have chosen to hook up our immediate mode particle system as a post draw stage (osg)

void diguyScenario::pre_draw_cull_state_reset

(

)

Clears all the culling bits state for various characters, this should be called before any drawing is done.

It allows for multiple draw passes culling state info to get accumulated together. This is needed to efficiently avoiding updating graphics classes for characters that are out of all rendering viewports. If a character is generally visible we will update it's state with our multi-threaded pipeline. If it's not visible. then we won't update it until it's actually drawn. In retained mode renderers diguyCharacter::set_is_culled(0) must be set for each character that is drawn so that we know to update it's state in the faster manor.

void diguyScenario::post_draw_cull_state_save

(

)

Saves all the culling bits for various characters, should be called after all drawing is done so that the next call to update() has reasonable culling information to work with.

See pre_draw_cull_state_reset() for more information about graphics update culling.

void diguyScenario::calculate_character_lods

(

)

This function updates all character lods and updates the instancing system representation of the characters calling this is needed for the instancing system to work.

int diguyScenario::post_draw	(	int	call_plugins_post_draw = 1,
		int	call_lua_packages_draw = 1,
		int	call_post_draw_callback = 1
	)

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.

Parameters

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

int diguyScenario::set_graphics_attach_ptr

(

void *

graphics_attach_ptr

)

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

Parameters

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

diguyScenarioMergeSettings* diguyScenario::create_merge_settings

(

diguyScenarioMergeInitialSettings

initial_settings = DIGUY_MERGE_INITIAL_SETTINGS_DEFAULT

)

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

Parameters

initial_settings

what the initial settings should be when the object is created

DIGUY_MERGE_INITIAL_SETTINGS_DEFAULT

Parameters

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

Parameters

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

Parameters

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

Parameters

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

void diguyScenario::destroy_merge_settings

(

diguyScenarioMergeSettings *

merge_settings

)

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

int diguyScenario::merge	(	const char *	filename,
		diguyScenarioMergeSettings *	merge_settings = NULL
	)

This function merges the specified scenario.

Any previously loaded scenario elements will be retained, depending on settings in the merge_settings argument.

Parameters

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

int diguyScenario::merge_object

(

const char *

string

)

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!

int diguyScenario::include_object_library

(

const char *

library_name

)

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/config/diguy/object_libraries and $DIGUY/custom/config/diguy/object_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

Parameters

library_name

name of library

Returns:

0 on success, -1 on failure

int diguyScenario::uninclude_object_library

(

const char *

library_name

)

This function is the opposite of include_object_library().

Objects in the named library are made unavailable to the scenario.

Parameters

library_name

name of library

Returns:

0 on success, -1 on failure

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

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.

void diguyScenario::set_base_datetime	(	const char *	datetime_string,
		const char *	format
	)

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

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

Retrieves the base datetime.

Pass NULL for arguments that aren't needed.

void diguyScenario::set_base_datetime_default_to_now

(

int

to_now

)

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.

int diguyScenario::get_base_datetime_default_to_now

(

)

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

void diguyScenario::set_base_datetime_default_to_today

(

int

to_today

)

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

int diguyScenario::get_base_datetime_default_to_today

(

)

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

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

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.

void diguyScenario::set_current_datetime	(	const char *	datetime_string,
		const char *	format
	)

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

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

Retrieves the current datetime.

Pass NULL for arguments that aren't needed.

const char* diguyScenario::get_current_datetime_string

(

const char *

format

)

Retrieves the current datetime in string format.

Parameters

format

format returned string should be in; pass NULL for default "M/d/yyyy h:mm:ss AP" format

void diguyScenario::set_datetimes_are_utc

(

int

are_utc

)

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

int diguyScenario::get_datetimes_are_utc

(

)

Returns: 1 if datetimes use UTC time, 0 if not.

void diguyScenario::set_utc_offset_hours

(

float

utc_offset_hours

)

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

float diguyScenario::get_utc_offset_hours

(

)

Returns: offset in hours of datetimes from UTC.

void diguyScenario::set_use_local_tz_utc_offset_hours

(

int

use_local_tz

)

Causes the number of UTC offset hours to be derived from local system settings – an alternative to calling set_utc_offset_hours()

int diguyScenario::get_use_local_tz_utc_offset_hours

(

)

Returns value set in set_use_local_tz_utc_offset_hours()

void diguyScenario::set_current_datetime_advance_method

(

diguyDatetimeAdvanceMethod

advance_method

)

Sets the rate at which datetime can advance.

See diguyDatetimeAdvanceMethod for details.

diguyDatetimeAdvanceMethod diguyScenario::get_current_datetime_advance_method

(

)

Returns value set by set_current_datetime_advance_method()

void diguyScenario::set_current_datetime_advance_factor

(

float

advance_factor

)

Sets a multiplier that affects the rate at which datetime advances.

Set to less than 1 to go more slowly, greater than 1 to go faster. Only applies if datetime advance method is DIGUY_DATETIME_ADVANCE_METHOD_SIMULATION_TIME_RATE or DIGUY_DATETIME_ADVANCE_METHOD_REAL_TIME_RATE.

float diguyScenario::get_current_datetime_advance_factor

(

)

Returns value set by set_current_datetime_advance_factor()

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

Returns current exercise's datetime values.

int diguyScenario::set_tin_time_of_day

(

float

t

)

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.

Parameters

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

Returns:

0 on success, -1 on failure

float diguyScenario::get_tin_time_of_day

(

)

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

float diguyScenario::get_time_of_day

(

)

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)

int diguyScenario::add_appearance	(	const char *	appearance,
		char **	equipment_list,
		char **	character_types,
		const char *	actor
	)

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.

Parameters

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

int diguyScenario::add_appearance_based_on_existing_appearance	(	const char *	appearance,
		const char *	existing_appearance,
		char **	equipment_list
	)

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.

Parameters

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

int diguyScenario::remove_appearance

(

const char *

appearance

)

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.

Parameters

appearance

name of the appearance

Returns:

0 on success, -1 on failure

Callable From:

• C++

int diguyScenario::get_num_character_types_with_appearance

(

const char *

appearance_name

)

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

Parameters

appearance

name of the appearance

Returns:

the number of character types, or 0

const char* diguyScenario::get_character_type_from_appearance	(	const char *	appearance_name,
		int	index = 0
	)

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

Parameters

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

Returns:

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

int diguyScenario::get_num_hand_item_classes

(

)

const

Gets the number of configured hand item classes.

Returns:

The number of configured hand item classes.

const char* diguyScenario::get_hand_item_class_at_index

(

int

index

)

const

Gets the name of the hand item class at the given index.

Parameters

index

index of the hand item class to return the name of

Returns:

Name of hand item class on success, "none" on failure

int diguyScenario::get_item_class_num_character_types

(

const char *

item_class_name

)

const

Gets the number of character types a given hand item class is configured to be available to.

Parameters

item_class_name

name of the item class to get number of character types for

Returns:

Number of character types the given item class is configured to be available to.

const char* diguyScenario::get_item_class_character_type_at_index	(	const char *	item_class_name,
		int	index
	)		const

Gets the character types configured for availability with the given hand item class at the given index.

Parameters

item_class_name	name of the item class to get the available character types for
index	index of the character type for the given item class to get the name of

Returns:

The name of the character type configured for availability with the given item class at the given index.

const char* diguyScenario::get_hand_item_class	(	const char *	char_type_name,
		const char *	appearance_name = nullptr
	)

Gets the primary hand item class associated with a character type.

A given character type may support multiple hand item classes - the primary hand item class is the first one configured for the character type.

Parameters

char_type_name	name of the char type
appearance_name	optional appearance name, which might yield different results

Returns:

Name of hand item class on success, "none" on failure

int diguyScenario::get_num_hand_items_in_class

(

const char *

hand_item_class

)

Gets the number of hand items in a particular hand item class.

Parameters

hand_item_class

name of hand item class

Returns:

Number of hand items in class

const char* diguyScenario::get_hand_item_from_class	(	const char *	hand_item_class,
		int	index
	)

Gets the name of a hand item within the set associated with a hand item class.

Parameters

hand_item_class	name of hand item class
index	index within set

Returns:

Name of hand item, or "none"

int diguyScenario::preload_character_type

(

const char *

character_type

)

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.

Parameters

character_type

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

Returns:

0 on success, -1 on failure

int diguyScenario::preload_appearance

(

const char *

appearance

)

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.

Parameters

appearance

name of the appearance whose geometry is to be preloaded

Returns:

0 on success, -1 on failure

int diguyScenario::async_load_appearance	(	const char *	appearance,
		const char *	character_type = "soldier_17",
		const bool **	load_status = NULL
	)

This function asynchronously starts loading appearance data in a background thread and sends textures to the async texture loader.

Will attempt to use character type to figure out the hand appearance to load. This avoids hickups at run time if you can delay setting the appearance a few frames.

Parameters

appearance	name of the appearance, or head appearance whose geometry is to be loaded
character_type	name of the character type, used to derived hand item to load
load_status	pointer to the internal load data. monitor this to find out when the object has finished loading and avoid polling this function

Returns:

0 if successfully queued, 1 if already loaded, 2 if in the process of being loaded, -1 on failure

int diguyScenario::async_load_hand_item	(	const char *	appearance_name,
		const bool **	load_status = NULL
	)

int diguyScenario::preload_gesture	(	const char *	character_type,
		const char *	gesture_name
	)

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.

Parameters

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

Returns:

0 on success, -1 on failure

void diguyScenario::set_character_culling_enabled

(

int

character_culling

)

This function enables character culling.

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

int diguyScenario::get_character_culling_enabled

(

)

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.

void diguyScenario::set_scene_object_culling_enabled

(

int

object_culling

)

This function enables scene object culling.

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

int diguyScenario::get_scene_object_culling_enabled

(

)

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

void diguyScenario::set_scene_object_sub_culling_enabled

(

int

object_culling

)

This function enables scene object sub object culling.

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

int diguyScenario::get_scene_object_sub_culling_enabled

(

)

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

void diguyScenario::set_character_visualize_bounds_enabled

(

int

visualize_bounds

)

This function enables visualizing a character's bounding volume.

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

int diguyScenario::get_character_visualize_bounds_enabled

(

)

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

void diguyScenario::set_scene_object_visualize_bounds_enabled

(

int

val

)

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.

int diguyScenario::get_scene_object_visualize_bounds_enabled

(

)

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

int diguyScenario::get_num_character_types

(

)

Returns: number of available character types.

const char* diguyScenario::get_character_type_at_index

(

int

index

)

Returns: the string identifying the character type at the given index.

Parameters

index

index of the character type; indices start at 0

const char* diguyScenario::get_character_type_abbreviation

(

const char *

character_type

)

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

Parameters

character_type

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

const char* diguyScenario::get_character_type_deprecated_at_version

(

const char *

character_type

)

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.

Parameters

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
}

const char* diguyScenario::get_character_type_deprecated_suggested_alternatives

(

const char *

character_type

)

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.

Parameters

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
}

int diguyScenario::get_character_type_quality_bias

(

const char *

character_type

)

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

Parameters

character_type

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

diguyCharacterTypeMap* diguyScenario::get_character_type_map

(

const char *

character_type

)

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.

Parameters

character_type

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

Returns:

pointer to type diguyCharacterTypeMap; will never be NULL

const char* diguyScenario::get_character_type_default_appearance

(

const char *

character_type

)

Returns: default appearance of the specified character type.

Parameters

character_type

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

const char* diguyScenario::get_character_type_default_skinned_appearance

(

const char *

character_type

)

Returns: default skinned appearance of the specified character type.

Parameters

character_type

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

int diguyScenario::get_character_type_num_appearances

(

const char *

character_type

)

Returns: number of available appearances for the given character type.

Parameters

character_type

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

const char* diguyScenario::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.

Parameters

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

int diguyScenario::get_appearance_quality_bias

(

const char *

appearance

)

As the number of appearances DI-Guy provides has grown, newer appearances tend to be better than older ones.

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

Parameters

appearance

appearance name

int diguyScenario::get_num_appearances_of_appearance_type	(	const char *	character_type,
		const char *	base_appearance,
		diguyCharacterAppearanceTypes	appearance_type
	)

Parameters

character_type	a string indicating the character type
base_appearance	a string indicating the basic character appearance
appearance_type	a value indicating the type of supplementary appearance of concern, ie DIGUY_APPEARANCE_BODY, DIGUY_APPEARANCE_HEAD, DIGUY_APPEARANCE_EXPRESSIVE_HEAD, DIGUY_APPEARANCE_HAND_ITEM Returns:

The number of available supplementary appearances of given type

const char* diguyScenario::get_appearance_name_at_index	(	const char *	character_type,
		const char *	base_appearance,
		diguyCharacterAppearanceTypes	appearance_type,
		int	index
	)

Returns: The name of the supplementary appearance (body, head, expressive head, hand item) or NULL.

Parameters

character_type	a string indicating the character type
base_appearance	a string indicating the basic character appearance
appearance_type	a value indicating the type of appearance of concern
index	a value indicating the type of supplementary appearance of concern

int diguyScenario::get_num_patches_for_appearance	(	const char *	base_appearance,
		diguyTextureUniformPatchLocations	patch_location
	)

returns the number of texture patches for a given appearance, supports unit or rank

int diguyScenario::get_appearance_default_patch_index	(	const char *	base_appearance,
		diguyTextureUniformPatchLocations	patch_location
	)		const

returns the index of the default texture patch for the given appearance, supports unit or rank

const diguyPatchIdentifier& diguyScenario::get_appearance_default_patch_id	(	const char *	base_appearance,
		diguyTextureUniformPatchLocations	patch_location
	)		const

returns the id of the default texture patch for the given appearance, supports unit or rank

const char* diguyScenario::get_appearance_patch_name_at_index	(	const char *	base_appearance,
		diguyTextureUniformPatchLocations	patch_location,
		int	index
	)		const

returns the name of a texture patch for the given appearance, supports unit or rank

const diguyPatchIdentifier& diguyScenario::get_appearance_patch_id_at_index	(	const char *	base_appearance,
		diguyTextureUniformPatchLocations	patch_type,
		int	index
	)		const

Get the patch id for the given texture patch.

Returns the requested patch id or the null patch id (-1:-1:-1) if the patch could not be located or the id isn't set up.

int diguyScenario::get_num_actors

(

)

returns num actor typically broad skeleton type

const char* diguyScenario::get_actor_name_at_index

(

int

index

)

returns name of actor (broad skeleton type )

const char* diguyScenario::get_actor_name

(

const char *

base_appearance

)

returns actor that this appearance is based off of, typically broad skeleton type

int diguyScenario::get_num_equipment_for_actor

(

const char *

actor_name

)

returns number of equipment appearances available for this actor

const char* diguyScenario::get_equipment_name_for_actor	(	const char *	actor_name,
		int	index
	)

returns number of equipment appearances available for this actor

const char* diguyScenario::get_equipment_type_for_actor	(	const char *	actor_name,
		int	index
	)

returns class_type of equipment appearance available for this appearance, usually based on actor

int diguyScenario::get_num_equipment_for_appearance

(

const char *

base_appearance

)

returns number of equipment appearances available for this appearance, usually based on actor

const char* diguyScenario::get_equipment_name_for_appearance	(	const char *	base_appearance,
		int	index
	)

returns name of equipment appearance available for this appearance, usually based on actor

const char* diguyScenario::get_equipment_type_for_appearance	(	const char *	base_appearance,
		int	index
	)

returns class_type of equipment appearance available for this appearance, usually based on actor

int diguyScenario::get_character_type_num_actions

(

const char *

character_type

)

Returns: number of available actions for the given character type.

Parameters

character_type

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

const char* diguyScenario::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.

Parameters

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

const char* diguyScenario::get_character_type_action_display_name	(	const char *	character_type,
		const char *	action_name
	)

Returns: the display name for the specified action for the specified character type.

Parameters

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

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

Parameters

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

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

Parameters

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

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

Parameters

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

int diguyScenario::get_character_type_action_displacement	(	const char *	character_type,
		const char *	action_name,
		float *	x,
		float *	y,
		float *	z
	)

Returns: the displacement covered by one rep of the specified action for the specified character type.

Parameters

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

bool diguyScenario::get_character_type_transition_info	(	const char *	character_type,
		const char *	from_action_name,
		const char *	to_action_name,
		diguyTransitionInfo &	info
	)

Looks up the transition used between the given two actions, and returns information about the transition.

Parameters

character_type	character type name, as returned by get_character_type_at_index(), for example
from_action_name	the starting action to get transition info for
to_action_name	the ending action to get transition info for.

Returns:

true on success, false on failure

diguyMotionDirection diguyScenario::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.

Parameters

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

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

Parameters

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

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

Parameters

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

int diguyScenario::get_character_type_num_gestures

(

const char *

character_type

)

Returns: the number of gestures available to the specified character type.

Parameters

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

const char* diguyScenario::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.

Parameters

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

diguyGestureMetadata* diguyScenario::get_character_type_gesture_meta_data_at_index	(	const char *	character_type,
		int	index
	)

Returns: the metadata of the gesture available to the specified character type at the specified index see get_character_type_gesture_at_index() for args.

diguyCharacter* diguyScenario::create_character	(	const char *	name,
		const char *	character_type,
		const char *	appearance = NULL,
		const char *	head_appearance = NULL,
		const char *	hand_item = NULL
	)

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.

Parameters

name	name of the new character
character_type	character's type
appearance	base appearance of character; pass NULL to use default appearance
hand_item	hand item appearance; pass NULL to use default appearance

Returns:

pointer of type diguyCharacter; NULL if creation failed

diguyCharacter* diguyScenario::create_temporary_character	(	const char *	name,
		const char *	character_type,
		const char *	appearance = NULL
	)

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

Parameters

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

int diguyScenario::destroy_character

(

diguyCharacter *

character

)

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

Parameters

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.

int diguyScenario::destroy_character_later

(

diguyCharacter *

)

int diguyScenario::send_character_to_recycle_bin

(

diguyCharacter *

character

)

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

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

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.

Parameters

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

int diguyScenario::get_num_characters

(

)

Returns: number of characters in the scenario.

diguyCharacter* diguyScenario::get_character_at_index

(

int

index

)

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

Parameters

index

index of the character; indices start at 0

diguyCharacter* diguyScenario::find_character

(

const char *

name

)

This function returns a pointer to the specified character.

Parameters

name	name of character to be found

Returns:

pointer of type diguyCharacter; NULL if not found

void diguyScenario::look_at_character

(

diguyCharacter *

character

)

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

diguyCharacter* diguyScenario::this_character

(

)

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

Returns:

pointer of type diguyCharacter; NULL if no current character

diguyCharacterPathEvent* diguyScenario::this_event_bead

(

)

This function returns a pointer to the current event bead.

Returns:

pointer of type diguyCharacterPathEvent; NULL if no current event bead

int diguyScenario::get_num_path_shapes

(

)

Returns: number of path shapes in the scenario.

diguyPathShape* diguyScenario::get_path_shape_at_index

(

int

index

)

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

Parameters

index

index of the path shape; indices start at 0

diguyPathShape* diguyScenario::get_current_path_shape

(

)

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

diguyPathShape* diguyScenario::find_path_shape

(

const char *

name

)

This function returns a pointer to the specified path shape.

Parameters

name	name of path shape to be found

Returns:

pointer of type diguyPathShape; NULL if not found

diguyPathShape* diguyScenario::create_path_shape

(

const char *

name

)

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

Parameters

name	name of the new path shape

Returns:

pointer of type diguyPathShape; NULL if creation failed

diguyPathShape* diguyScenario::copy_path_shape	(	diguyPathShape *	existing_path_shape,
		const char *	name
	)

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

Parameters

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

int diguyScenario::destroy_path_shape

(

diguyPathShape *

path_shape

)

This function destroys a path shape.

Parameters

path_shape

pointer to a diguyPathShape

Returns:

0 on success, -1 on failure

diguyWaypoint* diguyScenario::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
	)

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

Parameters

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

int diguyScenario::destroy_waypoint

(

diguyWaypoint *

waypoint

)

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

Parameters

waypoint

waypoint to destroy

Returns:

0 on success, -1 on failure

diguyCharacterTypeMap* diguyScenario::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
	)

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.

Parameters

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

diguyCharacterTypeMap* diguyScenario::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
	)

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

int diguyScenario::get_num_matching_type_maps	(	const diguyCharacterTypeMapFieldValues *	field_values,
		const char *	character_type = NULL,
		const diguyCharacterTypeMapFieldValues *	alternate_values = NULL
	)

Get the number of type maps matching the given fields and (optional) character type.

The type maps in the list can then be referenced using get_matching_type_map_at_index(int). Once get_num_matching_type_maps is called again, the new filter will be applied, changing the number of type maps and their indices.

diguyCharacterTypeMap* diguyScenario::get_matching_type_map_at_index

(

int

index

)

Get the type map at the given index in the array of matches.

Note that this index is only valid until the next call to get_num_matching_type_maps, at which point the array of type maps is changed.

diguyCharacterTypeMap* diguyScenario::get_nearest_character_type_map_id_match

(

const char *

type_map_id

)

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.

int diguyScenario::get_num_character_type_map_entries

(

)

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

diguyCharacterTypeMap* diguyScenario::get_character_type_map_entry_at_index

(

int

index

)

Returns: type map entry at specified index; see get_num_character_type_map_entries()

int diguyScenario::get_num_type_map_character_classes

(

)

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

const char* diguyScenario::get_type_map_character_class_at_index

(

int

index

)

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

int diguyScenario::get_num_type_map_categories

(

const char *

character_class

)

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

const char* diguyScenario::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()

int diguyScenario::get_num_type_map_subcategories	(	const char *	character_class,
		const char *	category
	)

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

const char* diguyScenario::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()

int diguyScenario::get_num_signals

(

)

Returns: number of signals in the scenario.

diguySignal* diguyScenario::get_signal_at_index

(

int

index

)

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

Parameters

index

index of the signal; indices start at 0

diguySignal* diguyScenario::find_signal

(

const char *

name

)

This function returns a pointer to the specified signal.

Parameters

name	name of signal to be found

Returns:

pointer of type diguySignal; NULL if not found

diguySignal* diguyScenario::create_signal

(

const char *

name

)

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

Parameters

name	name of the new signal

Returns:

pointer of type diguySignal

int diguyScenario::destroy_signal

(

diguySignal *

signal

)

This function destroys a signal.

Parameters

signal

pointer to a diguySignal

Returns:

0 on success, -1 on failure

void diguyScenario::reset_signals

(

)

This function resets all signals in the scenario.

int diguyScenario::signal_palette_hide_all

(

const char *

filter = NULL

)

This function hides all signals in the signal palette.

Parameters

filter

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

int diguyScenario::signal_palette_show_all

(

const char *

filter = NULL

)

This function shows all signals in the signal palette.

Parameters

filter

optional filter, will only show signals tagged with info_text filter

int diguyScenario::get_num_sounds

(

)

Returns: number of sounds in the scenario.

diguySound* diguyScenario::get_sound_at_index

(

int

index

)

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

Parameters

index

index of the sound; indices start at 0

diguySound* diguyScenario::find_sound

(

const char *

name

)

This function returns a pointer to the specified sound.

Parameters

name	name of sound to be found

Returns:

pointer of type diguySound; NULL if not found

diguySound* diguyScenario::create_sound	(	const char *	name,
		const char *	sound_filename = NULL
	)

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

Parameters

name	name of the new sound
sound_filename	filename of the sound

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

int diguyScenario::destroy_sound

(

diguySound *

sound

)

This function destroys a sound.

Parameters

sound

pointer to diguySound to be destroyed

Returns:

0 on success, -1 on failure

int diguyScenario::preload_sound

(

diguySound *

sound

)

This function preloads data for the sound.

Parameters

sound

pointer to diguySound

Returns:

0 on success, -1 on failure

int diguyScenario::stop_all_sounds

(

float

rampdown_time = 0.0f

)

This function stops all sounds playing within the scenario.

Parameters

rampdown_time

how long to allow the sounds to fade out

Returns:

0 on success, -1 on failure

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

This function plays a non looping sound.

Parameters

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

int diguyScenario::get_num_groups

(

)

Returns: number of groups in the scenario.

diguyCharacterGroup* diguyScenario::get_group_at_index

(

int

index

)

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

Parameters

index

index of the group; indices start at 0

diguyCharacterGroup* diguyScenario::find_group

(

const char *

name

)

This function returns a pointer to the specified group.

Parameters

name	name of group to be found

Returns:

pointer of type diguyCharacterGroup; NULL if not found

diguyCharacterGroup* diguyScenario::create_group

(

const char *

name

)

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

Parameters

name	name of the new group

Returns:

pointer of type diguyCharacterGroup

diguyCharacterGroup* diguyScenario::find_or_create_group

(

const char *

name

)

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

Parameters

name	name of the group to find or create

Returns:

pointer of type diguyGroup; should never be NULL

int diguyScenario::destroy_group

(

diguyCharacterGroup *

group

)

This function destroys a group.

Parameters

group

pointer to a diguyCharacterGroup

Returns:

0 on success, -1 on failure

int diguyScenario::get_num_sensor_regions

(

)

Returns the number of sensor regions in the scenario.

diguySensorRegion* diguyScenario::get_sensor_region_at_index

(

int

index

)

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

Parameters

index

index of the sensor region; indices start at 0

diguySensorRegion* diguyScenario::find_sensor_region

(

const char *

name

)

Returns a pointer to the specified sensor region, NULL if not found.

diguySensorRegion* diguyScenario::find_or_create_sensor_region

(

const char *

name

)

finds or creates a sensor region with specified name

int diguyScenario::get_num_scene_objects

(

)

Returns: number of scene objects in the scenario.

diguySceneObject* diguyScenario::get_scene_object_at_index

(

int

index

)

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

Parameters

index

index of the scene object; indices start at 0

diguySceneObject* diguyScenario::find_scene_object

(

const char *

name

)

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

void diguyScenario::set_scene_objects_enabled

(

int

scene_objects_enabled

)

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

Scene objects are not enabled by default.

Parameters

scene_objects_enabled

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

int diguyScenario::get_scene_objects_enabled

(

)

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

diguySceneObject* diguyScenario::create_scene_object	(	const char *	name,
		const char *	filename
	)

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

Parameters

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

Returns:

pointer of type diguySceneObject; NULL if creation failed

diguySceneObject* diguyScenario::create_user_defined_scene_object

(

const char *

name

)

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

Parameters

name	name of the new scene object

Returns:

pointer of type diguySceneObject; NULL if creation failed

int diguyScenario::destroy_scene_object

(

diguySceneObject *

scene_object

)

This function destroys a scene object.

Parameters

scene_object

pointer to a diguySceneObject

Returns:

0 on success, -1 on failure

diguyView* diguyScenario::get_primary_view

(

)

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

bool diguyScenario::create_new_secondary_view

(

)

Creates a new secondary view for the scenario.

Returns:

true on success, false on failure

int diguyScenario::get_num_secondary_views

(

)

Returns: number of secondary views in the scenario.

diguyView* diguyScenario::get_secondary_view_at_index

(

int

index

)

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

Parameters

index

index of the secondary view; indices start at 0

diguyView* diguyScenario::find_view

(

const char *

name

)

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

diguyViewCamera* diguyScenario::get_scenario_camera

(

)

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

diguyViewCamera* diguyScenario::find_camera

(

const char *

name

)

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

void diguyScenario::set_scenario_camera_affected_by_script_events

(

int

flag

)

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.

Parameters

flag	1 to enable, 0 to disable

int diguyScenario::get_scenario_camera_affected_by_script_events

(

)

Returns: the most recent setting made by set_scenario_camera_affected_by_script_events()

void diguyScenario::set_scenario_camera_affected_by_script_events_when_iguy_active

(

int

flag

)

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.

Parameters

flag	1 to enable, 0 to disable

int diguyScenario::get_scenario_camera_affected_by_script_events_when_iguy_active

(

)

Returns: the most recent setting made by set_scenario_camera_affected_by_script_events()

int diguyScenario::get_num_camera_settings

(

)

Returns: number of camera settings saved in the scenario.

diguyViewCameraSettings* diguyScenario::get_camera_settings_at_index

(

int

index

)

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

Parameters

index

index of the camera settings; indices start at 0

diguyViewCameraSettings* diguyScenario::find_camera_settings

(

const char *

settings_name

)

This function returns a pointer to the specified camera settings.

Parameters

settings_name

name of camera settings to be found

Returns:

pointer of type diguyViewCamera; NULL if not found

int diguyScenario::load_camera_settings	(	const char *	settings_name,
		int	update_current_camera = 1
	)

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

Parameters

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

void diguyScenario::set_render_camera

(

diguyViewCamera *

camera

)

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.

Parameters

camera

camera to use for camera-related operations

diguyViewCamera* diguyScenario::get_render_camera

(

)

diguyViewFog* diguyScenario::get_scenario_fog

(

)

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

diguyViewFog* diguyScenario::find_fog

(

const char *

name

)

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

diguyViewFog* diguyScenario::find_or_create_fog

(

const char *

name

)

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

Returns:

pointer of type diguyViewFog

name

void diguyScenario::load_current_fog

(

const char *

name

)

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

name

int diguyScenario::get_num_fog_settings

(

)

Returns: number of fog settings in the scenario.

diguyViewFogSettings* diguyScenario::get_fog_settings_at_index

(

int

index

)

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

Parameters

index

index of the fog settings; indices start at 0

diguyViewFogSettings* diguyScenario::find_fog_settings

(

const char *

settings_name

)

This function returns a pointer to the specified fog settings.

Parameters

settings_name

name of fog settings to be found

Returns:

pointer of type diguyViewFogSettings; NULL if not found

int diguyScenario::load_fog_settings

(

const char *

settings_name

)

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

Parameters

settings_name

name of fog settings to be loaded

Returns:

pointer of type diguyViewFog; NULL if not found

diguyViewLight* diguyScenario::get_scenario_light

(

int

i = 0

)

This function returns a pointer to the scenario light.

These are the lights of the primary view.

Parameters

number

number of light to be found

Returns:

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

diguyViewLight* diguyScenario::find_light

(

const char *

name

)

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

int diguyScenario::get_num_light_settings

(

)

Returns: number of light settings in the scenario.

diguyViewLightSettings* diguyScenario::get_light_settings_at_index

(

int

index

)

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

Parameters

index

index of the light settings; indices start at 0

diguyViewLightSettings* diguyScenario::find_light_settings

(

const char *

settings_name

)

This function returns a pointer to the specified light settings.

Parameters

name	name of light settings to be found

Returns:

pointer of type diguyViewLightSettings; NULL if not found

int diguyScenario::load_light_settings	(	const char *	settings_name,
		int	light_num = 0
	)

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

Parameters

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

void diguyScenario::set_use_override_ambient_material

(

int

enabled

)

DI-Guy content has come from many sources over the years.

The ambient material has had many different defaults depending on the authoring tools. Often the scene's ambient ambient material should depend on the time of day/environment. This flag allows you to control a override value that will replace the value in all materials. See diguyOglUniformBufferUpdater::set_material() for how it is implemented

int diguyScenario::get_use_override_ambient_material

(

)

Should this scenario override the ambient values on all materials.

void diguyScenario::set_global_ambient_material

(

float

value

)

The value used to replace the ambient material's (expands to rgb)

float diguyScenario::get_global_ambient_material

(

)

Returns the value used to replace the ambient material's (expands to rgb)

int diguyScenario::get_num_info_popups

(

)

Returns: number of info popups in the scenario.

diguyInfoPopup* diguyScenario::get_info_popup_at_index

(

int

index

)

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

Parameters

index

index of the info popup; indices start at 0

diguyInfoPopup* diguyScenario::find_info_popup

(

const char *

name

)

This function returns a pointer to the specified info popup.

Parameters

name	name of info popup to be found

Returns:

pointer of type diguyInfoPopup; NULL if not found

int diguyScenario::set_info_popup_default_encoding

(

const char *

info_popup_default_encoding

)

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

Parameters

info_popup_default_encoding

new default encoding

Returns:

0 on success, -1 on failure

const char* diguyScenario::get_info_popup_default_encoding

(

)

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

int diguyScenario::get_num_variables

(

)

Returns: number of variables in the scenario.

diguyVariable* diguyScenario::get_variable_at_index

(

int

index

)

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

Parameters

index

index of the variable; indices start at 0

diguyVariable* diguyScenario::find_variable

(

const char *

name

)

This function returns a pointer to the specified variable.

Parameters

name	name of variable to be found

Returns:

pointer of type diguyVariable; NULL if not found

diguyVariable* diguyScenario::find_or_create_variable

(

const char *

name

)

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

Parameters

name	name of the variable to find or create

Returns:

pointer of type diguyVariable; should never be NULL

int diguyScenario::destroy_variable

(

diguyVariable *

variable

)

This function destroys the passed variable.

Parameters

variable

pointer to a diguyVariable

Returns:

0 on success, -1 on failure

int diguyScenario::get_num_face_expressions

(

)

Returns: number of face_expressions in the scenario.

diguyCharacterFaceExpression* diguyScenario::get_face_expression_at_index

(

int

index

)

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

Parameters

index

index of the face_expression; indices start at 0

diguyCharacterFaceExpression* diguyScenario::find_face_expression

(

const char *

name

)

This function returns a pointer to the specified face expression.

Parameters

name	name of face_expression to be found

Returns:

pointer of type diguyCharacterFaceExpression; NULL if not found

diguyCharacterFaceExpression* diguyScenario::create_face_expression	(	const char *	name,
		const char *	target_actor = "exface"
	)

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

Parameters

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

int diguyScenario::destroy_face_expression

(

diguyCharacterFaceExpression *

face_expression

)

This function destroys the passed face expression.

Parameters

face_expression

pointer to a diguyCharacterFaceExpression

Returns:

0 on success, -1 on failure

int diguyScenario::get_num_chain_settings

(

)

Returns: number of chain settings in the scenario.

diguyChainSettings* diguyScenario::get_chain_settings_at_index

(

int

index

)

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

Parameters

index

index of the chain settings; indices start at 0

diguyChainSettings* diguyScenario::find_chain_settings

(

const char *

name

)

This function returns a pointer to the specified chain settings.

Parameters

name	name of chain settings to be found

Returns:

pointer of type diguyChainSettings; NULL if not found

diguyChainSettings* diguyScenario::create_chain_settings

(

const char *

name

)

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

Parameters

name	name of the new chain settings

Returns:

pointer of type diguyChainSettings

int diguyScenario::destroy_chain_settings

(

diguyChainSettings *

chain_settings

)

This function destroys a chain settings.

Parameters

chain

settings pointer to a diguyChainSettings

Returns:

0 on success, -1 on failure

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

This function adds a scenario callback.

Parameters

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

int diguyScenario::remove_callback	(	int	callback_id,
		diguyScenarioCallback *	callback
	)

This function removes a user callback.

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

Parameters

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

Returns:

0 on success, -1 on failure

Callable From:

• C++

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

This function removes a user callback.

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

Parameters

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

Returns:

0 on success, -1 on failure

Callable From:

• C++

int diguyScenario::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
	)

This function sets a default user callback that will be added to all new characters.

See diguyCharacter::add_callback() for details.

Callable From:

• C++

int diguyScenario::remove_default_character_callback	(	int	callback_id,
		diguyCharacterCallback *	callback
	)

This function removes a user callback.

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

Parameters

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

Callable From:

• C++

int diguyScenario::remove_default_character_callback_with_user_data	(	int	callback_id,
		void *	callback_user_data
	)

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

int diguyScenario::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
	)

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

int diguyScenario::remove_default_sensor_region_callback	(	int	callback_id,
		diguySensorRegionCallback *	callback
	)

This function removes a user callback.

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

Parameters

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

Callable From:

• C++

int diguyScenario::remove_default_sensor_region_callback_with_user_data	(	int	callback_id,
		void *	callback_user_data
	)

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.

Parameters

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

Callable From:

• C++

int diguyScenario::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
	)

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

Callable From:

• C++

int diguyScenario::remove_default_signal_callback	(	int	callback_id,
		diguySignalCallback *	callback
	)

This function removes a user callback.

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

Parameters

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

Callable From:

• C++

int diguyScenario::remove_default_signal_callback_with_user_data	(	int	callback_id,
		void *	callback_user_data
	)

This function removes a default user callback.

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

Parameters

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

Callable From:

• C++

int diguyScenario::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
	)

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

Callable From:

• C++

int diguyScenario::remove_default_variable_callback	(	int	callback_id,
		diguyVariableCallback *	callback
	)

This function removes a user callback.

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

Parameters

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

Callable From:

• C++

int diguyScenario::remove_default_variable_callback_with_user_data	(	int	callback_id,
		void *	callback_user_data
	)

This function removes a default user callback.

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

Parameters

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

Callable From:

• C++

int diguyScenario::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
	)

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

int diguyScenario::remove_default_view_callback	(	int	callback_id,
		diguyViewCallback *	callback
	)

This function removes a user callback.

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

Parameters

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

Callable From:

• C++

int diguyScenario::remove_default_view_callback_with_user_data	(	int	callback_id,
		void *	callback_user_data
	)

This function removes a default user callback.

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

Parameters

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

Callable From:

• C++

int diguyScenario::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
	)

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

Callable From:

• C++

int diguyScenario::remove_default_camera_callback	(	int	callback_id,
		diguyViewCameraCallback *	callback
	)

This function removes a user callback.

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

Parameters

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

Callable From:

• C++

int diguyScenario::remove_default_camera_callback_with_user_data	(	int	callback_id,
		void *	callback_user_data
	)

This function removes a default user callback.

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

Parameters

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

Callable From:

• C++

int diguyScenario::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
	)

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

Callable From:

• C++

int diguyScenario::remove_default_fog_callback	(	int	callback_id,
		diguyViewFogCallback *	callback
	)

This function removes a user callback.

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

Parameters

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

Callable From:

• C++

int diguyScenario::remove_default_fog_callback_with_user_data	(	int	callback_id,
		void *	callback_user_data
	)

This function removes a default user callback.

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

Parameters

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

Callable From:

• C++

int diguyScenario::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
	)

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

Callable From:

• C++

int diguyScenario::remove_default_light_callback	(	int	callback_id,
		diguyViewLightCallback *	callback
	)

This function removes a user callback.

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

Parameters

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

Callable From:

• C++

int diguyScenario::remove_default_light_callback_with_user_data	(	int	callback_id,
		void *	callback_user_data
	)

This function removes a default user callback.

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

Parameters

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

Callable From:

• C++

void diguyScenario::manually_invoke_callbacks_now

(

int

callback_id

)

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

Parameters

callback_id

integer id of callback

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

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.

Parameters

callback_id	integer id of the callback
callback_script	Script text of callback to be added
callback_script_type	the type of script contained in callback_script
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

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

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

See diguyCharacter::remove_callback_script() for an example of use.

Parameters

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

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

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

Lua specific:

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

Returns:

0 on success, -1 on failure

int diguyScenario::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
	)

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

int diguyScenario::remove_default_character_callback_script	(	int	callback_id,
		const char *	callback_script,
		const char *	callback_script_type = NULL
	)

This function removes a default character callback script.

See diguyCharacter::remove_callback_script() for more details.

Returns:

0 on success, -1 on failure

int diguyScenario::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
	)

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

int diguyScenario::remove_default_sensor_region_callback_script	(	int	callback_id,
		const char *	callback_script,
		const char *	callback_script_type = NULL
	)

This function removes a default sensor region callback script.

See diguySensorRegion::remove_callback_script() for more details.

Returns:

0 on success, -1 on failure

int diguyScenario::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
	)

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

int diguyScenario::remove_default_signal_callback_script	(	int	callback_id,
		const char *	callback_script,
		const char *	callback_script_type = NULL
	)

This function removes a default signal callback script.

See diguySignal::remove_callback_script() for more details.

Returns:

0 on success, -1 on failure

int diguyScenario::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
	)

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

int diguyScenario::remove_default_variable_callback_script	(	int	callback_id,
		const char *	callback_script,
		const char *	callback_script_type = NULL
	)

This function removes a default variable callback script.

See diguySignal::remove_callback_script() for more details.

Returns:

0 on success, -1 on failure

int diguyScenario::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
	)

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

int diguyScenario::remove_default_view_callback_script	(	int	callback_id,
		const char *	callback_script,
		const char *	callback_script_type = NULL
	)

This function removes a default character view script.

See diguyView::remove_callback_script() for more details.

Returns:

0 on success, -1 on failure

int diguyScenario::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
	)

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

int diguyScenario::remove_default_camera_callback_script	(	int	callback_id,
		const char *	callback_script,
		const char *	callback_script_type = NULL
	)

This function removes a default camera callback script.

See diguyViewCamera::remove_callback_script() for more details.

Returns:

0 on success, -1 on failure

int diguyScenario::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
	)

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

int diguyScenario::remove_default_fog_callback_script	(	int	callback_id,
		const char *	callback_script,
		const char *	callback_script_type = NULL
	)

This function removes a default fog callback script.

See diguyViewFog::remove_callback_script() for more details.

Returns:

0 on success, -1 on failure

int diguyScenario::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
	)

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

int diguyScenario::remove_default_light_callback_script	(	int	callback_id,
		const char *	callback_script,
		const char *	callback_script_type = NULL
	)

This function removes a default light callback script.

See diguyViewLight::remove_callback_script() for more details.

Returns:

0 on success, -1 on failure

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

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

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

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

The event handler is one of the following:

• a 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"

Parameters

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

Returns:

0 on success, -1 on failure

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

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

Parameters

callback_id	integer id of callback
handler_name	name of the event handler to 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

diguyCallbackReturn diguyScenario::manually_invoke_event_handler

(

const char *

handler_name

)

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"

Parameters

handler_name

name of the event handler to invoke

Returns:

DIGUY_CALLBACK_CONTINUE or DIGUY_CALLBACK_STOP

Callable From:

• C++
• Script
• Decision

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

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.

Parameters

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

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

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.

Parameters

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

int diguyScenario::register_character_event_handler_script	(	const char *	handler_name,
		const char *	handler_script,
		const char *	handler_script_type = 0
	)

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.

Parameters

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

int diguyScenario::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.

Parameters

handler_name

name of the event handler

int diguyScenario::unregister_character_event_handler

(

const char *

handler_name

)

This function unregisters a character event handler.

This will unmap the event handler from any mappings it is a part of.

Parameters

handler_name

name of the event handler

Returns:

0 on success, -1 on failure

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

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

Callable From:

• C++

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

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

int diguyScenario::register_signal_event_handler_script	(	const char *	handler_name,
		const char *	handler_script,
		const char *	handler_script_type = 0
	)

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

int diguyScenario::has_registered_signal_event_handler

(

const char *

handler_name

)

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

int diguyScenario::unregister_signal_event_handler

(

const char *

handler_name

)

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

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

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

Callable From:

• C++

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

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

int diguyScenario::register_sensor_region_event_handler_script	(	const char *	handler_name,
		const char *	handler_script,
		const char *	handler_script_type = 0
	)

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

int diguyScenario::has_registered_sensor_region_event_handler

(

const char *

handler_name

)

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

int diguyScenario::unregister_sensor_region_event_handler

(

const char *

handler_name

)

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

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

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

Callable From:

• C++

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

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

int diguyScenario::register_variable_event_handler_script	(	const char *	handler_name,
		const char *	handler_script,
		const char *	handler_script_type = 0
	)

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

int diguyScenario::has_registered_variable_event_handler

(

const char *

handler_name

)

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

int diguyScenario::unregister_variable_event_handler

(

const char *

handler_name

)

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

int diguyScenario::save_review_data

(

const char *

filename

)

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.

Parameters

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

int diguyScenario::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)

int diguyScenario::set_history_type

(

diguyHistoryType

history_type

)

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.

Parameters

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

diguyHistoryType diguyScenario::get_history_type

(

)

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

void diguyScenario::set_overall_history_type

(

diguyHistoryType

overall_history_type

)

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

Parameters

history_type

history type to be used for the scenario and all characters

diguyHistoryType diguyScenario::get_overall_history_type

(

)

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

int diguyScenario::get_replaying_history

(

)

Returns: whether the scenario is playing back stored history.

void diguyScenario::set_history_max_sound_instances

(

int

num_sound_instances

)

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.

Parameters

num_sound_instances

override system default of 100

Returns:

none

void diguyScenario::set_automatic_graphics_lod_switching

(

int

enable_graphics_lod_switching

)

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

By default it is enabled.

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.

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.

int diguyScenario::get_automatic_graphics_lod_switching

(

)

Returns: most recent setting of set_automatic_graphics_lod_switching()

int diguyScenario::set_character_culling_distance

(

float

dist

)

Sets the maximum distance a character should draw from the camera.

Defaults to -1 or no max distance.

float diguyScenario::get_character_culling_distance

(

)

Returns the maximum distance a character should draw from the camera.

void diguyScenario::set_cull_bounds_scale_factor

(

float

size

)

Sets a scale factor to use on the bounding sphere when determining if the character should draw.

this is useful when using shadow maps to so that main pass cull results can be reused. 2/3x will get most off screen folks.

float diguyScenario::get_cull_bounds_scale_factor

(

)

gets a scale factor to use on the bounding sphere when determining if the character should draw.

int diguyScenario::set_vehicle_culling_distance

(

float

dist

)

Sets the maximum distance a vehicle should draw from the camera.

Defaults to -1 or no max distance.

float diguyScenario::get_vehicle_culling_distance

(

)

Returns the maximum distance a vehicle should draw from the camera.

int diguyScenario::set_prop_culling_distance

(

float

dist

)

Sets the maximum distance a prop should draw from the camera.

Defaults to -1 or no max distance.

float diguyScenario::get_prop_culling_distance

(

)

Returns the maximum distance a prop should draw from the camera.

void diguyScenario::set_instancing_enabled

(

int

val

)

Turns on instancing system.

This can yield much faster rendering, but can make rendering pipeline much more complex. This value is initially set by use_shader_instancing in the diguy graphics init structure.

int diguyScenario::get_instancing_enabled

(

)

const

Returns: if the instancing system is enabled.

void diguyScenario::set_instancing_min_lod

(

int

val

)

Sets the minimum LOD that the instancing system turns on this defaults to LOD 4.

int diguyScenario::get_instancing_min_lod

(

)

const

Returns: the minimum LOD that instancing activates.

void diguyScenario::set_visualize_instance_groups

(

int

val

)

Sets visualization for instancing groups.

int diguyScenario::get_visualize_instance_groups

(

)

const

Returns: the minimum LOD that instancing activates.

void diguyScenario::set_instancing_tbo_patching_enabled

(

int

enable_patching

)

For scene graph renderers, it can be necessary to patch the texture buffer object after the scene graph finishes updating various post processes (ground clamping for instance), or modifying the TBO with a local space camera.

This function lets DI-Guy knows to keep track of TBO shape index data, and not fill out the positions in the TBO data.

This function allows the end user to set the matrix in the TBO for each shape the character has. It requires diguyCharacter::set_final_tbo_position_matrix() is called after build_instance_groups() and before update_instancing_data()

int diguyScenario::get_instancing_tbo_patching_enabled

(

)

const

void diguyScenario::set_instancing_position_callback_enabled

(

int

use_user_position_matrices

)

trigger a callback on links fill out the transform data that belongs in the texture buffer object This will call diguyGraphicsLink::fill_out_tbo_position_matrix() for every instanced shape in the character.

int diguyScenario::get_instancing_position_callback_enabled

(

)

const

void diguyScenario::set_num_extra_per_instance_data_floats

(

int

number

)

Allows the end user to set extra per instance data that will go to the video card and can be sampled.

setting this to a number greater then 0 will trigger diguyGraphicsLink::fill_out_tbo_additional_data to be called on a per shape basis

needs to be a multiple of 4

int diguyScenario::get_num_extra_per_instance_data_floats

(

)

const

void diguyScenario::build_instance_groups

(

)

Creates instancing groups, automatically done in diguyScenario::draw() for immediate mode renderers.

void diguyScenario::update_instancing_data

(

)

Updates instancing data and sends to the video card.

Automatically done in diguyScenario::draw() for immediate mode renderers

void diguyScenario::get_tbo_instance_data	(	int &	num_floats,
		const float *&	data
	)

gets the instancing data and allows you to send it to the video card.

void diguyScenario::set_default_lod_ranges	(	const char *	character_type,
		float *	ranges
	)

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.

Parameters

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

void diguyScenario::set_scale_graphics_lod_ranges_from_view_settings

(

int

do_scale

)

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.

do_scale - pass 1 to enable scaling, 0 to disable

int diguyScenario::get_scale_graphics_lod_ranges_from_view_settings

(

)

Returns: most recent setting of set_scale_graphics_lod_ranges_from_view_settings()

void diguyScenario::set_automatic_motion_lod_switching

(

int

enable_motion_lod_switching

)

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.

int diguyScenario::get_automatic_motion_lod_switching

(

)

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

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

This function sends the passed string through the script interpreter.

Parameters

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

int diguyScenario::eval_script_file	(	const char *	filename,
		const char *	script_type = NULL
	)

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

Parameters

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

int diguyScenario::trigger_script

(

const char *

script_name

)

This function manually triggers a script.

Parameters

script_name

name of the script to be triggered

Returns:

return result of script; 0 if script not found

Callable From:

• C++
• Script
• Decision

void diguyScenario::trigger_script_delayed	(	const char *	script_name,
		float	t_delay
	)

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

Parameters

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

Callable From:

• C++
• Script
• Decision

int diguyScenario::trigger_decision

(

const char *

decision_name

)

This function manually triggers a decision.

Parameters

decision_name

name of the decision to be triggered

Returns:

return result of decision; 0 if decision not found

Callable From:

• C++
• Script
• Decision

void diguyScenario::trigger_decision_delayed	(	const char *	decision_name,
		float	t_delay
	)

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

Parameters

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

Callable From:

• C++
• Script
• Decision

void diguyScenario::push_transient_script_event	(	float	t,
		const char *	script_text,
		const char *	script_type
	)

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.

Parameters

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

void diguyScenario::clear_transient_script_events

(

)

This function deletes all transient script events.

int diguyScenario::save_transient_script_events

(

const char *

filename

)

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.

Parameters

filename

file in which transient script events should be saved

Returns:

0 on success, -1 on failure

int diguyScenario::load_transient_script_events

(

const char *

filename

)

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

Parameters

filename

file from which transient script events should be loaded

Returns:

0 on success, -1 on failure

int diguyScenario::load_package	(	const char *	filename,
		const char *	language = NULL,
		int	warn_if_not_found = 1
	)

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.

int diguyScenario::load_package_with_dependency	(	const char *	filename,
		const char *	depends_on_package,
		const char *	language = NULL,
		int	warn_if_not_found = 1
	)

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. Dependency package will also be loaded.

int diguyScenario::get_character_type_num_postures

(

const char *

character_type

)

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.

Parameters

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

diguyMotionPosture diguyScenario::get_character_type_posture_at_index	(	const char *	character_type,
		int	index
	)

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.

Parameters

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

diguyMotionPosture diguyScenario::get_character_type_action_posture	(	const char *	character_type,
		const char *	action_name
	)

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.

Parameters

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

int diguyScenario::get_character_type_num_variants

(

const char *

character_type

)

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.

Parameters

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

diguyMotionVariant diguyScenario::get_character_type_variant_at_index	(	const char *	character_type,
		int	index
	)

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.

Parameters

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

diguyMotionVariant diguyScenario::get_character_type_action_primary_variant	(	const char *	character_type,
		const char *	action_name
	)

This function returns the primary variant of the specified action.

Parameters

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

int diguyScenario::get_character_type_action_num_variants	(	const char *	character_type,
		const char *	action_name
	)

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.

Parameters

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

diguyMotionVariant diguyScenario::get_character_type_action_variant_at_index	(	const char *	character_type,
		const char *	action_name,
		int	index
	)

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.

Parameters

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

Returns:

the variant at the specified index

int diguyScenario::get_character_type_num_action_compatibility_names	(	const char *	character_type,
		const char *	action_name
	)

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

Use this function along with get_character_type_action_compatibility_name_at_index() to enumerate the character's compatible action names.

Parameters

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 compatible action names for the specified action of the specified character type

const char* diguyScenario::get_character_type_action_compatibility_name_at_index	(	const char *	character_type,
		const char *	action_name,
		int	index
	)

This function returns the action compatibility name at the specified index.

Use this function along with get_character_type_num_action_compatibility_names() to enumerate the character's compatible action names.

Parameters

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

Returns:

the action compatibility name at the specified index

int diguyScenario::get_character_type_num_directions

(

const char *

character_type

)

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.

Parameters

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

diguyMotionDirection diguyScenario::get_character_type_direction_at_index	(	const char *	character_type,
		int	index
	)

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.

Parameters

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

int diguyScenario::get_num_interaction_machines

(

)

Returns: number of interaction machines in the scenario.

diguyInteractionMachine* diguyScenario::create_interaction_machine

(

const char *

name

)

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.

Parameters

name	name of the new interaction machine

Returns:

pointer of type diguyInteractionMachine; NULL if creation failed

void diguyScenario::destroy_interaction_machine

(

diguyInteractionMachine *

interaction_machine

)

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

Parameters

interaction_machine

pointer to a diguyInteractionMachine to be destroyed

diguyInteractionMachine* diguyScenario::get_interaction_machine_at_index

(

int

index

)

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

Parameters

index

index of the interaction machine; indices start at 0

diguyInteractionMachine* diguyScenario::find_interaction_machine

(

const char *

name

)

This function returns a pointer to the specified interaction machine.

Parameters

name	name of interaction machine to be found

Returns:

pointer of type diguyInteractionMachine; NULL if not found

diguyInteractionMachine* diguyScenario::get_active_interaction_machine

(

)

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.

diguyInteractionMachine* diguyScenario::get_shared_interaction_machine

(

)

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

int diguyScenario::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
	)

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.

Parameters

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

diguyIGuyController* diguyScenario::get_iguy_controller

(

)

This function returns a pointer to the I-Guy controller object of the scenario.

Returns:

pointer of type diguyIGuyController; should never be NULL

diguyViewLabel* diguyScenario::find_or_create_label

(

const char *

name

)

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

Parameters

name	name of the diguyViewLabel to find or create

Returns:

pointer of type diguyViewLabel; should never be NULL

diguyViewLabel* diguyScenario::find_label

(

const char *

name

)

This function returns a pointer to the specified diguyViewLabel.

Parameters

name	name of diguyViewLabel to be found

Returns:

pointer of type diguyViewLabel; NULL if not found

int diguyScenario::destroy_label

(

diguyViewLabel *

label

)

This function destroys the passed in diguyViewLabel.

Parameters

label

pointer to a diguyViewLabel

Returns:

0 on success, -1 on failure

int diguyScenario::get_num_labels

(

)

Returns: The number of diguyViewLabel objects in the scenario.

diguyViewLabel* diguyScenario::get_label_at_index

(

int

index

)

Returns: The diguyViewLabel at the given index.

Parameters

index

index of the diguyViewLabel; indices start at 0

void diguyScenario::reset_labels

(

)

This function removes all diguyViewLabels in the scenario.

void diguyScenario::send_label_to_front

(

diguyViewLabel *

label

)

This function moves the specified diguyViewLabel to the front of the drawing list.

This is sometimes necessary if labels overlap.

Parameters

label

pointer to diguyViewLabel to move

void diguyScenario::send_label_to_back

(

diguyViewLabel *

label

)

This function moves the specified diguyViewLabel to the back of the drawing list.

This is sometimes necessary if labels overlap.

Parameters

label

pointer to diguyViewLabel to move

int diguyScenario::draw_character_labels

(

)

Functions that allow the built-in OGL renderer to draw labels on screen for debugging use, update_character_labels must be called first.

scenario->update_character_labels();
scenario->draw_character_labels();

Returns:

-1 if not possible to draw labels

void diguyScenario::update_character_labels

(

)

See draw_character_labels.

diguyViewButtonPanel* diguyScenario::find_or_create_panel	(	const char *	name,
		int	horizontal = 0,
		int	title = 1
	)

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

Parameters

name	name of the diguyViewButtonPanel to find or create

Returns:

pointer of type diguyViewButtonPanel; should never be NULL

diguyViewButtonPanel* diguyScenario::find_panel

(

const char *

name

)

This function returns a pointer to the specified diguyViewButtonPanel.

Parameters

name	name of diguyViewButtonPanel to be found

Returns:

pointer of type diguyViewButtonPanel; NULL if not found

int diguyScenario::destroy_panel

(

diguyViewButtonPanel *

panel

)

This function destroys the passed in diguyViewButtonPanel.

Parameters

panel

pointer to a diguyViewButtonPanel

Returns:

0 on success, -1 on failure

int diguyScenario::get_num_panels

(

)

Returns: The number of diguyViewButtonPanel objects in the scenario.

diguyViewButtonPanel* diguyScenario::get_panel_at_index

(

int

index

)

Returns: The diguyViewButtonPanel at the given index.

Parameters

index

index of the diguyViewButtonPanel; indices start at 0

int diguyScenario::get_num_minds

(

)

This function returns the number of AI minds that are available to AI agent characters.

Returns:

number of available minds

const char* diguyScenario::get_mind_name_at_index

(

int

index

)

Returns: name of the AI mind at the specified index.

int diguyScenario::is_valid_character_pointer

(

diguyCharacter *

character

)

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

int diguyScenario::is_valid_character_group_pointer

(

diguyCharacterGroup *

character_group

)

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

diguyCrowd* diguyScenario::create_crowd	(	const char *	name,
		int	make_companion_of_all = 1
	)

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.

Parameters

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

int diguyScenario::destroy_crowd	(	diguyCrowd *	crowd,
		int	also_destroy_crowd_members = 0,
		int	also_destroy_path_shapes = 0,
		int	delay_destruction = 0
	)

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.

Parameters

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

int diguyScenario::get_num_crowds

(

)

Returns: the number of crowds in the scenario.

diguyCrowd* diguyScenario::get_crowd_at_index

(

int

index

)

Returns: pointer of type diguyCrowd; NULL if no crowd at the specified index.

Parameters

index

index of the crowd; indices start at 0

const char* diguyScenario::get_unique_crowd_name

(

const char *

base_name

)

Returns: A unique name based on base_name, e.g.

"my_crowd7" from "my_crowd".

Parameters

base_name

base string from which to build a unique name

diguyCrowd* diguyScenario::find_crowd

(

const char *

crowd_name

)

This function returns a pointer to the specified crowd.

Parameters

name	name of crowd to be found

Returns:

pointer of type diguyCrowd; NULL if not found

diguyCrowd* diguyScenario::find_or_create_crowd	(	const char *	crowd_name,
		int	make_companion_of_all = 1
	)

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.

Parameters

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

void diguyScenario::set_create_network_crowds

(

int

do_create

)

This function sets whether crowds should be created for incoming network entities.

Parameters

do_create

pass 1 to create network crowds; 0 to not

int diguyScenario::get_create_network_crowds

(

)

Returns: 1 if network crowds will be created; 0 if not.

diguyCrowdProfile* diguyScenario::create_crowd_profile

(

const char *

name

)

This function creates a new crowd profile and returns a pointer to it.

Parameters

name	name of crowd profile to be created

Returns:

pointer of type diguyCrowdProfile

int diguyScenario::destroy_crowd_profile

(

diguyCrowdProfile *

crowd_profile

)

This function destroys a crowd profile.

Parameters

crowd_profile

pointer to a diguyCrowdProfile

Returns:

0 on success, -1 on failure

int diguyScenario::get_num_crowd_profiles

(

)

Returns: The number of crowd profiles in the scenario.

diguyCrowdProfile* diguyScenario::get_crowd_profile_at_index

(

int

index

)

Returns: pointer of type diguyCrowdProfile; NULL if no crowd profile at the specified index.

Parameters

index

index of the crowd profile; indices start at 0

diguyCrowdProfile* diguyScenario::find_crowd_profile

(

const char *

name

)

This function returns a pointer to the specified crowd profile.

Parameters

name	name of crowd profile to be found

Returns:

pointer of type diguyCrowdProfile; NULL if not found

diguyLoadManager* diguyScenario::get_character_load_manager

(

)

Returns: pointer of type diguyLoadManager; this scenario's character load manager.

int diguyScenario::force_octtree_generation

(

)

This function forces the octtree to rebuild if it's out of date.

void diguyScenario::add_character_to_octtree	(	diguyCharacter *	character,
		int	use_bounding_box_only = 0
	)

Adds the given character to the octtree.

If use_bounding_box_only is true, the bounding box will be used instead of using full link data.

void diguyScenario::remove_character_from_octtree

(

diguyCharacter *

character

)

Removes the given character from the octtree.

int diguyScenario::preload_octtree	(	const char *	character_type,
		const char *	appearance
	)

Preloads the given appearance for the character with octtree data.

Uses more memory, but avoids needing to build data as characters are instantiated.

int diguyScenario::check_visibility	(	float	x1,
		float	y1,
		float	z1,
		float	x2,
		float	y2,
		float	z2
	)

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.

int diguyScenario::set_default_character_altitude_function

(

diguyAltitudeFunction *

altitude_function

)

This function sets a default altitude function that will be added to all characters that are subsequently created.

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

void diguyScenario::set_altitude_function

(

diguyScenarioAltitudeFunction *

altitude_function

)

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.

This is for the benefit of SDK users who have their own representation of terrain and structures.

diguyScenario::ground_clamp() can be told to use the registered function, but this is optional.

DI-Guy Scenario has a default altitude function; replacing the default function is not recommended.

Callable From:

• C++

diguyScenarioAltitudeFunction* diguyScenario::get_altitude_function

(

)

Returns: the altitude function for the scenario as set by set_altitude_function()

Callable From:

• C++

void diguyScenario::set_altitude_max_climb

(

float

altitude_max_climb

)

Sets the height above the current altitude the ground clamp vector will begin.

Defaults to 5 meters

float diguyScenario::get_altitude_max_climb

(

)

void diguyScenario::set_altitude_max_drop

(

float

altitude_max_drop

)

The maximum amount below the current altitude that a character can drop via the altitude function.

Defaults to 100 meters,

float diguyScenario::get_altitude_max_drop

(

)

static void diguyScenario::set_default_intersection_function ( diguyScenarioIntersectionFunction *  intersection_function )

static

Sets the default intersection function.

This function will be used to determine whether there is an intersection between a specified ray and the world.

void diguyScenario::set_intersection_function

(

diguyScenarioIntersectionFunction *

intersection_function

)

int diguyScenario::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,
		int	ground_clamp_impact = 1
	)

Creates a detonation using the specified munition name.

If the DI-Guy networking module is enabled the detonation is broadcast over the network.

Parameters

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
ground_clamp_impact	13.2.1 change, make it posible to not ground clamp this,
was	default behavior : (

**

Note

Overriding the detonation radius will NOT work on broadcast detonations since the override value is not transmitted.

diguyImpact* diguyScenario::find_character_at_screen_coords	(	diguyView *	view,
		float	sx,
		float	sy
	)

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.

Parameters

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

diguyImpact* diguyScenario::get_impact_at_screen_coords	(	diguyView *	view,
		float	sx,
		float	sy,
		int	use_octtree = 0
	)

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.

Parameters

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

diguyImpact* diguyScenario::get_intersection_at_screen_coords	(	diguyView *	view,
		float	sx,
		float	sy,
		int	use_octtree = 0
	)

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.

Parameters

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

int diguyScenario::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
	)

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.

Parameters

origin_x,origin_y,origin_z	starting location of the ray trace
dir_x,dir_y,dir_z	direction of ray trace (should be normalized)
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.

float diguyScenario::ground_clamp	(	float	x,
		float	y,
		float	z,
		int *	valid = NULL,
		int	use_altitude_function = 1,
		int	use_octtree = 0
	)

This function returns the z height, or altitude, of the uppermost piece of terrain under the passed x, y, z point.

Two methods can be used to determine the altitude: a custom scenario altitude function set by the user, or by testing against DI-Guy's internal octtree calculated from terrain geometry.

See set_altitude_function() for information on the scenario altitude function. DI-Guy Scenario has its own version of this function, which 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. Users of the SDK typically have their own representations of terrain and structures.

Parameters

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 (tried first)
use_octtree	pass 1 to use internal octtree

Returns:

new_z if ground clamp was possible, original z if not

int diguyScenario::set_fire_weapon_intersection_function

(

diguyScenarioFindImpactOnLineFunction *

impact_function

)

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

static void diguyScenario::set_default_fire_weapon_intersection_function ( diguyScenarioFindImpactOnLineFunction *  impact_function )

static

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

diguyImpact* diguyScenario::map_color_to_impact	(	char	r,
		char	g,
		char	b
	)

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.

diguyImpact* diguyScenario::get_last_env_impact_info

(

)

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.

void diguyScenario::set_last_impact_been_processed

(

)

Reading of data from the last impact information will be considered complete when this function is called.

void diguyScenario::set_last_env_impact_info

(

const diguyImpact &

impact

)

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.

void diguyScenario::set_max_unprocessed_impacts

(

int

max_unprocessed_impacts

)

Sets the maximum number of unprocessed impacts there can be.

The unprocessed impact array is a first-in-first-out queue. If an impact occurs that pushes the number of unprocessed impacts past this maximum number, earlier impacts will be dropped from the array.

The initial value is 10.

int diguyScenario::set_default_point_los_function

(

diguyPointLOSFunction *

point_los_function

)

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

int diguyScenario::set_default_character_los_function

(

diguyCharacterLOSFunction *

character_los_function

)

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

int diguyScenario::set_default_agent_feeler_function

(

diguyFeelerFunction *

feeler_function

)

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.

Parameters

feeler_function

pointer to user-defined feeler function

Returns:

0 on success, -1 on failure

Callable From:

• C++

diguyIntersectionResult diguyScenario::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
	)

Experimental intersection-detection function.

Parameters

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

diguyRegion* diguyScenario::find_or_create_region

(

const char *

name

)

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.

Parameters

name	name of the region to find or create

Returns:

pointer of type diguyRegion; should never be NULL

diguyRegion* diguyScenario::find_region

(

const char *

name

)

This function returns a pointer to the specified region.

Parameters

name	name of region to be found

Returns:

pointer of type diguyRegion; NULL if not found

diguyRegion* diguyScenario::create_region

(

const char *

name

)

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

Parameters

name	name of the new region object

Returns:

pointer of type diguyRegion

void diguyScenario::destroy_region

(

diguyRegion *

region

)

This function destroys the passed region.

Parameters

region

region to destroy

int diguyScenario::get_num_regions

(

)

Returns: number of regions in the scenario.

diguyRegion* diguyScenario::get_region_at_index

(

int

index

)

Returns: pointer of type diguyRegion; NULL if no region at the specified index.

Parameters

index

index of the region; indices start at 0

int diguyScenario::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
	)

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

Parameters

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

void diguyScenario::set_max_distance_planning_multiplier

(

float

mul

)

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.

float diguyScenario::get_max_distance_planning_multiplier

(

)

Returns: float constant that's used to decide if planner should give up; -1 means off.

float diguyScenario::get_time_spent_path_planning_this_frame

(

)

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

void diguyScenario::set_multithreaded_path_planning_enabled

(

int

value

)

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.

int diguyScenario::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.

int diguyScenario::get_num_formations

(

)

Returns: number of formations in the scenario.

diguyFormation* diguyScenario::get_formation_at_index

(

int

index

)

Returns: pointer of type diguyFormation; NULL if no formation at the specified index.

Parameters

index

index of the formation; indices start at 0

diguyFormation* diguyScenario::find_formation

(

const char *

name

)

This function returns a pointer to the specified formation.

Parameters

name	name of formation to be found

Returns:

pointer of type diguyFormation; NULL if not found

diguyFormation* diguyScenario::find_formation_of_size

(

int

size

)

This function returns a pointer to the first formation it finds of a given size.

Parameters

size	size of formation to be found

Returns:

pointer of type diguyFormation; NULL if not found

diguyFormation* diguyScenario::create_formation

(

const char *

name

)

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

Parameters

name	name of the new formation

Returns:

pointer of type diguyFormation

diguyFormation* diguyScenario::find_or_create_formation

(

const char *

name

)

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

Parameters

name	name of the formation to find or create

Returns:

pointer of type diguyFormation; should never be NULL

int diguyScenario::destroy_formation

(

diguyFormation *

formation

)

This function destroys a formation.

Parameters

formation

pointer to a diguyFormation

Returns:

0 on success, -1 on failure

void diguyScenario::set_draw_authoring_visuals

(

int

visible

)

Required to turn on visual aids in programming examples.

int diguyScenario::get_draw_authoring_visuals

(

)

void diguyScenario::set_action_bead_labels_visible

(

diguyVisibleFlag

vflag

)

void diguyScenario::set_aim_trajectories_visible

(

diguyVisibleFlag

vflag

)

void diguyScenario::set_author_selection_handles_visible

(

diguyVisibleFlag

vflag

)

void diguyScenario::set_bead_array_visible

(

diguyVisibleFlag

vflag

)

void diguyScenario::set_character_labels_visible

(

diguyVisibleFlag

vflag

)

void diguyScenario::set_character_visible

(

diguyVisibleFlag

vflag

)

void diguyScenario::set_crowd_behavior_visible

(

diguyVisibleFlag

flag

)

void diguyScenario::set_crowd_feelers_visible

(

diguyVisibleFlag

flag

)

void diguyScenario::set_crowd_influence_visible

(

diguyVisibleFlag

flag

)

void diguyScenario::set_crowd_regions_visible

(

diguyVisibleFlag

flag

)

void diguyScenario::set_gaze_vector_visible

(

diguyVisibleFlag

flag

)

void diguyScenario::set_light_array_visible

(

diguyVisibleFlag

vflag

)

void diguyScenario::set_lua_objects_visible

(

diguyVisibleFlag

flag

)

void diguyScenario::set_mesh_region_array_visible

(

diguyVisibleFlag

vflag

)

void diguyScenario::set_sensor_region_array_visible

(

diguyVisibleFlag

vflag

)

void diguyScenario::set_spath_visible

(

diguyVisibleFlag

vflag

)

void diguyScenario::set_waypoint_array_visible

(

diguyVisibleFlag

vflag

)

diguyVisibleFlag diguyScenario::get_action_bead_labels_visible

(

)

diguyVisibleFlag diguyScenario::get_aim_trajectories_visible

(

)

diguyVisibleFlag diguyScenario::get_author_selection_handles_visible

(

)

diguyVisibleFlag diguyScenario::get_bead_array_visible

(

)

diguyVisibleFlag diguyScenario::get_character_labels_visible

(

)

diguyVisibleFlag diguyScenario::get_character_visible

(

)

diguyVisibleFlag diguyScenario::get_crowd_behavior_visible

(

)

diguyVisibleFlag diguyScenario::get_crowd_feelers_visible

(

)

diguyVisibleFlag diguyScenario::get_crowd_influence_visible

(

)

diguyVisibleFlag diguyScenario::get_crowd_regions_visible

(

)

diguyVisibleFlag diguyScenario::get_gaze_vectors_visible

(

)

diguyVisibleFlag diguyScenario::get_light_array_visible

(

)

diguyVisibleFlag diguyScenario::get_lua_objects_visible

(

)

diguyVisibleFlag diguyScenario::get_mesh_region_array_visible

(

)

diguyVisibleFlag diguyScenario::get_sensor_region_array_visible

(

)

diguyVisibleFlag diguyScenario::get_spath_visible

(

)

diguyVisibleFlag diguyScenario::get_waypoint_array_visible

(

)

void diguyScenario::set_hide_author_selection_handles_during_play

(

int

visible

)

int diguyScenario::get_hide_author_selection_handles_during_play

(

)

int diguyScenario::get_weapon_flash_enabled

(

)

Returns: If weapon fire will show flash geometry, (depending on munition configuration)

int diguyScenario::set_weapon_flash_enabled

(

int

enabled

)

Sets if weapon fire will create weapon geometry, (depending on munition configuration)

int diguyScenario::get_weapon_fire_effects_enabled

(

)

Returns: If weapon fire will create light flashes, smoke and shell ejections, (depending on munition configuration)

int diguyScenario::set_weapon_fire_effects_enabled

(

int

enabled

)

Sets if weapon fire will create light flashes, smoke and shell ejections, (depending on munition configuration)

int diguyScenario::get_num_active_fire_effects

(

)

Returns: The number of light flashes that are currently active.

int diguyScenario::get_weapon_fire_effect_data	(	int	index,
		float *	radius,
		double *	position_x,
		double *	position_y,
		double *	position_z,
		float *	color_r,
		float *	color_g,
		float *	color_b,
		float *	falloff_r,
		float *	falloff_rsq
	)

This function gets the data needed for producing a weapon flash light source in the world.

The convenience function diguyOglUtils::update_lighting() shows sample implementation for feeding this data into uniform buffers.

int diguyScenario::get_num_active_lights

(

)

Returns: The number of lights that are currently active, should be valid after update is called.

int diguyScenario::sort_active_lights

(

)

sorts the list of active lights for this frame

int diguyScenario::get_active_light_data	(	int	index,
		diguyLightRenderDesc *	light_desc
	)

This function gets the data needed for producing a particle system or vehicle light.

The convenience function diguyOglUtils::update_lighting() shows sample implementation for feeding this data into uniform buffers.

int diguyScenario::set_current_character

(

diguyCharacter *

current_character

)

Sets the current selected character in scenario.

Returns:

0 on success, -1 on failure

diguyCharacter* diguyScenario::get_current_character

(

)

Returns: The current selected character in scenario.

int diguyScenario::get_current_character_index

(

)

The current selected character's index.

int diguyScenario::set_current_crowd

(

diguyCrowd *

current_crowd

)

Sets the current selected crowd in scenario.

Returns:

0 on success, -1 on failure

diguyCrowd* diguyScenario::get_current_crowd

(

)

Returns: The current selected crowd in scenario.

int diguyScenario::set_current_crowd_profile

(

diguyCrowdProfile *

current_profile

)

Sets the active crowd profile, which determines the attributes of subsequently-created crowds.

See diguyCrowdProfile.

Returns:

0 on success, -1 on failure

int diguyScenario::set_current_crowd_profile_by_name

(

const char *

crowd_profile_name

)

Sets the active crowd profile by name.

Returns:

0 on success, -1 on failure

diguyCrowdProfile* diguyScenario::get_current_crowd_profile

(

)

Returns: Active crowd profile.

int diguyScenario::set_current_region

(

diguyRegion *

current_region

)

Sets the current region.

See diguyRegion.

Returns:

0 on success, -1 on failure

diguyRegion* diguyScenario::get_current_region

(

)

Returns: Current region.

void diguyScenario::set_particle_module_disabled

(

int

disable_particle_module

)

This function enables or disables the particle module.

By default the particle module is enabled.

int diguyScenario::create_particle_system	(	const char *	description_name,
		float	x,
		float	y,
		float	z,
		int	record_transient_event = 1,
		float	duration = -1.0f
	)

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.

Parameters

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

int diguyScenario::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
	)

Similar to create_particle_system(), but allows orientation to be set.

Parameters

rz,rx,ry

orientation axes

(See create_particle_system() for other parameters)

int diguyScenario::has_particle_description

(

const char *

description_name

)

Returns: 1 if the particle description named description_name exists, else 0.

void diguyScenario::set_global_wind	(	float	x,
		float	y,
		float	z
	)

Set wind velocity vector for particle system.

const char* diguyScenario::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.

Parameters

lua_object	a global lua object
field_name	name of the field; field_name can include ".", allowing retrieval of fields in complex data structures

const char* diguyScenario::lua_evaluate_object_function	(	const char *	lua_object,
		const char *	function_name,
		const char *	argument = NULL,
		int	has_return_string = 0
	)

Runs a member function of a lua object.

Parameters

lua_object	a lua object in the global scope, object names with fields should be properly handled ie object.subobject.blah should get properly parsed
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.

const char* diguyScenario::lua_evaluate_object_function_2a	(	const char *	lua_object,
		const char *	function_name,
		const char *	argument,
		const char *	argument2,
		int	has_return_string = 0
	)

A two argument version of lua_evaluate_object_function().

const char* diguyScenario::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
	)

A three argument version of lua_evaluate_object_function().

const char* diguyScenario::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
	)

A four argument version of lua_evaluate_object_function().

int diguyScenario::lua_send_message_to_object	(	const char *	lua_object,
		const char *	sender,
		const char *	message_type,
		const char *	message,
		const char *	message_params = NULL
	)

Executes a lua_object:state_manager() function call.

Useful for creating sleep-able coroutine based objects that aren't characters.

void* diguyScenario::get_lua_state

(

)

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.org/pil/24.html

NOTE:

Currently all scenarios share the same underlying Lua state object. This may cause issues in applications with multiple scenarios.

Callable From:

• C++

int diguyScenario::push_qt_pointer_to_lua	(	void *	lua_state,
		const char *	class_name,
		void *	ptr
	)

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.

Parameters

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

const char* diguyScenario::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
	)

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

Parameters

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

const char* diguyScenario::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
	)

Effectively the same as diguyScenario::lua_evaluate_object_function_4a_flex() but works on global functions.

Callable From:

• C++

int diguyScenario::lua_log_printf	(	int	notify_level,
		const char *	string
	)

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.

const char* diguyScenario::dump_package_info

(

const char *

package_name

)

Returns: package meta data as a formatted string; useful for debugging, only valid inside DI-Guy Scenario.

int diguyScenario::send_message	(	diguyCharacter *	to_character,
		diguyCharacter *	from_character,
		const char *	message_type,
		const char *	message,
		const char *	message_params = NULL
	)

Sends a message to specified diguyCharacter.

The recipient must have a Lua mind that is capable of handling the message. The message will wake up the sleep() function in the mind that last relinquished control from the mind's coroutine.

Parameters

to_character	the diguyCharacter to receive the message
from_character	the diguyCharacter from whom the message originates
message_type	should properly be "signal", but other settings may be used
message	the actual name of the message, e.g. "detonation"
message_params	comma-separated parameters, for use by the message handler

Returns:

1 if message delivery successful, otherwise 0

Callable From:

• C++ and Lua

int diguyScenario::broadcast_message	(	diguyCharacter *	from_character,
		float	radius,
		const char *	message_type,
		const char *	message,
		const char *	message_params = NULL
	)

Broadcasts a message to all other diguyCharacters within a certain radius of the from_character.

The recipients must have Lua minds that are capable of handling the message. The message will wake up the sleep() function in the mind that last relinquished control from the mind's coroutine.

Parameters

from_character	the diguyCharacter from whom the message originates
radius	how far the broadcast goes (in meters) from the from_character
message_type	should properly be "broadcast", but other settings may be used
message	the actual name of the message, e.g. "detonation"
message_params	comma-separated parameters, for use by the message handler

Returns:

-1 for failure, >= 0 for number of successful receptions

Callable From:

• C++ and Lua

int diguyScenario::broadcast_message_to_group	(	diguyCharacter *	from_character,
		const char *	group_name,
		float	radius,
		const char *	message_type,
		const char *	message,
		const char *	message_params = NULL
	)

Broadcasts a message to all diguyCharacters within named group, who are within given radius of the from_character.

See comments for broadcast_message() above.

Parameters

from_character	the diguyCharacter from whom the message originates
group_name	name of group to broadcast to
radius	how far the broadcast goes (in meters) from the from_character
message_type	should properly be "broadcast", but other settings may be used
message	the actual name of the message, e.g. "detonation"
message_params	comma-separated parameters, for use by the message handler

Returns:

-1 for failure, >= 0 for number of successful receptions

Callable From:

• C++ and Lua

int diguyScenario::get_eval_decisions_as_scripts

(

)

Returns: value set by last call to set_eval_decisions_as_scripts()

void diguyScenario::set_eval_decisions_as_scripts

(

int

eval_decisions_as_scripts

)

If called with an argument of 1, all decision beads and decision beads will be converted to scripts before being run.

diguyImpact* diguyScenario::get_impact_on_line	(	float	from_x,
		float	from_y,
		float	from_z,
		float	to_x,
		float	to_y,
		float	to_z
	)

Gets the point of impact with the world along specified line segment.

Returns:

pointer to diguyImpact object or NULL

void diguyScenario::wait_cursor_push

(

)

Increments wait cursor counter.

If non-zero, then wait cursor is displayed in DI-GUY scenario.

void diguyScenario::wait_cursor_pop

(

)

Decrements wait cursor counter.

diguyParticleSystemRenderer* diguyScenario::get_particle_renderer

(

)

returns pointer to current particle renderer implementation

void diguyScenario::set_character_sorting_enabled

(

int

enabled

)

turns off the sorting of characters for drawing, practical for retained mode renderers

int diguyScenario::get_character_sorting_enabled

(

)

void diguyScenario::set_graphics_api_node_ptr

(

void *

node_ptr

)

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

The pointer is otherwise not used.

Parameters

node_ptr

generic void* pointer

Callable From:

• C++

void* diguyScenario::get_graphics_api_node_ptr

(

)

Returns: pointer set by most recent call to set_graphics_api_node_ptr.

Callable From:

• C++

void diguyScenario::set_draw_character_shadow_disks

(

int

draw_character_shadow_disks

)

Sets whether shadow disks are drawn for characters.

Call with 1 to turn on, 0 to turn off.

int diguyScenario::get_draw_character_shadow_disks

(

)

Returns: 1 if shadow disks are drawn, 0 if not.

int diguyScenario::get_shadow_map_size

(

)

Returns: size of texture map for shadows.

int diguyScenario::set_shadow_map_size

(

int

shadow_size

)

Sets size of texture map for shadows.

Defaults to 1024. Allowed values are powers of two up to 4096.

void diguyScenario::set_default_character_scene_graph_mask

(

unsigned long

mask

)

Used for DI-Guy OSG Author Programming Example.

Sets the default value used for characters. See also diguyCharacter::set_scene_graph_mask()

unsigned long diguyScenario::get_default_character_scene_graph_mask

(

)

void diguyScenario::set_default_scene_object_scene_graph_mask

(

unsigned long

mask

)

Used for DI-Guy OSG Author Programming Example.

Sets the default value used for characters. See also diguySceneObject::set_scene_graph_mask()

unsigned long diguyScenario::get_default_scene_object_scene_graph_mask

(

)

void diguyScenario::set_internal_int	(	int	var,
		int	val
	)

For internal use.

void diguyScenario::set_internal_float	(	int	var,
		float	val
	)

int diguyScenario::set_num_active_point_lights

(

int

active_lights

)

This sets the number of point lights that get handed down to diguyGraphicsShaderTechnique::pick_shader_program().

int diguyScenario::get_num_active_point_lights

(

)

This gets the number of point lights that get handed down to diguyGraphicsShaderTechnique::pick_shader_program() the default is 0.

The convenience function diguyOglUtils::update_lighting() shows sample implementation for feeding this data into uniform buffers.

int diguyScenario::set_world_bounds	(	float	x_min,
		float	y_min,
		float	z_min,
		float	x_max,
		float	y_max,
		float	z_max
	)

Sets bounding box of world.

Parameters

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)

int diguyScenario::get_world_bounds	(	float *	x_min,
		float *	y_min,
		float *	z_min,
		float *	x_max,
		float *	y_max,
		float *	z_max
	)

Gets bounding box of world.

Parameters

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)

void diguyScenario::set_checkpoint_frequency

(

float

freq

)

Internal use.

float diguyScenario::get_checkpoint_frequency

(

)

Internal use.

void diguyScenario::set_checkpointing_enabled

(

int

enable_checkpointing

)

Internal use.

int diguyScenario::get_checkpointing_enabled

(

)

Internal use.

void diguyScenario::set_initial_render_mode

(

const char *

render_mode

)

Sets initial render mode.

Parameters

render_mode

string containing render mode setting name

Built-in render modes:

"normal" "shadow" "glow" "alternate1" "alternate2" "alternate3"

const char* diguyScenario::get_initial_render_mode

(

)

Returns: initial render mode, as string.

void diguyScenario::set_current_render_mode

(

const char *

render_mode

)

Sets current render mode.

See set_initial_render_mode()

const char* diguyScenario::derive_render_mode_from_light_settings

(

int

set_current_to_derived = 1

)

Returns: render mode, as string, derived from current light settings.

Parameters

set_current_to_derived

if 1, current render mode becomes derived mode

const char* diguyScenario::get_current_render_mode

(

)

Returns current render mode, as string.

void diguyScenario::set_default_character_shader	(	const char *	render_mode,
		const char *	shader_name,
		int	update_existing_characters = 1
	)

Sets default shader for characters.

Parameters

render_mode	string containing render mode name
shader_name	string containing name of shader technique (there should be a _glsl.cfg file of the same name)
update_existing_characters	if 1, all existing characters will now be drawn using this shader

const char* diguyScenario::get_default_character_shader

(

const char *

render_mode

)

Returns name of shader technique used for specified render mode.

void diguyScenario::set_default_scene_object_shader	(	const char *	render_mode,
		const char *	shader_name,
		int	update_existing_scene_objects = 1
	)

Sets default shader for scene objects.

Parameters

render_mode	string containing render mode name
shader_name	string containing name of shader technique (there should be a _glsl.cfg file of the same name)
update_existing_scene_objects	if 1, all existing scene objects will now be drawn using this shader

const char* diguyScenario::get_default_scene_object_shader

(

const char *

render_mode

)

Returns name of shader technique used for specified render mode.

void diguyScenario::set_default_particle_system_shader	(	const char *	render_mode,
		const char *	shader_name,
		int	update_existing_particle_systems = 1
	)

Sets default shader for particle systems.

Parameters

render_mode	string containing render mode name
shader_name	string containing name of shader technique (there should be a _glsl.cfg file of the same name)
update_existing_particle_systems	if 1, all existing particle systems will now be drawn using this shader

const char* diguyScenario::get_default_particle_system_shader

(

const char *

render_mode

)

Returns name of shader technique used for specified render mode.

int diguyScenario::facefx_mount_animset	(	const char *	actor_name,
		const char *	file_name
	)

Sets FaceFX animation set for a given actor.

Parameters

actor_name	actor's name
file_name	fully qualified file name ending in ".animset_ingame"

int diguyScenario::set_vehicle_smoothing_enabled

(

int

enable_smoothing

)

Sets vehicle smoothing on or off.

If 1, vehicle will be updated at a higher rate than frame dt

Default is on.

int diguyScenario::get_vehicle_smoothing_enabled

(

)

int diguyScenario::set_realtime_ik_enabled

(

int

val

)

Sets realtime IK on or off.

Experimental.

int diguyScenario::get_realtime_ik_enabled

(

)

int diguyScenario::set_draw_ik_visuals

(

int

val

)

int diguyScenario::get_draw_ik_visuals

(

)

int diguyScenario::set_draw_skeletons

(

int

val

)

int diguyScenario::get_draw_skeletons

(

)

float diguyScenario::get_last_update_time ( )

inline

void diguyScenario::set_disable_profiler

(

)

const char* diguyScenario::get_lua_field_as_string	(	const char *	lua_object,
		const char *	field_name,
		int	warn_if_no_field = 1
	)

float diguyScenario::get_lua_field_as_float	(	const char *	lua_object,
		const char *	field_name,
		int	warn_if_no_field = 1,
		int *	found_field = NULL
	)

void diguyScenario::update_particle_preview

(

float

time

)

int diguyScenario::get_character_type_num_head_appearances

(

const char *

character_type

)

Similar to get_character_type_num_appearances(), but for head appearances.

const char* diguyScenario::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.

static int diguyScenario::add_default_callback ( int  callback_id, diguyScenarioCallback *  callback, void *  callback_params = 0, void *  callback_user_data = 0  )

static

Deprecated; use diguyApp::add_default_scenario_callback() instead.

static int diguyScenario::remove_default_callback ( int  callback_id, diguyScenarioCallback *  callback  )

static

Deprecated; use diguyApp::remove_default_scenario_callback() instead.

static int diguyScenario::remove_default_callback_with_user_data ( int  callback_id, void *  callback_user_data  )

static

Deprecated; use diguyApp::remove_default_scenario_callback_with_User_data() instead.

static int diguyScenario::add_default_callback_script ( int  callback_id, const char *  callback_script, const char *  callback_script_type  )

static

Deprecated; use diguyApp::add_default_scenario_callback_script() instead.

static int diguyScenario::remove_default_callback_script ( int  callback_id, const char *  callback_script, const char *  callback_script_type  )

static

Deprecated; use diguyApp::remove_default_scenario_callback_script() instead.

const char* diguyScenario::get_character_type_class

(

const char *

character_type

)

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)

int diguyScenario::merge_asset

(

const char *

string

)

Deprecated as of 10.5.1; use merge_object() intead.

void diguyScenario::print_to_log	(	int	notify_level,
		const char *	string
	)

Deprecated as of 12.0.0; use bdi_log_print() from libbdilog.h instead.

diguyCharacter* diguyScenario::create_pending_reflected_character	(	const char *	name,
		const char *	character_type,
		const char *	appearance = NULL
	)

int diguyScenario::set_network_translation	(	float	x,
		float	y,
		float	z
	)

int diguyScenario::get_network_translation	(	float *	x,
		float *	y,
		float *	z
	)

void diguyScenario::set_project_filename

(

const char *

project_filename

)

Deprecated as of 12.0.0; use save_as() instead.

const char* diguyScenario::get_project_filename

(

)

Deprecated as of 12.0.0; use get_filename() or get_filename_without_directory() intead.

bdiScenario* diguyScenario::get_scripted_object

(

)

Friends And Related Function Documentation

friend class bdiScenario

friend

Member Data Documentation

bdiScenario* diguyScenario::m_scenario

private

A pointer to internal data.

float diguyScenario::m_last_update_time

private

---

The documentation for this class was generated from the following file:

• diguyScenario.h