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