diguyCharacter.h

Go to the documentation of this file.

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

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

#pragma once

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

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

class bdiScenarioCharacter;
class diguyAgentParams;
class diguyChainSimulation;
class diguyCharacter;
class diguyCharacterGesture;
class diguyCharacterGroup;
class diguyCharacterGuide;
class diguyCharacterPath;
class diguyCharacterPathAimBead;
class diguyCharacterPathDecisionBead;
class diguyCharacterPathGazeBead;
class diguyCharacterPathScriptBead;
class diguyCrowd;
class diguyGraphicsLink;
class diguyGraphicsShaderInstance;
class diguyGraphicsShaderProgram;
class diguyImpact;
class diguyLinkController;
class diguyPatchIdentifier;
class diguyPathShape;
class diguyScenario;
class diguySoundInstance;
class diguyVariable;
class diguyVehicleController;
class diguyView;
class diguyViewLabel;
class diguyWaypoint;

struct diguyActionParameters;
struct diguyMotionEngineSnapshot;

enum diguyConnectionPointType;

class DtEntityStateRepository;

#endif


class BDI_DECLSPEC_diguy diguyCharacter
{

public:

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

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

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

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

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

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

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

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

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

   diguyCharacterClass get_character_class_type();

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

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

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

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

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

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

   int get_invisible_flag();

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

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

   int get_was_drawn_last_frame();

   int set_was_drawn_last_frame( int drawn );

   int get_is_culled();

   int set_is_culled(int culled);

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

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

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

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

   /*l
    *b  Description:
    **
    **    This function sets the initial tin ("T In") time of the character.
    **    See set_current_tin() for a discussion of how tin and tout times
    **    affect the character.
    **
    **    When the scenario is reset or loaded from a .dss file, the current
    **    tin value will be set to this initial tin value.
    **
    **    Note that if the scenario is running (diguyScenario::get_t() returns > 0),
    **    tin can be set only if override_time_warning is set.
    **
    **    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
    *a    override_time_warning - if set, initial_tin can be set at any time
    **
    *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();

   float get_char_time();

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   float get_character_local_time();

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

   /*l
    *b  Description:
    **
    **    This function sets the desired action of the character. This function replaces
    **    the legacy set_desired_action(const char*,float,int), function. All arguments
    **    to the legacy function can be specified using the action parameters.
    **
    **    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 the character
    *a    action_parameters - parameters for setting the action (eg. speeds, path mode retention)
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int set_desired_action( const char* action_name, const diguyActionParameters& action_parameters );

   const char* get_desired_action();

   int get_desired_action_index();

   const char* get_current_action();

   int get_current_action_index();

   diguyMotionDirection get_desired_action_direction();

   diguyMotionDirection get_current_action_direction();

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

   /*l
    *b  Description:
    **
    **    This function forces the current action of the character to be the
    **    action identified by action_name.
    **
    **    See set_desired_action() for a discussion of the effects on
    **    position mode.
    **
    **    This function will have no effect on a dead character (see
    **    die_now() and get_dead()).
    **
    **    By passing a value greater than 0 for t_offset_into_new_action,
    **    the character can be made to begin the action partway in.  This is
    **    useful when forcing actions for a lot of characters at the same
    **    time; without the offset, the characters would move in lockstep. In
    **    general, the offset shouldn't be more than half the blend interval.
    **
    **    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 is similar to force_action(), but allows the
    **    specification of an offset to apply to the character's position.
    **
    *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    x, y, z - Offset to apply to character's position when transitioning
    *a               to given action.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    */
   int force_action_with_offset( 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,
      float x = 0, float y = 0, float z = 0 );

   /*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 forces the current action of the character to be the
    **    action identified by action_name. This function replaces the legacy
    **    force_action, force_action_with_offset, and force_action_with_duration
    **    functions, which each make use of different subsets of the action parameters.
    **
    **    This function will have no effect on a dead character (see
    **    die_now() and get_dead()).
    **
    **    See set_desired_action() for a discussion of the effects on
    **    position mode.
    **
    *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 the character
    *a    action_parameters   - parameters for setting the action (eg. speeds, offset, path)
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int force_action( const char* action_name, const diguyActionParameters& action_parameters );

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

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

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


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

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

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

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

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

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

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

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

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

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

   float get_animation_target_el();

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

   float get_animation_target_az();

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

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

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

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

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

   float get_animation_angular_velocity();


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   void get_acceleration(float* accel_x, float* accel_y, float* accel_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
    **    Used by the Drift and Adaptive guide -- see diguyCharacterGuide.
    **
    **    The guide attempts to rotate the character at the desired angular
    **    velocity.
    */
   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
    **    by 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);

   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 head appearance of this character.
    **    This will persist past reseting the scenario, see set_appearance()
    **    for conceptual similarities.
    **
    *b  Arguments:
    **
    *a    head_appearance - name of the new desired head appearance
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int set_head_appearance(const char* head_appearance);

   /*l
    *b  Description:
    **
    **    This function sets the current head appearance of this character.
    **    On failure head appearance will be set to "default". see set_head_appearance()
    **    for more details
    **
    *b  Available as Decision Bead/Event
    */
   int set_current_head_appearance(const char* head_appearance);

   const char* get_current_head_appearance();

   int get_num_compatible_head_appearances();

   const char* get_compatible_head_appearance_at_index(int index);

   int get_num_compatible_facefx_head_appearances();

   const char* get_compatible_facefx_head_appearance_at_index(int index);


   /*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 both the 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  Returns:
    **
    **    generic catagory of the hand item appearance.
    */
   const char* get_current_hand_item_type();

   const char* get_actor();

   int add_equipment_appearance( const char* equipment_appearance );

   int reset_equipment_appearance( const char* class_type );

   int reset_equipment_appearance();

   int get_num_equipment();

   const char* get_equipment_name_at_index( int index );

   const char* get_equipment_type_at_index( int index );

   int get_equipment_index_at_index( int index );

   int add_equipment_by_index( int index );

   /*l
    *b  Description:
    **
    **    Turns on texture modulation system that tries to make all characters look
    **    unique. Only supported by some appearances. See diguyGraphicsShape Texture Variation API
    **    for fine grained control of this feature
    */
   int set_use_texture_variations(int value);

   /*l
    *b  Returns:
    **    If texture variations have been enabled for this character. Note: only some
    **    appearances support this feature
    */
   int get_use_texture_variations();

   void set_texture_variation_seed(float seed);

   int get_supports_texture_variations();

   int get_supports_weight_variations();

   void set_weight_scale( float weight );

   float get_weight_scale();

   int set_blend_shape_weight(const char * name, float weight);


   bool set_unit_patch_by_name( const char* name, bool set_personal_patch = false );
   const char* get_unit_patch_name() const;

   bool set_personal_unit_patch_by_name( const char* name );
   const char* get_personal_unit_patch_name() const;



   bool set_unit_patch( const diguyPatchIdentifier& patch_id, bool set_personal_patch = false );
   const diguyPatchIdentifier& get_unit_patch() const;

   bool set_personal_unit_patch( const diguyPatchIdentifier& patch_id );
   const diguyPatchIdentifier& get_personal_unit_patch() const;



   bool set_rank_patch_by_name( const char* name );
   const char* get_rank_patch_name() const;



   bool set_rank_patch( const diguyPatchIdentifier& patch_id );
   const diguyPatchIdentifier& get_rank_patch() const;



   bool set_uniform_label_text( const char* name );
   const char* get_uniform_label_text() const;


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

   /*l
    *b  Returns:
    **
    **    The name of the supplementary appearance (body, head, expressive head, hand item) or NULL
    **
    *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
    **
    */
   const char* get_appearance_name_at_index(diguyCharacterAppearanceTypes appearance_type, int index);

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

#ifdef CPLUSPLUS_ONLY
   float* get_lod_ranges();

#endif

   int get_num_lods();

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

   int get_graphics_lod();

   float get_graphics_lod_fraction();

   int set_allow_instancing(int value);

   int get_allow_instancing() const;

   int get_is_instanced() const;

   // informs the internals that this character wasn't instanced, can cause an update if set_is_culled(0) is called
   void set_is_instanced(int val);

   int can_lod_be_instanced(int lod);

   /*l
    *b  Description:
    **
    **    For scene graph renderers it can be necessary to patch the texture buffer object after
    **    the scene graph finishes updating various post processes (ground clamping for instance),
    **    or modifying the TBO with a local space camera.
    **
    **    This function allows the end user to pre-multiply the matrix in the TBO for each shape
    **    the character has. It requires diguyScenario::set_use_user_position_matrices() is called
    **    so that DI-Guy knows to keep track of TBO shape index data.
    */
   int set_final_tbo_position_matrix(int include_local_to_global_transform,
      float a0, float a1, float a2, float a3,
      float b0, float b1, float b2, float b3,
      float c0, float c1, float c2, float c3);

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

   int get_has_bump_maps();

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

   void get_load_manager_current_update_rates(float & zone, int & pose_update_rate,
      int & position_update_rate, int & alt_update_rate);

/*****************************************************************************/
   /*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_ARC_CHANGED
    **
    **      This callback will be called whenever the character's current
    **      motion arc changes, typically after a call to set_desired_action()
    **      or force_action(), or when transitioning to the next motion arc.
    **
    *i    CALLBACK_ID_CURRENT_ACTION_CHANGED
    **
    **      This callback will be called whenever the character's current
    **      action changes, typically after a call to set_desired_action()
    **      or force_action().
    **
    *i    CALLBACK_ID_DESIRED_ACTION_CHANGED
    **
    **      This callback will be called whenever the character's desired
    **      action changes, typically after a call to set_desired_action().
    **
    *i    CALLBACK_ID_DESIRED_ACTION_REACHED
    **
    **      This callback will be called when the character reaches its
    **      desired action as set by a call to set_desired_action().
    **
    *i    CALLBACK_ID_MANUALLY_INVOKED
    **
    **      This callback id will be supplied to event handlers invoked by a
    **      call to manually_invoke_event_handler().
    **
    *i    CALLBACK_ID_USER_SELECTED
    **
    **      This callback will be called when the character is selected in DI-Guy Scenario.
    **
    *i    CALLBACK_ID_USER_UNSELECTED
    **
    **      This callback will be called on a currently selected character when a different
    **      character is selected in DI-Guy Scenario.
    **
    *i    CALLBACK_ID_IGUY_INTERACT
    **
    **      This callback will be called when the character has been clicked
    **      on while DI-Guy Scenario is in I-Guy Input Mode.  Note that this
    **      is called on the character clicked, not the I-Guy character.
    **
    *i    CALLBACK_ID_IGUY_INTERACT_WITH_SUBJECT
    **
    **      This callback will be called when the character, as the I-Guy
    **      character, has clicked another character in I-Guy Input Mode.
    **      Note that this is called for the I-Guy character, not the
    **      clicked character.
    **
    *i    CALLBACK_ID_GUIDE_POSITION_ACQUIRED
    **
    **      This callback will be called when the character has reached its
    **      desired position as set by set_desired_position(). The
    **      diguyCharacterGuide is responsible for moving the character towards
    **      this position.
    **
    *i    CALLBACK_ID_GUIDE_POSITION_UNACQUIRED
    **
    **      This callback will be called if the character moves too far away
    **      from its desired position after it has been previously reached.
    **
    *i    CALLBACK_ID_GUIDE_ORIENTATION_ACQUIRED
    **
    **      This callback will be called when the character has reached its
    **      desired orientation as set by set_desired_orientation(). The
    **      diguyCharacterGuide is responsible for moving the character towards
    **      this orientation.
    **
    *i    CALLBACK_ID_GUIDE_ORIENTATION_UNACQUIRED
    **
    **      This callback will be called if the character turns too far away
    **      from its desired orientation after it has been previously
    **      reached.
    **
    *i    CALLBACK_ID_GUIDE_ALTITUDE_ACQUIRED
    **
    **      This callback will be called when the character has reached its
    **      desired altitude as set by set_desired_orientation() or other functions.
    **      The callback is most meaningful for vehicles that need to achieve
    **      some sort "cruising altitude" while moving to a destination.
    **
    *i    CALLBACK_ID_GUIDE_ALTITUDE_UNACQUIRED
    **
    **      This callback will be called if the character turns too far away
    **      from its desired orientation after it has been previously
    **      reached.
    **
    *i    CALLBACK_ID_GUIDE_TARGET_LOST
    **
    **      This callback will be called when the character guide has determined
    **      that the character can't reach its desired position/orientation. An
    **      example would be a missile that has flown past its target
    **
    *i    CALLBACK_ID_CURRENT_TOUT_REACHED
    **
    **      This callback will be called when scenario time reaches this
    **      character's tout time as set by set_current_tout().
    **
    *i    CALLBACK_ID_POST_CREATE_GEOMETRY
    **
    **      This callback will be called just after the character's geometry
    **      has been created.
    **
    *i    CALLBACK_ID_PRE_DESTROY_GEOMETRY
    **
    **      This callback will be called just before the character's
    **      geometry is broken down and destroyed.
    **
    *i    CALLBACK_ID_END_OF_PATH_REACHED
    **
    **      This callback will be called when a character reaches the end of
    **      their current path. Note the path must finish, forcing to other
    **      paths will not trigger this callback.
    **
    **
    *************************************************************************
    *4  DI-Guy Scenario UI Callback enums:
    **
    *i    CALLBACK_ID_UI_PRE_TRANSLATION
    **
    **      This callback will be called when the user interface starts
    **      moving a character.
    **
    *i    CALLBACK_ID_UI_POST_TRANSLATION
    **
    **      This callback will be called when the user interface finishes
    **      moving a character.
    **
    *i    CALLBACK_ID_UI_MOUSE_DOWN
    **
    **      This callback will be called when the user interface gets a
    **      mouse click in the DIGUY_SCENARIO_INPUT_MODE_POINT_SELECT input
    **      mode.
    **
    *i    CALLBACK_ID_UI_MOUSE_UP
    **
    **      This callback will be called when the user interface gets a
    **      mouse release in the DIGUY_SCENARIO_INPUT_MODE_POINT_SELECT
    **      input mode.
    **
    *************************************************************************
    *4  DI-Guy AI Agent Callback enums:
    **
    *i    CALLBACK_ID_AGENT_NEW_BEHAVIOR
    **
    **      This callback will be called when an agent changes its current
    **      behavior.
    **
    *i    CALLBACK_ID_AGENT_NEW_FOCUS_CHARACTER
    **
    **      This callback will be called when an agent changes its current
    **      focus character; this happens most frequently when it is focused
    **      on a group.
    **
    *i    CALLBACK_ID_AGENT_ATTACK_OUT_OF_TARGETS
    **
    **      This callback will be called when an agent in attack behavior
    **      evaluates the group it's focused on and cannot find an
    **      appropriate target.  This can happen if all group members are
    **      dead.
    **
    *i    CALLBACK_ID_AGENT_ATTACK_NO_VISIBLE_TARGETS
    **
    **      This callback will be called when an agent in attack behavior
    **      can't see any potential members of the group it's focused on.
    **
    *i    CALLBACK_ID_AGENT_PURSUE_TARGET_REACHED
    **
    **      This callback will be called when an agent in pursue behavior
    **      has come within the pursuit distance of its pursuit target.
    **
    *i    CALLBACK_ID_AGENT_PURSUE_TARGET_LOST
    **
    **      This callback will be called when an agent in pursue behavior
    **      is no longer within the pursuit distance of its pursuit target.
    **
    *i    CALLBACK_ID_AGENT_MINGLE_TARGET_REACHED
    **
    **      This callback will be called when an agent in mingle behavior
    **      has reached its mingle target.
    **
    *i    CALLBACK_ID_AGENT_MINGLE_TARGET_LOST
    **
    **      This callback will be called when an agent in mingle behavior
    **      is no longer is range of its mingle target.
    **
    *i    CALLBACK_ID_AGENT_WANDER_TARGET_REACHED
    **
    **      This callback will be called when an agent in wander behavior
    **      has reached its wander target.
    **
    *i    CALLBACK_ID_AGENT_WANDER_TARGET_LOST
    **
    **      This callback will be called when an agent in wander behavior
    **      is no longer is range of its wander target.
    **
    *i    CALLBACK_ID_AGENT_FLEE_AREA_LEFT
    **
    **      This callback will be called when an agent in flee behavior has
    **      successfully moved out range of all fled characters or
    **      locations.  This will only be called when the agent is
    **      transitioning from inside the flee area to outside of it.
    **
    *i    CALLBACK_ID_AGENT_FLEE_AREA_ENTERED
    **
    **      This callback will be called when an agent in flee behavior has
    **      moved inside of the range of any fled characters or locations.
    **      This will only be called when the agent is transitioning from
    **      outside the flee area to inside of it.
    **
    *i    CALLBACK_ID_AGENT_TRAVEL_WAYPOINT_REACHED
    **
    **      This callback will be called when an agent in travel behavior
    **      has reached in intermediate waypoint and is about to move
    **      on to the next.
    **
    *i    CALLBACK_ID_AGENT_TRAVEL_FORWARD_DEST_REACHED
    **
    **      This callback will be called when an agent in travel behavior
    **      has reached the end of its travel path when moving forward
    **      along the path.
    **
    *i    CALLBACK_ID_AGENT_TRAVEL_BACKWARD_DEST_REACHED
    **
    **      This callback will be called when an agent in travel behavior
    **      has reached the beginning of its travel path when moving
    **      backward along the path.
    **
    *i    CALLBACK_ID_AGENT_TRAVEL_NEAR_FORWARD_DEST
    **
    **      This callback will be called when an agent gets within a specified
    **      distance of the end of the travel path
    **
    *i    CALLBACK_ID_AGENT_CROWD_MEMBER_KILLED
    **
    **      This callback will be called when fellow member of the crowd is
    **      killed.
    **
    *-      - This is the character version of
    *-        diguyCrowd::CALLBACK_ID_CROWD_MEMBER_KILLED
    *-      - The crowd's callback character is the crowd member that was
    *-        killed.
    *-      - The crowd's callback impact contains the impact information.
    **
    *i    CALLBACK_ID_AGENT_CROWD_MEMBER_IMPACT
    **
    **      This callback will be called when a fellow member of the crowd
    **      is hit by a detonation.  This callback does not replace
    **      diguyCharacter::CALLBACK_ID_IMPACT, which still needs to be
    **      handled to implement damage models.
    **
    *-      - The crowd's callback character is the crowd member that was
    *-        hit.
    *-      - The crowd's callback impact contains the impact information.
    **
    *i    CALLBACK_ID_AGENT_NEARBY_SCENE_OBJECT_IMPACT
    **
    **      This callback will be called when a detonation occurs within the
    **      awareness radius (as set by set_awareness_radius()) of the
    **      crowd's current bounds.
    **
    *-      - This is the character version of
    *-        diguyCrowd::CALLBACK_ID_NEARBY_SCENE_OBJECT_IMPACT
    *-      - The crowd's callback character is the character that caused
    *-        the detonation.
    *-      - The crowd's callback impact contains the impact information.
    **
    *i    CALLBACK_ID_AGENT_NEARBY_WEAPON_FIRED
    **
    **      This callback will be called when a weapon is fired within the
    **      awareness radius (as set by set_awareness_radius()) of the
    **      crowd's current bounds.
    **
    *-      - The crowd's callback character is the character that fired the
    *-        weapon.
    **
    *i    CALLBACK_ID_AGENT_VEHICLE_COLLISION
    **
    **      This callback will be called on a vehicle agent when it hits a
    **      member of a companion crowd.
    **
    *i    CALLBACK_ID_AGENT_VEHICLE_NEAR_COLLISION
    **
    **      This callback will be called on a vehicle agent when it
    **      approaches another vehicle.
    **
    *i    CALLBACK_ID_AGENT_NON_ZERO_REPULSION
    **
    **      This callback will be called when an agent character's repulsion
    **      forces become non-zero.
    **
    *i    CALLBACK_ID_AGENT_ZERO_REPULSION
    **
    **      This callback will be called when an agent character's repulsion
    **      forces become zero.
    **
    *i    CALLBACK_ID_AGENT_PATH_PLAN_COMPLETED
    **
    **      This callback will be called when a character who's requested a
    **      path plan via the background path planner
    **      (agent_move_to_point_bg) gets a path result. Call
    **      diguyCharacter::get_path_planning_result() to get the status of
    **      the result.
    **
    *i    CALLBACK_ID_AGENT_MIND_CURRENT_STATE_CHANGED
    **
    **      This callback will be called when the current state the agent's
    **      mind, if it has one, has changed.  Call
    **      diguyCharacter::get_mind_current_state_name() to get the new
    **      state name.
    */
   enum {
      CALLBACK_ID_CREATE = 1,
      CALLBACK_ID_DESTROY,
      CALLBACK_ID_PRE_CREATE,
      CALLBACK_ID_CURRENT_APPEARANCE_CHANGED,
      CALLBACK_ID_CURRENT_HEAD_APPEARANCE_CHANGED,
      CALLBACK_ID_CURRENT_HAND_ITEM_APPEARANCE_CHANGED,
      CALLBACK_ID_CURRENT_EQUIPMENT_APPEARANCE_CHANGED,
      CALLBACK_ID_SHAPE_VARIATIONS_CHANGED,
      CALLBACK_ID_SHAPE_VISIBILITY_CHANGED,
      CALLBACK_ID_PRE_UPDATE,
      CALLBACK_ID_POST_UPDATE,
      CALLBACK_ID_DONE_SPEAKING,
      CALLBACK_ID_GAZE_STATUS,
      CALLBACK_ID_LPOINT_STATUS,
      CALLBACK_ID_SHOW,
      CALLBACK_ID_HIDE,
      CALLBACK_ID_PRE_DIE,
      CALLBACK_ID_POST_DIE,
      CALLBACK_ID_PRE_FIRE_WEAPON,
      CALLBACK_ID_POST_FIRE_WEAPON,
      CALLBACK_ID_IMPACT,
      CALLBACK_ID_FIRE_WEAPON_SUCCESS,
      CALLBACK_ID_CURRENT_ARC_CHANGED,
      CALLBACK_ID_CURRENT_ACTION_CHANGED,
      CALLBACK_ID_DESIRED_ACTION_CHANGED,
      CALLBACK_ID_DESIRED_ACTION_REACHED,
      CALLBACK_ID_MANUALLY_INVOKED,
      CALLBACK_ID_USER_SELECTED,
      CALLBACK_ID_USER_UNSELECTED,
      CALLBACK_ID_IGUY_INTERACT,
      CALLBACK_ID_IGUY_INTERACT_WITH_SUBJECT,
      CALLBACK_ID_GUIDE_POSITION_ACQUIRED,
      CALLBACK_ID_GUIDE_POSITION_UNACQUIRED,
      CALLBACK_ID_GUIDE_ORIENTATION_ACQUIRED,
      CALLBACK_ID_GUIDE_ORIENTATION_UNACQUIRED,
      CALLBACK_ID_GUIDE_ALTITUDE_ACQUIRED,
      CALLBACK_ID_GUIDE_ALTITUDE_UNACQUIRED,
      CALLBACK_ID_GUIDE_TARGET_LOST,
      CALLBACK_ID_CURRENT_TOUT_REACHED,
      CALLBACK_ID_POST_CREATE_GEOMETRY,
      CALLBACK_ID_PRE_DESTROY_GEOMETRY,
      CALLBACK_ID_END_OF_PATH_REACHED,
      CALLBACK_ID_CHARACTER_CLICKED,

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

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

#ifdef CPLUSPLUS_ONLY
/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function adds a user callback.  Callbacks can be removed
    **    with remove_callback() or remove_callback_with_user_data().
    **
    *b  Arguments:
    **
    *a    callback        - pointer to function with prototype
    *a                      diguyCharacterCallback (typedefed above)
    *a    callback_id     - integer id of when this callback is to be called
    *a    callback_params - not currently used; pass NULL
    *a    callback_user_data - pointer for user's own use; DI-Guy will
    *a                         do nothing to the contents of this pointer
    *a                         beyond passing it back when the callback is
    *a                         invoked
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int add_callback(int callback_id,
      diguyCharacterCallback* callback,
      void* callback_params = 0,
      void* callback_user_data = 0);

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

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

#endif
/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function adds a user callback script.  Callback scripts can
    **    be removed with remove_callback_script().
    **
    *b  Arguments:
    **
    *a    callback_id          - integer id of the callback
    *a    callback_script      - script text of callback to be added
    *a    callback_script_type - the type of script contained in
    *a                           callback_script
    **
    **    If NULL is passed for callback_script_type, a default script type
    **    will be derived based on the default script interpreter of the
    **    scenario.
    **
    *i  lua specific:
    **
    **    When the script is called, the object for which it is being called
    **    will be in the callback_object global.
    **
    **    To pass NULL when calling from a lua script, use nil.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Lua Example:
    **
    *e     -------------------------------------------------------------------
    *e     local pre_fire_weapon_callback = [[
    *e
    *e         local ch_name = callback_object:get_name();
    *e         bdi_log_print(BDI_LOG_WARN, "Calling pre_fire_weapon_callback for character ".. ch_name .. ".\n");
    *e
    *e     ]]
    *e     -------------------------------------------------------------------
    *e
    *e     character:add_callback_script(diguyCharacter_CALLBACK_ID_PRE_FIRE_WEAPON,
    *e         pre_fire_weapon_callback,
    *e         "lua");
    */
   int add_callback_script(int callback_id,
      const char* callback_script,
      const char* callback_script_type = NULL);

   /*l
    *b  Description:
    **
    **    This function removes a user callback script previously added with
    **    add_callback_script().
    **
    *b  Arguments:
    **
    *a    callback_id          - integer id of the callback
    *a    callback_script      - script text of callback previously added
    *a    callback_script_type - the type of script contained in
    *a                           callback_script
    **
    **    If NULL is passed for callback_script, all callback
    **    scripts whose ids match callback_id and whose types match
    **    callback_script_type will be removed.
    **
    **    If NULL is passed for callback_script_type, a default script type
    **    will be derived based on the default script interpreter of the
    **    scenario.
    **
    *i  lua specific:
    **
    **    To pass NULL when calling from a lua script, use nil.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  lua Example:
    **
    *e     #
    *e     #  Remove all callback scripts with id
    *e     #  diguyCharacter_CALLBACK_ID_PRE_FIRE_WEAPON
    *e     #
    *e     character:remove_callback_script(diguyCharacter_CALLBACK_ID_PRE_FIRE_WEAPON,
    *e         nil,
    *e         "lua");
    */
   int remove_callback_script(int callback_id,
      const char* callback_script,
      const char* callback_script_type = NULL);


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

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

   /*l
    *b  Description:
    **
    **    This function manually invokes the named character event
    **    handler.  The callback_id that will be passed to the event
    **    handler will be CALLBACK_ID_MANUALLY_INVOKED.
    **
    **    See diguyCharacter::map_event_handler_to_callback_id() for
    **    a description of what comprises a character event handler.
    **
    **    Note that care should be taken not to end up in an
    **    infinite loop of event calls.  In general an event handler
    **    should not end up directly or indirectly invoking itself.
    **
    *b  Arguments:
    **
    *a    handler_name  - name of the event handler to invoke
    **
    *b  Returns:
    **
    **    DIGUY_CALLBACK_CONTINUE or DIGUY_CALLBACK_STOP
    **
    *b  Available as Decision Bead/Event
    */
   diguyCallbackReturn manually_invoke_event_handler(const char* handler_name);


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

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

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

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

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

   /*l
    *b  Description:
    **
    **    This function destroys a path created by create_path(),
    **    create_simple_path(), or a path from a loaded scenario.
    **
    **    The path the character is currently traveling, as returned by
    **    get_current_traveled_path(), cannot be destroyed.  Attempting to
    **    destroy it will result in a warning, and the path won't be deleted.
    **
    *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);

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

   int get_num_connection_points();

   const char * get_connection_point_name_at_index(int index);

   bool get_connection_point_info_at_index(int index, diguyGraphicsLink** link, float* matrix_offset, int transpose);

   int get_num_connection_points_with_type(diguyConnectionPointType type);

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

   bool find_connection_point(const char* name, diguyGraphicsLink** link, float* matrix_offset, int transpose);

   diguyGraphicsShape* find_shape(const char* shape_name);

   int remove_shape(const char* shape_name);

/*****************************************************************************/
   diguyLinkController * get_link_controller(const char * link_name);

   int set_link_translation_override(const char * link_name, float x, float y, float z, float ramp_time = .25f);

   int set_link_translation_override(const char * link_name, float x, float y, float z, float vx, float vy, float vz, float ramp_time = .25f);

   int end_link_translation_override(const char * link_name, float ramp_time = .25f);

   int set_link_rotation_override(const char * link_name, float rz, float rx, float ry, float ramp_time = .25f);
   int set_link_rotation_override(const char * link_name, float rz, float rx, float ry, float vrx, float vry, float vrz, float ramp_time = .25f);

   int end_link_rotation_override(const char * link_name, float ramp_time = .25f);


/*****************************************************************************/
   int get_num_articulated_parts();

   const char* get_articulated_part_link_name( int index );

   int get_articulated_part_id( int index );

   const char* map_articulated_part_id_to_link( int id );


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

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

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

#endif

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

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

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

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

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

   int get_altitude_update_rate();

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

   float get_altitude_interpolation_rate();

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

#ifdef CPLUSPLUS_ONLY

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

   int get_pose_in_quaternions(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  - deprecated as of 13.2
    *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()).
    **    distance argument - deprecated as of 13.2
    */
   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                 begins at 0 at the positive X axis of the DI-Guy
    *a                 coordinate system and proceeds counter-clockwise
    *a    elevation  - rotation in degrees about horizontal axis; positive
    *a                 value 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 the
    **    angles are relative to the character's frame of reference. These
    **    relative angles will be maintained even if the character rotates.
    **
    **    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 is identical to aim_at_angle() and aim_at_angle_local(),
   **    but includes velocity that will modify the angles every frame.
   **    This can be useful in networked simulations where targeting velocity is published.
   **
   **    This function will have no effect on a dead character (see
   **    die_now() and get_dead()).
   */
   int aim_at_angle_with_velocity(float azimuth, float elevation, float az_vel, float el_vel, int local, 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 the
    **    coordinates are relative to the character, in its own coordinate
    **    system. Use get_position() to learn the idealized position of the
    **    character if necessary.
    **
    **    This function will have no effect on a dead character (see
    **    die_now() and get_dead()).
    */
   int aim_at_point_local(float x, float y, float z, int is_new_aim = 1);

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

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

   const char * get_aim_at_character();

   float get_aim_azimuth();

   float get_aim_elevation();

   /*l
    *b  Description:
    **
    **    This function returns values that can be used to compute the
    **    character's weapon's trajectory, i.e. the mathematical ray that
    **    comes out of the end of the barrel.
    **
    *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();

   int set_aim_variable_interpolation_time(float time);
   float get_aim_variable_interpolation_time();

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

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

   const char* get_gaze_at_link();

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

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

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

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

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

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

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

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

   const char* get_weapon_supplemental_data_name();

   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);
   float get_weapon_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 );
   float get_weapon_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 duration of a weapon's muzzle flash.
    **    The duration is specified as the number of frames it will be visible
    **    when shown.
    */
   void set_weapon_flash_duration( int muzzle_flash_duration );

   /*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:
    **
    **    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 or motion file on disk.
    **
    **    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 to execute, as of diguy 13.2 this can be
    *a                       a bdm file, and a full body gesture will be created on the fly.
    *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:
    **
    **   Executes the given gesture and performs the given action as a table action.
    **
    *b  Arguments:
    **
    *a    gesture_name - name of the gesture to execute
    *a    desired_action - name of table action to perform
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    **/
   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 = .5f);

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

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


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

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

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

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

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

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

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

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

   const char* get_current_voice_actor();


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

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

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

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

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

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

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

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

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

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

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

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

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

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

   int get_DIS_damage_state();

   /*l
    *b  Description:
    **
    **    Returns the name of damage state appearances based on the base appearance of the character.
    **    NULL if there is no appearance specified.
    */
   const char * get_damage_state_appearance_name(int state);

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

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

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

   int get_DIS_power_plant_state();

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

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

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

   int get_DIS_trailing_effect_state();

   void set_DIS_station_name(int name);
   int get_DIS_station_name() const;

   void set_DIS_station_number(int number);
   int get_DIS_station_number() const;

   void set_head_lights_state(int state);

   int  get_head_lights_state() const;

   void set_tail_lights_state(int state);

   int  get_tail_lights_state() const;


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

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


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

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

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

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

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

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

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

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


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

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

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

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

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

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


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

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

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

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

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

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


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

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

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

   diguyMotionVariant get_desired_variant();

   /*l
    *b  Description:
    **
    **    This function looks up the character action that most closely
    **    matches the given criteria.
    **
    *b  Arguments:
    **
    *a    direction            - the direction of travel relative to
    *a                           the character's facing direction
    *a    posture              - overall desired posture; pass
    *a                           DIGUY_MOTION_POSTURE_ANY
    *a                           to specify that any posture will do
    *a    variant              - overall desired variant; pass
    *a                           DIGUY_MOTION_VARIANT_ANY
    *a                           to specify that any variant will do
    *a    speed                - speed in meters per second
    *a    comparison           - how the passed speed should compare
    *a                           to the action's speed
    *a    comparison_tolerance - tolerance of comparison
    *a    match_posture_before_variant - pass 1 if posture should be matched
    *a                                   before variant if an exact match is
    *a                                   not found; pass 0 if variant should
    *a                                   be matched before posture
    *a    posture_alternate1   - if an exact match is not found, use this
    *a                           as the first alternate posture; pass
    *a                           DIGUY_MOTION_POSTURE_UNKNOWN
    *a                           to specify that no alternate should be used
    *a    posture_alternate2   - if an exact match is not found, use this
    *a                           as the second alternate posture; pass
    *a                           DIGUY_MOTION_POSTURE_UNKNOWN
    *a                           to specify that no alternate should be used
    *a    variant_alternate1   - if an exact match is not found, use this
    *a                           as the first alternate variant; pass
    *a                           DIGUY_MOTION_VARIANT_UNKNOWN
    *a                           to specify that no alternate should be used
    *a    variant_alternate2   - if an exact match is not found, use this
    *a                           as the second alternate variant; pass
    *a                           DIGUY_MOTION_VARIANT_UNKNOWN
    *a                           to specify that no alternate should be used
    *a    return_random_match  - (Experimental) if multiple actions match the
    *a                           specified criteria randomly return one of
    *a                           them. Typically only used for still motions
    *a                           and restricted to EQUAL and NEAREST
    *a                           comparisons
    **
    **    The direction argument should be one of the following:
    **
    *-     - DIGUY_MOTION_DIRECTION_NONE           - does not move character
    *-     - DIGUY_MOTION_DIRECTION_FORWARD        - moves character forward
    *-     - DIGUY_MOTION_DIRECTION_BACKWARD       - moves character backward
    *-     - DIGUY_MOTION_DIRECTION_LEFT           - moves character left
    *-     - DIGUY_MOTION_DIRECTION_RIGHT          - moves character right
    *-     - DIGUY_MOTION_DIRECTION_UP             - moves character up
    *-     - DIGUY_MOTION_DIRECTION_DOWN           - moves character down
    *-     - DIGUY_MOTION_DIRECTION_TURN_LEFT      - turns character left
    *-     - DIGUY_MOTION_DIRECTION_TURN_RIGHT     - turns character right
    *-     - DIGUY_MOTION_DIRECTION_NONLINEAR      - moves character in
    *-                                               multiple directions
    *-     - DIGUY_MOTION_DIRECTION_LINEAR_OFFAXIS - moves character in a
    *-                                               line, but not on any
    *-                                               of the principle axes
    **
    **    Not every direction is supported by every character.  If the
    **    character does not have any actions that move in the specified
    **    direction, the returned action will be NULL.
    **
    **    Use the calls diguyScenario::get_character_type_num_directions()
    **    and diguyScenario::get_character_type_direction_at_index() to
    **    enumerate which directions a character can travel.
    **
    **    The posture arguments should be one of the following:
    **
    *-     - DIGUY_MOTION_POSTURE_UNKNOWN     - unknown posture
    *-     - DIGUY_MOTION_POSTURE_ANY         - any posture; a wildcard
    *-     - DIGUY_MOTION_POSTURE_UPRIGHT     - upright posture; e.g., standing,
    *-                                          walking, or running
    *-     - 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
    *-     - DIGUY_MOTION_POSTURE_KNEELING    - kneeling posture
    *-     - DIGUY_MOTION_POSTURE_SWIMMING    - swimming posture
    *-     - DIGUY_MOTION_POSTURE_PARACHUTING - parachuting posture
    *-     - DIGUY_MOTION_POSTURE_JUMPING     - jumping posture
    *-     - DIGUY_MOTION_POSTURE_SQUATTING   - jumping posture
    *-     - DIGUY_MOTION_POSTURE_WADING      - wading 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 technique 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 technique is not one of DI-Guy's stock shaders, a custom
    **    shader technique can be loaded explicitly by calling
    **    the diguyApp::load_shader_program() function.
    **
    *b  NOTE:
    **
    **    The specified shader technique 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 technique 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 technique for the specified render
    **    mode to its default.  This will be the shader technique 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 technique 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 technique name;
    *a                  pass NULL for "normal" render mode
    **
    *b  Returns:
    **
    **    name of shader technique; 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. This is here for backwards compatibility,
    **    and just returns the highest quality shader technique shader.
    **
    *b  Returns:
    **
    **    object of type diguyGraphicsShaderProgram; NULL if none
    */
   diguyGraphicsShaderProgram* get_shader_program();

   /*l
   *b  Description:
   **
   **    This function returns the shader technique that is in use by the
   **    character.  Shader techniques own a number of shader objects.
   **
   *b  Returns:
   **
   **    object of type diguyGraphicsShaderTechnique; NULL if none
   */
   diguyGraphicsShaderTechnique* get_shader_technique();

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   /*l
    *b  Description:
    **
    **    Agent will attempt to create a navigation path on the region
    **    via_region and then travel it.  An A* path planning algorithm is
    **    used to find the path.
    **
    **    The subregion masks are used to specify which subregions to use or
    **    avoid.  Cost bias values can be used to make tweak how strong the
    **    repulsion values are.
    **
    *b    Note:
    **
    **    As of DI-Guy 12 there is a version of this function
    **    agent_move_to_point_via_subregions_bg that uses a multi-threaded
    **    infrastructure.  We strongly recommend using it for future
    **    developments.
    **
    **    This function will fail and return -1 if a path cannot be found.
    **
    *b  Arguments:
    **
    *a    x, y, z        - the target location
    *a    via_region     - the name of the region to run A* on (pass in "*"
    *a                     to have the code attempt to find the nearest
    *a                     region automatically)
    *a    preferred_subregions_mask - diguySubregionMask value of regions
    *a        preferred for travel
    *a    cost_bias_for_preferred_regions - how much cheaper it will be
    *a        to cross spaces that are part of desired subregion;
    *a          should be < 1.0
    *a    cost_bias_for_neutral_regions - how much more expensive it will be
    *a        to cross spaces that are not part of desired subregion; see
    *a        below for more information
    *a    repulsed_regions_mask - diguySubregionMask value of regions *not*
    *a        preferred for travel
    *a    cost_bias_for_repulsed_regions - how much more expensive it will be
    *a        to cross regions that are marked as repulsive; pass
    *a        DIGUY_DEFAULT_FLOAT to avoid completely
    **
    **    Pass DIGUY_DEFAULT_FLOAT for cost_bias_for_neutral_regions and
    **    cost_bias_for_repulsed_regions to specify that they should be
    **    avoided completely.
    **
    **    The preferred_subregions_mask and repulsed_regions_mask use
    **    DI-Guy subregion mask values combined together.  For example,
    **    DIGUY_SUBREGION_MASK_SIDEWALK | DIGUY_SUBREGION_MASK_CROSSWALK.
    **
    **    For cost_bias_for_neutral_regions, specifying a non-zero value for
    **    this lowers the likelihood that searches fail on disjointed
    **    subregions.  A value < 1 will cause the planner to run faster but
    **    explore fewer points, possibly missing preferred regions.  Values
    **    greater then 1 will explore more points but will be slower.
    **
    *b  NOTE:
    **
    *b    THIS API has changed for DI-GUY 11.
    **
    **    cost_bias_for_preferred_regions has been added and the neutral and
    **    repulsed default values have changed.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int agent_move_to_point_via_subregions(float x, float y, float z,
      const char* via_region = NULL,
      int preferred_subregions_mask = DIGUY_SUBREGION_MASK_NONE,
      float cost_bias_for_preferred_regions = 0.25f,
      float cost_bias_for_neutral_regions = 1.1f,
      int repulsed_regions_mask = DIGUY_SUBREGION_MASK_NONE,
      float cost_bias_for_repulsed_regions = 10.0f,
      int cost_rule = 0);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

#ifdef CPLUSPLUS_ONLY

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

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

#endif


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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



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

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

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

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

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

#endif


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

   const char* get_ik_chain_name_at_index( int index );

   /*b  Description:
    **   Moves the end effector for the specified ik chain to a location in the world.
    **
    *b  Arguments:
    *a    ik_chain_target - index of ik chain
    *a    x,y,z           - world location of where to move the IK end effector to.
    *a    ramp_time       - how long to take blending in solution
    **
    *b  Returns:
    **   -1 on failure, 0 on success
    */
   int set_ik_target_world( int ik_chain_target, float x, float y, float z, float ramp_time = 0.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 = 0.25f );

   /*b  Description:
    **   Moves the end effector for the specified ik chain to location on another character.
    **
    *b  Arguments:
    *a    ik_chain_target - index of ik chain
    *a    target          - target character.
    *a    link_name       - target joint
    *a    ramp_time       - how long to take blending in solution
    **
    *b  Returns:
    **   -1 on failure, 0 on success
    */
   int set_ik_target_character( int ik_chain_target, diguyCharacter* target, const char* link_name, float ramp_time = 0.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 = 0.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);

   static int get_max_shader_quality_level();


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

   /*l
    **    Sets if this character will play back animation events that have been
    **    added to motion inits in the action table.
    */
   int set_animation_events_enabled(int enable);
   int get_animation_events_enabled();


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

   float get_normalized_age() const;

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

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

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

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

   int get_mind_always_updates();

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


   void set_scene_graph_mask(unsigned int mask);

   unsigned int get_scene_graph_mask();


   diguyMotionEngineSnapshot get_motion_engine_snapshot();

   int apply_motion_engine_snapshot( const diguyMotionEngineSnapshot& action_info );


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

#ifdef CPLUSPLUS_ONLY
   const float * get_local_to_world_orientation_matrix();
#endif
   int set_current_IK_world_conversion_matrix(
      float a0, float a1, float a2,
      float b0, float b1, float b2,
      float c0, float c1, float c2, int transpose = 0);
   // HACK fix me with generalized system
   void set_IK_use_vrv_swizzle(bool);


   int set_always_update_regardless_of_dt(int val);
   int get_always_update_regardless_of_dt();

   void set_shader_matrices_out_of_date();

   void draw_debugging_visuals();

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

   // Deprecated as of 13.0;
   int aim_converge(int max_iterations = 30);

   void set_aim_algorithm(int aim_algorithm);

   int get_aim_algorithm();


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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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


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

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


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

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

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

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

   //  Deprecated as of 12.0.0.  Not supported in FaceFX.
   //float get_azimuth_eye_right();

   //  Deprecated as of 12.0.0.  Not supported in FaceFX.
   //float get_elevation_eye_right();

   //  Deprecated as of 13.2 keys off of scenario weapons fire effects now
   //int set_weapon_shell_eject_enabled(int enabled);

   //  Deprecated as of 13.2 keys off of scenario weapons fire effects now
   //int get_weapon_shell_eject_enabled();

   //  Deprecated as of 13.2 keys off of scenario weapons fire effects now
   //int set_weapon_smoke_enabled(int enabled);

   //  Deprecated as of 13.2 keys off of scenario weapons fire effects now
   //int get_weapon_smoke_enabled();

   //  Deprecated as of 13.5
   // int set_shape_switches_disabled(int disabled_flag);
   // int get_shape_switches_disabled();

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

#ifdef CPLUSPLUS_ONLY

   bdiScenarioCharacter* get_scripted_object();
private:

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

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

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

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

#endif

};