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

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

#ifndef __diguyFormation_H
#define __diguyFormation_H

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

#ifdef CPLUSPLUS_ONLY

class bdiScenarioFormation;
class diguyFormation;
class diguyCharacter;

#endif


#include <declspec_diguy.h>

/*!
 ** \class diguyFormation
 ** \ingroup diguyCore
 ** \brief A class that represents the layout of a group of characters.
 **
 ** Usually, this is used for military-style formations.
*/

/****************************************************************************/
class BDI_DECLSPEC_diguy diguyFormation
{

public:
/*****************************************************************************/
/**
 *2  General Functions
 **
 **  Unless otherwise specified, all are callable from:
 **
 *-    - C++
 *-    - Script
 */

   /*l
    *b  Description:
    **
    **    Returns the name of the object.  This pointer will never be NULL.
    **
    *b  Returns:
    **
    **    name of the object
    */
   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:
    **
    **    type name of the object; this value will never be NULL
    */
   const char* get_type_name();


   /*l
    *b  Returns:
    **
    **    guide name used by this formation
    */
   const char* get_guide_name();

   /*l
    *b  Description:
    **
    **    Sets number of followers in the formation.
    **
    *b  Arguments:
    **
    *a    number - number of followers in this formation
    **
    *b  Returns:
    **
    **    0 if success
    */
   int set_num_followers(int number);

   /*l
    *b  Returns:
    **
    **    number of members of formation (leader not included)
    */
   int get_num_followers();

   /*l
    *b  Description:
    **
    **    Sets rz offset of member relative to leader.
    **
    *b  Arguments:
    **
    *a    follower_index - index of follower to modify
    *a    rz             - orientation of member relative to leader, in
    *a                     degrees
    **
    *b  Returns:
    **
    **    0 if success
    */
   int set_follower_rz_offset(int follower_index, float rz);

   /*l
    *b  Description:
    **
    **    Creates a string describing the formation, with positions being
    **    relative to relative_x and relative_y.
    **
    *b  Arguments:
    **
    *a    relative_x, relative_y - relative positions in meters
    **
    *b  Returns:
    **
    **    string containing lua script
    */
   const char* to_lua_string(float relative_x = 0.0f,
      float relative_y = 0.0f);

   /*l
    *b  Description:
    **
    **    Gets x offset of formation member relative to leader.
    **
    *b  Arguments:
    **
    *a    follower_index - index of follower in formation (does not include leader)
    **
    *b  Returns:
    **
    **    x offset in meters
    */
   float get_follower_x_offset(int follower_index);

   /*l
    *b  Description:
    **
    **    Gets y offset of formation member relative to leader.
    **
    *b  Arguments:
    **
    *a    follower_index - index of follower in formation (does not include leader)
    **
    *b  Returns:
    **
    **    y offset in meters
    */
   float get_follower_y_offset(int follower_index);

   /*l
    *b  Description:
    **
    **    Gets rz (or yaw) of formation member relative to leader.
    **
    *b  Arguments:
    **
    *a    follower_index - index of follower in formation (does not include leader)
    **
    *b  Returns:
    **
    **    rz offset in degrees
    */
   float get_follower_rz_offset(int follower_index);

   /*l
    *b  Description:
    **
    **    Sets role name of member.
    **
    *b  Arguments:
    **
    *a    follower_index - index of follower to modify
    *a    role_name      - new role
    **
    *b  Returns:
    **
    **    0 if success
    */
   int set_role_name(int follower_index, const char* role_name);

   /*l
    *b  Description:
    **
    **    Gets role.  Roles generally correlate with a character's carried
    **    object.
    **
    *    RYAN:  Give a little more information on what roles are, and at
    *    least one example.
    **
    *b  Arguments:
    **
    *a    follower_index - index of follower in formation (does not include
    *a                     leader)
    **
    *b  Returns:
    **
    **    string containing role, or "character" if specific role specified
    */
   const char* get_role_name(int follower_index);

   /*l
    *b  Arguments:
    **
    *a    follower_index - index of follower in formation (does not include leader)
    **
    *b  Returns:
    **
    **    string containing name of follower, if defined
    */
   const char* get_follower_instance(int follower_index);

   /*l
    *b  Arguments:
    **
    *a    follower_index - index of follower in formation (does not include leader)
    *a    string containing name of follower,
    */
   int set_follower_instance(int follower_index, const char * name);

   /*l
    *b  Description:
    **
    **    Sets subgroup size.  If > 0, this means that there are subgroups
    **    and that they will be applied.
    **
    *    RYAN:  What is a subgroup?  What is it used for?  Can there be
    *    only one?
    **
    *b  Arguments:
    **
    *a    size - size of subgroup
    **
    *b  Returns:
    **
    **    0 if success
    */
   int set_subgroup_size(int size);

   /*l
    *b  Description:
    **
    **    Gets size of subgroup.  If > 0, this means that there are subgroups
    **    and that they will be applied.
    **
    *b  Returns:
    **
    **    number of followers in subgroup
    */
   int get_subgroup_size();

   /*l
    *b  Description:
    **
    **    Get number of subgroups
    **
    *b  Returns:
    **
    **    number of subgroups
    */
   int get_num_subgroups();

   /*l
    *b  Description:
    **
    **    Sets index of first subgroup.  Any members before this member are
    **    not in a subgroup.
    **
    *b  Arguments:
    **
    *a    index - index of first follower in subgroup
    **
    *b  Returns:
    **
    **    0 if success
    */
   int set_first_subgroup_index(int index);

   /*l
    *b  Description:
    **
    **    Gets index of first formation member that's in a subgroup.
    **
    *b  Returns:
    **
    **    index of formation member
    */
   int get_first_subgroup_index();

   /*l
    *b  Description:
    **
    **    Sets x, y offsets of member relative to leader.
    **
    *b  Arguments:
    **
    *a    follower_index - index of follower to modify
    *a    x, y           - offsets of member relative to leader, in meters
    **
    *    RYAN:  Does follower_index include leader?
    **
    *b  Returns:
    **
    **    0 if success
    */
   int set_follower_offset(int follower_index, float x, float y);

   /*l
    *b  Returns:
    **
    **    radius of formation, in meters
    **
    *    RYAN:  Radius of what?  Relative to what?  The leader?
    */
   float get_radius();


/**
 *x  The functions and variables past this point are for internal use only.
 **   No external access to them is expected or necessary.
 */
#ifdef CPLUSPLUS_ONLY
   bdiScenarioFormation* get_scripted_object() {return m_scripted_object;}

private:

   /*l
    **    A private constructor.
    */
   diguyFormation(bdiScenarioFormation* formation);

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

   friend class bdiScenarioFormation;

#endif

};

#endif /* __diguyFormation_H */

