src/script/api/script_vehicle.hpp

   1 /* $Id: script_vehicle.hpp 24900 2013-01-08 22:46:42Z planetmaker $ */
   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_vehicle.hpp Everything to query and build vehicles. */
  11
  12 #ifndef SCRIPT_VEHICLE_HPP
  13 #define SCRIPT_VEHICLE_HPP
  14
  15 #include "script_road.hpp"
  16
  17 /**
  18  * Class that handles all vehicle related functions.
  19  * @api ai game
  20  */
  21 class ScriptVehicle : public ScriptObject {
  22 public:
  23         /**
  24          * All vehicle related error messages.
  25          */
  26         enum ErrorMessages {
  27                 /** Base for vehicle related errors */
  28                 ERR_VEHICLE_BASE = ScriptError::ERR_CAT_VEHICLE << ScriptError::ERR_CAT_BIT_SIZE,
  29
  30                 /** Too many vehicles in the game, can't build any more. */
  31                 ERR_VEHICLE_TOO_MANY,                   // [STR_ERROR_TOO_MANY_VEHICLES_IN_GAME]
  32
  33                 /** Vehicle is not available */
  34                 ERR_VEHICLE_NOT_AVAILABLE,              // [STR_ERROR_AIRCRAFT_NOT_AVAILABLE, STR_ERROR_ROAD_VEHICLE_NOT_AVAILABLE, STR_ERROR_SHIP_NOT_AVAILABLE, STR_ERROR_RAIL_VEHICLE_NOT_AVAILABLE]
  35
  36                 /** Vehicle can't be build due to game settigns */
  37                 ERR_VEHICLE_BUILD_DISABLED,             // [STR_ERROR_CAN_T_BUY_TRAIN, STR_ERROR_CAN_T_BUY_ROAD_VEHICLE, STR_ERROR_CAN_T_BUY_SHIP, STR_ERROR_CAN_T_BUY_AIRCRAFT]
  38
  39                 /** Vehicle can't be build in the selected depot */
  40                 ERR_VEHICLE_WRONG_DEPOT,                // [STR_ERROR_DEPOT_WRONG_DEPOT_TYPE]
  41
  42                 /** Vehicle can't return to the depot */
  43                 ERR_VEHICLE_CANNOT_SEND_TO_DEPOT,       // [STR_ERROR_CAN_T_SEND_TRAIN_TO_DEPOT, STR_ERROR_CAN_T_SEND_ROAD_VEHICLE_TO_DEPOT, STR_ERROR_CAN_T_SEND_SHIP_TO_DEPOT, STR_ERROR_CAN_T_SEND_AIRCRAFT_TO_HANGAR]
  44
  45                 /** Vehicle can't start / stop */
  46                 ERR_VEHICLE_CANNOT_START_STOP,          // [STR_ERROR_CAN_T_STOP_START_TRAIN, STR_ERROR_CAN_T_STOP_START_ROAD_VEHICLE, STR_ERROR_CAN_T_STOP_START_SHIP, STR_ERROR_CAN_T_STOP_START_AIRCRAFT]
  47
  48                 /** Vehicle can't turn */
  49                 ERR_VEHICLE_CANNOT_TURN,                // [STR_ERROR_CAN_T_MAKE_ROAD_VEHICLE_TURN, STR_ERROR_CAN_T_REVERSE_DIRECTION_TRAIN, STR_ERROR_CAN_T_REVERSE_DIRECTION_RAIL_VEHICLE, STR_ERROR_CAN_T_REVERSE_DIRECTION_RAIL_VEHICLE_MULTIPLE_UNITS]
  50
  51                 /** Vehicle can't be refit */
  52                 ERR_VEHICLE_CANNOT_REFIT,               // [STR_ERROR_CAN_T_REFIT_TRAIN, STR_ERROR_CAN_T_REFIT_ROAD_VEHICLE, STR_ERROR_CAN_T_REFIT_SHIP, STR_ERROR_CAN_T_REFIT_AIRCRAFT]
  53
  54                 /** Vehicle is destroyed */
  55                 ERR_VEHICLE_IS_DESTROYED,               // [STR_ERROR_VEHICLE_IS_DESTROYED]
  56
  57                 /** Vehicle is not in a depot */
  58                 ERR_VEHICLE_NOT_IN_DEPOT,               // [STR_ERROR_AIRCRAFT_MUST_BE_STOPPED_INSIDE_HANGAR, STR_ERROR_ROAD_VEHICLE_MUST_BE_STOPPED_INSIDE_DEPOT, STR_ERROR_TRAIN_MUST_BE_STOPPED_INSIDE_DEPOT, STR_ERROR_SHIP_MUST_BE_STOPPED_INSIDE_DEPOT]
  59
  60                 /** Vehicle is flying */
  61                 ERR_VEHICLE_IN_FLIGHT,                  // [STR_ERROR_AIRCRAFT_IS_IN_FLIGHT]
  62
  63                 /** Vehicle is without power */
  64                 ERR_VEHICLE_NO_POWER,                   // [STR_ERROR_TRAIN_START_NO_POWER]
  65
  66                 /** Vehicle would get too long during construction. */
  67                 ERR_VEHICLE_TOO_LONG,                   // [STR_ERROR_TRAIN_TOO_LONG]
  68         };
  69
  70         /**
  71          * The type of a vehicle available in the game. Trams for example are
  72          *  road vehicles, as maglev is a rail vehicle.
  73          */
  74         enum VehicleType {
  75                 VT_RAIL,           ///< Rail type vehicle.
  76                 VT_ROAD,           ///< Road type vehicle (bus / truck).
  77                 VT_WATER,          ///< Water type vehicle.
  78                 VT_AIR,            ///< Air type vehicle.
  79                 VT_INVALID = 0xFF, ///< Invalid vehicle type.
  80         };
  81
  82         /**
  83          * The different states a vehicle can be in.
  84          */
  85         enum VehicleState {
  86                 VS_RUNNING,        ///< The vehicle is currently running.
  87                 VS_STOPPED,        ///< The vehicle is stopped manually.
  88                 VS_IN_DEPOT,       ///< The vehicle is stopped in the depot.
  89                 VS_AT_STATION,     ///< The vehicle is stopped at a station and is currently loading or unloading.
  90                 VS_BROKEN,         ///< The vehicle has broken down and will start running again in a while.
  91                 VS_CRASHED,        ///< The vehicle is crashed (and will never run again).
  92
  93                 VS_INVALID = 0xFF, ///< An invalid vehicle state.
  94         };
  95
  96         static const VehicleID VEHICLE_INVALID = 0xFFFFF; ///< Invalid VehicleID.
  97
  98         /**
  99          * Checks whether the given vehicle is valid and owned by you.
 100          * @param vehicle_id The vehicle to check.
 101          * @return True if and only if the vehicle is valid.
 102          */
 103         static bool IsValidVehicle(VehicleID vehicle_id);
 104
 105         /**
 106          * Get the number of wagons a vehicle has.
 107          * @param vehicle_id The vehicle to get the number of wagons from.
 108          * @pre IsValidVehicle(vehicle_id).
 109          * @return The number of wagons the vehicle has.
 110          */
 111         static int32 GetNumWagons(VehicleID vehicle_id);
 112
 113         /**
 114          * Set the name of a vehicle.
 115          * @param vehicle_id The vehicle to set the name for.
 116          * @param name The name for the vehicle (can be either a raw string, or a ScriptText object).
 117          * @pre IsValidVehicle(vehicle_id).
 118          * @pre name != NULL && len(name) != 0.
 119          * @game @pre Valid ScriptCompanyMode active in scope.
 120          * @exception ScriptError::ERR_NAME_IS_NOT_UNIQUE
 121          * @return True if and only if the name was changed.
 122          */
 123         static bool SetName(VehicleID vehicle_id, Text *name);
 124
 125         /**
 126          * Get the name of a vehicle.
 127          * @param vehicle_id The vehicle to get the name of.
 128          * @pre IsValidVehicle(vehicle_id).
 129          * @return The name the vehicle has.
 130          */
 131         static char *GetName(VehicleID vehicle_id);
 132
 133         /**
 134          * Get the owner of a vehicle.
 135          * @param vehicle_id The vehicle to get the owner of.
 136          * @pre IsValidVehicle(vehicle_id).
 137          * @return The owner the vehicle has.
 138          * @api -ai
 139          */
 140         static ScriptCompany::CompanyID GetOwner(VehicleID vehicle_id);
 141
 142         /**
 143          * Get the current location of a vehicle.
 144          * @param vehicle_id The vehicle to get the location of.
 145          * @pre IsValidVehicle(vehicle_id).
 146          * @return The tile the vehicle is currently on.
 147          */
 148         static TileIndex GetLocation(VehicleID vehicle_id);
 149
 150         /**
 151          * Get the engine-type of a vehicle.
 152          * @param vehicle_id The vehicle to get the engine-type of.
 153          * @pre IsValidVehicle(vehicle_id).
 154          * @return The engine type the vehicle has.
 155          */
 156         static EngineID GetEngineType(VehicleID vehicle_id);
 157
 158         /**
 159          * Get the engine-type of a wagon.
 160          * @param vehicle_id The vehicle to get the engine-type of.
 161          * @param wagon The wagon in the vehicle to get the engine-type of.
 162          * @pre IsValidVehicle(vehicle_id).
 163          * @pre wagon < GetNumWagons(vehicle_id).
 164          * @return The engine type the vehicle has.
 165          */
 166         static EngineID GetWagonEngineType(VehicleID vehicle_id, int wagon);
 167
 168         /**
 169          * Get the unitnumber of a vehicle.
 170          * @param vehicle_id The vehicle to get the unitnumber of.
 171          * @pre IsValidVehicle(vehicle_id).
 172          * @return The unitnumber the vehicle has.
 173          */
 174         static int32 GetUnitNumber(VehicleID vehicle_id);
 175
 176         /**
 177          * Get the current age of a vehicle.
 178          * @param vehicle_id The vehicle to get the age of.
 179          * @pre IsValidVehicle(vehicle_id).
 180          * @return The current age the vehicle has.
 181          * @note The age is in days.
 182          */
 183         static int32 GetAge(VehicleID vehicle_id);
 184
 185         /**
 186          * Get the current age of a second (or third, etc.) engine in a train vehicle.
 187          * @param vehicle_id The vehicle to get the age of.
 188          * @param wagon The wagon in the vehicle to get the age of.
 189          * @pre IsValidVehicle(vehicle_id).
 190          * @pre wagon < GetNumWagons(vehicle_id).
 191          * @return The current age the vehicle has.
 192          * @note The age is in days.
 193          */
 194         static int32 GetWagonAge(VehicleID vehicle_id, int wagon);
 195
 196         /**
 197          * Get the maximum age of a vehicle.
 198          * @param vehicle_id The vehicle to get the age of.
 199          * @pre IsValidVehicle(vehicle_id).
 200          * @return The maximum age the vehicle has.
 201          * @note The age is in days.
 202          */
 203         static int32 GetMaxAge(VehicleID vehicle_id);
 204
 205         /**
 206          * Get the age a vehicle has left (maximum - current).
 207          * @param vehicle_id The vehicle to get the age of.
 208          * @pre IsValidVehicle(vehicle_id).
 209          * @return The age the vehicle has left.
 210          * @note The age is in days.
 211          */
 212         static int32 GetAgeLeft(VehicleID vehicle_id);
 213
 214         /**
 215          * Get the current speed of a vehicle.
 216          * @param vehicle_id The vehicle to get the speed of.
 217          * @pre IsValidVehicle(vehicle_id).
 218          * @return The current speed of the vehicle.
 219          * @note The speed is in OpenTTD's internal speed unit.
 220          *       This is mph / 1.6, which is roughly km/h.
 221          *       To get km/h multiply this number by 1.00584.
 222          */
 223         static int32 GetCurrentSpeed(VehicleID vehicle_id);
 224
 225         /**
 226          * Get the current state of a vehicle.
 227          * @param vehicle_id The vehicle to get the state of.
 228          * @pre IsValidVehicle(vehicle_id).
 229          * @return The current state of the vehicle.
 230          */
 231         static VehicleState GetState(VehicleID vehicle_id);
 232
 233         /**
 234          * Get the running cost of this vehicle.
 235          * @param vehicle_id The vehicle to get the running cost of.
 236          * @pre IsValidVehicle(vehicle_id).
 237          * @return The running cost of the vehicle per year.
 238          * @note Cost is per year; divide by 365 to get per day.
 239          * @note This is not equal to ScriptEngine::GetRunningCost for Trains, because
 240          *   wagons and second engines can add up in the calculation too.
 241          */
 242         static Money GetRunningCost(VehicleID vehicle_id);
 243
 244         /**
 245          * Get the current profit of a vehicle.
 246          * @param vehicle_id The vehicle to get the profit of.
 247          * @pre IsValidVehicle(vehicle_id).
 248          * @return The current profit the vehicle has.
 249          */
 250         static Money GetProfitThisYear(VehicleID vehicle_id);
 251
 252         /**
 253          * Get the profit of last year of a vehicle.
 254          * @param vehicle_id The vehicle to get the profit of.
 255          * @pre IsValidVehicle(vehicle_id).
 256          * @return The profit the vehicle had last year.
 257          */
 258         static Money GetProfitLastYear(VehicleID vehicle_id);
 259
 260
 261         /**
 262          * Get the current value of a vehicle.
 263          * @param vehicle_id The vehicle to get the value of.
 264          * @pre IsValidVehicle(vehicle_id).
 265          * @return The value the vehicle currently has (the amount you should get
 266          *  when you would sell the vehicle right now).
 267          */
 268         static Money GetCurrentValue(VehicleID vehicle_id);
 269
 270         /**
 271          * Get the type of vehicle.
 272          * @param vehicle_id The vehicle to get the type of.
 273          * @pre IsValidVehicle(vehicle_id).
 274          * @return The vehicle type.
 275          */
 276         static ScriptVehicle::VehicleType GetVehicleType(VehicleID vehicle_id);
 277
 278         /**
 279          * Get the RoadType of the vehicle.
 280          * @param vehicle_id The vehicle to get the RoadType of.
 281          * @pre IsValidVehicle(vehicle_id).
 282          * @pre GetVehicleType(vehicle_id) == VT_ROAD.
 283          * @return The RoadType the vehicle has.
 284          */
 285         static ScriptRoad::RoadType GetRoadType(VehicleID vehicle_id);
 286
 287         /**
 288          * Check if a vehicle is in a depot.
 289          * @param vehicle_id The vehicle to check.
 290          * @pre IsValidVehicle(vehicle_id).
 291          * @return True if and only if the vehicle is in a depot.
 292          */
 293         static bool IsInDepot(VehicleID vehicle_id);
 294
 295         /**
 296          * Check if a vehicle is in a depot and stopped.
 297          * @param vehicle_id The vehicle to check.
 298          * @pre IsValidVehicle(vehicle_id).
 299          * @return True if and only if the vehicle is in a depot and stopped.
 300          */
 301         static bool IsStoppedInDepot(VehicleID vehicle_id);
 302
 303         /**
 304          * Builds a vehicle with the given engine at the given depot.
 305          * @param depot The depot where the vehicle will be build.
 306          * @param engine_id The engine to use for this vehicle.
 307          * @pre The tile at depot has a depot that can build the engine and
 308          *   is owned by you.
 309          * @pre ScriptEngine::IsBuildable(engine_id).
 310          * @game @pre Valid ScriptCompanyMode active in scope.
 311          * @exception ScriptVehicle::ERR_VEHICLE_TOO_MANY
 312          * @exception ScriptVehicle::ERR_VEHICLE_BUILD_DISABLED
 313          * @exception ScriptVehicle::ERR_VEHICLE_WRONG_DEPOT
 314          * @return The VehicleID of the new vehicle, or an invalid VehicleID when
 315          *   it failed. Check the return value using IsValidVehicle. In test-mode
 316          *   0 is returned if it was successful; any other value indicates failure.
 317          * @note In Test Mode it means you can't assign orders yet to this vehicle,
 318          *   as the vehicle isn't really built yet. Build it for real first before
 319          *   assigning orders.
 320          */
 321         static VehicleID BuildVehicle(TileIndex depot, EngineID engine_id);
 322
 323         /**
 324          * Clones a vehicle at the given depot, copying or cloning its orders.
 325          * @param depot The depot where the vehicle will be build.
 326          * @param vehicle_id The vehicle to use as example for the new vehicle.
 327          * @param share_orders Should the orders be copied or shared?
 328          * @pre The tile 'depot' has a depot on it, allowing 'vehicle_id'-type vehicles.
 329          * @pre IsValidVehicle(vehicle_id).
 330          * @game @pre Valid ScriptCompanyMode active in scope.
 331          * @exception ScriptVehicle::ERR_VEHICLE_TOO_MANY
 332          * @exception ScriptVehicle::ERR_VEHICLE_BUILD_DISABLED
 333          * @exception ScriptVehicle::ERR_VEHICLE_WRONG_DEPOT
 334          * @return The VehicleID of the new vehicle, or an invalid VehicleID when
 335          *   it failed. Check the return value using IsValidVehicle. In test-mode
 336          *   0 is returned if it was successful; any other value indicates failure.
 337          */
 338         static VehicleID CloneVehicle(TileIndex depot, VehicleID vehicle_id, bool share_orders);
 339
 340         /**
 341          * Move a wagon after another wagon.
 342          * @param source_vehicle_id The vehicle to move a wagon away from.
 343          * @param source_wagon The wagon in source_vehicle to move.
 344          * @param dest_vehicle_id The vehicle to move the wagon to, or -1 to create a new vehicle.
 345          * @param dest_wagon The wagon in dest_vehicle to place source_wagon after.
 346          * @pre IsValidVehicle(source_vehicle_id).
 347          * @pre source_wagon < GetNumWagons(source_vehicle_id).
 348          * @pre dest_vehicle_id == -1 || (IsValidVehicle(dest_vehicle_id) && dest_wagon < GetNumWagons(dest_vehicle_id)).
 349          * @pre GetVehicleType(source_vehicle_id) == VT_RAIL.
 350          * @pre dest_vehicle_id == -1 || GetVehicleType(dest_vehicle_id) == VT_RAIL.
 351          * @game @pre Valid ScriptCompanyMode active in scope.
 352          * @return Whether or not moving the wagon succeeded.
 353          */
 354         static bool MoveWagon(VehicleID source_vehicle_id, int source_wagon, int dest_vehicle_id, int dest_wagon);
 355
 356         /**
 357          * Move a chain of wagons after another wagon.
 358          * @param source_vehicle_id The vehicle to move a wagon away from.
 359          * @param source_wagon The first wagon in source_vehicle to move.
 360          * @param dest_vehicle_id The vehicle to move the wagons to, or -1 to create a new vehicle.
 361          * @param dest_wagon The wagon in dest_vehicle to place source_wagon and following wagons after.
 362          * @pre IsValidVehicle(source_vehicle_id).
 363          * @pre source_wagon < GetNumWagons(source_vehicle_id).
 364          * @pre dest_vehicle_id == -1 || (IsValidVehicle(dest_vehicle_id) && dest_wagon < GetNumWagons(dest_vehicle_id)).
 365          * @pre GetVehicleType(source_vehicle_id) == VT_RAIL.
 366          * @pre dest_vehicle_id == -1 || GetVehicleType(dest_vehicle_id) == VT_RAIL.
 367          * @game @pre Valid ScriptCompanyMode active in scope.
 368          * @return Whether or not moving the wagons succeeded.
 369          */
 370         static bool MoveWagonChain(VehicleID source_vehicle_id, int source_wagon, int dest_vehicle_id, int dest_wagon);
 371
 372         /**
 373          * Gets the capacity of the given vehicle when refitted to the given cargo type.
 374          * @param vehicle_id The vehicle to refit.
 375          * @param cargo The cargo to refit to.
 376          * @pre IsValidVehicle(vehicle_id).
 377          * @pre ScriptCargo::IsValidCargo(cargo).
 378          * @pre You must own the vehicle.
 379          * @pre The vehicle must be stopped in the depot.
 380          * @return The capacity the vehicle will have when refited.
 381          */
 382         static int GetRefitCapacity(VehicleID vehicle_id, CargoID cargo);
 383
 384         /**
 385          * Refits a vehicle to the given cargo type.
 386          * @param vehicle_id The vehicle to refit.
 387          * @param cargo The cargo to refit to.
 388          * @pre IsValidVehicle(vehicle_id).
 389          * @pre ScriptCargo::IsValidCargo(cargo).
 390          * @pre You must own the vehicle.
 391          * @pre The vehicle must be stopped in the depot.
 392          * @game @pre Valid ScriptCompanyMode active in scope.
 393          * @exception ScriptVehicle::ERR_VEHICLE_CANNOT_REFIT
 394          * @exception ScriptVehicle::ERR_VEHICLE_IS_DESTROYED
 395          * @exception ScriptVehicle::ERR_VEHICLE_NOT_IN_DEPOT
 396          * @return True if and only if the refit succeeded.
 397          */
 398         static bool RefitVehicle(VehicleID vehicle_id, CargoID cargo);
 399
 400         /**
 401          * Sells the given vehicle.
 402          * @param vehicle_id The vehicle to sell.
 403          * @pre IsValidVehicle(vehicle_id).
 404          * @pre You must own the vehicle.
 405          * @pre The vehicle must be stopped in the depot.
 406          * @game @pre Valid ScriptCompanyMode active in scope.
 407          * @exception ScriptVehicle::ERR_VEHICLE_IS_DESTROYED
 408          * @exception ScriptVehicle::ERR_VEHICLE_NOT_IN_DEPOT
 409          * @return True if and only if the vehicle has been sold.
 410          */
 411         static bool SellVehicle(VehicleID vehicle_id);
 412
 413         /**
 414          * Sells the given wagon from the vehicle.
 415          * @param vehicle_id The vehicle to sell a wagon from.
 416          * @param wagon The wagon to sell.
 417          * @pre IsValidVehicle(vehicle_id).
 418          * @pre wagon < GetNumWagons(vehicle_id).
 419          * @pre You must own the vehicle.
 420          * @pre The vehicle must be stopped in the depot.
 421          * @game @pre Valid ScriptCompanyMode active in scope.
 422          * @exception ScriptVehicle::ERR_VEHICLE_IS_DESTROYED
 423          * @exception ScriptVehicle::ERR_VEHICLE_NOT_IN_DEPOT
 424          * @return True if and only if the wagon has been sold.
 425          */
 426         static bool SellWagon(VehicleID vehicle_id, int wagon);
 427
 428         /**
 429          * Sells all wagons from the vehicle starting from a given position.
 430          * @param vehicle_id The vehicle to sell a wagon from.
 431          * @param wagon The wagon to sell.
 432          * @pre IsValidVehicle(vehicle_id).
 433          * @pre wagon < GetNumWagons(vehicle_id).
 434          * @pre You must own the vehicle.
 435          * @pre The vehicle must be stopped in the depot.
 436          * @game @pre Valid ScriptCompanyMode active in scope.
 437          * @exception ScriptVehicle::ERR_VEHICLE_IS_DESTROYED
 438          * @exception ScriptVehicle::ERR_VEHICLE_NOT_IN_DEPOT
 439          * @return True if and only if the wagons have been sold.
 440          */
 441         static bool SellWagonChain(VehicleID vehicle_id, int wagon);
 442
 443         /**
 444          * Sends the given vehicle to a depot. If the vehicle has already been
 445          * sent to a depot it continues with its normal orders instead.
 446          * @param vehicle_id The vehicle to send to a depot.
 447          * @pre IsValidVehicle(vehicle_id).
 448          * @game @pre Valid ScriptCompanyMode active in scope.
 449          * @exception ScriptVehicle::ERR_VEHICLE_CANNOT_SEND_TO_DEPOT
 450          * @return True if the current order was changed.
 451          */
 452         static bool SendVehicleToDepot(VehicleID vehicle_id);
 453
 454         /**
 455          * Sends the given vehicle to a depot for servicing. If the vehicle has
 456          * already been sent to a depot it continues with its normal orders instead.
 457          * @param vehicle_id The vehicle to send to a depot for servicing.
 458          * @pre IsValidVehicle(vehicle_id).
 459          * @game @pre Valid ScriptCompanyMode active in scope.
 460          * @exception ScriptVehicle::ERR_VEHICLE_CANNOT_SEND_TO_DEPOT
 461          * @return True if the current order was changed.
 462          */
 463         static bool SendVehicleToDepotForServicing(VehicleID vehicle_id);
 464
 465         /**
 466          * Starts or stops the given vehicle depending on the current state.
 467          * @param vehicle_id The vehicle to start/stop.
 468          * @pre IsValidVehicle(vehicle_id).
 469          * @game @pre Valid ScriptCompanyMode active in scope.
 470          * @exception ScriptVehicle::ERR_VEHICLE_CANNOT_START_STOP
 471          * @exception (For aircraft only): ScriptVehicle::ERR_VEHICLE_IN_FLIGHT
 472          * @exception (For trains only): ScriptVehicle::ERR_VEHICLE_NO_POWER
 473          * @return True if and only if the vehicle has been started or stopped.
 474          */
 475         static bool StartStopVehicle(VehicleID vehicle_id);
 476
 477         /**
 478          * Turn the given vehicle so it'll drive the other way.
 479          * @param vehicle_id The vehicle to turn.
 480          * @pre IsValidVehicle(vehicle_id).
 481          * @pre GetVehicleType(vehicle_id) == VT_ROAD || GetVehicleType(vehicle_id) == VT_RAIL.
 482          * @game @pre Valid ScriptCompanyMode active in scope.
 483          * @return True if and only if the vehicle has started to turn.
 484          * @note Vehicles cannot always be reversed. For example busses and trucks need to be running
 485          *  and not be inside a depot.
 486          */
 487         static bool ReverseVehicle(VehicleID vehicle_id);
 488
 489         /**
 490          * Get the maximum amount of a specific cargo the given vehicle can transport.
 491          * @param vehicle_id The vehicle to get the capacity of.
 492          * @param cargo The cargo to get the capacity for.
 493          * @pre IsValidVehicle(vehicle_id).
 494          * @pre ScriptCargo::IsValidCargo(cargo).
 495          * @return The maximum amount of the given cargo the vehicle can transport.
 496          */
 497         static int32 GetCapacity(VehicleID vehicle_id, CargoID cargo);
 498
 499         /**
 500          * Get the length of a the total vehicle in 1/16's of a tile.
 501          * @param vehicle_id The vehicle to get the length of.
 502          * @pre IsValidVehicle(vehicle_id).
 503          * @pre GetVehicleType(vehicle_id) == VT_ROAD || GetVehicleType(vehicle_id) == VT_RAIL.
 504          * @return The length of the engine.
 505          */
 506         static int GetLength(VehicleID vehicle_id);
 507
 508         /**
 509          * Get the amount of a specific cargo the given vehicle is transporting.
 510          * @param vehicle_id The vehicle to get the load amount of.
 511          * @param cargo The cargo to get the loaded amount for.
 512          * @pre IsValidVehicle(vehicle_id).
 513          * @pre ScriptCargo::IsValidCargo(cargo).
 514          * @return The amount of the given cargo the vehicle is currently transporting.
 515          */
 516         static int32 GetCargoLoad(VehicleID vehicle_id, CargoID cargo);
 517
 518         /**
 519          * Get the group of a given vehicle.
 520          * @param vehicle_id The vehicle to get the group from.
 521          * @return The group of the given vehicle.
 522          */
 523         static GroupID GetGroupID(VehicleID vehicle_id);
 524
 525         /**
 526          * Check if the vehicle is articulated.
 527          * @param vehicle_id The vehicle to check.
 528          * @pre IsValidVehicle(vehicle_id).
 529          * @pre GetVehicleType(vehicle_id) == VT_ROAD || GetVehicleType(vehicle_id) == VT_RAIL.
 530          * @return True if the vehicle is articulated.
 531          */
 532         static bool IsArticulated(VehicleID vehicle_id);
 533
 534         /**
 535          * Check if the vehicle has shared orders.
 536          * @param vehicle_id The vehicle to check.
 537          * @pre IsValidVehicle(vehicle_id).
 538          * @return True if the vehicle has shared orders.
 539          */
 540         static bool HasSharedOrders(VehicleID vehicle_id);
 541
 542         /**
 543          * Get the current reliability of a vehicle.
 544          * @param vehicle_id The vehicle to check.
 545          * @pre IsValidVehicle(vehicle_id).
 546          * @return The current reliability (0-100%).
 547          */
 548         static int GetReliability(VehicleID vehicle_id);
 549
 550         /**
 551          * Get the maximum allowed distance between two orders for a vehicle.
 552          * The distance returned is a vehicle-type specific distance independent from other
 553          * map distances, you may use the result of this function to compare it
 554          * with the result of ScriptOrder::GetOrderDistance.
 555          * @param vehicle_id The vehicle to get the distance for.
 556          * @pre IsValidVehicle(vehicle_id).
 557          * @return The maximum distance between two orders for this vehicle
 558          *         or 0 if the distance is unlimited.
 559          * @note   The unit of the order distances is unspecified and should
 560          *         not be compared with map distances
 561          * @see ScriptOrder::GetOrderDistance
 562          */
 563         static uint GetMaximumOrderDistance(VehicleID vehicle_id);
 564
 565 private:
 566         /**
 567          * Internal function used by SellWagon(Chain).
 568          */
 569         static bool _SellWagonInternal(VehicleID vehicle_id, int wagon, bool sell_attached_wagons);
 570
 571         /**
 572          * Internal function used by MoveWagon(Chain).
 573          */
 574         static bool _MoveWagonInternal(VehicleID source_vehicle_id, int source_wagon, bool move_attached_wagons, int dest_vehicle_id, int dest_wagon);
 575 };
 576
 577 #endif /* SCRIPT_VEHICLE_HPP */