diguyScenario.h

Go to the documentation of this file.

/****************************************************************************
 * Copyright (c) 2025 MAK Technologies, Inc.
 * All rights reserved.
 ****************************************************************************/


#pragma once

#ifdef SWIG
%module diguyScenario
#else
#define CPLUSPLUS_ONLY
#endif

#ifdef CPLUSPLUS_ONLY

#include <declspec_diguy.h>
#include <diguyViewCamera.h>
#include <diguyViewFog.h>
#include <diguyViewLight.h>
#include <diguyMotionDirection.h>
#include <diguyMotionPosture.h>
#include <diguyMotionVariant.h>
#include <diguyCharacterTypeMap.h>
#include <diguy_vector_classes.h>

// for texture atlas enum
#include <diguyGraphicsTexture.h>

#include "diguy_constants.h"
#include "diguy_typedefs.h"
#include "diguyCharacterPath.h"
#include "diguyInteractionMachine.h"
#include "diguySensorRegion.h"
#include "diguySignal.h"
#include "diguyVariable.h"
#include "diguyView.h"

class bdiScenario;

class diguyViewButtonPanel;
class diguyChainSettings;
class diguyCharacter;
class diguyCharacterFaceExpression;
class diguyCharacterGroup;
class diguyCharacterPathEvent;
class diguyCharacterTypeMapFieldValues;
class diguyCrowd;
class diguyCrowdProfile;
class diguyGestureMetadata;
class diguyLoadManager;
class diguyFormation;
class diguyViewLabel;
class diguyIGuyController;
class diguyInfoPopup;
class diguyImpact;
class diguyPatchIdentifier;
class diguyPathShape;
class diguyRegion;
class diguyScenarioMergeSettings;
class diguySceneObject;
class diguySensorRegion;
class diguySound;
class diguyVariable;
class diguyWaypoint;
class diguyView;
class diguyViewCameraSettings;
class diguyViewFogSettings;
class diguyViewLightSettings;
class diguyIntersectionResult;

enum diguyTextureUniformPatchLocations;

struct diguyLightRenderDesc;
struct diguyTransitionInfo;

#endif

/****************************************************************************/
class BDI_DECLSPEC_diguy diguyScenario
{

/*****************************************************************************/
public:

   /*l
    *b  Description:
    **
    **    This static function returns a pointer to the current scenario
    **    object.  All functions below can then be called through this
    **    pointer.  This is the same pointer returned by the call
    **    diguy_create_scenario().
    **
    **    lua scripts get the current scenario through the variable
    **    this_scenario.
    **
    *b  Returns:
    **
    **    a pointer of type diguyScenario
    **
    *b  C++ Example:
    **
    *e     diguyScenario* sc = diguyScenario::get_current_scenario();
    *e     sc->reset();
    **
    *b  Lua Example:
    **
    *e     this_scenario:reset();
    */
   static diguyScenario* get_current_scenario();

   /*l
    *b  Description:
    **
    **    Returns the name of the object.  This pointer will never be NULL.
    **
    *b  Returns:
    **
    **    name of the object
    */
   const char* get_name();

   /*l
    *b  Description:
    **
    **    Returns the type name of the object.  This pointer will never be
    **    NULL.
    **
    *b  Returns:
    **
    **    type name of the object
    */
   const char* get_type_name();

   /*l
    *b  Returns:
    **
    **    the scenario description as specified in the scenario info page
    */
   const char* get_description();


/*****************************************************************************/
#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    Sets the desired simulation time of the scenario.
    **
    **    Some update operations will use the simulation desired time
    **    directly.
    **
    **    Many other scenario operations -- notably character position and
    **    pose updates -- will not happen until the desired t passes each
    **    subsequent tick dt threshold.  See set_tick_dt().
    **
    **    This function sets both elapsed simulation time and elapsed
    **    realtime to the same value.  This is usually desired in DI-Guy
    **    applications.  To pass separate values for simulation time and
    **    realtime time, call update2().
    **
    **    Time can be run backwards.  This happens if the passed t is lower
    **    than any t previously passed to the update() function; the
    **    scenario remembers the highest t it has reached.  If t is set to
    **    less that the highest t reached, characters that have history data
    **    will replay what they were doing at the specified time.
    **    Characters that do not have history will remain motionless until t
    **    advances past the previous highest t.
    **
    **    Scenario time will never go below 0.
    **
    **    If t reaches the scenario tout ("T Out") time (as set by
    **    set_tout(), a number of things may happen.  The scenario may:
    **
    *-    - simply stop at the tout time
    *-    - continue past the tout time
    *-    - rewind to time 0 and play back recorded history
    *-    - reset and re-simulate the scenario from time 0
    **
    **    The default tout time is 60000 for DI-Guy applications.  The tout
    **    can be enabled and disabled with set_tout_enabled().
    **
    **    This function cannot explicitly be called for DI-Guy Scenario, but
    **    the effects of t reaching tout during scenario simulation are
    **    outlined here anyway.
    **
    *b    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.
    *-
    *b    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.
    **
    *b  Arguments:
    **
    *a    t - desired time in seconds
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int update(float t);

   /*l
    *b  Description:
    **
    **    Similar to update(), but the realtime time can be explicitly
    **    passed in.
    **
    *b  Arguments:
    **
    *a    t          - desired simulation time in seconds
    *a    realtime_t - elapsed real time in seconds
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int update2(float t, float realtime_t);

   /*l
    *b  Description:
    **
    **    This function sets whether the scenario is designed to loop at
    **    tout.  The default is for scenarios to loop.
    **
    **    Note that this has an effect only in DI-Guy Scenario.  DI-Guy
    **    applications do not use this flag.
    **
    **    See get_playback_loop().
    **
    *b  Arguments:
    **
    *a    playback_loop - pass 1 to have scenario loop at tout, 0 to not
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int set_playback_loop(int playback_loop);

   /*l
    *b  Description:
    **
    **    Scenarios progress at discrete time steps, called "ticks".  Each
    **    tick is of the same duration.  This function sets the amount of
    **    time each tick takes.
    **
    **    Because changing the tick interval of a scenario changes when
    **    event beads occur, any change may introduce subtle differences in
    **    scenario playback.
    **
    **    Note that loading a .dss file will change the tick dt, as tick dt
    **    is set on a per scenario basis.
    **
    **    The default tick dt of a new scenario is 0.03125 seconds, or 32
    **    frames per second.
    **
    *b  Arguments:
    **
    *a    tick_dt - duration, in seconds, of each scenario tick
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    **
    *b  C++ Example:
    **
    *e    diguyScenario* sc = diguy_create_scenario();
    *e    if (sc)
    *e    {
    *e       sc->load("my_scenario.dss");
    *e       sc->set_tick_dt(0.033333);   // 30 fps
    *e    }
    */
   int set_tick_dt(float tick_dt);

#endif

   /*l
    *b  Description:
    **
    **    This function returns the time in seconds that the scenario is
    **    currently at.  See update().
    **
    **    Note that this value will not necessarily track the t passed in
    **    the update() function.  This t advances only when the scenario's
    **    current tick changes.  See set_tick_dt() and update().
    **
    *b  Returns:
    **
    **    current time in seconds
    */
   float get_t();

   /*l
    *b  Description:
    **
    **    This function returns the realtime time in seconds that the
    **    scenario is currently at.  This may be different than
    **    get_desired_t() if the scenario is stopped or the time passed in
    **    update() is not tracking realtime.
    **
    *b  Returns:
    **
    **    current time in seconds
    */
   float get_realtime_t();

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

   /*l
    *b  Description:
    **
    **    This function sets the tout ("T Out") time of the scenario.  What
    **    will happen when the scenario reaches this time depends on a
    **    number of factors.  See update() for more information.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int set_tout(float tout);

   /*l
    *b  Description:
    **
    **    This function returns the tout time of the scenario.  This is the
    **    time at which a scenario is designed to end.
    **
    **    See set_tout() and update().
    **
    *b  Returns:
    **
    **    tout of scenario
    */
   float get_tout();

   /*l
    *b  Description:
    **
    **    This function sets what will happen when the scenario reaches its
    **    tout time.  If set to 0, the scenario will ignore the tout time
    **    and continue indefinitely.
    **
    **    See update() for more information.
    */
   void set_tout_enabled(int tout_enabled);

   /*l
    *b  Description:
    **
    **    This function returns the whether tout is enabled.
    **
    **    See set_tout_enabled() and update().
    **
    *b  Returns:
    **
    **    1 if tout enabled, 0 if not
    */
   int get_tout_enabled();

   /*l
    *b  Description:
    **
    **    This function returns whether the scenario is designed to loop
    **    when the scenario's tout time is reached.
    **
    **    See update() for more information about looping.
    **
    *b  Returns:
    **
    **    0 if no loop desired; 1 if loop desired
    */
   int get_playback_loop();

   /*l
    *b  Description:
    **
    **    This function returns the most recent setting of set_tick_dt().
    */
   float get_tick_dt();

   /*l
    *b  Returns:
    **
    **    This function returns the most recent setting of
    **    set_ticks_can_be_dropped().
    */
   int get_ticks_can_be_dropped();

   /*l
    *b  Description:
    **
    **    This function sets whether a scenario can "drop" ticks in order to
    **    catch up if it falls behind.
    **
    **    Scenario updates progress in discrete time steps called ticks (see
    **    set_tick_dt() and update()).  If the difference in times specified
    **    in subsequent calls to update() is greater than the tick dt, which
    **    can happen if calls to update() are taking too long because the
    **    scenario is too complex or if the caller is attempting to "fast
    **    forward" to a particular time in the scenario, the scenario may
    **    skip processing of intermediate ticks in order to catch up.
    **
    **    The scenario will not consider itself behind until the number of
    **    ticks covered by a particular call to update() is equal to or
    **    greater than the value set by set_max_ticks_behind_until_drop().
    **
    **    Dropping ticks, while it improves performance, may have unintended
    **    side effects, including:
    **
    *-    - event beads of characters on paths that fall on the dropped
    *-      ticks -- including aim beads, decision beads, gaze beads, and
    *-      script beads -- will not be evaluated and will therefore have
    *-      no effect on the scenario
    *-    - review playback of characters (see
    *-      diguyCharacter::set_history_type()) over the dropped intervals
    *-      will be choppy
    **
    **    Not dropping ticks also has potential side effects:
    **
    *-    - if a scenario is falling behind more and more on each call
    *-      to update(), it may never be able to catch up and performance
    *-      of DI-Guy will increasingly degrade
    **
    **    The default setting is that ticks can be dropped.
    **
    *b  Arguments:
    **
    *a    ticks_can_be_dropped - pass 1 for ticks to be dropped; else
    *a                           pass 0
    */
   void set_ticks_can_be_dropped(int ticks_can_be_dropped);

   /*l
    *b  Returns:
    **
    **    This function returns the most recent setting of
    **    set_max_ticks_behind_until_drop().
    */
   long get_max_ticks_behind_until_drop();

   /*l
    *b  Description:
    **
    **    This function sets how many ticks a scenario must be behind before
    **    it starts dropping ticks in order to catch up.
    **
    **    For a discussion of how a scenario may fall behind, see
    **    set_ticks_can_be_dropped().
    **
    **    Note that if ticks cannot be dropped, (e.g., 0 is passed to
    **    set_ticks_can_be_dropped()) this function will have no effect.
    **
    **    The default value is 0 in the DI-Guy SDK, In DI-Guy Scenario it is 2.
    **
    *b  Arguments:
    **
    *a    max_ticks_behind_until_drop - how many ticks a scenario must
    *a                                  be behind until it drops ticks
    */
   void set_max_ticks_behind_until_drop(long max_ticks_behind_until_drop);

   /*l
    *b  Description:
    **
    **    This function sets the current playback mode of DI-Guy Scenario.
    **    It currently will have no effect in applications using the DI-Guy
    **    API.
    **
    *b  Arguments:
    **
    *a    playback_mode - new playback mode
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int set_playback_mode(diguyScenarioPlaybackMode playback_mode);

   /*l
    *b  Description:
    **
    **    This function is shorthand for the function call
    **    set_playback_mode(DIGUY_SCENARIO_PLAYBACK_MODE_STOP).  It is
    **    useful for pausing the scenario in decisions and decision beads.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    *-    - Decision
    */
   int set_playback_mode_stop();

   /*l
    *b  Description:
    **
    **    This function is shorthand for the function call
    **    set_playback_mode(DIGUY_SCENARIO_PLAYBACK_MODE_PLAY).  It is
    **    useful for resuming a paused scenario in decisions and decision
    **    beads.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    *-    - Decision
    */
   int set_playback_mode_play();

   /*l
    *b  Returns:
    **
    **    current playback mode as set by set_playback_mode() or the
    **    DI-Guy Scenario user interface
    */
   diguyScenarioPlaybackMode get_playback_mode();

   /*l
    *b  Description:
    **
    **    This function derives a dt based on an input dt (usually derived
    **    from change in realtime from previous to current frame) and the
    **    scenario's current playback mode.  The resulting dt can then be
    **    used to advance the time passed to diguyScenario::update() so that
    **    it emulates the effect of the VCR buttons in DI-Guy Scenario.
    **
    **    This function does not change the scenario's current time or
    **    playback mode.
    **
    **    Examples based on a dt_in of 0.03 seconds:
    **
    *-     - DIGUY_SCENARIO_PLAYBACK_MODE_STOP:         derived_dt = 0.0
    *-     - DIGUY_SCENARIO_PLAYBACK_MODE_PLAY:         derived_dt = 0.03
    *-     - DIGUY_SCENARIO_PLAYBACK_MODE_PLAY_REVERSE: derived_dt = -0.03
    *-     - DIGUY_SCENARIO_PLAYBACK_MODE_FF:           derived_dt = 0.12
    *-     - DIGUY_SCENARIO_PLAYBACK_MODE_FF_REVERSE:   derived_dt = -0.12
    *-     - DIGUY_SCENARIO_PLAYBACK_MODE_SS:           derived_dt = frame dt
    *-     - DIGUY_SCENARIO_PLAYBACK_MODE_SS_REVERSE:   derived_dt = - frame dt
    *-     - DIGUY_SCENARIO_PLAYBACK_MODE_REWIND:       derived_dt = - scenario t
    **
    **    Note that the playback mode should be set to
    **    DIGUY_SCENARIO_PLAYBACK_MODE_STOP after time advances in either of
    **    the single step ("SS") modes or the rewind mode.
    **
    *b  Arguments:
    **
    *a    dt_in - delta time in seconds from advancing simulation time
    */
   float derive_playback_mode_dt(float dt_in);

   /*l
    *b  Description:
    **
    **    This function resets all scenario characters, signals, variables,
    **    and all other scenario objects to their original state.  Scenario
    **    time will be set to 0.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int reset();


/*****************************************************************************/
#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    This function loads the specified scenario.  Any previously loaded
    **    scenario objects will be deleted.  To merge a scenario into the
    **    existing scenario (load without deleting existing objects), use
    **    the call merge().
    **
    **    The passed filename can be either a ".dss" file, which is a DI-Guy
    **    Scenario file, or a ".dsr" file, which is a DI-Guy Review file.
    **
    **    Once the file has been loaded an implicit reset() will occur.
    **
    *b  Arguments:
    **
    *a    filename - filename of scenario to be loaded
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int load(const char* filename);

   /*l
    *b  Description:
    **
    **    Saves the scenario into its current filename.  This filename will
    **    be the most recent of:
    **
    *-    - the filename used in a load() function call
    *-    - the filename used in a save_as() function call
    **
    **    The filename that will be used can be retrieved using the
    **    get_filename() or get_filename_without_directory() functions.
    **
    **    Once saved the "unsaved" flag (as returned by get_unsaved()) will
    **    be set to 0.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int save();

   /*l
    *b  Description:
    **
    **    Similar to save(), but new filename is specified by the filename
    **    argument.
    **
    *b  Arguments:
    **
    *a    filename - new filename of scenario
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int save_as(const char* filename);

   /*l
    *b  Description:
    **
    **    Returns the most recent of:
    **
    *-    - the filename used in a load() function call
    *-    - the filename used in a save_as() function call
    **
    *b  Returns:
    **
    **    filename of saved scenario
    **
    *b  Callable From:
    **
    *-    - C++
    */
   const char* get_filename();

   /*l
    *b  Description:
    **
    **    Similar to get_filename(), but with any leading directories
    **    removed.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   const char* get_filename_without_directory();

   /*l
    *b  Returns:
    **
    **    1 if scenario has been modified since save or load, else 0
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int get_unsaved();

   /*l
    *b  Description:
    **
    **    Manually sets the "unsaved" flag to the passed value.
    **
    *b  Arguments:
    **
    *a    unsaved - new unsaved status; 1 for unsaved, 0 for saved
    **
    *b  Callable From:
    **
    *-    - C++
    */
   void set_unsaved(int unsaved);

#endif // CPLUSPLUS_ONLY

/*****************************************************************************/
#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    This function draws all visible elements of the loaded scenario in
    **    immediate mode graphics environments (see below).  This is the
    **    equivalent of calling draw_pass1(), immediately followed by
    **    draw_pass2(), immediately followed by post_draw().
    **
    **    Note that any character graphics culling, far position rendering,
    **    etc., depend on the render camera set by the set_render_camera()
    **    function.  A render camera does not always need to be set; see
    **    set_render_camera() for more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *i  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 draw();

   /*l
    *b  Description:
    **
    **    This function, along with draw_pass2(), allows the drawing of
    **    opaque and transparent polygons to be separated.  This function
    **    draws all opaque polygons.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *i  OpenGL Version:
    **
    **    This function immediately draws the opaque scenario elements.
    **    Either this function or draw() should be called once per frame.
    */
   int draw_pass1();

   /*l
    *b  Description:
    **
    **    Same as draw_pass1(), but draws transparent scenario elements.
    **    The also_call_post_draw argument is set to 1 for backwards
    **    compatibility.
    */
   int draw_pass2(int also_call_post_draw = 1);

   /*l
    *b  Description:
    **
    **    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)
    */
   int draw_particles();

   /*l
    *b  Description:
    **
    **    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 pre_draw_cull_state_reset();

   /*l
    *b  Description:
    **
    **    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 post_draw_cull_state_save();

   void calculate_character_lods();


   /*l
    *b  Description:
    **
    **    This function draws visual elements that must be drawn after the
    **    main render has been done.
    **
    **    Note that this function is called automatically by the draw()
    **    call.  Only call this function if draw() is not called; e.g.,
    **    if draw_pass1() and draw_pass2() are used.
    **
    **    This function can be called from scene graph type renderers which
    **    typically don't need or want to have the draw() function called.
    **
    *b  Arguments:
    **
    *a    call_plugins_post_draw  - pass 1 to call plugin post_draw()
    *a                              functions
    *a    call_lua_packages_draw  - pass 1 to call lua package draw functions
    *a    call_post_draw_callback - pass 1 to invoke callbacks with callback
    *a                              id CALLBACK_ID_POST_DRAW
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int post_draw(int call_plugins_post_draw = 1,
      int call_lua_packages_draw = 1,
      int call_post_draw_callback = 1);

   /*l
    *b  Description:
    **
    **    This function sets the attachment point that to be used for
    **    graphics created by the library.
    **
    *b  Arguments:
    **
    *a    graphics_attach_ptr - this is a pointer to a group-type object;
    *a                          the specific type is dependent on graphics
    *a                          environment
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *i  OpenGL Version:
    **
    **    This function does not have any effect.
    **
    *i  Direct3D Version:
    **
    **    The passed pointer should be a LPDIRECT3DRMFRAME2.
    **
    *e     LPDIRECT3DRMFRAME2 attach_frame = get_scene_frame();
    *e     scenario->set_graphics_attach_ptr(attach_frame);
    */
   int set_graphics_attach_ptr(void* graphics_attach_ptr);

#endif // CPLUSPLUS_ONLY


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function creates a merge settings object.  This object can
    **    allow for fine control over which elements in a scenario are
    **    merged during a merge() call, and what to do if there is a
    **    collision with an existing element.
    **
    **    Once the initial settings are made based on the initial_settings
    **    argument, the settings can be fine-tuned by calling member
    **    functions of the diguyScenarioMergeSettings object.
    **
    **    Destroy the object with a call to destroy_merge_settings().
    **
    *b  Arguments:
    **
    *a    initial_settings - what the initial settings should be when
    *a                       the object is created
    **
    *i    DIGUY_MERGE_INITIAL_SETTINGS_DEFAULT
    **
    *a       scenario settings     - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       current view settings - DIGUY_MERGE_FLAG_OVERWRITE_EXISTING
    *a       character             - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       decision              - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       formation             - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       group                 - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       guide                 - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       info popup            - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       library function      - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       script                - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       sensor region         - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       signal                - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       variables             - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       camera settings       - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       face exp              - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       fog settings          - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       light settings        - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       particle system       - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       path shape            - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       scene object          - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       scene object grid     - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       sound                 - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    **
    *i    DIGUY_MERGE_INITIAL_SETTINGS_MERGE_EVERYTHING
    **
    *a       scenario settings     - DIGUY_MERGE_FLAG_OVERWRITE_EXISTING
    *a       current view settings - DIGUY_MERGE_FLAG_OVERWRITE_EXISTING
    *a       character             - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       decision              - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       formation             - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       group                 - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       guide                 - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       info popup            - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       library function      - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       script                - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       sensor region         - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       signal                - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       variables             - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       camera settings       - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       face exp              - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       fog settings          - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       light settings        - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       particle system       - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       path shape            - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       scene object          - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       scene object grid     - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       sound                 - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    **
    *i    DIGUY_MERGE_INITIAL_SETTINGS_MERGE_NOTHING
    **
    *a       scenario settings     - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       current view settings - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       character             - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       decision              - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       formation             - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       group                 - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       guide                 - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       info popup            - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       library function      - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       script                - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       sensor region         - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       signal                - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       variables             - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       camera settings       - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       face exp              - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       fog settings          - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       light settings        - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       particle system       - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       path shape            - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       scene object          - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       scene object grid     - DIGUY_MERGE_FLAG_DONT_MERGE
    *a       sound                 - DIGUY_MERGE_FLAG_DONT_MERGE
    **
    *i    DIGUY_MERGE_INITIAL_SETTINGS_DIGUY6_COMPATIBLE
    **
    *a       scenario settings     - DIGUY_MERGE_FLAG_OVERWRITE_EXISTING
    *a       current view settings - DIGUY_MERGE_FLAG_OVERWRITE_EXISTING
    *a       character             - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
    *a       decision              - DIGUY_MERGE_FLAG_KEEP_BOTH
    *a       formation             - DIGUY_MERGE_FLAG_KEEP_BOTH
    *a       group                 - DIGUY_MERGE_FLAG_KEEP_BOTH
    *a       guide                 - DIGUY_MERGE_FLAG_KEEP_BOTH
    *a       info popup            - DIGUY_MERGE_FLAG_KEEP_BOTH
    *a       library function      - DIGUY_MERGE_FLAG_KEEP_BOTH
    *a       script                - DIGUY_MERGE_FLAG_KEEP_BOTH
    *a       sensor region         - DIGUY_MERGE_FLAG_KEEP_BOTH
    *a       signal                - DIGUY_MERGE_FLAG_KEEP_BOTH
    *a       variables             - DIGUY_MERGE_FLAG_KEEP_BOTH
    *a       camera settings       - DIGUY_MERGE_FLAG_KEEP_BOTH
    *a       face exp              - DIGUY_MERGE_FLAG_KEEP_BOTH
    *a       fog settings          - DIGUY_MERGE_FLAG_KEEP_BOTH
    *a       light settings        - DIGUY_MERGE_FLAG_KEEP_BOTH
    *a       particle system       - DIGUY_MERGE_FLAG_KEEP_EXISTING_ONLY_AND_WARN
    *a       path shape            - DIGUY_MERGE_FLAG_KEEP_BOTH
    *a       scene object          - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
    *a       scene object grid     - DIGUY_MERGE_FLAG_KEEP_BOTH
    *a       sound                 - DIGUY_MERGE_FLAG_KEEP_BOTH
    **
    *b  Returns:
    **
    **    object of type diguyScenarioMergeSettings
    */
   diguyScenarioMergeSettings* create_merge_settings(diguyScenarioMergeInitialSettings initial_settings = DIGUY_MERGE_INITIAL_SETTINGS_DEFAULT);

   /*l
    *b  Description:
    **
    **    This function destroys a merge settings object created by
    **    a call to create_merge_settings().
    */
   void destroy_merge_settings(diguyScenarioMergeSettings* merge_settings);

   /*l
    *b  Description:
    **
    **    This function merges the specified scenario.  Any previously loaded
    **    scenario elements will be retained, depending on settings in
    **    the merge_settings argument.
    **
    *b  Arguments:
    **
    *a    filename       - filename of scenario to be merged
    *a    merge_settings - object that controls how elements are merged;
    *a                     pass NULL for default merge handling
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int merge(const char* filename,
      diguyScenarioMergeSettings* merge_settings = NULL);

   /*l
    *b  Description:
    **
    **    This function performs a "micro merge", allowing a scenario to
    **    merge in the contents of a text string representing a single
    **    object.
    **
    **    On example of use is for a Lua Package to contain a number of
    **    text strings representing particle systems or sounds that an agent
    **    need will need.  When needed objects in text form can be merged
    **    into the scenario using this function.
    **
    **    The DI-Guy Scenario Particle System page has a "Display Object
    **    Text" button that can display the object text of a particle system
    **    that is appropriate for use by this function.  Other object pages
    **    that have this button are Sound, Formation, and Crowd Profile.
    **
    **    Text can also be taken directly from .dss files.
    **
    **    See also the diguyCharacter::merge_object() function.
    **
    **    Note: the parser is very sensitive to tabs and formatting!
    */
   int merge_object(const char* string);

   /*l
    *b  Description:
    **
    **    This function makes the objects in the specified library available
    **    for use in the scenario.
    **
    **    Object libraries allow new content to be created in one scenario
    **    and automatically shared to other scenarios.  When including a
    **    library, objects that are already in the scenario are preserved.
    **
    **    A library with specified name must be available for inclusion.
    **    Object libraries are located in the
    **    $DIGUY/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
    **
    *b  Arguments:
    **
    *a    library_name - name of library
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int include_object_library(const char* library_name);

   /*l
    *b  Description:
    **
    **    This function is the opposite of include_object_library().
    **    Objects in the named library are made unavailable to the scenario.
    **
    *b  Arguments:
    **
    *a    library_name - name of library
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int uninclude_object_library(const char* library_name);


/*****************************************************************************/
   /******************************************************
    **
    *4  Datetime Functions
    **
    */

   /*l
    *b  Description:
    **
    **    This function will set what the current datetime will be when the
    **    scanario is reset.
    **
    **    Pass -1 for values that should be set based on current datetime.
    **
    **    Note that if set_base_datetime_default_to_now() and
    **    set_base_datetime_default_to_today() can override these values.
    */
   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);

   /*l
    *b  Description:
    **
    **    Similar to set_base_datetime(), but datetime is stored in the
    **    passed string, formatted in the passed format string.
    */
   void set_base_datetime(const char* datetime_string,
      const char* format);

   /*l
    *b  Description:
    **
    **    Retrieves the base datetime.  Pass NULL for arguments that aren't
    **    needed.
    */
   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);

   /*l
    *b  Description:
    **
    **    Setting this value to 1 will cause the time part of the datetime to
    **    be set to whatever "real" time it is when reset() is called,
    **    instead of the time stored in the base datetime as set by
    **    set_base_datetime().  For example, if it is 10:30 AM in "real time"
    **    when the scenario is reset, the current time will be set to
    **    10:30:00:000 on reset.
    **
    **    Setting this value to 0 will restore the default behavior.
    */
   void set_base_datetime_default_to_now(int to_now);

   /*l
    *b  Returns:
    **
    **    1 if the current time will be set to the "real time" on reset,
    **    0 is not
    */
   int get_base_datetime_default_to_now();

   /*l
    *b  Description:
    **
    **    Similar to set_base_datetime_default_to_now(), but for the date
    **    part of the datetime.
    */
   void set_base_datetime_default_to_today(int to_today);

   /*l
    *b  Returns:
    **
    **    1 if the current date will be set to the "real date" on reset,
    **    0 is not
    */
   int get_base_datetime_default_to_today();

   /*l
    *b  Description:
    **
    **    Allows current datetime to be explicitly set.  Note that in most
    **    cases the current datetime should be set by the base datetime plus
    **    how much time has advanced in the scenario.
    **
    **    This function can be useful if the datetime needs to be syncronized
    **    with that from another source, say, from network exercise data.
    */
   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);

   /*l
    *b  Description:
    **
    **    Similar to set_current_datetime(), but datetime is stored in the
    **    passed string, formatted in the passed format string.
    */
   void set_current_datetime(const char* datetime_string,
      const char* format);

   /*l
    *b  Description:
    **
    **    Retrieves the current datetime.  Pass NULL for arguments that
    **    aren't needed.
    */
   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);

   /*l
    *b  Description:
    **
    **    Retrieves the current datetime in string format.
    **
    *b  Arguments:
    **
    *a    format - format returned string should be in; pass NULL for default
    *a             "M/d/yyyy h:mm:ss AP" format
    */
   const char* get_current_datetime_string(const char* format);

   /*l
    *b  Description:
    **
    **    Pass 1 to specify that datetimes use UTC time, 0 to specify they
    **    are local time.
    */
   void set_datetimes_are_utc(int are_utc);

   /*l
    *b  Returns:
    **
    **    1 if datetimes use UTC time, 0 if not
    */
   int get_datetimes_are_utc();

   /*l
    *b  Description:
    **
    **    If datetimes use UTC time, this function sets the offset hours
    **    of the current time from UTC.
    */
   void set_utc_offset_hours(float utc_offset_hours);

   /*l
    *b  Returns:
    **
    **    offset in hours of datetimes from UTC
    */
   float get_utc_offset_hours();

   /*l
    *b  Description:
    **
    **    Causes the number of UTC offset hours to be derived from local
    **    system settings -- an alternative to calling set_utc_offset_hours()
    */
   void set_use_local_tz_utc_offset_hours(int use_local_tz);

   int get_use_local_tz_utc_offset_hours();

   /*l
    *b  Description:
    **
    **    Sets the rate at which datetime can advance. See diguyDatetimeAdvanceMethod
    **    for details.
    */
   void set_current_datetime_advance_method(diguyDatetimeAdvanceMethod advance_method);

   diguyDatetimeAdvanceMethod get_current_datetime_advance_method();

   /*l
    **    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.
    */
   void set_current_datetime_advance_factor(float advance_factor);

   float get_current_datetime_advance_factor();

   /*l
    *b  Description:
    **
    **    Returns current exercise's datetime values.
    */
   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);


   /******************************************************
    **
    *4  Simple Time Functions
    **
    */

   /*l
    *b  Description:
    **
    **    This function sets the time of day which corresponds to scenario
    **    tin.  It is a wall-clock time, and has no date content.
    **
    **    Note that if more detailed time and date information is needed
    **    refer to the "datetime" functions.
    **
    *b  Arguments:
    **
    *a    t - number of seconds after midnight; zero means
    *a        midnight; 86399.0 means 11:59:59 pm
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int set_tin_time_of_day(float t);

   /*l
    *b  Description:
    **
    **    This function returns what time of day corresponds to scenario tin.
    **    It is a wall-clock time, and has no date content.
    **
    **    See set_tin_time_of_day().
    **
    **    Note that if more detailed time and date information is needed
    **    refer to the "datetime" functions.
    **
    *b  Returns:
    **
    **    number of seconds after midnight
    */
   float get_tin_time_of_day();

   /*l
    *b  Description:
    **
    **    This function returns what the simulated time of day is right now.
    **    It is computed by adding (scenario t - tin) to the value passed to
    **    set_tin_time_of_day();
    **
    **    See set_tin_time_of_day().
    **
    **    Note that if more detailed time and date information is needed
    **    refer to the "datetime" functions.
    **
    *b  Returns:
    **
    **    number of seconds after midnight (simulated time of day)
    */
   float get_time_of_day();


/*****************************************************************************/
#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    This function adds an appearance with the given name to the list of
    **    available appearances.  If an appearance with the given name
    **    already exists the operation will fail and a message will be
    **    printed at debug level to the output log.
    **
    **    Internal copies are made of the passed strings.
    **
    *b  Arguments:
    **
    *a    appearance      - name of the appearance
    *a    equipment_list  - NULL-terminated list of equipment that
    *a                      makes up the appearance
    *a    character_types - NULL-terminated list of character types
    *a                      that this appearance will be available to
    *a    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.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int add_appearance(const char* appearance,
      char** equipment_list,
      char** character_types,
      const char* actor);

   /*l
    *b  Description:
    **
    **    This function is similar to add_appearance(), but adds
    **    equipment_list shapes to an existing appearance.
    **
    **    The character types that the new appearance will be available to
    **    will match that of the specified existing appearance.
    **
    *b  Arguments:
    **
    *a    appearance          - name of the new appearance
    *a    existing_appearance - name of the existing appearance on which to
    *a                          base new appearance
    *a    equipment_list      - NULL-terminated list of equipment to add to
    **                          the existing appearance
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int add_appearance_based_on_existing_appearance(const char* appearance,
      const char* existing_appearance,
      char** equipment_list);

   /*l
    *b  Description:
    **
    **    This function removes an appearance with the given name
    **    from the list of available appearances.  If an appearance with
    **    the given name does not exist the operation will fail and
    **    a message will be printed at debug level to the output log.
    **
    *b  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.
    **
    *b  Arguments:
    **
    *a    appearance      - name of the appearance
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_appearance(const char* appearance);

#endif // CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    This function returns the number of character types associated with
    **    the given appearance, if any.
    **
    *b  Arguments:
    **
    *a    appearance      - name of the appearance
    **
    *b  Returns:
    **
    **    the number of character types, or 0
    */
   int get_num_character_types_with_appearance(const char* appearance_name);

   /*l
    *b  Description:
    **
    **    This function returns one of the character types associated with
    **    the appearance, if any exists
    **
    *b  Arguments:
    **
    *a    appearance      - name of the appearance
    *a    index           - which character type of the set to return
    **
    *b  Returns:
    **
    **    a character type name on success, "none" on failure
    */
   const char*get_character_type_from_appearance(const char* appearance_name, int index = 0);


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    Gets the number of configured hand item classes.
    **
    *b  Returns:
    **
    **    The number of configured hand item classes.
    */
   int get_num_hand_item_classes() const;

   /*l
    *b  Description:
    **
    **    Gets the name of the hand item class at the given index.
    **
    *b  Arguments:
    **
    *a    index - index of the hand item class to return the name of
    **
    *b  Returns:
    **
    **    Name of hand item class on success, "none" on failure
    */
   const char* get_hand_item_class_at_index( int index ) const;

   /*l
    *b  Description:
    **
    **    Gets the number of character types a given hand item class is configured to be available to.
    **
    *b  Arguments:
    **
    *a    item_class_name - name of the item class to get number of character types for
    **
    *b  Returns:
    **
    **    Number of character types the given item class is configured to be available to.
    */
   int get_item_class_num_character_types( const char* item_class_name ) const;

   /*l
    *b  Description:
    **
    **    Gets the character types configured for availability with the given hand item class at the given index.
    **
    *b  Arguments:
    **
    *a    item_class_name - name of the item class to get the available character types for
    *a    index - index of the character type for the given item class to get the name of
    **
    *b  Returns:
    **
    **    The name of the character type configured for availability with the given item class at the given index.
    */
   const char* get_item_class_character_type_at_index( const char* item_class_name, int index ) const;

   /*l
    *b  Description:
    **
    **    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.
    **
    *b  Arguments:
    **
    *a    char_type_name      - name of the char type
    *a    appearance_name     - optional appearance name, which might yield
    *a                      different results
    **
    *b  Returns:
    **
    **    Name of hand item class on success, "none" on failure
    */
   const char* get_hand_item_class( const char* char_type_name, const char* appearance_name = nullptr );

   /*l
    *b  Description:
    **
    **    Gets the number of hand items in a particular hand item class.
    **
    *b  Arguments:
    **
    *a    hand_item_class     - name of hand item class
    **
    *b  Returns:
    **
    **    Number of hand items in class
    */
   int get_num_hand_items_in_class( const char*hand_item_class );

   /*l
    *b  Description:
    **
    **    Gets the name of a hand item within the set associated with
    **      a hand item class.
    **
    *b  Arguments:
    **
    *a    hand_item_class     - name of hand item class
    *a    index            - index within set
    **
    *b  Returns:
    **
    **    Name of hand item, or "none"
    */
   const char*get_hand_item_from_class(const char*hand_item_class, int index);

/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function preloads all base motions and the default
    **    appearance for the specified character type.
    **
    **    This can be done during initialization to preload characters that
    **    will be needed later in a scenario, to avoid a hitch in frame rate
    **    when the characters are loaded.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int preload_character_type(const char* character_type);

   /*l
    *b  Description:
    **
    **    This function preloads all geometry for the specified appearance.
    **    This can be done during initialization to preload geometry that
    **    will be needed later in a scenario, to avoid a hitch in frame rate
    **    when the geometry is loaded.
    **
    *b  Arguments:
    **
    *a    appearance - name of the appearance whose geometry is to be
    *a                 preloaded
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int preload_appearance(const char* appearance);

   /*l
    *b  Description:
    **
    **    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.
    **
    *b  Arguments:
    **
    *a    appearance - name of the appearance, or head appearance whose geometry is to be
    *a                 loaded
    *a    character_type - name of the character type, used to derived hand item to load
    *a    load_status  - pointer to the internal load data. monitor this to find out when
    *a                   the object has finished loading and avoid polling this function
    **
    *b  Returns:
    **
    **    0 if successfully queued, 1 if already loaded, 2 if in the process of being loaded, -1 on failure
    */
   int async_load_appearance(const char* appearance, const char* character_type = "soldier_17", const bool ** load_status = NULL);
   int async_load_hand_item(const char* appearance_name, const bool** load_status = NULL);

   /*l
    *b  Description:
    **
    **    This function preloads all motions for the specified gesture
    **    for the specified character type.
    **
    **    This can be done during initialization to preload gestures that
    **    will be needed later in a scenario, to avoid a hitch in frame rate
    **    when the motions are loaded.
    **
    *b  Arguments:
    **
    *a    character_type      - character's type
    *a    gesture_name        - name of the gesture to preload
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int preload_gesture(const char* character_type, const char* gesture_name);


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function enables character culling.
    **
    **    This function works only in the OpenGL version when a valid render
    **    camera is set.
    */
   void set_character_culling_enabled(int character_culling);

   /*l
    *b  Description:
    **
    **    This function gets the state of character culling.
    **
    **    This function works only in the OpenGL version when a valid render
    **    camera is set.
    **
    *b  Returns:
    **
    **       1 if enabled, 0 if disabled.
    */
   int get_character_culling_enabled();

   /*l
    *b  Description:
    **
    **    This function enables scene object culling.
    **
    **    This function works only in the OpenGL version when a
    **    valid render camera is set.
    */
   void set_scene_object_culling_enabled(int object_culling);

   /*l
    *b  Description:
    **
    **    This function get the state of scene object culling.
    **
    **    This function works only in the OpenGL version when a
    **    valid render camera is set.
    **
    *b  Returns:
    **
    **     1 if enabled, 0 if disabled
    */
   int  get_scene_object_culling_enabled();

   /*l
    *b  Description:
    **
    **    This function enables scene object sub object culling.
    **
    **    This function works only in the OpenGL version when a
    **    valid render camera is set.
    */
   void set_scene_object_sub_culling_enabled(int object_culling);

   /*l
    *b  Description:
    **
    **    This function get the state of scene object sub culling.
    **
    **    This function works only in the OpenGL version when a
    **    valid render camera is set.
    **
    *b  Returns:
    **
    **    1 if enabled, 0 if disabled
    */
   int  get_scene_object_sub_culling_enabled();

   /*l
    *b  Description:
    **
    **    This function enables visualizing a character's bounding
    **    volume.
    **
    **    This function works only in the OpenGL version when a
    **    valid render camera is set.
    */
   void set_character_visualize_bounds_enabled(int visualize_bounds);

   /*l
    *b  Description:
    **
    **    This function get the state of character bounding volume
    **    visualization.
    **
    **    This function works only in the OpenGL version when a
    **    valid render camera is set.
    **
    *b  Returns:
    **
    **      1 if enabled, 0 if disabled
    */
   int  get_character_visualize_bounds_enabled();

   /*l
    *b  Description:
    **
    **    This function enables visualizing a scene object's bounding
    **    volume.
    **
    **    This function works only in the OpenGL version when a
    **    valid render camera is set.
    */
   void set_scene_object_visualize_bounds_enabled(int val);

   /*l
    *b  Description:
    **
    **    This function gets the state of scene objects bounding volume
    **    visualization.
    **
    **    This function works only in the OpenGL version when a
    **    valid render camera is set.
    **
    *b  Returns:
    **
    **      1 if enabled, 0 if disabled
    */
   int  get_scene_object_visualize_bounds_enabled();


/*****************************************************************************/
   /*l
    *b  Returns:
    **
    **    number of available character types
    */
   int get_num_character_types();

   /*l
    *b  Returns:
    **
    **    the string identifying the character type at the given index
    **
    *b  Arguments:
    **
    *a    index - index of the character type; indices start at 0
    */
   const char* get_character_type_at_index(int index);

   /*l
    *b  Returns:
    **
    **    abbreviation of the given character type, when a shorter
    **    identifier is needed
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    */
   const char* get_character_type_abbreviation(const char* character_type);

   /*l
    *b  Description:
    **
    **    This function returns the version at which the specified
    **    character type was deprecated.
    **
    **    If the character type has not been deprecated, the empty string
    **    ("") is returned.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    **
    *b  Returns:
    **
    **    version at which character became deprecated; empty string ("")
    **    if it hasn't been
    **
    *b  C++ Example:
    **
    *e     const char* version = scenario->get_character_type_deprecated_at_version();
    *e     if (strlen(version) > 0)
    *e     {
    *e        // do something
    *e     }
    */
   const char* get_character_type_deprecated_at_version(const char* character_type);

   /*l
    *b  Description:
    **
    **    This function returns the suggested character type(s) that are
    **    recommended for deprecated character types.
    **
    **    If the character type has not been deprecated, the empty string
    **    ("") is returned.
    **
    **    If there is more than one suggested alternative, they will be
    **    separated by spaces.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    **
    *b  Returns:
    **
    **    suggested replacement character type(s)
    **
    *b  C++ Example:
    **
    *e     const char* alternatives = scenario->get_character_type_deprecated_suggested_alternatives();
    *e     if (strlen(version) > 0)
    *e     {
    *e        // do something
    *e     }
    */
   const char* get_character_type_deprecated_suggested_alternatives(const char* character_type);

   /*l
    *b  Description:
    **
    **    As the number of character types DI-Guy provides has grown,
    **    newer character types tend to be better than older ones.
    **    This can be because of a greater selection of actions, better
    **    quality motions, and other factors.
    **
    **    This function returns a value representing a qualitative "bias"
    **    of this character they relative to other character types.
    **    The higher the bias, the more recommended the character type is.
    **    A bias of 1 means strongly not recommended, 5 means average,
    **    10 means highly recommended.
    **
    *b  Returns:
    **
    **    quality bias, a unitless value from 1 to 10
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    */
   int get_character_type_quality_bias(const char* character_type);

   /*l
    *b  Description:
    **
    **    This function returns the type map of the specified character
    **    type.  See the documentation for diguyCharacterTypeMap for what
    **    this information means.
    **
    **    Only the character type fields will have useful information; the
    **    appearance fields will contain default wildcard values.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    **
    *b  Returns:
    **
    **    pointer to type diguyCharacterTypeMap; will never be NULL
    */
   diguyCharacterTypeMap* get_character_type_map(const char* character_type);

   /*l
    *b  Returns:
    **
    **    default appearance of the specified character type
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    */
   const char* get_character_type_default_appearance(const char* character_type);

   /*l
    *b  Returns:
    **
    **    default skinned appearance of the specified character type
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    */
   const char* get_character_type_default_skinned_appearance(const char* character_type);

   /*l
    *b  Returns:
    **
    **    number of available appearances for the given character type
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    */
   int get_character_type_num_appearances(const char* character_type);

   /*l
    *b  Returns:
    **
    **    the string identifying the appearance at the given index for
    **    the specified character type
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    *a    index          - index of the appearance; indices start at 0
    */
   const char* get_character_type_appearance_at_index(const char* character_type,
      int index);

   /*l
    *b  Description:
    **
    **    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.
    **
    *b  Returns:
    **
    **    quality bias, a unitless value from 1 to 10
    **
    *b  Arguments:
    **
    *a    appearance - appearance name
    */
   int get_appearance_quality_bias(const char* appearance);

   /*l
    *b  Arguments:
    **
    *a    character_type  - a string indicating the character type
    *a    base_appearance - a string indicating the basic character appearance
    *a    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
    *b  Returns:
    **
    **    The number of available supplementary appearances of given type
    */
   int get_num_appearances_of_appearance_type( const char* character_type, const char* base_appearance,
      diguyCharacterAppearanceTypes appearance_type );

   /*l
    *b  Returns:
    **
    **    The name of the supplementary appearance (body, head, expressive head, hand item) or NULL
    **
    *b  Arguments:
    **
    *a    character_type  - a string indicating the character type
    *a    base_appearance - a string indicating the basic character appearance
    *a    appearance_type - a value indicating the type of appearance of concern
    *a    index - a value indicating the type of supplementary appearance of concern
    **
    */
   const char* get_appearance_name_at_index( const char* character_type, const char* base_appearance,
      diguyCharacterAppearanceTypes appearance_type, int index );

   int get_num_patches_for_appearance( const char* base_appearance, diguyTextureUniformPatchLocations patch_location );

   int get_appearance_default_patch_index( const char* base_appearance,
      diguyTextureUniformPatchLocations patch_location ) const;

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

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

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

   int get_num_actors();
   const char* get_actor_name_at_index( int index );

   const char* get_actor_name( const char* base_appearance );

   int get_num_equipment_for_actor( const char* actor_name );

   const char* get_equipment_name_for_actor( const char* actor_name, int index );

   const char* get_equipment_type_for_actor( const char* actor_name, int index );

   int get_num_equipment_for_appearance( const char* base_appearance );

   const char* get_equipment_name_for_appearance( const char* base_appearance, int index );

   const char* get_equipment_type_for_appearance( const char* base_appearance, int index );

    /*l
    *b  Returns:
    **
    **    number of available actions for the given character type
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by get_character_type_at_index(), for example
    */
   int get_character_type_num_actions( const char* character_type );

   /*l
    *b  Returns:
    **
    **    the string identifying the action at the given index for the specified character type
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by get_character_type_at_index(), for example
    *a    index          - index of the action name; indices start at 0
    */
   const char* get_character_type_action_at_index( const char* character_type, int index );

   /*l
    *b  Returns:
    **
    **    the display name for the specified action for the specified character type
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by get_character_type_at_index(), for example
    *a    action_name    - the action to query
    */
   const char* get_character_type_action_display_name( const char* character_type, const char* action_name );

   /*l
    *b  Returns:
    **
    **    the average speed of the specified action for the specified character type
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by get_character_type_at_index(), for example
    *a    action_name    - the action to query
    */
   float get_character_type_action_speed( const char* character_type, const char* action_name );

   /*l
    *b  Returns:
    **
    **    the duration of one rep of the specified action for the specified character type
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by get_character_type_at_index(), for example
    *a    action_name    - the action to query
    */
   float get_character_type_action_duration( const char* character_type, const char* action_name );

   /*l
    *b  Returns:
    **
    **    the distance covered by one rep of the specified action for the specified character type
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by get_character_type_at_index(), for example
    *a    action_name    - the action to query
    */
   float get_character_type_action_distance( const char* character_type, const char* action_name );

   /*l
    *b  Returns:
    **
    **    the displacement covered by one rep of the specified action for the specified character type
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by get_character_type_at_index(), for example
    *a    action_name    - the action to query
    */
   int get_character_type_action_displacement( const char* character_type, const char* action_name,
      float* x, float* y, float* z );

   /*l
    *b  Description:
    **
    **    Looks up the transition used between the given two actions, and returns information about the transition.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by get_character_type_at_index(), for example
    *a    from_action_name  - the starting action to get transition info for
    *a    to_action_name    - the ending action to get transition info for.
    **
    *b  Returns:
    **
    **    true on success, false on failure
    **
    */
   bool get_character_type_transition_info( const char* character_type, const char* from_action_name,
      const char* to_action_name, diguyTransitionInfo& info );

   /*l
    *b  Returns:
    **
    **    the diguyMotionDirection identifying the direction of travel of the specified action for the specified character type
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by get_character_type_at_index(), for example
    *a    action_name    - the action to query
    */
   diguyMotionDirection get_character_type_action_direction( const char* character_type, const char* action_name );

   /*l
    *b  Returns:
    **
    **    the facing angle at the start of each repetition of the specified action for the specified character type, in degrees
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by get_character_type_at_index(), for example
    *a    action_name    - the action to query
    */
   float get_character_type_action_facing_angle_in( const char* character_type, const char* action_name );

   /*l
    *b  Returns:
    **
    **    the facing angle at the end of each repetition of the specified action for the specified character type, in degrees
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by get_character_type_at_index(), for example
    *a    action_name    - the action to query
    */
   float get_character_type_action_facing_angle_out( const char* character_type, const char* action_name );

   /*l
    *b  Returns:
    **
    **    the number of gestures available to the specified character type
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by get_character_type_at_index(), for example;
    *a                     pass "all" to get all gestures available, regardless of character type
    */
   int get_character_type_num_gestures( const char* character_type );

   /*l
    *b  Returns:
    **
    **    the name of the gesture available to the specified character type at the specified index
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by get_character_type_at_index(), for example;
    *a                     pass "all" to get all gestures available, regardless of character type
    *a    index          - index of the gesture; indices start at 0
    */
   const char* get_character_type_gesture_at_index( const char* character_type, int index );

   /*l
    *b  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
    */
   diguyGestureMetadata* get_character_type_gesture_meta_data_at_index( const char* character_type, int index );


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function creates a new character and returns a
    **    pointer to it.
    **
    **    The function preload_character_type() should be called
    **    at the beginning of a scenario in which this call will
    **    be made to avoid a hitch in frame rate.
    **
    **    See also retrieve_character_from_recycle_bin() for a
    **    potentially faster way of creating a character.
    **
    *b  Arguments:
    **
    *a    name                - name of the new character
    *a    character_type      - character's type
    *a    appearance          - base appearance of character; pass
    *a                          NULL to use default appearance
    *a    hand_item           - hand item appearance; pass
    *a                          NULL to use default appearance
    **
    *b  Returns:
    **
    **    pointer of type diguyCharacter; NULL if creation failed
    */
   diguyCharacter* create_character(const char* name,
      const char* character_type,
      const char* appearance = NULL,
      const char* head_appearance = NULL,
      const char* hand_item = NULL);

   /*l
    *b  Description:
    **
    **    This function is very similar to create_character(), but the
    **    character created is temporary.
    **
    **    Temporary characters will be destroyed automatically when the
    **    scenario is reset, and are not saved in .dss files.  They are
    **    commonly used for projectiles, effects, and other objects that can
    **    come and go multiple times.
    **
    **    Temporary characters can be destroyed before scenario reset by
    **    calling destroy_character(), and can be sent to the character
    **    recycle bin by calling send_character_to_recycle_bin().
    **
    *b  Arguments:
    **
    *a    name                - name of the new character
    *a    character_type      - character's type
    *a    appearance          - base appearance of character; pass
    *a                          NULL to use default appearance
    **
    *b  Returns:
    **
    **    pointer of type diguyCharacter; NULL if creation failed
    */
   diguyCharacter* create_temporary_character(const char* name,
      const char* character_type,
      const char* appearance = NULL);

   /*l
    *b  Description:
    **
    **    This function destroys a character.
    **
    **    If a character of the same character type and appearance may be
    **    needed later in the scenario, consider using
    **    send_character_to_recycle_bin() instead.  Characters can be
    **    retrieved from the recycle bin more quickly than creating them
    **    "from scratch" with create_character().
    **
    *b  Arguments:
    **
    *a    character - pointer to a diguyCharacter
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  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 destroy_character(diguyCharacter* character);

   int destroy_character_later(diguyCharacter*)
;
   /*l
    *b  Description
    **
    **    This function is an alternative way of removing a character from
    **    the scenario.  When a character is recycled it is removed from the
    **    scenario's list of active characters, but the memory associated
    **    with it is not freed.  Instead, the character is placed in a
    **    "character recycle bin" from which it may be later retrieved with a
    **    call to retrieve_character_from_recycle_bin().
    **
    **    For an application that is creating and destroying a lot of
    **    characters with the same character types and appearances, this can
    **    avoid performance hiccups that happen when memory is allocated for
    **    new characters.
    **
    **    If it is known ahead of time what types and appearances of
    **    characters will be needed in the future, the recycle bin can be
    **    "pre-stocked" at scenario load time by first creating and then
    **    recycling a large number of characters all at once.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int send_character_to_recycle_bin(diguyCharacter* character);

   /*l
    *b  Description
    **
    **    This function is an alternative way of creating a character.  The
    **    character recycle bin is checked for a recycled character whose
    **    character type and appearance match that requested by this call.
    **    Characters are sent to the recycle bin by a call to
    **    send_character_to_recycle_bin().
    **
    **    If a match is found the recycled character will be removed from
    **    the recycle bin, given the passed name, and placed in the
    **    scenario's list of characters, for the most part just as if the
    **    character had been created by a call to create_character().  Some
    **    things such as position, current action, etc., may need to be
    **    immediately set.
    **
    **    If a match is not found, this function returns NULL and a call to
    **    create_character() must be made instead.
    **
    *b  Arguments:
    **
    *a    name           - new name for the character retrieved from bin
    *a    character_type - the character type to retrieve from the bin
    *a    appearance     - the appearance to retrieve from the bin, pass NULL
    *a                     or "default" to retrieve the default appearance
    *a    make_character_temporary - pass 1 to make character temporary,
    *a                               0 to leave permanent
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   diguyCharacter* retrieve_character_from_recycle_bin(const char* name,
      const char* character_type,
      const char* appearance,
      int make_character_temporary = 0);

   /*l
    *b  Returns:
    **
    **    number of characters in the scenario
    */
   int get_num_characters();

   /*l
    *b  Returns:
    **
    **    pointer of type diguyCharacter; NULL if no character at the
    **    specified index
    **
    *b  Arguments:
    **
    *a    index - index of the character; indices start at 0
    */
   diguyCharacter* get_character_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified character.
    **
    *b  Arguments:
    **
    *a    name    - name of character to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyCharacter; NULL if not found
    */
   diguyCharacter* find_character(const char* name);

   /*l
    *b  Description:
    **
    **    This function changes the scenario camera's position
    **    and fix point so it will be looking at the specified
    **    character.
    */
   void look_at_character(diguyCharacter* character);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the target character
    **    of an event bead.
    **
    *b  Returns:
    **
    **    pointer of type diguyCharacter; NULL if no current character
    */
   diguyCharacter* this_character();

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the current event bead.
    **
    *b  Returns:
    **
    **    pointer of type diguyCharacterPathEvent; NULL if no current event
    **    bead
    */
   diguyCharacterPathEvent* this_event_bead();


/*****************************************************************************/
   /*l
    *b  Returns:
    **
    **    number of path shapes in the scenario
    */
   int get_num_path_shapes();

   /*l
    *b  Returns:
    **
    **    pointer of type diguyPathShape; NULL if no
    **    path shape at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the path shape; indices start at 0
    */
   diguyPathShape* get_path_shape_at_index(int index);

   /*l
    *b  Returns:
    **
    **    pointer of type diguyPathShape; NULL if no
    **    path shape at the specified index
    */
   diguyPathShape* get_current_path_shape();

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified path shape.
    **
    *b  Arguments:
    **
    *a    name - name of path shape to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyPathShape; NULL if not found
    */
   diguyPathShape* find_path_shape(const char* name);

   /*l
    *b  Description:
    **
    **    This function creates a new path shape and returns a
    **    pointer to it.
    **
    *b  Arguments:
    **
    *a    name - name of the new path shape
    **
    *b  Returns:
    **
    **    pointer of type diguyPathShape; NULL if creation failed
    */
   diguyPathShape* create_path_shape(const char* name);

   /*l
    *b  Description:
    **
    **    This function creates a new path shape based on an
    **    existing path shape and returns a pointer to it.
    **
    *b  Arguments:
    **
    *a    existing_path_shape - pointer to diguyPathShape to be copied
    *a    name                - name of the new path shape
    **
    *b  Returns:
    **
    **    pointer of type diguyPathShape; NULL if creation failed
    */
   diguyPathShape* copy_path_shape(diguyPathShape* existing_path_shape,
      const char* name);

   /*l
    *b  Description:
    **
    **    This function destroys a path shape.
    **
    *b  Arguments:
    **
    *a    path_shape - pointer to a diguyPathShape
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int destroy_path_shape(diguyPathShape* path_shape);


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function creates a new waypoint that can be used for creating
    **    new paths and path shapes.
    **
    **    The returned pointer must be destroyed using destroy_waypoint().
    **    The scenario keeps no record of waypoints created with this
    **    function.
    **
    **    The weights of the waypoint control how long the "control handles"
    **    of the waypoint are, in meters.  The longer the control handle,
    **    the more the path will be stretched in the direction of the
    **    waypoint's orientation.
    **
    **  Unless otherwise specified, callable from:
    **
    *-    - C++
    *-    - Script
    **
    *b  Arguments:
    **
    *a    tx, ty, tz - position in meters from the origin
    *a    rz, rx, ry - orientations in degrees counter-clockwise
    *a                 from the positive X axis
    *a    weight_in  - how much influence this waypoint exerts
    *a                 over the path curve entering this waypoint
    *a    weight_out - how much influence this waypoint exerts
    *a                 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.
    **
    *b  Returns:
    **
    **    pointer to type diguyWaypoint
    */
   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);

   /*l
    *b  Description:
    **
    **    This function destroys a waypoint created by create_waypoint().
    **    Path shapes created using this waypoint will not be affected;
    **    they make internal copies of the waypoints that are used to
    **    create them.
    **
    **    Do *not* call this function on waypoints not created by
    **    create_waypoint()!  e.g., a waypoint returned by a call to
    **    diguyCharacterPath::get_waypoint_at_index().
    **
    *b  Arguments:
    **
    *a    waypoint - waypoint to destroy
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int destroy_waypoint(diguyWaypoint* waypoint);


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function searches DI-Guy's available character types and
    **    appearances for the closest match to the specified fields and
    **    values.  See the documentation for diguyCharacterTypeMap for
    **    information on what fields are available, and what values they
    **    may take.
    **
    *b  Arguments:
    **
    *a    field1                 - field in type map to check
    *a    field1_value           - value to check for
    *a    field1_alternate_value - acceptable alternate value
    **
    **    (Arguments for fields 2 through 8 are the same.)
    **
    *b  Returns:
    **
    **    pointer to type diguyCharacterTypeMap
    */
   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);

   /*l
    *b  Description:
    **
    **    Same as above, but fields to check are specified by string name
    **    instead of enumeration value.
    */
   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);

   /*l
    *b  Description:
    **    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.
    */
   int get_num_matching_type_maps( const diguyCharacterTypeMapFieldValues* field_values, const char* character_type = NULL,
      const diguyCharacterTypeMapFieldValues* alternate_values = NULL );

   /*l
    *b  Description:
    **
    **    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* get_matching_type_map_at_index( int index );

   /*l
    *b  Description:
    **
    **    Same as above, but field values to match against are specified
    **    by the given type map id.  No alternate values can be provided,
    **    though wildcards can be used by putting a "*" in for a field.
    */
   diguyCharacterTypeMap* get_nearest_character_type_map_id_match(const char* type_map_id);

   /*l
    *b  Description:
    **
    **    This function returns the total number of type map entries that
    **    are in DI-Guy.  It is against these entries that matches will be
    **    made.
    **
    **    This function, along with get_character_type_map_entry_at_index(),
    **    enables all type map information to be queried.
    **
    *b  Returns:
    **
    **    number of total type map entries against which matches will be
    **    made
    */
   int get_num_character_type_map_entries();

   /*l
    *b  Returns:
    **
    **    type map entry at specified index; see
    **    get_num_character_type_map_entries()
    */
   diguyCharacterTypeMap* get_character_type_map_entry_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns the total number of values that may
    **    be specified or returned in the character class field.
    **
    **    This function, along with get_type_map_character_class_at_index(),
    **    enables all available character classes to be queried.
    **
    *b  Returns:
    **
    **    number of character classes
    */
   int get_num_type_map_character_classes();

   /*l
    *b  Returns:
    **
    **    character class field value at specified index; see
    **    get_num_type_map_character_classes()
    */
   const char* get_type_map_character_class_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns the total number of values that may
    **    be specified or returned in the category field of a type
    **    map with the given character class.
    **
    **    This function, along with get_type_map_category_at_index(),
    **    enables all available categories available to each character
    **    class to be queried.
    **
    *b  Returns:
    **
    **    number of categories
    */
   int get_num_type_map_categories(const char* character_class);

   /*l
    *b  Returns:
    **
    **    category field value at specified index; see
    **    get_num_type_map_categories()
    */
   const char* get_type_map_category_at_index(const char* character_class,
      int index);

   /*l
    *b  Description:
    **
    **    This function returns the total number of values that may
    **    be specified or returned in the subcategory field of a type
    **    map with the given character class and category.
    **
    **    This function, along with get_type_map_subcategory_at_index(),
    **    enables all available subcategories available to each character
    **    class and category to be queried.
    **
    *b  Returns:
    **
    **    number of subcategories
    */
   int get_num_type_map_subcategories(const char* character_class,
      const char* category);

   /*l
    *b  Returns:
    **
    **    subcategory field value at specified index; see
    **    get_num_type_map_subcategories()
    */
   const char* get_type_map_subcategory_at_index(const char* character_class,
      const char* category,
      int index);


/*****************************************************************************/
   /*l
    *b  Returns:
    **
    **    number of signals in the scenario
    */
   int get_num_signals();

   /*l
    *b  Returns:
    **
    **    pointer of type diguySignal; NULL if no
    **    signal at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the signal; indices start at 0
    */
   diguySignal* get_signal_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified signal.
    **
    *b  Arguments:
    **
    *a    name    - name of signal to be found
    **
    *b  Returns:
    **
    **    pointer of type diguySignal; NULL if not found
    */
   diguySignal* find_signal(const char* name);

   /*l
    *b  Description:
    **
    **    This function creates a new signal and returns a
    **    pointer to it.
    **
    *b  Arguments:
    **
    *a    name - name of the new signal
    **
    *b  Returns:
    **
    **    pointer of type diguySignal
    */
   diguySignal* create_signal(const char* name);

   /*l
    *b  Description:
    **
    **    This function destroys a signal.
    **
    *b  Arguments:
    **
    *a    signal - pointer to a diguySignal
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int destroy_signal(diguySignal* signal);

   /*l
    *b  Description:
    **
    **    This function resets all signals in the scenario.
    */
   void reset_signals();


   /*l
    *b  Description:
    **
    **    This function hides all signals in the signal palette.
    **
    *b  Arguments:
    **
    *a    filter - optional filter, will only hide signals tagged with
    *a             info_text equaling filter
    */
   int signal_palette_hide_all(const char* filter = NULL);

   /*l
    *b  Description:
    **
    **    This function shows all signals in the signal palette.
    **
    *b  Arguments:
    **
    *a    filter - optional filter, will only show signals tagged with
    *a             info_text filter
    */
   int signal_palette_show_all(const char* filter = NULL);


/*****************************************************************************/
   /*l
    *b  Returns:
    **
    **    number of sounds in the scenario
    */
   int get_num_sounds();

   /*l
    *b  Returns:
    **
    **    pointer of type diguySound; NULL if no sound at the specified
    **    index
    **
    *b  Arguments:
    **
    *a    index - index of the sound; indices start at 0
    */
   diguySound* get_sound_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified sound.
    **
    *b  Arguments:
    **
    *a    name    - name of sound to be found
    **
    *b  Returns:
    **
    **    pointer of type diguySound; NULL if not found
    */
   diguySound* find_sound(const char* name);

   /*l
    *b  Description:
    **
    **    This function creates a new sound and returns a pointer to it.
    **
    **    Note that sounds are not played directly.  Instead they are used as
    **    templates for sound instances.  See diguyCharacter::play_sound()
    **    and diguyCharacter::create_sound_instance().
    **
    *b  Arguments:
    **
    *a    name             - name of the new sound
    *a    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.
    **
    *b  Returns:
    **
    **    pointer of type diguySound
    */
   diguySound* create_sound(const char* name,
      const char* sound_filename = NULL);

   /*l
    *b  Description:
    **
    **    This function destroys a sound.
    **
    *b  Arguments:
    **
    *a    sound - pointer to diguySound to be destroyed
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int destroy_sound(diguySound* sound);

   /*l
    *b  Description:
    **
    **    This function preloads data for the sound.
    **
    *b  Arguments:
    **
    *a    sound - pointer to diguySound
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int preload_sound(diguySound* sound);

   /*l
    **
    *b  Description:
    **
    **    This function stops all sounds playing within the scenario.
    **
    *b  Arguments:
    **
    *a    rampdown_time - how long to allow the sounds to fade out
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int stop_all_sounds(float rampdown_time = 0.0f);

   /*l
    **
    *b  Description:
    **
    **    This function plays a non looping sound.
    **
    *b  Arguments:
    **
    *a    name       - name of the sound
    *a    x, y, z    - location in the world the sound comes from
    *a    gain       - a volume multiplier
    *a    save_event - if review data should record the creation of this
    *a                 sound
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int play_3d_sound(const char* name,
      float x, float y, float z,
      float gain,
      int save_event);


/*****************************************************************************/
   /*l
    *b  Returns:
    **
    **    number of groups in the scenario
    */
   int get_num_groups();

   /*l
    *b  Returns:
    **
    **    pointer of type diguyCharacterGroup; NULL if no
    **    group at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the group; indices start at 0
    */
   diguyCharacterGroup* get_group_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified group.
    **
    *b  Arguments:
    **
    *a    name - name of group to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyCharacterGroup; NULL if not found
    */
   diguyCharacterGroup* find_group(const char* name);

   /*l
    *b  Description:
    **
    **    This function creates a new group and returns a
    **    pointer to it.
    **
    *b  Arguments:
    **
    *a    name - name of the new group
    **
    *b  Returns:
    **
    **    pointer of type diguyCharacterGroup
    */
   diguyCharacterGroup* create_group(const char* name);


   /*l
    *b  Description:
    **
    **    This function finds the group with the given name or
    **    creates it if it doesn't exist.
    **
    *b  Arguments:
    **
    *a    name - name of the group to find or create
    **
    *b  Returns:
    **
    **    pointer of type diguyGroup; should never be NULL
    */
   diguyCharacterGroup* find_or_create_group(const char* name);


   /*l
    *b  Description:
    **
    **    This function destroys a group.
    **
    *b  Arguments:
    **
    *a    group - pointer to a diguyCharacterGroup
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int destroy_group(diguyCharacterGroup* group);


/*****************************************************************************/
   int get_num_sensor_regions();

   /*l
    *b  Returns:
    **
    **    pointer of type diguySensorRegion; NULL if no
    **    sensor region at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the sensor region; indices start at 0
    */
   diguySensorRegion* get_sensor_region_at_index(int index);

   diguySensorRegion* find_sensor_region(const char* name);

   diguySensorRegion* find_or_create_sensor_region(const char* name);

/*****************************************************************************/
   /*l
    *b  Returns:
    **
    **    number of scene objects in the scenario
    */
   int get_num_scene_objects();

   /*l
    *b  Returns:
    **
    **    pointer of type diguySceneObject; NULL if no
    **    scene object at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the scene object; indices start at 0
    */
   diguySceneObject* get_scene_object_at_index(int index);

   /*l
    *b  Returns:
    **
    **    pointer of type diguySceneObject; NULL if no
    **    scene object with specified name
    */
   diguySceneObject* find_scene_object(const char* name);

   /*l
    *b  Description:
    **
    **    This function sets whether scene objects defined in the
    **    scenario are enabled, and therefore potentially visible.
    **
    **    Scene objects are *not* enabled by default.
    **
    *b  Arguments:
    **
    *a    scene_objects_enabled - flag determining whether scene
    *a                            objects are enabled; 1 for enabled,
    *a                            0 for disabled
    */
   void set_scene_objects_enabled(int scene_objects_enabled);

   /*l
    *b  Returns:
    **
    **    the most recent setting made by a call to
    **    set_scene_objects_enabled()
    */
   int get_scene_objects_enabled();

   /*l
    *b  Description:
    **
    **    This function creates a new scene object and returns a
    **    pointer to it.
    **
    *b  Arguments:
    **
    *a    name          - name of the new scene object
    *a    filename      - file the scene object should use
    **
    *b  Returns:
    **
    **    pointer of type diguySceneObject; NULL if creation failed
    */
   diguySceneObject* create_scene_object(const char* name,
      const char* filename);

   /*l
    *b  Description:
    **
    **    This function creates a new user defined scene object and returns a
    **    pointer to it.
    **
    *b  Arguments:
    **
    *a    name          - name of the new scene object
    **
    *b  Returns:
    **
    **    pointer of type diguySceneObject; NULL if creation failed
    */
   diguySceneObject* create_user_defined_scene_object(const char* name);

   /*l
    *b  Description:
    **
    **    This function destroys a scene object.
    **
    *b  Arguments:
    **
    *a    scene_object - pointer to a diguySceneObject
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int destroy_scene_object(diguySceneObject* scene_object);


/*****************************************************************************/
   /*l
    *b  Returns:
    **
    **    pointer to the scenario's primary view; there is one
    **    and only one primary view in the scenario
    */
   diguyView* get_primary_view();

   /*l
    *b  Description:
    **
    **    Creates a new secondary view for the scenario.
    **
    *b  Returns:
    **
    **    true on success, false on failure
    */
   bool create_new_secondary_view();

   /*l
    *b  Returns:
    **
    **    number of secondary views in the scenario
    */
   int get_num_secondary_views();

   /*l
    *b  Returns:
    **
    **    pointer of type diguyView; NULL if no
    **    secondary view at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the secondary view; indices start at 0
    */
   diguyView* get_secondary_view_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the view with
    **    the given name.  The primary view and all of the
    **    secondary views are checked for a name match.
    **
    *b  Returns:
    **
    **    pointer of type diguyView; NULL if not found
    */
   diguyView* find_view(const char* name);


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function returns a pointer to the primary view's camera.
    **    This is equivalent to:
    **
    *e     diguyView* v = scenario->get_primary_view();
    *e     return v->get_camera();
    **
    *b  Returns:
    **
    **    pointer of type diguyViewCamera; should never be NULL
    */
   diguyViewCamera* get_scenario_camera();

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the camera with
    **    the given name.  The primary view's camera and all of the
    **    secondary views' cameras are checked for a name match.
    **
    *b  Returns:
    **
    **    pointer of type diguyViewCamera; NULL if not found
    */
   diguyViewCamera* find_camera(const char* name);

   /*l
    *b  Description:
    **
    **    This function sets a flag that determines whether script
    **    calls can set the primary view's camera settings.
    **    Specifically, if flag is 0, calls to diguyViewCamera::load()
    **    will have no effect; the camera should remain completely under
    **    user control.
    **
    *b  Arguments:
    **
    *a    flag - 1 to enable, 0 to disable
    */
   void set_scenario_camera_affected_by_script_events(int flag);

   /*l
    *b  Returns:
    **
    **    the most recent setting made by
    **    set_scenario_camera_affected_by_script_events()
    */
   int get_scenario_camera_affected_by_script_events();

   /*l
    *b  Description:
    **
    **    This function, like
    **    set_scenario_camera_affected_by_script_events(), determines
    **    whether script calls can set the primary view's camera settings,
    **    but only disables camera changes if there is an active I-Guy
    **    character as set by the set_iguy_character() call.
    **
    **    If set_scenario_camera_affected_by_script_events() has been called
    **    with a value of 0, then this function has no effect.
    **
    *b  Arguments:
    **
    *a    flag - 1 to enable, 0 to disable
    */
   void set_scenario_camera_affected_by_script_events_when_iguy_active(int flag);

   /*l
    *b  Returns:
    **
    **    the most recent setting made by
    **    set_scenario_camera_affected_by_script_events()
    */
   int get_scenario_camera_affected_by_script_events_when_iguy_active();

   /*l
    *b  Returns:
    **
    **    number of camera settings saved in the scenario
    */
   int get_num_camera_settings();

   /*l
    *b  Returns:
    **
    **    pointer of type diguyViewCameraSettings; NULL if no
    **    camera settings at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the camera settings; indices start at 0
    */
   diguyViewCameraSettings* get_camera_settings_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified camera settings.
    **
    *b  Arguments:
    **
    *a    settings_name - name of camera settings to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyViewCamera; NULL if not found
    */
   diguyViewCameraSettings* find_camera_settings(const char* settings_name);

   /*l
    *b  Description:
    **
    **    This function loads the specified camera settings into
    **    the primary view's camera.
    **
    *b  Arguments:
    **
    *a    settings_name         - name of camera settings to be loaded
    *a    update_current_camera - whether the current camera should be
    *a                            updated; defaults to 1
    **
    **    Not updating the current camera will cause the camera history
    **    to be lost.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int load_camera_settings(const char* settings_name, int update_current_camera = 1);

   /*l
    *b  Description:
    **
    **    This function sets camera that will be used for down-stream
    **    camera-related operations.  This includes:
    **
    *-    - far position rendering in the OpenGL renderer
    *-    - various culling operations (e.g. set_character_culling_enabled())
    *-    - graphics LOD range scaling; see
    *-      set_scale_graphics_lod_ranges_from_view_settings()
    **
    **    Typically the passed camera should be the primary view's camera.
    **
    **    A render camera does not always need to be set.  If one is not
    **    set, the above camera-related operations will not be performed.
    **
    **    If a render camera is set the actual rendering environment
    **    camera settings (e.g. as set by gluLookAt() in OpenGL)
    **    should match the settings in the render camera, or there
    **    may be unexpected visual results.
    **
    *b  Arguments:
    **
    *a    camera - camera to use for camera-related operations
    */
   void set_render_camera(diguyViewCamera* camera);
   diguyViewCamera* get_render_camera();

/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function returns a pointer to the scenario fog.
    **    This is the fog of the primary view.
    **
    *b  Returns:
    **
    **    pointer of type diguyViewFog; should never be NULL
    */
   diguyViewFog* get_scenario_fog();

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the fog with
    **    the given name.  The primary view's fog and all of the
    **    secondary views' fogs are checked for a name match.
    **
    *b  Returns:
    **
    **    pointer of type diguyViewFog; NULL if not found
    */
   diguyViewFog* find_fog(const char* name);

   /*l
    *b  Description:
    **
    **    This function returns the fog object with the given name, or
    **    creates one if not found.
    **
    *b  Returns:
    **
    **    pointer of type diguyViewFog
    **
    *b  Arguments:
    **
    *a    name
    */
   diguyViewFog* find_or_create_fog(const char* name);

   /*l
    *b  Description:
    **
    **    This function loads the named fog settings the currently active
    **    one.
    **
    *b  Arguments:
    **
    *a    name
    */
   void load_current_fog(const char* name);

   /*l
    *b  Returns:
    **
    **    number of fog settings in the scenario
    */
   int get_num_fog_settings();

   /*l
    *b  Returns:
    **
    **    pointer of type diguyViewFogSettings; NULL if no
    **    fog at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the fog settings; indices start at 0
    */
   diguyViewFogSettings* get_fog_settings_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified fog settings.
    **
    *b  Arguments:
    **
    *a    settings_name - name of fog settings to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyViewFogSettings; NULL if not found
    */
   diguyViewFogSettings* find_fog_settings(const char* settings_name);

   /*l
    *b  Description:
    **
    **    This function loads the specified fog settings into
    **    the scenario fog.
    **
    *b  Arguments:
    **
    *a    settings_name - name of fog settings to be loaded
    **
    *b  Returns:
    **
    **    pointer of type diguyViewFog; NULL if not found
    */
   int load_fog_settings(const char* settings_name);


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function returns a pointer to the scenario light.
    **    These are the lights of the primary view.
    **
    *b  Arguments:
    **
    *a    number    - number of light to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyViewLight; can be null if asked for a
    **    non-existent light
    */
   diguyViewLight* get_scenario_light(int i = 0);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the light with
    **    the given name.  The primary view's light and all of the
    **    secondary views' lights are checked for a name match.
    **
    *b  Returns:
    **
    **    pointer of type diguyViewLight; NULL if not found
    */
   diguyViewLight* find_light(const char* name);

   /*l
    *b  Returns:
    **
    **    number of light settings in the scenario
    */
   int get_num_light_settings();

   /*l
    *b  Returns:
    **
    **    pointer of type diguyViewLightSettings; NULL if no
    **    light settings at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the light settings; indices start at 0
    */
   diguyViewLightSettings* get_light_settings_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified light settings.
    **
    *b  Arguments:
    **
    *a    name    - name of light settings to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyViewLightSettings; NULL if not found
    */
   diguyViewLightSettings* find_light_settings(const char* settings_name);

   /*l
    *b  Description:
    **
    **    This function loads the specified light settings into
    **    the scenario light.
    **
    *b  Arguments:
    **
    *a    settings_name - name of light settings to be loaded
    *a    light_num     - which light to load into
    **
    *b  Returns:
    **
    **    pointer of type diguyViewLight; NULL if not found
    */
   int load_light_settings(const char* settings_name, int light_num = 0);

   void set_use_override_ambient_material(int enabled);

   int get_use_override_ambient_material();

   void set_global_ambient_material(float value);

   float get_global_ambient_material();

/*****************************************************************************/
   /*l
    *b  Returns:
    **
    **    number of info popups in the scenario
    */
   int get_num_info_popups();

   /*l
    *b  Returns:
    **
    **    pointer of type diguyInfoPopup; NULL if no
    **    info popup at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the info popup; indices start at 0
    */
   diguyInfoPopup* get_info_popup_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified info popup.
    **
    *b  Arguments:
    **
    *a    name    - name of info popup to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyInfoPopup; NULL if not found
    */
   diguyInfoPopup* find_info_popup(const char* name);

   /*l
    *b  Description:
    **
    **    This function sets the default encoding for info popups
    **    that do not have an encoding specified.
    **
    *b  Arguments:
    **
    *a    info_popup_default_encoding - new default encoding
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int set_info_popup_default_encoding(const char* info_popup_default_encoding);

   /*l
    *b  Description:
    **
    **    This function returns the default encoding of info popups.
    **
    *b  Returns:
    **
    **    default encoding; value will never be NULL, but may be
    **    the empty string ("") if no default encoding has been
    **    specified
    */
   const char* get_info_popup_default_encoding();


/*****************************************************************************/
   /*l
    *b  Returns:
    **
    **    number of variables in the scenario
    */
   int get_num_variables();

   /*l
    *b  Returns:
    **
    **    pointer of type diguyVariable; NULL if no
    **    variable at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the variable; indices start at 0
    */
   diguyVariable* get_variable_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified variable.
    **
    *b  Arguments:
    **
    *a    name - name of variable to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyVariable; NULL if not found
    */
   diguyVariable* find_variable(const char* name);

   /*l
    *b  Description:
    **
    **    This function finds the variable with the given name or
    **    creates it if it doesn't exist.
    **
    *b  Arguments:
    **
    *a    name - name of the variable to find or create
    **
    *b  Returns:
    **
    **    pointer of type diguyVariable; should never be NULL
    */
   diguyVariable* find_or_create_variable(const char* name);

   /*l
    *b  Description:
    **
    **    This function destroys the passed variable.
    **
    *b  Arguments:
    **
    *a    variable - pointer to a diguyVariable
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int destroy_variable(diguyVariable* variable);


/*****************************************************************************/
   /*l
    *b  Returns:
    **
    **    number of face_expressions in the scenario
    */
   int get_num_face_expressions();

   /*l
    *b  Returns:
    **
    **    pointer of type diguyCharacterFaceExpression; NULL if no
    **    info popup at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the face_expression; indices start at 0
    */
   diguyCharacterFaceExpression* get_face_expression_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified face expression.
    **
    *b  Arguments:
    **
    *a    name    - name of face_expression to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyCharacterFaceExpression; NULL if not found
    */
   diguyCharacterFaceExpression* find_face_expression(const char* name);

   /*l
    *b  Description:
    **
    **    This function creates a new face expression with the given name.
    **
    *b  Arguments:
    **
    *a    name         - name of the new face expression
    *a    target_actor - name of the actor to use as template; defaults to
    *a                   "exface" for backwards compatiblity
    **
    *b  Returns:
    **
    **    pointer of type diguyCharacterFaceExpression
    */
   diguyCharacterFaceExpression* create_face_expression(const char* name,
      const char* target_actor = "exface");

   /*l
    *b  Description:
    **
    **    This function destroys the passed face expression.
    **
    *b  Arguments:
    **
    *a    face_expression - pointer to a diguyCharacterFaceExpression
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int destroy_face_expression(diguyCharacterFaceExpression* face_expression);


/*****************************************************************************/
   /*l
    *b  Returns:
    **
    **    number of chain settings in the scenario
    */
   int get_num_chain_settings();

   /*l
    *b  Returns:
    **
    **    pointer of type diguyChainSettings; NULL if no
    **    chain settings at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the chain settings; indices start at 0
    */
   diguyChainSettings* get_chain_settings_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified chain settings.
    **
    *b  Arguments:
    **
    *a    name - name of chain settings to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyChainSettings; NULL if not found
    */
   diguyChainSettings* find_chain_settings(const char* name);

   /*l
    *b  Description:
    **
    **    This function creates a new chain settings and returns a
    **    pointer to it.
    **
    *b  Arguments:
    **
    *a    name - name of the new chain settings
    **
    *b  Returns:
    **
    **    pointer of type diguyChainSettings
    */
   diguyChainSettings* create_chain_settings(const char* name);

   /*l
    *b  Description:
    **
    **    This function destroys a chain settings.
    **
    *b  Arguments:
    **
    *a    chain settings - pointer to a diguyChainSettings
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int destroy_chain_settings(diguyChainSettings* chain_settings);


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This is an enumeration of the different callbacks
    **    that can be registered with add_callback() and
    **    add_callback_script().
    **
    **    Callbacks return a value of type diguyCallbackReturn,
    **    which will be DIGUY_CALLBACK_STOP or DIGUY_CALLBACK_CONTINUE.
    **    If the callback returns DIGUY_CALLBACK_STOP, the default handler
    **    of the function will not be called; the callback is asserting
    **    that it has done everything necessary for the function call.
    **    If the callback returns DIGUY_CALLBACK_CONTINUE, the default
    **    handler for the function will be called after the callback.
    **
    *************************************************************************
    *4  Callback Enums:
    **
    *i    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.
    **
    *i    CALLBACK_ID_RESET
    **
    **      This callback will be called when the scenario is reset.
    **
    *i    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.
    **
    *i    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.
    **
    *i    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.
    **
    *i    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.
    **
    *i    CALLBACK_ID_LOAD_SCENARIO_FILE
    **
    **      This callback will be called just before a scenario loads
    **      a new file.
    **
    *i    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.
    **
    *i    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.
    **
    *i    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.
    **
    *i    Lua Example:
    **
    *e      local painter = this_app:get_view_painter();
    *e      painter:set_pen_color(1,1,0);
    *e      painter:draw_line(0,0,0, 1,1,1);
    **
    *i    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.
    **
    *i    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.
    **
    *i    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.
    **
    *i    CALLBACK_ID_POST_LOAD_CHECKPOINT
    **
    **      This callback will be called just after a scenario finishes
    **      loading a checkpoint file.
    */
   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
   };

#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    This function adds a scenario callback.
    **
    *b  Arguments:
    **
    *a    callback        - pointer to function with prototype
    *a                      diguyScenarioCallback (typedefed above)
    *a    callback_id     - integer id of when this callback is to be called
    *a    callback_params - not currently used; pass NULL
    *a    callback_user_data - pointer for user's own use; DI-Guy will
    *a                         do nothing to the contents of this pointer
    *a                         beyond passing it back when the callback is
    *a                         invoked
    *a    remove_on_scenario_load - pass 1 to remove the callback on a
    *a                              scenario load, 0 to not
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int add_callback(int callback_id,
      diguyScenarioCallback* callback,
      void* callback_params = 0,
      void* callback_user_data = 0,
      int remove_on_scenario_load = 1);

   /*l
    *b  Description:
    **
    **    This function removes a user callback.  All callbacks matching
    **    the specified callback_id and callback function will be removed.
    **
    *b  Arguments:
    **
    *a    callback_id     - integer id of callback
    *a    callback        - pointer to function with prototype
    *a                      diguyCharacterCallback (typedefed above)
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_callback(int callback_id,
      diguyScenarioCallback* callback);

   /*l
    *b  Description:
    **
    **    This function removes a user callback.  All callbacks matching
    **    the specified callback_id and callback_user_data pointer will
    **    be removed.
    **
    *b  Arguments:
    **
    *a    callback_id        - integer id of callback
    *a    callback_user_data - pointer for user's own use
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_callback_with_user_data(int callback_id,
      void* callback_user_data);

   /*l
    *b  Description:
    **
    **    This function sets a default user callback that will be added to
    **    all new characters. See diguyCharacter::add_callback() for
    **    details.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   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);

   /*l
    *b  Description:
    **
    **    This function removes a user callback.  All default character
    **    callbacks matching the specified callback_id and callback function
    **    will be removed.
    **
    *b  Arguments:
    **
    *a    callback_id     - integer id of callback
    *a    callback        - pointer to function with prototype
    *a                      diguyCharacterCallback (typedefed above)
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_default_character_callback(int callback_id,
      diguyCharacterCallback* callback);

   /*l
    *b  Description:
    **
    **    This function removes a default user callback previously added by
    **    add_default_character_callback().  See
    **    diguyCharacter::remove_callback_with_user_data() for details.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_default_character_callback_with_user_data(int callback_id,
      void* callback_user_data);


   /*l
    *b  Description:
    **
    **    This function sets a default user callback that will be added
    **    to all new sensor regions. See
    **    diguySensorRegion::add_callback() for details.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   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);

   /*l
    *b  Description:
    **
    **    This function removes a user callback.  All default sensor region
    **    callbacks matching the specified callback_id and callback function
    **    will be removed.
    **
    *b  Arguments:
    **
    *a    callback_id     - integer id of callback
    *a    callback        - pointer to function with prototype
    *a                      diguyCharacterCallback (typedefed above)
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_default_sensor_region_callback(int callback_id,
      diguySensorRegionCallback* callback);

   /*l
    *b  Description:
    **
    **    This function removes a default user callback.  All default sensor
    **    region callbacks matching the specified callback_id and
    **    callback_user_data pointer will be removed.
    **
    *b  Arguments:
    **
    *a    callback_id        - integer id of callback
    *a    callback_user_data - pointer for user's own use
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_default_sensor_region_callback_with_user_data(int callback_id,
      void* callback_user_data);

   /*l
    *b  Description:
    **
    **    This function adds a default user callback that will be added
    **    to all new signals.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   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);

   /*l
    *b  Description:
    **
    **    This function removes a user callback.  All default signal
    **    callbacks matching the specified callback_id and callback function
    **    will be removed.
    **
    *b  Arguments:
    **
    *a    callback_id     - integer id of callback
    *a    callback        - pointer to function with prototype
    *a                      diguyCharacterCallback (typedefed above)
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_default_signal_callback(int callback_id,
      diguySignalCallback* callback);

   /*l
    *b  Description:
    **
    **    This function removes a default user callback.  All default signal
    **    callbacks matching the specified callback_id and callback_user_data
    **    pointer will be removed.
    **
    *b  Arguments:
    **
    *a    callback_id        - integer id of callback
    *a    callback_user_data - pointer for user's own use
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_default_signal_callback_with_user_data(int callback_id,
      void* callback_user_data);

   /*l
    *b  Description:
    **
    **    This function adds a default user callback that will be added
    **    to all new variables.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   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);

   /*l
    *b  Description:
    **
    **    This function removes a user callback.  All default variable
    **    callbacks matching the specified callback_id and callback function
    **    will be removed.
    **
    *b  Arguments:
    **
    *a    callback_id     - integer id of callback
    *a    callback        - pointer to function with prototype
    *a                      diguyCharacterCallback (typedefed above)
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_default_variable_callback(int callback_id,
      diguyVariableCallback* callback);

   /*l
    *b  Description:
    **
    **    This function removes a default user callback.  All default
    **    variable callbacks matching the specified callback_id and
    **    callback_user_data pointer will be removed.
    **
    *b  Arguments:
    **
    *a    callback_id        - integer id of callback
    *a    callback_user_data - pointer for user's own use
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_default_variable_callback_with_user_data(int callback_id,
      void* callback_user_data);

   /*l
    *b  Description:
    **
    **    This function adds a default user callback that will be added
    **    to all new views.
    **
    **    Note that unlike most of the other add default callback
    **    functions, this one's add_to_existing_objects_flag argument
    **    defaults to a value of 1, since views in scenarios always
    **    exist and are neither created nor destroyed.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   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);

   /*l
    *b  Description:
    **
    **    This function removes a user callback.  All default view
    **    callbacks matching the specified callback_id and callback function
    **    will be removed.
    **
    *b  Arguments:
    **
    *a    callback_id     - integer id of callback
    *a    callback        - pointer to function with prototype
    *a                      diguyCharacterCallback (typedefed above)
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_default_view_callback(int callback_id,
      diguyViewCallback* callback);

   /*l
    *b  Description:
    **
    **    This function removes a default user callback.  All default view
    **    callbacks matching the specified callback_id and callback_user_data
    **    pointer will be removed.
    **
    *b  Arguments:
    **
    *a    callback_id        - integer id of callback
    *a    callback_user_data - pointer for user's own use
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_default_view_callback_with_user_data(int callback_id,
      void* callback_user_data);

   /*l
    *b  Description:
    **
    **    This function adds a default user callback that will be added
    **    to all cameras.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   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);

   /*l
    *b  Description:
    **
    **    This function removes a user callback.  All default camera
    **    callbacks matching the specified callback_id and callback function
    **    will be removed.
    **
    *b  Arguments:
    **
    *a    callback_id     - integer id of callback
    *a    callback        - pointer to function with prototype
    *a                      diguyCharacterCallback (typedefed above)
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_default_camera_callback(int callback_id,
      diguyViewCameraCallback* callback);

   /*l
    *b  Description:
    **
    **    This function removes a default user callback.  All default camera
    **    callbacks matching the specified callback_id and callback_user_data
    **    pointer will be removed.
    **
    *b  Arguments:
    **
    *a    callback_id        - integer id of callback
    *a    callback_user_data - pointer for user's own use
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_default_camera_callback_with_user_data(int callback_id,
      void* callback_user_data);

   /*l
    *b  Description:
    **
    **    This function adds a default user callback that will be added
    **    to all new fogs.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   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);

   /*l
    *b  Description:
    **
    **    This function removes a user callback.  All default fog
    **    callbacks matching the specified callback_id and callback function
    **    will be removed.
    **
    *b  Arguments:
    **
    *a    callback_id     - integer id of callback
    *a    callback        - pointer to function with prototype
    *a                      diguyCharacterCallback (typedefed above)
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_default_fog_callback(int callback_id,
      diguyViewFogCallback* callback);

   /*l
    *b  Description:
    **
    **    This function removes a default user callback.  All default fog
    **    callbacks matching the specified callback_id and callback_user_data
    **    pointer will be removed.
    **
    *b  Arguments:
    **
    *a    callback_id        - integer id of callback
    *a    callback_user_data - pointer for user's own use
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_default_fog_callback_with_user_data(int callback_id,
      void* callback_user_data);

   /*l
    *b  Description:
    **
    **    This function adds a default user callback that will be added
    **    to all new lights.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   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);

   /*l
    *b  Description:
    **
    **    This function removes a user callback.  All default light
    **    callbacks matching the specified callback_id and callback function
    **    will be removed.
    **
    *b  Arguments:
    **
    *a    callback_id     - integer id of callback
    *a    callback        - pointer to function with prototype
    *a                      diguyCharacterCallback (typedefed above)
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_default_light_callback(int callback_id,
      diguyViewLightCallback* callback);

   /*l
    *b  Description:
    **
    **    This function removes a default user callback.  All default light
    **    callbacks matching the specified callback_id and callback_user_data
    **    pointer will be removed.
    **
    *b  Arguments:
    **
    *a    callback_id        - integer id of callback
    *a    callback_user_data - pointer for user's own use
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_default_light_callback_with_user_data(int callback_id,
      void* callback_user_data);

#endif

   /*l
    *b  Description:
    **
    **    This function causes all of the scenario callbacks with the given
    **    callback_id to be called now.
    **
    *b  Arguments:
    **
    *a    callback_id - integer id of callback
    */
   void manually_invoke_callbacks_now(int callback_id);

   /*l
    *b  Description:
    **
    **    This function adds a user callback script.  Callback scripts can
    **    be removed with remove_callback_script().
    **
    **    See diguyCharacter::add_callback_script() for an example
    **    of use.
    **
    *b  Arguments:
    **
    *a    callback_id          - integer id of the callback
    *a    callback_script      - Script text of callback to be added
    *a    callback_script_type - the type of script contained in
    *a                           callback_script
    *a    remove_on_scenario_load - if the callback is removed when a new
    *a                              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.
    **
    *i  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.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int add_callback_script(int callback_id,
      const char* callback_script,
      const char* callback_script_type = NULL,
      int remove_on_scenario_load = 1);

   /*l
    *b  Description:
    **
    **    This function removes a user callback script previously added with
    **    add_callback_script().
    **
    **    See diguyCharacter::remove_callback_script() for an example
    **    of use.
    **
    *b  Arguments:
    **
    *a    callback_id          - integer id of the callback
    *a    callback_script      - Script text of callback previously added
    *a    callback_script_type - the type of script contained in
    *a                           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.
    **
    *i  Lua specific:
    **
    **    To pass NULL when calling from a lua script, use nil.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int remove_callback_script(int callback_id,
      const char* callback_script,
      const char* callback_script_type = NULL);

   /*l
    *b  Description:
    **
    **    This function adds a default character callback script.
    **    The callback script will be added to all new characters.
    **    See diguyCharacter::add_callback_script() for
    **    more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   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);

   /*l
    *b  Description:
    **
    **    This function removes a default character callback script.
    **    See diguyCharacter::remove_callback_script() for
    **    more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int remove_default_character_callback_script(int callback_id,
      const char* callback_script,
      const char* callback_script_type = NULL);

   /*l
    *b  Description:
    **
    **    This function adds a default sensor region callback script.
    **    The callback script will be added to all new sensor regions.
    **    See diguySensorRegion::add_callback_script() for
    **    more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   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);

   /*l
    *b  Description:
    **
    **    This function removes a default sensor region callback script.
    **    See diguySensorRegion::remove_callback_script() for
    **    more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int remove_default_sensor_region_callback_script(int callback_id,
      const char* callback_script,
      const char* callback_script_type = NULL);

   /*l
    *b  Description:
    **
    **    This function adds a default signal callback script.
    **    The callback script will be added to all new signals.
    **    See diguySignal::add_callback_script() for
    **    more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   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);

   /*l
    *b  Description:
    **
    **    This function removes a default signal callback script.
    **    See diguySignal::remove_callback_script() for
    **    more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int remove_default_signal_callback_script(int callback_id,
      const char* callback_script,
      const char* callback_script_type = NULL);

   /*l
    *b  Description:
    **
    **    This function adds a default variable callback script.
    **    The callback script will be added to all new variables.
    **    See diguySignal::add_callback_script() for
    **    more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   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);

   /*l
    *b  Description:
    **
    **    This function removes a default variable callback script.
    **    See diguySignal::remove_callback_script() for
    **    more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int remove_default_variable_callback_script(int callback_id,
      const char* callback_script,
      const char* callback_script_type = NULL);

   /*l
    *b  Description:
    **
    **    This function adds a default view callback script.
    **    The callback script will be added to all new views.
    **    See diguyView::add_callback_script() for
    **    more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   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);

   /*l
    *b  Description:
    **
    **    This function removes a default character view script.
    **    See diguyView::remove_callback_script() for
    **    more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int remove_default_view_callback_script(int callback_id,
      const char* callback_script,
      const char* callback_script_type = NULL);

   /*l
    *b  Description:
    **
    **    This function adds a default camera callback script.
    **    The callback script will be added to all new cameras.
    **    See diguyViewCamera::add_callback_script() for
    **    more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   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);

   /*l
    *b  Description:
    **
    **    This function removes a default camera callback script.
    **    See diguyViewCamera::remove_callback_script() for
    **    more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int remove_default_camera_callback_script(int callback_id,
      const char* callback_script,
      const char* callback_script_type = NULL);

   /*l
    *b  Description:
    **
    **    This function adds a default fog callback script.
    **    The callback script will be added to all new fogs.
    **    See diguyViewFog::add_callback_script() for
    **    more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   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);

   /*l
    *b  Description:
    **
    **    This function removes a default fog callback script.
    **    See diguyViewFog::remove_callback_script() for
    **    more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int remove_default_fog_callback_script(int callback_id,
      const char* callback_script,
      const char* callback_script_type = NULL);

   /*l
    *b  Description:
    **
    **    This function adds a default light callback script.
    **    The callback script will be added to all new lights.
    **    See diguyViewLight::add_callback_script() for
    **    more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   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);

   /*l
    *b  Description:
    **
    **    This function removes a default light callback script.
    **    See diguyViewLight::remove_callback_script() for
    **    more details.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int remove_default_light_callback_script(int callback_id,
      const char* callback_script,
      const char* callback_script_type = NULL);


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function maps the event handler with the given name
    **    to a callback id.  This mapping will be saved in the .dss
    **    file and restored when the .dss file is loaded.
    **
    **    Mappings can also be made via the DI-Guy Scenario UI.
    **
    **    The event handler is one of the following:
    **
    *-      - a scenario callback function registered by
    *-        diguyApp::register_scenario_event_handler() or
    *-        diguyApp::register_scenario_event_handler_from_library()
    *-      - a script registered by
    *-        diguyApp::register_scenario_event_handler_script()
    *-      - a Script, Decision, or Library Function in the scenario
    *-        whose "Event Type" is "Scenario"
    **
    *b  Arguments:
    **
    *a    callback_id        - integer id of callback
    *a    handler_name       - name of the event handler to map
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int map_event_handler_to_callback_id(int callback_id,
      const char* handler_name);

   /*l
    *b  Description:
    **
    **    This function unmaps the event handler with the given name
    **    from a callback id.
    **
    *b  Arguments:
    **
    *a    callback_id        - integer id of callback
    *a    handler_name       - name of the event handler to map
    *a    unmap_all_matches  - pass 0 to unmap only the first match,
    *a                         pass 1 to unmap all matches
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int unmap_event_handler_from_callback_id(int callback_id,
      const char* handler_name,
      int unmap_all_matches = 0);

   /*l
    *b  Description:
    **
    **    This function manually invokes the named scenario event handler.
    **    The callback_id that will be passed to the event handler will
    **    be CALLBACK_ID_MANUALLY_INVOKED.
    **
    **    Note that care should be taken not to end up in an infinite loop
    **    of event calls.  In general an event handler should not end up
    **    directly or indirectly invoking itself.
    **
    **    The event handler is one of the following:
    **
    *-      - a scenario callback function registered by
    *-        diguyApp::register_scenario_event_handler() or
    *-        diguyApp::register_scenario_event_handler_from_library()
    *-      - a script registered by
    *-        diguyApp::register_scenario_event_handler_script()
    *-      - a Script, Decision, or Library Function in the scenario
    *-        whose "Event Type" is "Scenario"
    **
    *b  Arguments:
    **
    *a    handler_name  - name of the event handler to invoke
    **
    *b  Returns:
    **
    **    DIGUY_CALLBACK_CONTINUE or DIGUY_CALLBACK_STOP
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    *-    - Decision
    */
   diguyCallbackReturn manually_invoke_event_handler(const char* handler_name);

#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    This function registers a character event handler
    **    function that can later be mapped via a call to
    **    diguyCharacter::map_event_handler_to_callback_id().
    **
    **    Call unregister_character_event_handler() to
    **    unregister the function.
    **
    *b  Arguments:
    **
    *a    handler_name       - name of the event handler
    *a    callback           - pointer to handler function
    *a    callback_user_data - pointer for user's own use; DI-Guy will
    *a                         do nothing to the contents of this pointer
    *a                         beyond passing it back when the handler
    *a                         function is called
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int register_character_event_handler(const char* handler_name,
      diguyCharacterCallback* callback,
      void* callback_user_data = 0);

#endif

   /*l
    *b  Description:
    **
    **    This function registers a character event handler
    **    function that can later be mapped via a call to
    **    diguyCharacter::map_event_handler_to_callback_id().
    **
    **    Unlike register_character_event_handler(), which directly
    **    passes a function pointer, this function looks up the
    **    function pointer from a shared library (a .dll under
    **    Windows, a .so under Unix).
    **
    **    The passed library_name should not include the
    **    .dll or .so extension; these will be added automatically.
    **    This allows for cross-platform scenarios that don't
    **    have differing dynamic library extensions built into
    **    them.
    **
    **    Call unregister_character_event_handler() to
    **    unregister the function.
    **
    *b  Arguments:
    **
    *a    handler_name       - name of the event handler
    *a    library_name       - pointer to handler function
    *a    function_name      - pointer to handler function
    *a    callback_user_data - pointer for user's own use; DI-Guy will
    *a                         do nothing to the contents of this pointer
    *a                         beyond passing it back when the handler
    *a                         function is called
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int register_character_event_handler_from_library(const char* handler_name,
      const char* library_name,
      const char* function_name,
      void* callback_user_data = 0);

   /*l
    *b  Description:
    **
    **    This function registers a character event handler
    **    script that can later be mapped via a call to
    **    diguyCharacter::map_event_handler_to_callback_id().
    **
    **    Call unregister_character_event_handler() to
    **    unregister the script.
    **
    *b  Arguments:
    **
    *a    handler_name        - name of the event handler
    *a    handler_script      - Script text
    *a    handler_script_type - type of script; pass NULL
    *a                          for scenario to use the default
    *a                          script interpreter
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int register_character_event_handler_script(const char* handler_name,
      const char* handler_script,
      const char* handler_script_type = 0);

   /*l
    *b  Returns:
    **
    **    1 if there is a character event handler with the given
    **    name, 0 if not
    **
    *b  Arguments:
    **
    *a    handler_name        - name of the event handler
    */
   int has_registered_character_event_handler(const char* handler_name);

   /*l
    *b  Description:
    **
    **    This function unregisters a character event handler.
    **    This will unmap the event handler from any mappings
    **    it is a part of.
    **
    *b  Arguments:
    **
    *a    handler_name        - name of the event handler
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int unregister_character_event_handler(const char* handler_name);

#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    This function is analogous to the
    **    register_character_event_handler() function,
    **    but is for signals rather than characters.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int register_signal_event_handler(const char* handler_name,
      diguySignalCallback* callback,
      void* callback_user_data = 0);

#endif

   /*l
    *b  Description:
    **
    **    This function is analogous to the
    **    register_character_event_handler_from_library() function,
    **    but is for signals rather than characters.
    */
   int register_signal_event_handler_from_library(const char* handler_name,
      const char* library_name,
      const char* function_name,
      void* callback_user_data = 0);

   /*l
    *b  Description:
    **
    **    This function is analogous to the
    **    register_character_event_handler_script() function,
    **    but is for signals rather than characters.
    */
   int register_signal_event_handler_script(const char* handler_name,
      const char* handler_script,
      const char* handler_script_type = 0);

   /*l
    *b  Description:
    **
    **    This function is analogous to the
    **    has_registered_character_event_handler() function,
    **    but is for signals rather than characters.
    */
   int has_registered_signal_event_handler(const char* handler_name);

   /*l
    *b  Description:
    **
    **    This function is analogous to the
    **    unregister_character_event_handler() function,
    **    but is for signals rather than characters.
    */
   int unregister_signal_event_handler(const char* handler_name);

#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    This function is analogous to the
    **    register_character_event_handler() function,
    **    but is for sensor regions rather than characters.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int register_sensor_region_event_handler(const char* handler_name,
      diguySensorRegionCallback* callback,
      void* callback_user_data = 0);

#endif

   /*l
    *b  Description:
    **
    **    This function is analogous to the
    **    register_character_event_handler_from_library() function,
    **    but is for sensor regions rather than characters.
    */
   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);

   /*l
    *b  Description:
    **
    **    This function is analogous to the
    **    register_character_event_handler_script() function,
    **    but is for sensor regions rather than characters.
    */
   int register_sensor_region_event_handler_script(const char* handler_name,
      const char* handler_script,
      const char* handler_script_type = 0);

   /*l
    *b  Description:
    **
    **    This function is analogous to the
    **    has_registered_character_event_handler() function,
    **    but is for sensor regions rather than characters.
    */
   int has_registered_sensor_region_event_handler(const char* handler_name);

   /*l
    *b  Description:
    **
    **    This function is analogous to the
    **    unregister_character_event_handler() function,
    **    but is for sensor regions rather than characters.
    */
   int unregister_sensor_region_event_handler(const char* handler_name);

#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    This function is analogous to the
    **    register_character_event_handler() function,
    **    but is for variables rather than characters.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int register_variable_event_handler(const char* handler_name,
      diguyVariableCallback* callback,
      void* callback_user_data = 0);

#endif

   /*l
    *b  Description:
    **
    **    This function is analogous to the
    **    register_character_event_handler_from_library() function,
    **    but is for variables rather than characters.
    */
   int register_variable_event_handler_from_library(const char* handler_name,
      const char* library_name,
      const char* function_name,
      void* callback_user_data = 0);

   /*l
    *b  Description:
    **
    **    This function is analogous to the
    **    register_character_event_handler_script() function,
    **    but is for variables rather than characters.
    */
   int register_variable_event_handler_script(const char* handler_name,
      const char* handler_script,
      const char* handler_script_type = 0);

   /*l
    *b  Description:
    **
    **    This function is analogous to the
    **    has_registered_character_event_handler() function,
    **    but is for variables rather than characters.
    */
   int has_registered_variable_event_handler(const char* handler_name);

   /*l
    *b  Description:
    **
    **    This function is analogous to the
    **    unregister_character_event_handler() function,
    **    but is for variables rather than characters.
    */
   int unregister_variable_event_handler(const char* handler_name);



/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function saves the current run of the scenario to the
    **    specified file, and other files whose names are derived from
    **    the passed filename.  The passed filename should end with the
    **    extension ".dsr" (DI-Guy Review).
    **
    **    The review data can be reloaded later by calling the load()
    **    function, and passing the same filename.
    **
    **    The following is saved for later review:
    **
    *-      - all character positions and poses
    *-      - sounds played by characters due to play_sound() and
    **        fire_weapon_n_times() calls
    **
    **    Note that Paths, Waypoints, and Event Beads per se are *not* saved,
    **    but rather their effects on the characters' positions and poses.
    **
    *b  Arguments:
    **
    *a    filename         - file in which to save review data
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    *b  C++ Example:
    **
    *e     // when shutting down the current run:
    *e     scenario->save_review_data("review0.dsr");
    *e
    *e     // when after action review is needed:
    *e     scenario->load("review0.dsr");
    */
   int save_review_data(const char* filename);

   /*l
    *b  Returns:
    **
    **    1 if scenario was loaded from review data (from a .dsr file);
    **    0 if not (from a .dss file)
    */
   int get_loaded_from_review_data();

   /*l
    *b  Description:
    **
    **    This function sets what type of "history" will be kept for the
    **    scenario.
    **
    **    If time is run backwards in a scenario with history,
    **    the following will be "remembered" and replayed:
    **
    *-    - camera settings currently in the primary view's camera
    *-    - signal trigger counts
    *-    - enabled/disabled status of scene objects
    *-    - sounds
    **
    **    The default is DIGUY_HISTORY_TYPE_NONE for scenarios created
    **    using the DI-Guy API, and DIGUY_HISTORY_TYPE_COMPLETE for scenarios
    **    created using the DI-Guy Scenario editor.
    **
    *b  Arguments:
    **
    *a    history_type - history type to be used for the scenario
    **
    **    history_type should be one of the following values:
    **
    *i    DIGUY_HISTORY_TYPE_NONE
    **
    **      This history type saves no history.
    **
    *i    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.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int set_history_type(diguyHistoryType history_type);

   /*l
    *b  Returns:
    **
    **    the current history type of the scenario; see
    **    set_history_type()
    */
   diguyHistoryType get_history_type();

   /*l
    *b  Description:
    **
    **    This function sets the history type for this scenario, as well as
    **    the history types of all characters.
    **
    **    See also diguyScenario::set_history_type() and
    **    diguyCharacter::set_history_type().
    **
    *b  Arguments:
    **
    *a    history_type - history type to be used for the scenario and all
    *a                   characters
    */
   void set_overall_history_type(diguyHistoryType overall_history_type);

   /*l
    *b  Description:
    **
    **    This function returns the overall history type of the scenario.
    **
    **    The return value will be:
    **
    *-    - DIGUY_HISTORY_TYPE_COMPLETE if history is enabled for the
    *-      scenario and *all* characters
    *-    - DIGUY_HISTORY_TYPE_PARTIAL if history is enabled for at least
    *-      one of the scenario or any character, but not all
    *-    - DIGUY_HISTORY_TYPE_NONE if history is not enabled for the
    *-      scenario or any character
    **
    **    See also diguyScenario::get_history_type() and
    **    diguyCharacter::get_history_type().
    */
   diguyHistoryType get_overall_history_type();

   /*l
    *b  Returns:
    **
    **    whether the scenario is playing back stored history
    */
   int get_replaying_history();

   /*l
    *b  Description:
    **
    **    This function sets how many sound instances are kept in memory when
    **    history is enabled.  By keeping them in memory, users can "scrub"
    **    backwards in time and hear sounds that were started earlier in time
    **    and will be resumed at the proper offset into the sound.  This
    **    function lets users balance that need with memory management.
    **
    *b  Arguments:
    **
    *a    num_sound_instances - override system default of 100
    **
    *b  Returns:
    **
    **    none
    */
   void set_history_max_sound_instances(int num_sound_instances);


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    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.
    **
    *i  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.
    **
    *i  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.
    */
   void set_automatic_graphics_lod_switching(int enable_graphics_lod_switching);

   int get_automatic_graphics_lod_switching();

   int set_character_culling_distance(float dist);

   float get_character_culling_distance();

   void set_cull_bounds_scale_factor(float size);

   float get_cull_bounds_scale_factor();


   int set_vehicle_culling_distance(float dist);

   float get_vehicle_culling_distance();

   int set_prop_culling_distance(float dist);
   float get_prop_culling_distance();

   /*l
    *b  Description:
    **
    **  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.
    */
   void set_instancing_enabled(int val);

   int get_instancing_enabled() const;

   /*l
    *b  Description:
    **
    **  Sets the minimum LOD that the instancing system turns on this defaults to LOD 4.
    */
   void set_instancing_min_lod(int val);

   int get_instancing_min_lod() const;

   void set_visualize_instance_groups(int val);

   int get_visualize_instance_groups() const;

   /*l
    *b  Description:
    **    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()
    */
   void set_instancing_tbo_patching_enabled(int enable_patching);
   int get_instancing_tbo_patching_enabled() const;

   void set_instancing_position_callback_enabled(int use_user_position_matrices);
   int get_instancing_position_callback_enabled() const;

   void set_num_extra_per_instance_data_floats(int number);
   int get_num_extra_per_instance_data_floats() const;

   void build_instance_groups();

   void update_instancing_data();

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

#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    Sets the distances at which level of detail switching occurs
    **    for characters of the specified type.  Existing characters
    **    are not affected; only newly created characters will have the
    **    specified LOD switching ranges.
    **
    **    Characters will display with the highest level of detail when
    **    viewed from a distance between ranges[0] and ranges[1].
    **    Characters will not display at all when viewed from further
    **    away than the highest switching range.
    **
    **    Note: ranges[0] should almost always be 0.0.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index()
    *a    ranges         - an array of 8 non-negative floating point numbers,
    *a                     each larger than the one before, specifying the
    *a                     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.
    **
    *e       lod   polys  min   max
    *e       --------------------------
    *e         1    2300    0     5
    *e         2     900    5    10
    *e         3     550   10    20
    *e         4     280   20    40
    *e         5     130   40    70
    *e         6      60   70   100
    *e         7      40  100  1000
    **
    *b  Callable From:
    **
    *-    - C++
    */
   void set_default_lod_ranges(const char* character_type, float* ranges);

#endif

   /*l
    *b  Description:
    **
    **    This function sets whether view and camera settings such as
    **    field-of-view (FOV) and window size should be taken into account
    **    when determining the graphics LOD from a character's LOD ranges.
    **
    **    The camera settings that are used are taken from the current
    **    render camera, as set by set_render_camera().  This happens
    **    automatically in DI-Guy Scenario, but must be set manually
    **    in the DI-Guy SDK.
    **
    **    DI-Guy graphics LODs are distance-based, but this approach can
    **    be problematic if the current camera's FOV is very narrow; a
    **    narrow FOV essentially acts like a telephoto lens.  In this case
    **    a character that is far away, and would therefore be rendered
    **    with few polygons, can actually be quite large in the 3D view.
    **
    **    Setting this flag to 1 will cause the FOV to be taken into account
    **    when calculating the effective distance of a character from the
    **    camera.
    **
    **    Many DI-Guy LOD distances assume that the vertical FOV of the
    **    view is around 40.  Smaller FOVs will scale the distances larger
    **    so that LOD changes happen further out.  Likewise larger FOVs
    **    will scale the distances smaller; in this case even nearby
    **    characters will appear small and therefore need less resolution.
    **
    *b  Arguments:
    **
    **    do_scale   - pass 1 to enable scaling, 0 to disable
    */
   void set_scale_graphics_lod_ranges_from_view_settings(int do_scale);

   /*l
    *b  Returns:
    **
    **    most recent setting of
    **    set_scale_graphics_lod_ranges_from_view_settings()
    */
   int  get_scale_graphics_lod_ranges_from_view_settings();

   /*l
    *b  Description:
    **
    **    This function sets whether automatic motion LOD switching
    **    should be enabled.
    **
    **    By default it is enabled in DI-Guy Scenario, and disabled in a
    **    DI-Guy API application.
    **
    **    When running in a user application that uses the DI-Guy
    **    API, the primary view's camera's position and orientation
    **    must be kept consistent with the application's perception
    **    of current camera settings.  A pointer to the primary view's
    **    camera can be obtained by calling get_scenario_camera().
    **
    **    The following describes the algorithm used by automatic motion
    **    LOD switching:
    **
    *-    - if a character is in front of the primary view's camera,
    *-      the motion LOD is set to 1 (animate all joints)
    *-    - else set motion LOD to 5 (stop animating everything but
    *-      base position)
    **
    **    Note that if there are multiple views open on the scenario,
    **    the character must be behind *all* cameras for the motion
    **    LOD to be set to 5.
    **
    **    Also, if the history type of the character (as set by
    **    diguyCharacter::set_history_type()) is anything but
    **    DIGUY_HISTORY_TYPE_NONE, motion LOD 1 will be used since
    **    during scenario playback the character might be in front
    **    of any camera.
    */
   void set_automatic_motion_lod_switching(int enable_motion_lod_switching);

   /*l
    *b  Description:
    **
    **    This function returns whether automatic motion LOD switching
    **    is be enabled for characters in the scenario, as set by
    **    set_automatic_motion_lod_switching().
    **
    *b  Returns:
    **
    **    1 if LODs enabled; 0 if not
    */
   int get_automatic_motion_lod_switching();


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function sends the passed string through the script
    **    interpreter.
    **
    *b  Arguments:
    **
    *a    script_text       - string to be evaluated
    *a    save_as_transient - flag stating whether script_text should
    *a                        be remembered as a transient event at
    *a                        the current scenario t; see
    *a                        push_transient_script_event()
    *a    script_type       - type of script contained in script_text; pass
    *a                        NULL to use scenario's default interpreter
    *a    script_source     - string identifying the 'source' of the script;
    *a                        will be printed in error output if there are
    *a                        syntax errors in the script
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  C++ Example:
    **
    *e     scenario->eval_script("signal1:trigger();",
    *e         0,
    *e         "lua",
    *e         "User Script");
    */
   int eval_script(const char* script_text,
      int save_as_transient = 0,
      const char* script_type = NULL,
      const char* script_source = NULL);

   /*l
    *b  Description:
    **
    **    This function sends the contents of the specified file through
    **    the script interpreter.
    **
    *b  Arguments:
    **
    *a    filename    - filename of script to be evaluated
    *a    script_type - type of script contained in file; pass NULL
    *a                  to use the scenario's default interpreter
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  C++ Example:
    **
    *e     scenario->eval_script_file("my_scripts.pl");
    */
   int eval_script_file(const char* filename,
      const char* script_type = NULL);

   /*l
    *b  Description:
    **
    **    This function manually triggers a script.
    **
    *b  Arguments:
    **
    *a    script_name - name of the script to be triggered
    **
    *b  Returns:
    **
    **    return result of script; 0 if script not found
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    *-    - Decision
    */
   int trigger_script(const char* script_name);

   /*l
    *b  Description:
    **
    **    This function is similar to trigger_script(), but delays the
    **    trigger by the specified time.
    **
    *b  Arguments:
    **
    *a    script_name - name of the script to be triggered
    *a    t_delay     - how many seconds to delay trigger
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    *-    - Decision
    */
   void trigger_script_delayed(const char* script_name, float t_delay);

   /*l
    *b  Description:
    **
    **    This function manually triggers a decision.
    **
    *b  Arguments:
    **
    *a    decision_name - name of the decision to be triggered
    **
    *b  Returns:
    **
    **    return result of decision; 0 if decision not found
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    *-    - Decision
    */
   int trigger_decision(const char* decision_name);

   /*l
    *b  Description:
    **
    **    This function is similar to trigger_decision(), but delays the
    **    trigger by the specified time.
    **
    *b  Arguments:
    **
    *a    decision_name - name of the decision to be triggered
    *a    t_delay       - how many seconds to delay trigger
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    *-    - Decision
    */
   void trigger_decision_delayed(const char* decision_name, float t_delay);

   /*l
    *b  Description:
    **
    **    This function places the passed script text on a list of scripts
    **    that should be re-evaluated when the scenario is replayed from
    **    review data.
    **
    **    Note that the script is *not* evaluated at this time.  This can be
    **    done by calling eval_script() and passing 1 for the
    **    save_as_transient argument.
    **
    **    If the scenario is reset (as in a call to reset()), all transient
    **    scripts will be deleted.  The transient script events can be saved
    **    and restored by calling save_transient_script_events() and
    **    load_transient_script_events(), respectively.
    **
    *b  Arguments:
    **
    *a    t            - time at which script should be re-evaluated
    *a                   during scenario playback
    *a    script_text  - Script to be evaluated
    *a    script_type  - Scripting language to use (lua)
    **
    **    A copy of the passed script text is made.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   void push_transient_script_event(float t, const char* script_text, const char* script_type);

   /*l
    *b  Description:
    **
    **    This function deletes all transient script events.
    */
   void clear_transient_script_events();

   /*l
    *b  Description:
    **
    **    This function saves the transient script events to the specified
    **    file.  They can be restored by calling
    **    load_transient_script_events() with the same filename.
    **
    *b  Arguments:
    **
    *a    filename - file in which transient script events should be saved
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int save_transient_script_events(const char* filename);

   /*l
    *b  Description:
    **
    **    This function loads transient script events saved by a call to
    **    save_transient_script_events().
    **
    *b  Arguments:
    **
    *a    filename - file from which transient script events should be
    *a               loaded
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int load_transient_script_events(const char* filename);

   /*l
    *b  Description:
    **
    **    This function creates a package object that points to an external
    **    file.  If the language is not specified it will be determined based
    **    on the filename's extension.  DI-Guy will attempt to derive an
    **    appropriate name for the package.  In DI-Guy Scenario package
    **    dependencies are also extracted and loaded; currently this must be
    **    done manually in the SDK.
    */
   int load_package( const char* filename, const char* language = NULL,
      int warn_if_not_found = 1 );

   /*l
    *b  Description:
    **
    **    This function creates a package object that points to an external
    **    file.  If the language is not specified it will be determined based
    **    on the filename's extension.  DI-Guy will attempt to derive an
    **    appropriate name for the package. Dependency package will also be loaded.
    **
    */
   int load_package_with_dependency( const char* filename, const char* depends_on_package,
      const char* language = NULL, int warn_if_not_found = 1 );


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function returns the number of postures the specified
    **    character type's actions support.
    **
    **    Use this function along with get_character_type_posture_at_index()
    **    to enumerate the character's postures.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    **
    *b  Returns:
    **
    **    the number of postures the specified character type's actions
    **    support
    */
   int get_character_type_num_postures(const char* character_type);

   /*l
    *b  Description:
    **
    **    This function returns the posture at the specified index.
    **
    **    Use this function along with get_character_type_num_postures()
    **    to enumerate the character's postures.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    *a    index          - index of the posture; indices start at 0
    **
    *b  Returns:
    **
    **    the posture at the specified index
    */
   diguyMotionPosture get_character_type_posture_at_index(const char* character_type,
      int index);

   /*l
    *b  Description:
    **
    **    This function returns the overall posture of the specified action.
    **
    **    The results of this function call can be useful in calls to the
    **    diguyCharacter::get_action_from_description() function, if
    **    for example an action with the same posture but a faster speed
    **    is desired.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    *a    action_name    - the action to query
    **
    *b  Returns:
    **
    **    the overall posture of the specified action
    */
   diguyMotionPosture get_character_type_action_posture(const char* character_type,
      const char* action_name);

   /*l
    *b  Description:
    **
    **    This function returns the number of variants the specified
    **    character type's actions support.
    **
    **    Use this function along with get_character_type_variant_at_index()
    **    to enumerate the character's variants.
    **
    **    This function differs from
    **    get_character_type_action_num_variants() in that this function
    **    returns the number of variants of *all* actions of the
    **    character.  The other function returns the number of variants
    **    of a single action.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    **
    *b  Returns:
    **
    **    the number of variants the specified character type's actions
    **    support
    */
   int get_character_type_num_variants(const char* character_type);

   /*l
    *b  Description:
    **
    **    This function returns the variant at the specified index.
    **
    **    Use this function along with get_character_type_num_variants()
    **    to enumerate the character's variants.
    **
    **    This function differs from
    **    get_character_type_action_variant_at_index() in that this function
    **    returns one of the variants of *all* actions of the
    **    character.  The other function returns one of the variants
    **    of a single action.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    *a    index          - index of the posture; indices start at 0
    **
    *b  Returns:
    **
    **    the variant at the specified index
    */
   diguyMotionVariant get_character_type_variant_at_index(const char* character_type,
      int index);

   /*l
    *b  Description:
    **
    **    This function returns the primary variant of the specified action.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    *a    action_name    - the action to query
    **
    *b  Returns:
    **
    **    the overall variant of the specified action
    */
   diguyMotionVariant get_character_type_action_primary_variant(const char* character_type,
      const char* action_name);

   /*l
    *b  Description:
    **
    **    This function returns the number of variants the specified
    **    action of the specified character type has.
    **
    **    Use this function along with
    **    get_character_type_action_variant_at_index()
    **    to enumerate the character's variants.
    **
    **    This function differs from
    **    get_character_type_num_variants() in that this function
    **    returns the number of variants of a single action of the
    **    character.  The other function returns the number of variants
    **    of *all* actions.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    *a    action_name    - the action to query
    **
    *b  Returns:
    **
    **    the number of variants of the specified action of the specified
    **    character type
    */
   int get_character_type_action_num_variants(const char* character_type,
      const char* action_name);

   /*l
    *b  Description:
    **
    **    This function returns the variant at the specified index.
    **
    **    Use this function along with
    **    get_character_type_action_num_variants()
    **    to enumerate the character's variants.
    **
    **    This function differs from
    **    get_character_type_variant_at_index() in that this function
    **    returns one of the variants of a single action of the
    **    character.  The other function returns one of the variants
    **    of *all* actions.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    *a    index          - index of the variant; indices start at 0
    **
    *b  Returns:
    **
    **    the variant at the specified index
    */
   diguyMotionVariant get_character_type_action_variant_at_index(const char* character_type,
      const char* action_name,
      int index);

   /*l
    *b  Description:
    **
    **    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.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by get_character_type_at_index(), for example
    *a    action_name    - the action to query
    **
    *b  Returns:
    **
    **    the number of compatible action names for the specified action of the specified character type
    */
   int get_character_type_num_action_compatibility_names( const char* character_type, const char* action_name );

   /*l
    *b  Description:
    **
    **    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.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by get_character_type_at_index(), for example
    *a    index          - index of the action; indices start at 0
    **
    *b  Returns:
    **
    **    the action compatibility name at the specified index
    */
   const char* get_character_type_action_compatibility_name_at_index( const char* character_type,
      const char* action_name, int index );

   /*l
    *b  Description:
    **
    **    This function returns the number of directions the specified
    **    character type's actions can move.
    **
    **    Use the get_character_type_direction_at_index() function to
    **    enumerate the directions available to a character.
    **
    **    The results of this function call can be useful in calls to the
    **    diguyCharacter::get_action_from_description() function.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    **
    *b  Returns:
    **
    **    the number of directions the specified character type's actions
    **    can move
    */
   int get_character_type_num_directions(const char* character_type);

   /*l
    *b  Description:
    **
    **    Use the get_character_type_num_directions() function to
    **    get the number of directions available to a character.
    **
    **    The results of this function call can be useful in calls to the
    **    diguyCharacter::get_action_from_description() function.
    **
    *b  Arguments:
    **
    *a    character_type - character type name, as returned by
    *a                     get_character_type_at_index(), for example
    *a    index          - index of the direction; indices start at 0
    **
    *b  Returns:
    **
    **    the direction at the specified index
    */
   diguyMotionDirection get_character_type_direction_at_index(const char* character_type,
      int index);


/*****************************************************************************/
   /*l
    *b  Returns:
    **
    **    number of interaction machines in the scenario
    */
   int get_num_interaction_machines();

   /*l
    *b  Description:
    **
    **    This function creates a new interaction machine and returns a
    **    pointer to it.
    **
    **    Note that there is a shared interaction machine that always
    **    exists; a pointer to it can be obtained by calling
    **    get_shared_interaction_machine().  See that function for more
    **    details.
    **
    *b  Arguments:
    **
    *a    name            - name of the new interaction machine
    **
    *b  Returns:
    **
    **    pointer of type diguyInteractionMachine; NULL if creation failed
    */
   diguyInteractionMachine* create_interaction_machine(const char* name);

   /*l
    *b  Description:
    **
    **    This function destroys the passed interaction machine.
    **
    **    NOTE:  This function should not be called on the shared
    **    interaction machine returned by get_shared_interaction_machine().
    **
    *b  Arguments:
    **
    *a    interaction_machine - pointer to a diguyInteractionMachine
    *a                          to be destroyed
    */
   void destroy_interaction_machine(diguyInteractionMachine* interaction_machine);

   /*l
    *b  Returns:
    **
    **    pointer of type diguyInteractionMachine; NULL if no interaction
    **    machine at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the interaction machine; indices start at 0
    */
   diguyInteractionMachine* get_interaction_machine_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified interaction
    **    machine.
    **
    *b  Arguments:
    **
    *a    name    - name of interaction machine to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyInteractionMachine; NULL if not found
    */
   diguyInteractionMachine* find_interaction_machine(const char* name);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the "active" interaction
    **    machine.  Only one interaction machine can be showing and
    **    accepting input at a time.
    **
    *b  Returns:
    **
    **    pointer of type diguyInteractionMachine; NULL if no interaction
    **    machine is active.
    */
   diguyInteractionMachine* get_active_interaction_machine();

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the shared interaction machine
    **    that is always available.
    **
    **    This shared interaction machine is convenient for quick
    **    alerts, notifications, or questions.  Because it is shared,
    **    however, most or all of its parameters need to be set each
    **    time it is to be shown.
    **
    **    Do not call destroy_interaction_machine() on the returned
    **    object.  It is owned by the scenario.
    **
    *b  Returns:
    **
    **    pointer of type diguyInteractionMachine; should never be NULL
    */
   diguyInteractionMachine* get_shared_interaction_machine();

   /*l
    *b  Description:
    **
    **    This is a convenience function for using the shared interaction
    **    machine to show a notification to the user.  It sets parameters
    **    of the shared interaction machine based on the passed info and
    **    shows/activates the machine.
    **
    *b  Arguments:
    **
    *a    heading        - text that will be at the top of the dialog
    *a    info           - informational text
    *a    pause_scenario - pass 1 to pause the scenario while the
    *a                     interaction machine is active, 0 to leave
    *a                     the scenario running if it was when this
    *a                     function was called
    *a    input_text     - text that user will have to click to dismiss
    *a                     the interaction machine; something like "Ok"
    *a                     is typical
    *a    ui_appearance  - the color theme of the interaction machine
    **
    **    See the diguyInteractionMachine documentation for more information
    **    on what the various parameters mean.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Lua Example:
    **
    *e     this_scenario:show_notification_with_shared_interaction_machine(
    *e         "WARNING!",
    *e         "Moving any closer to the harmful gas is not advised.",
    *e         0,
    *e         "Ok",
    *e         diguyInteractionMachine_UI_APPEARANCE_NOTIFICATION);
    **
    */
   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);


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function returns a pointer to the I-Guy controller object
    **    of the scenario.
    **
    *b  Returns:
    **
    **    pointer of type diguyIGuyController; should never be NULL
    */
   diguyIGuyController* get_iguy_controller();


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function finds the diguyViewLabel with the given name or
    **    creates it if it doesn't exist.
    **
    *b  Arguments:
    **
    *a    name - name of the diguyViewLabel to find or create
    **
    *b  Returns:
    **
    **    pointer of type diguyViewLabel; should never be NULL
    */
   diguyViewLabel* find_or_create_label(const char* name);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified diguyViewLabel.
    **
    *b  Arguments:
    **
    *a    name - name of diguyViewLabel to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyViewLabel; NULL if not found
    */
   diguyViewLabel* find_label(const char* name);

   /*l
    *b  Description:
    **
    **    This function destroys the passed in diguyViewLabel.
    **
    *b  Arguments:
    **
    *a    label - pointer to a diguyViewLabel
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int destroy_label(diguyViewLabel* label);

   /*l
    *b  Returns:
    **
    **   The number of diguyViewLabel objects in the scenario.
    */
   int   get_num_labels();

   /*l
    *b  Returns:
    **
    **    The diguyViewLabel at the given index.
    **
    *b  Arguments:
    **
    *a    index - index of the diguyViewLabel; indices start at 0
    */
   diguyViewLabel* get_label_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function removes all diguyViewLabels in the scenario.
    */
   void reset_labels();

   /*l
    *b  Description:
    **
    **    This function moves the specified diguyViewLabel to the front of
    **    the drawing list.  This is sometimes necessary if labels overlap.
    **
    *b  Arguments:
    **
    *a    label - pointer to diguyViewLabel to move
    */
   void send_label_to_front(diguyViewLabel* label);

   /*l
    *b  Description:
    **
    **    This function moves the specified diguyViewLabel to the back of
    **    the drawing list.  This is sometimes necessary if labels overlap.
    **
    *b  Arguments:
    **
    *a    label - pointer to diguyViewLabel to move
    */
   void send_label_to_back(diguyViewLabel* label);

   /*l
    *b  Description:
    **
    **   Functions that allow the built-in OGL renderer to draw labels on screen for
    **   debugging use, update_character_labels must be called first.
    **
    *e    scenario->update_character_labels();
    *e    scenario->draw_character_labels();
    **
    *b  Returns:
    **
    **    -1 if not possible to draw labels
    */
   int draw_character_labels();

   void update_character_labels();

/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function finds the diguyViewButtonPanel with the given name or
    **    creates it if it doesn't exist.
    **
    *b  Arguments:
    **
    *a    name - name of the diguyViewButtonPanel to find or create
    **
    *b  Returns:
    **
    **    pointer of type diguyViewButtonPanel; should never be NULL
    */
   diguyViewButtonPanel* find_or_create_panel(const char* name,
      int horizontal = 0,
      int title = 1);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified
    **    diguyViewButtonPanel.
    **
    *b  Arguments:
    **
    *a    name - name of diguyViewButtonPanel to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyViewButtonPanel; NULL if not found
    */
   diguyViewButtonPanel* find_panel(const char* name);

   /*l
    *b  Description:
    **
    **    This function destroys the passed in diguyViewButtonPanel.
    **
    *b  Arguments:
    **
    *a    panel - pointer to a diguyViewButtonPanel
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int destroy_panel(diguyViewButtonPanel* panel);

   /*l
    *b  Returns:
    **
    **   The number of diguyViewButtonPanel objects in the scenario.
    */
   int   get_num_panels();

   /*l
    *b  Returns:
    **
    **    The diguyViewButtonPanel at the given index.
    **
    *b  Arguments:
    **
    *a    index - index of the diguyViewButtonPanel; indices start at 0
    */
   diguyViewButtonPanel* get_panel_at_index(int index);


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function returns the number of AI minds that are available to
    **    AI agent characters.
    **
    *b  Returns:
    **
    **    number of available minds
    */
   int get_num_minds();

   /*l
    *b  Returns:
    **
    **    name of the AI mind at the specified index
    */
   const char* get_mind_name_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function tests if a diguyCharacter pointer is a valid pointer.
    **    This is done by comparing the passed address to those of all
    **    characters in the scenario.  The function is not exceedingly fast
    **    but can be useful when building AI that functions in a networked
    **    environment.
    **
    *b   Returns:
    **
    **    0 if invalid, 1 if valid
    */
   int is_valid_character_pointer(diguyCharacter* character);

   /*l
    *b  Description:
    **
    **    This function tests if a diguyCharacterGroup pointer is a valid
    **    pointer.  This is done by comparing the passed address to those of
    **    all groups in the scenario.  The function is not exceedingly fast
    **    but can be useful when building AI that functions in a networked
    **    environment.
    **
    *b   Returns:
    **
    **    0 if invalid, 1 if valid
    */
   int is_valid_character_group_pointer(diguyCharacterGroup* character_group);

/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function creates a new crowd and returns a pointer to it.
    **
    **    A Lua object is also created that has a pointer to this crowd.
    **    This object can be retrieved by calling find_lua_crowd(crowd_name)
    **    or find_lua_crowd(diguyCrowd* pointer) in lua.
    **
    *b  Arguments:
    **
    *a    name                  - name of crowd to be created
    *a    make_companion_of_all - pass 1 to make this crowd a companion
    *a                            of all existing crowds
    **
    *b  Returns:
    **
    **    pointer of type diguyCrowd
    */
   diguyCrowd* create_crowd(const char* name,
      int make_companion_of_all = 1);

   /*l
    *b  Description:
    **
    **    This function destroys a crowd.  It can also optionally destroy the
    **    characters that are crowd members, and the path shape that is
    **    associated with the crowd.
    **
    *b  Arguments:
    **
    *a    crowd                      - pointer to a diguyCrowd
    *a    also_destroy_crowd_members - pass 1 to also destroy crowd member
    *a                                 characters
    *a    also_destroy_path_shapes   - pass 1 to also destroy crowd-
    *a                                 associated path shapes
    *a    delay_destruction          - pass 1 to wait till the next update
    *a                                 call to destroy the crowd; can avoid
    *a                                 crashes when AI's receive destruction
    *a                                 messages
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int destroy_crowd(diguyCrowd* crowd,
      int also_destroy_crowd_members = 0,
      int also_destroy_path_shapes = 0,
      int delay_destruction = 0);

   /*l
    *b  Returns:
    **
    **    the number of crowds in the scenario
    */
   int get_num_crowds();

   /*l
    *b  Returns:
    **
    **    pointer of type diguyCrowd; NULL if no crowd at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the crowd; indices start at 0
    */
   diguyCrowd* get_crowd_at_index(int index);

   /*l
    *b  Returns:
    **
    **   A unique name based on base_name, e.g. "my_crowd7" from "my_crowd".
    **
    *b  Arguments:
    **
    *a   base_name - base string from which to build a unique name
    */
   const char* get_unique_crowd_name(const char* base_name);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified crowd.
    **
    *b  Arguments:
    **
    *a    name - name of crowd to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyCrowd; NULL if not found
    */
   diguyCrowd* find_crowd(const char* crowd_name);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the crowd with the given
    **    name.  A new crowd with the given name will be created if
    **    it doesn't already exist.
    **
    *b  Arguments:
    **
    *a    name                  - name of the crowd to find or create
    *a    make_companion_of_all - pass 1 to make this crowd a companion
    *a                            of all existing crowds
    **
    *b  Returns:
    **
    **    pointer of type diguyCrowd; should never be NULL
    */
   diguyCrowd* find_or_create_crowd(const char* crowd_name,
      int make_companion_of_all = 1);

   /*l
    *b  Description:
    **
    **    This function sets whether crowds should be created for
    **    incoming network entities.
    **
    *b  Arguments:
    **
    *a    do_create - pass 1 to create network crowds; 0 to not
    */
   void set_create_network_crowds(int do_create);

   /*l
    *b  Returns:
    **
    *a    1 if network crowds will be created; 0 if not
    **
    */
   int get_create_network_crowds();


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function creates a new crowd profile and returns a
    **    pointer to it.
    **
    *b  Arguments:
    **
    *a    name - name of crowd profile to be created
    **
    *b  Returns:
    **
    **    pointer of type diguyCrowdProfile
    */
   diguyCrowdProfile* create_crowd_profile(const char* name);

   /*l
    *b  Description:
    **
    **    This function destroys a crowd profile.
    **
    *b  Arguments:
    **
    *a    crowd_profile - pointer to a diguyCrowdProfile
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int destroy_crowd_profile(diguyCrowdProfile* crowd_profile);

   /*l
    *b  Returns:
    **
    **    The number of crowd profiles in the scenario.
    */
   int get_num_crowd_profiles();

   /*l
    *b  Returns:
    **
    **    pointer of type diguyCrowdProfile; NULL if no crowd profile
    **    at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the crowd profile; indices start at 0
    */
   diguyCrowdProfile* get_crowd_profile_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified crowd profile.
    **
    *b  Arguments:
    **
    *a    name - name of crowd profile to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyCrowdProfile; NULL if not found
    */
   diguyCrowdProfile* find_crowd_profile(const char* name);


/*****************************************************************************/
   /*l
    *b  Returns:
    **
    **    pointer of type diguyLoadManager; this scenario's character
    **    load manager
    */
   diguyLoadManager* get_character_load_manager();


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function forces the octtree to rebuild if it's out of date.
    */
   int force_octtree_generation();

   /*l
    *b  Description:
    **
    **    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 add_character_to_octtree(diguyCharacter* character,
      int use_bounding_box_only = 0);

   /*l
    *b  Description:
    **
    **    Removes the given character from the octtree.
    **
    */
   void remove_character_from_octtree(diguyCharacter* character);

   /*l
    *b  Description:
    **
    **    Preloads the given appearance for the character with octtree data.
    **    Uses more memory, but avoids needing to build data as characters are instantiated.
    **
    */
   int preload_octtree(const char* character_type, const char* appearance);

   /*l
    *b  Description:
    **
    **    This function uses the octtree to check if the path between x1,
    **    y1, z1 and x2, y2, z2 has any static obstructions.
    **
    *b  Returns:
    **
    **    1 if the path is clear, 0 if static obstructions are present.
    */
   int check_visibility(float x1, float y1, float z1,
      float x2, float y2, float z2);


/*****************************************************************************/
#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    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.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int set_default_character_altitude_function(diguyAltitudeFunction* altitude_function);

   /*l
    *b  Description:
    **
    **    This function sets a generic altitude function for the scenario
    **    that is used for local path clamping and other operations that
    **    require the altitude at specific x, y coordinates to be calculated.
    **    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.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   void set_altitude_function(diguyScenarioAltitudeFunction* altitude_function);

   /*l
    *b  Returns:
    **
    **    the altitude function for the scenario as set by
    **    set_altitude_function()
    **
    *b  Callable From:
    **
    *-    - C++
    */
   diguyScenarioAltitudeFunction* get_altitude_function();

#endif

   void set_altitude_max_climb(float altitude_max_climb);
   float get_altitude_max_climb();

   void set_altitude_max_drop(float altitude_max_drop);
   float get_altitude_max_drop();


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    Sets the default intersection function. This function will be used to determine
    **   whether there is an intersection between a specified ray and the world.
    */
   static void set_default_intersection_function(diguyScenarioIntersectionFunction* intersection_function);
   void set_intersection_function(diguyScenarioIntersectionFunction* intersection_function);

   /*l
    *b  Description:
    **
    **    Creates a detonation using the specified munition name.  If the
    **    DI-Guy networking module is enabled the detonation is broadcast
    **    over the network.
    **
    *b  Arguments:
    **
    *a    munition_name - name of the munition to detonate; this will
    *a                    potentially trigger special effects depending
    *a                    on the munition
    *a    x, y, z       - location of the detonation
    *a    attacker_name - this MUST be specified if the detonation is being
    *a                    broadcast over the network
    *a    radius_override - defaults to the data in the munition config file
    *a    broadcast_on_network - pass 0 to not broadcast detonation on DIS
    *a                           network
    *a    ground_clamp_impact - 13.2.1 change, make it posible to not ground clamp this,
    *a                          was default behavior :-(
    **
    **    Note: Overriding the detonation radius will NOT work on broadcast
    **    detonations since the override value is not transmitted.
    */
   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 );

   /*l
    *b  Description:
    **
    **    This function checks for intersection against characters in the
    **    specified view.
    **
    **    To check for intersections against both characters and scene
    **    objects, call get_intersection_at_screen_coords().
    **
    **    The returned diguyImpact pointer is owned by the scenario and
    **    should not be deleted.  It will remain valid until the next call
    **    to any one of the following functions:
    **
    *-      - find_character_at_screen_coords()
    *-      - get_impact_at_screen_coords()
    *-      - get_intersection_at_screen_coords()
    **
    *i    This function should only be called from a DI-Guy Scenario Plugin.
    **
    *b  Arguments:
    **
    *a    view   - view to check
    *a    sx, sy - view coordinates to check
    **
    *b  Returns:
    **
    **    pointer of type diguyImpact; NULL if no character intersected
    **
    *b  Callable From:
    **
    *-    - DI-Guy Scenario Plugin
    */
   diguyImpact* find_character_at_screen_coords(diguyView* view,
      float sx,
      float sy);

   /*l
    *b  Description:
    **
    **    This function creates an impact object based on the sx and sy in
    **    the specified view. This function will trigger an impact callback
    **    on individuals who are touched, (it will not however kill
    **    characters who don't have impact callbacks.
    **
    **    The returned diguyImpact pointer is owned by the scenario and
    **    should not be deleted.  It will remain valid until the next call
    **    to any one of the following functions:
    **
    *-      - find_character_at_screen_coords()
    *-      - get_impact_at_screen_coords()
    *-      - get_intersection_at_screen_coords()
    **
    *i    This function should only be called from a DI-Guy Scenario Plugin.
    **
    *b  Arguments:
    **
    *a    view   - view to check
    *a    sx, sy - view coordinates to check
    *a    use_octtree - use the octtree; will not test against all
    *a                  characters unless they are explicitly added,
    *a                  but much faster
    **
    *b  Returns:
    **
    **    pointer of type diguyImpact;
    **
    *b  Callable From:
    **
    *-    - DI-Guy Scenario Plugin
    */
   diguyImpact* get_impact_at_screen_coords(diguyView* view,
      float sx,
      float sy,
      int use_octtree = 0);

   /*l
    *b  Description:
    **
    **    This function checks for intersection against the world *and*
    **    characters in the specified view.  Unlike the function
    **    get_impact_at_screen_coords(), this function doesn't trigger
    **    callbacks; instead, it just fills out the impact info.
    **
    **    The returned diguyImpact pointer is owned by the scenario and
    **    should not be deleted.  It will remain valid until the next call to
    **    any one of the following functions:
    **
    *-      - find_character_at_screen_coords()
    *-      - get_impact_at_screen_coords()
    *-      - get_intersection_at_screen_coords()
    **
    *i    This function should only be called from a DI-Guy Scenario Plugin.
    **
    *b  Arguments:
    **
    *a    view        - view to check
    *a    sx, sy      - view coordinates to check
    *a    use_octtree - use the octtree; will not test against all
    *a                  characters unless they are explicitly added,
    *a                  but much faster
    **
    *b  Returns:
    **
    **    diguyImpact with the xyz location of the intersection; NULL if
    **    there was nothing to intersect there
    **
    *b  Callable From:
    **
    *-    - DI-Guy Scenario Plugin
    */
   diguyImpact* get_intersection_at_screen_coords(diguyView* view,
      float sx,
      float sy,
      int use_octtree = 0);

   /*l
    *b  Description:
    **
    **    This function checks for intersection against the world and returns
    **    basic collision results.
    **
    **    This function will only return valid results in environments where
    **    the DI-Guy geometry octtree is available; currently that is when
    **    using OpenGL and the DI-Guy flight geometry loader.  DI-Guy
    **    Scenario is such a case.
    **
    *b  Arguments:
    **
    *a    origin_x, origin_y, origin_z - starting location of the ray trace
    *a    dir_x, dir_y, dir_z          - direction of ray trace (should be normalized)
    *a    max_distance_to_test         - max distance ray will travel;
    *a      -1.0 will test an infinitely long ray
    *a    intersection_x, _y, and _z   - world location of intersection
    *a    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.
    **
    *b  Returns:
    **
    **    1 if intersection occurred, 0 if not.
    */
   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);

   /*l
    *b  Description:
    **
    **    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.
    **
    *b  Arguments:
    **
    *a    x, y, z - world location to ground clamp
    *a    valid   - optional pointer to get an explicit result if anything
    *a              was hit
    *a    use_altitude_function - pass 1 to use scenario altitude function
    *a                            (tried first)
    *a    use_octtree           - pass 1 to use internal octtree
    **
    *b  Returns:
    **
    **    new_z if ground clamp was possible, original z if not
    */
   float ground_clamp(float x, float y, float z,
      int* valid = NULL,
      int use_altitude_function = 1,
      int use_octtree = 0);


#ifdef CPLUSPLUS_ONLY

   /******************************************************
    **
    *4  Impact Callback Functions:
    **
    **  Unless otherwise specified, callable from:
    **
    *-    - C++
    *-    - Script
    */

   /*l
    *b  Description:
    **
    **    The following prototype should be used for the impact
    **    function:
    **
    *e     int impact_func(diguyImpact* impact,
    *e         float from_x,
    *e         float from_y,
    *e         float from_z,
    *e         float to_x,
    *e         float to_y,
    *e         float to_z,
    *e         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.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int set_fire_weapon_intersection_function(diguyScenarioFindImpactOnLineFunction* impact_function);

   /*l
    *b  Description:
    **
    **    This function sets an impact function that will be added to all new
    **    scenarios.  It can be overridden by an explicit call to
    **    diguyScenario::set_fire_weapon_intersection_function().  See that
    **    function for details.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   static void set_default_fire_weapon_intersection_function(diguyScenarioFindImpactOnLineFunction* impact_function);

#endif

   /*l
    *b  Description:
    **
    **    Most DI-Guy visual objects (e.g., characters, path shapes,
    **    waypoints) have a unique identified, or UID.  In many cases these
    **    UID values can be coded into 24-bit color values.  This can be
    **    useful for implementing some types of intersection detection
    **    functions, in which each visual object is rendered with a different
    **    color.
    **
    **    This function will take the passed color values and update internal
    **    DI-Guy state of which objects objects have been hit.
    **
    **    It will also return an impact record containing information a
    **    subset of that information.
    **
    **    This can include:
    **
    *-      - the hit character, if one was hit
    *-      - the hit link and shape of the character
    *-      - the hit scene object, if one was hit
    **
    **    Note that the returned impact pointer is owned by DI-Guy and is
    **    temporary.  The information you need from it should be immediately
    **    read, and the pointer should not be stored.
    */
   diguyImpact* map_color_to_impact(char r, char g, char b);

   /*l
    *b  Description:
    **
    **    When the callback with id diguyScenario::CALLBACK_ID_SCENE_OBJECT_IMPACT
    **    is called, this function will return the impact object containing
    **    information about that impact.
    **
    **    There may be multiple impacts that result from some operations.
    **    In this case this function should be called multiple times, until
    **    it returns NULL.  When processing of data from each successive
    **    impact is done, call set_last_impact_been_processed() to queue up
    **    the next impact object for processing.
    **
    **    The maximum number of unprocessed impacts is finite, and set by
    **    the function set_max_unprocessed_impacts().
    **
    **    Note that the returned impact pointers are owned by DI-Guy and are
    **    temporary.  The information you need from them should be
    **    immediately read, and the pointers should not be stored.
    */
   diguyImpact* get_last_env_impact_info();

   /*l
    *b  Description:
    **
    **    Reading of data from the last impact information will be considered
    **    complete when this function is called.
    */
   void set_last_impact_been_processed();

   /*l
    *b  Description:
    **
    **    This function will add the passed impact object to the list of
    **    impact objects to be processed by calls to
    **    get_last_env_impact_info().  An internal copy of the impact object
    **    is made.
    */
   void set_last_env_impact_info(const diguyImpact& impact);

   /*l
    *b  Description:
    **
    **    Sets the maximum number of unprocessed impacts there can be.
    **
    **    The unprocessed impact array is a first-in-first-out queue.  If an
    **    impact occurs that pushes the number of unprocessed impacts past
    **    this maximum number, earlier impacts will be dropped from the
    **    array.
    **
    **    The initial value is 10.
    */
   void set_max_unprocessed_impacts(int max_unprocessed_impacts);


#ifdef CPLUSPLUS_ONLY


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function sets a default point line of sight function that
    **    will be added to all new characters.  It can be overridden by an
    **    explicit call to diguyCharacter::set_point_los_function().  See
    **    that function for details.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int set_default_point_los_function(diguyPointLOSFunction* point_los_function);

   /*l
    *b  Description:
    **
    **    This function sets a default character line of sight function that
    **    will be added to all new characters.  It can be overridden by an
    **    explicit call to diguyCharacter::set_character_los_function().
    **    See that function for details.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int set_default_character_los_function(diguyCharacterLOSFunction* character_los_function);

   /*l
    *b  Description:
    **
    **    This function sets a default feeler function that will be added
    **    to all new DI-Guy AI agents.  It can be overridden by an explicit
    **    call to diguyCharacter::agent_set_feeler_function().
    **
    **    See the "User-Defined Feelers" section in diguyCharacter.h for
    **    more information.
    **
    *b  Arguments:
    **
    *a    feeler_function - pointer to user-defined feeler function
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int set_default_agent_feeler_function(diguyFeelerFunction* feeler_function);

#endif

   /*l
    *b  Description:
    **
    **    Experimental intersection-detection function.
    **
    *b  Arguments:
    **
    *a    origin_x,origin_y,origin_z - starting point
    *a    dir_x,dir_y,dir_z - direction vector
    *a    max_distance_to_test - distance to test to
    *a    use_callback - 1 to use
    **
    *b  Returns:
    **
    **    diguyIntersectionResult structure
    */
   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);

/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function returns a pointer to the region with the given
    **    name.  A new region with the given name will be created if
    **    it doesn't already exist.
    **
    *b  Arguments:
    **
    *a    name - name of the region to find or create
    **
    *b  Returns:
    **
    **    pointer of type diguyRegion; should never be NULL
    */
   diguyRegion* find_or_create_region(const char* name);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified region.
    **
    *b  Arguments:
    **
    *a    name - name of region to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyRegion; NULL if not found
    */
   diguyRegion* find_region(const char* name);

   /*l
    *b  Description:
    **
    **    This function creates a new diguyRegion and returns a pointer to
    **    it.
    **
    *b  Arguments:
    **
    *a    name - name of the new region object
    **
    *b  Returns:
    **
    **    pointer of type diguyRegion
    */
   diguyRegion* create_region(const char* name);

   /*l
    *b  Description:
    **
    **    This function destroys the passed region.
    **
    *b  Arguments:
    **
    *a    region - region to destroy
    */
   void destroy_region(diguyRegion* region);

   /*l
    *b  Returns:
    **
    **    number of regions in the scenario
    */
   int get_num_regions();

   /*l
    *b  Returns:
    **
    **    pointer of type diguyRegion; NULL if no region at the
    **    specified index
    **
    *b  Arguments:
    **
    *a    index - index of the region; indices start at 0
    */
   diguyRegion* get_region_at_index(int index);

   /*l
    *b  Description:
    **
    **    The scenario will attempt to create a navigation path on the
    **    via_region.  An A* path planning algorithm is used to find the
    **    path.  See also diguyCharacter::agent_move_to_point() and
    **    diguyCharacter::agent_move_to_point_via_subregions().
    **
    *b  Arguments:
    **
    *a    x1, y1, z1     - start location
    *a    x2, y2, z2     - end location
    *a    via_region     - name of the region to run A* on
    *a    path_shape     - path shape that stores the created path
    *a    preferred_subregions_mask - diguySubregionMask value of regions
    *a        preferred for travel
    *a    cost_bias_for_preferred_regions - how much cheaper it will be
    *a        to cross spaces that are part of desired subregion;
    *a          should be < 1.0
    *a    cost_bias_for_neutral_regions - how much more expensive it will be
    *a        to cross spaces that are not part of desired subregion; see
    *a        below for more information
    *a    repulsed_regions_mask - diguySubregionMask value of regions *not*
    *a        preferred for travel
    *a    cost_bias_for_repulsed_regions - how much more expensive it will be
    *a        to cross regions that are marked as repulsive; pass
    *a        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.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   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);

   /*l
    *b  Description:
    **
    **   Sets an upper limit on how far a character is willing to travel as
    **   a multiple of the straight line distance between point A and point
    **   B before declaring that it can't get to a location.
    **
    **   Note that internally the straight line distance is forced to have a
    **   lower bound of 10 meters, so a character is always willing to
    **   travel a minimum of 10 * max_distance_planning_multiplier meters.
    **
    **   Defaults to -1, which means off.
    */
   void set_max_distance_planning_multiplier(float mul);

   /*l
    *b  Returns:
    **
    **    float constant that's used to decide if planner should give up;
    **    -1 means off
    */
   float get_max_distance_planning_multiplier();

   /*l
    *b  Description:
    **
    **    This function returns in seconds how much time has been spent path
    **    planning during the current frame.  It can be used to avoid 100
    **    characters simultaneously hitting the path planner.
    **
    *b  Returns:
    **
    **    time in seconds
    */
   float get_time_spent_path_planning_this_frame();

   /*l
    *b  Description:
    **
    **    This function enables the path planner to run in a background
    **    thread.  Note this only occurs if the
    **    diguyCharacter::agent_move_to_point_bg() or
    **    diguyCharacter::agent_move_to_point_via_subregions_bg() api
    **    functions are used.
    **
    **    By default the multi-threaded path planner is on.
    */
   void set_multithreaded_path_planning_enabled(int value);
   /*l
    *b  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 get_multithreaded_path_planning_enabled();


/*****************************************************************************/
   /*l
    *b  Returns:
    **
    **    number of formations in the scenario
    */
   int get_num_formations();

   /*l
    *b  Returns:
    **
    **    pointer of type diguyFormation; NULL if no
    **    formation at the specified index
    **
    *b  Arguments:
    **
    *a    index - index of the formation; indices start at 0
    */
   diguyFormation* get_formation_at_index(int index);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the specified formation.
    **
    *b  Arguments:
    **
    *a    name - name of formation to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyFormation; NULL if not found
    */
   diguyFormation* find_formation(const char* name);

   /*l
    *b  Description:
    **
    **    This function returns a pointer to the first formation it finds of
    **    a given size.
    **
    *b  Arguments:
    **
    *a    size - size of formation to be found
    **
    *b  Returns:
    **
    **    pointer of type diguyFormation; NULL if not found
    */
   diguyFormation* find_formation_of_size(int size);

   /*l
    *b  Description:
    **
    **    This function creates a new formation and returns a
    **    pointer to it.
    **
    *b  Arguments:
    **
    *a    name - name of the new formation
    **
    *b  Returns:
    **
    **    pointer of type diguyFormation
    */
   diguyFormation* create_formation(const char* name);

   /*l
    *b  Description:
    **
    **    This function finds the formation with the given name or
    **    creates it if it doesn't exist.
    **
    *b  Arguments:
    **
    *a    name - name of the formation to find or create
    **
    *b  Returns:
    **
    **    pointer of type diguyFormation; should never be NULL
    */
   diguyFormation* find_or_create_formation(const char* name);

   /*l
    *b  Description:
    **
    **    This function destroys a formation.
    **
    *b  Arguments:
    **
    *a    formation - pointer to a diguyFormation
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int destroy_formation(diguyFormation* formation);


/*****************************************************************************/
   void set_draw_authoring_visuals(int visible);
   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();


/*****************************************************************************/
 /*l
   *b  Returns:
   **
   **  If weapon fire will show flash geometry, (depending on munition configuration)
   */
   int get_weapon_flash_enabled();

   /*l
    *b  Description:
    **
    **  Sets if weapon fire will create weapon geometry, (depending on munition configuration)
    */
   int set_weapon_flash_enabled(int enabled);

   /*l
    *b  Returns:
    **
    **  If weapon fire will create light flashes, smoke and shell ejections, (depending on munition configuration)
    */
   int get_weapon_fire_effects_enabled();

   /*l
    *b  Description:
    **
    **  Sets if weapon fire will create light flashes, smoke and shell ejections, (depending on munition configuration)
    */
   int set_weapon_fire_effects_enabled(int enabled);

   /*l
    *b  Returns:
    **
    **  The number of light flashes that are currently active
    */
   int get_num_active_fire_effects();

   /*l
    *b  Description:
    **
    **    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 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);

   int get_num_active_lights();

   int sort_active_lights();

   /*l
    *b  Description:
    **
    **    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 get_active_light_data(int index, diguyLightRenderDesc * light_desc);

/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    Sets the current selected character in scenario
    **
    *b  Returns:
    **
    **     0 on success, -1 on failure
    **/
   int set_current_character(diguyCharacter* current_character);

   /*l
    *b  Returns:
    **
    **    The current selected character in scenario
    **/
   diguyCharacter* get_current_character();

   int  get_current_character_index();

   /*l
    *b  Description:
    **
    **    Sets the current selected crowd in scenario
    **
    *b  Returns:
    **
    **     0 on success, -1 on failure
    **/
   int set_current_crowd(diguyCrowd* current_crowd);
   /*l
    *b  Returns:
    **
    **    The current selected crowd in scenario
    **/
   diguyCrowd* get_current_crowd();

   /*l
    *b  Description:
    **
    **    Sets the active crowd profile, which determines the attributes
    **   of subsequently-created crowds. See diguyCrowdProfile.
    **
    *b  Returns:
    **
    **     0 on success, -1 on failure
    **/
   int set_current_crowd_profile(diguyCrowdProfile* current_profile);
   /*l
    *b  Description:
    **
    **    Sets the active crowd profile by name.
    **
    *b  Returns:
    **
    **     0 on success, -1 on failure
    **/
   int set_current_crowd_profile_by_name(const char* crowd_profile_name);
   /*l
    *b  Returns:
    **
    **    Active crowd profile
    **/
   diguyCrowdProfile* get_current_crowd_profile();

   /*l
    *b  Description:
    **
    **    Sets the current region. See diguyRegion.
    **
    *b  Returns:
    **
    **     0 on success, -1 on failure
    **/
   int set_current_region(diguyRegion* current_region);
   /*l
    *b  Returns:
    **
    **    Current region.
    **/
   diguyRegion* get_current_region();


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function enables or disables the particle module.
    **    By default the particle module is enabled.
    */
   void set_particle_module_disabled(int disable_particle_module);

   /*l
    *b  Description:
    **
    **    This function creates a particle system with type description_name
    **    at x, y, z.  If duration is specified the system will automatically
    **    stop emitting after that amount of time.
    **
    *b  Arguments:
    **
    *a    description_name - name of particle description to create
    *a    x, y, z          - the world space position of the system
    *a    record_transient_event - pass 1 to have this particle system
    *a                             play in history playback
    *a    duration         - how long the emitter should emit; if -1 is
    *a                       specified then the description must have a
    *a                       lifetime specified
    */
   int create_particle_system(const char* description_name,
      float x, float y, float z,
      int record_transient_event = 1,
      float duration = -1.0f);

   /*l
    *b  Description:
    **
    **    Similar to create_particle_system(), but allows orientation to be set.
    **
    *b  Arguments:
    **
    *a    rz, rx, ry - orientation axes
    **
    **    (See create_particle_system() for other parameters)
    */
   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);

   /*l
    *b  Returns:
    **
    **    1 if the particle description named description_name exists,
    **    else 0
    */
   int has_particle_description(const char* description_name);

   /*l
    *b  Description:
    **
    **    Set wind velocity vector for particle system
    */
   void set_global_wind(float x, float y, float z);


/*****************************************************************************/
// These should probably be C++ only. Not sure how much they make sense for
//  exposure to the scripting languages, unless you want perl to call lua
//  via C++.

   /*l
    *b  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.
    **
    *b  Arguments:
    **
    *a    lua_object - a global lua object
    *a    field_name - name of the field; field_name can include ".",
    *a                 allowing retrieval of fields in complex data
    *a                 structures
    **/
   const char* lua_get_object_field_as_string(const char* lua_object,
      const char* field_name);

   /*l
    **
    *b  Description:
    **
    **      Runs a member function of a lua object.
    **
    *b  Arguments:
    **
    *a    lua_object    - a lua object in the global scope, object names with fields should be properly handled
    *a                    ie object.subobject.blah should get properly parsed
    *a    function_name - name of the function to call
    *a    argument      - optional string argument
    *a    has_return_string - if set to 1 function will pop the top value of
    *a                        the lua stack and return it as a string
    **
    *b  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* lua_evaluate_object_function(const char* lua_object,
      const char* function_name,
      const char* argument = NULL,
      int has_return_string = 0);

   /*l
    *b  Description:
    **
    **   A two argument version of lua_evaluate_object_function().
    */
   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);

   /*l
    *b  Description:
    **
    **   A three argument version of lua_evaluate_object_function().
    */
   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);

   /*l
    *b  Description:
    **
    **   A four argument version of lua_evaluate_object_function().
    */
   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);


   /*l
    *b  Description:
    **
    **    Executes a lua_object:state_manager() function call.  Useful for
    **    creating sleep-able coroutine based objects that aren't
    **    characters.
    **/
   int lua_send_message_to_object(const char* lua_object,
      const char* sender,
      const char* message_type,
      const char* message,
      const char* message_params = NULL);

#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    This function allows low level access to the lua_State pointer.
    **    This pointer can be used by a programmer to query and run functions
    **    on the Lua virtual machine. This object can also be used to
    **    register new C functions to lua, which allows you to instrument and
    **    create callbacks from script to your code.  See luaL_register
    **    on-line.
    **
    **    For more information on how the Lua C api works see:
    **    http://www.lua.org/pil/24.html
    **
    *b  NOTE:
    **
    **    Currently all scenarios share the same underlying Lua state object.
    **    This may cause issues in applications with multiple scenarios.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   void* get_lua_state();

   /*l
    *b  Description:
    **
    **    Mainly used to pass a qt pointer to lua so lqt can be used to
    **    modify/read from the widget. This requires the that the lqt package
    **    is loaded; see the lqt.lua utility package for more info.
    **
    *b  Arguments:
    **
    *a    lua_state  - a Lua_State pointer, might be the same as get_lua_state();
    *a                 depends if the calling function is inside a coroutine
    *a    class_name - class name should be a core class of qt with a star
    *a                 after it; i.e. "QWidget*" or "QLineEdit*"
    *a    ptr        - pointer to that is returned to the calling function in lua
    **
    *b  Callable From:
    **
    *-    - C++
    **
    *b  C++ Example:
    **
    *e     int push_graphics_view_to_lua(lua_State *L)
    *e     {
    *e        bdiQGraphicsView* graphics_view = get_primary_3d_window_graphics_view();
    *e        if (m_scenario->push_qt_pointer_to_lua(L, "QGraphicsView*", graphics_view) == -1)
    *e        {
    *e           return 0;
    *e        }
    *e        return 1;
    *e     }
    **
    ** Plug-in init code:
    **
    *e     lua_State* L = (lua_State*)scenario->get_lua_state();
    *e     if (L)
    *e     {
    *e        lua_register(L, "get_graphics_view", push_graphics_view_to_lua);
    *e     }
    **
    ** In lua:
    **
    *e     local graphics_view = get_graphics_view();
    **
    **/
   int push_qt_pointer_to_lua(void* lua_state,
      const char* class_name,
      void* ptr);

   /*l
    *b  Description:
    **
    **    The most open function calling function available, if this doesn't
    **    manage to accomplish what you need you probably want to start
    **    using the lua interpreter directly.
    **
    **    The type arguments are string versions of the type being sent to
    **    lua, options include:
    *>
    *-     - ''          - empty argument
    *-     - 'b' boolean - void* argument1 is assumed to be an int
    *-     - 'f' field   - void* argument1 assumed to be character string of
    *-                     a field of a global lua object; supports nested
    *-                     fields like foo.bar.a
    *-     - 's' string  - void* argument1 assumed to be character string
    *-     - 'd' double  - void* argument is assumed to be a double
    *-     - diguy...    - void* argument assumed to be a diguy class
    *-                     pointer ie "diguyCharacter", "diguyCrowd" (no
    *-                     star used for diguy classes)
    *-     - Q...*       - void* argument is assumed to be a pointer to a
    *-                     child of QObject; the class name should be a core
    *-                     class of qt with a star after it, e.g. "QWidget*"
    *-                     or "QLineEdit*"
    *<
    *b  Arguments:
    **
    *a    lua_object        - a global lua object
    *a    function_name     - name of the function to call
    *a    arg(1/2/3/4)_type - is the data type
    *a    argument(1/2/3/4) - void* pointers to data
    *a    has_return_string - if set to 1 function will pop the top value of
    *a                        the lua stack and return it as a string
    **
    *b  Returns:
    **
    **    NULL or string representation of lua_object:function_name(argument)
    **
    **    The returned string should be copied if it needs to be used later.
    **
    *b  Callable From:
    **
    *-    - C++
    **/
   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);

   /*l
    *b  Description:
    **
    **    Effectively the same as diguyScenario::lua_evaluate_object_function_4a_flex()
    **    but works on global functions.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   const char* lua_evaluate_global_function_4a_flex(const char* function_name,
      const char* arg_type, void* argument,
      const char* arg_type2, void* argument2,
      const char* arg_type3, void* argument3,
      const char* arg_type4, void* argument4,
      int has_return_string = 0);

#endif

   /*l
    *b  Description:
    **
    **    Prints a message to lua interpreter log object.  In DI-Guy
    **    Scenario this is sent to the AI Mind Editor and used to fill out
    **    the error log.  The Mind editor log parses debug.traceback()
    **    calls.
    **/
   int lua_log_printf(int notify_level, const char* string);

   /*l
    *b  Returns:
    **
    **    package meta data as a formatted string; useful for debugging,
    **    only valid inside DI-Guy Scenario
    */
   const char* dump_package_info(const char* package_name);

/*****************************************************************************/
   /*l
    **
    *b  Description:
    **
    **    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.
    **
    *b  Arguments:
    **
    *a    to_character      - the diguyCharacter to receive the message
    *a    from_character    - the diguyCharacter from whom the message originates
    *a    message_type      - should properly be "signal", but other settings may be used
    *a    message           - the actual name of the message, e.g. "detonation"
    *a    message_params    - comma-separated parameters, for use by the message handler
    **
    *b  Returns:
    **
    **    1 if message delivery successful, otherwise 0
    **
    *b  Callable From:
    **
    *-    - C++ and Lua
    **/
   int send_message(diguyCharacter *to_character,
      diguyCharacter *from_character,
      const char* message_type,
      const char* message,
      const char* message_params = NULL);

   /*l
    **
    *b  Description:
    **
    **      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.
    **
    *b  Arguments:
    **
    *a    from_character    - the diguyCharacter from whom the message originates
    *a    radius            - how far the broadcast goes (in meters) from the from_character
    *a    message_type      - should properly be "broadcast", but other settings may be used
    *a    message           - the actual name of the message, e.g. "detonation"
    *a    message_params    - comma-separated parameters, for use by the message handler
    **
    *b  Returns:
    **
    **    -1 for failure, >= 0 for number of successful receptions
    **
    *b  Callable From:
    **
    *-    - C++ and Lua
    **/
   int broadcast_message(diguyCharacter *from_character,
      float radius,
      const char* message_type,
      const char* message,
      const char* message_params = NULL);

   /*l
    **
    *b  Description:
    **
    **      Broadcasts a message to all diguyCharacters within named group, who
    **    are within given radius of the from_character. See comments for
    **    broadcast_message() above.
    **
    *b  Arguments:
    **
    *a    from_character    - the diguyCharacter from whom the message originates
    *a    group_name        - name of group to broadcast to
    *a    radius            - how far the broadcast goes (in meters) from the from_character
    *a    message_type      - should properly be "broadcast", but other settings may be used
    *a    message           - the actual name of the message, e.g. "detonation"
    *a    message_params    - comma-separated parameters, for use by the message handler
    **
    *b  Returns:
    **
    **    -1 for failure, >= 0 for number of successful receptions
    **
    *b  Callable From:
    **
    *-    - C++ and Lua
    **/
   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);

/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/

   /*l
    *b  Returns:
    **
    **    value set by last call to set_eval_decisions_as_scripts()
    */
   int get_eval_decisions_as_scripts();

   /*l
    *b  Description:
    **
    **    If called with an argument of 1, all decision beads and decision beads will
    **   be converted to scripts before being run.
    */
   void set_eval_decisions_as_scripts(int eval_decisions_as_scripts);

   /*l
    *b  Description:
    **
    **    Gets the point of impact with the world along specified line segment
    **
    *b  Returns:
    **
    **    pointer to diguyImpact object or NULL
    */
   diguyImpact* get_impact_on_line(float from_x,
      float from_y,
      float from_z,
      float to_x,
      float to_y,
      float to_z);

   /*l
    *b  Description:
    **
    **    Increments wait cursor counter. If non-zero, then wait cursor is displayed
    **   in DI-GUY scenario.
    */
   void wait_cursor_push();
   /*l
    *b  Description:
    **
    **    Decrements wait cursor counter.
    */
   void wait_cursor_pop();

   diguyParticleSystemRenderer * get_particle_renderer();

   void set_character_sorting_enabled(int enabled);
   int get_character_sorting_enabled();

#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    This function sets a generic node pointer that can later be
    **    retrieved by the get_graphics_api_node_ptr() call.  The pointer is
    **    otherwise not used.
    **
    *b  Arguments:
    **
    *a    node_ptr - generic void* pointer
    **
    *b  Callable From:
    **
    *-    - C++
    */
   void set_graphics_api_node_ptr(void* node_ptr);

   /*l
    *b  Returns:
    **
    **    pointer set by most recent call to set_graphics_api_node_ptr
    **
    *b  Callable From:
    **
    *-    - C++
    */
   void* get_graphics_api_node_ptr();

#endif

   /*l
    *b  Description:
    **
    **    Sets whether shadow disks are drawn for characters. Call with 1 to turn on,
    **   0 to turn off.
    */
   void set_draw_character_shadow_disks(int draw_character_shadow_disks);

   /*l
    *b  Returns:
    **
    **    1 if shadow disks are drawn, 0 if not
    */
   int  get_draw_character_shadow_disks();

   /*l
    *b  Returns:
    **
    **    size of texture map for shadows
    */
   int  get_shadow_map_size();

   /*l
    *b  Description:
    **
    **    Sets size of texture map for shadows. Defaults to 1024. Allowed values
    **   are powers of two up to 4096.
    */
   int  set_shadow_map_size(int shadow_size);

   /*l
    *b  Description:
    **
    **    Used for DI-Guy OSG Author Programming Example. Sets the default value
    **    used for characters. See also diguyCharacter::set_scene_graph_mask()
    */
   void          set_default_character_scene_graph_mask(unsigned long mask);
   unsigned long get_default_character_scene_graph_mask();

   /*l
    *b  Description:
    **
    **    Used for DI-Guy OSG Author Programming Example. Sets the default value
    **    used for characters. See also diguySceneObject::set_scene_graph_mask()
    */
   void          set_default_scene_object_scene_graph_mask(unsigned long mask);
   unsigned long get_default_scene_object_scene_graph_mask();

   /*l
    *b  Description:
    **
    **  For internal use.
    */
   void set_internal_int(int var, int val);
   void set_internal_float(int var, float val);

   /*l
    *b  Description:
    **
    **   This sets the number of point lights that get handed down to
    **   diguyGraphicsShaderTechnique::pick_shader_program().
    */
   int set_num_active_point_lights(int active_lights);

   /*l
    *b  Description:
    **   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 get_num_active_point_lights();

/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/

   /*l
    *b  Description:
    **
    **    Sets bounding box of world
    **
    *b  Arguments:
    **
    *a    x_min,y_min,z_min,x_max,y_max,z_max - bounds
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **    (float * arguments converted to return values in Lua)
    */
   int set_world_bounds(float x_min, float y_min, float z_min,
      float x_max, float y_max, float z_max);

   /*l
    *b  Description:
    **
    **    Gets bounding box of world
    **
    *b  Arguments:
    **
    *a    x_min,y_min,z_min,x_max,y_max,z_max - output parameters
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **    (float * arguments converted to return values in Lua)
    */
   int get_world_bounds(float* x_min, float* y_min, float* z_min,
      float* x_max, float* y_max, float* z_max);



/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/

   /*l
    *b  Description:
    **
    **  Internal use
    */
   void set_checkpoint_frequency(float freq);
   /*l
    *b  Description:
    **
    **  Internal use
    */
   float get_checkpoint_frequency();
   /*l
    *b  Description:
    **
    **  Internal use
    */
   void set_checkpointing_enabled(int enable_checkpointing);
   /*l
    *b  Description:
    **
    **  Internal use
    */
   int get_checkpointing_enabled();

   // should be removed, only for testing
   //void checkpoint();
   //void load_checkpoint();

/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/

   /*l
    *b  Description:
    **
    **    Sets initial render mode
    **
    *b  Arguments:
    **
    *a    render_mode - string containing render mode setting name
    **
    **  Built-in render modes:
    **
    *-    "normal"
    *-    "shadow"
    *-    "glow"
    *-    "alternate1"
    *-    "alternate2"
    *-    "alternate3"
    */
   void set_initial_render_mode(const char* render_mode);

   /*l
    *b  Returns:
    **
    **    initial render mode, as string
    **
    */
   const char* get_initial_render_mode();

   /*l
    *b  Description:
    **
    **    Sets current render mode. See set_initial_render_mode()
    **
    */
   void set_current_render_mode(const char* render_mode);

   /*l
    *b  Returns:
    **
    **    render mode, as string, derived from current light settings
    **
    *b  Arguments:
    **
    *a    set_current_to_derived - if 1, current render mode becomes derived
    *-                             mode
    **
    */
   const char* derive_render_mode_from_light_settings(int set_current_to_derived = 1);

   const char* get_current_render_mode();

   /*l
    *b  Description:
    **
    **    Sets default shader for characters
    **
    *b  Arguments:
    **
    *a    render_mode - string containing render mode name
    *a    shader_name - string containing name of shader technique
    *-                  (there should be a _glsl.cfg file of the same name)
    *a    update_existing_characters - if 1, all existing characters will now
    *-                  be drawn using this shader
    */
   void set_default_character_shader(const char* render_mode,
      const char* shader_name,
      int update_existing_characters = 1);

   const char* get_default_character_shader(const char* render_mode);

   /*l
    *b  Description:
    **
    **    Sets default shader for scene objects
    **
    *b  Arguments:
    **
    *a    render_mode - string containing render mode name
    *a    shader_name - string containing name of shader technique
    *-                  (there should be a _glsl.cfg file of the same name)
    *a    update_existing_scene_objects - if 1, all existing scene objects will now
    *-                  be drawn using this shader
    */
   void set_default_scene_object_shader(const char* render_mode,
      const char* shader_name,
      int update_existing_scene_objects = 1);

   const char* get_default_scene_object_shader(const char* render_mode);

   /*l
    *b  Description:
    **
    **    Sets default shader for particle systems
    **
    *b  Arguments:
    **
    *a    render_mode - string containing render mode name
    *a    shader_name - string containing name of shader technique
    *-                  (there should be a _glsl.cfg file of the same name)
    *a    update_existing_particle_systems - if 1, all existing particle systems will now
    *-                  be drawn using this shader
    */
   void set_default_particle_system_shader(const char* render_mode,
      const char* shader_name,
      int update_existing_particle_systems = 1);

   const char* get_default_particle_system_shader(const char* render_mode);

   /*l
    *b  Description:
    **
    **    Sets FaceFX animation set for a given actor.
    **
    *b  Arguments:
    **
    *a    actor_name - actor's name
    *a    file_name - fully qualified file name ending in ".animset_ingame"
    */
   int facefx_mount_animset(const char* actor_name, const char* file_name);

   /*l
    *b  Description:
    **
    **    Sets vehicle smoothing on or off. If 1, vehicle will be updated
    **   at a higher rate than frame dt
    **
    **    Default is on.
    */
   int set_vehicle_smoothing_enabled(int enable_smoothing);
   int get_vehicle_smoothing_enabled();

   /*l
    *b  Description:
    **
    **    Sets realtime IK on or off. Experimental.
    **
    */
   int set_realtime_ik_enabled( int val );
   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()
   {
      if ( m_last_update_time == -9999.0f )
      {
         return 0.0f;
      }
      return m_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);


/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/

   int get_character_type_num_head_appearances( const char* character_type );

   const char* get_character_type_head_appearance_at_index( const char* character_type, int index );

#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    Deprecated; use diguyApp::add_default_scenario_callback() instead.
    */
   static int add_default_callback(int callback_id,
      diguyScenarioCallback* callback,
      void* callback_params = 0,
      void* callback_user_data = 0);

   /*l
    *b  Description:
    **
    **    Deprecated; use diguyApp::remove_default_scenario_callback() instead.
    */
   static int remove_default_callback(int callback_id,
      diguyScenarioCallback* callback);

#endif

   /*l
    *b  Description:
    **
    **    Deprecated;
    **    use diguyApp::remove_default_scenario_callback_with_User_data()
    **    instead.
    */
   static int remove_default_callback_with_user_data(int callback_id,
      void* callback_user_data);

   /*l
    *b  Description:
    **
    **    Deprecated; use diguyApp::add_default_scenario_callback_script()
    **    instead.
    */
   static int add_default_callback_script(int callback_id,
      const char* callback_script,
      const char* callback_script_type);

   /*l
    *b  Description:
    **
    **    Deprecated; use diguyApp::remove_default_scenario_callback_script()
    **    instead.
    */
   static int remove_default_callback_script(int callback_id,
      const char* callback_script,
      const char* callback_script_type);

   /*l
    *b  Description:
    **
    **    Deprecated as of 10.0.0; use get_character_type_map() intead,
    **    and then call
    **    diguyCharacterTypeMap::get_field_value(DIGUY_CHARACTER_TYPE_MAP_FIELD_CHARACTER_CLASS)
    */
   const char* get_character_type_class(const char* character_type);

   /*l
    *b  Description:
    **
    **    Deprecated as of 10.5.1; use merge_object() intead.
    */
   int merge_asset(const char* string);

   /*l
    *b  Description:
    **
    **    Deprecated as of 12.0.0; use bdi_log_print() from libbdilog.h
    **    instead.
    */
   void print_to_log(int notify_level, const char* string);


#ifdef CPLUSPLUS_ONLY

   /*
    *2  VegaPrime Helper Functions
    */
   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);

   /*l
    *b  Description:
    **
    **    Deprecated as of 12.0.0; use save_as() instead.
    */
   void set_project_filename(const char* project_filename);

   /*l
    *b  Description:
    **
    **    Deprecated as of 12.0.0; use get_filename() or
    **    get_filename_without_directory() intead.
    */
   const char* get_project_filename();

   bdiScenario* get_scripted_object();


private:

   /*l
    **    A private constructor.  Use the DI-Guy function
    **    diguy_create_scenario() to obtain a diguyScenario object pointer.
    */
   diguyScenario(bdiScenario* scenario);

   /*l
    **    A private destructor.  Use the DI-Guy function
    **    diguy_destroy_scenario() to delete a diguyScenario object pointer.
    */
   virtual ~diguyScenario();

   /*l
    **    A pointer to internal data.
    */
   bdiScenario* m_scenario;
   float m_last_update_time;

   friend class bdiScenario;

#endif

};