diguyScenario.h

Go to the documentation of this file.

/****************************************************************************
 * Copyright (c) 2022 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 hand item class associated with a 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 = NULL);

        /*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:
         **
         **    0 on success, -1 on failure
         **
         */
        int 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_dependancy( 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 posture; 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 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

};