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"

    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

    29

	/**

    30

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

    31

	 */

    32

	enum AIOrderFlags {

    33

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

    34

		AIOF_NONE              = 0,

    35

    36

		/** Transfer instead of deliver the goods; only for stations. */

    37

		AIOF_TRANSFER          = 1 << 0,

    38

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

    39

		AIOF_UNLOAD            = 1 << 1,

    40

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

    41

		AIOF_FULL_LOAD         = 1 << 2,

    42

    43

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

    44

		AIOF_SERVICE_IF_NEEDED = 1 << 2,

    45

    46

		/** Do not stop at the stations that are passed when going to the destination. */

    47

		AIOF_NON_STOP          = 1 << 3,

    48

    49

		/** For marking invalid order flags */

    50

		AIOF_INVALID           = 0xFFFF,

    51

	};

    52

    53

	/**

    54

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

    55

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

    56

	 * @param order_id The order index to check.

    57

	 * @pre AIVehicle::IsValidVehicle(vehicle_id).

    58

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

    59

	 */

    60

	static bool IsValidVehicleOrder(VehicleID vehicle_id, uint32 order_id);

    61

    62

	/**

    63

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

    64

	 * @param destination The destination of the order.

    65

	 * @param order_flags The flags given to the order.

    66

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

    67

	 */

    68

	static bool AreOrderFlagsValid(TileIndex destination, AIOrderFlags order_flags);

    69

    70

	/**

    71

	 * Returns the number of orders for the given vehicle.

    72

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

    73

	 * @pre AIVehicle::IsValidVehicle(vehicle_id).

    74

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

    75

	 *   value when the vehicle does not exist.

    76

	 */

    77

	static int32 GetNumberOfOrders(VehicleID vehicle_id);

    78

    79

	/**

    80

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

    81

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

    82

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

    83

	 * @pre IsValidVehicleOrder(vehicle_id, order_id).

    84

	 * @return The destination tile of the order.

    85

	 */

    86

	static TileIndex GetOrderDestination(VehicleID vehicle_id, uint32 order_id);

    87

    88

	/**

    89

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

    90

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

    91

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

    92

	 * @pre IsValidVehicleOrder(vehicle_id, order_id).

    93

	 * @return The AIOrderFlags of the order.

    94

	 */

    95

	static AIOrderFlags GetOrderFlags(VehicleID vehicle_id, uint32 order_id);

    96

    97

	/**

    98

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

    99

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

   100

	 * @param destination The destination of the order.

   101

	 * @param order_flags The flags given to the order.

   102

	 * @pre AIVehicle::IsValidVehicle(vehicle_id).

   103

	 * @pre AreOrderFlagsValid(destination, order_flags).

   107

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

   108

	 */

   109

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

   110

   111

	/**

   112

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

   113

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

   114

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

   115

	 * @param destination The destination of the order.

   116

	 * @param order_flags The flags given to the order.

   117

	 * @pre IsValidVehicleOrder(vehicle_id, order_id).

   118

	 * @pre AreOrderFlagsValid(destination, order_flags).

   122

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

   123

	 */

   124

	static bool InsertOrder(VehicleID vehicle_id, uint32 order_id, TileIndex destination, AIOrderFlags order_flags);

   125

   126

	/**

   127

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

   128

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

   129

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

   130

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

   132

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

   133

	 */

   134

	static bool RemoveOrder(VehicleID vehicle_id, uint32 order_id);

   135

   136

	/**

   137

	 * Changes the order flags of the given order.

   138

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

   139

	 * @param order_id The order to change.

   140

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

   141

	 * @pre IsValidVehicleOrder(vehicle_id, order_id).

   142

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

   144

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

   145

	 */

   146

	static bool ChangeOrder(VehicleID vehicle_id, uint32 order_id, AIOrderFlags order_flags);

   147

   148

	/**

   149

	 * Move an order inside the orderlist

   150

	 * @param vehicle_id The vehicle to move the orders.

   151

	 * @param order_id_move The order to move.

   152

	 * @param order_id_target The target order

   153

	 * @pre IsValidVehicleOrder(vehicle_id, order_id_move).

   154

	 * @pre IsValidVehicleOrder(vehicle_id, order_id_target).

   156

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

   157

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

   158

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

   159

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

   160

	 *  downwards (e.g. 8).

   161

	 */

   162

	static bool MoveOrder(VehicleID vehicle_id, uint32 order_id_move, uint32 order_id_target);

   163

   164

	/**

   165

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

   166

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

   167

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

   168

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

   169

	 * @pre AIVehicle::IsValidVehicle(vehicle_id).

   170

	 * @pre AIVehicle::IsValidVehicle(main_vehicle_id).

   173

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

   174

	 */

   175

	static bool CopyOrders(VehicleID vehicle_id, VehicleID main_vehicle_id);

   176

   177

	/**

   178

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

   179

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

   180

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

   181

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

   182

	 * @pre AIVehicle::IsValidVehicle(vehicle_id).

   183

	 * @pre AIVehicle::IsValidVehicle(main_vehicle_id).

   185

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

   186

	 */

   187

	static bool ShareOrders(VehicleID vehicle_id, VehicleID main_vehicle_id);

   188

   189

	/**

   190

	 * Removes the given vehicle from a shared orders list.

   191

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

   192

	 * @pre AIVehicle::IsValidVehicle(vehicle_id).

   193

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

   194

	 */

   195

	static bool UnshareOrders(VehicleID vehicle_id);

   196

};

   197

DECLARE_ENUM_AS_BIT_SET(AIOrder::AIOrderFlags);

   198

   199

#endif /* AI_ORDER_HPP */