2 * This file is part of OpenTTD.
3 * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
4 * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
5 * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
8 /** @file script_order.hpp Everything to query and build orders. */
10 #ifndef SCRIPT_ORDER_HPP
11 #define SCRIPT_ORDER_HPP
13 #include "script_vehicle.hpp"
14 #include "../../order_type.h"
17 * Class that handles all order related functions.
20 class ScriptOrder
: public ScriptObject
{
23 * All order related error messages.
26 /** Base for all order related errors */
27 ERR_ORDER_BASE
= ScriptError::ERR_CAT_ORDER
<< ScriptError::ERR_CAT_BIT_SIZE
,
29 /** No more space for orders */
30 ERR_ORDER_TOO_MANY
, // [STR_ERROR_NO_MORE_SPACE_FOR_ORDERS]
32 /** Destination of new order is too far away from the previous order */
33 ERR_ORDER_TOO_FAR_AWAY_FROM_PREVIOUS_DESTINATION
, // [STR_ERROR_TOO_FAR_FROM_PREVIOUS_DESTINATION]
35 /** Aircraft has not enough range to copy/share orders. */
36 ERR_ORDER_AIRCRAFT_NOT_ENOUGH_RANGE
, // [STR_ERROR_AIRCRAFT_NOT_ENOUGH_RANGE]
40 * Flags that can be used to modify the behaviour of orders.
42 enum ScriptOrderFlags
{
43 /** Just go to the station/depot, stop unload if possible and load if needed. */
46 /** Do not stop at the stations that are passed when going to the destination. Only for trains and road vehicles. */
47 OF_NON_STOP_INTERMEDIATE
= 1 << 0,
48 /** Do not stop at the destination station. Only for trains and road vehicles. */
49 OF_NON_STOP_DESTINATION
= 1 << 1,
51 /** Always unload the vehicle; only for stations. Cannot be set when OF_TRANSFER or OF_NO_UNLOAD is set. */
53 /** Transfer instead of deliver the goods; only for stations. Cannot be set when OF_UNLOAD or OF_NO_UNLOAD is set. */
55 /** Never unload the vehicle; only for stations. Cannot be set when OF_UNLOAD, OF_TRANSFER or OF_NO_LOAD is set. */
56 OF_NO_UNLOAD
= 1 << 4,
58 /** Wt till the vehicle is fully loaded; only for stations. Cannot be set when OF_NO_LOAD is set. */
59 OF_FULL_LOAD
= 2 << 5,
60 /** Wt till at least one cargo of the vehicle is fully loaded; only for stations. Cannot be set when OF_NO_LOAD is set. */
61 OF_FULL_LOAD_ANY
= 3 << 5,
62 /** Do not load any cargo; only for stations. Cannot be set when OF_NO_UNLOAD, OF_FULL_LOAD or OF_FULL_LOAD_ANY is set. */
65 /** Service the vehicle when needed, otherwise skip this order; only for depots. */
66 OF_SERVICE_IF_NEEDED
= 1 << 2,
67 /** Stop in the depot instead of only go there for servicing; only for depots. */
68 OF_STOP_IN_DEPOT
= 1 << 3,
69 /** Go to nearest depot. */
70 OF_GOTO_NEAREST_DEPOT
= 1 << 8,
72 /** All flags related to non-stop settings. */
73 OF_NON_STOP_FLAGS
= OF_NON_STOP_INTERMEDIATE
| OF_NON_STOP_DESTINATION
,
74 /** All flags related to unloading. */
75 OF_UNLOAD_FLAGS
= OF_TRANSFER
| OF_UNLOAD
| OF_NO_UNLOAD
,
76 /** All flags related to loading. */
77 OF_LOAD_FLAGS
= OF_FULL_LOAD
| OF_FULL_LOAD_ANY
| OF_NO_LOAD
,
78 /** All flags related to depots. */
79 OF_DEPOT_FLAGS
= OF_SERVICE_IF_NEEDED
| OF_STOP_IN_DEPOT
| OF_GOTO_NEAREST_DEPOT
,
81 /** For marking invalid order flags */
86 * All conditions a conditional order can depend on.
89 /* Note: these values represent part of the in-game OrderConditionVariable enum */
90 OC_LOAD_PERCENTAGE
= ::OCV_LOAD_PERCENTAGE
, ///< Skip based on the amount of load, value is in tons.
91 OC_RELIABILITY
= ::OCV_RELIABILITY
, ///< Skip based on the reliability, value is percent (0..100).
92 OC_MAX_RELIABILITY
= ::OCV_MAX_RELIABILITY
, ///< Skip based on the maximum reliability. Value in percent
93 OC_MAX_SPEED
= ::OCV_MAX_SPEED
, ///< Skip based on the maximum speed, value is in OpenTTD's internal speed unit, see ScriptEngine::GetMaxSpeed.
94 OC_AGE
= ::OCV_AGE
, ///< Skip based on the age, value is in years.
95 OC_REQUIRES_SERVICE
= ::OCV_REQUIRES_SERVICE
, ///< Skip when the vehicle requires service, no value.
96 OC_UNCONDITIONALLY
= ::OCV_UNCONDITIONALLY
, ///< Always skip, no compare function, no value.
97 OC_REMAINING_LIFETIME
= ::OCV_REMAINING_LIFETIME
, ///< Skip based on the remaining lifetime
99 /* Custom added value, only valid for this API */
100 OC_INVALID
= -1, ///< An invalid condition, do not use.
104 * Comparators for conditional orders.
106 enum CompareFunction
{
107 /* Note: these values represent part of the in-game OrderConditionComparator enum */
108 CF_EQUALS
= ::OCC_EQUALS
, ///< Skip if both values are equal
109 CF_NOT_EQUALS
= ::OCC_NOT_EQUALS
, ///< Skip if both values are not equal
110 CF_LESS_THAN
= ::OCC_LESS_THAN
, ///< Skip if the value is less than the limit
111 CF_LESS_EQUALS
= ::OCC_LESS_EQUALS
, ///< Skip if the value is less or equal to the limit
112 CF_MORE_THAN
= ::OCC_MORE_THAN
, ///< Skip if the value is more than the limit
113 CF_MORE_EQUALS
= ::OCC_MORE_EQUALS
, ///< Skip if the value is more or equal to the limit
114 CF_IS_TRUE
= ::OCC_IS_TRUE
, ///< Skip if the variable is true
115 CF_IS_FALSE
= ::OCC_IS_FALSE
, ///< Skip if the variable is false
117 /* Custom added value, only valid for this API */
118 CF_INVALID
= -1, ///< Invalid compare function, do not use.
122 * Index in the list of orders for a vehicle. The first order has index 0, the second
123 * order index 1, etc. The current order can be queried by using ORDER_CURRENT. Do not
124 * use ORDER_INVALID yourself, it's used as return value by for example ResolveOrderPosition.
125 * @note Automatic orders are hidden from scripts, so OrderPosition 0 will always be the first
129 ORDER_CURRENT
= 0xFF, ///< Constant that gets resolved to the current order.
130 ORDER_INVALID
= -1, ///< An invalid order.
133 /** Where to stop trains in a station that's longer than the train */
135 STOPLOCATION_NEAR
, ///< Stop the train as soon as it's completely in the station
136 STOPLOCATION_MIDDLE
, ///< Stop the train in the middle of the station
137 STOPLOCATION_FAR
, ///< Stop the train at the far end of the station
138 STOPLOCATION_INVALID
= -1, ///< An invalid stop location
142 * Checks whether the given order id is valid for the given vehicle.
143 * @param vehicle_id The vehicle to check the order index for.
144 * @param order_position The order index to check.
145 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
146 * @return True if and only if the order_position is valid for the given vehicle.
148 static bool IsValidVehicleOrder(VehicleID vehicle_id
, OrderPosition order_position
);
151 * Checks whether the given order is a goto-station order.
152 * @param vehicle_id The vehicle to check.
153 * @param order_position The order index to check.
154 * @pre IsValidVehicleOrder(vehicle_id, order_position).
155 * @return True if and only if the order is a goto-station order.
157 static bool IsGotoStationOrder(VehicleID vehicle_id
, OrderPosition order_position
);
160 * Checks whether the given order is a goto-depot order.
161 * @param vehicle_id The vehicle to check.
162 * @param order_position The order index to check.
163 * @pre IsValidVehicleOrder(vehicle_id, order_position).
164 * @return True if and only if the order is a goto-depot order.
166 static bool IsGotoDepotOrder(VehicleID vehicle_id
, OrderPosition order_position
);
169 * Checks whether the given order is a goto-waypoint order.
170 * @param vehicle_id The vehicle to check.
171 * @param order_position The order index to check.
172 * @pre IsValidVehicleOrder(vehicle_id, order_position).
173 * @return True if and only if the order is a goto-waypoint order.
175 static bool IsGotoWaypointOrder(VehicleID vehicle_id
, OrderPosition order_position
);
178 * Checks whether the given order is a conditional order.
179 * @param vehicle_id The vehicle to check.
180 * @param order_position The order index to check.
181 * @pre order_position != ORDER_CURRENT && IsValidVehicleOrder(vehicle_id, order_position).
182 * @return True if and only if the order is a conditional order.
184 static bool IsConditionalOrder(VehicleID vehicle_id
, OrderPosition order_position
);
187 * Checks whether the given order is a void order.
188 * A void order is an order that used to be a goto station, depot or waypoint order but
189 * its destination got removed. In OpenTTD these orders as shown as "(Invalid Order)"
190 * in the order list of a vehicle.
191 * @param vehicle_id The vehicle to check.
192 * @param order_position The order index to check.
193 * @pre order_position != ORDER_CURRENT && IsValidVehicleOrder(vehicle_id, order_position).
194 * @return True if and only if the order is a void order.
196 static bool IsVoidOrder(VehicleID vehicle_id
, OrderPosition order_position
);
199 * Checks whether the given order has a valid refit cargo.
200 * @param vehicle_id The vehicle to check.
201 * @param order_position The order index to check.
202 * @pre order_position != ORDER_CURRENT && IsValidVehicleOrder(vehicle_id, order_position).
203 * @return True if and only if the order is has a valid refit cargo.
205 static bool IsRefitOrder(VehicleID vehicle_id
, OrderPosition order_position
);
208 * Checks whether the current order is part of the orderlist.
209 * @param vehicle_id The vehicle to check.
210 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
211 * @return True if and only if the current order is part of the order list.
212 * @note If the order is a non-'non-stop' order, and the vehicle is currently
213 * (un)loading at a station that is not the final destination, this function
214 * will still return true.
216 static bool IsCurrentOrderPartOfOrderList(VehicleID vehicle_id
);
219 * Resolves the given order index to the correct index for the given vehicle.
220 * If the order index was ORDER_CURRENT it will be resolved to the index of
221 * the current order (as shown in the order list). If the order with the
222 * given index does not exist it will return ORDER_INVALID.
223 * @param vehicle_id The vehicle to check the order index for.
224 * @param order_position The order index to resolve.
225 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
226 * @return The resolved order index.
228 static OrderPosition
ResolveOrderPosition(VehicleID vehicle_id
, OrderPosition order_position
);
231 * Checks whether the given order flags are valid for the given destination.
232 * @param destination The destination of the order.
233 * @param order_flags The flags given to the order.
234 * @return True if and only if the order_flags are valid for the given location.
236 static bool AreOrderFlagsValid(TileIndex destination
, ScriptOrderFlags order_flags
);
239 * Checks whether the given combination of condition and compare function is valid.
240 * @param condition The condition to check.
241 * @param compare The compare function to check.
242 * @return True if and only if the combination of condition and compare function is valid.
244 static bool IsValidConditionalOrder(OrderCondition condition
, CompareFunction compare
);
247 * Returns the number of orders for the given vehicle.
248 * @param vehicle_id The vehicle to get the order count of.
249 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
250 * @return The number of orders for the given vehicle or a negative
251 * value when the vehicle does not exist.
253 static SQInteger
GetOrderCount(VehicleID vehicle_id
);
256 * Gets the destination of the given order for the given vehicle.
257 * @param vehicle_id The vehicle to get the destination for.
258 * @param order_position The order to get the destination for.
259 * @pre IsValidVehicleOrder(vehicle_id, order_position).
260 * @pre order_position == ORDER_CURRENT || !IsConditionalOrder(vehicle_id, order_position).
261 * @note Giving ORDER_CURRENT as order_position will give the order that is
262 * currently being executed by the vehicle. This is not necessarily the
263 * current order as given by ResolveOrderPosition (the current index in the
264 * order list) as manual or autoservicing depot orders do not show up
265 * in the orderlist, but they can be the current order of a vehicle.
266 * @return The destination tile of the order.
268 static TileIndex
GetOrderDestination(VehicleID vehicle_id
, OrderPosition order_position
);
271 * Gets the ScriptOrderFlags of the given order for the given vehicle.
272 * @param vehicle_id The vehicle to get the destination for.
273 * @param order_position The order to get the destination for.
274 * @pre IsValidVehicleOrder(vehicle_id, order_position).
275 * @pre order_position == ORDER_CURRENT || (!IsConditionalOrder(vehicle_id, order_position) && !IsVoidOrder(vehicle_id, order_position)).
276 * @note Giving ORDER_CURRENT as order_position will give the order that is
277 * currently being executed by the vehicle. This is not necessarily the
278 * current order as given by ResolveOrderPosition (the current index in the
279 * order list) as manual or autoservicing depot orders do not show up
280 * in the orderlist, but they can be the current order of a vehicle.
281 * @return The ScriptOrderFlags of the order.
283 static ScriptOrderFlags
GetOrderFlags(VehicleID vehicle_id
, OrderPosition order_position
);
286 * Gets the OrderPosition to jump to if the check succeeds of the given order for the given vehicle.
287 * @param vehicle_id The vehicle to get the OrderPosition for.
288 * @param order_position The order to get the OrderPosition for.
289 * @pre IsValidVehicleOrder(vehicle_id, order_position).
290 * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
291 * @return The target of the conditional jump.
293 static OrderPosition
GetOrderJumpTo(VehicleID vehicle_id
, OrderPosition order_position
);
296 * Gets the OrderCondition of the given order for the given vehicle.
297 * @param vehicle_id The vehicle to get the condition type for.
298 * @param order_position The order to get the condition type for.
299 * @pre IsValidVehicleOrder(vehicle_id, order_position).
300 * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
301 * @return The OrderCondition of the order.
303 static OrderCondition
GetOrderCondition(VehicleID vehicle_id
, OrderPosition order_position
);
306 * Gets the CompareFunction of the given order for the given vehicle.
307 * @param vehicle_id The vehicle to get the compare function for.
308 * @param order_position The order to get the compare function for.
309 * @pre IsValidVehicleOrder(vehicle_id, order_position).
310 * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
311 * @return The CompareFunction of the order.
313 static CompareFunction
GetOrderCompareFunction(VehicleID vehicle_id
, OrderPosition order_position
);
316 * Gets the value to compare against of the given order for the given vehicle.
317 * @param vehicle_id The vehicle to get the value for.
318 * @param order_position The order to get the value for.
319 * @pre IsValidVehicleOrder(vehicle_id, order_position).
320 * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
321 * @return The value to compare against of the order.
323 static SQInteger
GetOrderCompareValue(VehicleID vehicle_id
, OrderPosition order_position
);
326 * Gets the stoplocation of the given order for the given train.
327 * @param vehicle_id The vehicle to get the value for.
328 * @param order_position The order to get the value for.
329 * @pre IsValidVehicleOrder(vehicle_id, order_position).
330 * @pre ScriptVehicle::GetVehicleType(vehicle_id) == ScriptVehicle::VT_RAIL.
331 * @pre IsGotoStationOrder(vehicle_id, order_position).
332 * @return The relative position where the train will stop inside a station.
334 static StopLocation
GetStopLocation(VehicleID vehicle_id
, OrderPosition order_position
);
337 * Gets the refit cargo type of the given order for the given vehicle.
338 * @param vehicle_id The vehicle to get the refit cargo for.
339 * @param order_position The order to get the refit cargo for.
340 * @pre IsValidVehicleOrder(vehicle_id, order_position).
341 * @pre order_position == ORDER_CURRENT || IsGotoStationOrder(vehicle_id, order_position) || IsGotoDepotOrder(vehicle_id, order_position).
342 * @note Giving ORDER_CURRENT as order_position will give the order that is
343 * currently being executed by the vehicle. This is not necessarily the
344 * current order as given by ResolveOrderPosition (the current index in the
345 * order list) as manual or autoservicing depot orders do not show up
346 * in the orderlist, but they can be the current order of a vehicle.
347 * @return The refit cargo of the order or CT_NO_REFIT if no refit is set.
349 static CargoID
GetOrderRefit(VehicleID vehicle_id
, OrderPosition order_position
);
352 * Sets the OrderPosition to jump to if the check succeeds of the given order for the given vehicle.
353 * @param vehicle_id The vehicle to set the OrderPosition for.
354 * @param order_position The order to set the OrderPosition for.
355 * @param jump_to The order to jump to if the check succeeds.
356 * @pre IsValidVehicleOrder(vehicle_id, order_position).
357 * @pre IsValidVehicleOrder(vehicle_id, jump_to).
358 * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
359 * @game @pre ScriptCompanyMode::IsValid().
360 * @return Whether the order has been/can be changed.
362 static bool SetOrderJumpTo(VehicleID vehicle_id
, OrderPosition order_position
, OrderPosition jump_to
);
365 * Sets the OrderCondition of the given order for the given vehicle.
366 * @param vehicle_id The vehicle to set the condition type for.
367 * @param order_position The order to set the condition type for.
368 * @param condition The condition to compare on.
369 * @pre IsValidVehicleOrder(vehicle_id, order_position).
370 * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
371 * @pre condition >= OC_LOAD_PERCENTAGE && condition <= OC_UNCONDITIONALLY.
372 * @game @pre ScriptCompanyMode::IsValid().
373 * @return Whether the order has been/can be changed.
375 static bool SetOrderCondition(VehicleID vehicle_id
, OrderPosition order_position
, OrderCondition condition
);
378 * Sets the CompareFunction of the given order for the given vehicle.
379 * @param vehicle_id The vehicle to set the compare function for.
380 * @param order_position The order to set the compare function for.
381 * @param compare The new compare function of the order.
382 * @pre IsValidVehicleOrder(vehicle_id, order_position).
383 * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
384 * @pre compare >= CF_EQUALS && compare <= CF_IS_FALSE.
385 * @game @pre ScriptCompanyMode::IsValid().
386 * @return Whether the order has been/can be changed.
388 static bool SetOrderCompareFunction(VehicleID vehicle_id
, OrderPosition order_position
, CompareFunction compare
);
391 * Sets the value to compare against of the given order for the given vehicle.
392 * @param vehicle_id The vehicle to set the value for.
393 * @param order_position The order to set the value for.
394 * @param value The value to compare against.
395 * @pre IsValidVehicleOrder(vehicle_id, order_position).
396 * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
397 * @pre value >= 0 && value < 2048.
398 * @game @pre ScriptCompanyMode::IsValid().
399 * @return Whether the order has been/can be changed.
401 static bool SetOrderCompareValue(VehicleID vehicle_id
, OrderPosition order_position
, SQInteger value
);
404 * Sets the stoplocation of the given order for the given train.
405 * @param vehicle_id The vehicle to get the value for.
406 * @param order_position The order to get the value for.
407 * @param stop_location The relative position where a train will stop inside a station.
408 * @pre IsValidVehicleOrder(vehicle_id, order_position).
409 * @pre ScriptVehicle::GetVehicleType(vehicle_id) == ScriptVehicle::VT_RAIL.
410 * @pre IsGotoStationOrder(vehicle_id, order_position).
411 * @pre stop_location >= STOPLOCATION_NEAR && stop_location <= STOPLOCATION_FAR
412 * @game @pre ScriptCompanyMode::IsValid().
413 * @return Whether the order has been/can be changed.
415 static bool SetStopLocation(VehicleID vehicle_id
, OrderPosition order_position
, StopLocation stop_location
);
418 * Sets the refit cargo type of the given order for the given vehicle.
419 * @param vehicle_id The vehicle to set the refit cargo for.
420 * @param order_position The order to set the refit cargo for.
421 * @param refit_cargo The cargo to refit to. The refit can be cleared by passing CT_NO_REFIT.
422 * @pre IsValidVehicleOrder(vehicle_id, order_position).
423 * @pre IsGotoStationOrder(vehicle_id, order_position) || (IsGotoDepotOrder(vehicle_id, order_position) && refit_cargo != CT_AUTO_REFIT).
424 * @pre ScriptCargo::IsValidCargo(refit_cargo) || refit_cargo == CT_AUTO_REFIT || refit_cargo == CT_NO_REFIT
425 * @game @pre ScriptCompanyMode::IsValid().
426 * @return Whether the order has been/can be changed.
428 static bool SetOrderRefit(VehicleID vehicle_id
, OrderPosition order_position
, CargoID refit_cargo
);
431 * Appends an order to the end of the vehicle's order list.
432 * @param vehicle_id The vehicle to append the order to.
433 * @param destination The destination of the order.
434 * @param order_flags The flags given to the order.
435 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
436 * @pre AreOrderFlagsValid(destination, order_flags).
437 * @game @pre ScriptCompanyMode::IsValid().
438 * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
439 * @exception ScriptOrder::ERR_ORDER_TOO_MANY
440 * @exception ScriptOrder::ERR_ORDER_TOO_FAR_AWAY_FROM_PREVIOUS_DESTINATION
441 * @return True if and only if the order was appended.
443 static bool AppendOrder(VehicleID vehicle_id
, TileIndex destination
, ScriptOrderFlags order_flags
);
446 * Appends a conditional order to the end of the vehicle's order list.
447 * @param vehicle_id The vehicle to append the order to.
448 * @param jump_to The OrderPosition to jump to if the condition is true.
449 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
450 * @pre IsValidVehicleOrder(vehicle_id, jump_to).
451 * @game @pre ScriptCompanyMode::IsValid().
452 * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
453 * @exception ScriptOrder::ERR_ORDER_TOO_MANY
454 * @return True if and only if the order was appended.
456 static bool AppendConditionalOrder(VehicleID vehicle_id
, OrderPosition jump_to
);
459 * Inserts an order before the given order_position into the vehicle's order list.
460 * @param vehicle_id The vehicle to add the order to.
461 * @param order_position The order to place the new order before.
462 * @param destination The destination of the order.
463 * @param order_flags The flags given to the order.
464 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id)
465 * @pre IsValidVehicleOrder(vehicle_id, order_position).
466 * @pre AreOrderFlagsValid(destination, order_flags).
467 * @game @pre ScriptCompanyMode::IsValid().
468 * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
469 * @exception ScriptOrder::ERR_ORDER_TOO_MANY
470 * @exception ScriptOrder::ERR_ORDER_TOO_FAR_AWAY_FROM_PREVIOUS_DESTINATION
471 * @return True if and only if the order was inserted.
473 static bool InsertOrder(VehicleID vehicle_id
, OrderPosition order_position
, TileIndex destination
, ScriptOrderFlags order_flags
);
476 * Appends a conditional order before the given order_position into the vehicle's order list.
477 * @param vehicle_id The vehicle to add the order to.
478 * @param order_position The order to place the new order before.
479 * @param jump_to The OrderPosition to jump to if the condition is true.
480 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
481 * @pre IsValidVehicleOrder(vehicle_id, order_position).
482 * @pre IsValidVehicleOrder(vehicle_id, jump_to).
483 * @game @pre ScriptCompanyMode::IsValid().
484 * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
485 * @exception ScriptOrder::ERR_ORDER_TOO_MANY
486 * @return True if and only if the order was inserted.
488 static bool InsertConditionalOrder(VehicleID vehicle_id
, OrderPosition order_position
, OrderPosition jump_to
);
491 * Removes an order from the vehicle's order list.
492 * @param vehicle_id The vehicle to remove the order from.
493 * @param order_position The order to remove from the order list.
494 * @pre IsValidVehicleOrder(vehicle_id, order_position).
495 * @game @pre ScriptCompanyMode::IsValid().
496 * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
497 * @return True if and only if the order was removed.
499 static bool RemoveOrder(VehicleID vehicle_id
, OrderPosition order_position
);
502 * Internal function to help SetOrderFlags.
505 static bool _SetOrderFlags();
508 * Changes the order flags of the given order.
509 * @param vehicle_id The vehicle to change the order of.
510 * @param order_position The order to change.
511 * @param order_flags The new flags given to the order.
512 * @pre IsValidVehicleOrder(vehicle_id, order_position).
513 * @pre AreOrderFlagsValid(GetOrderDestination(vehicle_id, order_position), order_flags).
514 * @pre (order_flags & OF_GOTO_NEAREST_DEPOT) == (GetOrderFlags(vehicle_id, order_position) & OF_GOTO_NEAREST_DEPOT).
515 * @game @pre ScriptCompanyMode::IsValid().
516 * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
517 * @return True if and only if the order was changed.
519 static bool SetOrderFlags(VehicleID vehicle_id
, OrderPosition order_position
, ScriptOrderFlags order_flags
);
522 * Move an order inside the orderlist
523 * @param vehicle_id The vehicle to move the orders.
524 * @param order_position_move The order to move.
525 * @param order_position_target The target order
526 * @pre IsValidVehicleOrder(vehicle_id, order_position_move).
527 * @pre IsValidVehicleOrder(vehicle_id, order_position_target).
528 * @pre order_position_move != order_position_target.
529 * @game @pre ScriptCompanyMode::IsValid().
530 * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
531 * @return True if and only if the order was moved.
532 * @note If the order is moved to a lower place (e.g. from 7 to 2)
533 * the target order is moved upwards (e.g. 3). If the order is moved
534 * to a higher place (e.g. from 7 to 9) the target will be moved
535 * downwards (e.g. 8).
537 static bool MoveOrder(VehicleID vehicle_id
, OrderPosition order_position_move
, OrderPosition order_position_target
);
540 * Make a vehicle execute next_order instead of its current order.
541 * @param vehicle_id The vehicle that should skip some orders.
542 * @param next_order The order the vehicle should skip to.
543 * @pre IsValidVehicleOrder(vehicle_id, next_order).
544 * @game @pre ScriptCompanyMode::IsValid().
545 * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
546 * @return True if and only the current order was changed.
548 static bool SkipToOrder(VehicleID vehicle_id
, OrderPosition next_order
);
551 * Copies the orders from another vehicle. The orders of the main vehicle
552 * are going to be the orders of the changed vehicle.
553 * @param vehicle_id The vehicle to copy the orders to.
554 * @param main_vehicle_id The vehicle to copy the orders from.
555 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
556 * @pre ScriptVehicle::IsPrimaryVehicle(main_vehicle_id).
557 * @game @pre ScriptCompanyMode::IsValid().
558 * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
559 * @exception ScriptOrder::ERR_ORDER_TOO_MANY
560 * @exception ScriptOrder::ERR_ORDER_AIRCRAFT_NOT_ENOUGH_RANGE
561 * @return True if and only if the copying succeeded.
563 static bool CopyOrders(VehicleID vehicle_id
, VehicleID main_vehicle_id
);
566 * Shares the orders between two vehicles. The orders of the main
567 * vehicle are going to be the orders of the changed vehicle.
568 * @param vehicle_id The vehicle to add to the shared order list.
569 * @param main_vehicle_id The vehicle to share the orders with.
570 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
571 * @pre ScriptVehicle::IsPrimaryVehicle(main_vehicle_id).
572 * @game @pre ScriptCompanyMode::IsValid().
573 * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
574 * @exception ScriptOrder::ERR_ORDER_AIRCRAFT_NOT_ENOUGH_RANGE
575 * @return True if and only if the sharing succeeded.
577 static bool ShareOrders(VehicleID vehicle_id
, VehicleID main_vehicle_id
);
580 * Removes the given vehicle from a shared orders list.
581 * After unsharing orders, the orders list of the vehicle is empty.
582 * @param vehicle_id The vehicle to remove from the shared order list.
583 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
584 * @game @pre ScriptCompanyMode::IsValid().
585 * @return True if and only if the unsharing succeeded.
587 static bool UnshareOrders(VehicleID vehicle_id
);
590 * Get the distance between two points for a vehicle type.
591 * Use this function to compute the distance between two tiles wrt. a vehicle type.
592 * These vehicle-type specific distances are independent from other map distances, you may
593 * use the result of this function to compare it with the result of
594 * ScriptEngine::GetMaximumOrderDistance or ScriptVehicle::GetMaximumOrderDistance.
595 * @param vehicle_type The vehicle type to get the distance for.
596 * @param origin_tile Origin, can be any tile or a tile of a specific station.
597 * @param dest_tile Destination, can be any tile or a tile of a specific station.
598 * @return The distance between the origin and the destination for a
599 * vehicle of the given vehicle type.
600 * @note The unit of the order distances is unspecified and should
601 * not be compared with map distances
602 * @see ScriptEngine::GetMaximumOrderDistance and ScriptVehicle::GetMaximumOrderDistance
604 static SQInteger
GetOrderDistance(ScriptVehicle::VehicleType vehicle_type
, TileIndex origin_tile
, TileIndex dest_tile
);
606 DECLARE_ENUM_AS_BIT_SET(ScriptOrder::ScriptOrderFlags
)
608 #endif /* SCRIPT_ORDER_HPP */