diguyCharacterGroup.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2022 MAK Technologies, Inc.
 ** All rights reserved.
 *********************************************************************/


/*********************************************************************
 **
 *t  diguyCharacterGroup
 **
 */

#ifndef __diguyCharacterGroup_H
#define __diguyCharacterGroup_H


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

#ifdef CPLUSPLUS_ONLY
#include <stdio.h>
class bdiScenarioCharacterGroup;
class diguyCharacter;
class diguyVariable;
class diguyViewLabel;
class diguyFormation;
#endif


#include <declspec_diguy.h>

class BDI_DECLSPEC_diguy diguyCharacterGroup
{

/*****************************************************************************/
public:

   /*l
    *b  Returns:
    **
    **    name of the group; 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  Description:
    **
    **    Adds the passed character to the group if not already in it.
    **
    *b  Returns:
    **
    **    0 if the character is now a part of the group, -1 if not
    */
   int add_member(diguyCharacter* character);

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

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

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

   /*l
    *b  Description:
    **
    **    The function can be used to check if a specific character is in
    **    this group.
    **
    **    Also see diguyCharacter::is_group_member().
    **
    *b  Returns:
    **
    **    1 if the passed character is a member of the group;
    **    0 if not
    */
   int is_member(diguyCharacter* character);

   /*l
    *b  Returns:
    **
    **    number of member characters in group

    */
   int get_num_members();

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

   /*l
    *b  Returns:
    **
    **    index of member, or -1 if not found
    */
   int get_index_of_member(diguyCharacter* character);

   /*l
    *b  Description:
    **
    **    See diguyFormation for a description of subgroups.
    **
    *b  Returns:
    **
    **    subgroup number within formation of character at index,
    **    or -1
    */
   int get_subgroup_number(diguyFormation* formation, int index);

   /*l
    *b  Description:
    **
    **    See diguyFormation for a description of subgroups.
    **
    *b  Returns:
    **
    **    index within subgroup, or 0
    */
   int get_index_in_subgroup(diguyFormation* formation, int index);


   /*l
    *b  Description:
    **
    **    Sets whether all characters in group are enabled.  Equivalent to
    **    calling diguyCharacter::set_enabled() for group members.
    **
    *b  Returns:
    **
    **    Always return 0.
    */
   int set_all_members_enabled(int enabled);

   /*l
    *b  Description:
    **
    **    Updates all characters in the group.  Equivalent to calling
    **    diguyCharacter::update() for all group members.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int update_all_members(float t);

#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    This function draws all members of the group.
    **    See diguyCharacter::draw().
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int draw_all_members();

   /*l
    *b  Description:
    **
    **    This function draws pass 1 of all members of the group.
    **    See diguyCharacter::draw_pass1().
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int draw_pass1_all_members();

   /*l
    *b  Description:
    **
    **    This function draws pass 2 all members of the group.
    **    See diguyCharacter::draw_pass2().
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int draw_pass2_all_members();

#endif

   /*l
    *b  Description:
    **
    **    This function sets the current tin time of all characters
    **    in the group.  See diguyCharacter::set_current_tin().
    **
    *b  Arguments:
    **
    *a    tin - new value of current tin in seconds
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure

    */
   int set_all_members_current_tin(float tin);

   /*l
    *b  Description:
    **
    **    This function sets the current tout time of all characters
    **    in the group.  See diguyCharacter::set_current_tout().
    **
    *b  Arguments:
    **
    *a    tout - new value of current tout in seconds
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int set_all_members_current_tout(float tout);


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

    */
   diguyViewLabel* get_label();

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

   /*l
    *b  Returns:
    **
    **    how high the label of the group will float above the group centroid
    */
   float get_label_offset_above_centroid();


/*****************************************************************************/
   /*l
    *b  Returns:
    **
    **    number of variables the group has
    */
   int   get_num_variables();

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

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

   /*l
    *b  Description:
    **
    **    This function finds the variable with the given name or
    **    creates it if it doesn't exist.
    **
    *b  Arguments:
    **
    *a    name - name of the variable to find or create
    **
    *b  Returns:
    **
    **    pointer of type diguyVariable; should never be NULL
    */
   diguyVariable* find_or_create_variable(const char* name);

   /*l
    *b  Description:
    **
    **    This function destroys the passed variable.
    **
    *b  Arguments:
    **
    *a    variable - pointer to a diguyVariable
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int destroy_variable(diguyVariable* variable);


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

   int translate_all_paths(float tx, float ty, float tz);

   int rotate_all_paths_about_point(float rz, float rx, float ry,
      float rotation_pt_x, float rotation_pt_y, float rotation_pt_z);

   int rotate_all_paths_about_current_waypoint(float rz, float rx, float ry);

   /*l
    *b  Description:
    **
    **    Get the character closest to the specified point.
    **
    *b  Arguments:
    **
    *a    x, y, z - position in meters from the origin
    **
    *b  Returns:
    **
    **    pointer to diguyCharacter, or NULL in none found
    */
   diguyCharacter* get_nearest_character_to_point(float x, float y, float z);

   /*l
    *b  Description:
    **
    **    Get the character furthest from the specified point.
    **
    *b  Arguments:
    **
    *a    x, y, z - position in meters from the origin
    **
    *b  Returns:
    **
    **    pointer to diguyCharacter, or NULL if none found
    */
   diguyCharacter* get_farthest_character_to_point(float x, float y, float z);

   /*l
    *b  Description:
    **
    **    Get centroid of group (average of character positions).
    **
    *b  Arguments:
    **
    *a    x, y, z - position in meters from the origin
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int get_group_centroid(float* x, float* y, float* z);

   /*l
    *b  Description:
    **
    **    Get minimum enclosing circle of group. Note that this is slower
    **    than getting the centroid.
    **
    *b  Arguments:
    **
    *a    x, y, z - center of circle of group in meters from the origin
    *a    radius  - radius of circle
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int get_group_min_circle(float* x, float* y, float* z, float* radius);

   /*l
    *b  Description:
    **
    **    Send a message to all characters in group. See
    **    diguyCharacter::agent_accept_message().
    **
    *b  Arguments:
    **
    *a    sender         - who is sending the message
    *a    message_type   - what type of message is being sent
    *a    message        - the message string
    *a    message_params - optional parameter string
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int send_message_to_all_members(const char* sender,
      const char* message_type,
      const char* message,
      const char* message_params = NULL);

   /*l
    *b  Description:
    **
    **    Puts the group into the specified formation, applying
    **    agent_pursue_character_with_offset() to each character except the
    **    leader.
    **
    *b  Arguments:
    **
    *a    leader         - leader; can be NULL
    *a    formation      - name of formation
    *a    dir_x      - x component of the formation's heading
    *a    dir_y      - y component of the formation's heading
    *a    desired_radius - if not given (-1.0), get radius from formation
    *a    require_sort   - if 1, group must be resorted; if 0, it may still
    *a                     be
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int apply_formation_to_group_with_dir(diguyCharacter* leader,
      diguyFormation* formation,
      float dir_x,
      float dir_y,
      float desired_radius = -1.0f,
      int require_sort = 1);

   /*l
    *b  Description:
    **
    **    Puts the group into the specified formation, applying
    **    agent_pursue_character_with_offset() to each character except the
    **    leader.
    **
    *b  Arguments:
    **
    *a    leader         - leader; can be NULL
    *a    formation      - name of formation
    *a    goal_x      - x component of the formation's goal point
    *a    goal_y      - y component of the formation's goal point
    *a    desired_radius - if not given (-1.0), get radius from formation
    *a    require_sort   - if 1, group must be resorted; if 0, it may still
    *a                     be
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure

    */
   int apply_formation_to_group_with_goal(diguyCharacter* leader,
      diguyFormation* formation,
      float goal_x,
      float goal_y,
      float desired_radius = -1.0f,
      int require_sort = 1);

   /*l
    *b  Description:
    **
    **    Puts the group into the specified formation, applying
    **    agent_pursue_character_with_offset() to each character except the
    **    leader.
    **
    *b  Arguments:
    **
    *a    leader         - leader; can be NULL
    *a    formation      - name of formation
    *a    desired_radius - if not given (-1.0), get radius from formation
    *a    require_sort   - if 1, group must be resorted; if 0, it may still
    *a                     be
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int apply_formation_to_group(diguyCharacter* leader,
      diguyFormation* formation,
      float desired_radius = -1.0f,
      int require_sort = 1);

   /*l
    *b  Description:
    **
    **    Returns the last-set formation
    **
    *b  Returns:
    **
    **    The formation or NULL
    */
   diguyFormation* get_current_formation();

   /*l
    *b  Description:
    **
    **    Sorts group relative to the point given. The point should be on
    **    the left or in the front, depending on what order the formation is
    **    in.  This updates an internal list of sorted group members.
    **
    *b  Arguments:
    **
    *a    x         - x component of point
    *a    y         - y component of point
    *a    z         - z component of point
    *a    formation - the formation; pass NULL for no formation
    *a    leader    - the leader; pass NULL for no formation leader
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int sort_group_based_on_pos(float x,
      float y,
      float z,
      diguyFormation* formation = NULL,
      diguyCharacter* leader = NULL);

   /*l
    *b  Returns:
    **
    **    member of formation-sorted group; NULL if no character at index
    */
   diguyCharacter* get_sorted_member_at_index(int index);

   /*l
    *b  Returns:
    **
    **    number of active members
    */
   int get_num_active_members();

#ifdef CPLUSPLUS_ONLY

   bdiScenarioCharacterGroup* get_scripted_object() {return m_scripted_object;}

private:

   /*l
    **    A private constructor.
    */
   diguyCharacterGroup(bdiScenarioCharacterGroup* scripted_object);

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

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

   friend class bdiScenarioCharacterGroup;

#endif

};


#endif /* __diguyCharacterGroup_H */


/*********************************************************************
 ** Copyright (c) 1992-2022 MAK Technologies, Inc.
 ** All rights reserved.
 *********************************************************************/