1

/* $Id$ */

     2

     3

/** @file ai_group.hpp Everything to put vehicles into groups. */

     4

     5

#ifndef AI_GROUP_HPP

     6

#define AI_GROUP_HPP

     7

     8

#include "ai_object.hpp"

     9

#include "ai_vehicle.hpp"

    10

    11

/**

    12

 * Class that handles all group related functions.

    13

 */

    14

class AIGroup : public AIObject {

    15

public:

    16

	static const char *GetClassName() { return "AIGroup"; }

    17

    18

	/**

    19

	 * The group IDs of some special groups.

    20

	 */

    21

	enum GroupID {

    22

		/* Values are important, as they represent the internal state of the game (see group_type.h). */

    23

		ALL_GROUP = 0xFFFD,     //!< All vehicles are in this group.

    24

		DEFAULT_GROUP = 0xFFFE, //!< Vehicles not put in any other group are in this one.

    25

		INVALID_GROUP = 0xFFFF, //!< An invalid group id.

    26

	};

    27

    28

	/**

    29

	 * Checks whether the given group is valid.

    30

	 * @param group_id The group to check.

    31

	 * @pre group_id != DEFAULT_GROUP && group_id != ALL_GROUP.

    32

	 * @return True if and only if the group is valid.

    33

	 */

    34

	static bool IsValidGroup(GroupID group_id);

    35

    36

	/**

    37

	 * Create a new group.

    38

	 * @param vehicle_type The type of vehicle to create a group for.

    39

	 * @return The GroupID of the new group, or an invalid GroupID when

    40

	 *  it failed. Check the return value using IsValidGroup(). In test-mode

    41

	 *  0 is returned if it was successful; any other value indicates failure.

    42

	 */

    43

	static GroupID CreateGroup(AIVehicle::VehicleType vehicle_type);

    44

    45

	/**

    46

	 * Delete the given group. When the deletion succeeds all vehicles in the

    47

	 *  given group will move to the DEFAULT_GROUP.

    48

	 * @param group_id The group to delete.

    49

	 * @pre IsValidGroup(group_id).

    50

	 * @return True if and only if the group was succesfully deleted.

    51

	 */

    52

	static bool DeleteGroup(GroupID group_id);

    53

    54

	/**

    55

	 * Get the vehicle type of a group.

    56

	 * @param group_id The group to get the type from.

    57

	 * @pre IsValidGroup(group_id).

    58

	 * @return The vehicletype of the given group.

    59

	 */

    60

	static AIVehicle::VehicleType GetVehicleType(GroupID group_id);

    61

    62

	/**

    63

	 * Set the name of a group.

    64

	 * @param group_id The group to set the name for.

    65

	 * @param name The name for the group.

    66

	 * @pre IsValidGroup(group_id).

    67

	 * @pre Name has to be unique.

    68

	 * @pre Name has to be at least one character long.

    69

	 * @return True if and only if the name was changed.

    70

	 */

    71

	static bool SetName(GroupID group_id, const char *name);

    72

    73

	/**

    74

	 * Get the name of a group.

    75

	 * @param group_id The group to get the name of.

    76

	 * @pre IsValidGroup(group_id).

    77

	 * @return The name the group has.

    78

	 */

    79

	static char *GetName(GroupID group_id);

    80

    81

	/**

    82

	 * Enable or disable autoreplace protected. If the protection is

    83

	 *  enabled, global autoreplace won't affect vehicles in this group.

    84

	 * @param group_id The group to change the protection for.

    85

	 * @param enable True if protection should be enabled.

    86

	 * @pre IsValidGroup(group_id).

    87

	 * @return True if and only if the protection was succesfully changed.

    88

	 */

    89

	static bool EnableAutoReplaceProtection(GroupID group_id, bool enable);

    90

    91

	/**

    92

	 * Get the autoreplace protection status.

    93

	 * @param group_id The group to get the protection status for.

    94

	 * @pre IsValidGroup(group_id).

    95

	 * @return The autoreplace protection status for the given group.

    96

	 */

    97

	static bool GetAutoReplaceProtection(GroupID group_id);

    98

    99

	/**

   100

	 * Get the number of engines in a given group.

   101

	 * @param group_id The group to get the number of engines in.

   102

	 * @param engine_id The engine id to count.

   103

	 * @pre IsValidGroup(group_id) || group_id == ALL_GROUP || group_id == DEFAULT_GROUP.

   104

	 * @return The number of engines with id engine_id in the group with id group_id.

   105

	 */

   106

	static int32 GetNumEngines(GroupID group_id, EngineID engine_id);

   107

   108

	/**

   109

	 * Move a vehicle to a group.

   110

	 * @param group_id The group to move the vehicel to.

   111

	 * @param vehicle_id The vehicle to move to the group.

   112

	 * @pre IsValidGroup(group_id) || group_id == DEFAULT_GROUP.

   113

	 * @pre AIVehicle::IsValidVehicle(vehicle_id).

   114

	 * @return True if and only if the vehicle was succesfully moved to the group.

   115

	 * @note A vehicle can be in only one group at the same time. To remove it from

   116

	 *  a group, move it to another or to DEFAULT_GROUP. Moving the vehicle to the

   117

	 *  given group means removing it from another group.

   118

	 */

   119

	static bool MoveVehicle(GroupID group_id, VehicleID vehicle_id);

   120

   121

	/**

   122

	 * Start replacing all vehicles with a specified engine with another engine.

   123

	 * @param group_id The group to replace vehicles from. Use ALL_GROUP to replace

   124

	 *  vehicles from all groups that haven't set autoreplace protection.

   125

	 * @param engine_id_old The engine id to start replacing.

   126

	 * @param engine_id_new The engine id to replace with.

   127

	 * @pre IsValidGroup(group_id) || group_id == ALL_GROUP.

   128

	 * @pre AIEngine.IsValidEngine(engine_id_new).

   129

	 * @note To stop autoreplacing engine_id_old, call StopAutoReplace(group_id, engine_id_old).

   130

	 */

   131

	static bool SetAutoReplace(GroupID group_id, EngineID engine_id_old, EngineID engine_id_new);

   132

   133

	/**

   134

	 * Get the EngineID the given EngineID is replaced with.

   135

	 * @param group_id The group to get the replacement from.

   136

	 * @param engine_id The engine that is being replaced.

   137

	 * @pre IsValidGroup(group_id) || group_id == ALL_GROUP.

   138

	 * @return The EngineID that is replacing engine_id or an invalid EngineID

   139

	 *   in case engine_id is not begin replaced.

   140

	 */

   141

	static EngineID GetEngineReplacement(GroupID group_id, EngineID engine_id);

   142

   143

	/**

   144

	 * Stop replacing a certain engine in the specified group.

   145

	 * @param group_id The group to stop replacing the engine in.

   146

	 * @param engine_id The engine id to stop replacing with another engine.

   147

	 * @pre IsValidGroup(group_id) || group_id == ALL_GROUP.

   148

	 * @return True if and if the replacing was succesfully stopped.

   149

	 */

   150

	static bool StopAutoReplace(GroupID group_id, EngineID engine_id);

   151

};

   152

   153

#endif /* AI_GROUP_HPP */