diguyCharacter.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2014 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 <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;

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

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

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

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

        /*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 of 'z' or 'n' or even
         **    sometimes 'd' (as set by the set_up_vector() call) the rx and ry
         **    values will not have any effect.  To be able to set rx and ry
         **    values, set the up vector 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, and the up vector
         **    that will be set when the character is reset.  To change only the
         **    current up vector (a temporary change that goes away on reset),
         **    call set_up_vector()).
         **
         *b  Arguments:
         **
         *a    axis - the up vector the character should use; legal
         *a           values shown below:
         **
         *-     - 'd' - use default settings; character will change
         *-             up vector 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 of 'z' effectively zeroes out the rx and ry
         **    values of the character's orientation.
         **
         **    Having an up vector 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 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(char axis);

        /*l
         *b  Returns:
         **
         **    current up vector; see set_initial_up_vector()
         */
        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.  To change the
         **    up vector that will be used when the character is reset, call
         **    set_initial_up_vector().
         **
         *b  Arguments:
         **
         *a    axis - the up vector the character should use; see
         *a           set_initial_up_vector() for description
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Available as Decision Bead/Event
         */
        int set_up_vector(char axis);

        /*l
         *b  Returns:
         **
         **    current up vector; see set_up_vector()
         */
        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 of 'z' or 'n' or even
         **    sometimes 'd' (as set by the set_up_vector() call) this function
         **    will not have any effect.  To be able to set rx and ry values,
         **    set the up vector 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; links are named after their inbound
         *a                 joint name
         *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(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; links are named after their inbound
         *a                 joint name
         *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_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
         *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
         *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.
         **
         *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);

        /*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().
         **
         *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().
         **
         *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.
         **
         *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_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_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_CURRENT_TOUT_REACHED,
                CALLBACK_ID_POST_CREATE_GEOMETRY,
                CALLBACK_ID_PRE_DESTROY_GEOMETRY,
                CALLBACK_ID_END_OF_PATH_REACHED,

                // 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,

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


/*****************************************************************************/
#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.
         **
         **    A default altitude function that should be set for all
         **    characters can be set by calling
         **    diguyScenario::set_default_character_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
         *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();

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

/*****************************************************************************/
        /*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:
         **
         **    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.
         **    It's still up to the end user to change the appearance based on
         **    this information.
         **
         *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.
         **    Note that it's still up to the end user to change the
         **    character appearance based on this information.
         **
         *b  Returns:
         **
         *a    one of the values shown in set_DIS_damage_state()
         */
        int get_DIS_damage_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();

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


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

#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:
         **
         **    Get a spherical area containing geometry with specified tag,
         **   in specified world space.
         **
         *b  Arguments:
         **
         *a    tag             - the tag
         *a    world_space     - the world space
         *a    x1,y1,z1,radius - output parameters returning sphere definition
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **    (float * arguments converted to return values in Lua)
         */
        int get_geometry_tag(int tag,
                int world_space,
                float* x1, float* y1, float* z1, float* radius);

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


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

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



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

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

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

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

        /*l
         **    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() {return m_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 */