src/script/api/script_industry.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_industry.hpp Everything to query and build industries. */
   9
  10 #ifndef SCRIPT_INDUSTRY_HPP
  11 #define SCRIPT_INDUSTRY_HPP
  12
  13 #include "script_company.hpp"
  14 #include "script_date.hpp"
  15 #include "script_object.hpp"
  16 #include "../../industry.h"
  17
  18 /**
  19  * Class that handles all industry related functions.
  20  * @api ai game
  21  */
  22 class ScriptIndustry : public ScriptObject {
  23 public:
  24         /** Ways for an industry to accept a cargo. */
  25         enum CargoAcceptState {
  26                 CAS_NOT_ACCEPTED, ///< The CargoID is not accepted by this industry.
  27                 CAS_ACCEPTED,     ///< The industry currently accepts this CargoID.
  28                 CAS_TEMP_REFUSED, ///< The industry temporarily refuses to accept this CargoID but may do so again in the future.
  29         };
  30
  31         /**
  32          * Control flags for industry
  33          * @api -ai
  34          */
  35         enum IndustryControlFlags {
  36                 /**
  37                  * When industry production change is evaluated, rolls to decrease are ignored.
  38                  * This also prevents industry closure due to production dropping to the lowest level.
  39                  */
  40                 INDCTL_NO_PRODUCTION_DECREASE = ::INDCTL_NO_PRODUCTION_DECREASE,
  41                 /**
  42                  * When industry production change is evaluated, rolls to increase are ignored.
  43                  */
  44                 INDCTL_NO_PRODUCTION_INCREASE = ::INDCTL_NO_PRODUCTION_INCREASE,
  45                 /**
  46                  * Industry can not close regardless of production level or time since last delivery.
  47                  * This does not prevent a closure already announced.
  48                  */
  49                 INDCTL_NO_CLOSURE             = ::INDCTL_NO_CLOSURE,
  50                 /**
  51                  * Indicates that the production level of the industry is controlled by a game script.
  52                  */
  53                 INDCTL_EXTERNAL_PROD_LEVEL    = ::INDCTL_EXTERNAL_PROD_LEVEL,
  54         };
  55
  56         /**
  57          * Gets the number of industries.
  58          * @return The number of industries.
  59          * @note The maximum valid IndustryID can be higher than the value returned.
  60          */
  61         static SQInteger GetIndustryCount();
  62
  63         /**
  64          * Checks whether the given industry index is valid.
  65          * @param industry_id The index to check.
  66          * @return True if and only if the industry is valid.
  67          */
  68         static bool IsValidIndustry(IndustryID industry_id);
  69
  70         /**
  71          * Get the IndustryID of a tile, if there is an industry.
  72          * @param tile The tile to find the IndustryID of.
  73          * @return IndustryID of the industry.
  74          * @post Use IsValidIndustry() to see if the industry is valid.
  75          * @note GetIndustryID will return an invalid IndustryID for the
  76          *   station tile of industries with a dock/heliport.
  77          */
  78         static IndustryID GetIndustryID(TileIndex tile);
  79
  80         /**
  81          * Get the name of the industry.
  82          * @param industry_id The industry to get the name of.
  83          * @pre IsValidIndustry(industry_id).
  84          * @return The name of the industry.
  85          */
  86         static std::optional<std::string> GetName(IndustryID industry_id);
  87
  88         /**
  89          * Get the construction calendar-date of an industry.
  90          * @param industry_id The index of the industry.
  91          * @pre IsValidIndustry(industry_id).
  92          * @return Calendar-date the industry was constructed.
  93          * @see \ref ScriptCalendarTime
  94          * @api -ai
  95          */
  96         static ScriptDate::Date GetConstructionDate(IndustryID industry_id);
  97
  98         /**
  99          * Set the custom text of an industry, shown in the GUI.
 100          * @param industry_id The industry to set the custom text of.
 101          * @param text The text to set it to (can be either a raw string, or a ScriptText object). If null, or an empty string, is passed, the text will be removed.
 102          * @pre ScriptCompanyMode::IsDeity().
 103          * @pre IsValidIndustry(industry_id).
 104          * @return True if the action succeeded.
 105          * @api -ai
 106          */
 107         static bool SetText(IndustryID industry_id, Text *text);
 108
 109         /**
 110          * See whether an industry currently accepts a certain cargo.
 111          * @param industry_id The index of the industry.
 112          * @param cargo_id The index of the cargo.
 113          * @pre IsValidIndustry(industry_id).
 114          * @pre ScriptCargo::IsValidCargo(cargo_id).
 115          * @return Whether the industry accepts, temporarily refuses or never accepts this cargo.
 116          */
 117         static CargoAcceptState IsCargoAccepted(IndustryID industry_id, CargoID cargo_id);
 118
 119         /**
 120          * Get the amount of cargo stockpiled for processing.
 121          * @param industry_id The index of the industry.
 122          * @param cargo_id The index of the cargo.
 123          * @pre IsValidIndustry(industry_id).
 124          * @pre ScriptCargo::IsValidCargo(cargo_id).
 125          * @return The amount of cargo that is waiting for processing.
 126          */
 127         static SQInteger GetStockpiledCargo(IndustryID industry_id, CargoID cargo_id);
 128
 129         /**
 130          * Get the total last economy-month's production of the given cargo at an industry.
 131          * @param industry_id The index of the industry.
 132          * @param cargo_id The index of the cargo.
 133          * @pre IsValidIndustry(industry_id).
 134          * @pre ScriptCargo::IsValidCargo(cargo_id).
 135          * @return The last economy-month's production of the given cargo for this industry.
 136          * @see \ref ScriptEconomyTime
 137          */
 138         static SQInteger GetLastMonthProduction(IndustryID industry_id, CargoID cargo_id);
 139
 140         /**
 141          * Get the total amount of cargo transported from an industry last economy-month.
 142          * @param industry_id The index of the industry.
 143          * @param cargo_id The index of the cargo.
 144          * @pre IsValidIndustry(industry_id).
 145          * @pre ScriptCargo::IsValidCargo(cargo_id).
 146          * @return The amount of given cargo transported from this industry last economy-month.
 147          * @see \ref ScriptEconomyTime
 148          */
 149         static SQInteger GetLastMonthTransported(IndustryID industry_id, CargoID cargo_id);
 150
 151         /**
 152          * Get the percentage of cargo transported from an industry last economy-month.
 153          * @param industry_id The index of the industry.
 154          * @param cargo_id The index of the cargo.
 155          * @pre IsValidIndustry(industry_id).
 156          * @pre ScriptCargo::IsValidCargo(cargo_id).
 157          * @return The percentage of given cargo transported from this industry last economy-month.
 158          * @see \ref ScriptEconomyTime
 159          */
 160         static SQInteger GetLastMonthTransportedPercentage(IndustryID industry_id, CargoID cargo_id);
 161
 162         /**
 163          * Gets the location of the industry.
 164          * @param industry_id The index of the industry.
 165          * @pre IsValidIndustry(industry_id).
 166          * @return The location of the industry.
 167          */
 168         static TileIndex GetLocation(IndustryID industry_id);
 169
 170         /**
 171          * Get the number of stations around an industry. All stations that can
 172          * service the industry are counted, your own stations but also your
 173          * opponents stations.
 174          * @param industry_id The index of the industry.
 175          * @pre IsValidIndustry(industry_id).
 176          * @return The number of stations around an industry.
 177          */
 178         static SQInteger GetAmountOfStationsAround(IndustryID industry_id);
 179
 180         /**
 181          * Get the manhattan distance from the tile to the ScriptIndustry::GetLocation()
 182          *  of the industry.
 183          * @param industry_id The industry to get the distance to.
 184          * @param tile The tile to get the distance to.
 185          * @pre IsValidIndustry(industry_id).
 186          * @pre ScriptMap::IsValidTile(tile).
 187          * @return The distance between industry and tile.
 188          */
 189         static SQInteger GetDistanceManhattanToTile(IndustryID industry_id, TileIndex tile);
 190
 191         /**
 192          * Get the square distance from the tile to the ScriptIndustry::GetLocation()
 193          *  of the industry.
 194          * @param industry_id The industry to get the distance to.
 195          * @param tile The tile to get the distance to.
 196          * @pre IsValidIndustry(industry_id).
 197          * @pre ScriptMap::IsValidTile(tile).
 198          * @return The distance between industry and tile.
 199          */
 200         static SQInteger GetDistanceSquareToTile(IndustryID industry_id, TileIndex tile);
 201
 202         /**
 203          * Is this industry built on water.
 204          * @param industry_id The index of the industry.
 205          * @pre IsValidIndustry(industry_id).
 206          * @return True when the industry is built on water.
 207          */
 208         static bool IsBuiltOnWater(IndustryID industry_id);
 209
 210         /**
 211          * Does this industry have a heliport?
 212          * @param industry_id The index of the industry.
 213          * @pre IsValidIndustry(industry_id).
 214          * @return True when the industry has a heliport.
 215          */
 216         static bool HasHeliport(IndustryID industry_id);
 217
 218         /**
 219          * Gets the location of the industry's heliport.
 220          * @param industry_id The index of the industry.
 221          * @pre IsValidIndustry(industry_id).
 222          * @pre HasHeliport(industry_id).
 223          * @return The location of the industry's heliport.
 224          */
 225         static TileIndex GetHeliportLocation(IndustryID industry_id);
 226
 227         /**
 228          * Does this industry have a dock?
 229          * @param industry_id The index of the industry.
 230          * @pre IsValidIndustry(industry_id).
 231          * @return True when the industry has a dock.
 232          */
 233         static bool HasDock(IndustryID industry_id);
 234
 235         /**
 236          * Gets the location of the industry's dock.
 237          * @param industry_id The index of the industry.
 238          * @pre IsValidIndustry(industry_id).
 239          * @pre HasDock(industry_id).
 240          * @return The location of the industry's dock.
 241          */
 242         static TileIndex GetDockLocation(IndustryID industry_id);
 243
 244         /**
 245          * Get the IndustryType of the industry.
 246          * @param industry_id The index of the industry.
 247          * @pre IsValidIndustry(industry_id).
 248          * @return The IndustryType of the industry.
 249          */
 250         static IndustryType GetIndustryType(IndustryID industry_id);
 251
 252         /**
 253          * Get the last economy-year this industry had any production output.
 254          * @param industry_id The index of the industry.
 255          * @pre IsValidIndustry(industry_id).
 256          * @return Economy-year the industry last had production, 0 if error.
 257          * @see \ref ScriptEconomyTime
 258          * @api -ai
 259          */
 260         static SQInteger GetLastProductionYear(IndustryID industry_id);
 261
 262         /**
 263          * Get the last economy-date this industry accepted any cargo delivery.
 264          * @param industry_id The index of the industry.
 265          * @param cargo_type The cargo to query, or INVALID_CARGO to query latest of all accepted cargoes.
 266          * @pre IsValidIndustry(industry_id).
 267          * @pre IsValidCargo(cargo_type) || cargo_type == INVALID_CARGO.
 268          * @return Economy-date the industry last received cargo from a delivery, or ScriptDate::DATE_INVALID on error.
 269          * @see \ref ScriptEconomyTime
 270          * @api -ai
 271          */
 272         static ScriptDate::Date GetCargoLastAcceptedDate(IndustryID industry_id, CargoID cargo_type);
 273
 274         /**
 275          * Get the current control flags for an industry.
 276          * @param industry_id The index of the industry.
 277          * @pre IsValidIndustry(industry_id).
 278          * @return Bit flags of the IndustryControlFlags enumeration.
 279          * @api -ai
 280          */
 281         static SQInteger GetControlFlags(IndustryID industry_id);
 282
 283         /**
 284          * Change the control flags for an industry.
 285          * @param industry_id The index of the industry.
 286          * @param control_flags New flags as a combination of IndustryControlFlags values.
 287          * @pre IsValidIndustry(industry_id).
 288          * @pre ScriptCompanyMode::IsDeity().
 289          * @return True if the action succeeded.
 290          * @api -ai
 291          */
 292         static bool SetControlFlags(IndustryID industry_id, SQInteger control_flags);
 293
 294         /**
 295          * Find out which company currently has the exclusive rights to deliver cargo to the industry.
 296          * @param industry_id The index of the industry.
 297          * @pre IsValidIndustry(industry_id).
 298          * @return The company that has the exclusive rights. The value
 299          *         ScriptCompany::COMPANY_INVALID means that there are currently no
 300          *         exclusive rights given out to anyone.
 301          */
 302         static ScriptCompany::CompanyID GetExclusiveSupplier(IndustryID industry_id);
 303
 304         /**
 305          * Sets or resets the company that has exclusive right to deliver cargo to the industry.
 306          * @param industry_id The index of the industry.
 307          * @param company_id The company to set (ScriptCompany::COMPANY_INVALID to reset).
 308          * @pre IsValidIndustry(industry_id).
 309          * @pre ScriptCompanyMode::IsDeity().
 310          * @return True if the action succeeded.
 311          * @api -ai
 312          */
 313         static bool SetExclusiveSupplier(IndustryID industry_id, ScriptCompany::CompanyID company_id);
 314
 315         /**
 316          * Find out which company currently has the exclusive rights to take cargo from the industry.
 317          * @param industry_id The index of the industry.
 318          * @pre IsValidIndustry(industry_id).
 319          * @return The company that has the exclusive rights. The value
 320          *         ScriptCompany::COMPANY_SPECTATOR means that there are currently no
 321          *         exclusive rights given out to anyone.
 322          */
 323         static ScriptCompany::CompanyID GetExclusiveConsumer(IndustryID industry_id);
 324
 325         /**
 326          * Sets or resets the company that has exclusive right to take cargo from the industry.
 327          * @param industry_id The index of the industry.
 328          * @param company_id The company to set (ScriptCompany::COMPANY_INVALID to reset).
 329          * @pre IsValidIndustry(industry_id).
 330          * @pre ScriptCompanyMode::IsDeity().
 331          * @return True if the action succeeded.
 332          * @api -ai
 333          */
 334         static bool SetExclusiveConsumer(IndustryID industry_id, ScriptCompany::CompanyID company_id);
 335
 336         /**
 337          * Gets the current production level of an industry.
 338          * @param industry_id The index of the industry.
 339          * @return The current production level of the industry.
 340          * @api -ai
 341          */
 342         static SQInteger GetProductionLevel(IndustryID industry_id);
 343
 344         /**
 345          * Sets the current production level of an industry.
 346          * @note Setting the production level automatically sets the control flag INDCTL_EXTERNAL_PROD_LEVEL if it wasn't already set.
 347          *     Normal production behaviour can be restored by clearing the control flag.
 348          * @param industry_id The index of the industry.
 349          * @param prod_level The production level to set.
 350          * @param show_news If set to true and the production changed, generate a production change news message. If set to false, no news message is shown.
 351          * @param custom_news Custom news message text to override the default news text with. Pass null to use the default text. Only used if \c show_news is set to true.
 352          * @pre IsValidIndustry(industry_id).
 353          * @pre ScriptCompanyMode::IsDeity().
 354          * @pre prod_level >= 4 && prod_level <= 128.
 355          * @return True if the action succeeded.
 356          * @api -ai
 357          */
 358         static bool SetProductionLevel(IndustryID industry_id, SQInteger prod_level, bool show_news, Text *custom_news);
 359 };
 360
 361 #endif /* SCRIPT_INDUSTRY_HPP */