diguyCharacter.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2015 VT MAK
 ** All rights reserved. 
 *********************************************************************/

/*********************************************************************
 **
 *t  diguyCharacter
 **
 *b    Link against: libdiguy
 */

#ifndef __diguyCharacter_H
#define __diguyCharacter_H

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

#ifdef CPLUSPLUS_ONLY
#include <declspec_diguy.h>
#include <diguy_constants.h>
#include <diguy_typedefs.h>
#include <diguy_vector_classes.h>
#include <diguyConnectionPointType.h>
#include <diguyCharacterPoseOverride.h>
#include <diguyCharacterTypeMap.h>
#include <diguyMotionDirection.h>
#include <diguyMotionPosture.h>
#include <diguyMotionVariant.h>

class bdiScenarioCharacter;
class diguyAgentParams;
class diguyChainSimulation;
class diguyCharacter;
class diguyCharacterGuide;
class diguyCharacterGesture;
class diguyCharacterGroup;
class diguyCharacterPath;
class diguyCharacterPathAimBead;
class diguyCharacterPathDecisionBead;
class diguyCharacterPathGazeBead;
class diguyCharacterPathScriptBead;
class diguyCrowd;
class diguyGraphicsLink;
class diguyGraphicsShaderProgram;
class diguyGraphicsShaderInstance;
class diguyViewLabel;
class diguyPathShape;
class diguyScenario;
class diguyWaypoint;
class diguySoundInstance;
class diguyImpact;
class diguyVariable;
class diguyVehicleController;
class diguyView;
class DtEntityStateRepository;
struct diguyMotionEngineSnapshot;
enum diguyConnectionPointType;

#endif


/****************************************************************************/
class BDI_DECLSPEC_diguy diguyCharacter
{

public:

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

        /*l
         *b  Description:
         **
         **    This function sets the name of this object.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_name(const char* name);

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

        /*l
         *b  Description:
         **
         **    All characters are assigned a unique identifier, or uid.  This
         **    function returns this character's uid.
         **
         **    *Note*: unique identifiers will change between DI-Guy runs!
         **
         */
        long get_uid();

        /*l
         *b  Description:
         **
         **    Returns the index of the object.  This index may change if
         **    characters are created or destroyed, so it should not be considered
         **    a unique identifier for the character.  See get_uid().
         */
        int get_index();

        /*l
         *b  Description:
         **
         **    This function updates the character.  The character's position and
         **    pose will be set to be what it will be (or was) at the specified t.
         **
         **    If the scenario has control of t (return value of
         **    get_t_controlled_by_scenario_t() is 0), then this function's
         **    effects will be overridden the next time diguyScenario::update() is
         **    called with a new t.
         **
         **    Note: diguyScenario::update() must be called as or more frequently
         **    than diguyCharacter::update() for proper DI-Guy operation.  
         **    diguyCharacter::update() is intended for load management use, where 
         **    the user intends to update far away or out-of-frustum characters 
         **    less frequently than the overall scenario.  This is done in con-
         **    junction with set_t_controlled_by_scenario_t(0) for the character.
         **    diguyCharacter::update() is not intended as a replacement for
         **    diguyScenario::update().
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Arguments:
         **
         *a    t           - new time for the character
         *a    full_update - set to 1 to cause full update of character
         */
        int update(float t, int full_update = 1);

        /*l
         *b  Description:
         **
         **    This function sets the current type of this character.
         **
         *b  Arguments:
         **
         *a    type - name of the new desired type
         **
         *b  See Also:
         **
         **    get_character_type_string()
         */
        void set_character_type(const char* type);

        /*l
         *b  Description:
         **
         **    Returns the type of the character (never NULL).
         **
         **    Character types specify the types of motions the character will be
         **    able to perform.  Some characters can move like soldiers, others
         **    can move like civilians, still others can move like specific
         **    animals.
         **
         **    The character type is explicitly specified in the call to
         **    diguyScenario::create_character().
         **
         **    Examples of character types are:
         *>
         *-    - soldier
         *-    - male_pedestrian
         *-    - horse
         *-    - prop
         *<
         */
        const char* get_character_type_string();

        /*l
         *b  Description:
         **
         **    Returns the class of the character (never NULL).
         **
         **    Character classes are a higher level description than character
         **    types, and allow for more generalized logic.  For example, instead
         **    of having something happen when one of a large set of specific
         **    character types enters a region, something can happen when any
         **    human enters the region.
         **
         **    Character classes are not specified directly, but are instead
         **    derived from the character type.  (In DI-Guy, all soldiers are
         **    humans, for example.)
         **
         **    Examples of character classes are:
         *>
         *-    - human
         *-    - vehicle
         *-    - object
         *-    - animal
         *<
         */
        const char* get_character_class();

        diguyCharacterClass get_character_class_type();

        /*l
         *b  Description:
         **
         **    Returns the scenario that this character is a part of.
         */
        diguyScenario* get_scenario();

        /*l
         *b  Description:
         **
         **    This is the top-level on/off switch for the character.  A character
         **    that is not enabled has very little processing overhead: it is
         **    neither updated during an update() call, nor is it drawn during a
         **    draw() call.  A disabled character will remain disabled until
         **    set_enabled(1) is called on it; nothing else implicitly re-enables
         **    the character.
         **
         **    There are several other diguyCharacter functions that have somewhat
         **    similar effects that may be more appropriate at times:
         **
         *-    - set_current_tin() and set_current_tout(): These functions
         *-      show and animate the character starting at time tin ("T In"),
         *-      and ending at time tout ("T Out")
         *-    - set_invisible_flag(): This function disables drawing of
         *-      the character, but the character still updates and changes
         *-      position.
         **
         **    Refer to the documentation of these functions for more information.
         **
         *b  Returns:
         **
         **    always return 0
         */
        int set_enabled(int enabled);

        /*l
         *b  Description:
         **
         **    Returns whether the character is enabled, as set by the
         **    set_enabled() call.  New characters are enabled by default.
         **
         *b  Returns:
         **
         **    1 if the character is enabled, 0 if not
         */
        int get_enabled();

        /*l
         *b  Description:
         **
         **    Sets whether this character is drawn automatically by the scenario.
         **
         **    Note depending on the rendering environment if this flag is set to 0, 
         **    it is up to the user to call the character draw_pass1() and draw_pass2() 
         **    calls at the appropriate time.
         **
         *b  Arguments:
         **
         *a    flag - pass 1 for character drawing to automatically be
         *a           handled by scenario (this is the default);
         *a           0 for it not to be
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_drawn_by_scenario_flag(int flag);

        /*l
         *b  Description:
         **
         **    Returns whether character drawing is done automatically by the
         **    scenario.
         **
         *b  Returns:
         **
         **    1 if character drawing is done by the scenario;
         **    0 if not
         **
         *b  See Also:
         **
         **    set_drawn_by_scenario_flag()
         */
        int get_drawn_by_scenario_flag();

        /*l
         *b  Description:
         **
         **    This function makes the character invisible; i.e., draw() calls
         **    for the character will have no effect.  Note that the character
         **    will still update its position and pose during update() calls.  To
         **    more thoroughly disable a character, consider the functions
         **    set_enabled() and set_current_tout().
         **
         *b  Arguments:
         **
         *a    invisible_flag - pass 1 to make character invisible, 0 to
         *a                     make it visible
         **
         *b  Available as Decision Bead/Event
         */
        void set_invisible_flag(int invisible_flag);

        /*l
         *b  Returns:
         **
         **    the character's invisible flag, as set by set_invisible_flag()
         */
        int get_invisible_flag();

        /*l
         *b  Description:
         **
         **    Returns whether the character is active.  A character is
         **    active if:
         **
         *-    - it is enabled as per the set_enabled() call
         *-    - it is within its tin/tout interval as set by the
         *-      set_current_tin() and set_current_tout() calls
         *-    - it is not "network paused" (get_is_network_paused()
         *-      returns 0)
         **
         *b  Returns:
         **
         **    1 if the character is active, 0 if not
         **
         *b  Available as Decision Bead
         */
        int get_is_active();

        /*l
         *b  Description:
         **
         **    Returns whether the character will be drawn during scenario and
         **    character draw() calls.  A character will be drawn if:
         **
         *-      - it is enabled as per the set_enabled() call
         *-      - it is within its tin/tout interval as set by the
         *-        set_current_tin() and set_current_tout() calls
         *-      - its invisible flag is 0, as set by the
         *-        set_invisible_flag() call
         **
         **    There is no corresponding set_is_drawn() function; use
         **    set_invisible_flag() to explicitly make a character not be drawn.
         **
         *b  Returns:
         **
         **    1 if the character will be drawn, 0 if not
         */
        int get_is_drawn();

        int get_was_drawn_last_frame();
        
        int set_was_drawn_last_frame(int drawn);
        
        int get_is_culled();
        
        int set_is_culled(int culled);

        /*l
         *b  Returns:
         **
         **    1 if the character is temporary (created by diguyScenario::create_temporary_character() 
         **    call; 0 if not
         */
        int get_is_temporary();

        /*l
         *b  Description:
         **
         **    This function returns 1 if the character has been recycled from the
         **    character recycle bin, 0 if not.
         **
         **    See diguyScenario::send_character_to_recycle_bin()
         **    and diguyScenario::retrieve_character_from_recycle_bin().
         */
        int get_is_recycled();

        /*l
         *b  Description:
         **
         **    This function sets how the character's t (time) is controlled.  If
         **    1, the character's t will be set by the scenario on each call to
         **    diguyScenario::update().  If 0, the character should be updated by
         **    calls to update().
         **
         *b  Arguments:
         **
         *a    t_controlled_by_scenario_t - 1 for controlled by scenario, 0 for
         *a                                 manual update
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_t_controlled_by_scenario_t(int t_controlled_by_scenario_t);

        /*l
         *b  Returns:
         **
         **    whether character's t is controlled by the scenario;
         **    see set_t_controlled_by_scenario_t()
         */
        int get_t_controlled_by_scenario_t();

        /*l
         *b  Description:
         **
         **    This function sets the initial tin ("T In") time of the character.
         **    See set_current_tin() for a discussion of how tin and tout times
         **    affect the character.
         **
         **    When the scenario is reset or loaded from a .dss file, the current
         **    tin value will be set to this initial tin value.
         **
         **    Note that this function cannot be called once the scenario has
         **    begun running (diguyScenario::get_t() returns > 0).
         **
         **    Note that both tin and tout times are scenario-relative times, not
         **    character-relative.
         **
         **    This call makes an implicit call to set_current_tin() with the
         **    same value.
         **
         *b  Arguments:
         **
         *a    tin - new value of initial tin in seconds
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_initial_tin(float tin, int override_time_warning = 0);

        /*l
         *b  Description:
         **
         **    This function sets the initial tout ("T Out") time of the
         **    character.  See set_current_tin() for a discussion of how tin and
         **    tout times affect the character.
         **
         **    When the scenario is reset or loaded from a .dss file, the current
         **    tout value will be set to this initial tout value.
         **
         **    Note that this function cannot be called once the scenario has
         **    begun running (diguyScenario::get_t() returns > 0).
         **
         **    Note that both tin and tout times are scenario-relative times, not
         **    character-relative.
         **
         **    This call makes an implicit call to set_current_tout() with the
         **    same value.
         **
         *b  Arguments:
         **
         *a    tout - new value of initial tout in seconds
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_initial_tout(float tout);

        /*l
         *b  Description:
         **
         **    This function sets the current tin ("T In") time of the character.
         **    The character will not be visible nor will it start moving or
         **    animating until the scenario reaches this time.
         **
         **    There are two ways the tin and tout times of the character can be
         **    used:
         **
         **    The first is to set them to their desired values when the scenario
         **    begins.  If, for example, it is known that this character should
         **    only be visible and active from 60 seconds to 80 seconds, the tin
         **    and tout times can be set to 60 and 80, respectively.  The
         **    scenario will then spend very little time for character updates
         **    and draws outside of these limits.
         **
         **    The second is to use them to quickly "trigger" a character to
         **    become visible and start moving.  This is done by setting the
         **    initial values of tin and tout to very high values, and then
         **    changing them to lower values when the character should become
         **    active.  Consider the following example:  This character is
         **    waiting just inside a doorway, and should emerge when another
         **    character comes close.  If the tin time of the character is very
         **    high, very little time will be taken for this character's updates
         **    and draws.  When the other character does come close, this
         **    character's tin time can be set to "now" (the scenario's current
         **    t, as returned by diguyScenario::get_t()).  This character will
         **    then become visible and start moving out of the doorway.
         **
         **    The default current tin time is the current time of the scenario
         **    when the character is created.
         **
         **    Note that both tin and tout times are scenario-relative times, not
         **    character-relative.
         **
         *b  Arguments:
         **
         *a    tin - new value of current tin in seconds
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_current_tin(float tin);

        /*l
         *b  Description:
         **
         **    Same as set_current_tin(), but time is set to current scenario time.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int set_current_tin_to_now();

        /*l
         *b  Description:
         **
         **    This function returns the current tin time of the character.  See
         **    set_current_tin().
         **
         *b  Returns:
         **
         **    Current tin time in seconds.
         */
        float get_current_tin();

        /*l
         *b  Description:
         **
         **    This function sets the current tout ("T Out") time of the
         **    character.  If tout is enabled the character will become invisible
         **    and will stop moving and animating when the scenario reaches this
         **    time.
         **
         **    Note that both tin and tout times are scenario-relative times, not
         **    character-relative.
         **
         **    Default tout time is 60000 seconds.
         **
         *b  Arguments:
         **
         *a    tout - new value of current tout in seconds
         *a    disable_character_at_tout - this argument is present to keep
         *a                                the function prototype will remain
         *a                                backward compatible; it has no effect
         */
        int set_current_tout(float tout,
                int disable_character_at_tout = 0);

        /*l
         *b  Description:
         **
         **    Same as set_current_tout(), but time is set to current scenario
         **    time.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead
         */
        int set_current_tout_to_now();

        /*l
         *b  Description:
         **
         **    This function returns the current tout ("T Out") time of the
         **    character in seconds.  See set_current_tout().
         */
        float get_current_tout();

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

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

        /*l
         *b  Description:
         **
         **    When the motion data of a character is interpolated a quick
         **    interpolation method can be used which may yield incorrect results,
         **    or an expensive interpolation method can be used which will yield
         **    correct results at the expense of time.  The threshold at which
         **    the interpolation method changes is specified by this function.
         **
         *b  Arguments:
         **
         *a    threshold - float between 0 (careful never) and 1 (careful always);
         **                default is 0.7
         **
         **    DI-Guy compares the careful interpolation threshold to the cosine
         **    of an angle.  Both the threshold and the cosine are dimensionless
         **    and thus have no units.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_careful_interpolation_threshold(float threshold);

        /*l
         *b  Returns:
         **
         **    most recent setting of the careful interpolation threshold;
         **    see set_careful_interpolation_threshold()
         */
        float get_careful_interpolation_threshold();

        /*l
         *b  Description:
         **
         **    Sets whether the motion data of the character is interpolated.
         **    Interpolation is disabled by default for better performance.  For
         **    applications achieving high frame rates, smoother motion may be
         **    achieved by turning interpolation on.
         **
         *b  Arguments:
         **
         *a    flag - 0 by default
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_motion_interpolation_flag(int flag);

        /*l
         *b  Returns:
         **
         **    most recent setting of the motion interpolation flag; see
         **    set_motion_interpolation_flag()
         */
        int get_motion_interpolation_flag();

        /*l
         *b  Description:
         **
         **    Sets the scale of the character on each of the three major axes.
         **
         *b  Arguments:
         **
         *a    scale_x, scale_y, scale_z - the factor by which to scale along
         *a                                the given axis
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_scale(float scale_x, float scale_y, float scale_z);

        /*l
         *b  Description:
         **
         **    Returns the scale of the character.
         **
         *b  Arguments:
         **
         *a    sx, sy, sz - scale of the character along each axis
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_scale(float* scale_x, float* scale_y, float* scale_z);

        /*l
         *b  Description:
         **
         **    Sets the parent of this character to be the passed character.
         **    This means that the coordinate system of this character will be
         **    local to the parent character rather than the world coordinate
         **    system.
         **
         *b  Arguments:
         **
         *a    parent_name      - character to which this character should
         *a                       be attached; pass NULL to have no parent
         *a                       and be attached to the world
         *a    parent_link_name - name of the link or connection point to which this character's
         *a                       position link should attach; pass "" to attach
         *a                       to the parent's position link
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int set_parent(const char* parent_name, const char* parent_link_name = "");

        /*l
         *b  Description:
         **
         **    Gets the parent of this character.
         **
         *b  Returns:
         **
         **    pointer to type diguyCharacter; NULL if no parent
         **
         *b  Available as Decision Bead/Event
         */
        diguyCharacter* get_parent();

        /*l
         *b  Description:
         **
         **    Gets the link name that the character is parented to, if any.
         **
         *b  Returns:
         **
         **    name of link, NULL if no parent
         */
        const char* get_parent_link_name();

        /*l
         *b  Description:
         **
         **    Detaches a character from its parent and reattaches it to the
         **    world.  This is equivalent to diguyCharacter::set_parent(NULL).
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int unset_parent();

        /*l
         *b  Description:
         **
         **    Gets the number of children the character has.
         */
        int get_num_children();

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the nth child of the character.
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacter; NULL if no
         **    child at the specified index
         **
         *b  Arguments:
         **
         *a    index - index of the child; indices start at 0
         */
        diguyCharacter* get_child_at_index(int index);

        /*l
         *b  Description:
         **
         **    Gets if a character is a static object, by default any blitzed .
         **    in props are.
         **
         *b  Returns:
         **
         **    1 if true, 0 if false
         */
        int get_is_scene_object();

        /*l
         *b  Description:
         **
         **    Sets if a character is a static object.  By default any blitzed
         **    in props are.
         **
         *b  Arguments:
         **
         *a    is_scene_object - pass 1 to make the object a scene object,
         *a                      0 to not
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_is_scene_object(int is_scene_object);

        /*l
         *b  Description:
         **
         **    Gets the bounding radius currently used for this character
         **    for purposes of culling it from the draw operation.
         **
         *b  Returns:
         **
         **    The current draw-culling bounding radius for the character, in
         **    meters.
         */
        float get_bounding_radius();

        /*l
         *b  Description:
         **
         **    Gets the default draw-culling bounding radius for this
         **    character, as specified in its actor cfg file.  See
         **    actor_vehicle.cfg for an example.
         **
         *b  Returns:
         **
         **    The default draw-culling bounding radius for the character.
         */
        float get_default_bounding_radius();

        /*l
         *b  Description:
         **
         **    Sets the current draw-culling bounding radius to be used for
         **    this character.
         */
        void set_bounding_radius(float f);

        /*l
         *b  Description:
         **
         **    This function returns the number of seconds before the blend
         **    into the next motion begins.  If the character is already
         **    in a blend between motions the function returns 0.
         **
         **    Note that this function is of limited practical use; in most
         **    cases get_time_to_reach_desired_action() returns
         **    information that is more useful.
         **
         *b  Returns:
         **
         **    time to next blend, in seconds
         **
         *b  Mode Restrictions:
         **
         *-    - This function can only be called in free action mode.
         */
        float get_time_to_transition();

        /*l
         *b  Returns:
         **
         **    the action mode of the character
         */
        diguyCharacterMode get_action_mode();

        /*l
         *b  Returns:
         **
         **    the position mode of the character
         */
        diguyCharacterMode get_position_mode();

        /*l
         *b  Description:
         **
         **    This function speeds up or slows down the character.  Setting
         **    this value greater than 1 will cause character actions to
         **    be played back at a slower pace, setting to less that 1 will
         **    cause character actions to be played at a faster pace.
         **
         **    This will override other factors that may scale the time
         **    scale factor of a character.  (For example, smaller scale
         **    characters will generally move faster.)
         **
         **    Call unset_t_scale_factor() to allow other factors such
         **    as scale or desired speed to determine the time scale factor.
         **
         *b  Mode Restrictions:
         **
         *-    - This function can only be called in free action mode.
         **
         *b  Arguments:
         **
         *a    t_scale_factor - time scale factor
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_t_scale_factor(float t_scale_factor);

        /*l
         *b  Description:
         **
         **    This function removes the manual setting of the time
         **    scale factor as set by set_t_scale_factor().
         **
         *b  Mode Restrictions:
         **
         *-    - This function can only be called in free action mode.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int unset_t_scale_factor();

        /*l
         *b  Description:
         **
         **    This function determines whether this character is within the
         **    specified distance of another.
         **
         *b  Arguments:
         **
         *a    character - character to be checked
         *a    distance  - distance to character in meters
         **
         *b  Returns:
         **
         **    1 if within distance; 0 if not
         */
        int is_within_distance_n_of_character(const char* character_name,
                float distance);

        /*l
         *b  Description:
         **
         **    This function determines whether this character is within the
         **    specified distance of any members of the specified group.
         **
         *b  Arguments:
         **
         *a    group_name - name of group to be checked
         *a    distance   - distance in meters
         **
         *b  Returns:
         **
         **    1 if member of group is within distance; 0 if not
         */
        int is_within_distance_n_of_member_of_group(const char* group_name,
                float distance);

        /*l
         *b  Description:
         **
         **    This function determines whether a character is a member of
         **    a particular group.
         **
         **    Also see diguyCharacterGroup::is_member().
         **
         *b  Arguments:
         **
         *a    group_name - name of group to be checked
         **
         *b  Returns:
         **
         **    1 if character is in group, 0 if not
         */
        int is_group_member(const char* group_name);

        /*l
         *b  Description:
         **
         **    This function returns the number of groups that a character is a
         **    member of.
         **
         **    Also see diguyCharacterGroup::is_member().
         */
        int get_num_group_memberships();

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the nth group that this
         **    character is a member of.
         **
         **    Also see diguyCharacterGroup::is_member().
         **
         *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_membership_at_index(int index);

        /*l
         *b  Description:
         **
         **    This function will check all characters in the scenario and return
         **    the nearest character that is both alive and enabled.  An optional
         **    argument specifies whether to skip characters that are invisible
         **    to the caller because a scene object is in the way.  Checking
         **    visibility is only an option if an octtree is generated from scene
         **    objects. Typically only DI-Guy Scenario does this.
         **
         *b  Arguments:
         **
         *a    check_visibility - whether to check that characters are
         *a                       visible to calling character; pass 1
         *a                       to check, 0 to not check
         *a    xy_distance      - whether to include the z component
         *a                       in distance calculations; pass 1 to
         *a                       check only XY distance, 0 to check
         *a                       XYZ distance
         **
         *b  Returns:
         **
         **   pointer of type diguyCharacter; may be NULL
         */
        diguyCharacter* get_nearest_active_character(int check_visibility,
                int xy_distance = 0,
                float max_distance_to_check = 100000);

        /*l
         *b  Description:
         **
         **    This function will check all characters in a group and return the
         **    nearest character that is both alive and enabled.  An optional
         **    argument specifies whether to skip characters that are invisible
         **    to the caller because a scene object is in the way.  Checking
         **    visibility is only an option if an octtree is generated from scene
         **    objects. Typically only DI-Guy Scenario does this.
         **
         *b  Arguments:
         **
         *a    group_name       - name of group to check
         *a    check_visibility - whether to check that characters are
         *a                       visible to calling character; pass 1
         *a                       to check, 0 to not check
         *a    xy_distance      - whether to include the z component
         *a                       in distance calculations; pass 1 to
         *a                       check only XY distance, 0 to check
         *a                       XYZ distance
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacter; may be NULL
         */
        diguyCharacter* get_nearest_active_character_in_group(const char* group_name,
                int check_visibility = 1,
                int xy_distance = 0,
                float max_distance_to_check = 100000);

        /*l
         *b  Description:
         **
         **    This function will check all characters in the scenario and return
         **    a random character within max_distance that is both alive and
         **    enabled. An optional argument specifies whether to skip characters
         **    that are invisible to the caller because a scene object is in the
         **    way. Checking visibility is only an option if an octtree is
         **    generated from scene objects. Typically only DI-Guy Scenario does
         **    this.
         **
         *b  Arguments:
         **
         *a    check_visibility - whether to check that characters are
         *a                       visible to calling character; pass 1
         *a                       to check, 0 to not check
         *a    max_distance     - how far away the search cut off should be pass
         *a                       in -1.0f to use all characters
         *a    xy_distance      - whether to include the z component
         *a                       in distance calculations; pass 1 to
         *a                       check only XY distance, 0 to check
         *a                       XYZ distance
         **
         *b  Returns:
         **
         **   pointer of type diguyCharacter; may be NULL
         */
        diguyCharacter* get_random_active_character(float max_distance = 10.0f,
                int check_visibility = 1,
                int xy_distance = 0);

        /*l
         *b  Description:
         **
         **    This function will check all characters in a group and return a
         **    random character within max_distance that is both alive and
         **    enabled. An optional argument specifies whether to skip characters
         **    that are invisible to the caller because a scene object is in the
         **    way. Checking visibility is only an option if an octtree is
         **    generated from scene objects. Typically only DI-Guy Scenario does
         **    this.
         **
         *b  Arguments:
         **
         *a    group_name       - name of group to check
         *a    max_distance     - how far away the search cut off should be, pass
         *a                       in -1.0f to use all characters
         *a    check_visibility - whether to check that characters are
         *a                       visible to calling character; pass 1
         *a                       to check, 0 to not check
         *a    xy_distance      - whether to include the z component
         *a                       in distance calculations; pass 1 to
         *a                       check only XY distance, 0 to check
         *a                       XYZ distance
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacter; may be NULL
         */
        diguyCharacter* get_random_active_character_in_group(const char* group_name,
                float max_distance = 10,
                int check_visibility = 1,
                int xy_distance = 0);

        /*l
         *b  Description:
         **
         **    This function returns the 3D distance from this character to the
         **    specified character, in meters.  The distance is calculated from
         **    the characters' idealized positions.
         */
        float get_distance_to_character(diguyCharacter* character);

        /*l
         *b  Description:
         **
         **    This function returns the 2D distance in X and Y coordinates only
         **    from this character to the specified character, in meters.  The
         **    distance is calculated from the characters' idealized positions.
         */
        float get_distance_xy_to_character(diguyCharacter* character);

        /*l
         *b  Description:
         **
         **    This function returns the 3D distance from this character to the
         **    specified impact, in meters.  The distance is calculated from the
         **    characters' idealized positions.
         */
        float get_distance_to_impact(diguyImpact* impact);

        /*l
         *b  Description:
         **
         **    Each character has a "random factor" between 0 and 1.  This value
         **    is persistent with the character; i.e., the random factor will
         **    stay constant for the entire lifetime of the character.
         **
         **    This random factor can be used to add some variability between
         **    different characters.
         **
         **    Though each character has a random factor that has a very good
         **    chance of being different from all other characters' in the
         **    scenario, this is not guaranteed and so should not be used as a
         **    unique identifier.
         **
         **    An example of use:  Instead of all characters beginning an action
         **    or behavior at the same time, have each one begin (random_factor *
         **    2.0) seconds from the current time.  This will result in more
         **    natural looking behavior as characters one by one begin the new
         **    behavior in the next two seconds, rather than all beginning at
         **    once.
         **
         *b  Returns:
         **
         **    the character's random factor, a value between 0 and 1
         */
        float get_random_factor();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function draws this character in immediate mode graphics
         **    environments (see below).  This is the equivalent of calling
         **    draw_pass1() immediately followed by draw_pass2().
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *i  OpenGL Version:
         **
         **    This function immediately draws this character.  Either this
         **    function or draw_pass1() and draw_pass2() 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 of this character.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *i  OpenGL Version:
         **
         **    This function immediately draws the opaque character parts.  Either
         **    this function or draw() should be called once per frame.
         */
        int draw_pass1();

        /*l
         *b  Description:
         **
         **    Same as draw_pass1(), but draws transparent character parts.
         */
        int draw_pass2();

#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Returns:
         **
         **    A pointer to the character's graphics.
         **
         *i  Vega Prime Version:
         **
         **    The return pointer may be cast to point to a vpDiguyCharacter,
         **    which is derived from vpObject.
         **
         *i  OpenGL Version:
         **
         **    This function returns NULL.
         **
         *i  DI-Guy Graphics API:
         **
         **    This function returns the pointer set from the most recent
         **    set_graphics_ptr() call.
         */
        void* get_graphics_ptr();

        /*l
         *b  Description:
         **
         **    Sets a graphics environment-specific pointer to graphics data.
         **    The pointer can be retrieved using get_graphics_ptr().
         **
         *b  Arguments:
         **
         *a    graphics_ptr - pointer to graphics data
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *i  OpenGL Version:
         **
         *b    This function should not be called for these environments.
         **
         *i  DI-Guy Graphics API Version:
         **
         **    This function allows graphics environment-specific data to be
         **    stored for later retrieval by get_graphics_ptr().  DI-Guy does
         **    not directly use the pointer, beyond returning it using the
         **    get_graphics_ptr() function.
         */
        int set_graphics_ptr(void* graphics_ptr);

        /*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.
         **
         *i  Callback Info:
         **
         **    This function can be safely be called in the
         **    CALLBACK_ID_SET_GRAPHICS_API_NODE_PTR callback.
         **
         *b  Arguments:
         **
         *a    node_ptr - generic void* pointer
         */
        void set_graphics_api_node_ptr(void* node_ptr);

        /*l
         *b  Returns:
         **
         **    pointer set by most recent call to set_graphics_api_node_ptr
         */
        void* get_graphics_api_node_ptr();

        /*l
         *b  Description:
         **
         **    This function stores a pointer to user data.
         **
         *b  Arguments:
         **
         *a    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 requested
         *a                by get_user_data()
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_user_data(void* user_data);

        /*l
         *b  Returns:
         **
         **    The user data pointer set by set_user_data()
         */
        void* get_user_data();

#endif

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets the desired action of the character.
         **
         **    This function will put the character into free action mode.  If
         **    the character was in path action mode, actions will no longer be
         **    set by action beads on the path.
         **
         **    If the character is in path position mode and 1 is passed for
         **    retain_path_shape, the character will stay in path position mode.
         **    If 0 is passed for retain_path_shape, the character will be put
         **    into free position mode.
         **
         **    If the character is in free position mode the retain_path_shape
         **    argument will have no effect.
         **
         **    If this call is interrupting a character in path action mode
         **    and path position mode, the character will not be able to resume
         **    the interrupted path unless retain_path_shape is set to 1.
         **    See resume_interrupted_path().
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free action mode.
         *-    - This function may change the position mode; see Description.
         **
         *b  Arguments:
         **
         *a    action_name       - name of the desired action to be performed by
         *a                        the character
         *a    speed             - the speed at which the character should travel
         *a                        while performing the action; pass
         *a                        DIGUY_DEFAULT_FLOAT for the optimal speed to
         *a                        be used
         *a    retain_path_shape - pass 1 to remain in path position mode; pass
         *a                        0 to change to free position mode
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_desired_action(const char* action_name,
                float speed = DIGUY_DEFAULT_FLOAT,
                int retain_path_shape = 0);

        const char* get_desired_action();

        int get_desired_action_index();

        const char* get_current_action();

        int get_current_action_index();

        diguyMotionDirection get_current_action_direction();
        
        /*l
         *b  Description:
         **
         **    This function returns the transition state of the action
         **    of a character.  When commanding an action, DI-Guy may
         **    transition the character through one or more intermediate
         **    actions to reach the final action.  For example, a character
         **    with the action "walk" that is commanded to "prone" would
         **    transition through the intermediate action "stand".
         **
         *b  Returns:
         **
         **    1 if the character is transitioning between actions
         **    0 otherwise
         */
        int get_is_in_action_transition();

        /*l
         *b  Description:
         **
         **    This function forces the current action of the character to be the
         **    action identified by action_name.
         **
         **    See set_desired_action() for a discussion of the effects on
         **    position mode.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         **    By passing a value greater than 0 for t_offset_into_new_action,
         **    the character can be made to begin the action partway in.  This is
         **    useful when forcing actions for a lot of characters at the same
         **    time; without the offset, the characters would move in lockstep.
         **
         **    The most recent forced action, the time at which it was forced,
         **    and any time offset can be queried using the functions
         **    get_most_recent_forced_action(),
         **    get_most_recent_forced_action_t(), and
         **    get_most_recent_forced_action_t_offset().
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free action mode.
         *-    - This function may change the position mode; see Description.
         **
         *b  Arguments:
         **
         *a    action_name            - name of the action to be performed by
         *a                             the character
         *a    speed                  - the speed at which the character should
         *a                             travel while performing the action; pass
         *a                             DIGUY_DEFAULT_FLOAT for the optimal speed
         *a                             to be used
         *a    include_transition_arc - flag for whether the transition
         *a                             motion from the current action to
         *a                             the new action is included;
         *a                             pass 1 for best chance of good looking
         *a                             transition;
         *a                             pass 0 for fastest response
         *a    max_rampdown_interval  - max amount of time spent trying to
         *a                             smooth over any motion seams; set
         *a                             to 0.5 for a smooth transition, set
         *a                             to 0 for a potentially rough transition
         *a    retain_path_shape      - pass 1 to remain in path position mode;
         *a                             pass 0 to change to free position mode
         *a    t_offset_into_new_action - how much to shift time forward into
         *a                             new action; must be >= 0; see comment
         *a                             above for more info
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int force_action(const char* action_name,
                float speed = DIGUY_DEFAULT_FLOAT,
                int include_transition_arc = 1,
                float max_rampdown_interval = 0.5f,
                int retain_path_shape = 0,
                float t_offset_into_new_action = 0.0f);

        /*l
         *b  Description:
         **
         **    This function is similar to force_action(), but allows the
         **    specification of how long the interruption should last.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Mode Restrictions:
         **
         *-    - This function can only be called if the character is in
         *-      path action mode *and* path position mode.
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free action mode.
         *-    - This function will not change the position mode.
         **
         *b  Arguments:
         **
         *a    duration - how long the action should be performed before
         *a               an automatic resume_interrupted_path() call is
         *a               made
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int force_action_with_duration(const char* action_name,
                float duration,
                int include_transition_arc = 1,
                float max_rampdown_interval = 0.5f);

        /*l
         *b  Description:
         **
         **    This function forces the current action of the character to be the
         **    action identified by action_name, to be executed along the path
         **    shape specified by path_shape_name.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free action mode.
         *-    - This function will put the character into path position mode.
         **
         *b  Arguments:
         **
         *a    action_name     - name of the action to be performed by
         *a                      the character
         *a    path_shape_name - name of the path shape on which action
         *a                      should be performed
         *a    waypoint_name   - name of waypoint on path shape to begin at;
         *a                      default of NULL will start at first waypoint
         *a    distance_into_path - distance into path shape to start at, if
         *a                         waypoint_name isn't specified
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int force_action_and_path_shape(const char* action_name,
                const char* path_shape_name,
                const char* waypoint_name = NULL,
                float distance_into_path = 0.0f);

        /*l
         *b  Description:
         **
         **    This function returns the most recently forced action as set by
         **    by force_action(), force_action_with_duration(), or
         **    force_action_and_path_shape().
         **
         *b  Returns:
         **
         **    the name of the most recent forced action, or NULL if no action
         **    has been forced
         */
        const char* get_most_recent_forced_action();

        /*l
         *b  Description:
         **
         **    This function returns the time at which the most recently forced
         **    action occurred.
         **
         *b  Returns:
         **
         **    time at which force action occurred; -1.0 if no action has been
         **    forced
         */
        float get_most_recent_forced_action_t();

        /*l
         *b  Description:
         **
         **    This function returns the action time offset of the most recently
         **    forced action.  This is typically value of the
         **    t_offset_into_new_action argument of the force_action() call.
         **
         *b  Returns:
         **
         **    time at which force action occurred; -1.0 if no action has been
         **    forced
         */
        float get_most_recent_forced_action_t_offset();


        /*l
         *b  Description:
         **
         **    This function adds a "pending action" to the character.  This is
         **    essentially a delayed set_desired_action() call.  The desired
         **    action will be set at the passed scenario t, just as if
         **    set_desired_action() is called at that time.
         **
         **    *Note:* Any call to set_desired_action() or force_action(), or
         **    their related variants, will clear any pending actions.
         **
         *b  Arguments:
         **
         *a    action            - name of pending desired action
         *a    scenario_t        - time at which to set desired action
         *a    remove_existing_pending_actions - pass 1 to remove any previously
         *a                        added pending actions, 0 to leave them
         *a    speed             - as passed to set_desired_action()
         *a    retain_path_shape - as passed to set_desired_action()
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int add_pending_desired_action(const char* action,
                float scenario_t,
                int   remove_existing_pending_actions = 0,
                float speed = DIGUY_DEFAULT_FLOAT,
                int   retain_path_shape = 1);

        /*l
         *b  Description:
         **
         **    Similar to add_pending_desired_action(), but will do a
         **    force_action() at the passed scenario_t instead of a
         **    set_desired_action().
         **
         **    *Note:* Any call to set_desired_action() or force_action(), or
         **    their related variants, will clear any pending actions.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int add_pending_force_action(const char* action,
                float scenario_t,
                int   remove_existing_pending_actions = 0,
                float speed = DIGUY_DEFAULT_FLOAT,
                int   include_transition_arc = 1,
                float max_rampdown_interval = 0.5f,
                int   retain_path_shape = 1,
                float first_arc_time_shift = 0.0f);

        /*l
         *b  Returns:
         **
         **    1 if the passed action name is an action available to this
         **    character, 0 if not
         */
        int is_valid_action(const char* action);

        /*l
         *b  Description:
         **
         **    This function sends this character a signal to die as soon as
         **    possible.  The character will transition to a dead action.
         **
         **    The following side-effects will also happen:
         *>
         *-        - all aiming is ended
         *-        - all gazing is ended
         *-        - all pointing is ended
         *-        - head nodding and shaking are stopped
         *-        - all gestures are aborted
         *-        - all sounds originated by the character are stopped
         *-        - Destroyed appearance might be switched to.
         *<
         **    Many function calls will have no effect on dead characters;
         **    see individual function descriptions for limitations.
         **
         **    Use the get_dead() call to retrieve the dead state of a
         **    character.
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free action mode.
         *-    - This function will not change the position mode.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int die_now(const char* preferred_dead_action_name = "(default)");

        /*l
         *b  Description:
         **
         **    This function revives a dead character.  The limitations of dead
         **    characters will be lifted from the revived character; e.g., the
         **    character will be able to gaze, execute gestures, etc.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int revive_now(const char* preferred_revive_action_name = "(default)");

        /*l
         *b  Description:
         **
         **    This function returns whether or not the character is dead.
         **    Characters can be killed by die_now() function calls, as well as
         **    by being hit by weapon fire.
         **
         *b  Returns:
         **
         **    1 if character is dead (die_now() function has been called),
         **    0 if not.
         */
        int get_dead();

        /*l
         *b  Description:
         **
         **    Sets the speed the character should attempt to move, in meters per
         **    second.
         **
         **    This setting takes effect immediately.  To set a desired action
         **    and a desired speed at the same time, use the speed argument of
         **    the set_desired_action() call.
         **
         **    This desired speed setting can be undone in a couple of ways:
         **
         *-    1. by calling set_speed() with an argument of
         *-       DIGUY_DEFAULT_FLOAT, or
         *-    2. by calling set_desired_action(), or
         *-    3. by calling one of the force_action() functions
         **
         *b  Arguments:
         **
         *a    speed - desired speed in meters per second
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_speed(float speed);

        /*l
         *b  Returns:
         **
         **    the approximate speed at which the character is moving, in meters
         **    per second
         */
        float get_speed();

        /*l
         *b  Returns:
         **
         **    The desired speed of the character, in meters per second. Calls to
         **    set_speed(), set_desired_action(), or force_action() assign
         **    the character a desired speed, to which it transitions over some
         **    amount of time. If the speed-setting was instantaneous, the current
         **    speed will be returned.
         */
        float get_desired_speed();

/*****************************************************************************/
        /*l
         *b  Description:
         ** 
         **   Sets a generic parameter that can be mapped to a blend tree driver. 
         **   Useful for creating animations that can play back at different vertical angles.
         */
        int set_animation_target_el(float elevation, float ramp_time = .25f);

        float get_animation_target_el();

        /*l
         *b  Description:
         ** 
         **   Sets a generic parameter that can be mapped to a blend tree driver. 
         **   Useful for creating animations that can play back at different horizontal angles.
         */
        int set_animation_target_az(float azimuth, float ramp_time = .25f);

        float get_animation_target_az();

        /*l
         *b  Description:
         ** 
         **   Sets a generic parameter in world space that can be mapped to a blend tree driver. 
         **   The locomotion actions are driven by these values allowing one action to go
         **   many different direction.
         **   Internally this is mapped to local space.
         **
         **   In practical terms, this means that a character with the appropriate animation blend 
         **   tree can be made to move at an arbitrary speed in an arbitrary direction, provided 
         **   that the blend tree supports these motions. One example would be a soldier who can 
         **   "strafe" from side to side while pointing his weapon in a certain direction. Another 
         **   example would be a car that can travel forwards or backwards at a speed within a 
         **   continuous range.
         **
         **   Users can see a demonstration of this feature in the character view by selecting an 
         **   appropriate character type (e.g. vehicle_09), appearance (e.g. taxi_2013), and 
         **   action ("movement"). The exercise blend tree widget will allow adjustments.
         **
         */
        void set_animation_velocity(float vel_x, float vel_y, float vel_z, float ramp_time = .25f);

        void get_animation_velocity(float *vel_x, float *vel_y, float *vel_z);

        /*l
         *b  Description:
         ** 
         **   Sets a generic parameter in local space that can be mapped to a blend tree driver. 
         **   The locomotion actions are driven by these values allowing one action to go 
         **   many different directions.
         **
         **   Similar to set_animation_velocity() in terms of overall practical details.
         **   Note that the local velocity setting will affect the character's world velocity.
         */
        void set_animation_local_velocity(float vel_x, float vel_y, float vel_z, float ramp_time = .25f);

        void get_animation_local_velocity(float *vel_x, float *vel_y, float *vel_z);

        /*l
         *b  Description:
         ** 
         **   Sets a generic parameter in that can be mapped to a blend tree driver. 
         **   The locomotion actions are driven by these values allowing one action to turn 
         */
        void set_animation_angular_velocity(float vel_rz,  float ramp_time = .25f);

        float get_animation_angular_velocity();

        
/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Sets the position of the character relative to the origin of the
         **    DI-Guy global coordinate system.
         **
         **    The new settings will take effect immediately, possibly causing
         **    the character to "teleport" if the new values are significantly
         **    different than the old.
         **
         **    The DI-Guy global coordinate system is right-handed, with
         **    X forward, Z up, and Y to the left.  Rotation directions follow
         **    standard right-handed coordinate system conventions:
         **
         *-      - positive rotations about X cause a counter-clockwise roll
         *-      - position rotations about Y cause a forward pitch
         *-      - positive rotations about Z cause a yaw to the left
         **
         **    Note that if the character has an altitude function (see
         **    set_altitude_function()), the tz argument will effectively be
         **    ignored as the altitude function will override it.
         **
         **    If the magnitude of the numbers is large (say 32000 or higher),
         **    the function set_position_double() should be used instead.
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free position mode.
         *-    - This function will put the character into free action mode.
         **
         *b  Arguments:
         **
         *a    tx, ty, tz - position in meters from the origin
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_position(float tx, float ty, float tz);

        /*l
         *b  Description:
         **
         **    Similar to set_position(), but using double-precision rather than
         **    single-precision numbers.  If the magnitude of the numbers is large
         **    (say 32000 or higher), this function should be used.
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free position mode.
         *-    - This function will put the character into free action mode.
         **
         *b  Arguments:
         **
         *a    tx, ty, tz - position in meters from the origin
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_position_double(double tx, double ty, double tz);

        /*l
         *b  Description:
         **
         **    Retrieves the position of the character in the DI-Guy
         **    global coordinate system.
         **
         **    See set_position() for a description of the coordinate system.
         **
         *b  Arguments:
         **
         *a    tx, ty, tz - position in meters from the origin
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_position(float* tx, float* ty, float* tz);

        /*l
         *b  Description:
         **
         **    Retrieves the position of the character in the DI-Guy
         **    global coordinate system.
         **
         **    See set_position() for a description of the coordinate system.
         **
         **    Unlike get_position(), this function returns higher-precision
         **    values for the position, which is important when the character is
         **    far from the coordinate system origin.
         **
         *b  Arguments:
         **
         *a    tx, ty, tz - position in meters from the origin
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_position_double(double* tx, double* ty, double* tz);

        /*l
         *b  Description:
         **
         **    Sets the position of the character relative to its parent or the
         **    origin of the DI-Guy global coordinate system if this
         **    character is not parented.
         **
         **    See set_position() for a description of the coordinate system.
         **
         **    The new settings will take effect immediately, possibly causing the
         **    character to "teleport" if the new values are significantly
         **    different than the old.
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free position mode.
         *-    - This function will put the character into free action mode.
         **
         *b  Arguments:
         **
         *a    tx, ty, tz - position in meters from the origin
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_position_relative_to_parent(float tx, float ty, float tz);

        /*l
         *b  Description:
         **
         **    Retrieves the position of the character relative to its parent, or
         **    relative to the origin of the DI-Guy global coordinate
         **    system if this character is not parented.
         **
         **    See set_position() for a description of the coordinate system.
         **
         *b  Arguments:
         **
         *a    tx, ty, tz - position in meters from the origin
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_position_relative_to_parent(float* tx, float* ty, float* tz);

        /*l
         *b  Description:
         **
         **    Similar to set_position_relative_to_parent(), but the position is
         **    either from the other character's overall position (if
         **    other_link_name is NULL), or the position of the other character's
         **    link (if other_link_name specifies a link on the other character).
         **
         **    The position that is set is relative to this character's parent.
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free position mode.
         *-    - This function will put the character into free action mode.
         **
         *b  Arguments:
         **
         *a    other_character_name - other character from which to read
         *a                           position
         *a    other_link_name      - optional link on other character; if
         *a                           NULL, other character's base position is
         *a                           used
         *a    offset_x, offset_y, offset_z - offset to apply to position
         *a                                   read from other character
         *a    also_set_orientation - pass 1 to also set this character's
         *a                           orientation from the other character's
         *a                           orientation
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_position_to_other_character_position(const char* other_character_name,
                const char* other_link_name = NULL,
                float offset_x = 0.0f, float offset_y = 0.0f, float offset_z = 0.0f,
                int also_set_orientation = 1);

        /*l
         *b  Description:
         **
         **    Sets the desired position of the character.  How the character
         **    moves toward the desired position is determined by its current
         **    guides; see add_guide() and create_guide().
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free position mode.
         *-    - This function will put the character into free action mode.
         **
         *b  Arguments:
         **
         *a    tx, ty, tz - desired position in meters from the origin
         *a    force_guide_unacquired - this optional argument will set any guides
         *a                             the character has to be unacquired
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_desired_position(float tx, float ty, float tz,
                int force_guide_unacquired = 0);

        int set_desired_position_double(double tx, double ty, double tz,
                int force_guide_unacquired = 0);
        /*l
         *b  Description:
         **
         **    Like set_desired_position(), but uses the character's current
         **    position as the desired position.
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free position mode.
         *-    - This function will put the character into free action mode.
         **
         *b  Arguments:
         **
         *a    also_set_orientation - pass 1 to also set this character's
         *a                           orientation to its current orientation
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_desired_position_to_current_position(int also_set_orientation = 1);

        /*l
         *b  Description:
         **
         **    Like set_desired_position(), but sets the character's desired
         **    position to passed waypoint's position.
         **
         **    The passed waypoint can be one created by
         **    diguyScenario::create_waypoint, a waypoint from a character's
         **    diguyCharacterPath, or waypoint from a diguyPathShape.
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free position mode.
         *-    - This function will put the character into free action mode.
         **
         *b  Arguments:
         **
         *a    waypoint                     - pointer to diguyWaypoint object
         *a    offset_x, offset_y, offset_z - offset to apply to waypoint
         *a                                   position
         *a    offset_in_world_coords       - 1 if offset is to be in world
         *a                                   coordinates, 0 if it is to be
         *a                                   in waypoint-local coordinates
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_desired_position_to_waypoint(diguyWaypoint* waypoint,
                float offset_x = 0.0f, float offset_y = 0.0f, float offset_z = 0.0f,
                int offset_in_world_coords = 0);

        /*l
         *b  Description:
         **
         **    Like set_desired_position(), but finds the specified waypoint on
         **    the specified path and sets the character's desired position to the
         **    waypoint's position.
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free position mode.
         *-    - This function will put the character into free action mode.
         **
         *b  Arguments:
         **
         *a    path_name     - name of path on which to find waypoint
         *a    waypoint_name - name of waypoint
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_desired_position_to_path_waypoint(const char* path_name,
                const char* waypoint_name);

        /*l
         *b  Description:
         **
         **    Like set_desired_position(), but finds the specified waypoint on
         **    the specified path shape and sets the character's desired position
         **    to the waypoint's position.
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free position mode.
         *-    - This function will put the character into free action mode.
         **
         *b  Arguments:
         **
         *a    path_shape_name - name of path shape on which to find waypoint
         *a    waypoint_name   - name of waypoint
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_desired_position_to_path_shape_waypoint(const char* path_shape_name,
                const char* waypoint_name);

        /*l
         *b  Description:
         **
         **    Retrieves the desired position of the character.
         **
         *b  Mode Restrictions:
         **
         *-    - This function can only be called in free position mode.
         **
         *b  Arguments:
         **
         *a    tx, ty, tz - desired position in meters from the origin
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_desired_position(float* tx, float* ty, float* tz);
        int get_desired_position_double(double* tx, double* ty, double* tz);

        /*l
         *b  Description:
         **
         **    Retrieves the delta vector from current position to desired one.
         **
         *b  Mode Restrictions:
         **
         *-    - This function can only be called in free position mode.
         **
         *b  Arguments:
         **
         *a    tx, ty, tz - delta in meters
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_delta_to_desired_position(float* tx, float* ty, float* tz);

        /*l
         *b  Description:
         **
         **    Sets the initial position the character should move to on a call to
         **    diguyScenario::reset().
         **
         **    If the character has an initial path, that path, not this function
         **    call, will determine its initial position.
         **
         *b  Arguments:
         **
         *a    tx, ty, tz - initial position in meters from the origin
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_initial_position(float tx, float ty, float tz);

        /*l
         *b  Description:
         **
         **    Retrieves the initial position of the character.
         **
         **    If the character is in free position mode or has no initial path,
         **    this will be the position set by set_initial_position().
         **
         **    Otherwise this will be the position of the first waypoint of the
         **    initial path.
         **
         *b  Arguments:
         **
         *a    tx, ty, tz - initial position in meters from the origin
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_initial_position(float* tx, float* ty, float* tz);

        /*l
         *b  Description:
         **
         **    Sets the orientation of the character relative to the origin of the
         **    DI-Guy global coordinate system.
         **
         **    See set_position() for a description of the coordinate system.
         **
         **    The new settings will take effect immediately, possibly causing the
         **    character to "teleport" if the new values are significantly
         **    different than the old.
         **
         **    Note that if the character has an up vector type of 'z' or 'n' or even
         **    sometimes 'd' (as set by the set_up_vector_type() call) the rx and ry
         **    values will not have any effect.  To be able to set rx and ry
         **    values, set the up vector type of the character to 'c', for "custom".
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free position mode.
         *-    - This function will put the character into free action mode.
         **
         *b  Arguments:
         **
         *a    rz, rx, ry - orientations in degrees
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_orientation(float rz, float rx, float ry);

        /*l
         *b  Description:
         **
         **    Retrieves the orientation of the character in the DI-Guy
         **    global coordinate system.  See set_position() for a description of
         **    the coordinate system.
         **
         *i    Note:
         **
         **    For vehicles, you may want to use the function
         **    get_vehicle_body_orientation().  See that function for more
         **    information.
         **
         *b  Arguments:
         **
         *a    rz, rx, ry - orientations in degrees counter-clockwise from the
         *a                 positive X axis
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_orientation(float* rz, float* rx, float* ry);

        /*l
         *b  Description:
         **
         **    Sets the orientation of the character relative to its parent or the
         **    origin of the DI-Guy global coordinate system if this
         **    character is not parented.
         **
         **    See set_position() for a description of the coordinate system.
         **
         **    The new settings will take effect immediately, possibly causing the
         **    character to "teleport" if the new values are significantly
         **    different than the old.
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free position mode.
         *-    - This function will put the character into free action mode.
         **
         *b  Arguments:
         **
         *a    rz, rx, ry - orientations in degrees
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_orientation_relative_to_parent(float rz, float rx, float ry);

        /*l
         *b  Description:
         **
         **    Retrieves the orientation of the character relative to its parent,
         **    or the origin of the DI-Guy global coordinate system if
         **    this character does not have a parent.
         **
         **    See set_position() for a description of the coordinate system.
         **
         *b  Arguments:
         **
         *a    rz, rx, ry - orientations in degrees counter-clockwise from the
         *a                 positive X axis
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_orientation_relative_to_parent(float* rz, float* rx, float* ry);

        /*l
         *b  Description:
         **
         **    This function sets how the character should be oriented relative
         **    to its surroundings.
         **
         **    This function changes the current up vector type, and the up vector type
         **    that will be set when the character is reset.  To change only the
         **    current up vector type (a temporary change that goes away on reset),
         **    call set_up_vector_type()).
         **
         *b  Arguments:
         **
         *a    axis - the up vector type the character should use; legal
         *a           values shown below:
         **
         *-     - 'd' - use default settings; character will change
         *-             up vector type depending on current action and
         *-             path shape parameters
         *-     - 'z' - Z axis is up; character will be oriented
         *-             so that positive Z in character coordinates is
         *-             always oriented along the positive world Z axis
         *-     - 'n' - normal to path; character will be oriented
         *-             so that positive Z in character coordinates is
         *-             normal to the path shape the character is on
         *-     - 'g' - ground-clamped; the vehicle will attempt to cling
         *-             to the terrain, in an approximation of real rigid
         *-             body physics
         *-     - 'c' - custom; character's rx and ry orientation values
         *-             will not be modified
         **
         **    Having an up vector type of 'z' effectively zeroes out the rx and ry
         **    values of the character's orientation.
         **
         **    Having an up vector type of 'n' may override rx and ry values of the
         **    character's orientation with values derived from the character's
         **    path shape.
         **
         **    Having an up vector type of 'c' allows the pitch and roll of the
         **    character to be changed without taking it off the path it in on by
         **    calling set_custom_orientation_rx_and_ry().  Calling
         **    set_orientation() has the side-effect of putting the character
         **    into free position mode, taking it off of any path it's on.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_initial_up_vector_type(char axis);

        /*l
         *b  Description:
         **
         **  This function is being deprecated, but remains for backwards compatibility.
         **  It does the same thing as set_initial_up_vector_type()
         **
         */
        int set_initial_up_vector(char axis);

        /*l
         *b  Returns:
         **
         **    current up vector type; see set_initial_up_vector_type()
         */
        char get_initial_up_vector_type();

        /*l
         *b  Description:
         **
         **  This function is being deprecated, but remains for backwards compatibility.
         **  It does the same thing as get_initial_up_vector_type()
         **
         */
        char get_initial_up_vector();

        /*l
         *b  Description:
         **
         **    This function sets how the character should be oriented relative
         **    to its surroundings.
         **
         **    This function changes only the current up vector type.  To change the
         **    up vector type that will be used when the character is reset, call
         **    set_initial_up_vector_type().
         **
         *b  Arguments:
         **
         *a    axis - the up vector type the character should use; see
         *a           set_initial_up_vector_type() for description
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int set_up_vector_type(char axis);

        /*l
         *b  Description:
         **
         **  This function is being deprecated, but remains for backwards compatibility.
         **  It does the same thing as set_up_vector_type()
         **
         */
        int set_up_vector(char axis);

        /*l
         *b  Returns:
         **
         **    current up vector type; see set_up_vector_type()
         */
        char get_up_vector_type();

        /*l
         *b  Description:
         **
         **  This function is being deprecated, but remains for backwards compatibility.
         **  It does the same thing as get_up_vector_type()
         **
         */
        char get_up_vector();

        /*l
         *b  Description:
         **
         **    This function sets the rx and ry components of the character's
         **    orientation.  Unlike set_orientation(), this function does not
         **    put the character into free position mode if it is currently in
         **    path position mode.
         **
         **    Note that if the character has an up vector type of 'z' or 'n' or even
         **    sometimes 'd' (as set by the set_up_vector_type() call) this function
         **    will not have any effect.  To be able to set rx and ry values,
         **    set the up vector type of the character to 'c', for "custom".
         **
         **    The passed rx and ry values are in character-local coordinates,
         **    not parent coordinates if the character has a parent.
         **
         *b  Mode Effects:
         **
         *-    - None.
         **
         *b  Arguments:
         **
         *a    rx, ry - orientations in degrees
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_custom_orientation_rx_and_ry(float rx,
                float ry);

        /*l
         *b  Description:
         **
         **    Sets the desired orientation of the character.  See
         **    set_desired_position().
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free position mode.
         *-    - This function will put the character into free action mode.
         **
         *b  Arguments:
         **
         *a    rz, rx, ry - orientations in degrees counter-clockwise from
         *a                 the positive X axis
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_desired_orientation(float rz, float rx, float ry,
                int force_guide_unacquired = 0);

        /*l
         *b  Description:
         **
         **    Retrieves the desired orientation of the character.
         **
         *b  Mode Restrictions:
         **
         *-    - This function can only be called in free position mode.
         **
         *b  Arguments:
         **
         *a    rz, rx, ry - orientations in degrees counter-clockwise from
         *a                 the positive X axis
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_desired_orientation(float* rz, float* rx, float* ry);

        /*l
         *b  Description:
         **
         **    Retrieves the delta from current orientation of the character
         **   to the desired one.
         **
         *b  Mode Restrictions:
         **
         *-    - This function can only be called in free position mode.
         **
         *b  Arguments:
         **
         *a    rz, rx, ry - orientation deltas in degrees counter-clockwise from
         *a                 the positive X axis
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_delta_to_desired_orientation(float* rz, float* rx, float* ry);

        /*l
         *b  Description:
         **
         **    Like set_desired_orientation(), but uses the character's current
         **    orientation as the desired orientation.
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free position mode.
         *-    - This function will put the character into free action mode.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_desired_orientation_to_current_orientation();

        /*l
         *b  Description:
         **
         **    Like set_desired_orientation(), but orients the character towards
         **    the position specified.
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free position mode.
         *-    - This function will put the character into free action mode.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_desired_orientation_towards_position(float x, float y, float z,
                int force_guide_unacquired = 0);

        /*l
         *b  Description:
         **
         **    Sets the initial orientation the character should move
         **    to on a call to diguyScenario::reset().
         **
         **    If the character is on a path the path, not this function
         **    call, will determine its initial orientation.
         **
         *b  Arguments:
         **
         *a    rz, rx, ry - orientations in degrees counter-clockwise from
         *a                 the positive X axis
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_initial_orientation(float rz, float rx, float ry);

        /*l
         *b  Description:
         **
         **    Retrieves the initial orientation of the character.
         **
         **    If the character is in free position mode or has no
         **    initial path, this will be the orientation set by
         **    set_initial_orientation().
         **
         **    Otherwise this will be the orientation of the first
         **    waypoint of the initial path.
         **
         *b  Arguments:
         **
         *a    rz, rx, ry - orientations in degrees counter-clockwise from
         *a                 the positive X axis
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_initial_orientation(float* rz, float* rx, float* ry);

        /*l
         *b  Description:
         **
         **    Returns the location and orientation of a specific link of the
         **    character.
         **
         *b  Arguments:
         **
         *a    link_name  - name of the link or connection point; links are named after their inbound
         *a                 joint name
         *a    tx, ty, tz - position in meters from the origin of the world
         *a    rz, rx, ry - orientations in degrees counter-clockwise from the
         *a                 positive X axis
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_link_position(const char* link_name,
                float* tx, float* ty, float* tz,
                float* rz, float* rx, float* ry);

        /*l
         *b  Description:
         **
         **    Returns the location and orientation of a specific link
         **    of the character.
         **
         *b  Arguments:
         **
         *a    link_name  - name of the link or connection point; links are named after their inbound
         *a                 joint name
         *a    tx, ty, tz - position in meters from the origin of the world
         *a    rz, rx, ry - orientations in degrees counter-clockwise from the
         *a                 positive X axis
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_link_position_double(const char* link_name,
                double* tx, double* ty, double* tz,
                double* rz, double* rx, double* ry);

        /*l
         *b  Description:
         **
         **    Similar to get_link_position(), but allows specification
         **    of offset into ending link.
         **
         *b  Arguments:
         **
         *a    link_name  -  name of the link or connection point
         *a    offset_tx, offset_ty, offset_tz - offset in link
         *a    tx, ty, tz - position in meters from the origin
         *a    rz, rx, ry - orientations in degrees counter-clockwise from the
         *a                 positive X axis
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_link_position_with_offset(const char* link_name,
                float offset_tx, float offset_ty, float offset_tz,
                float* tx, float* ty, float* tz,
                float* rz, float* rx, float* ry);

        /*l
         *b  Description:
         **
         **    Similar to get_link_position(), but allows specification
         **    of offset into ending link.
         **
         *b  Arguments:
         **
         *a    link_name  -  name of the link or connection point
         *a    offset_tx, offset_ty, offset_tz - offset in link
         *a    tx, ty, tz - position in meters from the origin
         *a    rz, rx, ry - orientations in degrees counter-clockwise from the
         *a                 positive X axis
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_link_position_with_offset_double(const char* link_name,
                double offset_tx, double offset_ty, double offset_tz,
                double* tx, double* ty, double* tz,
                double* rz, double* rx, double* ry);

        /*l
         *b  Description:
         **
         **    Returns the location and orientation of a specific link
         **    of the character relative to the position of another link.
         **
         *b  Arguments:
         **
         *a    beginning_link_name - name of the first link; send NULL to
         *a                          to specify the position link
         *a    ending_link_name -    name of the last link; send NULL to
         *a                          to specify the position link
         *a    tx, ty, tz - position in meters from the origin
         *a    rz, rx, ry - orientations in degrees counter-clockwise from the
         *a                 positive X axis
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_link_relative_position(const char* beginning_link_name,
                const char* ending_link_name,
                float* tx, float* ty, float* tz,
                float* rz, float* rx, float* ry);

        /*l
         *b  Description:
         **
         **    Similar to get_link_relative_position(), but allows specification
         **    of offset into ending link.
         **
         *b  Arguments:
         **
         *a    beginning_link_name - name of the first link; send NULL to
         *a                          to specify the position link
         *a    ending_link_name -    name of the last link; send NULL to
         *a                          to specify the position link
         *a    offset_tx, offset_ty, offset_tz - offset in ending link
         *a    tx, ty, tz - position in meters from the origin
         *a    rz, rx, ry - orientations in degrees counter-clockwise from the
         *a                 positive X axis
         **
         **    Pass NULL for any values that are not needed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_link_relative_position_with_offset(const char* beginning_link_name,
                const char* ending_link_name,
                float offset_tx, float offset_ty, float offset_tz,
                float* tx, float* ty, float* tz,
                float* rz, float* rx, float* ry);

        /*l
         *b  Description:
         **
         **    By default characters on a path will scale their movement speed
         **    and velocity based on the scale of the actor the character is
         **    based on.  For example, if a tall character and short character
         **    are both playing the exact same walk motion, the tall character
         **    will move further per motion repetition than the short character.
         **
         **    Scaling the travel in this way leads to more realistic looking
         **    motion, but can cause different characters using the same actions
         **    and underlying motions to move at different speeds.  At times it
         **    is convenient to not scale the travel.
         **
         **    If actor scaling is disabled, characters of different sizes will
         **    all move the same distance, and at the same speed, if they have
         **    the same path shapes and action beads.  Note that in cases of
         **    extreme differences between the actor the motion is based on
         **    and the actor the character's current appearance is based on,
         **    the characters feet may slip on the ground more than normal.
         **
         *b  Arguments:
         **
         *a    apply_scale_flag - pass 1 to apply actor scale to travel;
         *a                       0 to not
         */
        void set_apply_actor_scale_to_action_bead_travel(int apply_scale_flag);

        /*l
         *b  Returns:
         **
         **    1 if actor scale is being applied to travel, 0 if not
         */
        int get_apply_actor_scale_to_action_bead_travel();

        /*l
         *b  Description:
         **
         **    This function transforms a point that is in the local space of the
         **    character into a location in the world. Useful for things like
         **    navigating AIs to a location near a prop. Or moving to a spot
         **    in front of someone else.
         **
         **    This code presumes up_axis is 'z' and that there is only rotation
         **    about that axis.
         */
        int local_to_global(float x, float y, float z,
                float* res_x, float* res_y, float* res_z);

        /*l
         *b  Description:
         **
         **    This function transforms a point that is in world space into the
         **    local space of a character. Useful for figuring out if something
         **    was seen.
         **
         **    This code presumes up_axis is 'z' and that there is only rotation
         **    about that axis.
         **
         */
        int global_to_local(float x, float y, float z,
                float* res_x, float* res_y, float* res_z);

        /*l
         *b  Description:
         **
         **    Retrieves the current estimated velocity of the character.  Note
         **    this value may not be valid in environments where characters are
         **    transformed independent of DI-Guy function calls.  Teleporting
         **    characters can also temporarily make this calculation incorrect.
         **
         *b  Arguments:
         **
         *a    vel_x, vel_y, vel_z - meters/sec
         **
         **    Pass NULL for any values that are not needed.
         **
         */
        void get_velocity(float* vel_x, float* vel_y, float* vel_z);

        /*l
         *b  Description:
         **
         **    Used by the Drift and Adaptive guide
         **    
         *b  Arguments:
         **
         *a    vel_x, vel_y, vel_z - meters/sec
         */
        void set_desired_velocity(float vel_x, float vel_y, float vel_z, float ramp_time = 0.0);
        void get_desired_velocity(float *vel_x, float *vel_y, float *vel_z);

        /*l
         *b  Description:
         **
         **    Retrieves the current estimated angular velocity of the character.
         **    As above, changes made to characters independent of DI-Guy
         **    function calls will temporarily make this value incorrect.
         **
         **    Currently only the angular velocity in yaw is measured.
         **
         *b  Arguments:
         **
         *a    vel_rz - degrees/sec
         **
         */
        void get_angular_velocity(float* vel_rz);

        /*l
         *b  Description:
         **
         **    Used by the Drift and Adaptive guide
         **    
         * Documentation Pending
         */
        void set_desired_angular_velocity(float vel_rz);
        void get_desired_angular_velocity(float* vel_rz);

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Returns the base appearance of the character, as passed to
         **    the function diguyScenario::create_character(). This pointer will
         **    never be NULL.
         **
         **    Note that the current appearance (as returned by
         **    get_current_appearance()) may be different than the base
         **    appearance.  This base appearance is the starting appearance
         **    of the character before any calls to set_current_appearance()
         **    have been made.
         **
         *b  Returns:
         **
         **    name of base appearance of the character
         */
        const char* get_appearance();

        /*l
         *b  Description:
         **
         **    This function sets the base appearance of the character.
         **    The base appearance is the appearance the character will take
         **    if the scenario is reset, undoing any appearance changes made
         **    be calls to set_current_appearance().
         **
         **    Calling this function also makes an implicit call to
         **    set_current_appearance().
         **
         *b  Arguments:
         **
         *a    appearance - name of new base appearance
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_appearance(const char* appearance);

        /*l
         *b  Description:
         **
         **    This function sets the current appearance of this character.
         **
         **    Note that different appearances may be based on different actors.
         **    Different actors represent people of different sizes, so
         **    changing to an appearance that has a different actor can
         **    cause a pronounced change in character size.
         **
         **    Also, changing actors can take some time, as more internal
         **    character state needs to be updated to support the new size
         **    of the character.
         **
         *b  Arguments:
         **
         *a    appearance         - name of new desired appearance
         *a    allow_actor_change - pass 1 to allow the appearance change
         *a                         even if the actor changes, 0 to not
         **
         *b  See Also:
         **
         **    get_current_appearance(), set_current_head_appearance()
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int set_current_appearance(const char* appearance,
                int allow_actor_change = 1);

        /*l
         *b  Returns:
         **
         **    current appearance; see set_current_appearance()
         */
        const char* get_current_appearance();

        /*l
         *b  Description:
         **
         **    This function can be used to see if the current appearance
         **    has the passed name.  This is primarily useful for decisions
         **    and other limited logic applications.
         **
         *b  Returns:
         **
         **    1 if current appearance has passed name; 0 if not
         **
         *b  Available as Decision Bead/Event
         */
        int get_current_appearance_is(const char* appearance);

        /*l
         *b  Description:
         **
         **    This function sets the current head appearance of this character.
         **    On failure head appearance will be set to "default".
         **
         *b  Arguments:
         **
         *a    head_appearance - name of the new desired head appearance
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int set_current_head_appearance(const char* head_appearance);
        
        /*l
         *b  Description:
         **
         **    This function sets the head appearance of this character.
         */
        int set_head_appearance(const char* head_appearance);

        const char* get_current_head_appearance();

        /*l
         *b  Description:
         **
         **    Similar to get_current_appearance_is(), but for head appearance.
         **
         *b  Returns:
         **
         **    1 if current head appearance has passed name; 0 if not
         **
         *b  Available as Decision Bead/Event
         */
        int get_current_head_appearance_is(const char* head_appearance);


        /*b  Description:
         **
         **    This function sets the both base and current hand item appearance 
         **    of this character. The base hand item is the one it will have upon
         **    reset.
         **
         *b  Arguments:
         **
         *a        hand_item_appearance -- name of the desired hand item or "default"
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int set_hand_item(const char* hand_item_appearance);

        /*l
         *b  Returns:
         **
         **    Hand item appearance; see set_hand_item()
         **
         **    Might return "default"
         */
        const char* get_hand_item();

         /*b  Description:
         **
         **    This function sets the current hand item appearance of this character. 
         **    The base hand item will remain unaffected.
         **
         *b  Arguments:
         **
         *a        hand_item_appearance -- name of the desired hand item or "default"
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int set_current_hand_item(const char* hand_item_appearance);

        /*l
         *b  Returns:
         **
         **    Current hand item appearance. Will be the actual appearance
         **    displayed, not "default"
         */
        const char* get_current_hand_item();

        /*l
         *b  Description:
         **
         **
         *b  Arguments:
         **
         *a    appearance_type - a value indicating the type of supplementary appearance of concern
         **
         *b  Returns:
         **
         **    The number of available supplementary appearances of given type
         */
        int get_num_appearances_of_type(diguyCharacterAppearanceTypes appearance_type);

        /*l
         *b  Description:
         **
         **    See description for get_num_supplementary_appearances_of_type()
         **
         *b  Arguments:
         **
         *a    appearance_type - a value indicating the type of appearance of concern
         *a    index - a value indicating the type of supplementary appearance of concern
         **
         *b  Returns:
         **
         **    The name of the appearance or NULL
         */
        const char* get_appearance_name_at_index(diguyCharacterAppearanceTypes appearance_type, int index);

 /*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Sets the graphics level of detail (LOD) ranges for this character.
         **    Compare with diguyScenario::set_default_lod_ranges(), which sets
         **    the LOD ranges for newly created characters of a particular type.
         **    In both cases, ranges must be a static array of 8 floats,
         **    each larger than the one before.
         **
         **    This function sets graphics LOD ranges only.  Motion levels of
         **    detail can be set by calling set_motion_lod().
         **
         *b  Arguments:
         **
         *a    lod_ranges - new lod ranges for this character;
         **
         **    See diguyScenario::set_default_lod_ranges() for a description
         **    of what to pass in lod_ranges.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int set_lod_ranges(float* lod_ranges);

#ifdef CPLUSPLUS_ONLY
        float* get_lod_ranges();
#endif 
        int get_num_lods();

        /*l
         *b  Description:
         **
         **    Set the desired graphics level of detail (LOD) for this character.
         **    This may be overridden if this character uses automatic LOD
         **    switching.  See
         **    diguyScenario::set_automatic_graphics_lod_switching().
         **
         **    DI-Guy graphics LODs are numbered 1 (most detail) through 7
         **    (least detail).
         **
         *b  Arguments:
         **
         *a    lod - an integer between 1 and 7
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_graphics_lod(int lod);

        int get_graphics_lod();
        
        /*l
         *b  Description:
         **
         **    Set the desired shader level of detail (LOD) for this character.
         **    By default this is -1 and the shader is automatically picked by distance.
         **
         **    DI-Guy shaders LODs are numbered 1 (most quality) through the number of shaders in the 
         **    current technique.
         **
         *b  Arguments:
         **
         *a    lod - an integer between 1 and the number of shaders in the current technique
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_shader_lod(int lod);

        int get_shader_lod();
        
        /*l
         *b  Description:
         **
         *b    Note:  As of DI-Guy 12.5 we strongly recommend using the 
         **    multi-threaded pipeline for increasing performance.
         **
         **     Sets the motion level of detail (LOD) for this character.
         **    LOD 1 animates all joints of a character.  Higher LODs
         **    animate fewer joints.
         **
         **    For LOD 6, *nothing* in the pose is updated.  The character's
         **    pose will remain whatever it was the last time pose data
         **    was changed.
         **
         *a    LOD - Effect
         *a     1  - animate all joints
         *a     2  - stop animating wrists and ankles
         *a     3  - stop animating elbows and knees
         *a     4  - stop animating everything but pelvis and position
         *a     5  - stop animating everything but position
         *a     6  - stop animating everything but position
         **
         **    Note that characters that are load managed
         **    (get_is_load_managed() returns 1) have this parameter managed
         **    automatically.  The corresponding function for load managed
         **    characters is diguyLoadManager::set_zone_motion_lod().
         **
         *b  Arguments:
         **
         *a    motion_lod - an integer between 1 and 6
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_motion_lod(int motion_lod);

        int get_motion_lod();

        int get_current_motion_lod();

        /*l
         *b  Description:
         **
         *b    Note:  As of DI-Guy 12.5 we strongly recommend using the 
         **    multi-threaded pipeline for increasing performance.
         **
         **    This function sets the minimum CPL (character performance
         **    level) of the character.
         **
         **    A higher CPL will limit the types of operations that the character
         **    can perform, but will allow for more optimized update() calls.
         **
         **    The following CPL limitations are cumulative:
         **
         *-    - CPL 1: all character function calls are available
         *-    - CPL 2: the character cannot save history
         *-    - CPL 3: no advanced pose operations that alter the basic pose
         *-             of the character, including:
         *>
         *-        - gazing
         *-        - pointing
         *-        - aiming
         *-        - gestures
         *-        - head nodding and shaking
         *-        - pose overrides
         *-        - features relying on link matrices
         *-        - wheel rolling and turning on vehicles
         **
         **        Since link matrices are not computed, the DI-Guy Graphics API
         **        function diguyGraphicsLink::get_transformation_matrix() will
         **        not return valid results.
         *<
         *-    - CPL 4: no blends between motions
         *-    - CPL 5: (not currently implemented)
         **
         **    Note that characters that are load managed (get_is_load_managed()
         **    returns 1) have this parameter managed automatically.  The
         **    corresponding function for load managed characters is
         **    diguyLoadManager::set_zone_minimum_cpl().
         **
         **    The passed minimum_cpl may not be achievable if the character
         **    is already in the process of doing something not allowed by the
         **    new CPL.  For example, if the character is already gazing, trying
         **    to set the minimum CPL to 3 will fail, as CPL 3 would disable
         **    gazing.  In this case the minimum CPL will be set to the current
         **    highest possible CPL based on what the character is already doing.
         **    In this example the minimum CPL would be set to 2, as gazing is
         **    allowed at that CPL.
         **
         **    Conversely, if the minimum CPL has been successfully been set to
         **    3 or higher, any gaze calls such as diguyCharacter::gaze_at_point()
         **    will fail.
         **
         *b  Arguments:
         **
         *a    cpl - minimum CPL allowed for this character
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_minimum_cpl(int minimum_cpl);

        int get_minimum_cpl();

        /*l
         *b  Description:
         **
         **    This function returns that maximum possible CPL the character
         **    can attain based on what it is currently doing.  Advanced pose
         **    operations like gazing and pose overrides will limit the maximum
         **    CPL that can be achieved.
         **
         **    See diguyCharacter::set_minimum_cpl() for a description of
         **    what is possible under the different CPL levels.
         **
         *b  Returns:
         **
         **    maximum possible current CPL
         */
        int get_maximum_possible_current_cpl();

        /*l
         *b  Description:
         **
         **    This function puts the character into the maximum possible CPL
         **    that can be achieved based on what the character is currently
         **    doing.
         **
         **    This current CPL does not prevent the character from starting
         **    operations that will potentially lower the CPL.  e.g., if the
         **    character starts gazing, the CPL will potentially go down.
         **    Use set_minimum_cpl() to prevent that character from starting
         **    such operations.
         **
         **    See diguyCharacter::set_minimum_cpl() for a description of
         **    what is possible under the different CPL levels.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int maximize_current_cpl();

        /*l
         *b  Description:
         **
         **    This function sets a flag that determines whether the character
         **    should raise and lower its CPL automatically.  If automatic
         **    CPL switching is enabled then any time a potential CPL-changing
         **    operation is performed, the character will check the maximum
         **    possible current CPL (as per a call to maximize_current_cpl())
         **    and set its current CPL to the maximum possible.
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable automatic CPL switching, 0 to
         *a              disable it
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_automatic_cpl_switching_enabled(int enabled);

        int get_automatic_cpl_switching_enabled();

        /*l
         *b  Description:
         **
         **    This function sets the current CPL of the character.  Trying
         **    to set the CPL lower than the minimum (as set by
         **    set_minimum_cpl()) of higher than the maximum (as returned by
         **    get_maximum_possible_current_cpl()) will fail.
         **
         **    Note that characters that have automatic CPL switching enabled
         **    (get_automatic_cpl_switching_enabled() returns 1) will override
         **    this value.
         **
         **    See diguyCharacter::set_minimum_cpl() for a description of
         **    what is possible under the different CPL levels.
         **
         *b  Arguments:
         **
         *a    cpl - new current CPL
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_current_cpl(int current_cpl);

        int get_current_cpl();

        /*l
         *b  Description:
         **
         **    This function sets the position update rate of the character.  If
         **    the character's position is not updated on a particular update
         **    tick, its position will not change for that tick.  This can
         **    result is a modest performance increase.
         **
         **    The default value for new characters is 100.
         **
         **    This value may be overridden by the minimum full update period, as
         **    set by set_minimum_full_update_period().
         **
         **    Note that if the character's pose is updated, (see
         **    diguyCharacter::set_pose_update_rate()) its position will be
         **    updated as well.
         **
         **    Note that characters that are load managed
         **    (get_is_load_managed() returns 1) have this parameter managed
         **    automatically.  The corresponding function for load managed
         **    characters is diguyLoadManager::set_zone_position_update_rate().
         **
         *b  Arguments:
         **
         *a    update_rate - percentage of scenario ticks for which
         *a                  position should update; can be between
         *a                  1 and 100
         **
         **    Passing 100 means position will update every tick.
         **    Passing 50 means position will update every other tick.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_position_update_rate(int update_rate);

        int get_position_update_rate();

        /*l
         *b  Description:
         **
         **    This function is very similar to set_position_update_rate(), but
         **    sets the percentage of ticks for which the character's pose is
         **    updated.
         **
         **    The default value for new characters is 100.
         **
         **    This value may be overridden by the minimum full update period,
         **    as set by set_minimum_full_update_period().
         **
         **    Note that if the character's pose is updated, its position will
         **    be updated as well.
         **
         **    Note that characters that are load managed (get_is_load_managed()
         **    returns 1) have this parameter managed automatically.  The
         **    corresponding function for load managed characters is
         **    diguyLoadManager::set_zone_pose_update_rate().
         **
         *b  Arguments:
         **
         *a    update_rate - percentage of scenario ticks for which
         *a                  pose should update; can be between
         *a                  1 and 100
         **
         **    Passing 100 means pose will update every tick.
         **    Passing 50 means pose will update every other tick.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_pose_update_rate(int update_rate);

        int get_pose_update_rate();

        /*l
         *b  Description:
         **
         **    This function sets the minimum period for position or pose
         **    updates.  If the passed amount of time passes with no position or
         **    pose update (see set_position_update_rate() and
         **    set_pose_update_rate()), the character's position and potentially
         **    pose will be updated.
         **
         **    Note that characters that are load managed (get_is_load_managed()
         **    returns 1) have this parameter managed automatically.  The
         **    corresponding function for load managed characters is
         **    diguyLoadManager::set_minimum_full_update_period().
         **
         **    The default for new characters is 1.0 seconds.
         **
         *b  Arguments:
         **
         *a    min_period - in seconds
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_minimum_full_update_period(float min_period);

        float get_minimum_full_update_period();

        /*l
         *b  Description:
         **
         **    This function disables position accumulation due to played
         **    actions.  The character will stay in whatever position has most
         **    recently been set by set_position(), regardless of action.
         **    Because of this the character will, for example, walk in place.
         **    It is up to the user application to correctly set and update the
         **    character's position.
         **
         **    This function can be used when a host application provides
         **    absolute control over character positions.
         **
         **    Disabling position accumulation will result in a modest
         **    performance increase.
         **
         *b  Arguments:
         **
         *a    disabled_flag - pass 1 to disable position accumulation, 0
         *a                    to enable it
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_position_accumulation_disabled(int disabled_flag);

        int get_position_accumulation_disabled();

        /*l
         *b  Description:
         **
         **    This function disables all blends between motions of the
         **    character.  This will speed up performance at the expense of
         **    visual quality of the motions.  If the character is far from the
         **    current camera position, however, the lack of blends may be
         **    visually acceptable.
         **
         **    Note that characters that are load managed (get_is_load_managed()
         **    returns 1) have this parameter managed automatically.
         **
         *b  Arguments:
         **
         *a    disabled_flag - pass 1 to disable all blends, 0
         *a                    to enable them
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_all_blends_disabled(int disabled_flag);

        int get_all_blends_disabled();

        /*l
         *b  Description:
         **
         *b    Note: This function is not recommended. There is minimal perf gain.
         **    This function disables all update calls for shape switches. 
         **
         **    Switches currently control:
         **
         *-    - muzzle flashes
         *-    - hand switching for selected characters
         **
         **    For DI-Guy Graphics API users this means that most calls to
         **    diguyGraphicsShape::show() and diguyGraphicsShape::hide() will not
         **    be made.
         **
         **    Note that characters that are load managed (get_is_load_managed()
         **    returns 1) have this parameter managed automatically.
         **
         *b  Arguments:
         **
         *a    disabled_flag - pass 1 to disable shape switches, 0
         *a                    to enable them
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_shape_switches_disabled(int disabled_flag);

        int get_shape_switches_disabled();

        /*l
         *b  Description:
         **
         *b    Note: This function is not recommended. There is minimal perf gain.
         **    This function disables all shape callbacks.  Shape callbacks are
         **    used internally for updating some advanced visual effects.
         **
         **    Shape callbacks currently control:
         **
         *-    - expressive faces
         *-    - particle systems
         **
         **    Disabling shape callbacks will make these visual effects work
         **    incorrectly but will result in a performance increase for
         **    characters that do not use them.
         **
         **    Note that characters that are load managed (get_is_load_managed()
         **    returns 1) have this parameter managed automatically.
         **
         *b  Arguments:
         **
         *a    disabled_flag - pass 1 to disable shape callbacks, 0
         *a                    to enable them
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_shape_callbacks_disabled(int disabled_flag);
        
        int get_shape_callbacks_disabled();

        /*l
         *b  Description:
         **
         *b    Note: This function is not recommend. There is minimal perf gain.
         **    This function disables all calls to the virtual diguyGraphicsShape::update() 
         **    function.  
         **    
         **    Note that characters that are load managed (get_is_load_managed()
         **    returns 1) have this parameter managed automatically.
         **
         *b  Arguments:
         **
         *a    disabled_flag - pass 1 to disable update calls, 0
         *a                    to enable them
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_graphics_api_shape_update_disabled(int disabled_flag);

        int get_graphics_api_shape_update_disabled();

        /*l
         *b  Description:
         **
         **    This function is a stripped-down version of the normal update()
         **    function.  This function is for high performance applications that
         **    are willing to sacrifice advanced character functionality in
         **    exchange for faster performance.
         **
         **    Characters using optimized_update() must not do any of the
         **    following:
         **
         *-    - change character types (e.g., set_character_type())
         *-    - play sounds (e.g., play_sound())
         *-    - use history (e.g., set_history_type())
         *-    - use paths (e.g., push_path())
         *-    - weapon firing (e.g., fire_weapon())
         *-    - advanced pose operations (as per CPL 3)
         *-    - be a DI-Guy Network Module character
         *-    - need to use character callbacks
         *-    - use advanced visual effects, such as expressive faces and particle systems
         **
         **    Like update(), the scenario must not call the character's update()
         **    function (return value of get_t_controlled_by_scenario_t() is 0)
         **    for this function to work properly.
         **
         **    In some cases the regular update() call can be used for a time in
         **    place of optimized_update() if one of the above operations is
         **    desired.
         **
         *b  Arguments:
         **
         *a    t - new time for the character
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int optimized_update(float t);

        /*l
         *b  Description:
         **
         **    This function sets whether many of the performance tuning
         **    functions above are automatically managed by a diguyLoadManager
         **    object, which can be obtained by calling
         **    diguyApp::create_load_manager().
         **
         **    Note that this function will have no effect if a load manager has
         **    not been enabled.
         **
         **    The default for new characters is to be load managed if the load
         **    manager has been enabled.
         **
         *b  Arguments:
         **
         *a    is_load_managed - pass 1 to have character automatically
         *a                      load managed, 0 for manual management
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_is_load_managed(int is_load_managed);

        int get_is_load_managed();


/*****************************************************************************/
        /*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, in some cases the default
         **    handler of the function will not be called; the callback is
         **    asserting that it has done everything necessary for the function
         **    call. If the callback returns DIGUY_CALLBACK_CONTINUE, the default
         **    handler for the function will be called after the callback.
         **
         *b  Usable From:
         **
         *-    - C++
         *-    - Script
         **
         *************************************************************************
         *4  Callback Enums:
         **
         *i    CALLBACK_ID_CREATE
         **
         **      This callback will be called when a new character is created,
         **      *after* the character is fully initialized.
         **
         **      Note that this callback can only be added by calling
         **      diguyScenario::add_default_character_callback(); adding it with
         **      diguyCharacter::add_callback() will have no effect, as by that
         **      time the character has already been created.
         **
         *i    CALLBACK_ID_DESTROY
         **
         **      This callback will be called when a character is
         **      destroyed.
         **
         *i    CALLBACK_ID_PRE_CREATE
         **
         **      Like CALLBACK_ID_CREATE, this callback will be called when a
         **      new character is created; however, it is called *before* the
         **      character is fully initialized.
         **
         *b      NOTE:  Care must be taken when using this callback!
         **      As mentioned above, the character is not fully initialized,
         **      meaning that most member functions of the diguyCharacter object
         **      should not be called.  Those member functions that are safe
         **      to call will be mentioned in the documentation for the function;
         **      e.g., set_graphics_api_node_ptr().
         **
         **      Note that this callback can only be added by calling
         **      diguyScenario::add_default_character_callback(); adding it
         **      with diguyCharacter::add_callback() will have no effect, as
         **      by that time the character has already been created.
         **
         *i    CALLBACK_ID_CURRENT_APPEARANCE_CHANGED
         **
         **      This callback will be called when a character's current
         **      appearance is changed.
         **
         *i    CALLBACK_ID_CURRENT_HEAD_APPEARANCE_CHANGED
         **
         **      This callback will be called when a character's current head
         **      appearance is changed.
         **
         *i    CALLBACK_ID_PRE_UPDATE
         **
         **      This callback will be called before the character is updated as
         **      a result of the diguyScenario::update() function.
         **
         *i    CALLBACK_ID_POST_UPDATE
         **
         **      This callback will be called after the character is updated as a
         **      result of the diguyScenario::update() function.
         **
         *i    CALLBACK_ID_DONE_SPEAKING
         **
         **      This callback will be called when the character has finished
         **      speaking the contents of a speak() function call.
         **
         *i    CALLBACK_ID_GAZE_STATUS
         **
         **      This callback will be called after the character's gaze has
         **      experienced a status change.
         **
         *i    CALLBACK_ID_LPOINT_STATUS
         **
         **      This callback will be called after the character's lpoint (left
         **      arm pointing) has experienced a status change.
         **
         *i    CALLBACK_ID_SHOW
         **
         **      This callback will be called when the character is being shown
         **      for any reason.
         **
         *i    CALLBACK_ID_HIDE
         **
         **      This callback will be called when the character is being hidden
         **      for any reason.
         **
         *i    CALLBACK_ID_PRE_DIE
         **
         **      This callback will be called when the character has been told to
         **      die, before a die action has been selected and initiated.
         **
         **      If the returned diguyCallbackReturn value is
         **      DIGUY_CALLBACK_STOP, the character will not die.
         **
         *i    CALLBACK_ID_POST_DIE
         **
         **      This callback will be called when the character has been told to
         **      die, after a die action has been selected and initiated.
         **
         *i    CALLBACK_ID_PRE_FIRE_WEAPON
         **
         **      This callback will be called when the character has been told to
         **      fire its weapon, before a final decision has been made to fire.
         **
         **      If the returned diguyCallbackReturn value is
         **      DIGUY_CALLBACK_STOP, the character will not fire.
         **
         *i    CALLBACK_ID_IMPACT
         **
         **      This callback will be called when the character has been hit.
         **      diguyCharacter::get_last_impact_record() contains a pointer to
         **      the impact information. If a character has this callback the
         **      standard behavior (killing the character) is skipped and the
         **      system assumes the end user has handled the impact.
         **
         **      Similar behavior results if
         **      diguyCrowd::CALLBACK_ID_CROWD_MEMBER_IMPACT is registered.
         **
         *i    CALLBACK_ID_POST_FIRE_WEAPON
         **
         **      This callback will be called when the character has been told to
         **      fire its weapon, after a final decision has been made to fire.
         **
         *i    CALLBACK_ID_CURRENT_ACTION_CHANGED
         **
         **      This callback will be called whenever the character's current
         **      action changes, typically after a call to set_desired_action()
         **      or force_action().
         **
         *i    CALLBACK_ID_DESIRED_ACTION_CHANGED
         **
         **      This callback will be called whenever the character's desired
         **      action changes, typically after a call to set_desired_action().
         **
         *i    CALLBACK_ID_DESIRED_ACTION_REACHED
         **
         **      This callback will be called when the character reaches its
         **      desired action as set by a call to set_desired_action().
         **
         *i    CALLBACK_ID_MANUALLY_INVOKED
         **
         **      This callback id will be supplied to event handlers invoked by a
         **      call to manually_invoke_event_handler().
         **
         *i    CALLBACK_ID_USER_SELECTED
         **
         **      This callback will be called when the character is selected in DI-Guy Scenario.
         **
         *i    CALLBACK_ID_USER_UNSELECTED
         **
         **      This callback will be called on a currently selected character when a different 
         **      character is selected in DI-Guy Scenario.
         **
         *i    CALLBACK_ID_IGUY_INTERACT
         **
         **      This callback will be called when the character has been clicked
         **      on while DI-Guy Scenario is in I-Guy Input Mode.  Note that this
         **      is called on the character clicked, not the I-Guy character.
         **
         *i    CALLBACK_ID_IGUY_INTERACT_WITH_SUBJECT
         **
         **      This callback will be called when the character, as the I-Guy
         **      character, has clicked another character in I-Guy Input Mode.
         **      Note that this is called for the I-Guy character, not the
         **      clicked character.
         **
         *i    CALLBACK_ID_GUIDE_POSITION_ACQUIRED
         **
         **      This callback will be called when the character has reached its
         **      desired position as set by set_desired_position(). The
         **      diguyCharacterGuide is responsible for moving the character towards
         **      this position.
         **
         *i    CALLBACK_ID_GUIDE_POSITION_UNACQUIRED
         **
         **      This callback will be called if the character moves too far away
         **      from its desired position after it has been previously reached.
         **
         *i    CALLBACK_ID_GUIDE_ORIENTATION_ACQUIRED
         **
         **      This callback will be called when the character has reached its
         **      desired orientation as set by set_desired_orientation(). The
         **      diguyCharacterGuide is responsible for moving the character towards
         **      this orientation.
         **
         *i    CALLBACK_ID_GUIDE_ORIENTATION_UNACQUIRED
         **
         **      This callback will be called if the character turns too far away
         **      from its desired orientation after it has been previously
         **      reached.
         **
         *i    CALLBACK_ID_GUIDE_ALTITUDE_ACQUIRED
         **
         **      This callback will be called when the character has reached its
         **      desired altitude as set by set_desired_orientation() or other functions.
         **      The callback is most meaningful for vehicles that need to achieve
         **      some sort "cruising altitude" while moving to a destination.
         **
         *i    CALLBACK_ID_GUIDE_ALTITUDE_UNACQUIRED
         **
         **      This callback will be called if the character turns too far away
         **      from its desired orientation after it has been previously
         **      reached.
         **
         *i    CALLBACK_ID_GUIDE_TARGET_LOST
         **
         **      This callback will be called when the character guide has determined
         **      that the character can't reach its desired position/orientation. An
         **      example would be a missile that has flown past its target
         **
         *i    CALLBACK_ID_CURRENT_TOUT_REACHED
         **
         **      This callback will be called when scenario time reaches this
         **      character's tout time as set by set_current_tout().
         **
         *i    CALLBACK_ID_POST_CREATE_GEOMETRY
         **
         **      This callback will be called just after the character's geometry
         **      has been created.
         **
         *i    CALLBACK_ID_PRE_DESTROY_GEOMETRY
         **
         **      This callback will be called just before the character's
         **      geometry is broken down and destroyed.
         **
         *i    CALLBACK_ID_END_OF_PATH_REACHED
         **
         **      This callback will be called when a character reaches the end of
         **      their current path. Note the path must finish, forcing to other
         **      paths will not trigger this callback.
         **
         **
         *************************************************************************
         *4  DI-Guy Scenario UI Callback enums:
         **
         *i    CALLBACK_ID_UI_PRE_TRANSLATION
         **
         **      This callback will be called when the user interface starts
         **      moving a character.
         **
         *i    CALLBACK_ID_UI_POST_TRANSLATION
         **
         **      This callback will be called when the user interface finishes
         **      moving a character.
         **
         *i    CALLBACK_ID_UI_MOUSE_DOWN
         **
         **      This callback will be called when the user interface gets a
         **      mouse click in the DIGUY_SCENARIO_INPUT_MODE_POINT_SELECT input
         **      mode.
         **
         *i    CALLBACK_ID_UI_MOUSE_UP
         **
         **      This callback will be called when the user interface gets a
         **      mouse release in the DIGUY_SCENARIO_INPUT_MODE_POINT_SELECT
         **      input mode.
         **
         *************************************************************************
         *4  DI-Guy AI Agent Callback enums:
         **
         *i    CALLBACK_ID_AGENT_NEW_BEHAVIOR
         **
         **      This callback will be called when an agent changes its current
         **      behavior.
         **
         *i    CALLBACK_ID_AGENT_NEW_FOCUS_CHARACTER
         **
         **      This callback will be called when an agent changes its current
         **      focus character; this happens most frequently when it is focused
         **      on a group.
         **
         *i    CALLBACK_ID_AGENT_ATTACK_OUT_OF_TARGETS
         **
         **      This callback will be called when an agent in attack behavior
         **      evaluates the group it's focused on and cannot find an
         **      appropriate target.  This can happen if all group members are
         **      dead.
         **
         *i    CALLBACK_ID_AGENT_ATTACK_NO_VISIBLE_TARGETS
         **
         **      This callback will be called when an agent in attack behavior
         **      can't see any potential members of the group it's focused on.
         **
         *i    CALLBACK_ID_AGENT_PURSUE_TARGET_REACHED
         **
         **      This callback will be called when an agent in pursue behavior
         **      has come within the pursuit distance of its pursuit target.
         **
         *i    CALLBACK_ID_AGENT_PURSUE_TARGET_LOST
         **
         **      This callback will be called when an agent in pursue behavior
         **      is no longer within the pursuit distance of its pursuit target.
         **
         *i    CALLBACK_ID_AGENT_MINGLE_TARGET_REACHED
         **
         **      This callback will be called when an agent in mingle behavior
         **      has reached its mingle target.
         **
         *i    CALLBACK_ID_AGENT_MINGLE_TARGET_LOST
         **
         **      This callback will be called when an agent in mingle behavior
         **      is no longer is range of its mingle target.
         **
         *i    CALLBACK_ID_AGENT_WANDER_TARGET_REACHED
         **
         **      This callback will be called when an agent in wander behavior
         **      has reached its wander target.
         **
         *i    CALLBACK_ID_AGENT_WANDER_TARGET_LOST
         **
         **      This callback will be called when an agent in wander behavior
         **      is no longer is range of its wander target.
         **
         *i    CALLBACK_ID_AGENT_FLEE_AREA_LEFT
         **
         **      This callback will be called when an agent in flee behavior has
         **      successfully moved out range of all fled characters or
         **      locations.  This will only be called when the agent is
         **      transitioning from inside the flee area to outside of it.
         **
         *i    CALLBACK_ID_AGENT_FLEE_AREA_ENTERED
         **
         **      This callback will be called when an agent in flee behavior has
         **      moved inside of the range of any fled characters or locations.
         **      This will only be called when the agent is transitioning from
         **      outside the flee area to inside of it.
         **
         *i    CALLBACK_ID_AGENT_TRAVEL_WAYPOINT_REACHED
         **
         **      This callback will be called when an agent in travel behavior
         **      has reached in intermediate waypoint and is about to move
         **      on to the next.
         **
         *i    CALLBACK_ID_AGENT_TRAVEL_FORWARD_DEST_REACHED
         **
         **      This callback will be called when an agent in travel behavior
         **      has reached the end of its travel path when moving forward
         **      along the path.
         **
         *i    CALLBACK_ID_AGENT_TRAVEL_BACKWARD_DEST_REACHED
         **
         **      This callback will be called when an agent in travel behavior
         **      has reached the beginning of its travel path when moving
         **      backward along the path.
         **
         *i    CALLBACK_ID_AGENT_TRAVEL_NEAR_FORWARD_DEST
         **
         **      This callback will be called when an agent gets within a specified
         **      distance of the end of the travel path
         **
         *i    CALLBACK_ID_AGENT_CROWD_MEMBER_KILLED
         **
         **      This callback will be called when fellow member of the crowd is
         **      killed.
         **
         *-      - This is the character version of
         *-        diguyCrowd::CALLBACK_ID_CROWD_MEMBER_KILLED
         *-      - The crowd's callback character is the crowd member that was
         *-        killed.
         *-      - The crowd's callback impact contains the impact information.
         **
         *i    CALLBACK_ID_AGENT_CROWD_MEMBER_IMPACT
         **
         **      This callback will be called when a fellow member of the crowd
         **      is hit by a detonation.  This callback does not replace
         **      diguyCharacter::CALLBACK_ID_IMPACT, which still needs to be
         **      handled to implement damage models.
         **
         *-      - The crowd's callback character is the crowd member that was
         *-        hit.
         *-      - The crowd's callback impact contains the impact information.
         **
         *i    CALLBACK_ID_AGENT_NEARBY_SCENE_OBJECT_IMPACT
         **
         **      This callback will be called when a detonation occurs within the
         **      awareness radius (as set by set_awareness_radius()) of the
         **      crowd's current bounds.
         **
         *-      - This is the character version of
         *-        diguyCrowd::CALLBACK_ID_NEARBY_SCENE_OBJECT_IMPACT
         *-      - The crowd's callback character is the character that caused
         *-        the detonation.
         *-      - The crowd's callback impact contains the impact information.
         **
         *i    CALLBACK_ID_AGENT_NEARBY_WEAPON_FIRED
         **
         **      This callback will be called when a weapon is fired within the
         **      awareness radius (as set by set_awareness_radius()) of the
         **      crowd's current bounds.
         **
         *-      - The crowd's callback character is the character that fired the
         *-        weapon.
         **
         *i    CALLBACK_ID_AGENT_VEHICLE_COLLISION
         **
         **      This callback will be called on a vehicle agent when it hits a
         **      member of a companion crowd.
         **
         *i    CALLBACK_ID_AGENT_VEHICLE_NEAR_COLLISION
         **
         **      This callback will be called on a vehicle agent when it
         **      approaches another vehicle.
         **
         *i    CALLBACK_ID_AGENT_NON_ZERO_REPULSION
         **
         **      This callback will be called when an agent character's repulsion
         **      forces become non-zero.
         **
         *i    CALLBACK_ID_AGENT_ZERO_REPULSION
         **
         **      This callback will be called when an agent character's repulsion
         **      forces become zero.
         **
         *i    CALLBACK_ID_AGENT_PATH_PLAN_COMPLETED
         **
         **      This callback will be called when a character who's requested a
         **      path plan via the background path planner
         **      (agent_move_to_point_bg) gets a path result. Call
         **      diguyCharacter::get_path_planning_result() to get the status of
         **      the result.
         **
         *i    CALLBACK_ID_AGENT_MIND_CURRENT_STATE_CHANGED
         **
         **      This callback will be called when the current state the agent's
         **      mind, if it has one, has changed.  Call
         **      diguyCharacter::get_mind_current_state_name() to get the new
         **      state name.
         */
        enum {
                CALLBACK_ID_CREATE = 1,
                CALLBACK_ID_DESTROY,
                CALLBACK_ID_PRE_CREATE,
                CALLBACK_ID_CURRENT_APPEARANCE_CHANGED,
                CALLBACK_ID_CURRENT_HEAD_APPEARANCE_CHANGED,
                CALLBACK_ID_CURRENT_HAND_ITEM_APPEARANCE_CHANGED,
                CALLBACK_ID_SHAPE_VISIBILITY_CHANGED,
                CALLBACK_ID_PRE_UPDATE,
                CALLBACK_ID_POST_UPDATE,
                CALLBACK_ID_DONE_SPEAKING,
                CALLBACK_ID_GAZE_STATUS,
                CALLBACK_ID_LPOINT_STATUS,
                CALLBACK_ID_SHOW,
                CALLBACK_ID_HIDE,
                CALLBACK_ID_PRE_DIE,
                CALLBACK_ID_POST_DIE,
                CALLBACK_ID_PRE_FIRE_WEAPON,
                CALLBACK_ID_POST_FIRE_WEAPON,
                CALLBACK_ID_IMPACT,
                CALLBACK_ID_FIRE_WEAPON_SUCCESS,
                CALLBACK_ID_CURRENT_ACTION_CHANGED,
                CALLBACK_ID_DESIRED_ACTION_CHANGED,
                CALLBACK_ID_DESIRED_ACTION_REACHED,
                CALLBACK_ID_MANUALLY_INVOKED,
                CALLBACK_ID_USER_SELECTED,
                CALLBACK_ID_USER_UNSELECTED,
                CALLBACK_ID_IGUY_INTERACT,
                CALLBACK_ID_IGUY_INTERACT_WITH_SUBJECT,
                CALLBACK_ID_GUIDE_POSITION_ACQUIRED,
                CALLBACK_ID_GUIDE_POSITION_UNACQUIRED,
                CALLBACK_ID_GUIDE_ORIENTATION_ACQUIRED,
                CALLBACK_ID_GUIDE_ORIENTATION_UNACQUIRED,
                CALLBACK_ID_GUIDE_ALTITUDE_ACQUIRED,
                CALLBACK_ID_GUIDE_ALTITUDE_UNACQUIRED,
                CALLBACK_ID_GUIDE_TARGET_LOST,
                CALLBACK_ID_CURRENT_TOUT_REACHED,
                CALLBACK_ID_POST_CREATE_GEOMETRY,
                CALLBACK_ID_PRE_DESTROY_GEOMETRY,
                CALLBACK_ID_END_OF_PATH_REACHED,
                CALLBACK_ID_CHARACTER_CLICKED,

                // DI-Guy Scenario UI callbacks:
                CALLBACK_ID_UI_PRE_TRANSLATION,
                CALLBACK_ID_UI_POST_TRANSLATION,
                CALLBACK_ID_UI_MOUSE_DOWN,
                CALLBACK_ID_UI_MOUSE_UP,
                CALLBACK_ID_UI_RIGHT_MOUSE_DOWN,
                CALLBACK_ID_UI_RIGHT_MOUSE_UP,
                CALLBACK_ID_UI_LEFT_CLICK,
                CALLBACK_ID_UI_RIGHT_CLICK,
                CALLBACK_ID_UI_DOUBLE_CLICK,
                CALLBACK_ID_UI_MIDDLE_CLICK,
                CALLBACK_ID_UI_SCROLL_UP,
                CALLBACK_ID_UI_SCROLL_DOWN,
                //CALLBACK_ID_UI_DRAG,

                // DI-Guy AI agent callbacks:
                CALLBACK_ID_AGENT_NEW_BEHAVIOR,
                CALLBACK_ID_AGENT_NEW_PATH_SHAPE,
                CALLBACK_ID_AGENT_NEW_FOCUS_CHARACTER,
                CALLBACK_ID_AGENT_ATTACK_OUT_OF_TARGETS,
                CALLBACK_ID_AGENT_ATTACK_NO_VISIBLE_TARGETS,
                CALLBACK_ID_AGENT_PURSUE_TARGET_REACHED,
                CALLBACK_ID_AGENT_PURSUE_TARGET_LOST,
                CALLBACK_ID_AGENT_MINGLE_TARGET_REACHED,
                CALLBACK_ID_AGENT_MINGLE_TARGET_LOST,
                CALLBACK_ID_AGENT_WANDER_TARGET_REACHED,
                CALLBACK_ID_AGENT_WANDER_TARGET_LOST,
                CALLBACK_ID_AGENT_FLEE_AREA_LEFT,
                CALLBACK_ID_AGENT_FLEE_AREA_ENTERED,
                CALLBACK_ID_AGENT_TRAVEL_WAYPOINT_REACHED,
                CALLBACK_ID_AGENT_TRAVEL_FORWARD_DEST_REACHED,
                CALLBACK_ID_AGENT_TRAVEL_BACKWARD_DEST_REACHED,
                CALLBACK_ID_AGENT_TRAVEL_NEAR_FORWARD_DEST,
                CALLBACK_ID_AGENT_CROWD_MEMBER_KILLED,
                CALLBACK_ID_AGENT_CROWD_MEMBER_IMPACT,
                CALLBACK_ID_AGENT_NEARBY_SCENE_OBJECT_IMPACT,
                CALLBACK_ID_AGENT_NEARBY_WEAPON_FIRED,
                CALLBACK_ID_AGENT_VEHICLE_COLLISION,
                CALLBACK_ID_AGENT_VEHICLE_NEAR_COLLISION,
                CALLBACK_ID_AGENT_PATH_PLAN_COMPLETED,
                CALLBACK_ID_AGENT_MIND_CURRENT_STATE_CHANGED,
                CALLBACK_ID_AGENT_NON_ZERO_REPULSION,
                CALLBACK_ID_AGENT_ZERO_REPULSION
        };

#ifdef CPLUSPLUS_ONLY
/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function adds a user callback.  Callbacks can be removed
         **    with remove_callback() or remove_callback_with_user_data().
         **
         *b  Arguments:
         **
         *a    callback        - pointer to function with prototype
         *a                      diguyCharacterCallback (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
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int add_callback(int callback_id,
                diguyCharacterCallback* callback,
                void* callback_params = 0,
                void* callback_user_data = 0);

        /*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 when this callback is to be called
         *a    callback        - pointer to function with prototype
         *a                      diguyCharacterCallback (typedefed above)
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_callback(int callback_id,
                diguyCharacterCallback* 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 when this callback is to be
         *a                         called
         *a    callback_user_data - pointer for user's own use
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_callback_with_user_data(int callback_id,
                void* callback_user_data);

#endif
/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function adds a user callback script.  Callback scripts can
         **    be removed with remove_callback_script().
         **
         *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
         **
         **    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
         **
         *b  Lua Example:
         **
         *e     -------------------------------------------------------------------
         *e     local pre_fire_weapon_callback = [[
         *e
         *e         local ch_name = callback_object:get_name();
         *e         bdi_log_print(BDI_LOG_WARN, "Calling pre_fire_weapon_callback for character ".. ch_name .. ".\n");
         *e
         *e     ]]
         *e     -------------------------------------------------------------------
         *e
         *e     character:add_callback_script(diguyCharacter_CALLBACK_ID_PRE_FIRE_WEAPON,
         *e         pre_fire_weapon_callback,
         *e         "lua");
         */
        int add_callback_script(int callback_id,
                const char* callback_script,
                const char* callback_script_type = NULL);

        /*l
         *b  Description:
         **
         **    This function removes a user callback script previously added with
         **    add_callback_script().
         **
         *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
         **
         *b  lua Example:
         **
         *e     #
         *e     #  Remove all callback scripts with id
         *e     #  diguyCharacter_CALLBACK_ID_PRE_FIRE_WEAPON
         *e     #
         *e     character:remove_callback_script(diguyCharacter_CALLBACK_ID_PRE_FIRE_WEAPON,
         *e         nil,
         *e         "lua");
         */
        int remove_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 character callback function registered by
         *-        diguyScenario::register_character_event_handler() or
         *-        diguyScenario::register_character_event_handler_from_library()
         *-      - a script registered by
         *-        diguyScenario::register_character_event_handler_script()
         *-      - a Script, Decision, or Library Function in the scenario
         *-        whose "Event Type" is "Character"
         **
         *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 unmap
         *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 character event
         **    handler.  The callback_id that will be passed to the event
         **    handler will be CALLBACK_ID_MANUALLY_INVOKED.
         **
         **    See diguyCharacter::map_event_handler_to_callback_id() for
         **    a description of what comprises a character event handler.
         **
         **    Note that care should be taken not to end up in an
         **    infinite loop of event calls.  In general an event handler
         **    should not end up directly or indirectly invoking itself.
         **
         *b  Arguments:
         **
         *a    handler_name  - name of the event handler to invoke
         **
         *b  Returns:
         **
         **    DIGUY_CALLBACK_CONTINUE or DIGUY_CALLBACK_STOP
         **
         *b  Available as Decision Bead/Event
         */
        diguyCallbackReturn manually_invoke_event_handler(const char* handler_name);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function creates a new path.  The created path has no
         **    waypoints and no actions.  Waypoints can be added using
         **    diguyCharacterPath::create_waypoint() or
         **    diguyCharacterPath::add_waypoint().  Action beads should be added
         **    using diguyCharacterPath::create_action_bead().
         **
         **    To create a simple path that has a few waypoints and actions, use
         **    create_simple_path().
         **
         **    The waypoints for the path should be created using the function
         **    diguyScenario::create_waypoint().  They should be deleted using the
         **    function diguyScenario::destroy_waypoint().  Copies of the
         **    waypoints are made during the function call, so it is safe to
         **    destroy them immediately after this function call returns, or use
         **    the waypoints again for another path.
         **
         **    The returned diguyCharacterPath pointer should be destroyed using
         **    destroy_path().
         **
         *b  Arguments:
         **
         **    The path makes internal copies of all arguments.
         **
         *a    name - name of the new path
         **
         *b  Returns:
         **
         **    pointer to type diguyCharacterPath
         **
         */
        diguyCharacterPath* create_path(const char* name);

        /*l
         *b  Description:
         **
         **    This function creates a new simple path.  The path is simple
         **    because it has only two waypoints and three specified actions.
         **
         **    The waypoints for the path should be created using the function
         **    diguyScenario::create_waypoint().  They should be deleted using the
         **    function diguyScenario::destroy_waypoint().  Copies of the
         **    waypoints are made during the function call, so it is safe to
         **    destroy them immediately after this function call returns, or use
         **    the waypoints again for another path.
         **
         **    The returned diguyCharacterPath pointer should be destroyed using
         **    destroy_path().
         **
         *b  Arguments:
         **
         **    The path makes internal copies of all arguments.
         **
         *a    name                        - name of the new path
         *a    waypoint0                   - beginning waypoint
         *a    waypoint1                   - ending waypoint
         *a    transition_from_action_name - name of the action the character
         *a                                  should be transitioning from at the
         *a                                  beginning of the path; can be NULL
         *a    fill_action_name            - name of the action that should fill
         *a                                  the majority of the path; can be
         *a                                  NULL, but see below
         *a    transition_to_action_name   - name of the action the character
         *a                                  should transition into at the end of
         *a                                  the path
         **
         **    If transition_from_action_name is NULL, an initial action bead that
         **    transitions to the fill action will not be created.
         **
         **    If fill_action_name is NULL, no action beads will be created for
         **    the path, even if transition_from_action_name and/or
         **    transition_to_action_name are non-NULL.
         **
         **    If transition_to_action_name is NULL, a final action bead that
         **    transitions from the fill action will not be created.
         **
         *b  Returns:
         **
         **    pointer to type diguyCharacterPath
         */
        diguyCharacterPath* create_simple_path(const char* name,
                diguyWaypoint* waypoint0,
                diguyWaypoint* waypoint1,
                const char* transition_from_action_name,
                const char* fill_action_name,
                const char* transition_to_action_name);

        /*l
         *b  Description:
         **
         **    This function is similar to create_simple_path(), but creates its
         **    waypoints based on waypoints from the passed path shape.
         **
         *b  Arguments:
         **
         **    The path makes internal copies of all arguments.
         **
         *a    name                        - name of the new path
         *a    source_path_shape           - path shape whose waypoints are used
         *a                                  to define shape of new path
         *a    transition_from_action_name - same as for create_simple_path()
         *a    fill_action_name            - same as for create_simple_path()
         *a    transition_to_action_name   - same as for create_simple_path()
         **
         *b  Returns:
         **
         **    pointer to type diguyCharacterPath
         */
        diguyCharacterPath* create_path_from_path_shape(const char* name,
                diguyPathShape* source_path_shape,
                const char* transition_from_action_name,
                const char* fill_action_name,
                const char* transition_to_action_name);

        /*l
         *b  Description:
         **
         **    This function creates a temporary path and immediately forces it as
         **    the character's current path.  Once it has been traversed it will
         **    be automatically deleted.
         **
         **    The beginning waypoint of this path is at the character's current
         **    position; the ending waypoint is at the specified action bead on
         **    the specified path (or the first action bead of the specified path
         **    if no action bead is specified).  The character will use the
         **    specified action to move from the beginning waypoint to the ending
         **    waypoint.
         **
         **    This function is useful for getting a free position mode character
         **    back onto a path.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into path position mode.
         *-    - This function will put the character into path action mode.
         **
         *b  Arguments:
         **
         *a    destination_path_name      - the path the character is trying to
         *a                                 reach
         *a    via_action_name            - the action used over the majority of
         *a                                 the bridge path
         *a    destination_path_action_bead_name - the target action bead on the
         *a                                        destination path; pass NULL
         *a                                        to start at the beginning
         *a                                        of the path
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int create_and_force_bridge_path(const char* destination_path_name,
                const char* destination_path_action_bead_name,
                const char* via_action_name);

        /*l
         *b  Description:
         **
         **    This function creates a temporary path and immediately forces it as
         **    the character's current path.  Once the path has been traversed it
         **    will be automatically deleted.  The character then begins the local
         **    path specified by path_to_push.
         **
         **    The beginning waypoint of this path is at the character's current
         **    position; the ending waypoint is at the specified x, y, z.  A
         **    path_offset is available to shorten the distance to the end point
         **    along the vector to the destination.  The character will use the
         **    specified action to move from the beginning waypoint to the ending
         **    waypoint.
         **
         **    An optional follow-on path can be specified that the character will
         **    move onto once the end position is reached.  This must be the name
         **    of an existing path for the character.  A local path copy of the
         **    specified path will be created, and will be pushed to occur after
         **    this bridge path completes.
         **
         **    This function is useful for branching from one location to another
         **    in the world.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into path position mode.
         *-    - This function will put the character into path action mode.
         **
         *b  Arguments:
         **
         *a    x, y, z         - location in world space the bridge path
         *a                      should aim for
         *a    path_offset     - the amount to shorten the bridge path
         *a    via_action_name - the action used over the majority of the
         *a                      bridge path
         *a    next_local_path - local path to push when the character
         *a                      arrives at it's destination; pass NULL
         *a                      to not push a local path
         *a    orientation     - amount to rotate the local path
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int create_and_force_bridge_path_to_point(float x, float y, float z,
                float path_offset,
                const char* via_action_name,
                const char* next_local_path = NULL,
                float orientation = 0.0f);

        /*l
         *b  Description:
         **
         **    This function destroys a path created by create_path(),
         **    create_simple_path(), or a path from a loaded scenario.
         **
         **    The path the character is currently traveling, as returned by
         **    get_current_traveled_path(), cannot be destroyed.  Attempting to
         **    destroy it will result in an error.
         **
         *b  Arguments:
         **
         *a    path    - path to be destroyed
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int destroy_path(diguyCharacterPath* path);

        /*l
         *b  Returns:
         **
         **     the number of paths belonging to this character
         */
        int get_num_paths();

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

        /*l
         *b  Returns:
         **
         **    the name of the path at the given index; NULL if no
         **    path at the specified index
         */
        const char* get_path_name_at_index(int index);

        /*l
         *b  Description:
         **
         **    This function returns the index of the path the character
         **    is currently following.  If the character is not following
         **    a path the returned index will be -1.  (i.e., the character
         **    must be in path action mode *and* path position mode.)
         **
         *b  Mode Restrictions:
         **
         *-    - This function will only return a 0 or greater index if the
         **      character is in path action mode *and* path position mode.
         **
         *b  Returns:
         **
         **    the index of the current path; -1 if not on a path
         */
        int get_current_path_index();

        /*l
         *b  Description:
         **
         **    This function returns the path the character is currently
         **    traveling.
         **
         *b  Mode Restrictions:
         **
         *-    - This function can only be called in path position mode.
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacterPath; NULL if no path is currently
         **    being traveled
         */
        diguyCharacterPath* get_current_traveled_path();

        /*l
         *b  Description:
         **
         **    This function can be used to see if the current traveled has the
         **    passed name.  This is primarily useful for decisions and other
         **    limited logic applications.
         **
         *b  Returns:
         **
         **    1 if currently traveled path has the passed name; 0 if the name
         **    doesn't match, or no path is currently being traveled
         **
         *b  Available as Decision Bead/Event
         */
        int get_current_traveled_path_is(const char* path_name);

        /*l
         *b  Description:
         **
         **    This function pushes the path with the specified name
         **    onto the queue of paths this character will follow.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    name - name of the path to be pushed
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int push_path(const char* path_name);

        /*l
         *b  Description:
         **
         **    This function clears the queue of paths the character will follow
         **    and then pushes the path with the specified name.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    name                  - name of the path to be pushed
         *a    max_rampdown_interval - max amount of time spent trying to
         *a                            smooth over any motion seams; set
         *a                            to 0.5 for a smooth transition, set
         *a                            to 0 for a potentially rough transition
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int force_path(const char* path_name,
                float max_rampdown_interval = 0.5f);

        /*l
         *b  Description:
         **
         **    Same as force_path(), but only motions at or after the specified
         **    action bead are added.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Available as Decision Bead/Event
         */
        int force_partial_path(const char* path_name,
                const char* beginning_action_bead_name,
                float max_rampdown_interval = 0.5f);

        /*l
         *b  Description:
         **
         **    Resumes a path that was interrupted with a call such as
         **    set_desired_action() or force_action().  Note that the
         **    retain_path_shape argument to these functions must have been 1 for
         **    the path to be resumable.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Mode Restrictions:
         **
         *-    - This function can only be called if the character is in
         *-      free action mode *and* path position mode.
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into path position mode.
         *-    - This function will put the character into path action mode.
         **
         *b  Arguments:
         **
         *a    max_rampdown_interval - max amount of time spent trying to
         *a                            smooth over any motion seams; set
         *a                            to 0.5 for a smooth transition, set
         *a                            to 0 for a potentially rough transition
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int resume_interrupted_path(float max_rampdown_interval = 0.5f);

        /*l
         *b  Description:
         **
         **    This function creates a temporary path that is a copy of path_name
         **    but transformed so that the starting point is the same as where
         **    the character currently is. It then forces it as the character's
         **    current path.
         **
         *b  Arguments:
         **
         *a    path_name                  - path to copy
         *a    use_character_orientation  - whether the character's orientation be
         *a                                 incorporated into the transform of the
         *a                                 path
         *a    rotation                   - additional amount to rotate the path,
         *a                                 in degrees
         *a    clamp_path                 - whether the path be ground clamped
         **
         *b  Returns:
         **
         **    pointer to type diguyCharacterPath
         */
        diguyCharacterPath* force_local_path(const char* path_name,
                int use_character_orientation,
                float rotation = 0.0f,
                int clamp_path = 1);

        /*l
         *b  Description:
         **
         **    This function sets which path the character will start on when the
         **    scenario is reset.
         **
         *b  Arguments:
         **
         *a    name - name of the path that will be the initial path
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_initial_path(const char* name);

        /*l
         *b  Description:
         **
         **    This function returns the name of the path the character will start
         **    on when the scenario is reset.
         **
         **    See set_initial_path().
         **
         *b  Returns:
         **
         **    name of initial path; NULL if there is none
         */
        const char* get_initial_path();

        /*l
         *b  Description:
         **
         **    This function translates all of the paths of this character.
         **
         *b  Arguments:
         **
         *a    tx, ty, tz        - distance in meters to move all waypoints
         *a    reclamp_waypoints - pass 1 to reclamp waypoints to ground
         */
        void translate_all_paths(float tx, float ty, float tz,
                int reclamp_waypoints = 1);

        /*l
         *b  Description:
         **
         **    This function rotates all of the paths of this character.
         **    The rotation will occur about the specified point.
         **
         **    *Note:*  It is currently recommended that only rotations
         **    about the Z axis be done.  (i.e., only rz should be non-zero.)
         **
         *b  Arguments:
         **
         *a    rz, rx, ry        - amount of rotation, in degrees
         *a    rotation_pt_x, rotation_pt_y, rotation_pt_z - point around
         *a                        which rotation should occur
         *a    reclamp_waypoints - pass 1 to reclamp waypoints to ground
         */
        int rotate_all_paths_about_point(float rz, float rx, float ry,
                float rotation_pt_x, float rotation_pt_y, float rotation_pt_z,
                int reclamp_waypoints = 1);

        /*l
         *b  Description:
         **
         **    This function is similar to rotate_all_paths_about_point(),
         **    but rotates around the character's current waypoint instead
         **    of an explicitly specified point.
         **
         **    *Note:*  It is currently recommended that only rotations
         **    about the Z axis be done.  (i.e., only rz should be non-zero.)
         **
         *b  Arguments:
         **
         *a    rz, rx, ry        - amount of rotation, in degrees
         *a    reclamp_waypoints - pass 1 to reclamp waypoints to ground
         */
        int rotate_all_paths_about_current_waypoint(float rz, float rx, float ry,
                int reclamp_waypoints = 1);

        /*l
         *b  Description:
         **
         **    This function causes the character to jump forward along
         **    its current path to the specified action bead.  Motions
         **    and beads that would have otherwise been played or processed
         **    will be skipped.
         **
         *b  Arguments:
         **
         *a    bead_name             - name of the bead to jump to
         *a    max_rampdown_interval - max amount of time spent trying to
         *a                            smooth over any motion seams; set
         *a                            to 0.5 for a smooth transition, set
         *a                            to 0 for a potentially rough transition
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int jump_to_action_bead(const char* bead_name,
                float max_rampdown_interval = 0.5f);

        /*l
         *b  Description:
         **
         **    This function finds and returns a pointer to the specified path.
         **
         *b  Arguments:
         **
         *a    name - name of the path to be found
         **
         *b  Returns:
         **
         **    Pointer to object of type diguyCharacterPath;
         **    NULL if path not found.
         */
        diguyCharacterPath* find_path(const char* path_name);

        /*l
         *b  Description:
         **
         **    This function causes the effects of the given aim bead to be
         **    applied to this character, regardless of whether the
         **    bead belongs to the character or whether character is within
         **    the bead's time interval.
         **
         *b  Arguments:
         **
         *a    how_far - how far into the bead the call should be; should
         *a              be between 0 (beginning of bead time interval) and
         *a              1 (end of bead time interval)
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int apply_aim_bead(diguyCharacterPathAimBead* bead,
                float how_far = 0.0f);

        /*l
         *b  Description:
         **
         **    This function causes the effects of the given decision bead to be
         **    applied to this character, regardless of whether the
         **    bead belongs to the character or whether character is within
         **    the bead's time interval.
         **
         *b  Arguments:
         **
         *a    how_far - how far into the bead the call should be; should
         *a              be between 0 (beginning of bead time interval) and
         *a              1 (end of bead time interval)
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int apply_decision_bead(diguyCharacterPathDecisionBead* bead,
                float how_far = 0.0f);

        /*l
         *b  Description:
         **
         **    This function causes the effects of the given gaze bead to be
         **    applied to this character, regardless of whether the
         **    bead belongs to the character or whether character is within
         **    the bead's time interval.
         **
         *b  Arguments:
         **
         *a    how_far - how far into the bead the call should be; should
         *a              be between 0 (beginning of bead time interval) and
         *a              1 (end of bead time interval)
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int apply_gaze_bead(diguyCharacterPathGazeBead* bead,
                float how_far = 0.0f);

        /*l
         *b  Description:
         **
         **    This function causes the effects of the given script bead to be
         **    applied to this character, regardless of whether the
         **    bead belongs to the character or whether character is within
         **    the bead's time interval.
         **
         *b  Arguments:
         **
         *a    how_far - how far into the bead the call should be; should
         *a              be between 0 (beginning of bead time interval) and
         *a              1 (end of bead time interval)
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int apply_script_bead(diguyCharacterPathScriptBead* bead,
                float how_far = 0.0f);

        /*l
         *b  Description:
         **
         **    This function sets how far along the current path shape
         **    the character will be.
         **
         *b  Mode Restrictions:
         **
         *-    - This function can only be called if the character is in
         *-      free action mode *and* path position mode.  i.e., the
         *-      character is following a path shape, and is not on a
         *-      diguyCharacterPath.
         **
         *b  Arguments:
         **
         *a    distance - distance in meters; 0.0 is the beginning of the
         *a               path shape
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_distance_along_path(float distance);

        /*l
         *b  Returns:
         **
         **    the distance in meters along the path shape; see
         **    set_distance_along_path()
         **
         *b  Mode Restrictions:
         **
         *-    - This function can only be called in path position mode.
         */
        float get_distance_along_path();

        /*l
         *b  Description:
         **
         **    This function takes the character off of its current path
         **    or path shape.
         **
         *b  Mode Restrictions:
         **
         *-    - This function can only be called in path position mode.
         **
         *b  Mode Effects:
         **
         *-    - This function will put the character into free position mode.
         *-    - This function will put the character into free action mode.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int leave_path();

        /*l
         *b  Description:
         **
         **    This function returns the index of the nearest waypoint in a path,
         **    the path argument is looked up in both the character's path list
         **    and the scenario's paths.
         **
         *b  Returns:
         **
         **    waypoint index
         */
        int get_nearest_waypoint_index_in_path(const char* path_name);

        /*l
         *b  Returns:
         **
         **             Distance to action bead or first waypoint, 100000000.0 on failure
         */
        float get_distance_to_path(const char* path_name,
                const char* action_bead_name = NULL);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function gets the position link of the character skeleton.
         **    The rest of the skeleton can then be traversed by recursively
         **    calling the diguyGraphicsLink::get_num_child_links() and
         **    diguyGraphicsLink::get_child_link_at_index() functions.
         **
         **    Alternatively, the links of the character can be traversed
         **    by calling the get_num_links() and get_link_at_index()
         **    functions below.
         **
         *b  Returns:
         **
         **    pointer of type diguyGraphicsLink; NULL if there is no
         **    position link
         */
        diguyGraphicsLink* get_position_link();

        /*l
         *b  Returns:
         **
         **    number of links on this character
         */
        int get_num_links();

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

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

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

        /*l
         *b  Returns:
         **
         **    the number of shapes on the specified link
         **
         *b  Arguments:
         **
         *a    link_name - name of the link
         */
        int get_num_link_shapes(const char* link_name);

        /*l
         *b  Returns:
         **
         **    the name of the shape at the specified index on the link
         **
         *b  Arguments:
         **
         *a    link_name   - name of the link
         *a    shape_index - index of the shape on the link; indices start at 0
         */
        const char* get_link_shape_name_at_index(const char* link_name,
                int shape_index);

        int get_num_connection_points();

        const char * get_connection_point_name_at_index(int index);

        int get_num_connection_points_with_type(diguyConnectionPointType type);

        const char * get_connection_point_name_with_type(diguyConnectionPointType type, int index);

        void set_link_visibility(const char* link_or_connection_name, int visible, int shape_index = -1);

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

        /*l
         *b  Description:
         **
         **    The following prototype should be used for the altitude
         **    function:
         **
         *e     float altitude_func(diguyCharacter* character,
         *e             float x,
         *e             float y,
         *e             float old_z);
         **
         **    When a character needs new altitude info, DI-Guy calls this
         **    function with a pointer to the diguyCharacter in question,
         **    the character's current (x, y) coordinates, and its previous
         **    altitude in old_z.
         **
         **    The altitude function should then compute and return the new
         **    altitude based on this information.  This can be done in a
         **    number of ways; a typical approach is to do an intersection
         **    test with the visual scene. Some users might want to implement
         **    fairly complex behavior, such as attempting to make all four 
         **    wheels of a vehicle touch the terrain, or causing a character
         **    to drift slowly towards the ground.
         **
         **    A default altitude function that should be set for all
         **    characters can be set by calling
         **    diguyScenario::set_default_character_altitude_function().
         **
         **        This function is normally called for all characters if the flags
         **    for enabling it in free movement or path-following mode are
         **    set (see below). Some character systems, such as certain kinds
         **    of vehicle control code, will also use the scenario altitude
         **    function.
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int set_altitude_function(diguyAltitudeFunction* altitude_function);

        /*l
         *b  Returns:
         **
         **    current altitude function; see set_altitude_function()
         **
         *b  Callable From:
         **
         *-    - C++
         */
        diguyAltitudeFunction* get_altitude_function();

#endif

        /*l
         *b  Description:
         **
         **    This function sets whether the character's altitude function is
         **    enabled in free position mode.  Altitude functions are set by the
         **    functions set_altitude_function() or
         **    diguyScenario::set_default_character_altitude_function().
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable, 0 to disable
         **
         *b  Mode Effects:
         **
         *-    - This function will not change the position mode.
         **
         *b  Mode Restrictions:
         **
         *-    - This function will only affect characters in free position mode.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_altitude_function_enabled_in_free_position_mode(int enabled);

        /*l
         *b  Returns:
         **
         **    whether the character's altitude function is enabled in free
         **    position mode; see
         **    set_altitude_function_enabled_in_free_position_mode()
         */
        int get_altitude_function_enabled_in_free_position_mode();

        /*l
         *b  Description:
         **
         **    This function sets whether the character's altitude function is
         **    enabled in path position mode.  Altitude functions are set by
         **    the functions set_altitude_function() or
         **    diguyScenario::set_default_character_altitude_function().
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable, 0 to disable
         **
         *b  Mode Effects:
         **
         *-    - This function will not change the position mode.
         **
         *b  Mode Restrictions:
         **
         *-    - This function will only affect characters in path position mode.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_altitude_function_enabled_in_path_position_mode(int value);

        /*l
         *b  Returns:
         **
         **    whether the character's altitude function is enabled in path
         **    position mode;
         **    see set_altitude_function_enabled_in_path_position_mode()
         */
        int get_altitude_function_enabled_in_path_position_mode();

        /*l
         *b  Description
         **
         **    This function sets the altitude update rate of the character.
         **
         **    The default value for new characters is 100.
         **
         **    Note that characters that are load managed (get_is_load_managed()
         **    returns 1) have this parameter managed automatically.  The
         **    corresponding function for load managed characters is
         **    diguyLoadManager::set_zone_altitude_update_rate().
         **
         *b  Arguments:
         **
         *a    update_rate - percentage of scenario ticks for which altitude
         *a                  should update; can be between 1 and 100
         **
         **    Passing 100 means altitude will update every tick.
         **    Passing 50 means altitude will update every other tick.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_altitude_update_rate(int update_rate);

        int get_altitude_update_rate();

        /*l
         *b  Description
         **
         **    This function sets the altitude interpolation rate of the
         **    character.  This function only has an effect if the character's
         **    altitude function is enabled.
         **
         **    When the altitude function determines that the character's Z
         **    position should be updated to bring it closer to the ground, the
         **    altitude interpolation rate determines how quickly the Z height
         **    is adjusted.
         **
         **    The default value is 10.
         **
         *b  Arguments:
         **
         *a    interpolation_rate - how much of the error will be made up
         *a                         each second
         **
         **    An interpolation_rate of 100 means that all error will be made
         **    up each frame.
         */
        void set_altitude_interpolation_rate(float interpolation_rate);

        float get_altitude_interpolation_rate();

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Returns the number of variables in this character's pose array.
         **    See get_pose_in_radians() for an example of use.
         **
         *b  Returns:
         **
         **    size of this character's pose array
         */
        int get_pose_array_size();

#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    Fills an array of floats with the character's current joint angles.
         **    Angles are expressed in radians.  The size of the float array must
         **    be at least as large as that returned by get_pose_array_size().
         **
         *b  Arguments:
         **
         *a    pose_array - an array of floats
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         **
         *b  C++ Example:
         **
         *e     diguyCharacter* ch = scenario->get_character_at_index(0);
         *e     float* pose_array;
         *e
         *e     // allocate a float array of the proper size
         *e     int n = ch->get_pose_array_size();
         *e     pose_array = new float[n];
         *e
         *e     // get the pose array
         *e     ch->get_pose_in_radians(pose_array);
         */
        int get_pose_in_radians(float* pose_array);

#endif

        /*l
         *b  Description:
         **
         **    Creates and returns a pose override object. The newly created
         **    pose override object is added to the character's previously
         **    created override objects, if any.
         **
         **    How the pose override interacts with other effects that affect
         **    the pose of the character depends on the override stage.  See
         **    the section "Pose Override Stages" for a discussion of pose
         **    override stages.
         **
         *b  Arguments:
         **
         *a    override_stage - the stage in the DI-Guy motion engine at
         *a                     which the override should be applied
         **
         *b  Returns:
         **
         **    object of type diguyCharacterPoseOverride
         */
        diguyCharacterPoseOverride* create_pose_override(int override_stage = 3);

        /*l
         *b  Description:
         **
         **    Destroys a pose override object, ending its influence on the
         **    character.
         **
         *b  Arguments:
         **
         *a    po - pose override object to be destroyed
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int destroy_pose_override(diguyCharacterPoseOverride* po);

        /*l
         *b  Returns:
         **
         **     the number of pose overrides belonging to this character
         */
        int get_num_pose_overrides();

        /*l
         *b  Returns:
         **
         **    pointer of type diguyCharacterPoseOverride; NULL if no
         **    pose override at the specified index
         **
         *b  Arguments:
         **
         *a    index - index of the pose override; indices start at 0
         */
        diguyCharacterPoseOverride* get_pose_override_at_index(int index);

        /*l
         *b  Description:
         **
         **    Creates and returns a pose override object that completely
         **    overrides all other character pose operations, including motions,
         **    aiming, gazing, gestures, other pose overrides, etc.  The values
         **    set in the complete pose override object will be the values used
         **    to animate the character.
         **
         **    Having only one thing that affects a character's pose allows for
         **    much faster updating of the character.
         **
         **    There can only be one complete pose override object per character.
         **
         **    To remove the complete pose override, call
         **    destroy_complete_pose_override().
         **
         *b  Returns:
         **
         **    object of type diguyCharacterPoseOverride
         */
        diguyCharacterPoseOverride* create_complete_pose_override();

        /*l
         *b  Description:
         **
         **    Removes and destroys the complete pose override created by
         **    create_complete_pose_override().
         */
        void destroy_complete_pose_override();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets the current azimuth, elevation, and
         **    distance of the character's gaze.  A fixed point in 3D space
         **    is then found using the two angles and the given distance
         **    from the DI-Guy coordinate system origin.  Angles are
         **    given with respect to the DI-Guy coordinate system.
         **
         **    See set_position() for a description of the coordinate
         **    system.
         **
         **    Gazing will continue until end_gaze() is called.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    azimuth   - rotation in degrees about up (vertical) axis;
         *a                positive rotates to character's left
         *a    elevation - rotation in degrees about forward (horizontal) axis;
         *a                positive rotates down
         *a    distance  - distance in meters from the position of the character
         *a                to the gaze target; positive values only,
         *a                typically this is a large value (e.g. 10,000 meters)
         *a    is_new_gaze - set to 1 if this is a new gaze;
         *a                set to 0 if this is continuing an already started
         *a                gaze
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int gaze_at_angle(float azimuth,
                float elevation,
                float distance,
                int is_new_gaze = 1);

        /*l
         *b  Description:
         **
         **    This function is identical to gaze_at_angle() except that it uses
         **    body local coordinates for the character.  The angles
         **    are given with respect to the idealized position of the
         **    character.  Use get_position() to learn the idealized position.
         **    The distance is between the idealized position of the character
         **    and the fixation point.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         */
        int gaze_at_angle_local(float azimuth,
                float elevation,
                float distance = 10000.0f,
                int is_new_gaze = 1);

        /*l
         *b  Description:
         **
         **    This function sets the current fixation point of the character's
         **    gaze.  Point coordinates are given in meters in the DI-Guy
         **    global coordinate system.  The function uses default gaze behavior
         **    settings.  Gazing will continue until end_gaze() is called.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    tx, ty, tz  - position in meters from the DI-Guy global
         *a                  origin
         *a    is_new_gaze - set to 1 if this is a new gaze;
         *a                  set to 0 if this is continuing an already started
         *a                  gaze
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int gaze_at_point(float tx,
                float ty,
                float tz,
                int is_new_gaze = 1);

        /*l
         *b  Description:
         **
         **    This function is identical to gaze_at_point() except that it uses
         **    body local coordinates for the character.  Use get_position()
         **    to learn the idealized position of the character if necessary.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         */
        int gaze_at_point_local(float tx,
                float ty,
                float tz,
                int is_new_gaze = 1);

        /*l
         *b  Description:
         **
         **    This function effectively does a gaze_at_point() each tick.
         **    The point to be gazed at is updated each tick to be the position
         **    of the specified link on the specified character.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    target_character_name      - name of the character to be
         *a                                 gazed at
         *a    target_character_link_name - link on the character that should
         *a                                 be gazed at; pass NULL to gaze at
         *a                                 the position link of the character
         *a    offset_tx, offset_ty, offset_tz - offset onto the link, in meters
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         **
         *b  C++ Example:
         **
         *e    // gaze at the head of character "soldier-1".
         *e    ch->gaze_at_character("soldier-1",
         *e        "cervical",
         *e        0.0,
         *e        0.0,
         *e        0.0);
         */
        int gaze_at_character(const char* target_character_name,
                const char* target_character_link_name = NULL,
                float offset_tx = 0.0f,
                float offset_ty = 0.0f,
                float offset_tz = 0.0f);

        /*l
         *b  Returns:
         **
         **    1 if the character is actively gazing, 0 if not
         */
        int get_gaze_is_active();

        /*l
         *b  Returns:
         **
         **    the current gaze point relative to the DI-Guy
         **    global coordinate system
         */
        int get_gaze_point(float* x, float* y, float* z);

        /*l
         *b  Description:
         **
         **    A gaze is acquired if the final link in the gaze link chain
         **    has fully oriented toward the gaze target, even if other
         **    links in the gaze chain are still moving.
         **
         **    If the gaze is acquired, but any links in the gaze chain
         **    are still moving, the gaze is considered acquired but not
         **    steady (see get_gaze_is_steady().)  If all links have reached
         **    a relatively steady state, the gaze is considered acquired
         **    and steady.
         **
         **    If either the acquired or steady status of a gaze has changed
         **    (e.g., was acquired but now is not, or was steady but now
         **    a link is moving), the diguyCharacter callback with callback_id
         **    CALLBACK_ID_GAZE_STATUS will be called.
         **
         *b  Returns:
         **
         *-    - 1 if the final link in the gaze can and has become oriented
         *-      toward the gaze target
         *-    - 0 if not
         *-    - -1 on error
         */
        int get_gaze_is_acquired();

        /*l
         *b  Description:
         **
         **    A gaze is steady if it is acquired, and if all links involved
         **    in the gaze have reached a steady state.
         **
         **    For example, since the eyes move faster than the neck, which
         **    moves faster than the back, it's possible for the gaze to
         **    be acquired (see get_gaze_is_acquired()) by the eyes as the
         **    neck and back are still moving.  As the neck and back move into
         **    a more natural position, the eyes will not need to be turned
         **    as far to keep the gaze acquired.
         **
         **    If either the acquired or steady status of a gaze has changed
         **    (e.g., was acquired but now is not, or was steady but now
         **    a link is moving), the diguyCharacter callback with callback_id
         **    CALLBACK_ID_GAZE_STATUS will be called.
         **
         *b  Returns:
         **
         *-    - 1 if all links participating in the gaze have reached a
         *-      relatively steady state
         *-    - 0 if not
         *-    - -1 on error
         */
        int get_gaze_is_steady();

        /*l
         *b  Description:
         **
         **    This function removes the fixation target of an ongoing gaze,
         **    allowing the character to return to a non-gaze posture and
         **    behavior.  This effectively frees the character's posture to
         **    other influences.
         */
        int end_gaze();

        /*l
         *b  Description:
         **
         **    This function is similar to gaze_at_angle(), but sets the target
         **    of left pointing rather than gaze.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    azimuth   - rotation in degrees about up (vertical) axis;
         *a                positive rotates to character's left
         *a    elevation - rotation in degrees about forward (horizontal) axis;
         *a                positive rotates down
         *a    distance  - distance in meters from the position of the character
         *a                to the lpoint target; positive values only
         *a    is_new_lpoint - set to 1 if this is a new lpoint;
         *a                    set to 0 if this is continuing an already started
         *a                    lpoint
         *a    base_gesture_name - the underlying gesture that should be used for
         *a                        motion of the arm; this is a placeholder
         *a                        argument for future functionality and should
         *a                        be set to NULL
         */
        int lpoint_at_angle(float azimuth,
                float elevation,
                float distance,
                int is_new_lpoint = 1,
                const char* base_gesture_name = 0);

        /*l
         *b  Description:
         **
         **    This function is identical to gaze_at_local() except that it uses
         **    body local coordinates for the character.  Use get_position()
         **    to learn the idealized position of the character if necessary.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         */
        int lpoint_at_angle_local(float azimuth,
                float elevation,
                float distance = 10000.0f,
                int is_new_lpoint = 1,
                const char* base_gesture_name = 0);

        /*l
         *b  Description:
         **
         **    This function sets the current fixation point for the character's
         **    left pointing.  Point coordinates are given in meters in the
         **    DI-Guy global coordinate system.
         **
         **    See set_position() for a description of the coordinate
         **    system.
         **
         **    Pointing will continue until end_lpoint() is called.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    tx, ty, tz  - position in meters from the DI-Guy global
         *a                  origin of the lpoint target
         *a    is_new_gaze - set to 1 if this is a new lpoint;
         *a                  set to 0 if this is continuing an already started
         *a                  lpoint
         *a    base_gesture_name - the underlying gesture that should be used for
         *a                        motion of the arm; this is a placeholder
         *a                        argument for future functionality and should
         *a                        be set to NULL
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int lpoint_at_point(float tx,
                float ty,
                float tz,
                int is_new_lpoint = 1,
                const char* base_gesture_name = 0);

        /*l
         *b  Description:
         **
         **    This function is identical to lpoint_at_local() except that it uses
         **    body local coordinates for the character.  Use get_position()
         **    to learn the idealized position of the character if necessary.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         */
        int lpoint_at_point_local(float tx,
                float ty,
                float tz,
                int is_new_lpoint = 1,
                const char* base_gesture_name = 0);

        /*l
         *b  Description:
         **
         **    This function is identical to gaze_at_character(), but sets the
         **    target of left pointing rather than gaze.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         */
        int lpoint_at_character(const char* target_character_name,
                const char* target_character_link_name = NULL,
                float offset_tx = 0.0f,
                float offset_ty = 0.0f,
                float offset_tz = 0.0f);

        /*l
         *b  Returns:
         **
         **    the current lpoint target point relative to the DI-Guy
         **    global coordinate system
         */
        int get_lpoint_point(float* x, float* y, float* z);

        /*l
         *b  Returns:
         **
         **    the current base gesture of the lpoint
         */
        const char* get_lpoint_base_gesture_name();

        /*l
         *b  Returns:
         **
         **    1 if the character is actively lpointing, 0 if not
         */
        int get_lpoint_is_active();

        /*l
         *b  Returns:
         **
         **    1 if the final link in the lpoint can and has become oriented
         **    toward the lpoint target;
         **    0 if not;
         **    -1 on error
         */
        int get_lpoint_is_acquired();

        /*l
         *b  Returns:
         **
         **    1 if all links participating in the lpoint have reached a
         **    relatively steady state;
         **    0 if not;
         **    -1 on error
         */
        int get_lpoint_is_steady();

        /*l
         *b  Description:
         **
         **    This function removes the fixation target of an ongoing lpoint,
         **    allowing the character to return to a non-point posture and
         **    behavior.  This effectively frees the character's posture to
         **    other influences.
         */
        int end_lpoint();

        /*l
         *b  Description:
         **
         **    This function sets all gaze control parameters back to their
         **    default settings.  This undoes modifications to gaze control
         **    parameters made by the following calls:
         **
         *-    - set_gaze_param_desired_locate_time()
         *-    - set_gaze_link_uses_desired_locate_time()
         *-    - set_gaze_link_azimuth_limits()
         *-    - set_gaze_link_elevation_limits()
         *-    - set_gaze_link_azimuth_tolerance()
         *-    - set_gaze_link_elevation_tolerance()
         *-    - set_gaze_link_max_angular_vel()
         *-    - set_gaze_link_scale_factor()
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_gaze_params_to_defaults();

        /*l
         *b  Description:
         **
         **    This function sets the desired amount of time in seconds it
         **    will take for the gaze or point target to be acquired.
         **
         **    Having a desired locate time effectively limits how fast links
         **    in the gaze chain can turn; they will turn as fast as it
         **    takes for them to arrive at their proper values, or as fast
         **    as their maximum angular velocity, whichever is longer.
         **
         **    The use of desired locate time can be turned on and off on a
         **    link by link bases using the function
         **    set_gaze_link_uses_desired_locate_time().
         **
         **    This value is only a guideline and may be overridden on a link
         **    by link basis during the actual gaze, as links try not to
         **    exceed their maximum angular velocities.
         **
         **    The default locate time is 1.0 seconds.
         **
         *b  Arguments:
         **
         *a    t - lower value results in faster turning rate
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_gaze_param_desired_locate_time(float t);

        /*l
         *b  Returns:
         **
         **    the most recent setting of set_gaze_param_desired_locate_time()
         */
        float get_gaze_param_desired_locate_time();

        /*l
         *b  Description:
         **
         **    This function sets whether the specified link will pay attention
         **    to the desired locate time (as set by
         **    set_gaze_param_desired_locate_time()), or whether the link turns
         **    as fast as its maximum angular velocity allows (as set by
         **    set_gaze_link_max_angular_vel()).
         **
         **    Note that if this value is set to 1, the link still pays attention
         **    to its maximum angular velocity as an upper limit on how fast
         **    it can turn.
         **
         **    Valid link names and defaults:
         **
         *a     orientation - 1
         *a     back        - 1
         *a     cervical    - 1
         *a     eye_l       - 0
         *a     shoulder_l  - 1
         *a     elbow_l     - 1
         **
         *b  Arguments:
         **
         *a    link_name                - name of the link
         *a    uses_desired_locate_time - 1 to use desired locate time, 0
         *a                               to disregard
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_gaze_link_uses_desired_locate_time(const char* link_name,
                int uses_desired_locate_time);

        /*l
         *b  Returns:
         **
         **    the most recent setting of set_gaze_link_uses_desired_locate_time()
         */
        int get_gaze_link_uses_desired_locate_time(const char* link_name);

        /*l
         *b  Description:
         **
         **    This function sets the maximum amount the character can turn
         **    the specified link horizontally in pursuit of a gaze or point
         **    target.
         **
         **    Valid link names and defaults:
         **
         *a     back        -  -45 to  45
         *a     cervical    -  -80 to  80
         *a     eye_l       -  -50 to  50
         *a     shoulder_l  -  -30 to 135
         *a     elbow_l     -  -30 to  10
         **
         *b  Arguments:
         **
         *a    link_name  - name of the link
         *a    min        - value <= 0; in degrees
         *a    max        - value >= 0; in degrees
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_gaze_link_azimuth_limits(const char* link_name, float min, float max);

        /*l
         *b  Returns:
         **
         **    the most recent setting of set_gaze_link_azimuth_max()
         */
        int get_gaze_link_azimuth_limits(const char* link_name,
                float* min,
                float* max);

        /*l
         *b  Description:
         **
         **    This function sets the maximum amount the character can turn
         **    the specified link vertically in pursuit of a gaze or point
         **    target.
         **
         **    Valid link names and defaults:
         **
         *a     back        -   -15 to 45
         *a     cervical    -   -80 to 45
         *a     eye_l       -   -40 to 40
         *a     shoulder_l  -   -80 to 80
         *a     elbow_l     -  -170 to  0
         **
         *b  Arguments:
         **
         *a    link_name  - name of the link
         *a    min        - value <= 0; in degrees
         *a    max        - value >= 0; in degrees
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_gaze_link_elevation_limits(const char* link_name,
                float min,
                float max);

        int get_gaze_link_elevation_limits(const char* link_name,
                float* min,
                float* max);

        /*l
         *b  Description:
         **
         **    This function sets how much difference there can be between
         **    the link's current horizontal orientation and the gaze or point
         **    target before the link begins to turn to acquire the gaze or
         **    point target.
         **
         **    The combination of this function and
         **    set_gaze_link_scale_factor() determine how close the link will
         **    turn toward the gaze or point target.
         **
         **    With a looser (higher) tolerance the link will not turn as much
         **    toward the target.  With a tighter (lower) tolerance the link
         **    will turn more toward the target.
         **
         **    Valid link names and defaults:
         **
         *a     orientation - -30 to 30
         *a     back        - -45 to 45
         *a     cervical    -  -5 to  5
         *a     eye_l       -  -1 to  1
         *a     shoulder_l  -  -5 to  5
         *a     elbow_l     -  -5 to  5
         **
         *b  Arguments:
         **
         *a    link_name  - name of the link
         *a    min        - value <= 0; in degrees
         *a    max        - value >= 0; in degrees
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_gaze_link_azimuth_tolerance(const char* link_name,
                float min,
                float max);

        int get_gaze_link_azimuth_tolerance(const char* link_name,
                float* min,
                float* max);

        /*l
         *b  Description:
         **
         **    The elevation equivalent of set_gaze_link_azimuth_tolerance(),
         **
         **    Valid link names and defaults:
         **
         *a     orientation - -90 to 90
         *a     back        - -45 to 45
         *a     cervical    -  -5 to  5
         *a     eye_l       -  -1 to  1
         *a     shoulder_l  -  -5 to  5
         *a     elbow_l     -  -5 to  5
         **
         *b  Arguments:
         **
         *a    link_name  - name of the link
         *a    min        - value <= 0; in degrees
         *a    max        - value >= 0; in degrees
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_gaze_link_elevation_tolerance(const char* link_name,
                float min,
                float max);

        int get_gaze_link_elevation_tolerance(const char* link_name,
                float* min,
                float* max);

        /*l
         *b  Description:
         **
         **    This function sets the maximum angular velocity that the
         **    back link angles may attain in pursuit of a gaze or point target.
         **
         **    Valid link names and defaults:
         **
         *a     back        -  30 deg/s
         *a     cervical    -  60 deg/s
         *a     eye_l       - 180 deg/s
         *a     shoulder_l  - 180 deg/s
         *a     elbow_l     - 180 deg/s
         **
         *b  Arguments:
         **
         *a    link_name   - name of the link
         *a    angular_vel - angular velocity in degrees per second
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_gaze_link_max_angular_vel(const char* link_name, float angular_vel);

        int get_gaze_link_max_angular_vel(const char* link_name, float* angular_vel);

        /*l
         *b  Description:
         **
         **    This function sets how much the link will make up the difference
         **    toward the gaze or point target.
         **
         **    The combination of this function and
         **    the tolerances determine how close the
         **    link will turn toward the gaze or point target.
         **
         **    With a smaller scale factor the link will not turn as much toward
         **    the target.  With a higher scale factor the link will turn more
         **    toward the target.
         **
         **    For example, if the gaze or point target is at 60 degrees yaw in
         **    back coordinates and the scale factor is 0.5, the back will turn
         **    30 degrees in pursuit of the target.
         **
         **    Valid link names and defaults:
         **
         *a     back        - 0.75
         *a     cervical    - 0.5
         *a     eye_l       - 1.0
         *a     shoulder_l  - 0.9
         *a     elbow_l     - 1.0
         **
         *b  Arguments:
         **
         *a    link_name    - name of the link
         *a    scale_factor - scale factor between 0 and 1
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_gaze_link_scale_factor(const char* link_name, float scale_factor);

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

        /*l
         *b  Description:
         **
         **    This function sets whether the character can turn the specified
         **    link in pursuit of the gaze target.
         **
         **    Valid link names and defaults:
         **
         *a     orientation - 0
         *a     back        - 1
         *a     cervical    - 1
         *a     eye_l       - 1 if character has movable eyes, else 0
         *a     shoulder_l  - 0
         *a     elbow_l     - 0
         **
         *b  Arguments:
         **
         *a    link_name - name of the link
         *a    enabled   - 1 to enable, 0 to disable
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_link_enabled_for_gaze(const char* link_name, int enabled);

        int get_link_enabled_for_gaze(const char* link_name);

        /*l
         *b  Description:
         **
         **    This function sets whether the character can change its current
         **    posture in pursuit of the gaze target.
         **
         **    Gaze can change current posture by default.
         **
         *b  Arguments:
         **
         *a    enabled   - 1 to enable, 0 to disable
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_gaze_can_change_posture(int enabled);

        int get_gaze_can_change_posture();

        /*l
         *b  Description:
         **
         **    This function sets whether the character can change its current
         **    variant in pursuit of the gaze target.
         **
         **    Gaze can change current variant by default.
         **
         *b  Arguments:
         **
         *a    enabled   - 1 to enable, 0 to disable
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_gaze_can_change_variant(int enabled);

        int get_gaze_can_change_variant();

        /*l
         *b  Description:
         **
         **    This function sets whether the character can move the specified
         **    link in pursuit of the lpoint target.
         **
         **    Valid link names and defaults:
         **
         *a     orientation - 0
         *a     back        - 1
         *a     cervical    - 0
         *a     eye_l       - 0
         *a     shoulder_l  - 1
         *a     elbow_l     - 1
         **
         *b  Arguments:
         **
         *a    link_name - name of the link
         *a    enabled   - 1 to enable, 0 to disable
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_link_enabled_for_lpoint(const char* link_name, int enabled);

        int get_link_enabled_for_lpoint(const char* link_name);

        /*l
         *b  Description:
         **
         **    This function adjusts the current azimuth and elevation offsets
         **    of the character's head.  If a gaze is ongoing, then the nod will
         **    be supplemented to the gazing, and the character will attempt to
         **    maintain its gaze.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    azimuth   - rotation offset about z (vertical) axis, in degrees;
         *a                positive rotates to character's left
         *a    elevation - rotation offset about y (horizontal) axis, in degrees;
         *a                positive rotates down
         *a    duration  - how long it should take to attain the new azimuth
         *a                and elevation
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_nod(float azimuth,
                float elevation,
                float duration = 0.5f);

        /*l
         *b  Description:
         **
         **    This function causes the character to nod its head for the
         **    specified number of times over the specified duration.
         **
         **    If nod_count is 0.5, the elevation of the head will move from its
         **    current elevation straight to nod_elevation_out. The arguments
         **    nod_elevation0 and nod_elevation1 will be ignored.
         **
         **    If nod_count is 1.0, the elevation of the head will move from
         **    its current elevation to nod_elevation0, then to
         **    nod_elevation_out.  The argument nod_elevation1 will be ignored.
         **
         **    If nod_count is 1.5 or greater, the nod elevation will begin at
         **    its current elevation, move to nod_elevation0, then alternate
         **    between nod_elevation0 and nod_elevation1, before finally ending
         **    at nod_elevation_out.
         **
         **    The head will maintain an elevation offset of nod_elevation_out
         **    until a new call to nod_head() or set_nod() is made.
         **
         **    This function overrides any nod settings made by the set_nod()
         **    function.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    duration          - for how long the nod should be executed
         *a    nod_count         - how many nods the character should perform;
         *a                        this will be rounded to the nearest multiple
         *a                        of 0.5
         *a    nod_elevation0    - elevation of initial nod in degrees
         *a    nod_elevation1    - elevation of return nod in degrees
         *a    nod_elevation_out - ending elevation when nod is complete
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int nod_head(float duration,
                float nod_count,
                float nod_elevation0 = 15.0f,
                float nod_elevation1 = 0.0f,
                float nod_elevation_out = 0.0f);

        /*l
         *b  Description:
         **
         **    This function is similar to nod_head(), except the direction
         **    of head movement is side to side rather than up and down.
         **    See the nod_head() function for a detailed description of usage.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    duration          - for how long the shake should be executed
         *a    shake_count       - how shakes the character should perform; this
         *a                        will be rounded to the nearest multiple of
         *a                        0.5
         *a    shake_azimuth0    - azimuth of initial shake in degrees
         *a    shake_azimuth1    - azimuth of return shake in degrees
         *a    shake_azimuth_out - ending azimuth when shake is complete
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int shake_head(float duration,
                float shake_count,
                float shake_azimuth0 = -20.0f,
                float shake_azimuth1 = 20.0f,
                float shake_azimuth_out = 0.0f);

        /*l
         *b  Returns:
         **
         **    current nod azimuth setting; see set_nod(), nod_head(), and
         **    shake_head()
         */
        float get_nod_azimuth();

        /*l
         *b  Returns:
         **
         **    current nod elevation setting; see set_nod(), nod_head(), and
         **    shake_head()
         */
        float get_nod_elevation();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets the current desired azimuth and elevation of
         **    the character's aim.  The angles are in character-local
         **    coordinates.  Zero values mean straight ahead and level.
         **    Aiming will continue until end_aim() is called.
         **
         **    This function effectively calls aim_at_angle_local(), with a
         **    distance of 10000 meters, and is_new_aim set to 1.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    azimuth   - rotation about z (vertical) axis, in degrees;
         *a                positive rotates to character's left
         *a    elevation - rotation about y (horizontal) axis, in degrees;
         *a                positive rotates down
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_aim(float azimuth, float elevation);

        /*l
         *b  Description:
         **
         **    This function sets the current azimuth, elevation, and
         **    distance of the character's aim.  A fixed point in 3D space is
         **    then found using the two angles and the given distance from
         **    the character's idealized position.  Angles are given with
         **    respect to the DI-Guy global coordinate system.
         **
         **    See set_position() for a description of the coordinate
         **    system.
         **
         **    Aiming will continue until end_aim() is called.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    azimuth    - rotation in degrees about up (vertical) axis;
         *a                 positive rotates to the character's left; zero means
         *a                 in the direction of the positive X axis of the Boston
         *a                 Dynamics coordinate system
         *a    elevation  - rotation in degrees about horizontal axis; positive
         *a                 rotates down
         *a    distance   - distance in meters from the idealized position of the
         *a                 character to the aim target; positive values only,
         *a                 typically this is a large value (e.g. 10,000 meters)
         *a    is_new_aim - set to 1 if this is a new aim, for jumping to a
         *a                 new target;
         *a                 set to 0 if this is continuing an already
         *a                 started aim, for tracking an existing target
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int aim_at_angle(float azimuth,
                float elevation,
                float distance,
                int is_new_aim = 1);

        /*l
         *b  Description:
         **
         **    This function is identical to aim_at_angle() except that it
         **    uses body local coordinates for the character.  The angles are
         **    given with respect to the idealized position of the character.
         **    Use get_position() to learn the idealized position.  The
         **    distance is between the idealized position of the character
         **    and the fixation point.  Aiming will continue until end_aim()
         **    is called.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         */
        int aim_at_angle_local(float azimuth,
                float elevation,
                float distance,
                int is_new_aim = 1);

        /*l
         *b  Description:
         **
         **    This function sets the current fixation point of the
         **    character's aim.  Point coordinates are given in meters in the
         **    DI-Guy global coordinate system.
         **
         **    The function uses default aim behavior settings.  Aiming will
         **    continue until end_aim() is called.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    tx, ty, tz - position in meters from the DI-Guy global
         *a                 origin
         *a    is_new_aim - set to 1 if this is a new aim;
         *a                 set to 0 if this is continuing an already started aim
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int aim_at_point(float x, float y, float z, int is_new_aim = 1);

        /*l
         *b  Description:
         **
         **    This function is identical to aim_at_point() except that it
         **    uses body local coordinates for the character.  Use
         **    get_position() to learn the idealized position of the
         **    character if necessary.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         */
        int aim_at_point_local(float x, float y, float z, int is_new_aim = 1);

        /*l
         *b  Description:
         **
         **    This function effectively does an aim_at_point() each tick.
         **    The point to be aimed at is updated each tick to be the position
         **    of the specified link on the specified character.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    target_character_name           - name of the character to be
         *a                                      aimed at
         *a    target_character_link_name      - link on the character that should
         *a                                      be aimed at; pass NULL or "" to
         *a                                      aim at the position link of the
         *a                                      character. If NULL is passed,
         *a                                                                              function will make best effort to
         *a                                                                              choose a character-appropriate link
         *a                                                                              to target.
         *a    offset_tx, offset_ty, offset_tz - offset onto the link, in meters
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         **
         *b  C++ Example:
         **
         *e    // aim at the head of character "soldier-1".
         *e    ch->aim_at_character("soldier-1",
         *e        "cervical",
         *e        0.0,
         *e        0.0,
         *e        0.0);
         */
        int aim_at_character(const char* target_character_name,
                const char* target_character_link_name = NULL,
                float offset_tx = 0.0f,
                float offset_ty = 0.0f,
                float offset_tz = 0.0f);

        /*l
         *b  Description:
         **
         **    This function terminates aiming started by the set_aim(),
         **    aim_at_point(), aim_at_point_local(), aim_at_angle(),
         **    aim_at_angle_local(), and aim_at_character() functions.
         */
        void end_aim();

        const char * get_aim_at_character();

        float get_aim_azimuth();

        float get_aim_elevation();

        /*l
         *b  Returns:
         **
         **    1 if the character is aiming 0 if not
         **
         *b  Arguments:
         **
         *a    muzzle_x, muzzle_y, muzzle_z - position of muzzle in meters from
         *a                                   the origin
         *a    far_x, far_y, far_z - position of end target in meters from the
         *a                          origin
         **
         **    Pass NULL for any values that are not needed.
         **    Note: values will be zero if the character isn't currently aiming
         */
        int get_aim_trajectory(float* muzzle_x, float* muzzle_y, float* muzzle_z,
                float* far_x, float* far_y, float* far_z);

        /*l
         *b  Description:
         **
         **    Not all actions of a character will be affected by aim
         **    commands.  This function returns 1 if this character
         **    is currently in an aim-able action.
         **
         *b  Returns:
         **
         **    1 if current action is aim-able; 0 if not
         */
        int get_aim_is_possible();

        /*l
         *b  Returns:
         **
         **    1 if the aim is acquired, 0 if not
         */
        int get_aim_is_acquired();

        /*l
         *b  Returns:
         **
         **    1 if all links participating in the aim have reached a
         **    relatively steady state, 0 if not, -1 on error
         */
        int get_aim_is_steady();


        /*l
         *b  Returns:
         **
         **    1 if character is currently aiming, 0 if not
         */
        int get_is_aiming();


        /******************************************************
         **
         *3  Aim Algorithm 8 Parameters
         **
         **    This aim algorithm works by adjusting the aiming character's pose
         **    such that the difference between the current aim angles and the
         **    desired aim angles is decreased each scenario tick.
         **
         **    How much of that difference that is made up each frame is
         **    determined by the factor parameters.  The difference between the
         **    desired aim angles and the current aim angles, multiplied by a
         **    calculated factor, is added to the current aim angles each frame.
         **    This causes the aim to "home in" on the desired aim angles.
         **
         **    For example, if for each frame the calculated factor is 0.5, half
         **    of the difference between the desired and current aim angles is
         **    made up.
         **
         **  Unless otherwise specified, all functions callable from:
         **
         *-    - C++
         *-    - Script
         */

        /*l
         *b  Description:
         **
         **    This function sets the steady-state factor that is used once
         **    an aim is no longer considered "new".
         **
         **    See the function set_aim_param_new_aim_duration() for information
         **    on when an aim is considered new, and how the effective acquire
         **    is calculated from this steady-state acquire factor and the
         **    new aim factor.
         **
         *b  Arguments:
         **
         *a    factor - unitless value between 0 and 1; default is 0.6
         */
        void set_aim_param_acquire_factor(float factor);

        /*l
         *b  Returns:
         **
         **    the current aim acquire factor parameter
         */
        float get_aim_param_acquire_factor();

        /*l
         *b  Description:
         **
         **    This function sets the factor that is used when an aim is
         **    considered new.
         **
         **    See the function set_aim_param_new_aim_duration() for information
         **    on when an aim is considered new, and how the effective acquire
         **    is calculated from this new aim factor and the steady-state acquire
         **    factor.
         **
         *b  Arguments:
         **
         *a    factor - unitless value between 0 and 1; default is 0.05
         */
        void set_aim_param_new_aim_factor(float factor);

        float get_aim_param_new_aim_factor();

        /*l
         *b  Description:
         **
         **    This function sets how long an aim is considered "new".
         **
         **    When an aim is brand-new, the effective acquire factor is equal
         **    to the new aim factor as set by set_aim_param_new_aim_factor().
         **    When the new aim duration has expired, the effective acquire factor
         **    is equal to the steady-state acquire factor as set by
         **    set_aim_param_acquire_factor().  In between, the effective acquire
         **    factor moves smoothly between the two.
         **
         **    For example, say that the new aim factor is 0.1, the acquire factor
         **    is 0.5, and the new aim duration is 0.2 seconds.
         **    If a new aim is started, say by a call to aim_at_angle_local(),
         **    the effective acquire factor of the first frame will be 0.1.  Over
         **    the next 0.2 seconds, the effective acquire factor will smoothly
         **    ramp up to 0.5, where it will stay until the aim is acquired.
         **
         *b  Arguments:
         **
         *a    duration - how long, in seconds, a new aim should be considered
         *a               new; default is 1 second
         */
        void set_aim_param_new_aim_duration(float duration);

        float get_aim_param_new_aim_duration();

        /*l
         *b  Description:
         **
         **    This function sets the maximum factor that can be used for any
         **    single frame for aim convergence attempts.
         **
         **    See set_aim_param_acquire_factor() for a discussion of why setting
         **    this too close to 1 is not recommended.
         **
         *b  Arguments:
         **
         *a    factor - unitless value between 0 and 1; default is 0.95
         */
        void set_aim_param_max_per_frame_adj_factor(float factor);

        float get_aim_param_max_per_frame_adj_factor();

        /*l
         *b  Description:
         **
         **    This function sets how close the current aim azimuth must be to
         **    the desired aim azimuth in order for the aim to be considered
         **    acquired.
         **
         **    Note that the aim isn't fully acquired until both azimuth and
         **    elevation are acquired.
         **
         **    Setting this value too close to 0 will result in the aim never
         **    being acquired.
         **
         *b  Arguments:
         **
         *a    range - how close, in degrees, the azimuth must be for the
         *a            aim to be acquired; default is 0.5 degrees
         */
        void set_aim_param_azimuth_acquired_range(float range);

        float get_aim_param_azimuth_acquired_range();

        /*l
         *b  Description:
         **
         **    This function sets how close the current aim elevation must be to
         **    the desired aim elevation in order for the aim to be considered
         **    acquired.
         **
         **    Note that the aim isn't fully acquired until both azimuth and
         **    elevation are acquired.
         **
         **    Setting this value too close to 0 will result in the aim never
         **    being acquired.
         **
         *b  Arguments:
         **
         *a    range - how close, in degrees, the elevation must be for the
         *a            aim to be acquired; default is 1.0 degrees
         */
        void set_aim_param_elevation_acquired_range(float range);

        float get_aim_param_elevation_acquired_range();
        
        /*l
         *b  Description:
         **
         **    This function attempts to have the character reach its desired
         **    aim angles instantly, every frame.  
         **
         **    Set enabled to 0 to disable instant aim convergence.
         **
         */
        void set_aim_converge_every_frame( int enabled );

        int get_aim_converge_every_frame();

                
/*****************************************************************************/
        const char* get_aim_at_link();

        int get_aim_at_link_offset(float* offset_x, float* offset_y, float* offset_z);

        const char* get_gaze_at_link();

        int get_gaze_at_link_offset(float* offset_x, float* offset_y, float* offset_z);

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function causes a character to fire his weapon.
         **
         **    Different weapons have different "munition types", which specify,
         **    among other things, the sound to be played, the network info to be
         **    sent, and muzzle flash effect.  See
         **    get_weapon_muzzle_munition_type() for more information on munition
         **    types.
         **
         **    If the weapon fires live rounds (as set by
         **    set_weapon_fires_live_rounds()) this function also computes a
         **    bullet trajectory, perhaps hitting and killing another character.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int fire_weapon(diguyMuzzle muzzle = DIGUY_MUZZLE_DEFAULT);

        /*l
         *b  Description:
         **
         **    This function causes a character to fire his weapon the
         **    specified number of times.  This causes a muzzle flash and
         **    the weapon's sound (if any) to be played.
         **
         **    The sound played will be one of, in order:
         **
         *-    - the passed override_sound_name, or
         *-    - the sound set by set_weapon_sound_override(), or
         *-    - the default weapon sound based on the character's appearance
         **
         **    If the weapon fires live rounds (as set by
         **    set_weapon_fires_live_rounds()), this function also computes a
         **    trajectory for each round, perhaps hitting and killing
         **    another character.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    count      - number of times weapon should be fired
         *a    override_sound_name - override sound to be played
         *a    dt         - time between firings if count > 1
         *a    muzzle     - muzzle on which flash should appear
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int fire_weapon_n_times(int count,
                float dt = 0.2f,
                const char* override_sound_name = NULL,
                diguyMuzzle muzzle = DIGUY_MUZZLE_DEFAULT);

        /*l
         *b  Description:
         **
         **    Fires a bullet at point (x, y) from the camera, using this
         **    character as the attacker.
         **
         *i    Currently OpenGL only.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Returns:
         **
         **    number of hits
         */
        int fire_screen_space_bullet(diguyView* view, float x, float y);

        /*l
         *b  Returns:
         **
         **    number of times weapon has been fired from specified muzzle
         **
         *b  Available as Decision Bead/Event
         */
        int get_weapon_fire_count(diguyMuzzle muzzle = DIGUY_MUZZLE_DEFAULT);

        /*l
         *b  Description:
         **
         **    This function sets the default muzzle that will flash when
         **    the character fires its weapon due to a call to fire_weapon()
         **    or fire_weapon_n_times().
         **
         **    The default value is DIGUY_MUZZLE_DEFAULT.
         **
         *b  Arguments:
         **
         *a    muzzle - the muzzle that will flash; muzzle 1 is common
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_default_weapon_muzzle(diguyMuzzle muzzle);

        /*l
         *b  Returns:
         **
         **    current default weapon muzzle that flashes when the character's
         **    weapon is fired; see set_default_weapon_muzzle()
         */
        diguyMuzzle get_default_weapon_muzzle();

        /*l
         *b  Description:
         **
         **    When the character fires its weapon, the results depend on the
         **    munition type of the muzzle fired from.  Munition types specify,
         **    among other things:
         **
         *-    - sound played
         *-    - muzzle flash effect
         *-    - network data sent (DIS septet)
         *-    - detonation effect
         *-    - detonation radius
         *-    - etc.
         **
         **    Default munition types for the each muzzle are set automatically
         **    when the character's appearance is set.  The munition type of the
         **    weapon can be overridden by calling
         **    set_weapon_munition_type_override().
         **
         **    Current munition types include:
         **
         *-    - m16
         *-    - m4
         *-    - m60
         *-    - m240
         *-    - m249
         *-    - m9
         *-    - hand_gun
         *-    - 50cal
         *-    - m256
         *-    - ak47
         *-    - pk74
         *-    - dragunov
         *-    - sa80
         *-    - rpg
         *-    - m203
         *-    - 40mm_hedp
         *-    - javelin
         *-    - stinger
         *-    - at4
         *-    - sa7
         *-    - molotov_cocktail
         *-    - 60mm_mortar
         *-    - 82mm_mortar
         *-    - 155mm_artillery
         *-    - IED_mortar
         *-    - VBIED
         *-    - m242
         *-    - 120mm
         *-    - 125mm
         *-    - ced
         *-    - pepper_spray
         **
         *b  Returns:
         **
         **    munition type of specified muzzle
         */
        const char* get_weapon_muzzle_munition_type(diguyMuzzle muzzle);

        const char* get_default_muzzle_munition_type();

        /*l
         *b  Description:
         **
         **    This function allows the default munition type to be overridden.
         **    The default value is NULL (don't override default munition type).
         **
         *b  Arguments:
         **
         *a    munition_type - name of a munition type
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_weapon_munition_type_override(const char* munition_type);

        const char* get_weapon_munition_type_override();

        /*l
         *b  Description:
         **
         **    This function sets whether the character's weapons fire live
         **    rounds.  If so, when fire_weapon() and fire_weapon_n_times() are
         **    called the trajectory of the bullet will be calculated and checked
         **    against characters in the scenario.
         **
         **    The default value is 1.
         **
         *b  Arguments:
         **
         *a    weapon_fires_live_rounds - set to 1 for live rounds; set to 0
         *a                               for "blanks"
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int set_weapon_fires_live_rounds(int weapon_fires_live_rounds);

        /*l
         *b  Returns:
         **
         **    current setting of whether weapon fires live rounds or blanks; see
         **    set_weapon_fires_live_rounds()
         **
         *b  Available as Decision Bead/Event
         */
        int get_weapon_fires_live_rounds();

        /*l
         *b  Description:
         **
         **    A weapon sound is played when the character fires its weapon
         **    due to a call to fire_weapon() or fire_weapon_n_times().
         **    The sound that is played is generally derived from the weapon's
         **    munition type, which can be different for each muzzle.
         **
         **    This function overrides the default sound that will be played.
         **    Note that this overrides the sound for all muzzles.
         **
         **    The default value is NULL (don't override default sound).
         **
         **    To *not* play a sound at all, set the weapon sound gain override
         **    to 0.
         **
         *b  Arguments:
         **
         *a    sound - name of a sound defined in the scenario;
         *a            pass NULL to specify that default should be played
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_weapon_sound_override(const char* sound_name);

        /*l
         *b  Description:
         **
         **    The function returns the current weapon sound override, if one
         **    is set; see set_weapon_sound_override().
         **
         **    This function will not return NULL.  The empty string ("") is
         **    returned if a weapon sound override is not set.
         **
         *b  Returns:
         **
         **    name of weapon sound override
         */
        const char* get_weapon_sound_override();

        /*l
         *b  Description:
         **
         **    This function overrides the default gain on the sound played
         **    due to a call to fire_weapon() or fire_weapon_n_times().
         **
         **    Pass 1.0 to use the sound's default amplitude.  Lower numbers
         **    decrease volume, higher numbers increase volume.
         **
         **    Pass 0.0 to completely disable playing of weapon sound.
         **
         **    The default value is 3.0.
         **
         **    See set_weapon_sound_override().
         **
         *b  Arguments:
         **
         *a    sound_gain - amount by which to change sound volume
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_weapon_sound_gain_override(float gain);

        float get_weapon_sound_gain_override();

        /*l
         *b  Description:
         **
         **    This function provides aiming assistance by making it possible for
         **    roughly-aimed weapons to hit targets.  When spread is nonzero,
         **    fire_weapon searches for a target within a conical space centered
         **    on the muzzle.  Within this cone, the live character within weapon
         **    range, and with the smallest angular deviation from the weapon, is
         **    chosen, by default, as the target.  Other function calls may alter
         **    this aiming behavior, making it aim only at enemy targets, for
         **    example, or making it prefer close targets to far ones.
         **
         *b  Arguments:
         **
         *a    spread - angular deviation from weapon muzzle within which a
         *a             target will be found
         **
         **    Spread values above 145 are suicidal (character can shoot himself).
         **    90 is the highest sensible value, which covers everything ahead
         **    of the weapon muzzle.  A value of 0 is the default, meaning that
         **    only targets in line with the muzzle are hit.
         */
        void set_weapon_spread(float spread);

        /*l
         *b  Description:
         **
         **    This function affects how targets are chosen when
         **    the character's weapon_spread is nonzero.  Only
         **    characters more than near_range meters away from the muzzle
         **    will be fired upon.  Characters which are closer than
         **    near_range meters will not be fired upon.
         **
         **    This value does not affect weapon behavior when weapon_spread
         **    is zero.
         **
         **    If this function is never called for a character, it is as if
         **    the function had been called with a value of zero.
         **
         *b  Arguments:
         **
         *a    near_range - distance closer than which no character will be
         *a                 targeted
         */
        void set_weapon_near_range(float near_range);

        /*l
         *b  Description:
         **
         **    This function sets the range of the character's
         **    weapon.
         **
         **    If this function is never called for a character, it is as if
         **    the function had been called with a value of 500.0.
         **
         *b  Arguments:
         **
         *a    far_range - range of the weapon in meters
         */
        void set_weapon_far_range(float far_range);

        /*l
         *b  Description:
         **
         **    This function sets a weapon's ratio of hits to fired rounds.  A
         **    value of 1.0 (the default) means the weapon will hit everything it
         **    is aimed at.  Values less than 1.0 cause the weapon to
         **    probabilistically miss targets, even when perfectly aimed at them.
         **    A value of zero means the weapon doesn't hit anything, even if it
         **    is perfectly aimed.  A value of 0.5 will hit half of the time.
         */
        void set_weapon_hit_ratio(float hit_ratio);

        /*l
         *b  Description:
         **
         **    This function sets the number of potential impacts a fired round
         **    can have.  The default is 1.  Specifying more than 1 means the
         **    round will completely go through objects, triggering a
         **    CALLBACK_ID_IMPACT callback each time, until the maximum number of
         **    impacts has been reached.
         */
        void set_weapon_max_impacts(int val);

        /*l
         *b  Returns:
         **
         **    state of accessory1
         */
        int get_accessory1_state();

        /*l
         *b  Returns:
         **
         **    state of the character's rifle
         */
        int get_rifle_state();

        /*l
         *b  Description
         **
         **    This function sets whether the projectiles of certain appearances'
         **    weapons (such as rocket launchers and RPGs) are visible.  Note that
         **    most weapons do not have visible projectiles and this function will
         **    therefore have no effect.
         **
         *b  Arguments:
         **
         *a    muzzle     - which muzzle's projectile should be shown/hidden
         *a    is_visible - pass 1 to show, pass 0 to hide
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_weapon_projectile_is_visible(diguyMuzzle muzzle, int is_visible);

        /*l
         *b  Description
         **
         **    This function returns the most recent setting of
         **    set_weapon_projectile_is_visible().
         **
         *b  Arguments:
         **
         *a    muzzle     - which muzzle's projectile should be queried
         **
         *b  Returns:
         **
         **    1 if visible, 0 if not
         */
        int get_weapon_projectile_is_visible(diguyMuzzle muzzle);

        /*l
         *b  Description:
         **
         **    Retrieves the position and direction of the character's weapon.
         **
         *b  Arguments:
         **
         *a    muzzle_tx, muzzle_ty, muzzle_tz - muzzle position, and beginning
         *a        of aim vector
         *a    end_pt_tx, end_pt_ty, end_pt_tz - end point of aim vector
         *a    muzzle_rz, muzzle_rx, muzzle_ry - orientation of muzzle in degrees
         *a    muzzle - the muzzle for which the aim vector is needed
         *a    in_character_local_coordinates  - pass 0 for values in world
         *a        coordinates (the default), 1 for values in character-local
         *a        coordinates
         **
         **    The muzzle position and end point are in meters from the origin
         **    (if using world coordinates) or in meters from the character's
         **    position (if using character-local coordinates).
         **
         **    The distance of the end point from the muzzle position should
         **    be the weapon's far range, set by set_weapon_far_range().
         **
         **    Pass NULL for any values that are not needed.
         **
         **    *Note:*  The muzzle argument is currently not used, and is present
         **    for future implementation.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_weapon_aim_vector(float* muzzle_tx, float* muzzle_ty, float* muzzle_tz,
                float* end_pt_tx = NULL, float* end_pt_ty = NULL, float* end_pt_tz = NULL,
                float* muzzle_rz = NULL, float* muzzle_rx = NULL, float* muzzle_ry = NULL,
                int in_character_local_coordinates = 0,
                diguyMuzzle muzzle = DIGUY_MUZZLE_DEFAULT);

        /*l
         *b  Description
         **
         **    This function returns the link the passed muzzle is associated
         **    with.  For example, soldier rifle muzzles are attached to the
         **    "rifle_joint" link.
         **
         **    Call get_muzzle_offset() to get the offset of the muzzle on this
         **    link.
         **
         *b  Arguments:
         **
         *a    muzzle - muzzle of interest
         **
         *b  Returns:
         **
         **    name of link, or NULL if the character doesn't have the specified
         **    muzzle
         */
        const char* get_muzzle_link(diguyMuzzle muzzle = DIGUY_MUZZLE_DEFAULT);

        /*l
         *b  Description
         **
         **    This function returns the offset of the muzzle from the link it
         **    is attached to as returned by get_muzzle_link().
         **
         *b  Arguments:
         **
         *a    muzzle                       - muzzle of interest
         *a    offset_x, offset_y, offset_z - variables in which to return results
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_muzzle_offset(diguyMuzzle muzzle = DIGUY_MUZZLE_DEFAULT,
                float* offset_x = NULL,
                float* offset_y = NULL,
                float* offset_z = NULL);

        /*l
         *b  Description
         **
         **    This function sets the highest horizontal error possible when the
         **    weapon is fired.  If non-0, a random horizontal error angle will
         **    be computed and added to the weapon's horizontal aim angle.
         **
         *b  Arguments:
         **
         *a    h_error - highest possible horizontal error
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_weapon_max_azimuth_error(float h_error);

        float get_weapon_max_azimuth_error();

        /*l
         *b  Description:
         **
         **    Similar to set_weapon_max_azimuth_error(), but for vertical aim.
         */
        int set_weapon_max_elevation_error(float v_error);

        float get_weapon_max_elevation_error();

        /*l
         *b  Description
         **
         **    This function sets whether tracer effects will be shown when
         **    the weapon is fired.  Not all weapons will support this effect.
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable, 0 to disable
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_weapon_tracers_enabled(int enabled);

        int get_weapon_tracers_enabled();

        /*l
         *b  Returns:
         **
         **    number of rounds until next tracer
         */
        int get_weapon_rounds_until_tracer(diguyMuzzle muzzle);

        /*l
         *b  Description
         **
         **    This function sets whether a shell eject effect will be shown when
         **    the weapon is fired.  Not all weapons will support this effect.
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable, 0 to disable
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_weapon_shell_eject_enabled(int enabled);

        int get_weapon_shell_eject_enabled();

        /*l
         *b  Description
         **
         **    This function sets whether a smoke effect will be shown when the
         **    weapon is fired.  Not all weapons will support this effect.
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable, 0 to disable
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_weapon_smoke_enabled(int enabled);

        int get_weapon_smoke_enabled();

        /*l
         *b  Description:
         **
         **    Similar to diguyScenario::trigger_detonation(), but detonation
         **    occurs at character's position.
         **
         *b  Arguments:
         **
         *a    munition_name  - name of the munition to detonate
         *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
         **
         **    Note: Overriding the detonation radius will NOT work on broadcast
         **    detonations since the override value is not transmitted.
         */
        int trigger_detonation_on_character(const char* munition_name,
                const char* attacker_name = NULL,
                float radius_override = -1.0f,
                int broadcast_on_network = 1);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function changes the face of the character to reflect the
         **    specified user-defined named facial expression.
         **
         **    Currently affects only "facefx" appearances.
         **
         *b  Arguments:
         **
         *a    facex_name     - name of face expression to be applied
         *a    blend_duration - how long (in seconds) to take to change the face
         *a    strength       - a multiplier between 0 and 1 on the expression 
         **
         **    Face expressions available by default in new scenarios are:
         **
         *-     - Neutral
         *-     - Smile_cl
         *-     - Trust
         *-     - Sad
         *-     - Mad
         *-     - Distrust
         *-     - Conniving
         *-     - Smile
         *-     - BrowsDown
         *-     - BrowsUp
         **
         **    New face expressions can be added using the
         **    diguyScenario::create_face_expression() function.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         **
         *b  C++ Example:
         **
         *e     diguyCharacter* ch = scenario->get_character_at_index(0);
         *e
         *e     // take one second to get mad
         *e     ch->set_face_expression("Mad", 1.0);
         */
        int set_face_expression(const char* facex_name, float blend_duration, float strength = 1.0f);

        /*l
         *b  Description:
         **
         **    This function sets the current azimuth and elevation of the
         **    character's eyes.
         **
         **    Currently affects only "facefx" appearances.
         **
         *b  Arguments:
         **
         *a    azimuth    - rotation about up (vertical) axis, in degrees;
         *a                 positive rotates to character's left
         *a    elevation  - rotation about forward (horizontal) axis, in degrees;
         *a                 positive rotates down
         *a    blend_time - how long to take to reach new orientation
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         */
        int set_orientation_eyes(float azimuth,
                float elevation,
                float blend_time = 0.0f);

        /*l
         *b  Description:
         **
         **    This function gets the current azimuth and elevation of the
         **    character's eyes.  It currently doesn't take blending into account.
         **
         **    Currently affects only "facefx" appearances.
         **/
        int get_orientation_eyes(float* azimuth, float* elevation);

        /*l
         *b  Description:
         **
         **    Sets how open the eyes are.  The eyes will stay at this level
         **    indefinitely.  To get automatic blinking behavior, call blink().
         **
         *b  Arguments:
         **
         *a    droop_amount - 1 = eyes closed, 0 = eyes open, 0.5 = half open
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int set_eye_droop(float droop_amount, float blend_time = 0.0f);

        float get_eye_droop();

        /*l
         *b  Description:
         **
         **    This function blinks the eyes.  To have the eyes close to a
         **    specific amount and stay there, call set_eye_droop().
         **
         **    Only characters with expressive face appearances can blink.
         **
         *b  Arguments:
         **
         *a    duration_in  - how long in seconds the first part of the blink
         *a                   (typically eyes closing) should take
         *a    duration_out - how long in seconds the second part of the blink
         *a                   (typically eyes opening) should take
         *a    target_in    - how closed the eyes should be at duration_in
         *a    target_out   - how open the eyes should be at duration_out and
         *a                   thereafter
         *a    tin          - time at which blink should occur; default is now
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int blink(float duration_in = 0.1f,
                float duration_out = 0.2f,
                float target_in = 1.0f,
                float target_out = 0.0f,
                float tin = DIGUY_DEFAULT_FLOAT);

        /*l
         *b  Description:
         **
         **    This function enables automatic eye blinking, so that blinks
         **    will happen without further function calls.  The various
         **    controlling factors of blinks are set by the following functions:
         **
         *-    - set_automatic_blink_duration_in()
         *-    - set_automatic_blink_duration_out()
         *-    - set_automatic_blink_target_in()
         *-    - set_automatic_blink_target_out()
         **
         **    See blink() for information on what these factors mean.
         **
         **    Only characters with expressive face appearances can blink.
         **
         *b  Arguments:
         **
         *a    enabled          - pass 1 to enable automatic blinks; 0 to disable
         *a    period           - how many seconds between each blink
         *a    period_variation - variation on how many seconds between
         *a                       each blink
         **
         **    If blinks are enabled, the first blink will happen immediately.
         **    Successive blinks will happen between times (period -
         **    period_variation) and (period + period_variation) after the
         **    previous blink ends.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int set_automatic_blinks_enabled(int enabled,
                float period = 6.0f,
                float period_variation = 3.0f);

        int get_automatic_blinks_enabled();

        /*l
         *b  Description:
         **
         **    This function sets how long it will take the eye to close during
         **    automatic eye blinks.  See set_automatic_blinks_enabled() and
         **    blink().
         **
         *b  Arguments:
         **
         *a    duration_in - time in seconds for eye droop to go from droop
         *a                  target in to target out
         **
         *b  Available as Decision Bead/Event
         */
        void set_automatic_blink_duration_in(float duration_in);

        float get_automatic_blink_duration_in();

        /*l
         *b  Description:
         **
         **    This function sets how long it will take the eye to open during
         **    automatic eye blinks.  See set_automatic_blinks_enabled() and
         **    blink().
         **
         *b  Arguments:
         **
         *a    duration_out - time in seconds for eye droop to go from droop
         *a                   target out to target in
         **
         *b  Available as Decision Bead/Event
         */
        void set_automatic_blink_duration_out(float duration_out);

        float get_automatic_blink_duration_out();

        /*l
         *b  Description:
         **
         **    This function sets how much the eye will close during
         **        automatic eye blinks.  See set_automatic_blinks_enabled() and
         **    blink().
         **
         *b  Arguments:
         **
         *a    target_in - how far to close eye; 1.0 is all closed, 0.0 is
         *a                all open
         **
         *b  Available as Decision Bead/Event
         */
        void set_automatic_blink_target_in(float target_in);

        float get_automatic_blink_target_in();

        /*l
         *b  Description:
         **
         **    This function sets how much the eye will open during
         **        automatic eye blinks.  See set_automatic_blinks_enabled() and
         **    blink().
         **
         *b  Arguments:
         **
         *a    target_out - how far to open eye; 1.0 is all closed, 0.0 is
         *a                 all open
         **
         *b  Available as Decision Bead/Event
         */
        void set_automatic_blink_target_out(float target_out);

        float get_automatic_blink_target_out();

        /*l
         *b  Returns:
         **
         **    1 if the character is speaking, 0 if not. With a FaceFX character
         **    this is true if a character is actively playing a FaceFX animation
         */
        int is_speaking();

        /*l
         *b  Description:
         **
         **    FaceFX animations are referred to as a group/animation name.
         **    This function allows you to set the current group once.
         **    See diguyScenario::facefx_mount_animset() for how to load a new
         **    animset on an actor.
         */
        int set_current_facefx_animation_group(const char* anim_group);

        /*l
         *b  Returns:
         **
         **    the current FaceFX animation group set for this character
         */
        const char* get_current_facefx_animation_group();

        /*l
         *b  Returns:
         **
         **    the name of the FaceFX actor that goes with the current head
         **    appearance; returns NULL if there's no FaceFX actor
         */
        const char* get_facefx_actor();

        /*l
         *b  Description:
         **
         **    Mounts an animset on the current FaceFX actor.  See also
         **    diguyScenario::facefx_mount_animset()
         */
        int facefx_mount_animset(const char* file_name);

        /*l
         *b  Description:
         **
         **    Plays a FaceFX animation.  This is the main way a facial animation
         **    sequence is triggered. The animation can be named
         **    "group_name/animation" or just "animation" if the proper group has
         **    been set with set_current_facefx_animation_group().
         */
        int play_facefx_animation(const char* animation,
                float magnitude_scale = 1.0f,
                float duration_scale = 1.0f,
                float blendin_time = 0.1f,
                float blendout_time = 0.1f,
                int loop = 0);

        /*l
         *b  Description:
         **
         **    Stops all active FaceFX animations.
         */
        int stop_facefx_animations(float blend_time = 0.25f, int stop_sounds = 1);

        /*****************************************************************************/
        /*l
         *b  Returns:
         **
         **    the number of nodes in the FaceFX actor's face graph
         */
        int get_num_facefx_nodes();

        /*l
         *b  Returns:
         **
         **    the name of the node with index 'index' in the FaceFX actor's face
         **    graph
         */
        const char* get_facefx_node_name(int index);

        /*l
         *b  Returns:
         **
         **    the index of the node with name 'node_name'
         */
        int find_facefx_node_index(const char* node_name);

        /*l
         *b  Description:
         **
         **    Allows low level control of individual nodes of the characters face
         **    graph.  End users can use this function to get finer grained
         **    control over eye direction and emotional state.
         */
        int set_facefx_node_value(int node_index,
                float value,
                float blend_time = 0.25f);

        /*l
         *b  Description:
         **
         **   Retrieves the current final value of a node
         **/
        float get_facefx_node_value(int node_index);

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function creates (but does not begin) the specified gesture.
         **    Exact control over the gesture, such as number of repetitions,
         **    when the gesture should begin, when it should end, when it
         **    should reach specific points within the gestures, etc., is then
         **    possible by making calls through the returned
         **    diguyCharacterGesture object.
         **
         **    To begin execution of the gesture, call the begin_now() function
         **    of the diguyCharacterGesture object.
         **
         **    *Do not* call delete on the returned object.  It should be
         **    destroyed either by calling destroy_gesture(), or by calling
         **    set_automatic_destroy_flag(1) on the diguyCharacterGesture
         **    object.
         **
         *b  Arguments:
         **
         *a    gesture_name - name of the gesture of create
         **
         *b  Returns:
         **
         **    pointer to object of type diguyCharacterGesture
         */
        diguyCharacterGesture* create_gesture(const char* gesture_name);

        /*l
         *b  Description:
         **
         **    This function destroys a gesture object created by
         **    create_gesture().
         **
         *b  Arguments:
         **
         *a    gesture - gesture to destroy
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int destroy_gesture(diguyCharacterGesture* gesture);

        /*l
         *b  Description:
         **
         **    This function executes the specified gesture.
         **
         **    The gesture will automatically begin and end.  The only control
         **    over the executed gesture is whether is should be ended or aborted
         **    early.  See end_executing_gesture() and abort_executing_gesture().
         **    For full control of gesture attributes, use create_gesture()
         **    instead.
         **
         **    A gesture takes over control of a subset of a character's pose
         **    variables and can be overlaid on top of most base actions of the
         **    character.
         **
         **    Note that gestures should be preloaded at the beginning of a
         **    scenario to avoid a hitch in frame rate.  See the function
         **    diguyScenario::preload_gesture().
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    gesture_name     - name of the gesture of execute
         *a    reps             - how many times the gesture should be
         *a                       repeated; default is 1 if no duration
         *a                       is specified, or best fit if there is
         *a                       a duration specified
         *a    overall_duration - for how long the gesture should be executed;
         *a                       default is such that no time scaling occurs
         *a    channel_A_weight - the weight given to channel A of the
         *a                       gesture; ignored if the gesture does not
         *a                       have multiple channels
         **
         **    If the gesture is a multi-stage gesture, the overall duration
         **    will be spread proportionately over each stage.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int execute_gesture(const char* gesture_name,
                int reps = DIGUY_DEFAULT_INT,
                float overall_duration = DIGUY_DEFAULT_FLOAT,
                float channel_A_weight = DIGUY_DEFAULT_FLOAT);

        /*l
         *b  Description:
         **
         **    The gesture will automatically begin and end.  The only control
         **    over the executed gesture is whether is should be ended or aborted
         **    early.  See end_executing_gesture() and abort_executing_gesture().
         **    For full control of gesture attributes, use create_gesture()
         **    instead.
         **
         **    If the specified gesture is not a 1 stage gesture, no gesture
         **    is executed and an error value is returned.
         **
         **    The specified gesture can be a one or two channel 1 stage gesture,
         **    in which case the specified channel weight will be used over the
         **    course of the entire gesture.
         **
         **    A 1 stage gesture is a comprised of a single motion that begins
         **    and ends the gesture.
         **
         **    n repetitions of a 1 stage gesture will repeat the stage 1
         **    motion n times.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    gesture_name     - name of the gesture of execute
         *a    reps             - how many times the gesture should be
         *a                       repeated; default is 1 if no duration
         *a                       is specified, or best fit if there is
         *a                       a duration specified
         *a    stage1_duration  - how long stage 1 of the gesture should take;
         *a                       default is such that no time scaling occurs
         *a    channel_A_weight - the weight given to channel A of the
         *a                       gesture; ignored if the gesture does not
         *a                       have multiple channels
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int execute_1stage_gesture(const char* gesture_name,
                int reps = DIGUY_DEFAULT_INT,
                float stage1_duration = DIGUY_DEFAULT_FLOAT,
                float channel_A_weight = DIGUY_DEFAULT_FLOAT);

        /*l
         *b  Description:
         **
         **    This function is similar to execute_1stage_gesture().
         **
         **    Stage 1 of a 2 stage gesture is a motion that begins the gesture
         **    and leads to the "peak" of the gesture.
         **
         **    Stage 2 of a 2 stage gesture is the motion that returns the
         **    gesture from the "peak" to the starting position.
         **
         **    n repetitions of a 2 stage gesture will repeat the stage 1 motion
         **    followed by the stage 2 motion n times.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    gesture_name     - name of the gesture of execute
         *a    reps             - how many times the gesture should be
         *a                       repeated; default is 1 if no duration
         *a                       is specified, or best fit if there is
         *a                       a duration specified
         *a    stage1_duration  - how long stage 1 of the gesture should take,
         *a                       i.e., how far into the gesture the "peak"
         *a                       will occur;
         *a                       default is such that no time scaling occurs
         *a    stage2_duration  - how long stage 2 of the gesture should take;
         *a                       default is such that no time scaling occurs
         *a    channel_A_weight - the weight given to channel A of the
         *a                       gesture; ignored if the gesture does not
         *a                       have multiple channels
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int execute_2stage_gesture(const char* gesture_name,
                int reps = DIGUY_DEFAULT_INT,
                float stage1_duration = DIGUY_DEFAULT_FLOAT,
                float stage2_duration = DIGUY_DEFAULT_FLOAT,
                float channel_A_weight = DIGUY_DEFAULT_FLOAT);

        /*l
         *b  Description:
         **
         **    This function is similar to execute_1stage_gesture().
         **
         **    Stage 1 of a 3 stage gesture is a motion that begins the gesture
         **    and leads to stage 2; e.g., raising the right arm in preparation
         **    for waving.
         **
         **    Stage 2 of a 3 stage gesture is a motion that can loop
         **    indefinitely; e.g., waving the right arm back and forth.
         **
         **    Stage 3 of a 3 stage gesture is the motion that ends the gesture;
         **    e.g., returning the right arm to the side of the body to complete
         **    the wave.
         **
         **    n repetitions of a 3 stage gesture will play the stage 1 motion
         **    once, followed by n reps of the stage 2 motion, followed by 1
         **    stage 3 motion.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    gesture_name     - name of the gesture of execute
         *a    reps             - how many times the gesture should be
         *a                       repeated; default is 1 if no duration
         *a                       is specified, or best fit if there is
         *a                       a duration specified
         *a    stage1_duration  - how long stage 1 of the gesture should take;
         *a                       default is such that no time scaling occurs
         *a    stage2_duration  - how long each repetition of stage 2 of the
         *a                       gesture should take;
         *a                       default is such that no time scaling occurs
         *a    stage3_duration  - how long stage 3 of the gesture should take;
         *a                       default is such that no time scaling occurs
         *a    channel_A_weight - the weight given to channel A of the
         *a                       gesture; ignored if the gesture does not
         *a                       have multiple channels
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int execute_3stage_gesture(const char* gesture_name,
                int reps = DIGUY_DEFAULT_INT,
                float stage1_duration = DIGUY_DEFAULT_FLOAT,
                float stage2_duration = DIGUY_DEFAULT_FLOAT,
                float stage3_duration = DIGUY_DEFAULT_FLOAT,
                float channel_A_weight = DIGUY_DEFAULT_FLOAT);

        /*l
         *b  Description:
         **
         **    The gesture will automatically begin and end.  The only control
         **    over the executed gesture is whether is should be ended or aborted
         **    early.  See end_executing_gesture() and abort_executing_gesture().
         **    For full control of gesture attributes, use create_gesture()
         **    instead.
         **
         **    This function serves as a quick way of executing a table gesture.
         **    There are many capabilities of table gestures that are accessible
         **    only through the full diguyCharacterGesture object.
         **
         **    If the specified gesture is not a table gesture, no gesture is
         **    executed and an error value is returned.
         **
         **    A table stage gesture is a comprised of a table of gesture actions
         **    that can be transitioned between without going through a neutral
         **    position.
         **
         **    n repetitions of a table gesture will repeat the loop action
         **    n times.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    gesture_name - name of the gesture of execute
         *a    reps         - how many times the gesture should be repeated;
         *a                   default is 1
         *a    loop_action  - which action in the gesture should be looped;
         *a                   default is action at index 1 of table
         *a    begin_action - which action the gesture should begin from;
         *a                   default is action at index 0
         *a    end_action   - which action the gesture should end at;
         *a                   default is action at index 0
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int execute_table_gesture(const char* gesture_name,
                int reps = DIGUY_DEFAULT_INT,
                const char* loop_action = NULL,
                const char* begin_action = NULL,
                const char* end_action = NULL);

        /*l
         *b  Description:
         **   
         **   Documentation Pending
         **/
        int set_executing_table_gesture_desired_action(const char* gesture_name,
                const char* desired_action);

        /*l
         *b  Description:
         **
         **    This function alerts the specified gesture that it should end.
         **    The gesture will stop repeating and play its "out" motions as
         **    soon as possible.
         **
         **    In order to immediately stop the gesture, use the
         **    abort_executing_gesture() function.
         **
         *b  Arguments:
         **
         *a    gesture_name - name of executing gesture to end
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  See Also:
         **
         **    abort_executing_gesture()
         */
        int end_executing_gesture(const char* gesture_name);

        /*l
         *b  Description:
         **
         **    This function aborts a gesture previously executed by one of
         **    the execute_*_gesture() calls, if it is currently executing.
         **    If a gesture with the given name is not executing, this function
         **    will have no effect.
         **
         **    This call won't cause the gesture to switch to its "out" motion;
         **    it is a straight-forward blend out of whatever the gesture is
         **    currently doing.  Use the end_executing_gesture() call to make
         **    the gesture play its "out" motion as soon as possible,
         **    therefore ending the gesture in a smoother way.
         **
         *b  Arguments:
         **
         *a    gesture_name          - name of executing gesture to abort
         *a    max_rampdown_interval - max amount of time spent trying to
         *a                            smooth over any motion seams; set
         *a                            to 0.5 for a smooth transition, set
         *a                            to 0 for an immediate abort
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  See Also:
         **
         **    end_executing_gesture(), abort_all_gestures()
         */
        int abort_executing_gesture(const char* gesture_name,
                float max_rampdown_interval);

        /*l
         *b  Description:
         **
         **    This function alerts all active gestures that they should end.
         **    The gestures will stop repeating and play their "out" motions as
         **    soon as possible.
         **
         **    In order to immediately stop all gestures, use the
         **    abort_all_gestures() function.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  See Also:
         **
         **    abort_all_gestures(), diguyCharacterGesture::end_gesture()
         */
        int end_all_gestures();

        /*l
         *b  Description:
         **
         **    This function aborts all active gestures.  All gestures will
         **    immediately begin to lose their effect on the
         **    character's pose.
         **
         **    This won't cause the gestures to switch to their "out" motions;
         **    it is a straight-forward blend out of whatever the gesture is
         **    currently doing.  Use the end_all_gestures() call to make all
         **    active gestures play their "out" motions as soon as possible,
         **    therefore ending the gestures in a smoother way.
         **
         *b  Arguments:
         **
         *a    max_rampdown_interval - max amount of time spent trying to
         *a                            smooth over any motion seams; set
         *a                            to 0.5 for a smooth transition, set
         *a                            to 0 for an immediate abort
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  See Also:
         **
         **    end_all_gestures(), diguyCharacterGesture::abort_now()
         */
        int abort_all_gestures(float max_rampdown_interval);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function will play the specified sound.  The sound will be
         **    "ambient"; i.e., it will be equally audible from everywhere within
         **    the world.  Use the function play_3d_sound() to play a sound that
         **    moves with the character.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         **    Unless the sound loops, the sound will play to completion and then
         **    stop.  To stop the sound early or stop a looping sound call
         **    diguyCharacter::stop_all_sounds() or diguyCharacter::stop_sound().
         **
         *b  Arguments
         **
         *a    sound_name - name of sound to play
         *a    sound_gain - by how much sound's amplitude should be multiplied
         *a    sound_loop - indicates that sound should loop indefinitely
         **
         **    There must be a diguySound in the scenario with the passed
         **    sound_name.  See diguyScenario::create_sound().
         **
         **    See set_current_voice_actor() for information on how a voice actor
         **    can change which sound in the scenario is selected.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int play_sound(const char* sound_name,
                float sound_gain = 1.0f,
                int sound_loops = 0);

        /*l
         *b  Description:
         **
         **    This function will play the specified sound at the character's
         **    location.  As the character moves, the sound will move with it.
         **    Use the function play_sound() to play a sound that is ambient and
         **    does not move with the character.
         **
         **    Note that not all sound modules support 3D sounds.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         **    Unless the sound loops, the sound will play to completion and then
         **    stop.  To stop the sound early or stop a looping sound call
         **    diguyCharacter::stop_all_sounds() or diguyCharacter::stop_sound().
         **
         *b  Arguments
         **
         *a    sound_name       - the name of the sound to play
         *a    sound_gain       - by how much the sound's amplitude
         *a                       should be multiplied
         *a    sound_loop       - indicates that the sound should loop
         *a                       indefinitely
         **
         **    There must be a diguySound in the scenario with the passed
         **    sound_name.  See diguyScenario::create_sound().
         **
         **    See set_current_voice_actor() for information on how a voice actor
         **    can change which sound in the scenario is selected.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int play_3d_sound(const char* sound_name,
                float sound_gain = 1.0f,
                int sound_loops = 0);

        /*l
         *b  Description:
         **
         **    This function creates (but does not start playing) an instance of
         **    the specified sound.
         **
         **    Exact control over the sound instance is possible by making calls
         **    through the returned diguySoundInstance object.
         **
         **    To begin playing the sound, call diguySoundInstance::begin_now().
         **
         **    *Do not* call delete on the returned object.  It should be
         **    destroyed either by calling diguyCharacter::destroy_sound_instance()
         **    or by calling diguySoundInstance::set_automatic_destroy_flag(1) on
         **    the returned object.
         **
         *b  Arguments:
         **
         *a    sound_name - name of the sound for which to create an instance
         **
         **    There must be a diguySound in the scenario with the passed
         **    sound_name.  See diguyScenario::create_sound().
         **
         *b  Returns:
         **
         **    pointer to object of type diguySoundInstance
         */
        diguySoundInstance* create_sound_instance(const char* sound_name);

        /*l
         *b  Description:
         **
         **    This function destroys a sound instance object created by
         **    create_sound_instance().
         **
         **    Do not destroy a sound for which the
         **    diguySoundInstance::set_automatic_destroy_flag(1) has been called.
         **
         *b  Arguments:
         **
         *a    sound_instance - sound instance to destroy
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int destroy_sound_instance(diguySoundInstance* sound_instance);

        /*l
         *b  Description:
         **
         **    This function stops all active sound instances from this character.
         **    All sounds being played by this character will fade out and stop
         **    after rampdown_time, by default fade out is instant.
         **
         **    Sound instances that are automatically managed will be destroyed.
         **    This includes sound started by a call to
         **    diguyCharacter::play_sound() or a sound instance whose
         **    set_automatic_destroy_flag() function has been called.
         **
         **    diguySoundInstance pointers returned by a call to
         **    diguyCharacter::create_sound_instance(), which have not been set to
         **    be automatically destroyed, will still be valid.
         **
         *b  Arguments:
         **
         *a    rampdown_time - how long to fade out the sound
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int stop_all_sounds(float rampdown_time = 0.0f);

        /*l
         *b  Description:
         **
         **    This function stops a named sound instance from this character.
         **
         **    Sound instances that are automatically managed will be destroyed.
         **    This includes sound started by a call to
         **    diguyCharacter::play_sound() or a sound instance whose
         **    set_automatic_destroy_flag() function has been called.
         **
         **    diguySoundInstance pointers returned by a call to
         **    diguyCharacter::create_sound_instance(), which have not been set to
         **    be automatically destroyed, will still be valid.
         **
         *b  Arguments:
         **
         *a    sound_name    - the name of the sound to stop
         *a    rampdown_time - how long to fade out the sound
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int stop_sound(const char* sound_name, float rampdown_time = 0.0f);

        /*l
         *b  Returns:
         **
         **    1 if the character is playing a the sound specified, 0 if not
         */
        int is_playing_sound(const char* sound_name);

        /*l
         *b  Description:
         **
         **    Sets the "voice actor" for the character.
         **
         **    Having a voice actor can change which sounds from the scenario a
         **    character selects when the diguyCharacter::play_sound() or
         **    diguyCharacter::play_3d_sound().
         **
         **    When play_sound() is called the character asks the scenario for
         **    the sound with the specified name.  If a voice actor has been set
         **    the character will first ask the scenario for the sound name
         **    prepended with the voice actor and a slash ("/").  If there isn't
         **    a sound with that modified name, it will ask the scenario for a
         **    sound with the exact specified name.
         **
         **    For example, if the character has the voice actor "carl" and is
         **    told to play the sound "run_away", the character will first look
         **    for a sound named "carl/run_away".  If that isn't found, it will
         **    look for a sound named "run_away".  (If that isn't found no sound
         **    is played.)
         **
         *b    Lua Example:
         **
         **    A more specific example: say that various characters in the
         **    scenario need to say "hello".  Some of the characters are male,
         **    some are female.  There are two ways this can be set up.
         **
         **    The first way, not using a voice actor, is to have two sounds
         **    specified in the scenario: "male_hello" and "female_hello".  These
         **    sounds specify the sound files "male_hello.wav" and
         **    "female_hello.wav", respectively.  A male character would then do
         **    the following to say hello:
         **
         *e        male_character:play_sound("male_hello")
         **
         **    A female character would do:
         **
         *e        female_character:play_sound("female_hello")
         **
         **    This is fine, except when one script or character mind needs to be
         **    shared by a range of characters, some male and some female.
         **
         **    In this case it's better to use a voice actor.  Say that the sounds
         **    specified above have the names "male/hello" and "female/hello";
         **    they still have the separate sound files specified.  If the
         **    character has its voice actor specified as "male" and is told to
         **    play the sound "hello", it will select the sound "male/hello" as
         **    the sound to play.  If its voice actor is "female" and is told to
         **    play the sound "hello", it will select the sound "female/hello".
         **
         *e        -- called earlier: character:set_voice_actor("male")
         *e        character:play_sound("hello")  -- plays sound "male/hello"
         **
         *e        -- called earlier: character:set_voice_actor("female")
         *e        character:play_sound("hello")  -- plays sound "female/hello"
         **
         *b  Arguments:
         **
         *a    voice_actor - name of voice actor
         **
         **    voice_actor can be an arbitrary string.  It doesn't need to match
         **    any character name, but should have matching sounds specified in
         **    the scenario.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_current_voice_actor(const char* voice_actor);

        const char* get_current_voice_actor();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function returns the state of the character in the form
         **    required by DIS.
         **
         **    Note that there is no corresponding set_DIS_lifeform_state()
         **    function.  The lifeform state is derived from the character's
         **    action, posture, and variant information.
         **
         *b  Returns:
         **
         **    one of the following values defined in diguy_dis_constants.h:
         **
         *-        DIGUY_DIS_LIFEFORM_UNUSED                 (0)
         *-        DIGUY_DIS_LIFEFORM_UPRIGHT_STANDING_STILL (1)
         *-        DIGUY_DIS_LIFEFORM_UPRIGHT_WALKING        (2)
         *-        DIGUY_DIS_LIFEFORM_UPRIGHT_RUNNING        (3)
         *-        DIGUY_DIS_LIFEFORM_KNEELING               (4)
         *-        DIGUY_DIS_LIFEFORM_PRONE                  (5)
         *-        DIGUY_DIS_LIFEFORM_CRAWLING               (6)
         *-        DIGUY_DIS_LIFEFORM_SWIMMING               (7)
         *-        DIGUY_DIS_LIFEFORM_PARACHUTING            (8)
         *-        DIGUY_DIS_LIFEFORM_JUMPING                (9)
         *-        DIGUY_DIS_LIFEFORM_SITTING                (10)
         *-        DIGUY_DIS_LIFEFORM_SQUATTING              (11)
         *-        DIGUY_DIS_LIFEFORM_CROUCHING              (12)
         *-        DIGUY_DIS_LIFEFORM_WADING                 (13)
         **
         *b  Callable For Networked Entities That Are:
         **
         *-    - DIS published and reflected
         */
        int get_DIS_lifeform_state();

        /*l
         *b  Description:
         **
         **    This function returns the position of the character's
         **    primary weapon, in the form required by DIS.
         **
         *b  Returns:
         **
         **    one of the following values defined in diguy_dis_constants.h:
         **
         *-        DIGUY_DIS_PRIMARY_WEAPON_NOT_PRESENT        (0)
         *-        DIGUY_DIS_PRIMARY_WEAPON_STOWED             (1)
         *-        DIGUY_DIS_PRIMARY_WEAPON_DEPLOYED           (2)
         *-        DIGUY_DIS_PRIMARY_WEAPON_IN_FIRING_POSITION (3)
         **
         *b  Callable For Networked Entities That Are:
         **
         *-    - DIS published
         */
        int get_DIS_primary_weapon_position();

        /*l
         *b  Description:
         **
         **    This function returns the position of the character's
         **    secondary weapon, in the form required by DIS.
         **
         *b  Returns:
         **
         **    one of the following values defined in diguy_dis_constants.h:
         **
         *-        DIGUY_DIS_SECONDARY_WEAPON_NOT_PRESENT        (0)
         *-        DIGUY_DIS_SECONDARY_WEAPON_STOWED             (1)
         *-        DIGUY_DIS_SECONDARY_WEAPON_DEPLOYED           (2)
         *-        DIGUY_DIS_SECONDARY_WEAPON_IN_FIRING_POSITION (3)
         **
         *b  Callable For Networked Entities That Are:
         **
         *-    - DIS published
         */
        int get_DIS_secondary_weapon_position();

        /*l
         *b  Description:
         **
         **    This function sets the Marking Text for characters that are
         **    published to the network by DI-Guy Networking.  The default
         **    network marking is the empty string "".
         **
         **    This function should only be called for published characters.
         **    The Marking Text is set internally for reflected characters.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Networked Entities That Are:
         **
         *-    - DIS published
         *-    - HLA published
         */
        int set_network_marking(const char* network_marking);

        /*l
         *b  Description:
         **
         **    This function gets the Marking Text for characters.
         **
         **    For published characters this value will be what was most
         **    recently set by set_network_marking().
         **
         **    For reflected characters this value will be read from the
         **    reflected characters' entity state information.
         **
         *b  Returns:
         **
         **    character's Marking Text; will never be NULL
         **
         *b  Callable For Networked Entities That Are:
         **
         *-    - DIS published and reflected
         *-    - HLA published and reflected
         */
        const char* get_network_marking();

        /*l
         *b  Description:
         **
         **    This function sets whether this character will be published
         **    by DI-Guy Networking.  This value is persistent, and does
         **    not depend on whether there actually *is* currently a
         **    network connection.
         **
         **    The default is 1, the character is published.
         **
         **    This function should *not* be called for reflected characters.
         **    It affects to both DIS and HLA networking.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Networked Entities That Are:
         **
         *-    - DIS published
         *-    - HLA published
         */
        int set_is_network_published(int is_network_published);

        /*l
         *b  Description:
         **
         **    This function returns whether the character is published
         **    by DI-Guy Networking.  It will always return 0 for reflected
         **    characters.
         **
         **    This function can be called for any character.
         **
         *b  Returns:
         **
         **    1 if published, 0 if not
         **
         *b  Available as Decision Bead/Event
         **
         *b  Callable For Networked Entities That Are:
         **
         *-    - DIS published and reflected
         *-    - HLA published and reflected
         */
        int get_is_network_published();

        /*l
         *b  Description:
         **
         **   Experimental function that returns a vrlink entity state repository, 
         **   useful for adding additional information to a diguy that we don't usually
         **   model.
         */
        DtEntityStateRepository * get_vrlink_entity_state_repository();

        /*l
         *b  Description:
         **
         **    This function returns whether the character is a
         **    reflected character created by DI-Guy Networking.
         **
         **    This function can be called for any character.
         **
         *b  Returns:
         **
         **    1 if reflected, 0 if not
         **
         *b  Available as Decision Bead/Event
         **
         *b  Callable For Networked Entities That Are:
         **
         *-    - DIS published and reflected
         *-    - HLA published and reflected
         */
        int get_is_network_reflected();

        /*l
         *b  Description:
         **
         **    This function returns whether this character is in a
         **    "paused" state.  This will only be true for reflected
         **    characters.
         **
         **    A reflected character will be paused if the network
         **    entity it is representing is paused; i.e., its personal
         **    timeline is not advancing.  The most common case of this
         **    is when this character is reflecting a published character
         **    of a DI-Guy Scenario application that is in a paused or
         **    stopped state.
         **
         **    If DI-Guy Scenario, paused characters will remain frozen
         **    in their current postures.
         **
         *b  Returns:
         **
         **    1 if paused, 0 if not
         **
         *b  Available as Decision Bead/Event
         */
        int get_is_network_paused();

        /*l
         *b  Description:
         **
         **   Overrides built-in logic for network pausing, becomes end user's responsibility 
         **   to manage
         */
        int set_is_network_paused(int paused);

        /*l
         *b  Description:
         **
         **    This function returns the character's "network entity number".
         **    This number is valid and persistent regardless of whether the
         **    character is currently published.
         **
         **    This number is primarily used internally by DI-Guy Networking
         **    for creating entity IDs.
         **
         *b  Returns:
         **
         **    character's network entity number
         **
         *b  Callable For Networked Entities That Are:
         **
         *-    - DIS published and reflected
         *-    - HLA published and reflected
         */
        int get_network_entity_number();

        /*l
         *b  Description:
         **
         **    This function returns the name of an action for a character,
         **    given the DIS damage state, lifeform state, primary weapon
         **    state, speed of the character, and direction of travel.
         **    Constants are all defined in diguy_dis_constants.h:
         **
         *b  Arguments:
         **
         *a    damage_state         - one of the values listed below
         *a    life_form_state      - one of the values listed below
         *a    primary_weapon_state - one of the values listed below
         *a    speed                - in meters/second
         *a    forward              - whether the action should move
         *a                           forward (pass 1), or backward (pass 0)
         **
         **    Valid values for damage_state:
         **
         *-      - DIGUY_DIS_DAMAGE_NONE      (0)
         *-      - DIGUY_DIS_DAMAGE_SLIGHT    (1)
         *-      - DIGUY_DIS_DAMAGE_MODERATE  (2)
         *-      - DIGUY_DIS_DAMAGE_DESTROYED (3)
         **
         **    Valid values for life_form_state:
         **
         *-      - DIGUY_DIS_LIFEFORM_UNUSED                 (0)
         *-      - DIGUY_DIS_LIFEFORM_UPRIGHT_STANDING_STILL (1)
         *-      - DIGUY_DIS_LIFEFORM_UPRIGHT_WALKING        (2)
         *-      - DIGUY_DIS_LIFEFORM_UPRIGHT_RUNNING        (3)
         *-      - DIGUY_DIS_LIFEFORM_KNEELING               (4)
         *-      - DIGUY_DIS_LIFEFORM_PRONE                  (5)
         *-      - DIGUY_DIS_LIFEFORM_CRAWLING               (6)
         *-      - DIGUY_DIS_LIFEFORM_SWIMMING               (7)
         *-      - DIGUY_DIS_LIFEFORM_PARACHUTING            (8)
         *-      - DIGUY_DIS_LIFEFORM_JUMPING                (9)
         *-      - DIGUY_DIS_LIFEFORM_SITTING                (10)
         *-      - DIGUY_DIS_LIFEFORM_SQUATTING              (11)
         *-      - DIGUY_DIS_LIFEFORM_CROUCHING              (12)
         *-      - DIGUY_DIS_LIFEFORM_WADING                 (13)
         **
         **    Valid values for primary_weapon_state:
         **
         *-      - DIGUY_DIS_PRIMARY_WEAPON_NOT_PRESENT        (0)
         *-      - DIGUY_DIS_PRIMARY_WEAPON_STOWED             (1)
         *-      - DIGUY_DIS_PRIMARY_WEAPON_DEPLOYED           (2)
         *-      - DIGUY_DIS_PRIMARY_WEAPON_IN_FIRING_POSITION (3)
         **
         **    Note that a backward motion can be requested in a couple of
         **    ways: either by passing a negative speed, or by passing
         **    0 for the forward argument, or both.
         **
         *b  Returns:
         **
         **    name of an action if a match is found, NULL if not
         **
         *b  Callable For Networked Entities That Are:
         **
         *-    - DIS published
         */
        const char* get_action_from_entity_state(int damage_state,
                int life_form_state,
                int primary_weapon_state,
                float speed,
                int forward);

        /*l
         *b  Description:
         **
         **    Sets the damage state for the network published character.
         **    Depending on the appearance configuration info the character may automatically switch to a new appearance.
         **
         *b  Arguments:
         **
         *a    state         - one of the values listed below
         **
         **    Valid values for state (defined in diguy_dis_constants.h):
         **
         *-      - DIGUY_DIS_DAMAGE_NONE      (0)
         *-      - DIGUY_DIS_DAMAGE_SLIGHT    (1)
         *-      - DIGUY_DIS_DAMAGE_MODERATE  (2)
         *-      - DIGUY_DIS_DAMAGE_DESTROYED (3)
         **
         *b  Callable For Networked Entities That Are:
         **
         *-    - DIS published
         */
        void set_DIS_damage_state(int state);

        /*l
         *b  Description:
         **
         **    Returns the damage state of a network published character.
         **
         *b  Returns:
         **
         *a    one of the values shown in set_DIS_damage_state()
         */
        int get_DIS_damage_state();

        /*l
         *b  Description:
         **
         **    Returns the name of damage state appearances based on the base appearance of the character.
         **    NULL if the state isn't available.
         */
        const char * get_damage_state_appearance_name(int state);

        /*l
         *b  Description:
         **
         **    Sets the smoke state for a network published character.
         **    Starts or stops the "smoke" and "engine_smoke" appearance
         **    effects as appropriate.
         **
         *b  Arguments:
         **
         *a    state  - one of the values listed below
         **
         **    Valid values for state (defined in diguy_dis_constants.h):
         **
         *-      - DIGUY_DIS_SMOKE_NOT_SMOKING                   (0)
         *-      - DIGUY_DIS_SMOKE_SMOKE_PLUME                   (1)
         *-      - DIGUY_DIS_SMOKE_ENGINE_SMOKE                  (2)
         *-      - DIGUY_DIS_SMOKE_ENGINE_SMOKE_AND_SMOKE_PLUME  (3)
         **
         *b  Callable For Networked Entities That Are:
         **
         *-    - DIS published
         */
        void set_DIS_smoke_state(int state);

        /*l
         *b  Description:
         **
         **    Returns the smoke state of a network published character.
         **
         *b  Returns:
         **
         *a    one of the values shown in set_DIS_smoke_state()
         */
        int get_DIS_smoke_state();

        /*l
         *b  Description:
         **
         **    Sets the flames state for a network published character.
         **    Starts or stops the "flames" appearance effect as appropriate.
         **
         *b  Arguments:
         **
         **    state - one of the values listed below
         **
         **    Valid values for state (defined in diguy_dis_constants.h):
         **
         *-      - DIGUY_DIS_FLAMES_NONE                   (0)
         *-      - DIGUY_DIS_FLAMES_PRESENT                (1)
         **
         *b  Callable For Networked Entities That Are:
         **
         *-    - DIS published
         */
        void set_DIS_flames_state(int state);

        /*l
         *b  Description:
         **
         **    Returns the flames state of a network published character.
         **
         *b  Returns:
         **
         *a    one of the values shown in set_DIS_flames_state()
         */
        int get_DIS_flames_state();

        /*l
         *b  Description:
         **
         **    Sets the power plant state for a network published character.
         **    Vehicle power plants default to being on.
         **
         *b  Arguments:
         **
         **    state - one of the values listed below
         **
         **    Valid values for state (defined in diguy_dis_constants.h):
         **
         *-      - DIGUY_DIS_POWER_PLANT_OFF              (0)
         *-      - DIGUY_DIS_POWER_PLANT_ON               (1)
         **
         *b  Callable For Networked Entities That Are:
         **
         *-    - DIS published
         */
        void set_DIS_power_plant_state(int state);

        /*l
         *b  Description:
         **
         **    Returns the power plant state of a network published character.
         **
         *b  Returns:
         **
         *a    one of the values shown in set_DIS_power_plant_state()
         */
        int get_DIS_power_plant_state();

        void set_emissivity(float r, float g, float b, float lerp_time = .25);

        void get_emissivity(float *r, float *g, float *b);

        /*l
         *b  Description:
         **
         **    Sets the trailing effect state for a network published character.
         **
         *b  Arguments:
         **
         **    state - one of the values listed below
         **
         **    Valid values for state (defined in diguy_dis_constants.h):
         **
         *-      - DIGUY_DIS_TRAILING_EFFECT_NONE    (0)
         *-      - DIGUY_DIS_TRAILING_EFFECT_SMALL   (1)
         *-      - DIGUY_DIS_TRAILING_EFFECT_MEDIUM  (2)
         *-      - DIGUY_DIS_TRAILING_EFFECT_LARGE   (3)
         **
         *b  Callable For Networked Entities That Are:
         **
         *-    - DIS published
         */
        void set_DIS_trailing_effect_state(int state);

        /*l
         *b  Description:
         **
         **    Returns the trailing effect state of a network published
         **    character.
         **
         *b  Returns:
         **
         *a    one of the values shown in set_DIS_smoke_trail_state()
         */
        int get_DIS_trailing_effect_state();

        void set_head_lights_state(int state);

        int  get_head_lights_state() const;

        void set_tail_lights_state(int state);

        int  get_tail_lights_state() const;

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function will create a new active formation with this
         **    character as its leader.  The formation followers will fall
         **    into the formation given by the formation name.
         **
         **    The formation is broken up, or disbanded, by calling
         **    break_formation().
         **
         *b  Arguments:
         **
         *a    formation_name        - the name of the formation
         *a    snap_to_position_flag - if 1, following characters will
         *a                            immediately snap to their assigned
         *a                            positions; otherwise following characters
         *a                            will move toward their assigned
         *a                            positions from their current positions
         *a    break_existing_formations_flag - if 1, any formations this
         *a                            character is leading with be broken
         *a                            as if the break_formation() call were
         *a                            made
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int call_formation(const char* formation_name,
                int snap_to_position_flag = 0,
                int break_existing_formations_flag = 1);

        /*l
         *b  Description:
         **
         **    This function breaks up a formation initiated by call_formation().
         **
         *b  Arguments:
         **
         *a    formation_name - the name of the formation to break;
         *a                     passing NULL or "(all)" will break all formations
         *a                     this character is leading
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int break_formation(const char* formation_name = NULL);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function adds a copy of the specified scenario guide
         **    to the character.  Any changes that are subsequently made
         **    to the added guide -- for example by a call to
         **    diguyCharacterGuide::set_algorithm_float_parameter() -- are
         **    private to this copy of the guide and will not affect others.
         **
         **    The guide will be enabled by default.  Guides can be disabled
         **    by calling diguyCharacterGuide::set_guide_enabled(0), or by
         **    passing 1 for the argument automatically_disable_when_acquired.
         **
         **    Note that disabling a guide is not the same as removing it.
         **    Disabled guides are still a part of the character and can
         **    later be re-enabled by calling diguyCharacterGuide::set_enabled().
         **
         *b  Arguments:
         **
         *a    guide_name        - name of guide to find and copy
         *a    automatically_disable_when_acquired - set to 1 to have the guide
         *a                        be automatically disabled when it has acquired
         *a                        its target
         **
         *b  Returns:
         **
         **    object of type diguyCharacterGuide; if a guide with guide_name
         **    is not found, returns NULL
         */
        diguyCharacterGuide* add_guide(const char* guide_name,
                int automatically_disable_when_acquired = 0);

        /*l
         *b  Description:
         **
         **    This function creates a new guide and adds it to the character.
         **
         **    The guide will be enabled by default.  Guides can be disabled
         **    by calling diguyCharacterGuide::set_guide_enabled(), or by
         **    passing 1 for the argument automatically_disable_when_acquired.
         **
         **    Important note: a new guide will always be created, even if one with
         **    the same name already exists
         **
         *b  Arguments:
         **
         *a    guide_name              - name of guide to find and copy
         *a    guide_algorithm         - name of guide algorithm to be used
         *a    automatically_disable_when_acquired - set to 1 to have the guide
         *a                              be automatically disabled when it has
         *a                              acquired its target
         **
         *b  Returns:
         **
         **    object of type diguyCharacterGuide; if a guide with guide_name
         **    is not found, returns NULL
         */
        diguyCharacterGuide* create_guide(const char* guide_name,
                const char* guide_algorithm,
                int automatically_disable_when_acquired = 0);

        /*l
         *b  Description:
         **
         **    Like create_guide(), but returns guide if it already exists
         **
         *b  Arguments:
         **
         *a    guide_name              - name of guide to find and copy
         *a    guide_algorithm         - name of guide algorithm to be used
         *a    automatically_disable_when_acquired - set to 1 to have the guide
         *a                              be automatically disabled when it has
         *a                              acquired its target
         **
         *b  Returns:
         **
         **    object of type diguyCharacterGuide; if a guide with guide_name
         **    is not found, returns NULL
         */
        diguyCharacterGuide* find_or_create_guide(const char* guide_name,
                const char* guide_algorithm,
                int automatically_disable_when_acquired = 0);

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the specified guide
         **    of the character, if is exists.
         **
         *b  Arguments:
         **
         *a    guide_name              - name of guide to find
         **
         *b  Returns:
         **
         **    object of type diguyCharacterGuide; if a guide with guide_name
         **    is not found, returns NULL
         */
        diguyCharacterGuide* find_guide(const char* guide_name);

        /*l
         *b  Description:
         **
         **    This function removes the specified guide from the
         **    character.
         **
         *b  Arguments:
         **
         *a    guide_name - name of the guide to remove; must match name
         *a                 used by add_guide() or create_guide() call
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_guide_with_name(const char* guide_name);

        /*l
         *b  Description:
         **
         **    This function removes the specified guide from the
         **    character.
         **
         *b  Arguments:
         **
         *a    guide - object returned by add_guide() call
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_guide(diguyCharacterGuide* guide);

        /*l
         *b  Description:
         **
         **    This function removes all guides from the character.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_all_guides();

        /*l
         *b  Description:
         **
         **    This function removes all guides that are disabled.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_all_disabled_guides();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function adds a "motion texture" to the character.  A
         **    motion texture is a relatively long (usually 10 seconds or
         **    more) loop that will add natural-looking, low amplitude
         **    joint angle adjustments.
         **
         **    This function will have no effect on a dead character (see
         **    die_now() and get_dead()).
         **
         *b  Arguments:
         **
         *a    motex_name         - name of the motion texture to add; see below
         *a    texture_gain       - the relative amplitude of the motion texture;
         *a                         higher numbers result in more pronounced
         *a                         movements
         *a    end_previous_motex - flag denoting whether this motion texture
         *a                         replaces all previously added motion
         *a                         textures; pass 1 to end existing textures
         *a    rampup_interval    - how long, in seconds, to take ramping up
         *a                         into the motion texture
         **
         **    List of currently available motion textures:
         **
         *-    - "default"
         *-    - "motex_stand_casual"
         **
         **    If 1 is passed for the argument end_previous_motex, the
         **    rampup_interval argument will be used as the interval for
         **    ending existing motion textures.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         */
        int add_motion_texture(const char* motex_name = "default",
                float texture_gain = 1.0f,
                int end_previous_motex = 1,
                float rampup_interval = 0.2f);

        /*l
         *b  Description:
         **
         **    This function gradually ends any active motion textures added by
         **    add_motion_texture().
         **
         *b  Arguments:
         **
         *a    rampdown_interval - how long, in seconds, to take ending the
         *a                        motion texture
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int end_motion_texture(float rampdown_interval = 0.2f);

        /*l
         *b  Description:
         **
         **    This function sets an initial motion texture that should be
         **    used by the character whenever the character is loaded from
         **    a scenario or the character's scenario is reset.
         **
         **    The gain of the motion texture can be set by calling
         **    set_initial_motion_texture_gain().  The initial motion
         **    texture gain is 1.0 by default.
         **
         *b  See Also:
         **
         **    add_motion_texture(), set_initial_motion_texture_gain()
         **
         *b  Arguments:
         **
         *a    motex_name - name of the motion texture
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_initial_motion_texture(const char* motex_name);

        /*l
         *b  Description:
         **
         **    This function returns the initial motion texture as set
         **    by a call to set_initial_motion_texture().
         **
         *b  Returns:
         **
         **    name of initial motion texture
         */
        const char* get_initial_motion_texture();

        /*l
         *b  Description:
         **
         **    This function sets the gain of the initial motion texture
         **    of the character.  The initial motion texture can be set
         **    by calling set_initial_motion_texture().
         **
         *b  Arguments:
         **
         *a    motex_gain - gain of the motion texture; higher gains
         *a                 result in more pronounced motion
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_initial_motion_texture_gain(float motex_gain);

        /*l
         *b  Description:
         **
         **    This function returns the initial motion texture gain as set
         **    by a call to set_initial_motion_texture_gain().
         **
         *b  Returns:
         **
         **    gain of initial motion texture
         */
        float get_initial_motion_texture_gain();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets what type of "history" will be kept for the
         **    character.
         **
         **    If time is run backwards in a scenario, characters
         **    with history will replay the motions they performed at that
         **    time.  Characters without history will stay frozen in place
         **    until time advances past the point from which it was run
         **    backwards.
         **
         **    The default is DIGUY_HISTORY_TYPE_NONE for characters created
         **    using the diguyScenario::create_character() function.
         **    Characters loaded from a .dss file will retain their history
         **    settings from the DI-Guy Scenario editing session.
         **
         *b  Arguments:
         **
         *a    history_type - history type to be used for the character
         **
         **    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 all of a character's history.
         **
         **      The initial amount of history to be saved, before memory buffers
         **      need to be resized, can be set by the function
         **      set_history_size_t().  The size by which memory buffers grow each
         **      time they do need to get resized by be set by
         **      set_history_size_increment_t().
         **
         *i    DIGUY_HISTORY_TYPE_FIRST
         **
         **      This history type is no longer supported.  Characters from
         **      a .dss that have this history type will have their history
         **      type set to DIGUY_HISTORY_TYPE_COMPLETE.
         **
         *i    DIGUY_HISTORY_TYPE_LAST
         **
         **      This history type is no longer supported.  Characters from
         **      a .dss that have this history type will have their history
         **      type set to DIGUY_HISTORY_TYPE_COMPLETE.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_history_type(diguyHistoryType history_type);

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

        /*l
         *b  Description:
         **
         **    This function sets the size of the character's history
         **    buffer, in seconds.
         **
         *b  Arguments:
         **
         *a    t - length of history buffer, in seconds
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_history_size_t(float t);

        /*l
         *b  Description:
         **
         **    This function returns the current history buffer size.
         **    See set_history_size_t().
         **
         *b  Returns:
         **
         **    current history size
         */
        float get_history_size_t();

        /*l
         *b  Description:
         **
         **    This function sets the size of the character's history
         **    buffer increment, in seconds.
         **
         *b  Arguments:
         **
         *a    t - length of history buffer increment, in seconds
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_history_size_increment_t(float t);

        /*l
         *b  Description:
         **
         **    This function returns the current history buffer size increment.
         **    See set_history_size_increment_t().
         **
         *b  Returns:
         **
         **    current history size increment
         */
        float get_history_size_increment_t();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets the desired posture of the character.  This,
         **    along with the desired variant, is used primarily by some guides.
         **    Specifically, to help choose which actions are used to reach the
         **    desired position and orientation of the character.
         **
         **    Pass DIGUY_MOTION_POSTURE_ANY for there to be no desired posture.
         **
         *b  Arguments:
         **
         *a    posture - new desired posture
         */
        void set_desired_posture(diguyMotionPosture desired_posture);

        /*l
         *b  Returns:
         **
         **    current desired posture of the character
         */
        diguyMotionPosture get_desired_posture();

        /*l
         *b  Description:
         **
         **    This function sets the desired variant of the character.  This,
         **    along with the desired posture, is used primarily by some guides.
         **    Specifically, to help choose which actions are used to reach the
         **    desired position and orientation of the character.
         **
         **    Pass DIGUY_MOTION_VARIANT_ANY for there to be no desired variant.
         **
         *b  Arguments:
         **
         *a    variant - new desired variant
         */
        void set_desired_variant(diguyMotionVariant desired_variant);

        diguyMotionVariant get_desired_variant();

        /*l
         *b  Description:
         **
         **    This function looks up the character action that most closely
         **    matches the given criteria.
         **
         *b  Arguments:
         **
         *a    direction            - the direction of travel relative to
         *a                           the character's facing direction
         *a    posture              - overall desired posture; pass
         *a                           DIGUY_MOTION_POSTURE_ANY
         *a                           to specify that any posture will do
         *a    variant              - overall desired variant; pass
         *a                           DIGUY_MOTION_VARIANT_ANY
         *a                           to specify that any variant will do
         *a    speed                - speed in meters per second
         *a    comparison           - how the passed speed should compare
         *a                           to the action's speed
         *a    comparison_tolerance - tolerance of comparison
         *a    match_posture_before_variant - pass 1 if posture should be matched
         *a                                   before variant if an exact match is
         *a                                   not found; pass 0 if variant should
         *a                                   be matched before posture
         *a    posture_alternate1   - if an exact match is not found, use this
         *a                           as the first alternate posture; pass
         *a                           DIGUY_MOTION_POSTURE_UNKNOWN
         *a                           to specify that no alternate should be used
         *a    posture_alternate2   - if an exact match is not found, use this
         *a                           as the second alternate posture; pass
         *a                           DIGUY_MOTION_POSTURE_UNKNOWN
         *a                           to specify that no alternate should be used
         *a    variant_alternate1   - if an exact match is not found, use this
         *a                           as the first alternate variant; pass
         *a                           DIGUY_MOTION_VARIANT_UNKNOWN
         *a                           to specify that no alternate should be used
         *a    variant_alternate2   - if an exact match is not found, use this
         *a                           as the second alternate variant; pass
         *a                           DIGUY_MOTION_VARIANT_UNKNOWN
         *a                           to specify that no alternate should be used
         *a    return_random_match  - (Experimental) if multiple actions match the
         *a                           specified criteria randomly return one of
         *a                           them. Typically only used for still motions
         *a                           and restricted to EQUAL and NEAREST
         *a                           comparisons
         **
         **    The direction argument should be one of the following:
         **
         *-     - DIGUY_MOTION_DIRECTION_NONE           - does not move character
         *-     - DIGUY_MOTION_DIRECTION_FORWARD        - moves character forward
         *-     - DIGUY_MOTION_DIRECTION_BACKWARD       - moves character backward
         *-     - DIGUY_MOTION_DIRECTION_LEFT           - moves character left
         *-     - DIGUY_MOTION_DIRECTION_RIGHT          - moves character right
         *-     - DIGUY_MOTION_DIRECTION_UP             - moves character up
         *-     - DIGUY_MOTION_DIRECTION_DOWN           - moves character down
         *-     - DIGUY_MOTION_DIRECTION_TURN_LEFT      - turns character left
         *-     - DIGUY_MOTION_DIRECTION_TURN_RIGHT     - turns character right
         *-     - DIGUY_MOTION_DIRECTION_NONLINEAR      - moves character in
         *-                                               multiple directions
         *-     - DIGUY_MOTION_DIRECTION_LINEAR_OFFAXIS - moves character in a
         *-                                               line, but not on any
         *-                                               of the principle axes
         **
         **    Not every direction is supported by every character.  If the
         **    character does not have any actions that move in the specified
         **    direction, the returned action will be NULL.
         **
         **    Use the calls diguyScenario::get_character_type_num_directions()
         **    and diguyScenario::get_character_type_direction_at_index() to
         **    enumerate which directions a character can travel.
         **
         **    The posture arguments should be one of the following:
         **
         *-     - DIGUY_MOTION_POSTURE_UNKNOWN  - unknown posture
         *-     - DIGUY_MOTION_POSTURE_ANY      - any posture; a wildcard
         *-     - DIGUY_MOTION_POSTURE_UPRIGHT  - upright posture; e.g., standing
         *-                                       or walking
         *-     - DIGUY_MOTION_POSTURE_CROUCHED - crouched posture; e.g., kneeling
         *-                                       or walking low
         *-     - DIGUY_MOTION_POSTURE_PRONE    - prone posture; e.g., lying prone
         *-                                       or crawling
         *-     - DIGUY_MOTION_POSTURE_SITTING  - sitting posture
         **
         **    The posture arguments specify the overall posture the action
         **    should have.  Most characters have an upright posture.
         **    The other postures a character has is dependent on character type.
         **    Passing DIGUY_MOTION_POSTURE_ANY for the arguments posture,
         **    posture_alternate1, or posture_alternate2 means that the posture of
         **    the action should not be used to determine a match.
         **
         **    Use the calls diguyScenario::get_character_type_num_postures()
         **    and diguyScenario::get_character_type_posture_at_index() to
         **    enumerate which postures a specific character type has.
         **
         **    The variant arguments specify the overall mood the action should
         **    convey.  Most characters have a "normal" variant.  The other
         **    variants a character has is dependent on character type.  Passing
         **    DIGUY_MOTION_VARIANT_ANY for the arguments variant,
         **    variant_alternate1, or variant_alternate2 means that the variant of
         **    the action should not be used to determine a match.
         **
         **    Use the calls diguyScenario::get_character_type_num_variants()
         **    and diguyScenario::get_character_type_variant_at_index() to
         **    enumerate which variants a specific character type has.
         **
         **    The comparison argument should be one of the following:
         **
         *-     - DIGUY_PARAMETER_COMPARISON_EQUAL   - matched action's speed
         *-                                            must be within
         *-                                            comparison_tolerance of
         *-                                            passed speed
         *-     - DIGUY_PARAMETER_COMPARISON_NEAREST - matched action's speed
         *-                                            is closer than any other
         *-                                            potential match's, but
         *-                                            still within
         *-                                            comparison_tolerance
         *-     - DIGUY_PARAMETER_COMPARISON_GREATER - matched action's speed
         *-                                            faster than passed speed,
         *-                                            but still within
         *-                                            comparison_tolerance
         *-     - DIGUY_PARAMETER_COMPARISON_LESS    - matched action's speed
         *-                                            slower than passed speed,
         *-                                            but still within
         *-                                            comparison_tolerance
         *-
         **    The difference between DIGUY_PARAMETER_COMPARISON_EQUAL and
         **    DIGUY_PARAMETER_COMPARISON_NEAREST is largely in the
         **    value used for comparison_tolerance if DIGUY_DEFAULT_FLOAT is
         **    passed; the comparison_tolerance argument defaults to 0.001 for
         **    DIGUY_PARAMETER_COMPARISON_EQUAL, and 16384.0 for all
         **    other comparison types.  Otherwise these two comparison types
         **    operate the same.
         **
         *b  Returns:
         **
         **    name of an action if a match is found, NULL if not
         **
         *b  C++ Example:
         **
         *e     diguyCharacter* ch = scenario->get_character_at_index(0);
         *e     const char* new_action;
         *e
         *e     //
         *e     //  Get an action that moves forward in an upright posture,
         *e     //  whose speed move at least 2.0 meters per second:
         *e     //
         *e     new_action = ch->get_action_from_description(
         *e         DIGUY_MOTION_DIRECTION_FORWARD,
         *e         DIGUY_MOTION_POSTURE_UPRIGHT,
         *e         DIGUY_MOTION_VARIANT_ANY,
         *e         2.0,
         *e         DIGUY_PARAMETER_COMPARISON_GREATER, DIGUY_DEFAULT_FLOAT);
         *e
         *e     //
         *e     //  Get an action that is standing still, with the variant
         *e     //  DIGUY_MOTION_VARIANT_READY.  If no action has that variant,
         *e     //  try DIGUY_MOTION_VARIANT_AIM as variant_alternate1,
         *e     //  and DIGUY_MOTION_VARIANT_ANY as variant_alternate2:
         *e     //
         *e     new_action = ch->get_action_from_description(
         *e         DIGUY_MOTION_DIRECTION_NONE,
         *e         DIGUY_MOTION_POSTURE_ANY,
         *e         DIGUY_MOTION_VARIANT_READY,
         *e         0.0,
         *e         DIGUY_PARAMETER_COMPARISON_NEAREST, DIGUY_DEFAULT_FLOAT,
         *e         0,
         *e         DIGUY_MOTION_POSTURE_UNKNOWN,
         *e         DIGUY_MOTION_POSTURE_UNKNOWN,
         *e         DIGUY_MOTION_VARIANT_AIM,
         *e         DIGUY_MOTION_VARIANT_ANY);
         **
         */
        const char* get_action_from_description(diguyMotionDirection direction,
                diguyMotionPosture posture,
                diguyMotionVariant variant,
                float speed,
                diguyParameterComparison comparison = DIGUY_PARAMETER_COMPARISON_NEAREST,
                float comparison_tolerance = DIGUY_DEFAULT_FLOAT,
                int match_posture_before_variant = 1,
                diguyMotionPosture posture_alternate1 = DIGUY_MOTION_POSTURE_UNKNOWN,
                diguyMotionPosture posture_alternate2 = DIGUY_MOTION_POSTURE_UNKNOWN,
                diguyMotionVariant variant_alternate1 = DIGUY_MOTION_VARIANT_UNKNOWN,
                diguyMotionVariant variant_alternate2 = DIGUY_MOTION_VARIANT_UNKNOWN,
                int return_random_match = 0);

        /*l
         *b  Description:
         **
         **    This function is very similar to get_action_from_description(),
         **    but substitutes turn amount per action iteration for speed.
         **
         *b  Arguments:
         **
         *a    direction            - the direction of travel relative to
         *a                           the character's facing direction
         *a    posture              - overall desired posture; pass
         *a                           DIGUY_MOTION_POSTURE_ANY
         *a                           to specify that any posture will do
         *a    variant              - overall desired variant; pass
         *a                           DIGUY_MOTION_VARIANT_ANY
         *a                           to specify that any variant will do
         *a    turn_amount          - how many degrees each iteration of the
         *a                           action should turn the character
         *a    comparison           - how the passed turn amount should compare
         *a                           to the action's turn amount
         *a    comparison_tolerance - tolerance of comparison
         *a    match_posture_before_variant - pass 1 if posture should be matched
         *a                                   before variant if an exact match is
         *a                                   not found; pass 0 if variant should
         *a                                   be matched before posture
         *a    posture_alternate1   - if an exact match is not found, use this
         *a                           as the first alternate posture; pass
         *a                           DIGUY_MOTION_POSTURE_UNKNOWN
         *a                           to specify that no alternate should be used
         *a    posture_alternate2   - if an exact match is not found, use this
         *a                           as the second alternate posture; pass
         *a                           DIGUY_MOTION_POSTURE_UNKNOWN
         *a                           to specify that no alternate should be used
         *a    variant_alternate1   - if an exact match is not found, use this
         *a                           as the first alternate variant; pass
         *a                           DIGUY_MOTION_VARIANT_UNKNOWN
         *a                           to specify that no alternate should be used
         *a    variant_alternate2   - if an exact match is not found, use this
         *a                           as the second alternate variant; pass
         *a                           DIGUY_MOTION_VARIANT_UNKNOWN
         *a                           to specify that no alternate should be used
         **
         **    The direction argument should be one of the following:
         **
         *-     - DIGUY_MOTION_DIRECTION_TURN_LEFT      - turns character left
         *-     - DIGUY_MOTION_DIRECTION_TURN_RIGHT     - turns character right
         **
         **    Not every direction is supported by every character.  If the
         **    character does not have any actions that move in the specified
         **    direction, the returned action will be NULL.
         **
         **    The turn amount argument should be a positive number.
         **
         **    Refer to get_action_from_description() for more information on
         **    other arguments.
         **
         *b  Returns:
         **
         **    name of an action if a match is found, NULL if not
         **
         */
        const char* get_turning_action_from_description(diguyMotionDirection direction,
                diguyMotionPosture posture,
                diguyMotionVariant variant,
                float turn_amount,
                diguyParameterComparison comparison = DIGUY_PARAMETER_COMPARISON_NEAREST,
                float comparison_tolerance = DIGUY_DEFAULT_FLOAT,
                int match_posture_before_variant = 1,
                diguyMotionPosture posture_alternate1 = DIGUY_MOTION_POSTURE_UNKNOWN,
                diguyMotionPosture posture_alternate2 = DIGUY_MOTION_POSTURE_UNKNOWN,
                diguyMotionVariant variant_alternate1 = DIGUY_MOTION_VARIANT_UNKNOWN,
                diguyMotionVariant variant_alternate2 = DIGUY_MOTION_VARIANT_UNKNOWN);


/*****************************************************************************/
        /*l
         *b  Returns:
         **
         **    number of variables the character has
         */
        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:
         **
         **    1 if variable is equal to passed value,
         **    0 if not
         **
         *b  Arguments:
         **
         *a    varname  - name of variable to compare
         *a    value    - value to compare against
         **
         *b  Available as Decision Bead/Event
         */
        int variable_equal_to_int(const char* varname, int value);

        /*l
         *b  Returns:
         **
         **    1 if variable is greater than passed value,
         **    0 if not
         **
         *b  Arguments:
         **
         *a    varname  - name of variable to compare
         *a    value    - value to compare against
         **
         *b  Available as Decision Bead/Event
         */
        int variable_greater_than_int(const char* varname, int value);

        /*l
         *b  Returns:
         **
         **    1 if variable is less than passed value,
         **    0 if not
         **
         *b  Arguments:
         **
         *a    varname  - name of variable to compare
         *a    value    - value to compare against
         **
         *b  Available as Decision Bead/Event
         */
        int variable_less_than_int(const char* varname, int value);

        /*l
         *b  Returns:
         **
         **    1 if variable is equal to passed value,
         **    0 if not
         **
         *b  Arguments:
         **
         *a    varname  - name of variable to compare
         *a    value    - value to compare against
         **
         *b  Available as Decision Bead/Event
         */
        int variable_equal_to_float(const char* varname, float value);

        /*l
         *b  Returns:
         **
         **    1 if variable is greater than passed value,
         **    0 if not
         **
         *b  Arguments:
         **
         *a    varname  - name of variable to compare
         *a    value    - value to compare against
         **
         *b  Available as Decision Bead/Event
         */
        int variable_greater_than_float(const char* varname, float value);

        /*l
         *b  Returns:
         **
         **    1 if variable is less than passed value,
         **    0 if not
         **
         *b  Arguments:
         **
         *a    varname  - name of variable to compare
         *a    value    - value to compare against
         **
         *b  Available as Decision Bead/Event
         */
        int variable_less_than_float(const char* varname, float value);

        /*l
         *b  Returns:
         **
         **    1 if variable is equal than passed value,
         **    0 if not
         **
         *b  Arguments:
         **
         *a    varname  - name of variable to compare
         *a    value    - value to compare against
         **
         *b  Available as Decision Bead/Event
         */
        int variable_equal_to_string(const char* varname, const char* value);

        /*l
         *b  Returns:
         **
         **    1 if variable is greater than passed value (comes
         **    later alphabetically), 0 if not
         **
         *b  Arguments:
         **
         *a    varname  - name of variable to compare
         *a    value    - value to compare against
         **
         *b  Available as Decision Bead/Event
         */
        int variable_greater_than_string(const char* varname, const char* value);

        /*l
         *b  Returns:
         **
         **    1 if variable is less than passed value (comes
         **    sooner alphabetically), 0 if not
         **
         *b  Arguments:
         **
         *a    varname  - name of variable to compare
         *a    value    - value to compare against
         **
         *b  Available as Decision Bead/Event
         */
        int variable_less_than_string(const char* varname, const char* value);

        /*l
         *b  Description:
         **
         **    This function decrements the variable by the passed amount.
         **
         *b  Arguments:
         **
         *a    varname  - name of variable to modify
         *a    value    - amount to decrement
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int variable_decrement_value_as_int(const char* varname, int value = 1);

        /*l
         *b  Description:
         **
         **    This function increments the variable by the passed amount.
         **
         *b  Arguments:
         **
         *a    varname  - name of variable to modify
         *a    value    - amount to increment
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int variable_increment_value_as_int(const char* varname, int value = 1);

        /*l
         *b  Description:
         **
         **    This function is a convenience function for setting the variable
         **    to a new integer value without retrieving the diguyVariable
         **    object.
         **
         *b  Arguments:
         **
         *a    varname  - name of variable to modify
         *a    value    - new value
         *a    create_if_doesnt_exist - pass 1 to create the variable if it
         *a                             doesn't exist
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int variable_set_value_as_int(const char* varname,
                int value,
                int create_if_doesnt_exist = 1);

        /*l
         *b  Description:
         **
         **    Short form of variable_set_value_as_int().
         */
        int set_ivar(const char* varname,
                int value,
                int create_if_doesnt_exist = 1);

        /*l
         *b  Description:
         **
         **    This function is a convenience function for retrieving the
         **    value of a variable without retrieving the diguyVariable
         **    object.
         **
         **    If the variable doesn't exist and create_if_doesnt_exist is
         **    0, the returned value will be 0.
         **
         *b  Arguments:
         **
         *a    varname  - name of variable to query
         *a    create_if_doesnt_exist - pass 1 to create the variable if it
         *a                             doesn't exist
         **
         *b  Returns:
         **
         **    value of variable as int
         */
        int get_ivar(const char* varname,
                int create_if_doesnt_exist = 1);

        /*l
         *b  Description:
         **
         **    Similar to variable_set_value_as_int(), for sets a
         **    floating point value instead.
         */
        int variable_set_value_as_float(const char* varname,
                float value,
                int create_if_doesnt_exist = 1);

        /*l
         *b  Description:
         **
         **    Short form of variable_set_value_as_float().
         */
        int set_fvar(const char* varname,
                float value,
                int create_if_doesnt_exist = 1);

        /*l
         *b  Description:
         **
         **    Similar to variable_get_value_as_int(), for returns a
         **    floating point value instead.
         **
         **    If the variable doesn't exist and create_if_doesnt_exist is
         **    0, the returned value will be 0.0.
         */
        float get_fvar(const char* varname,
                int create_if_doesnt_exist = 1);

        /*l
         *b  Description:
         **
         **    Similar to variable_set_value_as_int(), for sets a
         **    string value instead.
         */
        int variable_set_value_as_string(const char* varname,
                const char* value,
                int create_if_doesnt_exist = 1);

        /*l
         *b  Description:
         **
         **    Short form of variable_set_value_as_string().
         */
        int set_svar(const char* varname,
                const char* value,
                int create_if_doesnt_exist = 1);

        /*l
         *b  Description:
         **
         **    Similar to variable_get_value_as_int(), for returns a
         **    string value instead.
         **
         **    If the variable doesn't exist and create_if_doesnt_exist is
         **    0, the returned value will be "".
         */
        const char* get_svar(const char* varname,
                int create_if_doesnt_exist = 1);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function returns a pointer to the label object of
         **    the character.
         **
         **    Currently character labels are only enabled in DI-Guy Scenario.
         **
         *b  Returns:
         **
         **    pointer to the character's label
         */
        diguyViewLabel* get_name_label();

        /*l
         *b  Description:
         **
         **    This function sets the text of the character's label.
         **    By default the label text matches the character's name.
         **
         **    Currently character labels are only enabled in DI-Guy Scenario.
         **
         *b  Arguments:
         **
         *a    label_text - new text for the label
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_label_text(const char* label_text);

        /*l
         *b  Description:
         **
         **    This function returns the character's label text.
         **    See set_label_text().
         **
         *b  Returns:
         **
         **    current label text; the returned pointer will never be NULL
         */
        const char* get_label_text();

        /*l
         *b  Description:
         **
         **    This function sets whether the label of this character
         **    is visible.  This setting will only be taken into account
         **    if the visibility flag for Character Labels is set to
         **    "Per Object".
         **
         **    Currently character labels are only enabled in DI-Guy Scenario.
         **
         *b  Arguments:
         **
         *a    is_visible - pass 1 to show, pass 0 to hide
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_label_is_visible(int is_visible);

        /*l
         *b  Description:
         **
         **    This function returns the most recent setting of
         **    set_label_is_visible().
         **
         *b  Returns:
         **
         **    1 if visible, 0 if not
         */
        int get_label_is_visible();

        /*l
         *b  Description:
         **
         **    This function sets the text color of the character's label.  By
         **    default the label text color is opaque white.
         **
         **    Currently character labels are only enabled in DI-Guy Scenario.
         **
         *b  Arguments:
         **
         *a    r, g, b, a - the red, green, blue, and alpha
         *a                 components of the text color
         **
         **    An alpha component of 0 makes the text completely transparent.
         **    An alpha component of 1 makes the text completely opaque.
         **    Values in between result in varying levels of transparency.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_label_text_color(float r, float g, float b, float a);

        /*l
         *b  Description:
         **
         **    Alternate version of set_label_text_color().
         */
        int set_label_text_color_vec4(const diguyVec4f & color);

        /*l
         *b  Description:
         **
         **    This function returns, in the passed variable pointers, the
         **    most recent setting of set_label_text_color().
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_label_text_color(float* r, float* g, float* b, float* a);

        /*l
         *b  Description:
         **
         **    Alternate version of get_label_text_color().
         */
        diguyVec4f get_label_text_color_vec4();

        /*l
         *b  Description:
         **
         **    This function sets the text shadow color of the character's label.
         **    By default the label text shadow color is gray.
         **
         **    Currently character labels are only enabled in DI-Guy Scenario.
         **
         *b  Arguments:
         **
         *a    r, g, b, a - the red, green, blue, and alpha
         *a                 components of the text shadow color
         **
         **    An alpha component of 0 makes the text completely transparent.
         **    An alpha component of 1 makes the text completely opaque.
         **    Values in between result in varying levels of transparency.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_label_text_shadow_color(float r, float g, float b, float a);

        /*l
         *b  Description:
         **
         **    Alternate version of set_label_text_shadow_color().
         */
        int set_label_text_shadow_color_vec4(const diguyVec4f & color);

        /*l
         *b  Description:
         **
         **    This function returns, in the passed variable pointers, the
         **    most recent setting of set_label_text_shadow_color().
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_label_text_shadow_color(float* r, float* g, float* b, float* a);

        /*l
         *b  Description:
         **
         **    Alternate version of get_label_text_shadow_color().
         */
        diguyVec4f get_label_text_shadow_color_vec4();

        /*l
         *b  Description:
         **
         **    This function sets the whether the text shadow is visible.
         **
         *b  Arguments:
         **
         *a    visible - pass 1 to make shadow visible, 0 to make it invisible
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_label_text_shadow_is_visible(int is_visible);

        /*l
         *b  Returns:
         **
         **    1 if text shadow is visible, 0 if not
         */
        int get_label_text_shadow_is_visible();

        /*l
         *b  Description:
         **
         **    This function sets the background color of the character's
         **    label.  By default the label background color is transparent
         **    blue.
         **
         **    Currently character labels are only enabled in DI-Guy Scenario.
         **
         *b  Arguments:
         **
         *a    r, g, b, a - the red, green, blue, and alpha
         *a                 components of the text color
         **
         **    An alpha component of 0 makes the text completely transparent.
         **    An alpha component of 1 makes the text completely opaque.
         **    Values in between result in varying levels of transparency.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_label_background_color(float r, float g, float b, float a);

        /*l
         *b  Description:
         **
         **    Alternate version of set_label_background_color().
         */
        int set_label_background_color_vec4(const diguyVec4f & color);

        /*l
         *b  Description:
         **
         **    This function returns, in the passed variable pointers, the
         **    most recent setting of set_label_background_color().
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_label_background_color(float* r, float* g, float* b, float* a);

        /*l
         *b  Description:
         **
         **    Alternate version of get_label_background_color().
         */
        diguyVec4f get_label_background_color_vec4();

        /*l
         *b  Description:
         **
         **    This function sets how high the label of the character will float
         **    above the character.
         **
         *b  Arguments:
         **
         *a    offset - offset, in meters, of label above character
         */
        void set_label_link_offset_override(float offset);

        /*l
         *b  Returns:
         **
         **    how high the label of the character will float above the character
         */
        float get_label_link_offset_override();

        /*l
         *b  Description:
         **
         **    This function sets whether the label text should show some basic
         **    state information about the character instead of its name or
         **    the text set by set_label_text().
         **
         **    The state shown is: Character name, current path, current action.
         **    The current path and current action will change as the character
         **    moves through paths and actions.
         **
         *b  Arguments:
         **
         *a    show_state - pass 1 to show state, 0 to show original text
         */
        int set_label_shows_character_state(int show_state);

        /*l
         *b  Returns:
         **
         **    whether character state information is shown instead of the
         **    character's name or other label text
         */
        int get_label_shows_character_state();


/*****************************************************************************/
        /*l
         *b  Returns:
         **
         **    pointer of type diguyImpact; NULL if there has been no recent
         **    impact recorded; useful for finding out who or what was hit
         */
        diguyImpact* get_last_impact_record();

        /*l
         *b  Returns:
         **
         **    the last impact number
         */
        int get_last_impact_number();

        /*l
         *b  Returns:
         **
         **    the processed flag on the diguyImpact class
         */
        int get_last_impact_been_processed();

        /*l
         *b  Description:
         **
         **    Sets the processed flag on the diguyImpact object.
         */
        void set_last_impact_been_processed();

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

        /*l
         *b  Returns:
         **
         **    maximum number of unprocessed impacts
         */
        int get_max_unprocessed_impacts();

        /*l
         *b  Returns:
         **
         **    the last impact link
         */
        const char* get_last_impact_link();

        /*l
         *b  Returns:
         **
         **    1 if the last impact link is the link named
         */
        int get_last_impact_link_is(const char* link_name);

        /*l
         *b  Returns:
         **
         **    1 if the last impact resulted from an impact with a vehicle,
         **    0 if not
         */
        int get_last_impact_is_from_vehicle();

        /*l
         *b  Returns:
         **
         **    1 if the last impact speed is greater than the passed speed,
         **    0 if not
         */
        int get_last_impact_speed_is_greater_than(float impact_speed);

        /*l
         *b  Description:
         **
         **    Sets if impacts are ever processed on this character.
         **    Useful for temporary effects and the like.
         */
        void set_is_immune_to_impacts(int immune);

        /*l
         *b  Returns:
         **
         **    1 if the character is immune to impacts
         **    0 if not
         */
        int get_is_immune_to_impacts();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function starts the specified appearance effect on
         **    the character.
         **
         **    The following appearance effects are available:
         **
         *-    - "brake_lights"
         *-    - "debris"
         *-    - "debris_dark"
         *-    - "dust"
         *-    - "engine_smoke"
         *-    - "explosion"
         *-    - "explosion_dark"
         *-    - "flames"
         *-    - "flashing_lights"
         *-    - "ground_dust_burst"
         *-    - "headlights"
         *-    - "rotor_wash"
         *-    - "smoke"
         *-    - "smoke_dark"
         *-    - "smoke_trail"
         **
         *b  Arguments:
         **
         *a    effect            - name of appearance effect to be started
         *a    override_link     - link to attach to; overrides default
         *a    override_scale    - scale to use for effect; overrides default
         *a    override_offset_x - x offset to use for effect; overrides default
         *a    override_offset_y - y offset to use for effect; overrides default
         *a    override_offset_z - z offset to use for effect; overrides default
         *a    override_duration - overrides how long the effect should show
         *a                        before automatically ending
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int begin_appearance_effect(const char* effect,
                const char* override_link = NULL,
                float override_scale = DIGUY_DEFAULT_FLOAT,
                float override_offset_x = DIGUY_DEFAULT_FLOAT,
                float override_offset_y = DIGUY_DEFAULT_FLOAT,
                float override_offset_z = DIGUY_DEFAULT_FLOAT,
                float override_duration = DIGUY_DEFAULT_FLOAT);

        /*l
         *b  Description:
         **
         **    This function ends the specified appearance effect on the
         **    character.
         **
         **    The active particles of the effect will go to completion.  Use
         **    stop_all_appearance_effects() to immediately stop effects,
         **    including their active particles.
         **
         **    If the effect hasn't been started, nothing happens.
         **
         *b  Arguments:
         **
         *a    effect        - name of appearance effect to be ended
         *a    override_link - optional override link effect is attached to
         **
         **    Pass "all" for the effect argument to end all of this character's
         **    appearance effects.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int end_appearance_effect(const char* effect,
                const char* override_link = NULL);

        /*l
         *b  Description:
         **
         **    This function stops the specified appearance effect on the
         **    character.
         **
         **    The active particle systems of the effect will immediately be
         **    removed.  Use end_appearance_effect() to gradually stop effects;
         **    that function lets active particles move to completion.
         **
         **    If the effect hasn't been started, nothing happens.
         **
         *b  Arguments:
         **
         *a    effect        - name of appearance effect to be ended
         *a    override_link - optional override link effect is attached to
         **
         **    Pass "all" for the effect argument to stop all of this character's
         **    appearance effects.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int stop_appearance_effect(const char* effect,
                const char* override_link = NULL);

        /*l
         *b  Description:
         **
         **   Equivalent to stop_appearance_effect("all");
         */
        int stop_all_appearance_effects();

        /*l
         *b  Description:
         **
         **    This function checks to see if the specified appearance effect
         **    has been started with begin_appearance_effect().
         **
         *b  Arguments:
         **
         *a    effect        - name of appearance effect to check
         *a    override_link - optional override link effect is attached to
         **
         *b  Returns:
         **
         **    1 if appearance is active, 0 if not
         */
        int appearance_effect_is_active(const char* effect,
                const char* override_link = NULL);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function returns a pointer to a diguyChainSimulation if the
         **    character is a chain_simulation type of character.
         **
         *b  Returns:
         **
         **    pointer to a diguyChainSimulation
         */
        diguyChainSimulation* get_chain_simulation();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function returns a pointer to a diguyVehicleController if the
         **    character has one.
         **
         *b  Returns:
         **
         **    pointer to a diguyVehicleController; may return NULL if character
         **    does not have a vehicle controller object
         */
        diguyVehicleController* get_vehicle_controller();

        /*l
         *b  Description:
         **
         **    For most characters playing a travel forward action, the
         **    character's facing direction matches the direction of travel.  For
         **    example, when humans walk forward their pelvis is generally
         **    aligned in the direction of travel.
         **
         **    Some vehicle characters behave differently.  For vehicles whose
         **    front wheels steer, when turning the vehicle body will pivot around
         **    the rear axle.  Only gradually will the rear of the vehicle swing
         **    in behind the direction of travel.  Think of a car making a very
         **    sharp turn, and how the rear of the car swings in behind the front
         **    as the turn is completed.
         **
         **    This function will return the orientation of the body of the
         **    vehicle; i.e., the orientation of the forward vector along the
         **    vehicle's long axis.  As mentioned above this may be different
         **    than the orientation of the direction of travel.
         **
         **    This function will return valid results for all characters, though
         **    the returned values from this function and that of
         **    get_orientation() will be the same for non-vehicle characters.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_vehicle_body_orientation(float* rz, float* rx, float* ry);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets the name of the shader program that will be
         **    used by the character when the scenario is using the specified
         **    render mode.  See diguyScenario::set_current_render_mode().
         **
         **    Note that care should be taken when changing the shader of
         **    characters with skinned appearances.  A shader capable of properly
         **    transforming vertices must be used for such characters.
         **
         **    The shader with the given name should be loaded first.  If the
         **    shader program is not one of DI-Guy's stock shaders, a custom
         **    shader program can be loaded explicitly by calling
         **    the diguyApp::load_shader_program() function.
         **
         *b  NOTE:
         **
         **    The specified shader program may not take effect immediately,
         **    if the scenario's current render mode is different than the
         **    passed render mode.  See
         **    diguyScenario::set_current_render_mode().
         **
         *b  Arguments:
         **
         *a    shader_name - shader program name; can be NULL
         *a    render_mode - render mode to modify; passing NULL will
         *a                  modify shader "normal" render mode
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_render_mode_shader(const char* shader_name,
                const char* render_mode = NULL);

        /*l
         *b  Description:
         **
         **    This function resets the shader program for the specified render
         **    mode to its default.  This will be the shader program name
         **    returned by
         **    diguyScenario::get_default_character_shader_program_name().
         **
         **    If the specified render mode is the current scenario render mode,
         **    the current shader will change immediately.  If not, the change
         **    will not take effect until the specified render mode becomes the
         **    current scenario render mode.  See
         **    diguyScenario::set_current_render_mode().
         **
         *b  Arguments:
         **
         *a    render_mode - render mode to modify; passing NULL will
         *a                  modify shader of "normal" render mode
         */
        void reset_render_mode_shader_to_default(const char* render_mode = NULL);

        /*l
         *b  Description:
         **
         **    This function returns the name of the shader that will be used by
         **    the character when the scenario is using the specified render
         **    mode.
         **
         *b  Arguments:
         **
         *a    render_mode - render mode for which to get program name;
         *a                  pass NULL for "normal" render mode
         **
         *b  Returns:
         **
         **    name of shader program; NULL if none or error
         */
        const char* get_render_mode_shader(const char* render_mode = NULL);

        /*l
         *b  Description:
         **
         **    This function returns the shader program that is in use by the
         **    character.  Shader programs are shared objects that can be used
         **    by multiple characters.
         **
         *b  Returns:
         **
         **    object of type diguyGraphicsShaderProgram; NULL if none
         */
        diguyGraphicsShaderProgram* get_shader_program();

        /*l
         *b  Description:
         **
         **    This function overrides the current shader with the specified
         **    temporary shader.  This temporary shader will remain in effect
         **    until:
         **
         *-    - the scenario is reset
         *-    - reset_current_shader_to_default() is called
         *-    - set_temporary_current_shader() is called with NULL
         **
         *b  Arguments:
         **
         *a    shader_name - shader name; can be NULL
         **
         **    Passing NULL for the shader name will un-set the temporary shader,
         **    resetting the render mode shader to its default.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_temporary_current_shader(const char* shader_name);

        /*l
         *b  Description:
         **
         **    This is a convenience function for resetting the current render
         **    mode shader to its default.
         **
         **    It is equivalent to retrieving the current render mode using
         **    diguyScenario::get_current_render_mode(), and calling
         **    reset_render_mode_shader_to_default() with that render mode.
         */
        void reset_current_shader_to_default();

        /*l
         *b  Description:
         **
         **    This is a convenience function for refreshing the shader
         **    of a character.  Usually used in conjunction with logic
         **    provided by the user with the graphics API.
         */
        void trigger_shader_refresh();

        /*l
         *b  Description:
         **
         **    This function returns the shader instance that is in use by the
         **    character.  Each character has its own shader instance.
         **
         **    Note that the shader instance of a character can change over the
         **    lifetime of the character.  For example, it will change if the
         **    appearance of the character changes.  Therefore the returned
         **    pointer should not be stored, but should be re-read each time
         **    it is needed.
         **
         *b  Returns:
         **
         **    object of type diguyGraphicsShaderInstance; NULL if none
         */
        diguyGraphicsShaderInstance* get_shader_instance();

        /*l
         *b  Description:
         **
         **    This function resets current values of the variables of the shader
         **    back to their initial reset values.
         */
        void reset_shader_instance_variables_to_initial_values();

        /*l
         *b  Description:
         **
         **    This function resets the current and initial values of variables
         **    of the shader to the built-in DI-Guy configuration defaults.
         */
        void reset_shader_instance_variables_to_program_defaults();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets the named character as the attack
         **    target of this agent.  This agent will pursue the
         **    target until it is within range, and then will fire its
         **    weapon in an attempt to kill the target.
         **
         **    This function will implicitly put this agent into the
         **    attack behavior.
         **
         **    The current focus character will be set the specified character.
         **    Pass NULL or the empty string ("") to not change the focus
         **    character, but still change to the pursue behavior.
         **
         **    The current focus group will be un-set.
         **
         *b  Arguments:
         **
         *a    character_name - character to attack
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int agent_attack_character(const char* character_name);

        /*l
         *b  Description:
         **
         **    This function is similar to agent_attack_character(), but instead
         **    will choose attack targets from the characters in the specified
         **    group.
         **
         **    This function will implicitly put this agent into the attack
         **    behavior.
         **
         **    The current focus group will be set to the specified group.  Pass
         **    NULL or the empty string ("") to not change the focus group, but
         **    still change to the attack behavior.
         **
         **    The current focus character will be un-set.
         **
         *b  Arguments:
         **
         *a    group_name - name of group from which attack targets should
         *a                 be chosen
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int agent_attack_group(const char* group_name);

        /*l
         *b  Description:
         **
         **    See diguyAgentParams::set_attack_zone_enabled().
         */
        int agent_set_attack_zone_enabled(int use_attack_zone);

        /*l
         *b  Description:
         **
         **    See diguyAgentParams::get_attack_zone_enabled().
         */
        int agent_get_attack_zone_enabled();

        /*l
         *b  Description:
         **
         **    See diguyAgentParams::set_attack_zone().
         */
        int agent_set_attack_zone(float x, float y, float z, float radius);

        /*l
         *b  Description:
         **
         **    See diguyAgentParams::get_attack_zone().
         */
        int agent_get_attack_zone(float* x, float* y, float* z, float* radius);

        /*l
         *b  Description:
         **
         **    This function adds a flee object to this agent.
         **    This agent will attempt to move away from the specified
         **    character until it is beyond the specified flee distance.
         **
         **    Note: Currently there can only be one flee object.  This
         **    restriction will be lifted in a future version.
         **
         **    This function will implicitly put this agent into the
         **    flee behavior.
         **
         **    Neither the current focus character nor group will be
         **    changed by this function.
         **
         *b  Arguments:
         **
         *a    character_name - character from which to flee
         *a    distance       - minimum distance to move away from character
         *a    danger_level   - how "strong" the flee should be; set from
         *a                     0 to 100
         **
         **    The danger_level argument is not currently used, but will be in
         **    a future version.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int agent_flee_character(const char* character_name,
                float distance,
                int danger_level = 50);

        /*l
         *b  Description:
         **
         **    This function adds a flee object to this agent.  This agent
         **    will attempt to move away from the specified group until it is
         **    beyond the specified flee distance.
         **
         **    This function will implicitly put this agent into the flee
         **    behavior.
         **
         **    Neither the current focus character nor group will be changed
         **    by this function.
         **
         *b  Arguments:
         **
         *a    group_name     - group from which to flee
         *a    distance       - minimum distance to move away from character
         *a    danger_level   - how "strong" the flee should be; set from
         *a                     0 to 100
         **
         **    The danger_level argument is not currently used, but will be in
         **    a future version.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int agent_flee_group(const char* group_name,
                float distance,
                int danger_level = 50);

        /*l
         *b  Description:
         **
         **    This function is similar to agent_flee_group(), but the
         **    agent will instead flee the members of the specified
         **    crowd.
         */
        int agent_flee_crowd(const char* crowd_name,
                float distance,
                int danger_level = 50);

        /*l
         *b  Description:
         **
         **    This function adds a flee object to this agent.
         **    This agent will attempt to move away from the specified
         **    location until it is beyond the specified flee distance.
         **
         **    Note: Currently there can only be one flee object.  This
         **    restriction will be lifted in a future version.
         **
         **    This function will implicitly put this agent into the
         **    flee behavior.
         **
         **    Neither the current focus character nor group will be
         **    changed by this function.
         **
         *b  Arguments:
         **
         *a    x, y, z      - location from which to flee
         *a    distance     - minimum distance to move away from character
         *a    danger_level - how "strong" the flee should be; set from
         *a                   0 to 100
         **
         **    The danger_level argument is not currently used, but will be in
         **    a future version.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int agent_flee_location(float x, float y, float z,
                float distance,
                int danger_level = 50);

        /*l
         *b  Description:
         **
         **    This function removes all flee objects.
         **
         **    This function has no effect on current behavior.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        void agent_remove_all_flee_objects();

        /*l
         *b  Description:
         **
         **    This function puts this agent into the mingle behavior, in which
         **    it will choose semi-random points in the specified region and
         **    subregion to move to.  The agent will remain at the selected
         **    points for some amount of time, and the select a new point.
         **
         **    If all members of a crowd have this behavior they will tend to get
         **    together in small groups.
         **
         **    Use diguyAgentParams::set_move_on_t_min() and
         **    diguyAgentParams::set_move_on_t_max() for setting how long the
         **    agent will remain at the selected mingle points.
         **
         *b  Arguments:
         **
         *a    region_name    - region in which to mingle
         *a    subregion_name - subregion in which to mingle
         **
         **    The behavior region will be set the specified region.  Pass NULL
         **    or "(current)" to not change the current behavior region.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int agent_mingle_in_region(const char* region_name = "(current)",
                const char* subregion_name = "base");

        /*l
         *b  Description:
         **
         **    This function is similar to agent_mingle_in_region(), but agents
         **    will pick completely random points and not try to clump together
         **    in small groups.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int agent_wander_region(const char* region_name = "(current)",
                const char* subregion_name = "base");

        /*l
         *b  Description:
         **
         **    This function will cause this agent to pursue the specified
         **    character.  This agent will attempt to move toward the specified
         **    character until it is within its still distance as specified in
         **    its agent params.
         **
         **    This function will implicitly put this agent into the pursue
         **    behavior.
         **
         **    The current focus group will be set to the specified group.  Pass
         **    NULL or the empty string ("") to not change the focus group, but
         **    still change to the attack behavior.
         **
         **    The current focus character will be un-set.
         **
         *b  Arguments:
         **
         *a    character_name - character to pursue
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int agent_pursue_character(const char* character_name);

        /*l
         *b  Description:
         **
         **    This function is similar to agent_pursue_character(), but the
         **    point toward the agent will move will be offset from the pursued
         **    character by the passed offset.
         */
        int agent_pursue_character_with_offset(const char* character_name,
                float offset_x,
                float offset_y);

        /*l
         *b  Description:
         **
         **    This function is similar to agent_pursue_character(), but instead
         **    will choose pursue characters from the characters in the specified
         **    group.
         **
         **    This function will implicitly put this agent into the pursue
         **    behavior.
         **
         **    The current focus group will be set to the specified group.  Pass
         **    NULL or the empty string ("") to not change the focus group, but
         **    still change to the pursue behavior.
         **
         **    The current focus character will be un-set.
         **
         *b  Arguments:
         **
         *a    group_name - name of group from which pursue characters should
         *a                 be chosen
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int agent_pursue_group(const char* group_name);

        /*l
         *b  Description:
         **
         **   Calls a formation with this character as a leader, oriented towards
         **   (target_x, target_y).
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int agent_call_formation(const char* formation_name,
                float target_x,
                float target_y);

        /*l
         *b  Description:
         **
         **    This function has the character travel along its behavior path
         **    shape, typically to the end and then back to the beginning.  It
         **    will put the agent into the travel behavior.
         **
         *b  Arguments:
         **
         *a    direction - should be either "forward" or "backward"; pass NULL
         *a                for default forward
         *a    at_end    - what to do when end of path reached
         *a    waypoint_index - index of waypoint to start at; -1 for nearest,
         *a                     -2 for random
         *a    offset_y  - sideways offset from behavior path
         **
         **    Valid values for at_end are:
         **
         *-    - "reverse"
         *-    - "loop"
         *-    - "stop"
         *-    - "teleport"
         **
         **    See the documentation for diguyNavPathAtEnd for information on
         **    what each value means.
         */
        int agent_travel_behavior_path(const char* direction = NULL,
                const char* at_end = NULL,
                int waypoint_index = -1,
                float offset_y = 0.5f);

        /*l
         *b  Description:
         **
         **    Similar to agent_travel_behavior_path(), but specific path can be
         **    set rather than using behavior path.
         */
        int agent_travel_path_shape(const char* path_shape_name,
                const char* direction = NULL,
                const char* at_end = NULL,
                int waypoint_index = -1,
                float offset_y = 0.5f);

        /*l
         *b  Description:
         **
         **    The agent will create a travel path around the border of the
         **    region specified.  A CALLBACK_ID_AGENT_TRAVEL_FORWARD_DEST_REACHED
         **    callback will be triggered every time a character completes a loop
         **    around the border.
         **
         *b  Arguments:
         **
         *a    region_name - the name of the region to patrol; leaving blank or
         *a                  passing NULL will use the agent's current region
         *a    subregion -   name of the subregion to use; defaults to the base
         *a                  subregion
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int agent_travel_region_border(const char* region_name = NULL,
                const char* subregion_name = "base");

        /*l
         *b  Description:
         **
         **    Agent will attempt to create a navigation path on the via_region
         **    and then travel it. An A* path planning algorithm is used to find
         **    the path, cost preferences from the character's current
         **    diguyAgentParams are used in the search.
         **
         *b    Note: as of DI-Guy 12 there is a version of this function
         **    agent_move_to_point_bg() that uses a multi-threaded infrastructure.
         **    We strongly recommend using it for future developments.
         **
         *b  Arguments:
         **
         *a    x, y, z        - the target location
         *a    via_region     - the name of the region to run A* on (pass in "*"
         *a                     to have the code attempt to find the nearest
         *a                     region automatically.)
         *a    subregion_name - the name of the subregion to restrict search to
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int agent_move_to_point(float x, float y, float z,
                const char* via_region = NULL,
                const char* subregion_name = "base");

        /*l
         *b  Description:
         **
         **   A multi-threaded version of agent_move_to_point().  See that
         **   function for more information.
         **
         **   We recommend switching to using this over the single threaded
         **   version.  When the path result has been computed a callback with id
         **   CALLBACK_ID_AGENT_PATH_PLAN_COMPLETED is triggered and the result is
         **   stored in get_path_planning_result().  You can also poll for
         **   completion via get_is_path_planning().
         **
         *b  Returns:
         **
         **    diguyNavPathSearchResults enum value
         **
         **    The return value is typically DIGUY_NAV_PATH_ERROR_NONE (0) on
         **    success, DIGUY_NAV_PATH_ERROR_SEARCH_QUEUED if this has been queued
         **    for multi-threading, or a negative value on failure.
         */
        int agent_move_to_point_bg(float x, float y, float z,
                const char* via_region = NULL,
                const char* subregion_name = "base");

        /*l
         *b  Description:
         **
         **    Agent will attempt to create a navigation path on the region
         **    via_region and then travel it.  An A* path planning algorithm is
         **    used to find the path.
         **
         **    The subregion masks are used to specify which subregions to use or
         **    avoid.  Cost bias values can be used to make tweak how strong the
         **    repulsion values are.
         **
         *b    Note:
         **
         **    As of DI-Guy 12 there is a version of this function
         **    agent_move_to_point_via_subregions_bg that uses a multi-threaded
         **    infrastructure.  We strongly recommend using it for future
         **    developments.
         **
         **    This function will fail and return -1 if a path cannot be found.
         **
         *b  Arguments:
         **
         *a    x, y, z        - the target location
         *a    via_region     - the name of the region to run A* on (pass in "*"
         *a                     to have the code attempt to find the nearest
         *a                     region automatically)
         *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  NOTE:
         **
         *b    THIS API has changed for DI-GUY 11.
         **
         **    cost_bias_for_preferred_regions has been added and the neutral and
         **    repulsed default values have changed.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int agent_move_to_point_via_subregions(float x, float y, float z,
                const char* via_region = NULL,
                int preferred_subregions_mask = DIGUY_SUBREGION_MASK_NONE,
                float cost_bias_for_preferred_regions = 0.25f,
                float cost_bias_for_neutral_regions = 1.1f,
                int repulsed_regions_mask = DIGUY_SUBREGION_MASK_NONE,
                float cost_bias_for_repulsed_regions = 10.0f,
                int cost_rule = 0);

        /*l
         *b  Description:
         **
         **   A multi-threaded version of agent_move_to_point_via_subregions().
         **   We recommend switching to using this over the single threaded
         **   version.  When the result is found a
         **   CALLBACK_ID_AGENT_PATH_PLAN_COMPLETED is triggered and the result is
         **   stored in get_path_planning_result(), you can also poll for
         **   completion via get_is_path_planning().
         **
         *b  Returns:
         **
         **    diguyNavPathSearchResults enum value
         **
         **    The return value is typically DIGUY_NAV_PATH_ERROR_NONE (0) on
         **    success, DIGUY_NAV_PATH_ERROR_SEARCH_QUEUED if this has been queued
         **    for multi-threading, or a negative value on failure.
         */
        int agent_move_to_point_via_subregions_bg(float x, float y, float z,
                const char* via_region = NULL,
                int preferred_subregions_mask = DIGUY_SUBREGION_MASK_NONE,
                float cost_bias_for_preferred_regions = 0.25f,
                float cost_bias_for_neutral_regions = 1.1f,
                int repulsed_regions_mask = DIGUY_SUBREGION_MASK_NONE,
                float cost_bias_for_repulsed_regions = 10.0f,
                int cost_rule = 0);

        /*l
         *b  Returns:
         **
         **    diguyNavPathSearchResults value after agent_move_to_point_bg()
         **    or agent_move_to_point_via_subregions_bg() has been called when
         **    the multi-threaded path planner has completed.
         */
        int get_path_planning_result();

        /*l
         *b  Returns:
         **
         **    1 if character is currently waiting for a result from the
         **    multi-threaded path planner, else 0
         */
        int get_is_path_planning();

        /*l
         *b  Description:
         **
         **    Agent will attempt to create a navigation path on the via_region
         **    to a point in the target region, and then travel it.  An A* path
         **    planning algorithm is used to find the path.  Cost preferences from
         **    the character's current diguyAgentParams are used in the search.
         **
         *b  Arguments:
         **
         *a    region         - target region
         *a    subregion_name - target subregion
         *a    via_region     - name of the region travel in
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int agent_move_to_region(const char* region,
                const char* subregion_name = "base",
                const char* via_region = NULL);

        /*l
         *b  Description:
         **
         **    Similar to agent_move_to_point_via_subregions(), but for moving to
         **    another region.
         **
         *b  NOTE:
         **
         *b    THIS API has changed for DI-GUY 11.
         **
         **    cost_bias_for_preferred_regions has been added and the neutral and
         **    repulsed default values have changed.
         **
         *b  See Also:
         **
         **    diguyScenario::set_max_distance_planning_multiplier();
         **    diguyScenario::get_time_spent_path_planning_this_frame();
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int agent_move_to_region_via_subregions(const char* region_name,
                const char* subregion_name = "base",
                const char* via_region = NULL,
                float cost_bias_for_preferred_regions = 0.25f,
                int preferred_subregions_mask = DIGUY_SUBREGION_MASK_NONE,
                float cost_bias_for_neutral_regions = 1.1f,
                int repulsed_regions_mask = DIGUY_SUBREGION_MASK_NONE,
                float cost_bias_for_repulsed_regions = 10.0f);

        /*l
         *b  Description:
         **
         **    The agent will begin following the specified path, using the path
         **    follow behavior (DIGUY_AGENT_BEHAVIOR_PATH_FOLLOW).
         **
         **    The path follow behavior allows an agent to approximately follow a
         **    diguyCharacterPath without being in path position mode.  The agent
         **    can respond to external stimuli (e.g., run away from gunfire), and
         **    later return to and resume the path.
         **
         **    Currently the path must be a path previously defined for the
         **    character, through either DI-Guy Scenario or via path API calls.
         **
         *b  Arguments:
         **
         *a    path_name - name of a path of this character
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int agent_path_follow(const char* path_name);

        /*l
         *b  Description:
         **
         **    The agent will resume following the path specified by a previous
         **    call to agent_path_follow().  This will put the agent back into
         **    the path follow behavior.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int agent_resume_path_follow();

        /*l
         *b  Returns:
         **
         **    the path being followed in path behavior mode
         */
        diguyCharacterPath* agent_get_path_follow_path();

        /*l
         *b  Description:
         **
         **    In path follow behavior the agent moves along the path specified
         **    in agent_path_follow().  How far along the agent is on the path is
         **    specified in seconds.  This function returns that time.
         **
         **    Note that advancing along the path may be paused for some reason,
         **    typically because the agent is resuming path follow behavior
         **    after being in a different behavior, or the agent is too far away
         **    from the current desired position on the path.  In this case the
         **    returned time may not advance for awhile until the agent is close
         **    enough to the path to resume advancing along it.
         **
         **    Call diguyAgentParams::set_path_follow_pause_t_when_off_path()
         **    to set whether time will be paused when off of the path.
         **
         **    Call diguyAgentParams::set_path_follow_unpause_t_at_radius() to
         **    set how close the agent must be to the last point on the path
         **    before time will resume.
         **
         *b  Returns:
         **
         **    how far, in seconds, the agent is along its path follow path
         */
        float agent_get_path_follow_path_t();

        /*l
         *b  Returns:
         **
         **    1 if time along the path is not advancing, else 0
         */
        int agent_get_path_follow_path_t_paused();

        /*l
         *b  Returns:
         **
         **    the crowd this agent is a part of, if any; returns NULL if not in
         **    a crowd
         */
        diguyCrowd* agent_get_crowd();

        /*l
         *b  Description:
         **
         **    This function allows the end user to directly change an agent's
         **    current behavior.  This function currently the only way to start
         **    an agent "idling".
         */
        int agent_begin_behavior(const char* behavior_name);

        /*l
         *b  Description:
         **
         **    This function sets the behavior of the agent to "none".
         */
        int agent_stop_behavior();

        /*l
         *b  Description:
         **
         **    This function is a convenience function that changes the focus
         **    character of this agent's current crowd params.
         **
         **    This can also be done by getting the character's current params
         **    using get_agent_current_params(), and then calling
         **    set_focus_character() on that object.  This function
         **    call, however, is available in decisions.
         **
         **    The agent currently need not be part of a crowd for this function
         **    to work.
         **
         *b  Arguments:
         **
         *a    character_name - name of character to become new focus
         *a                     character; pass NULL or "" to un-set
         *a                     the focus character
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int agent_set_current_focus_character(const char* character_name);

        /*l
         *b  Description:
         **
         **    This function returns the current character this agent
         **    is focused on.  This will either be the character named
         **    by the focus character, or the character chosen from the
         **    focus group to be the current focus character.
         **
         **    The agent currently need not be part of a crowd for this function
         **    to work.
         **
         *b  Returns:
         **
         *a    pointer to type diguyCharacter
         */
        diguyCharacter* agent_get_current_focus_character();

        /*l
         *b  Description:
         **
         **    Similar to set_current_focus_character(), but sets
         **    the current focus group instead of character.
         **
         **    The agent currently need not be part of a crowd for this function
         **    to work.
         **
         *b  Arguments:
         **
         *a    group_name - name of group to become new focus
         *a                 group; pass NULL or "" to un-set
         *a                 the focus group
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int agent_set_current_focus_group(const char* group_name);

        /*l
         *b  Description:
         **
         **    This function returns the initial agent parameters of
         **    this agent.  The initial parameters of this agent
         **    can then be edited through this object.
         **
         **    Changes to the initial parameters will have no effect until
         **    the scenario is reset.
         **
         **    The current agent parameters will be set to these
         **    initial parameters whenever the scenario is reset.
         **
         **    The agent currently need not be part of a crowd for this function
         **    to work.
         **
         *b  Returns:
         **
         *a    pointer to type diguyAgentParams
         */
        diguyAgentParams* agent_get_initial_params();

        /*l
         *b  Description:
         **
         **    This function returns the current agent parameters of
         **    this agent.  The current parameters of this agent
         **    can then be edited through this object.
         **
         **    Changes to the current parameters should take effect immediately.
         **
         **    The current agent parameters will be reset to the
         **    initial parameters whenever the scenario is reset.
         **
         **    The agent currently need not be part of a crowd for this function
         **    to work.
         **
         *b  Returns:
         **
         *a    pointer to type diguyAgentParams
         */
        diguyAgentParams* agent_get_current_params();

        /*l
         *b  Description:
         **
         **    This function gets the name of the agent's current profile.
         **
         *b  Returns:
         **
         **    the name of the agent's current profile
         */
        const char* agent_get_current_params_profile_name();

        /*l
         *b  Description:
         **
         **    This function sets this agent's current agent parameters from the
         **    specified crowd profile.
         **
         **    The agent currently need not be part of a crowd for this function
         **    to work.
         **
         *b  Arguments:
         **
         *a    profile_name         - name of existing crowd profile
         *a    retain_focus_objects - pass 1 to not change focus object from
         *a                           current focus
         *a    retain_navigation_values - pass 1 to not change current navigation
         *a                               parameters
         *a    retain_behavior      - pass 1 to not change current behavior
         **
         **    Navigation values are things like:
         **
         *-    - behavior path
         *-    - behavior region and subregion
         *-    - region masks
         *-    - cost biases
         *-    - path planner settings
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int agent_set_current_params_from_profile(const char* profile_name,
                int retain_focus_objects = 1,
                int retain_navigation_values = 1,
                int retain_behavior = 0);

        /*l
         *b  Description:
         **
         **    Similar to agent_set_current_params_from_profile(), but initial
         **    parameters are changed.
         */
        int agent_set_initial_params_from_profile(const char* profile_name);

        /*l
         *b  Description:
         **
         **    This function sets the current parameters from the agent's
         **    initial parameters.
         */
        void agent_set_current_params_from_initial_params();

        /*l
         *b  Description:
         **
         **    This function sets whether the borders of the current behavior
         **    region of the agent is solid.
         **
         **    If they are, the agent will treat the walls as if they are
         **    solid walls in the environment.  If not, the agent is free to
         **    walk through them.
         **
         **    The agent currently need not be part of a crowd for this function
         **    to work.
         **
         *b  Arguments:
         **
         *a    is_solid - 1 if region border should be solid, 0 if not
         **
         *b  Available as Decision Bead/Event
         */
        void agent_set_current_behavior_region_border_is_solid(int is_solid);

        /*l
         *b  Description:
         **
         **    If the agent is in a behavior that stays in one place before moving
         **    to another, such as wander or mingle, this function will request
         **    that the agent move on to the next location.
         **
         *b  Available as Decision Bead/Event
         */
        void agent_move_on();

        
        /*l
         *b  Description:
         **
         **    This function controls if the AI will attempt to automatically change variants
         **    depending on the behavior. This should only change how still motions are performed
         **    when the default variant is Normal. Characters in wander and idle will automatically
         **    shift to ambient still motions, mingle will alternate between socialize and ambient 
         **    motions. Attack should automatically switch from aiming to ambient.
         **    defaults to being on.
         */
        int agent_set_auto_variant_selection(int selection_enabled);

        /*l
         *b  Description:
         **
         **   Returns if automatic variant selection is enabled, defaults to being on.
         */
        int agent_get_auto_variant_selection();

        /*l
         *b  Description:
         **
         **   Returns current travel path or nav path.
         */
        diguyPathShape * agent_get_current_traveled_path();

        /*l
         *b  Description:
         **
         **   Allows agent to determine speed zone based on distance to endpoint of current
         **   path. With this off, speed zones are determined by "desired position", which
         **   when following a path is not the endpoint, but a point on the path a short
         **   distance ahead of the current position.
         **
         **   The default value is false.
         **
         **   Enable this if you want the character to automatically run when following a
         **   long path.
         */
        void agent_set_use_speed_zones_on_paths(int enabled);

        /*l
         *b  Description:
         **
         **   Returns the current value set by agent_set_use_speed_zones_on_paths().
         */
        int agent_get_use_speed_zones_on_paths();

#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    This function sets a feeler function that will be used by this
         **    character for environment collision detection.  The feeler will
         **    replace any existing feeler function (including the default
         **    function used in DI-Guy Scenario).
         **
         **    See the "User-Defined Feelers" information for more information.
         **
         *b  Arguments:
         **
         *a    feeler_function - pointer to user-defined feeler function
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int agent_set_feeler_function(diguyFeelerFunction* feeler_function);

        /*l
         *b  Returns:
         **
         **    current feeler function; see set_feeler_function()
         **
         *b  Callable From:
         **
         *-    - C++
         */
        diguyFeelerFunction* agent_get_feeler_function();

#endif


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Creates a Lua mind object based off of the contents of base_class.
         **
         *b  Arguments:
         **
         *a    base_class  - the class to use as the basis for the character's
         *a                  mind
         *a    init_arg1-2 - experimental optional arguments passed to the init
         *a                  function; your lua init function will need to take
         *a                  arguments
         **
         */
        int create_lua_mind(const char* base_class, const char* init_arg1 = NULL,
                const char* init_arg2 = NULL);

        /*l
         *b  Description:
         **
         **    Returns the name of the mind, e.g. "luaPedestrian". This is, in other
         **        words, the mind's base class
         */
        const char *get_mind_name();

        /*l
         *b  Description:
         **
         **    Agent characters with minds will typically have the mind be in
         **    some state, such as "patrolling", "fleeing", "mobbing", etc.  This
         **    function returns the name of that state.
         **
         **    Currently this is only applicable to characters with Lua minds.
         **
         *b  Returns:
         **
         **    the name of the agent's current mind state
         */
        const char* get_mind_current_state_name();

        /*l
         *b  Description:
         **
         **    This function causes callback functions with the callback id
         **    CALLBACK_ID_AGENT_MIND_CURRENT_STATE_CHANGED to be called.
         **    It's intended use is for mind implementations that need to
         **    signal that the mind's current state has changed.
         **
         **    Currently this is only applicable to characters with Lua minds.
         */
        void do_mind_current_state_changed_callback();

        /*l
         *b  Description:
         **
         **    How long until the character's main coroutine thread should be
         **    resumed.  This function is typically used by various luaCharacter
         **    sleep functions.
         **
         *b  Arguments:
         **
         *a    sleep_length - how long relative to the current time the character
         *a                   should sleep
         */
        int set_sleep_timer(float sleep_length);

        /*l
         *b  Returns:
         **
         **    How long until the character's main coroutine thread resumes,
         **    relative to the current time.
         */
        float get_sleep_timer();

        /*l
         *b  Description:
         **
         **    The frequency at which the luaCharacter's heartbeat function
         **    should run.  This defaults to once per second. The character
         **    must have a Lua function named heartbeat.
         **
         *b  Arguments:
         **
         *a    heartbeat_dt - frequency of heartbeat
         */
        int set_heartbeat_dt(float heartbeat_dt);

        /*l
         *b  Description:
         **
         **    This function allows the addition of additional heartbeat
         **    functions.
         **
         *b  Arguments:
         **
         *a    function_name - the name of the Lua function to treat as a
         *a                    heartbeat; the function_name should not include
         *a                    the name of the character object
         *a    heartbeat_dt  - frequency of heartbeat
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int add_secondary_heartbeat(const char* function_name,
                float heartbeat_dt);

        /*l
         *b  Description:
         **
         **    This function removes an added heartbeat function.
         **
         *b  Arguments:
         **
         *a    function_name - the name of the Lua function to treat as a
         *a                    heartbeat; the function_name should not include
         *a                    the name of the character object
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_secondary_heartbeat(const char* function_name);

        /*l
         *b  Description:
         **
         **    The frequency at which a luaCharacter's secondary heartbeat
         **    function should run.  The character must have a Lua function named
         **    function_name.
         **
         *b  Arguments:
         **
         *a    function_name - heartbeat function to adjust
         *a    heartbeat_dt  - frequency of heartbeat
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_secondary_heartbeat_dt(const char* function_name, float heartbeat_dt);

        /*l
         *b  Description:
         **
         **    This function creates a request that whenever the specified
         **    callback is triggered, the character is woken up with a message.
         **    The message will be of the form:
         *>
         *-    - message_type = "callback"
         *-    - message = the string representation of the callback
         *<
         **    A good example of the use for this is a flexible "move to"
         **    command:
         **
         *b   Lua Example:
         **
         *e    self.character:add_wakeup_callback(diguyCharacter_CALLBACK_ID_AGENT_TRAVEL_FORWARD_DEST_REACHED);
         *e    -- begin to move to a location
         *e    self.character:agent_move_to_region_via_subregions("navmesh", "green", "navmesh",
         *e       DIGUY_SUBREGION_MASK_BASE, 12);
         *e    -- sleep till arrived
         *e    self:sleep(100);
         *e    self.character:remove_wakeup_callback(diguyCharacter_CALLBACK_ID_AGENT_TRAVEL_FORWARD_DEST_REACHED);
         **
         **    Effectively the character will wake up either after 100 seconds or
         **    when they arrive at their desired destination.
         **
         *b  Arguments:
         **
         *a    callback - the callback id that should wake up the character
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int add_wakeup_callback(int callback);

        /*l
         *b  Description:
         **
         **   This function removes a request to trigger a message when a
         **   callback is triggered.
         **
         *b  Arguments:
         **
         *a    callback - callback id that should no longer wake up the
         *a               character
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_wakeup_callback(int callback);

        /*l
         *b  Description:
         **
         **   This function removes all requests to trigger a message when
         **   callbacks are triggered.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_all_wakeup_callbacks();

        /*l
         *b  Description:
         **
         **   This function check for a requests to trigger a message when
         **   a given callback is triggered.
         **
         *b  Returns:
         **
         **    0 on false, 1 on true
         */
        int has_wakeup_callback(int callback);

        /*l
         *b  Description:
         **
         **    This function wakes up a character and sends them a message.
         **    Currently this is only applicable to characters with Lua minds.
         **
         *b  Arguments:
         **
         *a    sender         - who is sending the message
         *a    message_type   - what type of message is being sent
         *a    message        - the message string
         *a    message_params - optional parameter string
         **
         *b  Returns:
         **
         **    number of times message was successfully parsed
         */
        int agent_accept_message(const char* sender,
                const char* message_type,
                const char* message,
                const char* message_params = NULL);

        /*l
         **
         *b  Description:
         **
         **    This function wakes up nearby characters and sends them a message.
         **    The sender of the message is implicitly set to the individual
         **    calling the broadcast function
         **
         **    Currently this is only applicable to characters with Lua minds.
         **
         *b  Arguments:
         **
         *a    radius         - how far to broadcast the message
         *a    message_type   - what type of message is being sent
         *a    message        - the message string
         *a    message_params - optional parameter string
         **
         *b  Returns:
         **
         **    number of times message was successfully parsed
         */
        int agent_broadcast_message(float radius,
                const char* message_type,
                const char* message,
                const char* message_params = NULL);

        /*l
         *b  Description:
         **
         **    This function wakes up nearby characters in the group specified
         **    and sends them a message. The sender of the message is implicitly
         **    set to the individual calling the broadcast function.
         **
         **    Currently this is only applicable to characters with Lua minds.
         **
         *b  Arguments:
         **
         *a    group_name     - group to broadcast message to
         *a    radius         - how far to broadcast the message
         *a    message_type   - what type of message is being sent
         *a    message        - the message string
         *a    message_params - optional parameter string
         **
         **
         *b  Returns:
         **
         **    number of times message was successfully parsed,
         **    -1 on failure
         */
        int agent_broadcast_message_to_group(const char* group_name,
                float radius,
                const char* message_type,
                const char* message,
                const char* message_params = NULL);

        /*l
         **
         *b  Returns:
         **
         **    name of character's lua mind object; typically this is the
         **    character's name with '-' replaced by '_'
         */
        const char* get_lua_object_name();

        /*l
         *b  Description:
         **
         **    Sets the specified field of the mind to the string field_value.
         */
        void set_mind_field_as_string(const char* field_name,
                const char* field_value);

        /*l
         *b  Description:
         **
         **    Queries the luaCharacter object for a specific field, and attempts
         **    to convert it into a string.  This works for strings and
         **    numbers.
         **
         **    This returned pointer will stay valid until the next time this
         **    function is called, so if the results need to be saved they must
         **    be copied.
         **
         *b  Returns:
         **
         **    field_name as string
         */
        const char* get_mind_field_as_string(const char* field_name,
                int warn_if_no_field = 1);

        /*l
         *b  Description:
         **
         **    Sets the specified field of the mind to the floating point
         **    number field_value.
         */
        void set_mind_field_as_float(const char* field_name, float field_value);

        /*l
         *b  Description:
         **
         **    Similar to get_mind_field_as_string(), but returns field as
         **    a float.
         **
         *b  Returns:
         **
         **    field_name as double
         */
        float get_mind_field_as_float(const char* field_name,
                int warn_if_no_field = 1,
                int* found_field = NULL);

        /*l
         *b  Description:
         **
         **    Sets the specified field of the mind to the integer number
         **    field_value.
         */
        void set_mind_field_as_int(const char* field_name, int field_value);

        /*l
         *b  Description:
         **
         **    Similar to get_mind_field_as_int(), but returns field as
         **    an integer.
         **
         *b  Returns:
         **
         **    field_name as int
         */
        int get_mind_field_as_int(const char* field_name,
                int warn_if_no_field = 1,
                int* found_field = NULL);

        /*l
         *b  Description:
         **
         **    Attempts to run a luaCharacter member function, and can optionally
         **    return the function's result.  Lua return values can be converted
         **    to strings and numbers -- other data types will cause an error.
         **
         **    This returned pointer will stay valid until the next time this
         **    function is called, so if the results need to be saved they must
         **    be copied.
         **
         *b    *Note:*  This function should be considered experimental, as the
         *b    API may change.
         **
         *b  Arguments:
         **
         *a    function_name     - luaCharacter function field to invoke
         *a    argument          - optional string argument to the function
         *a    has_return_string - 0 or 1; determines if lua interface should
         *a                        attempt to retrieve a string value
         **
         *b  Returns:
         **
         **    Lua function return value
         */
        const char* evaluate_mind_function(const char* function_name,
                const char* argument = NULL,
                int has_return_string = 0);

        /*l
         *b  Description:
         **
         **    This function produces a string with a long list of character
         **    information, including: current path, crowd, behavior, lua state,
         **    lua call stack, wakeup callbacks and lua object fields.  It is
         **    meant to help with debugging agents.
         **
         **    This returned pointer will stay valid until the next time this
         **    function is called, so if the results need to be saved they must
         **    be copied.
         **
         *b  Arguments:
         **
         *a    include_stack - pass 1 to include callstack info, 0 to not
         *a    include_locals - pass 1 to include local variable info, 0 to not
         **
         *b  Returns:
         **
         **    string containing character information
         */
        const char* get_ai_state_string(int include_stack = 1, int include_locals = 1);


/*****************************************************************************/
/*
 *3 Visibility Tests
 */

        /*l
         *b  Description:
         **
         **    This function tests whether this character can see the passed
         **    character.  Currently this tests if the cervical link of this
         **    character has a clear line of sight to either the cervical or the
         **    position links of the target. Currently the orientation of this
         **    character isn't factored in.
         **
         **    This function does not fail if other characters are between the
         **    two characters in question.
         **
         **    Checking visibility is only an option if an octtree is generated
         **    from scene objects; typically only DI-Guy Scenario does this.
         **    Outside of DI-Guy Scenario set_character_los_function() should be
         **    used if no octtree is present.
         **
         *b  Arguments:
         **
         *a    character      - character to check
         *a    los_check_type - currently unused but passed to callback function
         *a                     if end users wish to pass an additional parameter
         **
         *b  Returns:
         **
         **    1 if character is visible, 0 if not
         */
        int check_character_visibility(diguyCharacter* character,
                int los_check_type = 0);

        /*l
         *b  Description:
         **
         **    This function tests whether this character can see the x, y, z
         **    location specified.  Currently this tests if the cervical link of
         **    this character has a clear line of sight to the x, y, z location.
         **    Currently the orientation of this character isn't factored in.
         **
         **    This function does not fail if other characters are between the
         **    character and the location in question.
         **
         **    Checking visibility is only an option if an octtree is generated
         **    from scene objects; typically only DI-Guy Scenario does this.
         **
         *b  Arguments:
         **
         *a    x, y, z - location to check
         **
         *b  Returns:
         **
         **    1 if location is visible, 0 if not
         */
        int check_point_visibility(float x, float y, float z);



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

        /*l
         *b  Description:
         **
         **    When a character needs to check if it can see a location, DI-Guy
         **    calls this function with a pointer to the diguyCharacter in
         **    question, and the coordinates of the point that is being looked
         **    at.  This currently happens when an agent is told to move to a new
         **    region.
         **
         **    The following prototype should be used for the point line-of-sight
         **    function:
         **
         *e     int diguyPointLOSFunction(diguyCharacter* character,
         *e         float x,
         *e         float y,
         *e         float z);
         **
         **    The function should then check if the desired location is visible.
         **    This can be done in a number of ways; a typical approach is to do
         **    an intersection test with the static scene.
         **
         **    The function should return 1 if the path to the target is clear, 0
         **    if there is an obstruction.
         **
         **    A default point line-of-sight function can be set for all
         **    subsequently created characters by calling
         **    diguyScenario::set_default_point_los_function().
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int set_point_los_function(diguyPointLOSFunction* point_los_function);

        /*l
         *b  Returns:
         **
         **    current point line-of-sight function; see set_point_los_function()
         **
         *b  Callable From:
         **
         *-    - C++
         */
        diguyPointLOSFunction* get_point_los_function();

        /*l
         *b  Description:
         **
         **    When a character needs to check if it can see another character,
         **    DI-Guy calls this function with a pointer to the diguyCharacter in
         **    question.  This can happen when check_character_visibility() is
         **    invoked or when AI attack code assesses if it should take a shot.
         **
         **    The following prototype should be used for the character
         **    line-of-sight function:
         **
         *e    int diguyCharacterLOSFunction(diguyCharacter* character,
         *e        diguyCharacter* target_character,
         *e        int los_test_type) // (currently unused)
         **
         **    Currently the los_test_type argument defaults to 0 and is not used
         **    internally.  It is, however, available in
         **    check_character_visibility() and will be passed to the callback.
         **    This can be useful if the end user wants to write scripting code
         **    that has alternative Line of Sight tests depending on agent
         **    conditions. (e.g. a test that factors in the character's field of
         **    view.)
         **
         **    The function then checks if the target character is visible.  This
         **    can be done in a number of ways; a typical approach is to do an
         **    intersection test with the static scene.  The default
         **    implementation tests the path from the characters head to the
         **    target's head and then to the target's feet.
         **
         **    The function should return 1 if the path to the target is clear,
         **    and 0 if there is an obstruction.
         **
         **    A default character line-of-sight function can be set for all
         **    subsequently created characters by calling
         **    diguyScenario::set_default_character_los_function().
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int set_character_los_function(diguyCharacterLOSFunction* character_los_function);

        /*l
         *b  Returns:
         **
         **    current character line-of-sight function; see
         **    set_character_los_function()
         **
         *b  Callable From:
         **
         *-    - C++
         */
        diguyCharacterLOSFunction* get_character_los_function();

#endif


/*****************************************************************************/
        int get_num_ik_chains();

        const char * get_ik_chain_name_at_index(int index);

        /*b  Description: 
         **   Moves the end effector for the specified ik chain to a location in the world.
         **   
         *b  Arguments:
         *a    ik_chain_target - index of ik chain
         *a    x,y,z           - world location of where to move the IK end effector to.
         *a    ramp_time       - how long to take blending in solution
         **
         *b  Returns:
         **   -1 on failure, 0 on success
         */
        int set_ik_target_world(int ik_chain_target, float x, float y, float z, float ramp_time = .25f);
        
        /*b  Description: 
         **   Moves the end effector for the specified ik chain to a location relative to the character.
         **   
         *b  Arguments:
         *a    ik_chain_target - index of ik chain
         *a    x,y,z           - local location of where to move the IK end effector to.
         *a    ramp_time       - how long to take blending in solution
         **
         *b  Returns:
         **   -1 on failure, 0 on success
         */
        int set_ik_target_local(int ik_chain_target, float x, float y, float z, float ramp_time = .25f);
        
        /*b  Description: 
         **   Resets the end effector to be solely driven by the animation system */
        int disable_ik_target(int ik_chain_target, float ramp_time = .25f);

        /*b  Description: 
         **    Sets the distance to the primary camera, this should be automatically set in OpenGL
         **  or if you set the camera position, in retained mode renderers you will need to set this 
         **  manually. Currently only used by IK system for performance culling.
         */
        void set_distance_to_primary_camera(float camera_dist);
        
        float get_distance_to_primary_camera();

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets the initial character simulator this character
         **    will use.  The current simulator will be set to this value on
         **    scenario reset.
         **
         **    The current simulator can be set by calling
         **    set_current_character_simulator().
         **
         **    The default simulator is
         **    DIGUY_CHARACTER_SIMULATOR_DIGUY_MOTION_ENGINE.
         **
         **    Requires active physics module if character simulator is set to
         **    DIGUY_CHARACTER_SIMULATOR_PHYSICS_SIM_MODULE.
         **
         *b  Arguments:
         **
         *a    character_simulator - which simulator to use at reset
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_initial_character_simulator(diguyCharacterSimulator character_simulator);

        /*l
         *b  Returns:
         **
         **    initial character simulator
         */
        diguyCharacterSimulator get_initial_character_simulator();

        /*l
         *b  Description:
         **
         **    This function sets the current character simulator this character
         **    will use.  The current simulator will be reset to the initial
         **    character simulator on scenario reset.
         **
         **    The initial simulator can be set by calling
         **    set_initial_character_simulator().
         **
         *b  Arguments:
         **
         *a    character_simulator - new current character simulator
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_current_character_simulator(diguyCharacterSimulator character_simulator);

        /*l
         *b  Returns:
         **
         **    current character simulator
         */
        diguyCharacterSimulator get_current_character_simulator();

        /*l
         *b  Description:
         **
         **    This function sets the initial physics simulation mode this
         **    character will use.  The current simulation mode will be set to
         **    this value on scenario reset.
         **
         **    The current simulation mode can be set by calling
         **    set_current_physics_simulation_mode().
         **
         **    The default simulation mode is
         **    DIGUY_PHYSICS_SIMULATION_MODE_SIM_DRIVES_CHARACTER.
         **
         **    The physics simulation mode will have no effect unless the current
         **    character simulator is
         **    DIGUY_CHARACTER_SIMULATOR_PHYSICS_SIM_MODULE.
         **
         *b  Arguments:
         **
         *a    physics_simulation_mode - which simulation mode to use at reset
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_initial_physics_simulation_mode(diguyPhysicsSimulationMode physics_simulation_mode);

        /*l
         *b  Returns:
         **
         **    initial physics simulation mode
         */
        diguyPhysicsSimulationMode get_initial_physics_simulation_mode();

        /*l
         *b  Description:
         **
         **    This function sets the current physics simulation mode this
         **    character will use.  The current simulation mode will be reset to
         **    the initial physics simulator mode on scenario reset.
         **
         **    The initial simulation mode can be set by calling
         **    set_initial_physics_simulation_mode().
         **
         **    The physics simulation mode will have no effect unless the current
         **    character simulator is
         **    DIGUY_CHARACTER_SIMULATOR_PHYSICS_SIM_MODULE.
         **
         *b  Arguments:
         **
         *a    physics_simulation_mode - new current physics simulation mode
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_current_physics_simulation_mode(diguyPhysicsSimulationMode physics_simulation_mode);

        /*l
         *b  Returns:
         **
         **    initial physics simulation mode
         */
        diguyPhysicsSimulationMode get_current_physics_simulation_mode();

        /*l
         *b  Description:
         **
         **    This function sets the physics collision group this character will
         **    be in when being simulated.  For improved performance, collision
         **    detection between various characters and scene objects will not
         **    be performed, based on which collision groups the objects are in.
         **
         **    By default:
         **
         *-      - characters in character group n collide against props in prop
         *-        group n and scene objects in scene object group n
         *-        in group n
         *-      - characters in group ghost don't collide against any other
         *-        characters, but do against scene objects and props
         *-      - characters in group everything collide against all characters,
         *-        props, and scene objects
         *-      - all props collide against all other props and scene objects
         **
         **    Collision group relationships can be modified using
         **    diguyApp::set_collision_group_detection_flag().
         **
         *b  Arguments:
         **
         *a    physics_simulation_mode - new current physics simulation mode
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_physics_collision_group(diguyPhysicsCollisionGroup collision_group);

        /*l
         *b  Returns:
         **
         **    physics collision group
         */
        diguyPhysicsCollisionGroup get_physics_collision_group();

        /*l
         *b  Description:
         **
         **    This function sets a time at which active simulation of a physics
         **    controlled character will stop.  This is useful for:
         **
         *-    - reducing simulation processing overhead
         *-    - freezing a simulation that is mostly in steady state, but some
         *-      small part remains oscillating
         **
         **    The physics controlled character will remain frozen in the last
         **    computed simulated pose.
         **
         *b  Arguments:
         **
         *a    t - scenario t at which simulation will freeze
         **
         **    t should be large enough for the simulation to reach a reasonably
         **    steady state, such as a human lying on the ground.  A value that
         **    is usually reasonable is around 5 seconds.
         */
        void set_stop_physics_sim_at_t(float t);

        /*l
         *b  Description:
         **
         **    Similar to set_stop_physics_sim_at_t(), but the passed time will
         **    be relative to the current simulation time as returned by
         **    diguyScenario::get_t().
         */
        void set_stop_physics_sim_in_t_seconds(float relative_t);

        /*l
         *b  Returns:
         **
         **    time at which physics simulation will freeze
         */
        float get_stop_physics_sim_at_t();

        /*l
         *b  Description:
         **
         **    This function applied an impulse force to the character.  An
         **    impulse is a force that is applied all at one time, such as an
         **    explosion shock wave.
         **
         *b  Arguments:
         **
         *a    link                    - link to which impulse should be applied
         *a    impulse_magnitude_[xyz] - magnitude of impulse in x direction
         *a    link_offset_[xyz]       - offset on link at which to apply impulse
         *a    set_simulation_drives_character - pass 1 to automatically change
         *a                              the character's current simulation mode
         *a                              to DIGUY_PHYSICS_SIMULATION_MODE_SIM_DRIVES_CHARACTER
         */
        void apply_impulse_to_physics_sim(const char* link,
                float impulse_magnitude_x,
                float impulse_magnitude_y,
                float impulse_magnitude_z,
                float link_offset_x = 0.0f,
                float link_offset_y = 0.0f,
                float link_offset_z = 0.0f,
                int set_simulation_drives_character = 1);

        /*l
         *b  Description:
         **
         **    Similar to apply_impulse_to_physics_sim(), but impulse can be
         **    calculated relative to a world position.  This is useful if, for
         **    example, a character should react to a nearby explosion.
         **
         *b  Arguments:
         **
         *a    link                    - link to which impulse should be applied
         *a    impulse_magnitude_[xyz] - magnitude of impulse
         *a    impulse_generator_position_[xyz] - world coordinates of impulse
         *a                              generating object
         *a    max_distance            - maximum distance from above position at
         *a                              which the impulse can affect this
         *a                              character
         *a    impulse_rolloff         - how much the impulse magnitude should
         *a                              decrease as distance from impulse source
         *a                              increases
         *a    link_offset_[xyz]       - offset on link at which to apply impulse
         *a    set_simulation_drives_character - pass 1 to automatically change
         *a                              the character's current simulation mode
         *a                              to DIGUY_PHYSICS_SIMULATION_MODE_SIM_DRIVES_CHARACTER
         */
        void apply_impulse_to_physics_sim_from_world_position(const char* link,
                float impulse_magnitude_x,
                float impulse_magnitude_y,
                float impulse_magnitude_z,
                float impulse_generator_position_x,
                float impulse_generator_position_y,
                float impulse_generator_position_z,
                float max_distance = 20.0f,
                float impulse_rolloff = 0.0f,
                float link_offset_x = 0.0f,
                float link_offset_y = 0.0f,
                float link_offset_z = 0.0f,
                int set_simulation_drives_character = 1);

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Sets texture load behavior to DIGUY_LOAD_INSTANTLY, DIGUY_LOAD_PRIORITY_ASYNC, or
         **  DIGUY_LOAD_ASYNC
         */
        static int set_texture_load_behavior(diguyGraphicsTextureLoadingBehavior mode);

        /*l
         *b  Returns current behavior, as set in set_texture_load_behavior()
         */
        static diguyGraphicsTextureLoadingBehavior get_texture_load_behavior();

        /*l
         *b  Description:
         **
         **    Sets maximum quality of shader to use (actual quality varies
         **   by distance from camera). See diguyGraphicsShaderQualityLevel for 
         **   possible values. 
         **
         *b  Arguments:
         **
         *a    quality_level        - a value between DIGUY_GRAPHICS_SHADER_QUALITY_UNLIT 
         *-                           and DIGUY_GRAPHICS_SHADER_QUALITY_MAX
         */
        static int set_max_shader_quality_level(int quality_level);

        /*l
         *b  Returns:
         **
         **    max shader quality level, as set by set_max_shader_quality_level()
         */
        static int get_max_shader_quality_level();



/****************************************************************************/
/****************************************************************************/
        /*l
         *b  Description:
         *   Documentation Pending
         */
        int set_animation_events_enabled(int enable);
        int get_animation_events_enabled();

        int get_has_bump_maps();

        /*l
         *b  Description:
         **
         **    This function returns how many channels the specified action has.
         **    If an action has more than one channel, the relative weights of
         **    its channels can be set using the set_action_channel_weight()
         **    function.
         **
         *b  Arguments:
         **
         *a    action_name - name of action to be queried
         **
         *b  Returns:
         **
         **    number of channels in specified action
         */
        int get_action_num_channels(const char* action_name);

        /*l
         *b  Description:
         **
         **    This function sets the weight one channel of a multi-channel
         **    action.
         **
         **    The passed weight should be between 0 and 1.  The weights of
         **    the other channels in the action will be adjusted so that the
         **    total weight of all channels is 1.
         **
         *b  Arguments:
         **
         *a    action_name - name of action to be affected
         *a    channel     - which channel's weight to set
         *a    weight      - weight of the channel, between 0 and 1
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_action_channel_weight(const char* action_name,
                char channel,
                float weight);

        /*l
         *b  Description:
         **
         **    This function returns the weight of one channel of a multi-channel
         **    action.
         **
         *b  Arguments:
         **
         *a    action_name - name of action to be queried
         *a    channel     - which channel's weight to return
         **
         *b  Returns:
         **
         **    weight of a channel
         */
        float get_action_channel_weight(const char* action_name,
                char channel);

        /*l
         *b  Description:
         **
         **    This function returns the number of seconds before the transition
         **    to the desired action begins.  If the character is already
         **    performing the desired action the function returns 0.
         **
         *b    THIS FUNCTION DOES NOT YET RETURN VALID RESULTS.
         **
         *b  Returns:
         **
         **    time to reach desired action, in seconds
         */
        float get_time_to_reach_desired_action();

        /*l
         *b  Description:
         **
         **     Maps a character type map field to its value. See diguyCharacterTypeMap.
         **
         **  Returns:
         **
         **     The value, as a string.
         */
        const char* get_type_map_field(diguyCharacterTypeMapField field);

        /*l
         *b  Description:
         **
         **     Maps a character type map field to its value, using a string version (e.g.
         **     "age") of the field name. See diguyCharacterTypeMap.
         **
         **  Returns:
         **
         **     The value, as a string.
         */
        const char* get_type_map_field_using_string(const char* field);

        /*l
         *b  Description:
         **
         **    This function performs a "micro merge", allowing a diguyCharacter
         **    to have objects added to it by parsing a .dss file fragment in the
         **    form of a string.
         **
         **    This function can be used, for example, to add paths to
         **    dynamically created agents.  A Lua Package can contain a number of
         **    text strings representing local paths for agents.  On character
         **    creation these strings can be merged in and turned into
         **    per-character objects.
         **
         **    The DI-Guy Scenario path page has a "Display Asset" button for
         **    generating merge_object() compatible strings.
         **
         **    There is also a diguyScenario::merge_object() function that allows
         **    the merging of text blocks that represent sounds and particle
         **    systems.
         **
         **    Note: the parser is very sensitive to tabs and formatting!
         */
        int merge_object(const char* object);

        /*l
         *b  Description:
         **
         **    Returns 1 if any active character in the named group is visible,
         **    otherwise 0. 
         **
         *b  Arguments:
         **
         *a    group_name
         *a    max_distance_to_check
         */
        int is_active_character_in_group_visible(const char* group_name,
                float max_distance_to_check = 100000.0f);

        /*l
         *b  Description:
         **
         **    Gets local space bounding box, this function is currently expensive
         **    and should be used with care.
         **
         *b  Arguments:
         **
         *a    x1,y1,z1,x2,y2,z2 - output parameters
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **    (float * arguments converted to return values in Lua)
         */
        int get_local_space_bounding_box(float* x1, float* y1, float* z1,
                float* x2, float* y2, float* z2);

        /*l
         *b  Description:
         **
         **    This causes a character's mind to get an update call even if time
         **    isn't passing in the scenario.  This is occasionally useful for
         **    characters that are managing the UI.
         **
         **    Note that there is now a luaUIStateMachine that might be a better
         **    solution.
         */
        void set_mind_always_updates(int force_update);

        int get_mind_always_updates();

        /*l
         **  Returns angle in degrees from character's "forward facing" vector
         **  to the specified action bead, on the specified path
         */
        float get_angle_to_path(const char* path_name,
                const char* action_bead_name = NULL);


        /*
         *  DI-Guy doesn't use these masks internally, but they can be useful
         *   for some DI-Guy Graphics API scene graph implementations.
         */
        void set_scene_graph_mask(unsigned int mask);
        unsigned int get_scene_graph_mask();

        /*l
         *b  Description:
         **
         **    Turns on texture modulation system that tries to make all characters look 
         **    unique. Only supported by some appearances currently.
         */
        int set_use_texture_variations(int value);

        /*l
         *b  Returns:
         **    If texture variations have been enabled for this character. Note: some 
         **    characters now have texture variation 
         */
        int get_use_texture_variations();

        
        diguyMotionEngineSnapshot get_motion_engine_snapshot();
        
        int apply_motion_engine_snapshot(const diguyMotionEngineSnapshot & action_info);


        
        int set_local_to_world_orientation_matrix( float rz, float rx, float ry);
        int set_local_to_world_orientation_matrix( 
                float a0, float a1, float a2, 
                float b0, float b1, float b2,
                float c0, float c1, float c2, int transpose = 0);

        int set_final_position_double(double x, double y, double z);
        int set_final_matrix(
                float a0, float a1, float a2, float a3,
                float b0, float b1, float b2, float b3,
                float c0, float c1, float c2, float c3,
                float d0, float d1, float d2, float d3);

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

        // Deprecated as of 13.0;               
        // Aim code has been robustified these shouldn't be needed anymore
        int aim_converge(int max_iterations = 30);

        void set_aim_algorithm(int aim_algorithm);

        int get_aim_algorithm();

        // Deprecated as of 9.1.3; use diguyCharacter::get_position_link() instead.
        // diguyGraphicsLink* get_base_link();

        // Deprecated as of 9.0.1; use set_apply_actor_scale_to_action_bead_travel() instead.
        // void set_apply_actor_scale_to_action_bead_xy_travel(int apply_scale_flag);

        // Deprecated as of 9.0.1; use get_apply_actor_scale_to_action_bead_travel() instead.
        // int get_apply_actor_scale_to_action_bead_xy_travel();

        /*l
         **    Deprecated as of 9.1.4.  In general setting the weapon sound
         **    should no longer be necessary, as weapon sounds are now specified
         **    by the weapon's munition type.  If this function is called, it
         **    will have the same effect as calling
         **    diguyCharacter::set_weapon_sound_override().
         */
         // int set_default_weapon_sound(const char* sound_name);

         // Deprecated as of 9.1.4.  See comments for set_default_weapon_sound().
         //const char* get_default_weapon_sound();

         // Deprecated as of 9.1.4.  See comments for set_default_weapon_sound().
         // int set_default_weapon_sound_gain(float gain);

         // Deprecated as of 9.1.4.  See comments for set_default_weapon_sound().
         // float get_default_weapon_sound_gain();

         // Deprecated as of 9.1.4.  Call set_weapon_munition_type_override() instead.
         // int set_weapon_munition_type(const char* munition_type);

         // Deprecated as of 9.1.4.  Call get_weapon_munition_type_override() instead.
         // const char* get_weapon_munition_type();

         // Deprecated as of 10.5.2.  Call set_weapon_max_azimuth_error() instead.
         // int set_weapon_horizontal_error(float h_error);

         // Deprecated as of 10.5.2.  Call get_weapon_max_azimuth_error() instead.
         // float get_weapon_horizontal_error();

         // Deprecated as of 10.5.2.  Call set_weapon_max_elevation_error() instead.
         // int set_weapon_vertical_error(float v_error);

         // Deprecated as of 10.5.2.  Call get_weapon_max_elevation_error() instead.
         // float get_weapon_vertical_error();

         //    Added as of 10.1.6.  Invokes the old implementation of
         //    begin_appearance_effect().
        //int begin_legacy_appearance_effect(const char* effect,
        //      const char* override_link = "",
        //      float override_scale = DIGUY_DEFAULT_FLOAT,
        //      float override_offset_x = DIGUY_DEFAULT_FLOAT,
        //      float override_offset_y = DIGUY_DEFAULT_FLOAT,
        //      float override_offset_z = DIGUY_DEFAULT_FLOAT);

        
         //    Added as of 10.1.6.  Invokes the old implementation of
         //    end_appearance_effect().
         //
        //int end_legacy_appearance_effect(const char* effect);

         //    Added as of 10.1.6.  Invokes the old implementation of
         //    appearance_effect_is_active().
        //int legacy_appearance_effect_is_active(const char* effect);

        // Deprecated as of 10.1.8.  Use set_render_mode_shader() instead.
        //int set_shader_program(const char* shader_name);

        // Deprecated as of 10.5.2.  Use get_render_mode_shader() instead.
        //const char* get_recommended_appearance_shader_program_name();

        // Deprecated as of 10.5.1.  Use merge_object() instead.
        //int merge_asset(const char* asset);

        // Deprecated as of 10.5.2.  Use get_DIS_trailing_effect_state() instead.
        // void set_DIS_smoke_trail_state(int state);

        // Deprecated as of 10.5.2.  Use get_DIS_trailing_effect_state() instead.
        // int get_DIS_smoke_trail_state();

        /*l
         **    Deprecated as of 12.0.0.  Not supported in FaceFX.
         */
        int speak(const char* string);

        /*l
         **    Deprecated as of 12.0.0.  Not supported in FaceFX.
         */
        int set_viseme(const char* viseme_name, float weight);

        /*l
         **    Deprecated as of 12.0.0.  Not supported in FaceFX.
         */
        float get_viseme(const char* viseme_name);

        /*l
         **    Deprecated as of 12.0.0.  Not supported in FaceFX.
         */
        int set_orientation_eye_left(float azimuth, float elevation);

        /*l
         **    Deprecated as of 12.0.0.  Not supported in FaceFX.
         */
        int set_orientation_eye_right(float azimuth, float elevation);

        /*l
         **    Deprecated as of 12.0.0.  Not supported in FaceFX.
         */
        float get_azimuth_eye_left();

        /*l
         **    Deprecated as of 12.0.0.  Not supported in FaceFX.
         */
        float get_elevation_eye_left();

        /*l
         *b  Returns:
         **
         **    the current azimuth of the right eye; see set_orientation_eyes()
         */
        float get_azimuth_eye_right();

        /*l
         *b  Returns:
         **
         **    the current elevation of the right eye; see set_orientation_eyes()
         */
        float get_elevation_eye_right();

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

#ifdef CPLUSPLUS_ONLY

        bdiScenarioCharacter* get_scripted_object(); 
private:

        /*l
         **    A private constructor.
         */
        diguyCharacter(bdiScenarioCharacter* character);

        /*l
         **    A private destructor.
         */
        ~diguyCharacter();

        /*l
         **    A pointer to internal data.
         */
        bdiScenarioCharacter* m_scripted_object;

        friend class bdiPublishedCharacter;
        friend class bdiScenarioCharacter;
        friend class diguySensorRegion;
        friend class diguyScenario;

#endif

};


#endif /* __diguyCharacter_H */