diguyCrowd.h

Go to the documentation of this file.

/****************************************************************************
 * Copyright (c) 2023 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

};