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 = ::TE_NONE, ///< This cargo has no effect on a town 46 TE_PASSENGERS = ::TE_PASSENGERS, ///< This cargo supplies passengers to a town 47 TE_MAIL = ::TE_MAIL, ///< This cargo supplies mail to a town 48 TE_GOODS = ::TE_GOODS, ///< This cargo supplies goods to a town 49 TE_WATER = ::TE_WATER, ///< This cargo supplies water to a town 50 TE_FOOD = ::TE_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 = ::CT_AUTO_REFIT, ///< Automatically choose cargo type when doing auto-refitting. 59 CT_NO_REFIT = ::CT_NO_REFIT, ///< Do not refit cargo of a vehicle. 60 CT_INVALID = ::CT_INVALID, ///< 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 char *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 char *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 * @param days_in_transit Amount of (game) days the cargo is in transit. The max value of this variable is 637. Any value higher returns the same as 637 would. 146 * @return The amount of money that would be earned by this trip. 147 */ 148 static Money GetCargoIncome(CargoID cargo_type, uint32 distance, uint32 days_in_transit); 149 150 /** 151 * Get the cargo distribution type for a cargo. 152 * @param cargo_type The cargo to check on. 153 * @return The cargo distribution type for the given cargo. 154 */ 155 static DistributionType GetDistributionType(CargoID cargo_type); 156 }; 157 158 #endif /* SCRIPT_CARGO_HPP */ 159