1
/* $Id: ai_order.hpp 15684 2009-03-12 11:43:40Z yexo $ */
3
/** @file ai_order.hpp Everything to query and build orders. */
8
#include "ai_object.hpp"
9
#include "ai_error.hpp"
12
* Class that handles all order related functions.
14
class AIOrder : public AIObject {
16
static const char *GetClassName() { return "AIOrder"; }
19
* All order related error messages.
22
/** Base for all order related errors */
23
ERR_ORDER_BASE = AIError::ERR_CAT_ORDER << AIError::ERR_CAT_BIT_SIZE,
25
/** No more space for orders */
26
ERR_ORDER_TOO_MANY, // [STR_8831_NO_MORE_SPACE_FOR_ORDERS]
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]
33
* Flags that can be used to modify the behaviour of orders.
36
/** Just go to the station/depot, stop unload if possible and load if needed. */
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,
44
/** Always unload the vehicle; only for stations. Cannot be set when AIOF_TRANSFER or AIOF_NO_UNLOAD is set. */
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,
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,
58
/** Service the vehicle when needed, otherwise skip this order; only for depots. */
59
AIOF_SERVICE_IF_NEEDED = 1 << 2,
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,
68
/** For marking invalid order flags */
69
AIOF_INVALID = 0xFFFF,
73
* All conditions a conditional order can depend on.
76
/* Order _is_ important, as it's based on OrderConditionVariable in order_type.h. */
77
OC_LOAD_PERCENTAGE, //!< Skip based on the amount of load, value is in tons.
78
OC_RELIABILITY, //!< Skip based on the reliability, value is percent (0..100).
79
OC_MAX_SPEED, //!< Skip based on the maximum speed, value is in OpenTTD's internal speed unit, see AIEngine::GetMaxSpeed.
80
OC_AGE, //!< Skip based on the age, value is in years.
81
OC_REQUIRES_SERVICE, //!< Skip when the vehicle requires service, no value.
82
OC_UNCONDITIONALLY, //!< Always skip, no compare function, no value.
83
OC_INVALID = -1, //!< An invalid condition, do not use.
87
* Comparators for conditional orders.
89
enum CompareFunction {
90
/* Order _is_ important, as it's based on OrderConditionComparator in order_type.h. */
91
CF_EQUALS, //!< Skip if both values are equal
92
CF_NOT_EQUALS, //!< Skip if both values are not equal
93
CF_LESS_THAN, //!< Skip if the value is less than the limit
94
CF_LESS_EQUALS, //!< Skip if the value is less or equal to the limit
95
CF_MORE_THAN, //!< Skip if the value is more than the limit
96
CF_MORE_EQUALS, //!< Skip if the value is more or equal to the limit
97
CF_IS_TRUE, //!< Skip if the variable is true
98
CF_IS_FALSE, //!< Skip if the variable is false
99
CF_INVALID = -1, //!< Invalid compare function, do not use.
102
/** Different constants related to the OrderPosition */
104
ORDER_CURRENT = 0xFF, //!< Constant that gets resolved to the current order.
105
ORDER_INVALID = -1, //!< An invalid order.
109
* Checks whether the given order id is valid for the given vehicle.
110
* @param vehicle_id The vehicle to check the order index for.
111
* @param order_position The order index to check.
112
* @pre AIVehicle::IsValidVehicle(vehicle_id).
113
* @return True if and only if the order_position is valid for the given vehicle.
115
static bool IsValidVehicleOrder(VehicleID vehicle_id, OrderPosition order_position);
118
* Checks whether the given order is a conditional order.
119
* @param vehicle_id The vehicle to check.
120
* @param order_position The order index to check.
121
* @pre order_position != ORDER_CURRENT && IsValidVehicleOrder(vehicle_id, order_position).
122
* @return True if and only if the order is a conditional order.
124
static bool IsConditionalOrder(VehicleID vehicle_id, OrderPosition order_position);
127
* Resolves the given order index to the correct index for the given vehicle.
128
* If the order index was ORDER_CURRENT it will be resolved to the index of
129
* the current order (as shown in the order list). If the order with the
130
* given index does not exist it will return ORDER_INVALID.
131
* @param vehicle_id The vehicle to check the order index for.
132
* @param order_position The order index to resolve.
133
* @pre AIVehicle::IsValidVehicle(vehicle_id).
134
* @return The resolved order index.
136
static OrderPosition ResolveOrderPosition(VehicleID vehicle_id, OrderPosition order_position);
139
* Checks whether the given order flags are valid for the given destination.
140
* @param destination The destination of the order.
141
* @param order_flags The flags given to the order.
142
* @return True if and only if the order_flags are valid for the given location.
144
static bool AreOrderFlagsValid(TileIndex destination, AIOrderFlags order_flags);
147
* Checks whether the given combination of condition and compare function is valid.
148
* @param condition The condition to check.
149
* @param compare The compare function to check.
150
* @return True if and only if the combination of condition and compare function is valid.
152
static bool IsValidConditionalOrder(OrderCondition condition, CompareFunction compare);
155
* Returns the number of orders for the given vehicle.
156
* @param vehicle_id The vehicle to get the order count of.
157
* @pre AIVehicle::IsValidVehicle(vehicle_id).
158
* @return The number of orders for the given vehicle or a negative
159
* value when the vehicle does not exist.
161
static int32 GetOrderCount(VehicleID vehicle_id);
164
* Gets the destination of the given order for the given vehicle.
165
* @param vehicle_id The vehicle to get the destination for.
166
* @param order_position The order to get the destination for.
167
* @pre IsValidVehicleOrder(vehicle_id, order_position).
168
* @pre order_position == ORDER_CURRENT || !IsConditionalOrder(vehicle_id, order_position).
169
* @note Giving ORDER_CURRENT as order_position will give the order that is
170
* currently being executed by the vehicle. This is not necessarily the
171
* current order as given by ResolveOrderPosition (the current index in the
172
* order list) as manual or autoservicing depot orders do not show up
173
* in the orderlist, but they can be the current order of a vehicle.
174
* @return The destination tile of the order.
176
static TileIndex GetOrderDestination(VehicleID vehicle_id, OrderPosition order_position);
179
* Gets the AIOrderFlags of the given order for the given vehicle.
180
* @param vehicle_id The vehicle to get the destination for.
181
* @param order_position The order to get the destination for.
182
* @pre IsValidVehicleOrder(vehicle_id, order_position).
183
* @pre order_position == ORDER_CURRENT || !IsConditionalOrder(vehicle_id, order_position).
184
* @note Giving ORDER_CURRENT as order_position will give the order that is
185
* currently being executed by the vehicle. This is not necessarily the
186
* current order as given by ResolveOrderPosition (the current index in the
187
* order list) as manual or autoservicing depot orders do not show up
188
* in the orderlist, but they can be the current order of a vehicle.
189
* @return The AIOrderFlags of the order.
191
static AIOrderFlags GetOrderFlags(VehicleID vehicle_id, OrderPosition order_position);
194
* Gets the OrderPosition to jump to if the check succeeds of the given order for the given vehicle.
195
* @param vehicle_id The vehicle to get the OrderPosition for.
196
* @param order_position The order to get the OrderPosition for.
197
* @pre IsValidVehicleOrder(vehicle_id, order_position).
198
* @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
199
* @return The target of the conditional jump.
201
static OrderPosition GetOrderJumpTo(VehicleID vehicle_id, OrderPosition order_position);
204
* Gets the OrderCondition of the given order for the given vehicle.
205
* @param vehicle_id The vehicle to get the condition type for.
206
* @param order_position The order to get the condition type for.
207
* @pre IsValidVehicleOrder(vehicle_id, order_position).
208
* @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
209
* @return The OrderCondition of the order.
211
static OrderCondition GetOrderCondition(VehicleID vehicle_id, OrderPosition order_position);
214
* Gets the CompareFunction of the given order for the given vehicle.
215
* @param vehicle_id The vehicle to get the compare function for.
216
* @param order_position The order to get the compare function for.
217
* @pre IsValidVehicleOrder(vehicle_id, order_position).
218
* @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
219
* @return The CompareFunction of the order.
221
static CompareFunction GetOrderCompareFunction(VehicleID vehicle_id, OrderPosition order_position);
224
* Gets the value to compare against of the given order for the given vehicle.
225
* @param vehicle_id The vehicle to get the value for.
226
* @param order_position The order to get the value for.
227
* @pre IsValidVehicleOrder(vehicle_id, order_position).
228
* @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
229
* @return The value to compare against of the order.
231
static int32 GetOrderCompareValue(VehicleID vehicle_id, OrderPosition order_position);
234
* Sets the OrderPosition to jump to if the check succeeds of the given order for the given vehicle.
235
* @param vehicle_id The vehicle to set the OrderPosition for.
236
* @param order_position The order to set the OrderPosition for.
237
* @param jump_to The order to jump to if the check succeeds.
238
* @pre IsValidVehicleOrder(vehicle_id, order_position).
239
* @pre IsValidVehicleOrder(vehicle_id, jump_to).
240
* @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
241
* @return Whether the order has been/can be changed.
243
static bool SetOrderJumpTo(VehicleID vehicle_id, OrderPosition order_position, OrderPosition jump_to);
246
* Sets the OrderCondition of the given order for the given vehicle.
247
* @param vehicle_id The vehicle to set the condition type for.
248
* @param order_position The order to set the condition type for.
249
* @pre IsValidVehicleOrder(vehicle_id, order_position).
250
* @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
251
* @return Whether the order has been/can be changed.
253
static bool SetOrderCondition(VehicleID vehicle_id, OrderPosition order_position, OrderCondition condition);
256
* Sets the CompareFunction of the given order for the given vehicle.
257
* @param vehicle_id The vehicle to set the compare function for.
258
* @param order_position The order to set the compare function for.
259
* @pre IsValidVehicleOrder(vehicle_id, order_position).
260
* @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
261
* @return Whether the order has been/can be changed.
263
static bool SetOrderCompareFunction(VehicleID vehicle_id, OrderPosition order_position, CompareFunction compare);
266
* Sets the value to compare against of the given order for the given vehicle.
267
* @param vehicle_id The vehicle to set the value for.
268
* @param order_position The order to set the value for.
269
* @pre IsValidVehicleOrder(vehicle_id, order_position).
270
* @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
271
* @pre value >= 0 && value < 2048.
272
* @return Whether the order has been/can be changed.
274
static bool SetOrderCompareValue(VehicleID vehicle_id, OrderPosition order_position, int32 value);
277
* Appends an order to the end of the vehicle's order list.
278
* @param vehicle_id The vehicle to append the order to.
279
* @param destination The destination of the order.
280
* @param order_flags The flags given to the order.
281
* @pre AIVehicle::IsValidVehicle(vehicle_id).
282
* @pre AreOrderFlagsValid(destination, order_flags).
283
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
284
* @exception AIOrder::ERR_ORDER_NO_MORE_SPACE
285
* @exception AIOrder::ERR_ORDER_TOO_FAR_AWAY_FROM_PREVIOUS_DESTINATION
286
* @return True if and only if the order was appended.
288
static bool AppendOrder(VehicleID vehicle_id, TileIndex destination, AIOrderFlags order_flags);
291
* Appends a conditional order to the end of the vehicle's order list.
292
* @param vehicle_id The vehicle to append the order to.
293
* @param jump_to The OrderPosition to jump to if the condition is true.
294
* @pre AIVehicle::IsValidVehicle(vehicle_id).
295
* @pre IsValidVehicleOrder(vehicle_id, jump_to).
296
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
297
* @exception AIOrder::ERR_ORDER_NO_MORE_SPACE
298
* @return True if and only if the order was appended.
300
static bool AppendConditionalOrder(VehicleID vehicle_id, OrderPosition jump_to);
303
* Inserts an order before the given order_position into the vehicle's order list.
304
* @param vehicle_id The vehicle to add the order to.
305
* @param order_position The order to place the new order before.
306
* @param destination The destination of the order.
307
* @param order_flags The flags given to the order.
308
* @pre IsValidVehicleOrder(vehicle_id, order_position).
309
* @pre AreOrderFlagsValid(destination, order_flags).
310
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
311
* @exception AIOrder::ERR_ORDER_NO_MORE_SPACE
312
* @exception AIOrder::ERR_ORDER_TOO_FAR_AWAY_FROM_PREVIOUS_DESTINATION
313
* @return True if and only if the order was inserted.
315
static bool InsertOrder(VehicleID vehicle_id, OrderPosition order_position, TileIndex destination, AIOrderFlags order_flags);
318
* Appends a conditional order before the given order_position into the vehicle's order list.
319
* @param vehicle_id The vehicle to add the order to.
320
* @param order_position The order to place the new order before.
321
* @param jump_to The OrderPosition to jump to if the condition is true.
322
* @pre IsValidVehicleOrder(vehicle_id, order_position).
323
* @pre IsValidVehicleOrder(vehicle_id, jump_to).
324
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
325
* @exception AIOrder::ERR_ORDER_NO_MORE_SPACE
326
* @return True if and only if the order was inserted.
328
static bool InsertConditionalOrder(VehicleID vehicle_id, OrderPosition order_position, OrderPosition jump_to);
331
* Removes an order from the vehicle's order list.
332
* @param vehicle_id The vehicle to remove the order from.
333
* @param order_position The order to remove from the order list.
334
* @pre IsValidVehicleOrder(vehicle_id, order_position).
335
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
336
* @return True if and only if the order was removed.
338
static bool RemoveOrder(VehicleID vehicle_id, OrderPosition order_position);
342
* Internal function to help SetOrderFlags.
344
static bool _SetOrderFlags();
345
#endif /* DOXYGEN_SKIP */
348
* Changes the order flags of the given order.
349
* @param vehicle_id The vehicle to change the order of.
350
* @param order_position The order to change.
351
* @param order_flags The new flags given to the order.
352
* @pre IsValidVehicleOrder(vehicle_id, order_position).
353
* @pre AreOrderFlagsValid(GetOrderDestination(vehicle_id, order_position), order_flags).
354
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
355
* @return True if and only if the order was changed.
357
static bool SetOrderFlags(VehicleID vehicle_id, OrderPosition order_position, AIOrderFlags order_flags);
360
* Deprecated, use SetOrderFlags instead.
362
static bool ChangeOrder(VehicleID vehicle_id, OrderPosition order_position, AIOrderFlags order_flags);
365
* Move an order inside the orderlist
366
* @param vehicle_id The vehicle to move the orders.
367
* @param order_position_move The order to move.
368
* @param order_position_target The target order
369
* @pre IsValidVehicleOrder(vehicle_id, order_position_move).
370
* @pre IsValidVehicleOrder(vehicle_id, order_position_target).
371
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
372
* @return True if and only if the order was moved.
373
* @note If the order is moved to a lower place (e.g. from 7 to 2)
374
* the target order is moved upwards (e.g. 3). If the order is moved
375
* to a higher place (e.g. from 7 to 9) the target will be moved
376
* downwards (e.g. 8).
378
static bool MoveOrder(VehicleID vehicle_id, OrderPosition order_position_move, OrderPosition order_position_target);
381
* Make a vehicle execute next_order instead of its current order.
382
* @param vehicle_id The vehicle that should skip some orders.
383
* @param next_order The order the vehicle should skip to.
384
* @pre IsValidVehicleOrder(vehicle_id, next_order).
385
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
386
* @return True if and only the current order was changed.
388
static bool SkipToOrder(VehicleID vehicle_id, OrderPosition next_order);
391
* Copies the orders from another vehicle. The orders of the main vehicle
392
* are going to be the orders of the changed vehicle.
393
* @param vehicle_id The vehicle to copy the orders to.
394
* @param main_vehicle_id The vehicle to copy the orders from.
395
* @pre AIVehicle::IsValidVehicle(vehicle_id).
396
* @pre AIVehicle::IsValidVehicle(main_vehicle_id).
397
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
398
* @exception AIOrder::ERR_ORDER_NO_MORE_SPACE
399
* @return True if and only if the copying succeeded.
401
static bool CopyOrders(VehicleID vehicle_id, VehicleID main_vehicle_id);
404
* Shares the orders between two vehicles. The orders of the main
405
* vehicle are going to be the orders of the changed vehicle.
406
* @param vehicle_id The vehicle to add to the shared order list.
407
* @param main_vehicle_id The vehicle to share the orders with.
408
* @pre AIVehicle::IsValidVehicle(vehicle_id).
409
* @pre AIVehicle::IsValidVehicle(main_vehicle_id).
410
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
411
* @return True if and only if the sharing succeeded.
413
static bool ShareOrders(VehicleID vehicle_id, VehicleID main_vehicle_id);
416
* Removes the given vehicle from a shared orders list.
417
* @param vehicle_id The vehicle to remove from the shared order list.
418
* @pre AIVehicle::IsValidVehicle(vehicle_id).
419
* @return True if and only if the unsharing succeeded.
421
static bool UnshareOrders(VehicleID vehicle_id);
423
DECLARE_ENUM_AS_BIT_SET(AIOrder::AIOrderFlags);
425
#endif /* AI_ORDER_HPP */
added
removed
src/ai/api/ai_order.hpp
