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 days.
 129          * @note Age is in days; divide by 366 to get per year.
 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 year.
 138          * @note Cost is per year; divide by 365 to get per day.
 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 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 date this engine was designed.
 174          */
 175         static ScriptDate::Date GetDesignDate(EngineID engine_id);
 176
 177         /**
 178          * Get the type of an engine.
 179          * @param engine_id The engine to get the type of.
 180          * @pre IsValidEngine(engine_id).
 181          * @return The type the engine has.
 182          */
 183         static ScriptVehicle::VehicleType GetVehicleType(EngineID engine_id);
 184
 185         /**
 186          * Check if an engine is a wagon.
 187          * @param engine_id The engine to check.
 188          * @pre IsValidEngine(engine_id).
 189          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_RAIL.
 190          * @return Whether or not the engine is a wagon.
 191          */
 192         static bool IsWagon(EngineID engine_id);
 193
 194         /**
 195          * Check if a train vehicle can run on a RailType.
 196          * @param engine_id The engine to check.
 197          * @param track_rail_type The type you want to check.
 198          * @pre IsValidEngine(engine_id).
 199          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_RAIL.
 200          * @pre ScriptRail::IsRailTypeAvailable(track_rail_type).
 201          * @return Whether an engine of type 'engine_id' can run on 'track_rail_type'.
 202          * @note Even if a train can run on a RailType that doesn't mean that it'll be
 203          *   able to power the train. Use HasPowerOnRail for that.
 204          */
 205         static bool CanRunOnRail(EngineID engine_id, ScriptRail::RailType track_rail_type);
 206
 207         /**
 208          * Check if a train engine has power on a RailType.
 209          * @param engine_id The engine to check.
 210          * @param track_rail_type Another RailType.
 211          * @pre IsValidEngine(engine_id).
 212          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_RAIL.
 213          * @pre ScriptRail::IsRailTypeAvailable(track_rail_type).
 214          * @return Whether an engine of type 'engine_id' has power on 'track_rail_type'.
 215          */
 216         static bool HasPowerOnRail(EngineID engine_id, ScriptRail::RailType track_rail_type);
 217
 218         /**
 219          * Check if a road vehicle can run on a RoadType.
 220          * @param engine_id The engine to check.
 221          * @param road_type Another RoadType.
 222          * @pre IsValidEngine(engine_id).
 223          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_ROAD.
 224          * @pre ScriptRoad::IsRoadTypeAvailable(road_type).
 225          * @return Whether an engine of type 'engine_id' can run on 'road_type'.
 226          */
 227         static bool CanRunOnRoad(EngineID engine_id, ScriptRoad::RoadType road_type);
 228
 229         /**
 230          * Check if a road vehicle has power on a RoadType.
 231          * @param engine_id The engine to check.
 232          * @param road_type Another RoadType.
 233          * @pre IsValidEngine(engine_id).
 234          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_ROAD.
 235          * @pre ScriptRoad::IsRoadTypeAvailable(road_type).
 236          * @return Whether an engine of type 'engine_id' has power on 'road_type'.
 237          */
 238         static bool HasPowerOnRoad(EngineID engine_id, ScriptRoad::RoadType road_type);
 239
 240         /**
 241          * Get the RoadType of the engine.
 242          * @param engine_id The engine to get the RoadType of.
 243          * @pre IsValidEngine(engine_id).
 244          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_ROAD.
 245          * @return The RoadType the engine has.
 246          */
 247         static ScriptRoad::RoadType GetRoadType(EngineID engine_id);
 248
 249         /**
 250          * Get the RailType of the engine.
 251          * @param engine_id The engine to get the RailType of.
 252          * @pre IsValidEngine(engine_id).
 253          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_RAIL.
 254          * @return The RailType the engine has.
 255          */
 256         static ScriptRail::RailType GetRailType(EngineID engine_id);
 257
 258         /**
 259          * Check if the engine is articulated.
 260          * @param engine_id The engine to check.
 261          * @pre IsValidEngine(engine_id).
 262          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_ROAD || GetVehicleType(engine_id) == ScriptVehicle::VT_RAIL.
 263          * @return True if the engine is articulated.
 264          */
 265         static bool IsArticulated(EngineID engine_id);
 266
 267         /**
 268          * Get the PlaneType of the engine.
 269          * @param engine_id The engine to get the PlaneType of.
 270          * @pre IsValidEngine(engine_id).
 271          * @pre GetVehicleType(engine_id) == ScriptVehicle::VT_AIR.
 272          * @return The PlaneType the engine has.
 273          */
 274         static ScriptAirport::PlaneType GetPlaneType(EngineID engine_id);
 275
 276         /**
 277          * Get the maximum allowed distance between two orders for an engine.
 278          * The distance returned is a vehicle-type specific distance independent from other
 279          * map distances, you may use the result of this function to compare it
 280          * with the result of ScriptOrder::GetOrderDistance.
 281          * @param engine_id The engine to get the max distance for.
 282          * @pre IsValidEngine(engine_id).
 283          * @return The maximum distance between two orders for the engine
 284          *         or 0 if the distance is unlimited.
 285          * @note   The unit of the order distances is unspecified and should
 286          *         not be compared with map distances
 287          * @see ScriptOrder::GetOrderDistance
 288          */
 289         static SQInteger GetMaximumOrderDistance(EngineID engine_id);
 290
 291         /**
 292          * Allows a company to use an engine before its intro date or after retirement.
 293          * @param engine_id The engine to enable.
 294          * @param company_id The company to allow using the engine.
 295          * @pre IsValidEngine(engine_id).
 296          * @pre ScriptCompany.ResolveCompanyID(company_id) != ScriptCompany::COMPANY_INVALID.
 297          * @return True if the action succeeded.
 298          * @api -ai
 299          */
 300         static bool EnableForCompany(EngineID engine_id, ScriptCompany::CompanyID company_id);
 301
 302         /**
 303          * Forbids a company to use an engine before its natural retirement.
 304          * @param engine_id The engine to disable.
 305          * @param company_id The company to forbid using the engine.
 306          * @pre IsValidEngine(engine_id).
 307          * @pre ScriptCompany.ResolveCompanyID(company_id) != ScriptCompany::COMPANY_INVALID.
 308          * @return True if the action succeeded.
 309          * @api -ai
 310          */
 311         static bool DisableForCompany(EngineID engine_id, ScriptCompany::CompanyID company_id);
 312
 313 };
 314
 315 #endif /* SCRIPT_ENGINE_HPP */