src/script/api/script_company.hpp

   1 /* $Id$ */
   2
   3 /*
   4  * This file is part of OpenTTD.
   5  * 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.
   6  * 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.
   7  * 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/>.
   8  */
   9
  10 /** @file script_company.hpp Everything to query a company's financials and statistics or build company related buildings. */
  11
  12 #ifndef SCRIPT_COMPANY_HPP
  13 #define SCRIPT_COMPANY_HPP
  14
  15 #include "script_text.hpp"
  16 #include "../../economy_type.h"
  17
  18 /**
  19  * Class that handles all company related functions.
  20  * @api ai game
  21  */
  22 class ScriptCompany : public ScriptObject {
  23 public:
  24         /** The range of possible quarters to get company information of. */
  25         enum Quarter {
  26                 CURRENT_QUARTER  = 0,                      ///< The current quarter.
  27                 EARLIEST_QUARTER = ::MAX_HISTORY_QUARTERS, ///< The earliest quarter company information is available for.
  28         };
  29
  30         /** Different constants related to CompanyID. */
  31         enum CompanyID {
  32                 /* Note: these values represent part of the in-game Owner enum */
  33                 COMPANY_FIRST   = ::COMPANY_FIRST,   ///< The first available company.
  34                 COMPANY_LAST    = ::MAX_COMPANIES,   ///< The last available company.
  35
  36                 /* Custom added value, only valid for this API */
  37                 COMPANY_INVALID = -1,                ///< An invalid company.
  38                 COMPANY_SELF    = 254,               ///< Constant that gets resolved to the correct company index for your company.
  39         };
  40
  41         /** Possible genders for company presidents. */
  42         enum Gender {
  43                 GENDER_MALE,         ///< A male person.
  44                 GENDER_FEMALE,       ///< A female person.
  45                 GENDER_INVALID = -1, ///< An invalid gender.
  46         };
  47
  48         /**
  49          * Types of expenses.
  50          * @api -ai
  51          */
  52         enum ExpensesType {
  53                 EXPENSES_CONSTRUCTION = ::EXPENSES_CONSTRUCTION, ///< Construction costs.
  54                 EXPENSES_NEW_VEHICLES = ::EXPENSES_NEW_VEHICLES, ///< New vehicles.
  55                 EXPENSES_TRAIN_RUN    = ::EXPENSES_TRAIN_RUN,    ///< Running costs trains.
  56                 EXPENSES_ROADVEH_RUN  = ::EXPENSES_ROADVEH_RUN,  ///< Running costs road vehicles.
  57                 EXPENSES_AIRCRAFT_RUN = ::EXPENSES_AIRCRAFT_RUN, ///< Running costs aircrafts.
  58                 EXPENSES_SHIP_RUN     = ::EXPENSES_SHIP_RUN,     ///< Running costs ships.
  59                 EXPENSES_PROPERTY     = ::EXPENSES_PROPERTY,     ///< Property costs.
  60                 EXPENSES_TRAIN_INC    = ::EXPENSES_TRAIN_INC,    ///< Income from trains.
  61                 EXPENSES_ROADVEH_INC  = ::EXPENSES_ROADVEH_INC,  ///< Income from road vehicles.
  62                 EXPENSES_AIRCRAFT_INC = ::EXPENSES_AIRCRAFT_INC, ///< Income from aircrafts.
  63                 EXPENSES_SHIP_INC     = ::EXPENSES_SHIP_INC,     ///< Income from ships.
  64                 EXPENSES_LOAN_INT     = ::EXPENSES_LOAN_INT,     ///< Interest payments over the loan.
  65                 EXPENSES_OTHER        = ::EXPENSES_OTHER,        ///< Other expenses.
  66                 EXPENSES_INVALID      = ::INVALID_EXPENSES,      ///< Invalid expense type.
  67         };
  68
  69         /**
  70          * Resolved the given company index to the correct index for the company. If
  71          *  the company index was COMPANY_SELF it will be resolved to the index of
  72          *  your company. If the company with the given index does not exist it will
  73          *  return COMPANY_INVALID.
  74          * @param company The company index to resolve.
  75          * @return The resolved company index.
  76          */
  77         static CompanyID ResolveCompanyID(CompanyID company);
  78
  79         /**
  80          * Check if a CompanyID is your CompanyID, to ease up checks.
  81          * @param company The company index to check.
  82          * @return True if and only if this company is your CompanyID.
  83          * @api -game
  84          */
  85         static bool IsMine(CompanyID company);
  86
  87         /**
  88          * Set the name of your company.
  89          * @param name The new name of the company (can be either a raw string, or a ScriptText object).
  90          * @pre name != NULL && len(name) != 0.
  91          * @exception ScriptError::ERR_NAME_IS_NOT_UNIQUE
  92          * @return True if the name was changed.
  93          */
  94         static bool SetName(Text *name);
  95
  96         /**
  97          * Get the name of the given company.
  98          * @param company The company to get the name for.
  99          * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 100          * @return The name of the given company.
 101          */
 102         static char *GetName(CompanyID company);
 103
 104         /**
 105          * Set the name of your president.
 106          * @param name The new name of the president (can be either a raw string, or a ScriptText object).
 107          * @pre name != NULL && len(name) != 0.
 108          * @exception ScriptError::ERR_NAME_IS_NOT_UNIQUE
 109          * @return True if the name was changed.
 110          */
 111         static bool SetPresidentName(Text *name);
 112
 113         /**
 114          * Get the name of the president of the given company.
 115          * @param company The company to get the president's name for.
 116          * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 117          * @return The name of the president of the given company.
 118          */
 119         static char *GetPresidentName(CompanyID company);
 120
 121         /**
 122          * Set the gender of the president of your company.
 123          * @param gender The new gender for your president.
 124          * @pre GetPresidentGender(ScriptCompany.COMPANY_SELF) != gender.
 125          * @return True if the gender was changed.
 126          * @note When successful a random face will be created.
 127          * @api -game
 128          */
 129         static bool SetPresidentGender(Gender gender);
 130
 131         /**
 132          * Get the gender of the president of the given company.
 133          * @param company The company to get the presidents gender off.
 134          * @return The gender of the president.
 135          */
 136         static Gender GetPresidentGender(CompanyID company);
 137
 138         /**
 139          * Sets the amount to loan.
 140          * @param loan The amount to loan (multiplier of GetLoanInterval()).
 141          * @pre 'loan' must be non-negative.
 142          * @pre GetLoanInterval() must be a multiplier of 'loan'.
 143          * @pre 'loan' must be below GetMaxLoanAmount().
 144          * @pre 'loan' - GetLoanAmount() + GetBankBalance() must be non-negative.
 145          * @game @pre Valid ScriptCompanyMode active in scope.
 146          * @return True if the loan could be set to your requested amount.
 147          */
 148         static bool SetLoanAmount(Money loan);
 149
 150         /**
 151          * Sets the minimum amount to loan, i.e. the given amount of loan rounded up.
 152          * @param loan The amount to loan (any positive number).
 153          * @pre 'loan' must be non-negative.
 154          * @pre 'loan' must be below GetMaxLoanAmount().
 155          * @game @pre Valid ScriptCompanyMode active in scope.
 156          * @return True if we could allocate a minimum of 'loan' loan.
 157          */
 158         static bool SetMinimumLoanAmount(Money loan);
 159
 160         /**
 161          * Gets the amount your company have loaned.
 162          * @return The amount loaned money.
 163          * @post GetLoanInterval() is always a multiplier of the return value.
 164          */
 165         static Money GetLoanAmount();
 166
 167         /**
 168          * Gets the maximum amount your company can loan.
 169          * @return The maximum amount your company can loan.
 170          * @post GetLoanInterval() is always a multiplier of the return value.
 171          */
 172         static Money GetMaxLoanAmount();
 173
 174         /**
 175          * Gets the interval/loan step.
 176          * @return The loan step.
 177          * @post Return value is always positive.
 178          */
 179         static Money GetLoanInterval();
 180
 181         /**
 182          * Gets the bank balance. In other words, the amount of money the given company can spent.
 183          * @param company The company to get the bank balance of.
 184          * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 185          * @return The actual bank balance.
 186          */
 187         static Money GetBankBalance(CompanyID company);
 188
 189         /**
 190          * Changes the bank balance by a delta value. This method does not affect the loan but instead
 191          * allows a GS to give or take money from a company.
 192          * @param company The company to change the bank balance of.
 193          * @param delta Amount of money to give or take from the bank balance. A positive value adds money to the bank balance.
 194          * @param expenses_type The account in the finances window that will register the cost.
 195          * @return True, if the bank balance was changed.
 196          * @game @pre No ScriptCompanyMode active in scope.
 197          * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 198          * @pre delta >= -2**31
 199          * @pre delta <   2**31
 200          * @note You need to create your own news message to inform about costs/gifts that you create using this command.
 201          * @api -ai
 202          */
 203         static bool ChangeBankBalance(CompanyID company, Money delta, ExpensesType expenses_type);
 204
 205         /**
 206          * Get the income of the company in the given quarter.
 207          * Note that this function only considers recurring income from vehicles;
 208          * it does not include one-time income from selling stuff.
 209          * @param company The company to get the quarterly income of.
 210          * @param quarter The quarter to get the income of.
 211          * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 212          * @pre quarter <= EARLIEST_QUARTER.
 213          * @return The gross income of the company in the given quarter.
 214          */
 215         static Money GetQuarterlyIncome(CompanyID company, uint32 quarter);
 216
 217         /**
 218          * Get the expenses of the company in the given quarter.
 219          * Note that this function only considers recurring expenses from vehicle
 220          * running cost, maintenance and interests; it does not include one-time
 221          * expenses from construction and buying stuff.
 222          * @param company The company to get the quarterly expenses of.
 223          * @param quarter The quarter to get the expenses of.
 224          * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 225          * @pre quarter <= EARLIEST_QUARTER.
 226          * @return The expenses of the company in the given quarter.
 227          */
 228         static Money GetQuarterlyExpenses(CompanyID company, uint32 quarter);
 229
 230         /**
 231          * Get the amount of cargo delivered by the given company in the given quarter.
 232          * @param company The company to get the amount of delivered cargo of.
 233          * @param quarter The quarter to get the amount of delivered cargo of.
 234          * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 235          * @pre quarter <= EARLIEST_QUARTER.
 236          * @return The amount of cargo delivered by the given company in the given quarter.
 237          */
 238         static int32 GetQuarterlyCargoDelivered(CompanyID company, uint32 quarter);
 239
 240         /**
 241          * Get the performance rating of the given company in the given quarter.
 242          * @param company The company to get the performance rating of.
 243          * @param quarter The quarter to get the performance rating of.
 244          * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 245          * @pre quarter <= EARLIEST_QUARTER.
 246          * @pre quarter != CURRENT_QUARTER.
 247          * @note The performance rating is calculated after every quarter, so the value for CURRENT_QUARTER is undefined.
 248          * @return The performance rating of the given company in the given quarter.
 249          */
 250         static int32 GetQuarterlyPerformanceRating(CompanyID company, uint32 quarter);
 251
 252         /**
 253          * Get the value of the company in the given quarter.
 254          * @param company The company to get the value of.
 255          * @param quarter The quarter to get the value of.
 256          * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 257          * @pre quarter <= EARLIEST_QUARTER.
 258          * @return The value of the company in the given quarter.
 259          */
 260         static Money GetQuarterlyCompanyValue(CompanyID company, uint32 quarter);
 261
 262         /**
 263          * Build your company's HQ on the given tile.
 264          * @param tile The tile to build your HQ on, this tile is the most northern tile of your HQ.
 265          * @pre ScriptMap::IsValidTile(tile).
 266          * @game @pre Valid ScriptCompanyMode active in scope.
 267          * @exception ScriptError::ERR_AREA_NOT_CLEAR
 268          * @exception ScriptError::ERR_FLAT_LAND_REQUIRED
 269          * @return True if the HQ could be build.
 270          * @note An HQ can not be removed, only by water or rebuilding; If an HQ is
 271          *  build again, the old one is removed.
 272          */
 273         static bool BuildCompanyHQ(TileIndex tile);
 274
 275         /**
 276          * Return the location of a company's HQ.
 277          * @param company The company the get the HQ of.
 278          * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 279          * @return The tile of the company's HQ, this tile is the most northern tile
 280          *  of that HQ, or ScriptMap::TILE_INVALID if there is no HQ yet.
 281          */
 282         static TileIndex GetCompanyHQ(CompanyID company);
 283
 284         /**
 285          * Set whether autorenew is enabled for your company.
 286          * @param autorenew The new autorenew status.
 287          * @return True if autorenew status has been modified.
 288          * @api -game
 289          */
 290         static bool SetAutoRenewStatus(bool autorenew);
 291
 292         /**
 293          * Return whether autorenew is enabled for a company.
 294          * @param company The company to get the autorenew status of.
 295          * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 296          * @return True if autorenew is enabled.
 297          */
 298         static bool GetAutoRenewStatus(CompanyID company);
 299
 300         /**
 301          * Set the number of months before/after max age to autorenew an engine for your company.
 302          * @param months The new months between autorenew.
 303          * @return True if autorenew months has been modified.
 304          * @api -game
 305          */
 306         static bool SetAutoRenewMonths(int16 months);
 307
 308         /**
 309          * Return the number of months before/after max age to autorenew an engine for a company.
 310          * @param company The company to get the autorenew months of.
 311          * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 312          * @return The months before/after max age of engine.
 313          */
 314         static int16 GetAutoRenewMonths(CompanyID company);
 315
 316         /**
 317          * Set the minimum money needed to autorenew an engine for your company.
 318          * @param money The new minimum required money for autorenew to work.
 319          * @return True if autorenew money has been modified.
 320          * @pre money >= 0
 321          * @pre money <  2**32
 322          * @api -game
 323          */
 324         static bool SetAutoRenewMoney(Money money);
 325
 326         /**
 327          * Return the minimum money needed to autorenew an engine for a company.
 328          * @param company The company to get the autorenew money of.
 329          * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 330          * @return The minimum required money for autorenew to work.
 331          */
 332         static Money GetAutoRenewMoney(CompanyID company);
 333 };
 334
 335 DECLARE_POSTFIX_INCREMENT(ScriptCompany::CompanyID)
 336
 337 #endif /* SCRIPT_COMPANY_HPP */