src/script/api/script_engine.hpp

   1 /* $Id: script_engine.hpp 26307 2014-02-06 19:50:34Z zuu $ */
   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_engine.hpp Everything to query and build engines. */
  11
  12 #ifndef SCRIPT_ENGINE_HPP
  13 #define SCRIPT_ENGINE_HPP
  14
  15 #include "script_vehicle.hpp"
  16 #include "script_rail.hpp"
  17 #include "script_airport.hpp"
  18 #include "script_date.hpp"
  19
  20 /**
  21  * Class that handles all engine related functions.
  22  * @api ai game
  23  */
  24 class ScriptEngine : public ScriptObject {
  25 public:
  26         /**
  27          * Checks whether the given engine type is valid.
  28          * An engine is valid for a company if it has at least one vehicle of this engine or it's currently buildable.
  29          * @game Outside ScriptCompanyMode scope the function reports all engines valid, which were or will be available at some point.
  30          * @param engine_id The engine to check.
  31          * @return True if and only if the engine type is valid.
  32          */
  33         static bool IsValidEngine(EngineID engine_id);
  34
  35         /**
  36          * Checks whether the given engine type is buildable for a company.
  37          * @game Outside ScriptCompanyMode scope the function checks whether the engine is currently buildable by all companies (no exclusive preview).
  38          * @param engine_id The engine to check.
  39          * @return True if and only if the engine type is buildable.
  40          */
  41         static bool IsBuildable(EngineID engine_id);
  42
  43         /**
  44          * Get the name of an engine.
  45          * @param engine_id The engine to get the name of.
  46          * @pre IsValidEngine(engine_id).
  47          * @return The name the engine has.
  48          */
  49         static char *GetName(EngineID engine_id);
  50
  51         /**
  52          * Get the cargo-type of an engine. In case it can transport multiple cargoes, it
  53          *  returns the first/main.
  54          * @param engine_id The engine to get the cargo-type of.
  55          * @pre IsValidEngine(engine_id).
  56          * @return The cargo-type of the engine.
  57          */
  58         static CargoID GetCargoType(EngineID engine_id);
  59
  60         /**
  61          * Check if the cargo of an engine can be refitted to your requested. If
  62          *  the engine already allows this cargo, the function also returns true.
  63          *  In case of articulated vehicles the function decides whether at least one
  64          *  part can carry the cargo.
  65          * @param engine_id The engine to check for refitting.
  66          * @param cargo_id The cargo to check for refitting.
  67          * @pre IsValidEngine(engine_id).
  68          * @pre ScriptCargo::IsValidCargo(cargo_id).
  69          * @return True if the engine can carry this cargo, either via refit, or
  70          *  by default.
  71          */
  72         static bool CanRefitCargo(EngineID engine_id, CargoID cargo_id);
  73
  74         /**
  75          * Check if the engine can pull a wagon with the given cargo.
  76          * @param engine_id The engine to check.
  77          * @param cargo_id The cargo to check.
  78          * @pre IsValidEngine(engine_id).
  79          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_RAIL.
  80          * @pre ScriptCargo::IsValidCargo(cargo_id).
  81          * @return True if the engine can pull wagons carrying this cargo.
  82          * @note This function is not exhaustive; a true here does not mean
  83          *  that the vehicle can pull the wagons, a false does mean it can't.
  84          */
  85         static bool CanPullCargo(EngineID engine_id, CargoID cargo_id);
  86
  87         /**
  88          * Get the capacity of an engine. In case it can transport multiple cargoes, it
  89          *  returns the first/main.
  90          * @param engine_id The engine to get the capacity of.
  91          * @pre IsValidEngine(engine_id).
  92          * @return The capacity of the engine.
  93          */
  94         static int32 GetCapacity(EngineID engine_id);
  95
  96         /**
  97          * Get the reliability of an engine. The value is between 0 and 100, where
  98          *  100 means 100% reliability (never breaks down) and 0 means 0%
  99          *  reliability (you most likely don't want to buy it).
 100          * @param engine_id The engine to get the reliability of.
 101          * @pre IsValidEngine(engine_id).
 102          * @pre GetVehicleType(engine_id) != ScriptVehicle::VT_TRAIN || !IsWagon(engine_id).
 103          * @return The reliability the engine has.
 104          */
 105         static int32 GetReliability(EngineID engine_id);
 106
 107         /**
 108          * Get the maximum speed of an engine.
 109          * @param engine_id The engine to get the maximum speed of.
 110          * @pre IsValidEngine(engine_id).
 111          * @return The maximum speed the engine has.
 112          * @note The speed is in OpenTTD's internal speed unit.
 113          *       This is mph / 1.6, which is roughly km/h.
 114          *       To get km/h multiply this number by 1.00584.
 115          */
 116         static int32 GetMaxSpeed(EngineID engine_id);
 117
 118         /**
 119          * Get the new cost of an engine.
 120          * @param engine_id The engine to get the new cost of.
 121          * @pre IsValidEngine(engine_id).
 122          * @return The new cost the engine has.
 123          */
 124         static Money GetPrice(EngineID engine_id);
 125
 126         /**
 127          * Get the maximum age of a brand new engine.
 128          * @param engine_id The engine to get the maximum age of.
 129          * @pre IsValidEngine(engine_id).
 130          * @returns The maximum age of a new engine in days.
 131          * @note Age is in days; divide by 366 to get per year.
 132          */
 133         static int32 GetMaxAge(EngineID engine_id);
 134
 135         /**
 136          * Get the running cost of an engine.
 137          * @param engine_id The engine to get the running cost of.
 138          * @pre IsValidEngine(engine_id).
 139          * @return The running cost of a vehicle per year.
 140          * @note Cost is per year; divide by 365 to get per day.
 141          */
 142         static Money GetRunningCost(EngineID engine_id);
 143
 144         /**
 145          * Get the power of an engine.
 146          * @param engine_id The engine to get the power of.
 147          * @pre IsValidEngine(engine_id).
 148          * @pre (GetVehicleType(engine_id) == ScriptVehicle::VT_RAIL || GetVehicleType(engine_id) == ScriptVehicle::VT_ROAD) && !IsWagon(engine_id).
 149          * @return The power of the engine in hp.
 150          */
 151         static int32 GetPower(EngineID engine_id);
 152
 153         /**
 154          * Get the weight of an engine.
 155          * @param engine_id The engine to get the weight of.
 156          * @pre IsValidEngine(engine_id).
 157          * @pre (GetVehicleType(engine_id) == ScriptVehicle::VT_RAIL || GetVehicleType(engine_id) == ScriptVehicle::VT_ROAD).
 158          * @return The weight of the engine in metric tons.
 159          */
 160         static int32 GetWeight(EngineID engine_id);
 161
 162         /**
 163          * Get the maximum tractive effort of an engine.
 164          * @param engine_id The engine to get the maximum tractive effort of.
 165          * @pre IsValidEngine(engine_id).
 166          * @pre (GetVehicleType(engine_id) == ScriptVehicle::VT_RAIL || GetVehicleType(engine_id) == ScriptVehicle::VT_ROAD) && !IsWagon(engine_id).
 167          * @return The maximum tractive effort of the engine in kN.
 168          */
 169         static int32 GetMaxTractiveEffort(EngineID engine_id);
 170
 171         /**
 172          * Get the date this engine was designed.
 173          * @param engine_id The engine to get the design date of.
 174          * @pre IsValidEngine(engine_id).
 175          * @return The date this engine was designed.
 176          */
 177         static ScriptDate::Date GetDesignDate(EngineID engine_id);
 178
 179         /**
 180          * Get the type of an engine.
 181          * @param engine_id The engine to get the type of.
 182          * @pre IsValidEngine(engine_id).
 183          * @return The type the engine has.
 184          */
 185         static ScriptVehicle::VehicleType GetVehicleType(EngineID engine_id);
 186
 187         /**
 188          * Check if an engine is a wagon.
 189          * @param engine_id The engine to check.
 190          * @pre IsValidEngine(engine_id).
 191          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_RAIL.
 192          * @return Whether or not the engine is a wagon.
 193          */
 194         static bool IsWagon(EngineID engine_id);
 195
 196         /**
 197          * Check if a train vehicle can run on a RailType.
 198          * @param engine_id The engine to check.
 199          * @param track_rail_type The type you want to check.
 200          * @pre IsValidEngine(engine_id).
 201          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_RAIL.
 202          * @pre ScriptRail::IsRailTypeAvailable(track_rail_type).
 203          * @return Whether an engine of type 'engine_id' can run on 'track_rail_type'.
 204          * @note Even if a train can run on a RailType that doesn't mean that it'll be
 205          *   able to power the train. Use HasPowerOnRail for that.
 206          */
 207         static bool CanRunOnRail(EngineID engine_id, ScriptRail::RailType track_rail_type);
 208
 209         /**
 210          * Check if a train engine has power on a RailType.
 211          * @param engine_id The engine to check.
 212          * @param track_rail_type Another RailType.
 213          * @pre IsValidEngine(engine_id).
 214          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_RAIL.
 215          * @pre ScriptRail::IsRailTypeAvailable(track_rail_type).
 216          * @return Whether an engine of type 'engine_id' has power on 'track_rail_type'.
 217          */
 218         static bool HasPowerOnRail(EngineID engine_id, ScriptRail::RailType track_rail_type);
 219
 220         /**
 221          * Get the RoadType of the engine.
 222          * @param engine_id The engine to get the RoadType of.
 223          * @pre IsValidEngine(engine_id).
 224          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_ROAD.
 225          * @return The RoadType the engine has.
 226          */
 227         static ScriptRoad::RoadType GetRoadType(EngineID engine_id);
 228
 229         /**
 230          * Get the RailType of the engine.
 231          * @param engine_id The engine to get the RailType of.
 232          * @pre IsValidEngine(engine_id).
 233          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_RAIL.
 234          * @return The RailType the engine has.
 235          */
 236         static ScriptRail::RailType GetRailType(EngineID engine_id);
 237
 238         /**
 239          * Check if the engine is articulated.
 240          * @param engine_id The engine to check.
 241          * @pre IsValidEngine(engine_id).
 242          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_ROAD || GetVehicleType(engine_id) == ScriptVehicle::VT_RAIL.
 243          * @return True if the engine is articulated.
 244          */
 245         static bool IsArticulated(EngineID engine_id);
 246
 247         /**
 248          * Get the PlaneType of the engine.
 249          * @param engine_id The engine to get the PlaneType of.
 250          * @pre IsValidEngine(engine_id).
 251          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_AIR.
 252          * @return The PlaneType the engine has.
 253          */
 254         static ScriptAirport::PlaneType GetPlaneType(EngineID engine_id);
 255
 256         /**
 257          * Get the maximum allowed distance between two orders for an engine.
 258          * The distance returned is a vehicle-type specific distance independent from other
 259          * map distances, you may use the result of this function to compare it
 260          * with the result of ScriptOrder::GetOrderDistance.
 261          * @param engine_id The engine to get the max distance for.
 262          * @pre IsValidEngine(engine_id).
 263          * @return The maximum distance between two orders for the engine
 264          *         or 0 if the distance is unlimited.
 265          * @note   The unit of the order distances is unspecified and should
 266          *         not be compared with map distances
 267          * @see ScriptOrder::GetOrderDistance
 268          */
 269         static uint GetMaximumOrderDistance(EngineID engine_id);
 270 };
 271
 272 #endif /* SCRIPT_ENGINE_HPP */