src/script/api/script_engine.hpp

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