(svn r15027) -Merge: tomatos and bananas left to be, here is NoAI for all to see.

  NoAI is an API (a framework) to build your own AIs in. See:
   http://wiki.openttd.org/wiki/index.php/AI:Main_Page
 With many thanks to:
  - glx and Rubidium for their syncing, feedback and hard work
  - Yexo for his feedback, patches, and AIs which tested the system very deep
  - Morloth for his feedback and patches
  - TJIP for hosting a challenge which kept NoAI on track
  - All AI authors for testing our AI API, and all other people who helped in one way or another
-Remove: all old AIs and their cheats/hacks

1 files changed, 170 insertions, 0 deletions

diff --git a/src/ai/api/ai_group.hpp b/src/ai/api/ai_group.hpp
new file mode 100644
index 000000000..84569c562
--- /dev/null
+++ b/src/ai/api/ai_group.hpp
@@ -0,0 +1,170 @@
+/* $Id$ */
+
+/** @file ai_group.hpp Everything to put vehicles into groups. */
+
+#ifndef AI_GROUP_HPP
+#define AI_GROUP_HPP
+
+#include "ai_object.hpp"
+#include "ai_vehicle.hpp"
+
+/**
+ * Class that handles all group related functions.
+ */
+class AIGroup : public AIObject {
+public:
+	static const char *GetClassName() { return "AIGroup"; }
+
+	/**
+	 * The group IDs of some special groups.
+	 */
+	enum GroupID {
+		/* Values are important, as they represent the internal state of the game (see group_type.h). */
+		ALL_GROUP = 0xFFFD,     //!< All vehicles are in this group.
+		DEFAULT_GROUP = 0xFFFE, //!< Vehicles not put in any other group are in this one.
+		INVALID_GROUP = 0xFFFF, //!< An invalid group id.
+	};
+
+	/**
+	 * Checks whether the given group is valid.
+	 * @param group_id The group to check.
+	 * @pre group_id != DEFAULT_GROUP && group_id != ALL_GROUP.
+	 * @return True if and only if the group is valid.
+	 */
+	static bool IsValidGroup(GroupID group_id);
+
+	/**
+	 * Create a new group.
+	 * @param vehicle_type The type of vehicle to create a group for.
+	 * @return The GroupID of the new group, or an invalid GroupID when
+	 *  it failed. Check the return value using IsValidGroup(). In test-mode
+	 *  0 is returned if it was successful; any other value indicates failure.
+	 */
+	static GroupID CreateGroup(AIVehicle::VehicleType vehicle_type);
+
+	/**
+	 * Delete the given group. When the deletion succeeds all vehicles in the
+	 *  given group will move to the DEFAULT_GROUP.
+	 * @param group_id The group to delete.
+	 * @pre IsValidGroup(group_id).
+	 * @return True if and only if the group was succesfully deleted.
+	 */
+	static bool DeleteGroup(GroupID group_id);
+
+	/**
+	 * Get the vehicle type of a group.
+	 * @param group_id The group to get the type from.
+	 * @pre IsValidGroup(group_id).
+	 * @return The vehicletype of the given group.
+	 */
+	static AIVehicle::VehicleType GetVehicleType(GroupID group_id);
+
+	/**
+	 * Set the name of a group.
+	 * @param group_id The group to set the name for.
+	 * @param name The name for the group.
+	 * @pre IsValidGroup(group_id).
+	 * @pre 'name' must have at least one character.
+	 * @pre 'name' must have at most 30 characters.
+	 * @exception AIError::ERR_NAME_IS_NOT_UNIQUE
+	 * @return True if and only if the name was changed.
+	 */
+	static bool SetName(GroupID group_id, const char *name);
+
+	/**
+	 * Get the name of a group.
+	 * @param group_id The group to get the name of.
+	 * @pre IsValidGroup(group_id).
+	 * @return The name the group has.
+	 */
+	static const char *GetName(GroupID group_id);
+
+	/**
+	 * Enable or disable autoreplace protected. If the protection is
+	 *  enabled, global autoreplace won't affect vehicles in this group.
+	 * @param group_id The group to change the protection for.
+	 * @param enable True if protection should be enabled.
+	 * @pre IsValidGroup(group_id).
+	 * @return True if and only if the protection was succesfully changed.
+	 */
+	static bool EnableAutoReplaceProtection(GroupID group_id, bool enable);
+
+	/**
+	 * Get the autoreplace protection status.
+	 * @param group_id The group to get the protection status for.
+	 * @pre IsValidGroup(group_id).
+	 * @return The autoreplace protection status for the given group.
+	 */
+	static bool GetAutoReplaceProtection(GroupID group_id);
+
+	/**
+	 * Get the number of engines in a given group.
+	 * @param group_id The group to get the number of engines in.
+	 * @param engine_id The engine id to count.
+	 * @pre IsValidGroup(group_id) || group_id == ALL_GROUP || group_id == DEFAULT_GROUP.
+	 * @return The number of engines with id engine_id in the group with id group_id.
+	 */
+	static int32 GetNumEngines(GroupID group_id, EngineID engine_id);
+
+	/**
+	 * Move a vehicle to a group.
+	 * @param group_id The group to move the vehicel to.
+	 * @param vehicle_id The vehicle to move to the group.
+	 * @pre IsValidGroup(group_id) || group_id == DEFAULT_GROUP.
+	 * @pre AIVehicle::IsValidVehicle(vehicle_id).
+	 * @return True if and only if the vehicle was succesfully moved to the group.
+	 * @note A vehicle can be in only one group at the same time. To remove it from
+	 *  a group, move it to another or to DEFAULT_GROUP. Moving the vehicle to the
+	 *  given group means removing it from another group.
+	 */
+	static bool MoveVehicle(GroupID group_id, VehicleID vehicle_id);
+
+	/**
+	 * Enable or disable the removal of wagons when a (part of a) vehicle is
+	 *  (auto)replaced with a longer variant (longer wagons or longer engines)
+	 *  If enabled, wagons are removed from the end of the vehicle until it
+	 *  fits in the same number of tiles as it did before.
+	 * @param keep_length If true, wagons will be removed if the a new engine is longer.
+	 * @return True if and only if the value was succesfully changed.
+	 */
+	static bool EnableWagonRemoval(bool keep_length);
+
+	/**
+	 * Get the current status of wagon removal.
+	 * @return Whether or not wagon removal is enabled.
+	 */
+	static bool HasWagonRemoval();
+
+	/**
+	 * Start replacing all vehicles with a specified engine with another engine.
+	 * @param group_id The group to replace vehicles from. Use ALL_GROUP to replace
+	 *  vehicles from all groups that haven't set autoreplace protection.
+	 * @param engine_id_old The engine id to start replacing.
+	 * @param engine_id_new The engine id to replace with.
+	 * @pre IsValidGroup(group_id) || group_id == ALL_GROUP.
+	 * @pre AIEngine.IsValidEngine(engine_id_new).
+	 * @note To stop autoreplacing engine_id_old, call StopAutoReplace(group_id, engine_id_old).
+	 */
+	static bool SetAutoReplace(GroupID group_id, EngineID engine_id_old, EngineID engine_id_new);
+
+	/**
+	 * Get the EngineID the given EngineID is replaced with.
+	 * @param group_id The group to get the replacement from.
+	 * @param engine_id The engine that is being replaced.
+	 * @pre IsValidGroup(group_id) || group_id == ALL_GROUP.
+	 * @return The EngineID that is replacing engine_id or an invalid EngineID
+	 *   in case engine_id is not begin replaced.
+	 */
+	static EngineID GetEngineReplacement(GroupID group_id, EngineID engine_id);
+
+	/**
+	 * Stop replacing a certain engine in the specified group.
+	 * @param group_id The group to stop replacing the engine in.
+	 * @param engine_id The engine id to stop replacing with another engine.
+	 * @pre IsValidGroup(group_id) || group_id == ALL_GROUP.
+	 * @return True if and if the replacing was succesfully stopped.
+	 */
+	static bool StopAutoReplace(GroupID group_id, EngineID engine_id);
+};
+
+#endif /* AI_GROUP_HPP */