src/script/api/script_subsidy.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_subsidy.hpp Everything to query subsidies. */
   9
  10 #ifndef SCRIPT_SUBSIDY_HPP
  11 #define SCRIPT_SUBSIDY_HPP
  12
  13 #include "script_company.hpp"
  14 #include "script_date.hpp"
  15
  16 /**
  17  * Class that handles all subsidy related functions.
  18  * @api ai game
  19  */
  20 class ScriptSubsidy : public ScriptObject {
  21 public:
  22         /**
  23          * Enumeration for source and destination of a subsidy.
  24          * @note The list of values may grow in future.
  25          */
  26         enum SubsidyParticipantType {
  27                 /* Values are important, as they represent the internal state of the game.
  28                  *  It is originally named SourceType. SourceType::Headquarters is intentionally
  29                  *  left out, as it cannot be used for Subsidies. */
  30                 SPT_INDUSTRY =    0, ///< Subsidy participant is an industry
  31                 SPT_TOWN     =    1, ///< Subsidy participant is a town
  32                 SPT_INVALID  = 0xFF, ///< Invalid/unknown participant type
  33         };
  34
  35         /**
  36          * Check whether this is a valid SubsidyID.
  37          * @param subsidy_id The SubsidyID to check.
  38          * @return True if and only if this subsidy is still valid.
  39          */
  40         static bool IsValidSubsidy(SubsidyID subsidy_id);
  41
  42         /**
  43          * Checks whether this subsidy is already awarded to some company.
  44          * @param subsidy_id The SubsidyID to check.
  45          * @pre IsValidSubsidy(subsidy).
  46          * @return True if and only if this subsidy is already awarded.
  47          */
  48         static bool IsAwarded(SubsidyID subsidy_id);
  49
  50         /**
  51          * Create a new subsidy.
  52          * @param cargo_type The type of cargo to cary for the subsidy.
  53          * @param from_type The type of the subsidy on the 'from' side.
  54          * @param from_id The ID of the 'from' side.
  55          * @param to_type The type of the subsidy on the 'to' side.
  56          * @param to_id The ID of the 'to' side.
  57          * @return True if the action succeeded.
  58          * @pre ScriptCompanyMode::IsDeity().
  59          * @pre ScriptCargo::IsValidCargo(cargo_type)
  60          * @pre from_type == SPT_INDUSTRY || from_type == SPT_TOWN.
  61          * @pre to_type   == SPT_INDUSTRY || to_type   == SPT_TOWN.
  62          * @pre (from_type == SPT_INDUSTRY && ScriptIndustry::IsValidIndustry(from_id)) || (from_type == SPT_TOWN && ScriptTown::IsValidTown(from_id))
  63          * @pre (to_type   == SPT_INDUSTRY && ScriptIndustry::IsValidIndustry(to_id))   || (to_type   == SPT_TOWN && ScriptTown::IsValidTown(to_id))
  64          * @api -ai
  65          */
  66         static bool Create(CargoID cargo_type, SubsidyParticipantType from_type, SQInteger from_id, SubsidyParticipantType to_type, SQInteger to_id);
  67
  68         /**
  69          * Get the company index of the company this subsidy is awarded to.
  70          * @param subsidy_id The SubsidyID to check.
  71          * @pre IsAwarded(subsidy_id).
  72          * @return The companyindex of the company this subsidy is awarded to.
  73          */
  74         static ScriptCompany::CompanyID GetAwardedTo(SubsidyID subsidy_id);
  75
  76         /**
  77          * Get the economy-date this subsidy expires. In case the subsidy is already
  78          *  awarded, return the economy-date the subsidy expires, else, return the economy-date the
  79          *  offer expires.
  80          * @param subsidy_id The SubsidyID to check.
  81          * @pre IsValidSubsidy(subsidy_id).
  82          * @return The last valid economy-date of this subsidy.
  83          * @note The return value of this function will change if the subsidy is
  84          *  awarded.
  85          * @see \ref ScriptEconomyTime
  86          */
  87         static ScriptDate::Date GetExpireDate(SubsidyID subsidy_id);
  88
  89         /**
  90          * Get the cargo type that has to be transported in order to be awarded this
  91          *  subsidy.
  92          * @param subsidy_id The SubsidyID to check.
  93          * @pre IsValidSubsidy(subsidy_id).
  94          * @return The cargo type to transport.
  95          */
  96         static CargoID GetCargoType(SubsidyID subsidy_id);
  97
  98         /**
  99          * Returns the type of source of subsidy.
 100          * @param subsidy_id The SubsidyID to check.
 101          * @pre IsValidSubsidy(subsidy_id).
 102          * @return Type of source of subsidy.
 103          */
 104         static SubsidyParticipantType GetSourceType(SubsidyID subsidy_id);
 105
 106         /**
 107          * Return the source IndustryID/TownID the subsidy is for.
 108          * \li GetSourceType(subsidy_id) == SPT_INDUSTRY -> return the IndustryID.
 109          * \li GetSourceType(subsidy_id) == SPT_TOWN -> return the TownID.
 110          * @param subsidy_id The SubsidyID to check.
 111          * @pre IsValidSubsidy(subsidy_id).
 112          * @return One of TownID/IndustryID.
 113          */
 114         static SQInteger GetSourceIndex(SubsidyID subsidy_id);
 115
 116         /**
 117          * Returns the type of destination of subsidy.
 118          * @param subsidy_id The SubsidyID to check.
 119          * @pre IsValidSubsidy(subsidy_id).
 120          * @return Type of destination of subsidy.
 121          */
 122         static SubsidyParticipantType GetDestinationType(SubsidyID subsidy_id);
 123
 124         /**
 125          * Return the destination IndustryID/TownID the subsidy is for.
 126          * \li GetDestinationType(subsidy_id) == SPT_INDUSTRY -> return the IndustryID.
 127          * \li GetDestinationType(subsidy_id) == SPT_TOWN -> return the TownID.
 128          * @param subsidy_id the SubsidyID to check.
 129          * @pre IsValidSubsidy(subsidy_id).
 130          * @return One of TownID/IndustryID.
 131          */
 132         static SQInteger GetDestinationIndex(SubsidyID subsidy_id);
 133 };
 134
 135 #endif /* SCRIPT_SUBSIDY_HPP */