src/script/api/script_cargo.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_cargo.hpp Everything to query cargoes. */
   9
  10 #ifndef SCRIPT_CARGO_HPP
  11 #define SCRIPT_CARGO_HPP
  12
  13 #include "script_object.hpp"
  14 #include "../../cargotype.h"
  15 #include "../../linkgraph/linkgraph_type.h"
  16
  17 /**
  18  * Class that handles all cargo related functions.
  19  * @api ai game
  20  */
  21 class ScriptCargo : public ScriptObject {
  22 public:
  23         /**
  24          * The classes of cargo.
  25          */
  26         enum CargoClass {
  27                 /* Note: these values represent part of the in-game CargoClass enum */
  28                 CC_PASSENGERS   = ::CC_PASSENGERS,   ///< Passengers. Cargoes of this class appear at bus stops. Cargoes not of this class appear at truck stops.
  29                 CC_MAIL         = ::CC_MAIL,         ///< Mail
  30                 CC_EXPRESS      = ::CC_EXPRESS,      ///< Express cargo (Goods, Food, Candy, but also possible for passengers)
  31                 CC_ARMOURED     = ::CC_ARMOURED,     ///< Armoured cargo (Valuables, Gold, Diamonds)
  32                 CC_BULK         = ::CC_BULK,         ///< Bulk cargo (Coal, Grain etc., Ores, Fruit)
  33                 CC_PIECE_GOODS  = ::CC_PIECE_GOODS,  ///< Piece goods (Livestock, Wood, Steel, Paper)
  34                 CC_LIQUID       = ::CC_LIQUID,       ///< Liquids (Oil, Water, Rubber)
  35                 CC_REFRIGERATED = ::CC_REFRIGERATED, ///< Refrigerated cargo (Food, Fruit)
  36                 CC_HAZARDOUS    = ::CC_HAZARDOUS,    ///< Hazardous cargo (Nuclear Fuel, Explosives, etc.)
  37                 CC_COVERED      = ::CC_COVERED,      ///< Covered/Sheltered Freight (Transportation in Box Vans, Silo Wagons, etc.)
  38         };
  39
  40         /**
  41          * The effects a cargo can have on a town.
  42          */
  43         enum TownEffect {
  44                 /* Note: these values represent part of the in-game TownEffect enum */
  45                 TE_NONE       = ::TAE_NONE,       ///< This cargo has no effect on a town
  46                 TE_PASSENGERS = ::TAE_PASSENGERS, ///< This cargo supplies passengers to a town
  47                 TE_MAIL       = ::TAE_MAIL,       ///< This cargo supplies mail to a town
  48                 TE_GOODS      = ::TAE_GOODS,      ///< This cargo supplies goods to a town
  49                 TE_WATER      = ::TAE_WATER,      ///< This cargo supplies water to a town
  50                 TE_FOOD       = ::TAE_FOOD,       ///< This cargo supplies food to a town
  51         };
  52
  53         /**
  54          * Special cargo types.
  55          */
  56         enum SpecialCargoID {
  57                 /* Note: these values represent part of the in-game CargoTypes enum */
  58                 CT_AUTO_REFIT = ::CARGO_AUTO_REFIT, ///< Automatically choose cargo type when doing auto-refitting.
  59                 CT_NO_REFIT   = ::CARGO_NO_REFIT, ///< Do not refit cargo of a vehicle.
  60                 CT_INVALID    = ::INVALID_CARGO, ///< An invalid cargo type.
  61         };
  62
  63         /**
  64          * Type of cargo distribution.
  65          */
  66         enum DistributionType {
  67                 DT_MANUAL = ::DT_MANUAL,         ///< Manual distribution.
  68                 DT_ASYMMETRIC = ::DT_ASYMMETRIC, ///< Asymmetric distribution. Usually cargo will only travel in one direction.
  69                 DT_SYMMETRIC = ::DT_SYMMETRIC,   ///< Symmetric distribution. The same amount of cargo travels in each direction between each pair of nodes.
  70                 INVALID_DISTRIBUTION_TYPE = 0xFFFF, ///< Invalid distribution type.
  71         };
  72
  73         /**
  74          * Checks whether the given cargo type is valid.
  75          * @param cargo_type The cargo to check.
  76          * @return True if and only if the cargo type is valid.
  77          */
  78         static bool IsValidCargo(CargoID cargo_type);
  79
  80         /**
  81          * Checks whether the given town effect type is valid.
  82          * @param towneffect_type The town effect to check.
  83          * @return True if and only if the town effect type is valid.
  84          */
  85         static bool IsValidTownEffect(TownEffect towneffect_type);
  86
  87         /**
  88          * Get the name of the cargo type.
  89          * @param cargo_type The cargo type to get the name of.
  90          * @pre IsValidCargo(cargo_type).
  91          * @return The name of the cargo type.
  92          */
  93         static std::optional<std::string> GetName(CargoID cargo_type);
  94
  95         /**
  96          * Gets the string representation of the cargo label.
  97          * @param cargo_type The cargo to get the string representation of.
  98          * @pre ScriptCargo::IsValidCargo(cargo_type).
  99          * @return The cargo label.
 100          * @note
 101          *  - The label uniquely identifies a specific cargo. Use this if you want to
 102          *    detect special cargos from specific industry set (like production booster cargos, supplies, ...).
 103          *  - For more generic cargo support, rather check cargo properties though. For example:
 104          *     - Use ScriptCargo::HasCargoClass(..., CC_PASSENGER) to decide bus vs. truck requirements.
 105          *     - Use ScriptCargo::GetTownEffect(...) paired with ScriptTown::GetCargoGoal(...) to determine
 106          *       town growth requirements.
 107          *  - In other words: Only use the cargo label, if you know more about the behaviour
 108          *    of a specific cargo from a specific industry set, than the API methods can tell you.
 109          */
 110         static std::optional<std::string> GetCargoLabel(CargoID cargo_type);
 111
 112         /**
 113          * Checks whether the give cargo is a freight or not.
 114          * This defines whether the "freight train weight multiplier" will apply to
 115          * trains transporting this cargo.
 116          * @param cargo_type The cargo to check on.
 117          * @pre ScriptCargo::IsValidCargo(cargo_type).
 118          * @return True if and only if the cargo is freight.
 119          */
 120         static bool IsFreight(CargoID cargo_type);
 121
 122         /**
 123          * Check if this cargo is in the requested cargo class.
 124          * @param cargo_type The cargo to check on.
 125          * @pre ScriptCargo::IsValidCargo(cargo_type).
 126          * @param cargo_class The class to check for.
 127          * @return True if and only if the cargo is in the cargo class.
 128          */
 129         static bool HasCargoClass(CargoID cargo_type, CargoClass cargo_class);
 130
 131         /**
 132          * Get the effect this cargo has on a town.
 133          * @param cargo_type The cargo to check on.
 134          * @pre ScriptCargo::IsValidCargo(cargo_type).
 135          * @return The effect this cargo has on a town, or TE_NONE if it has no effect.
 136          */
 137         static TownEffect GetTownEffect(CargoID cargo_type);
 138
 139         /**
 140          * Get the income for transporting a piece of cargo over the
 141          *   given distance within the specified time.
 142          * @param cargo_type The cargo to transport.
 143          * @pre ScriptCargo::IsValidCargo(cargo_type).
 144          * @param distance The distance the cargo travels from begin to end.
 145          *                 The value will be clamped to 0 .. MAX(uint32_t).
 146          * @param days_in_transit Amount of (game) days the cargo is in transit.
 147          *                        The max value of this variable is 637. Any value higher returns the same as 637 would.
 148          * @return The amount of money that would be earned by this trip.
 149          */
 150         static Money GetCargoIncome(CargoID cargo_type, SQInteger distance, SQInteger days_in_transit);
 151
 152         /**
 153          * Get the cargo distribution type for a cargo.
 154          * @param cargo_type The cargo to check on.
 155          * @return The cargo distribution type for the given cargo.
 156          */
 157         static DistributionType GetDistributionType(CargoID cargo_type);
 158
 159         /**
 160          * Get the weight in tonnes for the given amount of
 161          *   cargo for the specified type.
 162          * @param cargo_type The cargo to check on.
 163          * @param amount The quantity of cargo.
 164          *               The value will be clamped to 0 .. MAX(uint32_t).
 165          * @pre ScriptCargo::IsValidCargo(cargo_type).
 166          * @return The weight in tonnes for that quantity of cargo.
 167          */
 168         static SQInteger GetWeight(CargoID cargo_type, SQInteger amount);
 169 };
 170
 171 #endif /* SCRIPT_CARGO_HPP */