diguyCrowd.h

Go to the documentation of this file.

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

/*********************************************************************
 **
 *t  diguyCrowd
 **
 */

#pragma once

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

#ifdef CPLUSPLUS_ONLY

#include <diguyMotionSpeedType.h>
#include <diguyMotionPosture.h>
#include <diguyMotionVariant.h>

#include <diguy_typedefs.h>        // for diguyCharacterCallback diguyCrowdCallback

class bdiScenarioCrowd;
class diguyCharacter;
class diguyCharacterGroup;
class diguyCrowd;
class diguyImpact;
class diguyPathShape;
class diguyRegion;
class diguyVehicleNearCollision;
class DtAggregateStateRepository;


#endif

#include <declspec_diguy.h>

#include <stddef.h>

class BDI_DECLSPEC_diguy diguyCrowd
{
/*****************************************************************************/
public:

   /*l
    *b  Returns:
    **
    **    name of this object; this value 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  Returns:
    **
    **    UI name of this object; this value will never be NULL
    */
   const char* get_ui_name();

   /*l
    *b  Description:
    **
    **    This function sets the UI name of this object.  The UI name is what
    **    shows up in user interface windows that show information about this
    **    crowd.
    **
    **    For example, the crowd name may be "crowd_squad1", the UI name may
    **    be "Squad 1".
    **
    **    By default the UI name matches the internal name.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int set_ui_name(const char* ui_name);

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

   /*l
    *b  Description:
    **
    **    This function enables or disables the crowd.
    **
    **    Disabling a crowd does not disable or hide the members of the
    **    crowd.  It does turn off any effects the crowd may have on agent
    **    actions, position, orientation, etc.  To enable or disable all
    **    agents in the crowd, use set_all_members_enabled() instead.
    **
    **    Disabled crowds also will not interact with companion crowds.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int set_enabled(int enabled);

   /*l
    *b  Returns:
    **
    **    1 if enabled, 0 if not
    **
    *b  Available as Decision Bead/Event
    */
   int get_enabled();

   /*l
    *b  Description:
    **
    **    This function enables or disables all agents in the crowd.  This is
    **    the equivalent to calling diguyCharacter::set_enabled() for all
    **    members of the crowd.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   void set_all_members_enabled(int enabled);

   /*l
    **
    *b  Returns:
    **
    **    The size of the radius around the crowd's character that certain
    **    callbacks will be triggered within. Callbacks such as:
    **    CALLBACK_ID_NEARBY_SCENE_OBJECT_IMPACT, and
    **    CALLBACK_ID_NEARBY_WEAPON_FIRED, are affected by this value.
    */
   float get_awareness_radius();

   /*l
    **
    *b  Description:
    **
    **    Sets the crowd awareness radius.  See get_awareness_radius().
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int set_awareness_radius(float radius);


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    Adds the passed character to the crowd if not already in it.
    **
    *b  Returns:
    **
    **    0 if the character is now a part of the crowd;
    **    -1 if not
    */
   int add_member(diguyCharacter* character);

   /*l
    *b  Description:
    **
    **    Adds all characters of the group as members of the crowd.
    **
    *b  Returns:
    **
    **    Always return 0.
    */
   int add_all_characters_in_group(diguyCharacterGroup* group);

   /*l
    *b  Description:
    **
    **    Removes the passed character from the crowd if it is a member.
    **
    *b  Returns:
    **
    **    0 if the character was part of the crowd and removed;
    **    -1 if not
    */
   int remove_member(diguyCharacter* character);

   /*l
    *b  Description:
    **
    **    Removes all members of the crowd.
    **
    *b  Returns:
    **
    **    Always return 0.
    */
   int remove_all_members();

   /*l
    *b  Returns:
    **
    **    1 if the passed character is a member of the crowd; 0 if not
    */
   int is_member(diguyCharacter* character);

   /*l
    *b  Returns:
    **
    **    number of member characters in crowd
    */
   int get_num_members();

   /*l
    *b  Returns:
    **
    **    crowd member at specified index; NULL if no character at specified
    **    index
    */
   diguyCharacter* get_member_at_index(int index);

   /*l
    *b  Returns:
    **
    **    index of crowd member; -1 if not a member of the crowd
    */
   int get_index_of_member(diguyCharacter* member);

   /*l
    *b  Returns:
    **
    **    diguyCharacterGroup associated with the crowd
    */
   diguyCharacterGroup* get_associated_group();


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This is a shortcut for calling
    **    diguyCharacter::agent_attack_character() for all members of the
    **    crowd.
    **
    **    This function will implicitly put agents 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  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int agents_attack_character(const char* character_name);

   /*l
    *b  Description:
    **
    **    This is a shortcut for calling diguyCharacter::agent_attack_group()
    **    for all members of the crowd.
    **
    **    This function will implicitly put agents into the attack behavior.
    **
    **    The current focus group will be set 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  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int agents_attack_group(const char* group_name);

   /*l
    *b  Description:
    **
    **    This is a shortcut for calling
    **    diguyCharacter::agent_flee_character() for all members of the
    **    crowd.
    **
    **    This function will implicitly put agents into the flee behavior.
    **
    **    Neither the current focus character nor group will be changed by
    **    this function.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int agents_flee_character(const char* character_name,
      float distance,
      int danger_level = 50);

   /*l
    *b  Description:
    **
    **    This is a shortcut for calling diguyCharacter::agent_flee_group()
    **    for all members of the crowd.
    **
    **    This function will implicitly put agents into the flee behavior.
    **
    **    Neither the current focus character nor group will be changed by
    **    this function.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int agents_flee_group(const char* group_name,
      float distance,
      int danger_level = 50);

   /*l
    *b  Description:
    **
    **    This is a shortcut for calling diguyCharacter::agent_flee_crowd()
    **    for all members of the crowd.
    **
    **    This function will implicitly put agents into the flee behavior.
    **
    **    Neither the current focus character nor group will be changed by
    **    this function.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int agents_flee_crowd(const char* crowd_name,
      float distance,
      int danger_level = 50);

   /*l
    *b  Description:
    **
    **    This is a shortcut for calling
    **    diguyCharacter::agent_flee_location() for all members of the crowd.
    **
    **    This function will implicitly put agents into the flee behavior.
    **
    **    Neither the current focus character nor group will be changed by
    **    this function.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int agents_flee_location(float x, float y, float z,
      float distance,
      int danger_level = 50);

   /*l
    *b  Description:
    **
    **    This is a shortcut for calling
    **    diguyCharacter::agent_remove_all_flee_objects() for all members of
    **    the crowd.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   void agents_remove_all_flee_objects();

   /*l
    *b  Description:
    **
    **    This is a shortcut for calling
    **    diguyCharacter::agent_mingle_in_region() for all members of the
    **    crowd.
    **
    **    This function will implicitly put agents into the mingle behavior.
    **
    **    Neither the current focus character nor group will be changed by
    **    this function.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int agents_mingle_in_region( const char* region_name = NULL, const char* subregion = NULL );

   /*l
    *b  Description:
    **
    **    This is a shortcut for calling
    **    diguyCharacter::agent_pursue_character() for all members of the
    **    crowd.
    **
    **    This function will implicitly put agents into the pursue 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  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int agents_pursue_character(const char* character_name);

   /*l
    *b  Description:
    **
    **    This is a shortcut for calling diguyCharacter::agent_pursue_group()
    **    for all members of the crowd.
    **
    **    This function will implicitly put agents 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  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int agents_pursue_group(const char* group_name);

   /*l
    *b  Description:
    **
    **    This causes all members of the crowd to start pursuing the
    **    individual that is closer to the leader then they are.
    **
    **    This function will implicitly put all agents except the leader into
    **    the pursue behavior.
    **
    **    The current focus character will be set to the next nearest
    **    character.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int agents_chain_pursue(const char* leader_name);

   /*l
    *b  Description:
    **
    **    This is a shortcut for calling
    **    diguyCharacter::agent_travel_behavior_path() for all members of the
    **    crowd.
    **
    **    This function will implicitly put agents into the travel behavior.
    **
    **    Neither the current focus character nor group will be changed by
    **    this function.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int agents_travel_behavior_path(const char* direction = NULL,
      const char* at_end = NULL,
      int waypoint_index = -1,
      float offset_y = 0.5f);

   /*l
    *b  Description:
    **
    **    This is a shortcut for calling
    **    diguyCharacter::agent_travel_path_shape() for all members of the
    **    crowd.
    **
    **    This function will implicitly put agents into the travel behavior.
    **
    **    Neither the current focus character nor group will be changed by
    **    this function.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int agents_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:
    **
    **    This is a shortcut for calling
    **    diguyCharacter::agent_travel_region_border() for all members of the
    **    crowd.
    **
    **    This function will implicitly put agents into the travel behavior.
    **
    **    Neither the current focus character nor group will be changed by
    **    this function.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int agents_travel_region_border(const char* region_name,
      const char* subregion = NULL);

   /*l
    *b  Description:
    **
    **    This is a shortcut for calling
    **    diguyCharacter::agent_wander_region() for all members of the crowd.
    **
    **    This function will implicitly put agents into the wander behavior.
    **
    **    Neither the current focus character nor group will be changed by
    **    this function.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int agents_wander_region(const char* region_name = NULL,  // NULL -> populate region
      const char* subregion = NULL);

   /*l
    *b  Description:
    **
    **    This is a shortcut for calling
    **    diguyCharacter::agent_stop_behavior() for all members of the crowd.
    **
    **    This function will implicitly put agents into the none behavior.
    **
    **    Neither the current focus character nor group will be changed by
    **    this function.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int agents_stop_behavior();

   /*l
    *b  Description:
    **
    **    This is a shortcut for calling
    **    diguyCharacter::set_current_behavior() for all members of the
    **    crowd.
    **
    **    It's recommended that one of the higher level functions above that
    **    set behavior, for example agent_wander_region(), is used.  These
    **    functions allow for setting the most common parameters that affect
    **    the behavior in one function call.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int set_current_behavior(const char* behavior_name);

   /*l
    *b  Description:
    **
    **    Returns the current behavior used by crowd, expressed as a string
    **    (e.g. "travel").
    **
    *b  Returns:
    **
    **    string describing current crowd behavior, NULL on error
    */
   const char* get_current_behavior(int member_index = 0);

   /*l
    *b  Description:
    **
    **    Similar to diguyAgentParams::set_behavior_path_shape().  This is a
    **    shortcut for setting the current behavior path shape for all
    **    characters in the crowd.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int set_current_behavior_path_shape(const char* behavior_path_shape_name,
      float max_time_until_move_on = 0.0f);

   /*l
    *b  Description:
    **
    **    Similar to diguyAgentParams::set_behavior_region().  This is a
    **    shortcut for setting the current behavior region for all characters
    **    in the crowd.
    **
    **    This function does take an additional argument,
    **    max_time_until_move_on.  Setting this to 0 will cause all agents
    **    that occasionally pause their movement (for example, characters in
    **    the wander behavior) to move on to the new behavior region
    **    immediately.  Passing a higher number will allow agents to finish
    **    their "natural" wait interval before moving on to the new region.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int set_current_behavior_region(const char* behavior_region_name,
      const char* subregion = NULL,
      float max_time_until_move_on = 0.0f);

   /*l
    *b  Description:
    **
    **    Similar to diguyAgentParams::set_focus_character().  This is a
    **    shortcut for setting the current focus character for all characters
    **    in the crowd.
    **
    **    The current focus group will not be affected by this function.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int set_current_focus_character(const char* focus_character_name);

   /*l
    *b  Description:
    **
    **    Similar to diguyAgentParams::set_focus_group().  This is a shortcut
    **    for setting the current focus group for all characters in the
    **    crowd.
    **
    **    The current focus character will not be affected by this function.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int set_current_focus_group(const char* focus_group_name);

   /*l
    *b  Description:
    **
    **    This is a shortcut for calling
    **    diguyCharacter::agent_set_current_params_from_profile() for all
    **    members of the crowd.
    **
    **    This will affect most of the parameters of agents in this crowd,
    **    including behavior, posture and variant, etc.  Focus character and
    **    group by default are changed, but can be left alone by passing 0
    **    for retain_focus_objects.
    **
    *b  Arguments:
    **
    *a    profile_name - name of crowd profile whose default parameters
    *a                   should be used
    *a    retain_focus_objects - pass 1 to change focus objects to those
    *a                           of the named profile, 0 to retain existing
    *a                           settings
    *a    retain_navigation_values - keeps path_shape, region, subregion, path planner
    *a                               cost values and rules the same
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Available as Decision Bead/Event
    */
   int set_current_params_from_profile(const char* profile_name,
      int retain_focus_objects = 1,
      int retain_navigation_values = 1);

   /*l
    *b  Description:
    **
    **    This is a shortcut for calling
    **    diguyCharacter::agent_set_current_behavior_region_border_is_solid()
    **    for all members of the crowd.
    **
    **    Sets whether the walls of the region the agent is in are 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.
    **
    **    Pass 1 to make border walls solid, 0 to make them
    **    freely passable.
    **
    *b  Available as Decision Bead/Event
    */
   void set_current_behavior_region_border_is_solid(int is_solid);

   /*l
    *b  Description:
    **
    **    Sets the posture of all members of the crowd and restarts their
    **    behaviors.
    */
   void set_current_postures(diguyMotionPosture posture);

   /*l
    *b  Description:
    **
    **    Sets the variant of all members of the crowd and restarts their
    **    behaviors.
    */
   void set_current_variants(diguyMotionVariant variant);

   /*l
    *b  Description:
    **
    **    This function is similar to set_current_params_from_profile(), but
    **    instead sets initial params.
    **
    *b  Arguments:
    **
    *a    profile_name - name of crowd profile whose default parameters
    *a                   should be used
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int set_initial_params_from_profile(const char* profile_name);


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This is a query function meant to allow for flexible behavior when
    **    dealing with a crowd.  If more than threshold ratio are doing
    **    behavior_name then the function will return 1.  The default 0.5
    **    yields a simple majority check.
    **
    *b  Returns:
    **
    **    1 if true, 0 if false
    **
    *b  Available as Decision Bead/Event
    */
   int is_current_behavior(const char* behavior_name,
      float threshold = 0.5f);

   /*l
    *b  Description:
    **
    **    Similar to is_current_behavior(), but checks both behavior and
    **    focus character.
    */
   int is_current_behavior_and_focus_character(const char* behavior_name,
      const char* focus_character_name,
      float threshold = 0.5f);

   /*l
    *b  Description:
    **
    **    Similar to is_current_behavior(), but checks both behavior and
    **    focus group.
    */
   int is_current_behavior_and_focus_group(const char* behavior_name,
      const char* group_name,
      float threshold = 0.5f);

   /*l
    *b  Description:
    **
    **    Similar to is_current_behavior(), but checks whether characters are
    **    dead.
    */
   int is_crowd_dead(float threshold = 0.5f);


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function makes the specified crowd a "companion crowd" of this
    **    crowd.  Crowd members of companion crowds know about each other and
    **    will attempt to avoid each other.
    **
    **    If two crowds are not companions, their respective crowd members
    **    will make no attempt to avoid each other.
    **
    *b  Arguments:
    **
    *a    companion_crowd - name of crowd to become a companion
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int add_companion_crowd(diguyCrowd* companion_crowd);

   /*l
    *b  Description:
    **
    **    This function removes the specified crowd as a companion crowd.
    **
    *b  Arguments:
    **
    *a    companion_crowd - name of former companion
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int remove_companion_crowd(diguyCrowd* companion_crowd);


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function sets the dynamic avoidance method that members of
    **    this crowd will use to avoid each other.  Dynamic objects are
    **    objects that are moving around; these are almost always characters.
    **
    **    The enumeration is defined in diguy_constants.h.
    **
    *b  Arguments:
    **
    *a    method - avoidance method to use
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   void set_dynamic_object_avoidance_method(diguyDynamicAvoidanceMethod method);

   /*l
    *b  Returns:
    **
    **    current dynamic object avoidance method;
    **    see set_dynamic_object_avoidance_method()
    */
   diguyDynamicAvoidanceMethod get_dynamic_object_avoidance_method();

   /*l
    *b  Description:
    **
    **    This function sets the static avoidance method that members of this
    **    crowd will use to avoid walking through fixed walls and objects.
    **    Usually these are scene objects and fixed props.
    **
    **    The enumeration is defined in diguy_constants.h.
    **
    *b  Arguments:
    **
    *a    method - avoidance method to use
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   void set_static_object_avoidance_method(diguyStaticAvoidanceMethod method);

   /*l
    *b  Returns:
    **
    **    current static object avoidance method;
    **    see set_static_object_avoidance_method()
    */
   diguyStaticAvoidanceMethod get_static_object_avoidance_method();


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    Many of the diguyCrowd callbacks set a callback character which
    **    represents if there was a particular character that the callback
    **    relates to.  A few of the callbacks do not set this value.
    **
    *b  Returns:
    **
    **    pointer of type diguyCharacter; NULL if there was no associated
    **    character
    */
   diguyCharacter* get_callback_character();

   /*l
    *b  Description:
    **
    **    Many of the diguyCrowd callbacks set a callback impact which
    **    represents if there was impact that the callback relates to.  A few
    **    of the callbacks do not set this value.
    **
    *b  Returns:
    **
    **    pointer of type diguyImpact; NULL if there was no associated
    **    impact
    */
   diguyImpact* get_callback_impact();

   /*l
    *b  Description:
    **
    **    This is an enumeration of the different callbacks that can be
    **    registered with add_callback() and add_callback_script().
    **
    *i    CALLBACK_ID_CREATE
    **
    **      This callback will be called when a new crowd is created.
    **
    **      Note that this callback can only be added by calling
    **      diguyScenario::add_default_crowd_callback(); adding it
    **      with diguyCrowd::add_callback() will have no effect, as
    **      by that time the crowd has already been created.
    **      There is no associated callback character.
    **
    *i    CALLBACK_ID_DESTROY
    **
    **      This callback will be called when a crowd is destroyed. There
    **      is no associated callback character.
    **
    *i    CALLBACK_ID_CROWD_MEMBER_KILLED
    **
    **      This callback will be called when a member of the crowd is
    **      killed.
    **
    *-      - The callback character is the crowd member that was killed.
    *-      - The callback impact contains the impact information.
    **
    *i    CALLBACK_ID_CROWD_MEMBER_IMPACT
    **
    **      Similar to diguyCharacter::CALLBACK_ID_IMPACT, this callback will
    **      be called when a member of the crowd is hit by a detonation.  If
    **      this callback isn't present the impacted character automatically
    **      will die.  Handling this callback allows for the implementation
    **      of custom damage models at a crowd level.
    **
    *-      - The callback character is the crowd member that was hit.
    *-      - The callback impact contains the impact information.
    **
    *i    CALLBACK_ID_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.
    **
    *-      - The callback character is the character that caused the
    *-        detonation.
    *-      - The callback impact contains the impact information.
    **
    *i    CALLBACK_ID_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 callback character is the character that fired the weapon.
    **
    **    Callbacks return a value of type diguyCallbackReturn,
    **    which will be DIGUY_CALLBACK_STOP or DIGUY_CALLBACK_CONTINUE.
    **    If the callback returns DIGUY_CALLBACK_STOP, the default handler
    **    of the function will not be called; the callback is asserting
    **    that it has done everything necessary for the function call.
    **    If the callback returns DIGUY_CALLBACK_CONTINUE, the default
    **    handler for the function will be called after the callback.
    **
    *b  Usable From:
    **
    *-    - C++
    *-    - Script
    */
   enum {
      CALLBACK_ID_CREATE = 1,
      CALLBACK_ID_DESTROY,
      CALLBACK_ID_CROWD_MEMBER_KILLED,
      CALLBACK_ID_CROWD_MEMBER_IMPACT,
      CALLBACK_ID_NEARBY_SCENE_OBJECT_IMPACT,
      CALLBACK_ID_NEARBY_WEAPON_FIRED,
//       CALLBACK_ID_RENAME,
      CALLBACK_ID_SETPUBLISHED
   };

#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                      diguyCrowdRegionCallback (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
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int add_callback(int callback_id,
      diguyCrowdCallback* 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                      diguyCrowdCallback (typedefed above)
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int remove_callback(int callback_id,
      diguyCrowdCallback* 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 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().
    **
    **    See diguyCharacter::add_callback_script() for an example of use.
    **
    *b  Arguments:
    **
    *a    callback_id          - integer id of the callback
    *a    callback_script      - script text of callback to be added
    *a    callback_script_type - the type of script contained in
    *a                           callback_script
    **
    **    If NULL is passed for callback_script_type, a default script type
    **    will be derived based on the default script interpreter of the
    **    scenario.
    **
    *i  lua specific:
    **
    **    When the script is called, the object for which it is being called
    **    will be in the callback_object global.
    **
    **    To pass NULL when calling from a lua script, use nil.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int add_callback_script(int callback_id,
      const char* callback_script,
      const char* callback_script_type = NULL);

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

#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    Equivalent to calling diguyCharacter::add_callback() for all
    **    members of the crowd.
    **
    **    *Note*: callback_id should be a *diguyCharacter* id, not a
    **    diguyCrowd id.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   void all_members_add_character_callback(int callback_id,
      diguyCharacterCallback* callback,
      void* callback_params = NULL,
      void* callback_user_data = NULL);

   /*l
    *b  Description:
    **
    **    Equivalent to calling diguyCharacter::remove_callback() for all
    **    members of the crowd.
    **
    **    *Note*: callback_id should be a *diguyCharacter* id, not a
    **    diguyCrowd id.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   void all_members_remove_character_callback(int callback_id,
      diguyCharacterCallback* callback);

   /*l
    *b  Description:
    **
    **    Equivalent to calling diguyCharacter::remove_callback_with_user_data()
    **    for all members of the crowd.
    **
    **    *Note*: callback_id should be a *diguyCharacter* id, not a
    **    diguyCrowd id.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   void all_members_remove_character_callback_with_user_data(int callback_id,
      void* callback_user_data);

#endif

   /*l
    *b  Description:
    **
    **    Equivalent to calling diguyCharacter::add_callback_script() for all
    **    members of the crowd.
    **
    **    *Note*: callback_id should be a *diguyCharacter* id, not a
    **    diguyCrowd id.
    */
   void all_members_add_character_callback_script(int callback_id,
      const char* callback_script,
      const char* callback_script_type = NULL);

   /*l
    *b  Description:
    **
    **    Equivalent to calling diguyCharacter::remove_callback_script() for
    **    all members of the crowd.
    **
    **    *Note*: callback_id should be a *diguyCharacter* id, not a
    **    diguyCrowd id.
    */
   void all_members_remove_character_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 scene object callback function registered by
    *-        diguyScenario::register_crowd_event_handler() or
    *-        diguyScenario::register_crowd_event_handler_from_library()
    *-      - a script registered by
    *-        diguyScenario::register_crowd_event_handler_script()
    *-      - a Script, Decision, or Library Function in the scenario
    *-        whose "Event Type" is "Crowd"
    **
    *b  Arguments:
    **
    *a    callback_id        - integer id of callback
    *a    handler_name       - name of the event handler to map
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int map_event_handler_to_callback_id(int callback_id,
      const char* handler_name);

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


/*****************************************************************************/
   /*l
    *b  Returns:
    **
    **    diguyRegion associated with the crowd; will be created if it
    **    doesn't currently exist
    */
   diguyRegion* find_or_create_region();

   /*l
    *b  Returns:
    **
    **    diguyRegion associated with the crowd; may be NULL
    */
   diguyRegion* get_region();


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    Equivalent to calling diguyCharacter::agent_accept_message() for
    **    all members of the crowd.
    **
    *b  Arguments:
    **
    *a    message_type   - what type of message is being sent
    *a    message        - the message string
    *a    message_params - optional parameter string
    */
   void send_message_to_all_members(const char* message_type,
      const char* message,
      const char* message_params = NULL);


/*****************************************************************************/
   void                 set_unit_type(diguyTacticsUnitType tut);
   diguyTacticsUnitType get_unit_type();

   int                  set_unit_leader(diguyCharacter* leader);
   diguyCharacter*      get_unit_leader();


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function sets the Marking Text for crowds 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 crowds.
    **    The Marking Text is set internally for reflected crowds.
    **
    *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 crowds.
    **
    **    For published crowds this value will be what was most
    **    recently set by set_network_marking().
    **
    **    For reflected crowds this value will be read from the
    **    reflected crowds' entity state information.
    **
    *b  Returns:
    **
    **    Crowds'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 crowd 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 0, the crowd is *not* published.
    **
    **    This function should *not* be called for reflected crowds.
    **    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 crowd is published
    **    by DI-Guy Networking.  It will always return 0 for reflected
    **    crowds.
    **
    **    This function can be called for any crowd.
    **
    *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.
    */
   DtAggregateStateRepository * get_vrlink_entity_state_repository();

   /*l
    *b  Description:
    **
    **    This function returns whether the crowd is a
    **    reflected crowd created by DI-Guy Networking.
    **
    **    This function can be called for any crowd.
    **
    *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 crowd is in a
    **    "paused" state.  This will only be true for reflected
    **    crowds.
    **
    **    A reflected crowd 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 crowd is reflecting a published crowd
    **    of a DI-Guy Scenario application that is in a paused or
    **    stopped state.
    **
    **    If DI-Guy Scenario, paused crowds 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 crowd's "network entity number".
    **    This number is valid and persistent regardless of whether the
    **    crowd is currently published.
    **
    **    This number is primarily used internally by DI-Guy Networking
    **    for creating entity IDs.
    **
    *b  Returns:
    **
    **    crowd's network entity number
    **
    *b  Callable For Networked Entities That Are:
    **
    *-    - DIS published and reflected
    *-    - HLA published and reflected
    */
   int get_network_entity_number();

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


#ifdef CPLUSPLUS_ONLY

   bdiScenarioCrowd* get_scripted_object() { return m_scripted_object; }

private:

   /*l
    **    A private constructor.
    */
   diguyCrowd( bdiScenarioCrowd* scripted_object );

   /*l
    **    A private destructor.
    */
   virtual ~diguyCrowd();

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

   friend class bdiScenarioCrowd;

#endif

};