1

/* $Id$ */

     2

     3

/** @file ai_order.hpp Everything to query and build orders. */

     4

     5

#ifndef AI_ORDER_HPP

     6

#define AI_ORDER_HPP

     7

     8

#include "ai_object.hpp"

     9

#include "ai_error.hpp"

    10

    11

/**

    12

 * Class that handles all order related functions.

    13

 */

    14

class AIOrder : public AIObject {

    15

public:

    16

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

    17

    18

	/**

    19

	 * All order related error messages.

    20

	 */

    21

	enum ErrorMessages {

    22

		/** Base for all order related errors */

    23

		ERR_ORDER_BASE = AIError::ERR_CAT_ORDER << AIError::ERR_CAT_BIT_SIZE,

    24

    25

		/** No more space for orders */

    26

		ERR_ORDER_TOO_MANY,                                  // [STR_8831_NO_MORE_SPACE_FOR_ORDERS]

    27

    28

		/** Destination of new order is to far away from the previous order */

    29

		ERR_ORDER_TOO_FAR_AWAY_FROM_PREVIOUS_DESTINATION,    // [STR_0210_TOO_FAR_FROM_PREVIOUS_DESTINATIO]

    30

	};

    31

    32

	/**

    33

	 * Flags that can be used to modify the behaviour of orders.

    34

	 */

    35

	enum AIOrderFlags {

    36

		/** Just go to the station/depot, stop unload if possible and load if needed. */

    37

		AIOF_NONE              = 0,

    38

    39

		/** Do not stop at the stations that are passed when going to the destination. Only for trains and road vehicles. */

    40

		AIOF_NON_STOP_INTERMEDIATE = 1 << 0,

    41

		/** Do not stop at the destionation station. Only for trains and road vehicles. */

    42

		AIOF_NON_STOP_DESTINATION  = 1 << 1,

    43

    44

		/** Always unload the vehicle; only for stations. Cannot be set when AIOF_TRANSFER or AIOF_NO_UNLOAD is set. */

    45

		AIOF_UNLOAD            = 1 << 2,

    46

		/** Transfer instead of deliver the goods; only for stations. Cannot be set when AIOF_UNLOAD or AIOF_NO_UNLOAD is set. */

    47

		AIOF_TRANSFER          = 1 << 3,

    48

		/** Never unload the vehicle; only for stations. Cannot be set when AIOF_UNLOAD, AIOF_TRANSFER or AIOF_NO_LOAD is set. */

    49

		AIOF_NO_UNLOAD         = 1 << 4,

    50

    51

		/** Wait till the vehicle is fully loaded; only for stations. Cannot be set when AIOF_NO_LOAD is set. */

    52

		AIOF_FULL_LOAD         = 2 << 5,

    53

		/** Wait till at least one cargo of the vehicle is fully loaded; only for stations. Cannot be set when AIOF_NO_LOAD is set. */

    54

		AIOF_FULL_LOAD_ANY     = 3 << 5,

    55

		/** Do not load any cargo; only for stations. Cannot be set when AIOF_NO_UNLOAD, AIOF_FULL_LOAD or AIOF_FULL_LOAD_ANY is set. */

    56

		AIOF_NO_LOAD           = 1 << 7,

    57

    58

		/** Service the vehicle when needed, otherwise skip this order; only for depots. */

    59

		AIOF_SERVICE_IF_NEEDED = 1 << 2,

    60

    61

		/** All flags related to non-stop settings. */

    62

		AIOF_NON_STOP_FLAGS    = AIOF_NON_STOP_INTERMEDIATE | AIOF_NON_STOP_DESTINATION,

    63

		/** All flags related to unloading. */

    64

		AIOF_UNLOAD_FLAGS      = AIOF_TRANSFER | AIOF_UNLOAD | AIOF_NO_UNLOAD,

    65

		/** All flags related to loading. */

    66

		AIOF_LOAD_FLAGS        = AIOF_FULL_LOAD | AIOF_FULL_LOAD_ANY | AIOF_NO_LOAD,

    67

    68

		/** For marking invalid order flags */

    69

		AIOF_INVALID           = 0xFFFF,

    70

	};

    71

    72

	/** Different constants related to the OrderPosition */

    73

	enum OrderPosition {

    74

		CURRENT_ORDER = 0xFF, //!< Constant that gets resolved to the current order.

    75

		INVALID_ORDER = -1,   //!< An invalid order.

    76

	};

    77

    78

	/**

    79

	 * Checks whether the given order id is valid for the given vehicle.

    80

	 * @param vehicle_id The vehicle to check the order index for.

    81

	 * @param order_position The order index to check.

    82

	 * @pre AIVehicle::IsValidVehicle(vehicle_id).

    83

	 * @return True if and only if the order_position is valid for the given vehicle.

    84

	 */

    85

	static bool IsValidVehicleOrder(VehicleID vehicle_id, OrderPosition order_position);

    86

    87

	/**

    88

	 * Resolves the given order index to the correct index for the given vehicle.

    89

	 *  If the order index was CURRENT_ORDER it will be resolved to the index of

    90

	 *  the current order (as shown in the order list). If the order with the

    91

	 *  given index does not exist it will return INVALID_ORDER.

    92

	 * @param vehicle_id The vehicle to check the order index for.

    93

	 * @param order_position The order index to resolve.

    94

	 * @pre AIVehicle::IsValidVehicle(vehicle_id).

    95

	 * @return The resolved order index.

    96

	 */

    97

	static OrderPosition ResolveOrderPosition(VehicleID vehicle_id, OrderPosition order_position);

    98

    99

	/**

   100

	 * Checks whether the given order flags are valid for the given destination.

   101

	 * @param destination The destination of the order.

   102

	 * @param order_flags The flags given to the order.

   103

	 * @return True if and only if the order_flags are valid for the given location.

   104

	 */

   105

	static bool AreOrderFlagsValid(TileIndex destination, AIOrderFlags order_flags);

   106

   107

	/**

   108

	 * Returns the number of orders for the given vehicle.

   109

	 * @param vehicle_id The vehicle to get the order count of.

   110

	 * @pre AIVehicle::IsValidVehicle(vehicle_id).

   111

	 * @return The number of orders for the given vehicle or a negative

   112

	 *   value when the vehicle does not exist.

   113

	 */

   114

	static int32 GetOrderCount(VehicleID vehicle_id);

   115

   116

	/**

   117

	 * Gets the destination of the given order for the given vehicle.

   118

	 * @param vehicle_id The vehicle to get the destination for.

   119

	 * @param order_position The order to get the destination for.

   120

	 * @pre IsValidVehicleOrder(vehicle_id, order_position).

   121

	 * @note Giving CURRENT_ORDER as order_position will give the order that is

   122

	 *  currently being executed by the vehicle. This is not necessarily the

   123

	 *  current order as given by ResolveOrderPosition (the current index in the

   124

	 *  order list) as manual or autoservicing depot orders do not show up

   125

	 *  in the orderlist, but they can be the current order of a vehicle.

   126

	 * @return The destination tile of the order.

   127

	 */

   128

	static TileIndex GetOrderDestination(VehicleID vehicle_id, OrderPosition order_position);

   129

   130

	/**

   131

	 * Gets the AIOrderFlags of the given order for the given vehicle.

   132

	 * @param vehicle_id The vehicle to get the destination for.

   133

	 * @param order_position The order to get the destination for.

   134

	 * @pre IsValidVehicleOrder(vehicle_id, order_position).

   135

	 * @note Giving CURRENT_ORDER as order_position will give the order that is

   136

	 *  currently being executed by the vehicle. This is not necessarily the

   137

	 *  current order as given by ResolveOrderPosition (the current index in the

   138

	 *  order list) as manual or autoservicing depot orders do not show up

   139

	 *  in the orderlist, but they can be the current order of a vehicle.

   140

	 * @return The AIOrderFlags of the order.

   141

	 */

   142

	static AIOrderFlags GetOrderFlags(VehicleID vehicle_id, OrderPosition order_position);

   143

   144

	/**

   145

	 * Appends an order to the end of the vehicle's order list.

   146

	 * @param vehicle_id The vehicle to append the order to.

   147

	 * @param destination The destination of the order.

   148

	 * @param order_flags The flags given to the order.

   149

	 * @pre AIVehicle::IsValidVehicle(vehicle_id).

   150

	 * @pre AreOrderFlagsValid(destination, order_flags).

   151

	 * @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY

   152

	 * @exception AIOrder::ERR_ORDER_NO_MORE_SPACE

   153

	 * @exception AIOrder::ERR_ORDER_TOO_FAR_AWAY_FROM_PREVIOUS_DESTINATION

   154

	 * @return True if and only if the order was appended.

   155

	 */

   156

	static bool AppendOrder(VehicleID vehicle_id, TileIndex destination, AIOrderFlags order_flags);

   157

   158

	/**

   159

	 * Inserts an order before the given order_position into the vehicle's order list.

   160

	 * @param vehicle_id The vehicle to add the order to.

   161

	 * @param order_position The order to place the new order before.

   162

	 * @param destination The destination of the order.

   163

	 * @param order_flags The flags given to the order.

   164

	 * @pre IsValidVehicleOrder(vehicle_id, order_position).

   165

	 * @pre AreOrderFlagsValid(destination, order_flags).

   166

	 * @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY

   167

	 * @exception AIOrder::ERR_ORDER_NO_MORE_SPACE

   168

	 * @exception AIOrder::ERR_ORDER_TOO_FAR_AWAY_FROM_PREVIOUS_DESTINATION

   169

	 * @return True if and only if the order was inserted.

   170

	 */

   171

	static bool InsertOrder(VehicleID vehicle_id, OrderPosition order_position, TileIndex destination, AIOrderFlags order_flags);

   172

   173

	/**

   174

	 * Removes an order from the vehicle's order list.

   175

	 * @param vehicle_id The vehicle to remove the order from.

   176

	 * @param order_position The order to remove from the order list.

   177

	 * @pre AIVehicle::IsValidVehicleOrder(vehicle_id, order_position).

   178

	 * @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY

   179

	 * @return True if and only if the order was removed.

   180

	 */

   181

	static bool RemoveOrder(VehicleID vehicle_id, OrderPosition order_position);

   182

   183

	/**

   184

	 * Changes the order flags of the given order.

   185

	 * @param vehicle_id The vehicle to change the order of.

   186

	 * @param order_position The order to change.

   187

	 * @param order_flags The new flags given to the order.

   188

	 * @pre IsValidVehicleOrder(vehicle_id, order_position).

   189

	 * @pre AreOrderFlagsValid(GetOrderDestination(vehicle_id, order_position), order_flags).

   190

	 * @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY

   191

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

   192

	 */

   193

	static bool ChangeOrder(VehicleID vehicle_id, OrderPosition order_position, AIOrderFlags order_flags);

   194

   195

	/**

   196

	 * Move an order inside the orderlist

   197

	 * @param vehicle_id The vehicle to move the orders.

   198

	 * @param order_position_move The order to move.

   199

	 * @param order_position_target The target order

   200

	 * @pre IsValidVehicleOrder(vehicle_id, order_position_move).

   201

	 * @pre IsValidVehicleOrder(vehicle_id, order_position_target).

   202

	 * @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY

   203

	 * @return True if and only if the order was moved.

   204

	 * @note If the order is moved to a lower place (e.g. from 7 to 2)

   205

	 *  the target order is moved upwards (e.g. 3). If the order is moved

   206

	 *  to a higher place (e.g. from 7 to 9) the target will be moved

   207

	 *  downwards (e.g. 8).

   208

	 */

   209

	static bool MoveOrder(VehicleID vehicle_id, OrderPosition order_position_move, OrderPosition order_position_target);

   210

   211

	/**

   212

	 * Copies the orders from another vehicle. The orders of the main vehicle

   213

	 *  are going to be the orders of the changed vehicle.

   214

	 * @param vehicle_id The vehicle to copy the orders to.

   215

	 * @param main_vehicle_id The vehicle to copy the orders from.

   216

	 * @pre AIVehicle::IsValidVehicle(vehicle_id).

   217

	 * @pre AIVehicle::IsValidVehicle(main_vehicle_id).

   218

	 * @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY

   219

	 * @exception AIOrder::ERR_ORDER_NO_MORE_SPACE

   220

	 * @return True if and only if the copying succeeded.

   221

	 */

   222

	static bool CopyOrders(VehicleID vehicle_id, VehicleID main_vehicle_id);

   223

   224

	/**

   225

	 * Shares the orders between two vehicles. The orders of the main

   226

	 * vehicle are going to be the orders of the changed vehicle.

   227

	 * @param vehicle_id The vehicle to add to the shared order list.

   228

	 * @param main_vehicle_id The vehicle to share the orders with.

   229

	 * @pre AIVehicle::IsValidVehicle(vehicle_id).

   230

	 * @pre AIVehicle::IsValidVehicle(main_vehicle_id).

   231

	 * @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY

   232

	 * @return True if and only if the sharing succeeded.

   233

	 */

   234

	static bool ShareOrders(VehicleID vehicle_id, VehicleID main_vehicle_id);

   235

   236

	/**

   237

	 * Removes the given vehicle from a shared orders list.

   238

	 * @param vehicle_id The vehicle to remove from the shared order list.

   239

	 * @pre AIVehicle::IsValidVehicle(vehicle_id).

   240

	 * @return True if and only if the unsharing succeeded.

   241

	 */

   242

	static bool UnshareOrders(VehicleID vehicle_id);

   243

};

   244

DECLARE_ENUM_AS_BIT_SET(AIOrder::AIOrderFlags);

   245

   246

#endif /* AI_ORDER_HPP */