src/script/api/script_order.hpp

   1 /* $Id: script_order.hpp 25612 2013-07-14 20:21:36Z rubidium $ */
   2
   3 /*
   4  * This file is part of OpenTTD.
   5  * 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.
   6  * 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.
   7  * 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  */
   9
  10 /** @file script_order.hpp Everything to query and build orders. */
  11
  12 #ifndef SCRIPT_ORDER_HPP
  13 #define SCRIPT_ORDER_HPP
  14
  15 #include "script_vehicle.hpp"
  16 #include "../../order_type.h"
  17
  18 /**
  19  * Class that handles all order related functions.
  20  * @api ai game
  21  */
  22 class ScriptOrder : public ScriptObject {
  23 public:
  24         /**
  25          * All order related error messages.
  26          */
  27         enum ErrorMessages {
  28                 /** Base for all order related errors */
  29                 ERR_ORDER_BASE = ScriptError::ERR_CAT_ORDER << ScriptError::ERR_CAT_BIT_SIZE,
  30
  31                 /** No more space for orders */
  32                 ERR_ORDER_TOO_MANY,                                  // [STR_ERROR_NO_MORE_SPACE_FOR_ORDERS]
  33
  34                 /** Destination of new order is to far away from the previous order */
  35                 ERR_ORDER_TOO_FAR_AWAY_FROM_PREVIOUS_DESTINATION,    // [STR_ERROR_TOO_FAR_FROM_PREVIOUS_DESTINATION]
  36
  37                 /** Aircraft has not enough range to copy/share orders. */
  38                 ERR_ORDER_AIRCRAFT_NOT_ENOUGH_RANGE,                 // [STR_ERROR_AIRCRAFT_NOT_ENOUGH_RANGE]
  39         };
  40
  41         /**
  42          * Flags that can be used to modify the behaviour of orders.
  43          */
  44         enum ScriptOrderFlags {
  45                 /** Just go to the station/depot, stop unload if possible and load if needed. */
  46                 OF_NONE              = 0,
  47
  48                 /** Do not stop at the stations that are passed when going to the destination. Only for trains and road vehicles. */
  49                 OF_NON_STOP_INTERMEDIATE = 1 << 0,
  50                 /** Do not stop at the destination station. Only for trains and road vehicles. */
  51                 OF_NON_STOP_DESTINATION  = 1 << 1,
  52
  53                 /** Always unload the vehicle; only for stations. Cannot be set when OF_TRANSFER or OF_NO_UNLOAD is set. */
  54                 OF_UNLOAD            = 1 << 2,
  55                 /** Transfer instead of deliver the goods; only for stations. Cannot be set when OF_UNLOAD or OF_NO_UNLOAD is set. */
  56                 OF_TRANSFER          = 1 << 3,
  57                 /** Never unload the vehicle; only for stations. Cannot be set when OF_UNLOAD, OF_TRANSFER or OF_NO_LOAD is set. */
  58                 OF_NO_UNLOAD         = 1 << 4,
  59
  60                 /** Wt till the vehicle is fully loaded; only for stations. Cannot be set when OF_NO_LOAD is set. */
  61                 OF_FULL_LOAD         = 2 << 5,
  62                 /** Wt till at least one cargo of the vehicle is fully loaded; only for stations. Cannot be set when OF_NO_LOAD is set. */
  63                 OF_FULL_LOAD_ANY     = 3 << 5,
  64                 /** 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                 OF_NO_LOAD           = 1 << 7,
  66
  67                 /** Service the vehicle when needed, otherwise skip this order; only for depots. */
  68                 OF_SERVICE_IF_NEEDED = 1 << 2,
  69                 /** Stop in the depot instead of only go there for servicing; only for depots. */
  70                 OF_STOP_IN_DEPOT     = 1 << 3,
  71                 /** Go to nearest depot. */
  72                 OF_GOTO_NEAREST_DEPOT = 1 << 8,
  73
  74                 /** All flags related to non-stop settings. */
  75                 OF_NON_STOP_FLAGS    = OF_NON_STOP_INTERMEDIATE | OF_NON_STOP_DESTINATION,
  76                 /** All flags related to unloading. */
  77                 OF_UNLOAD_FLAGS      = OF_TRANSFER | OF_UNLOAD | OF_NO_UNLOAD,
  78                 /** All flags related to loading. */
  79                 OF_LOAD_FLAGS        = OF_FULL_LOAD | OF_FULL_LOAD_ANY | OF_NO_LOAD,
  80                 /** All flags related to depots. */
  81                 OF_DEPOT_FLAGS       = OF_SERVICE_IF_NEEDED | OF_STOP_IN_DEPOT | OF_GOTO_NEAREST_DEPOT,
  82
  83                 /** For marking invalid order flags */
  84                 OF_INVALID           = 0xFFFF,
  85         };
  86
  87         /**
  88          * All conditions a conditional order can depend on.
  89          */
  90         enum OrderCondition {
  91                 /* Note: these values represent part of the in-game OrderConditionVariable enum */
  92                 OC_LOAD_PERCENTAGE     = ::OCV_LOAD_PERCENTAGE,    ///< Skip based on the amount of load, value is in tons.
  93                 OC_RELIABILITY         = ::OCV_RELIABILITY,        ///< Skip based on the reliability, value is percent (0..100).
  94                 OC_MAX_SPEED           = ::OCV_MAX_SPEED,          ///< Skip based on the maximum speed, value is in OpenTTD's internal speed unit, see ScriptEngine::GetMaxSpeed.
  95                 OC_AGE                 = ::OCV_AGE,                ///< Skip based on the age, value is in years.
  96                 OC_REQUIRES_SERVICE    = ::OCV_REQUIRES_SERVICE,   ///< Skip when the vehicle requires service, no value.
  97                 OC_UNCONDITIONALLY     = ::OCV_UNCONDITIONALLY,    ///< Always skip, no compare function, no value.
  98                 OC_REMAINING_LIFETIME  = ::OCV_REMAINING_LIFETIME, ///< Skip based on the remaining lifetime
  99
 100                 /* Custom added value, only valid for this API */
 101                 OC_INVALID             = -1,                       ///< An invalid condition, do not use.
 102         };
 103
 104         /**
 105          * Comparators for conditional orders.
 106          */
 107         enum CompareFunction {
 108                 /* Note: these values represent part of the in-game OrderConditionComparator enum */
 109                 CF_EQUALS        = ::OCC_EQUALS,       ///< Skip if both values are equal
 110                 CF_NOT_EQUALS    = ::OCC_NOT_EQUALS,   ///< Skip if both values are not equal
 111                 CF_LESS_THAN     = ::OCC_LESS_THAN,    ///< Skip if the value is less than the limit
 112                 CF_LESS_EQUALS   = ::OCC_LESS_EQUALS,  ///< Skip if the value is less or equal to the limit
 113                 CF_MORE_THAN     = ::OCC_MORE_THAN,    ///< Skip if the value is more than the limit
 114                 CF_MORE_EQUALS   = ::OCC_MORE_EQUALS,  ///< Skip if the value is more or equal to the limit
 115                 CF_IS_TRUE       = ::OCC_IS_TRUE,      ///< Skip if the variable is true
 116                 CF_IS_FALSE      = ::OCC_IS_FALSE,     ///< Skip if the variable is false
 117
 118                 /* Custom added value, only valid for this API */
 119                 CF_INVALID       = -1,                 ///< Invalid compare function, do not use.
 120         };
 121
 122         /**
 123          * Index in the list of orders for a vehicle. The first order has index 0, the second
 124          * order index 1, etc. The current order can be queried by using ORDER_CURRENT. Do not
 125          * use ORDER_INVALID yourself, it's used as return value by for example ResolveOrderPosition.
 126          * @note Automatic orders are hidden from scripts, so OrderPosition 0 will always be the first
 127          * manual order.
 128          */
 129         enum OrderPosition {
 130                 ORDER_CURRENT = 0xFF, ///< Constant that gets resolved to the current order.
 131                 ORDER_INVALID = -1,   ///< An invalid order.
 132         };
 133
 134         /** Where to stop trains in a station that's longer than the train */
 135         enum StopLocation {
 136                 STOPLOCATION_NEAR,         ///< Stop the train as soon as it's completely in the station
 137                 STOPLOCATION_MIDDLE,       ///< Stop the train in the middle of the station
 138                 STOPLOCATION_FAR,          ///< Stop the train at the far end of the station
 139                 STOPLOCATION_INVALID = -1, ///< An invalid stop location
 140         };
 141
 142         /**
 143          * Checks whether the given order id is valid for the given vehicle.
 144          * @param vehicle_id The vehicle to check the order index for.
 145          * @param order_position The order index to check.
 146          * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
 147          * @return True if and only if the order_position is valid for the given vehicle.
 148          */
 149         static bool IsValidVehicleOrder(VehicleID vehicle_id, OrderPosition order_position);
 150
 151         /**
 152          * Checks whether the given order is a goto-station order.
 153          * @param vehicle_id The vehicle to check.
 154          * @param order_position The order index to check.
 155          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 156          * @return True if and only if the order is a goto-station order.
 157          */
 158         static bool IsGotoStationOrder(VehicleID vehicle_id, OrderPosition order_position);
 159
 160         /**
 161          * Checks whether the given order is a goto-depot order.
 162          * @param vehicle_id The vehicle to check.
 163          * @param order_position The order index to check.
 164          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 165          * @return True if and only if the order is a goto-depot order.
 166          */
 167         static bool IsGotoDepotOrder(VehicleID vehicle_id, OrderPosition order_position);
 168
 169         /**
 170          * Checks whether the given order is a goto-waypoint order.
 171          * @param vehicle_id The vehicle to check.
 172          * @param order_position The order index to check.
 173          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 174          * @return True if and only if the order is a goto-waypoint order.
 175          */
 176         static bool IsGotoWaypointOrder(VehicleID vehicle_id, OrderPosition order_position);
 177
 178         /**
 179          * Checks whether the given order is a conditional order.
 180          * @param vehicle_id The vehicle to check.
 181          * @param order_position The order index to check.
 182          * @pre order_position != ORDER_CURRENT && IsValidVehicleOrder(vehicle_id, order_position).
 183          * @return True if and only if the order is a conditional order.
 184          */
 185         static bool IsConditionalOrder(VehicleID vehicle_id, OrderPosition order_position);
 186
 187         /**
 188          * Checks whether the given order is a void order.
 189          * A void order is an order that used to be a goto station, depot or waypoint order but
 190          * its destination got removed. In OpenTTD these orders as shown as "(Invalid Order)"
 191          * in the order list of a vehicle.
 192          * @param vehicle_id The vehicle to check.
 193          * @param order_position The order index to check.
 194          * @pre order_position != ORDER_CURRENT && IsValidVehicleOrder(vehicle_id, order_position).
 195          * @return True if and only if the order is a void order.
 196          */
 197         static bool IsVoidOrder(VehicleID vehicle_id, OrderPosition order_position);
 198
 199         /**
 200          * Checks whether the given order has a valid refit cargo.
 201          * @param vehicle_id The vehicle to check.
 202          * @param order_position The order index to check.
 203          * @pre order_position != ORDER_CURRENT && IsValidVehicleOrder(vehicle_id, order_position).
 204          * @return True if and only if the order is has a valid refit cargo.
 205          */
 206         static bool IsRefitOrder(VehicleID vehicle_id, OrderPosition order_position);
 207
 208         /**
 209          * Checks whether the current order is part of the orderlist.
 210          * @param vehicle_id The vehicle to check.
 211          * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
 212          * @return True if and only if the current order is part of the order list.
 213          * @note If the order is a non-'non-stop' order, and the vehicle is currently
 214          * (un)loading at a station that is not the final destination, this function
 215          * will still return true.
 216          */
 217         static bool IsCurrentOrderPartOfOrderList(VehicleID vehicle_id);
 218
 219         /**
 220          * Resolves the given order index to the correct index for the given vehicle.
 221          *  If the order index was ORDER_CURRENT it will be resolved to the index of
 222          *  the current order (as shown in the order list). If the order with the
 223          *  given index does not exist it will return ORDER_INVALID.
 224          * @param vehicle_id The vehicle to check the order index for.
 225          * @param order_position The order index to resolve.
 226          * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
 227          * @return The resolved order index.
 228          */
 229         static OrderPosition ResolveOrderPosition(VehicleID vehicle_id, OrderPosition order_position);
 230
 231         /**
 232          * Checks whether the given order flags are valid for the given destination.
 233          * @param destination The destination of the order.
 234          * @param order_flags The flags given to the order.
 235          * @return True if and only if the order_flags are valid for the given location.
 236          */
 237         static bool AreOrderFlagsValid(TileIndex destination, ScriptOrderFlags order_flags);
 238
 239         /**
 240          * Checks whether the given combination of condition and compare function is valid.
 241          * @param condition The condition to check.
 242          * @param compare The compare function to check.
 243          * @return True if and only if the combination of condition and compare function is valid.
 244          */
 245         static bool IsValidConditionalOrder(OrderCondition condition, CompareFunction compare);
 246
 247         /**
 248          * Returns the number of orders for the given vehicle.
 249          * @param vehicle_id The vehicle to get the order count of.
 250          * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
 251          * @return The number of orders for the given vehicle or a negative
 252          *   value when the vehicle does not exist.
 253          */
 254         static int32 GetOrderCount(VehicleID vehicle_id);
 255
 256         /**
 257          * Gets the destination of the given order for the given vehicle.
 258          * @param vehicle_id The vehicle to get the destination for.
 259          * @param order_position The order to get the destination for.
 260          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 261          * @pre order_position == ORDER_CURRENT || !IsConditionalOrder(vehicle_id, order_position).
 262          * @note Giving ORDER_CURRENT as order_position will give the order that is
 263          *  currently being executed by the vehicle. This is not necessarily the
 264          *  current order as given by ResolveOrderPosition (the current index in the
 265          *  order list) as manual or autoservicing depot orders do not show up
 266          *  in the orderlist, but they can be the current order of a vehicle.
 267          * @return The destination tile of the order.
 268          */
 269         static TileIndex GetOrderDestination(VehicleID vehicle_id, OrderPosition order_position);
 270
 271         /**
 272          * Gets the ScriptOrderFlags of the given order for the given vehicle.
 273          * @param vehicle_id The vehicle to get the destination for.
 274          * @param order_position The order to get the destination for.
 275          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 276          * @pre order_position == ORDER_CURRENT || (!IsConditionalOrder(vehicle_id, order_position) && !IsVoidOrder(vehicle_id, order_position)).
 277          * @note Giving ORDER_CURRENT as order_position will give the order that is
 278          *  currently being executed by the vehicle. This is not necessarily the
 279          *  current order as given by ResolveOrderPosition (the current index in the
 280          *  order list) as manual or autoservicing depot orders do not show up
 281          *  in the orderlist, but they can be the current order of a vehicle.
 282          * @return The ScriptOrderFlags of the order.
 283          */
 284         static ScriptOrderFlags GetOrderFlags(VehicleID vehicle_id, OrderPosition order_position);
 285
 286         /**
 287          * Gets the OrderPosition to jump to if the check succeeds of the given order for the given vehicle.
 288          * @param vehicle_id The vehicle to get the OrderPosition for.
 289          * @param order_position The order to get the OrderPosition for.
 290          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 291          * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
 292          * @return The target of the conditional jump.
 293          */
 294         static OrderPosition GetOrderJumpTo(VehicleID vehicle_id, OrderPosition order_position);
 295
 296         /**
 297          * Gets the OrderCondition of the given order for the given vehicle.
 298          * @param vehicle_id The vehicle to get the condition type for.
 299          * @param order_position The order to get the condition type for.
 300          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 301          * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
 302          * @return The OrderCondition of the order.
 303          */
 304         static OrderCondition GetOrderCondition(VehicleID vehicle_id, OrderPosition order_position);
 305
 306         /**
 307          * Gets the CompareFunction of the given order for the given vehicle.
 308          * @param vehicle_id The vehicle to get the compare function for.
 309          * @param order_position The order to get the compare function for.
 310          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 311          * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
 312          * @return The CompareFunction of the order.
 313          */
 314         static CompareFunction GetOrderCompareFunction(VehicleID vehicle_id, OrderPosition order_position);
 315
 316         /**
 317          * Gets the value to compare against of the given order for the given vehicle.
 318          * @param vehicle_id The vehicle to get the value for.
 319          * @param order_position The order to get the value for.
 320          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 321          * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
 322          * @return The value to compare against of the order.
 323          */
 324         static int32 GetOrderCompareValue(VehicleID vehicle_id, OrderPosition order_position);
 325
 326         /**
 327          * Gets the stoplocation of the given order for the given train.
 328          * @param vehicle_id The vehicle to get the value for.
 329          * @param order_position The order to get the value for.
 330          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 331          * @pre ScriptVehicle::GetVehicleType(vehicle_id) == ScriptVehicle::VT_RAIL.
 332          * @pre IsGotoStationOrder(vehicle_id, order_position).
 333          * @return The relative position where the train will stop inside a station.
 334          */
 335         static StopLocation GetStopLocation(VehicleID vehicle_id, OrderPosition order_position);
 336
 337         /**
 338          * Gets the refit cargo type of the given order for the given vehicle.
 339          * @param vehicle_id The vehicle to get the refit cargo for.
 340          * @param order_position The order to get the refit cargo for.
 341          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 342          * @pre order_position == ORDER_CURRENT || IsGotoStationOrder(vehicle_id, order_position) || IsGotoDepotOrder(vehicle_id, order_position).
 343          * @note Giving ORDER_CURRENT as order_position will give the order that is
 344          *  currently being executed by the vehicle. This is not necessarily the
 345          *  current order as given by ResolveOrderPosition (the current index in the
 346          *  order list) as manual or autoservicing depot orders do not show up
 347          *  in the orderlist, but they can be the current order of a vehicle.
 348          * @return The refit cargo of the order or CT_NO_REFIT if no refit is set.
 349          */
 350         static CargoID GetOrderRefit(VehicleID vehicle_id, OrderPosition order_position);
 351
 352         /**
 353          * Sets the OrderPosition to jump to if the check succeeds of the given order for the given vehicle.
 354          * @param vehicle_id The vehicle to set the OrderPosition for.
 355          * @param order_position The order to set the OrderPosition for.
 356          * @param jump_to The order to jump to if the check succeeds.
 357          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 358          * @pre IsValidVehicleOrder(vehicle_id, jump_to).
 359          * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
 360          * @return Whether the order has been/can be changed.
 361          * @api -game
 362          */
 363         static bool SetOrderJumpTo(VehicleID vehicle_id, OrderPosition order_position, OrderPosition jump_to);
 364
 365         /**
 366          * Sets the OrderCondition of the given order for the given vehicle.
 367          * @param vehicle_id The vehicle to set the condition type for.
 368          * @param order_position The order to set the condition type for.
 369          * @param condition The condition to compare on.
 370          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 371          * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
 372          * @pre condition >= OC_LOAD_PERCENTAGE && condition <= OC_UNCONDITIONALLY.
 373          * @return Whether the order has been/can be changed.
 374          * @api -game
 375          */
 376         static bool SetOrderCondition(VehicleID vehicle_id, OrderPosition order_position, OrderCondition condition);
 377
 378         /**
 379          * Sets the CompareFunction of the given order for the given vehicle.
 380          * @param vehicle_id The vehicle to set the compare function for.
 381          * @param order_position The order to set the compare function for.
 382          * @param compare The new compare function of the order.
 383          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 384          * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
 385          * @pre compare >= CF_EQUALS && compare <= CF_IS_FALSE.
 386          * @return Whether the order has been/can be changed.
 387          * @api -game
 388          */
 389         static bool SetOrderCompareFunction(VehicleID vehicle_id, OrderPosition order_position, CompareFunction compare);
 390
 391         /**
 392          * Sets the value to compare against of the given order for the given vehicle.
 393          * @param vehicle_id The vehicle to set the value for.
 394          * @param order_position The order to set the value for.
 395          * @param value The value to compare against.
 396          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 397          * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
 398          * @pre value >= 0 && value < 2048.
 399          * @return Whether the order has been/can be changed.
 400          * @api -game
 401          */
 402         static bool SetOrderCompareValue(VehicleID vehicle_id, OrderPosition order_position, int32 value);
 403
 404         /**
 405          * Sets the stoplocation of the given order for the given train.
 406          * @param vehicle_id The vehicle to get the value for.
 407          * @param order_position The order to get the value for.
 408          * @param stop_location The relative position where a train will stop inside a station.
 409          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 410          * @pre ScriptVehicle::GetVehicleType(vehicle_id) == ScriptVehicle::VT_RAIL.
 411          * @pre IsGotoStationOrder(vehicle_id, order_position).
 412          * @pre stop_location >= STOPLOCATION_NEAR && stop_location <= STOPLOCATION_FAR
 413          * @return Whether the order has been/can be changed.
 414          * @api -game
 415          */
 416         static bool SetStopLocation(VehicleID vehicle_id, OrderPosition order_position, StopLocation stop_location);
 417
 418         /**
 419          * Sets the refit cargo type of the given order for the given vehicle.
 420          * @param vehicle_id The vehicle to set the refit cargo for.
 421          * @param order_position The order to set the refit cargo for.
 422          * @param refit_cargo The cargo to refit to. The refit can be cleared by passing CT_NO_REFIT.
 423          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 424          * @pre IsGotoStationOrder(vehicle_id, order_position) || (IsGotoDepotOrder(vehicle_id, order_position) && refit_cargo != CT_AUTO_REFIT).
 425          * @pre ScriptCargo::IsValidCargo(refit_cargo) || refit_cargo == CT_AUTO_REFIT || refit_cargo == CT_NO_REFIT
 426          * @return Whether the order has been/can be changed.
 427          * @api -game
 428          */
 429         static bool SetOrderRefit(VehicleID vehicle_id, OrderPosition order_position, CargoID refit_cargo);
 430
 431         /**
 432          * Appends an order to the end of the vehicle's order list.
 433          * @param vehicle_id The vehicle to append the order to.
 434          * @param destination The destination of the order.
 435          * @param order_flags The flags given to the order.
 436          * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
 437          * @pre AreOrderFlagsValid(destination, order_flags).
 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.
 442          * @api -game
 443          */
 444         static bool AppendOrder(VehicleID vehicle_id, TileIndex destination, ScriptOrderFlags order_flags);
 445
 446         /**
 447          * Appends a conditional order to the end of the vehicle's order list.
 448          * @param vehicle_id The vehicle to append the order to.
 449          * @param jump_to The OrderPosition to jump to if the condition is true.
 450          * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
 451          * @pre IsValidVehicleOrder(vehicle_id, jump_to).
 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.
 455          * @api -game
 456          */
 457         static bool AppendConditionalOrder(VehicleID vehicle_id, OrderPosition jump_to);
 458
 459         /**
 460          * Inserts an order before the given order_position into the vehicle's order list.
 461          * @param vehicle_id The vehicle to add the order to.
 462          * @param order_position The order to place the new order before.
 463          * @param destination The destination of the order.
 464          * @param order_flags The flags given to the order.
 465          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 466          * @pre AreOrderFlagsValid(destination, order_flags).
 467          * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
 468          * @exception ScriptOrder::ERR_ORDER_TOO_MANY
 469          * @exception ScriptOrder::ERR_ORDER_TOO_FAR_AWAY_FROM_PREVIOUS_DESTINATION
 470          * @return True if and only if the order was inserted.
 471          * @api -game
 472          */
 473         static bool InsertOrder(VehicleID vehicle_id, OrderPosition order_position, TileIndex destination, ScriptOrderFlags order_flags);
 474
 475         /**
 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 IsValidVehicleOrder(vehicle_id, order_position).
 481          * @pre IsValidVehicleOrder(vehicle_id, jump_to).
 482          * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
 483          * @exception ScriptOrder::ERR_ORDER_TOO_MANY
 484          * @return True if and only if the order was inserted.
 485          * @api -game
 486          */
 487         static bool InsertConditionalOrder(VehicleID vehicle_id, OrderPosition order_position, OrderPosition jump_to);
 488
 489         /**
 490          * Removes an order from the vehicle's order list.
 491          * @param vehicle_id The vehicle to remove the order from.
 492          * @param order_position The order to remove from the order list.
 493          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 494          * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
 495          * @return True if and only if the order was removed.
 496          * @api -game
 497          */
 498         static bool RemoveOrder(VehicleID vehicle_id, OrderPosition order_position);
 499
 500         /**
 501          * Internal function to help SetOrderFlags.
 502          * @api -all
 503          */
 504         static bool _SetOrderFlags();
 505
 506         /**
 507          * Changes the order flags of the given order.
 508          * @param vehicle_id The vehicle to change the order of.
 509          * @param order_position The order to change.
 510          * @param order_flags The new flags given to the order.
 511          * @pre IsValidVehicleOrder(vehicle_id, order_position).
 512          * @pre AreOrderFlagsValid(GetOrderDestination(vehicle_id, order_position), order_flags).
 513          * @pre (order_flags & OF_GOTO_NEAREST_DEPOT) == (GetOrderFlags(vehicle_id, order_position) & OF_GOTO_NEAREST_DEPOT).
 514          * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
 515          * @return True if and only if the order was changed.
 516          * @api -game
 517          */
 518         static bool SetOrderFlags(VehicleID vehicle_id, OrderPosition order_position, ScriptOrderFlags order_flags);
 519
 520         /**
 521          * Move an order inside the orderlist
 522          * @param vehicle_id The vehicle to move the orders.
 523          * @param order_position_move The order to move.
 524          * @param order_position_target The target order
 525          * @pre IsValidVehicleOrder(vehicle_id, order_position_move).
 526          * @pre IsValidVehicleOrder(vehicle_id, order_position_target).
 527          * @pre order_position_move != order_position_target.
 528          * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
 529          * @return True if and only if the order was moved.
 530          * @note If the order is moved to a lower place (e.g. from 7 to 2)
 531          *  the target order is moved upwards (e.g. 3). If the order is moved
 532          *  to a higher place (e.g. from 7 to 9) the target will be moved
 533          *  downwards (e.g. 8).
 534          * @api -game
 535          */
 536         static bool MoveOrder(VehicleID vehicle_id, OrderPosition order_position_move, OrderPosition order_position_target);
 537
 538         /**
 539          * Make a vehicle execute next_order instead of its current order.
 540          * @param vehicle_id The vehicle that should skip some orders.
 541          * @param next_order The order the vehicle should skip to.
 542          * @pre IsValidVehicleOrder(vehicle_id, next_order).
 543          * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
 544          * @return True if and only the current order was changed.
 545          * @api -game
 546          */
 547         static bool SkipToOrder(VehicleID vehicle_id, OrderPosition next_order);
 548
 549         /**
 550          * Copies the orders from another vehicle. The orders of the main vehicle
 551          *  are going to be the orders of the changed vehicle.
 552          * @param vehicle_id The vehicle to copy the orders to.
 553          * @param main_vehicle_id The vehicle to copy the orders from.
 554          * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
 555          * @pre ScriptVehicle::IsValidVehicle(main_vehicle_id).
 556          * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
 557          * @exception ScriptOrder::ERR_ORDER_TOO_MANY
 558          * @exception ScriptOrder::ERR_ORDER_AIRCRAFT_NOT_ENOUGH_RANGE
 559          * @return True if and only if the copying succeeded.
 560          * @api -game
 561          */
 562         static bool CopyOrders(VehicleID vehicle_id, VehicleID main_vehicle_id);
 563
 564         /**
 565          * Shares the orders between two vehicles. The orders of the main
 566          * vehicle are going to be the orders of the changed vehicle.
 567          * @param vehicle_id The vehicle to add to the shared order list.
 568          * @param main_vehicle_id The vehicle to share the orders with.
 569          * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
 570          * @pre ScriptVehicle::IsValidVehicle(main_vehicle_id).
 571          * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
 572          * @exception ScriptOrder::ERR_ORDER_AIRCRAFT_NOT_ENOUGH_RANGE
 573          * @return True if and only if the sharing succeeded.
 574          * @api -game
 575          */
 576         static bool ShareOrders(VehicleID vehicle_id, VehicleID main_vehicle_id);
 577
 578         /**
 579          * Removes the given vehicle from a shared orders list.
 580          * @param vehicle_id The vehicle to remove from the shared order list.
 581          * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
 582          * @return True if and only if the unsharing succeeded.
 583          * @api -game
 584          */
 585         static bool UnshareOrders(VehicleID vehicle_id);
 586
 587         /**
 588          * Get the distance between two points for a vehicle type.
 589          * Use this function to compute the distance between two tiles wrt. a vehicle type.
 590          * These vehicle-type specific distances are independent from other map distances, you may
 591          * use the result of this function to compare it with the result of
 592          * ScriptEngine::GetMaximumOrderDistance or ScriptVehicle::GetMaximumOrderDistance.
 593          * @param vehicle_type The vehicle type to get the distance for.
 594          * @param origin_tile Origin, can be any tile or a tile of a specific station.
 595          * @param dest_tile Destination, can be any tile or a tile of a specific station.
 596          * @return The distance between the origin and the destination for a
 597          *         vehicle of the given vehicle type.
 598          * @note   The unit of the order distances is unspecified and should
 599          *         not be compared with map distances
 600          * @see ScriptEngine::GetMaximumOrderDistance and ScriptVehicle::GetMaximumOrderDistance
 601          */
 602         static uint GetOrderDistance(ScriptVehicle::VehicleType vehicle_type, TileIndex origin_tile, TileIndex dest_tile);
 603 };
 604 DECLARE_ENUM_AS_BIT_SET(ScriptOrder::ScriptOrderFlags)
 605
 606 #endif /* SCRIPT_ORDER_HPP */