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_cargomonitor.hpp Everything to monitor cargo pickup and deliveries by companies. */ 9 10 #ifndef SCRIPT_CARGO_MONITOR_HPP 11 #define SCRIPT_CARGO_MONITOR_HPP 12 13 #include "script_list.hpp" 14 #include "script_object.hpp" 15 #include "script_company.hpp" 16 #include "../../cargomonitor.h" 17 18 /** 19 * Class that handles all cargo movement monitoring related functions. 20 * 21 * To get an understanding of what users are transporting, this class provides cargo pick-up and delivery monitoring functions. 22 * It works as follows: 23 * - Select a company, a cargo-type, and an industry that gets the cargo triplet. 24 * - Perform a call to #GetIndustryDeliveryAmount, setting 'keep_monitoring' to \c true. 25 * The return value is not important, but from this moment the program accumulates all deliveries by 26 * the given company to the given industry of the given cargo type. 27 * - Some time later, perform another call to #GetIndustryDeliveryAmount. It returns the accumulated 28 * amount of cargo that the company has delivered. 29 * The call causes the collected amount to be reset. On the next call you will thus always get the 30 * delivered amount since the previous call. 31 * - When monitoring the deliveries is not interesting any more, set 'keep_monitoring' to \c false. 32 * The collecting process that happens between calls is stopped. 33 * 34 * In the same way you can monitor town deliveries, and you can monitor pick-up from towns and industries. 35 * The latter get added at the moment the cargo is delivered. This prevents users from getting credit for 36 * picking up cargo without delivering it. 37 * 38 * The active monitors are saved and loaded. Upon bankruptcy or company takeover, the cargo monitors are 39 * automatically stopped for that company. You can reset to the empty state with #StopAllMonitoring. 40 * 41 * @api game 42 */ 43 class ScriptCargoMonitor : public ScriptObject { 44 public: 45 /** 46 * Get the amount of cargo delivered to a town by a company since the last query, and update the monitoring state. 47 * @param company %Company to query. 48 * @param cargo Cargo type to query. 49 * @param town_id %Town to query. 50 * @param keep_monitoring If \c true, the given combination continues to be monitored for the next call. If \c false, monitoring ends. 51 * @return Amount of delivered cargo of the given cargo type to the given town by the given company since the last call, or 52 * \c -1 if a parameter is out-of-bound. 53 */ 54 static int32 GetTownDeliveryAmount(ScriptCompany::CompanyID company, CargoID cargo, TownID town_id, bool keep_monitoring); 55 56 /** 57 * Get the amount of cargo delivered to an industry by a company since the last query, and update the monitoring state. 58 * @param company %Company to query. 59 * @param cargo Cargo type to query. 60 * @param industry_id %Industry to query. 61 * @param keep_monitoring If \c true, the given combination continues to be monitored for the next call. If \c false, monitoring ends. 62 * @return Amount of delivered cargo of the given cargo type to the given industry by the given company since the last call, or 63 * \c -1 if a parameter is out-of-bound. 64 */ 65 static int32 GetIndustryDeliveryAmount(ScriptCompany::CompanyID company, CargoID cargo, IndustryID industry_id, bool keep_monitoring); 66 67 /** 68 * Get the amount of cargo picked up (and delivered) from a town by a company since the last query, and update the monitoring state. 69 * @param company %Company to query. 70 * @param cargo Cargo type to query. 71 * @param town_id %Town to query. 72 * @param keep_monitoring If \c true, the given combination continues to be monitored for the next call. If \c false, monitoring ends. 73 * @return Amount of picked up cargo of the given cargo type to the given town by the given company since the last call, or 74 * \c -1 if a parameter is out-of-bound. 75 * @note Amounts of picked-up cargo are added during final delivery of it, to prevent users from getting credit for picking up without delivering it. 76 */ 77 static int32 GetTownPickupAmount(ScriptCompany::CompanyID company, CargoID cargo, TownID town_id, bool keep_monitoring); 78 79 /** 80 * Get the amount of cargo picked up (and delivered) from an industry by a company since the last query, and update the monitoring state. 81 * @param company %Company to query. 82 * @param cargo Cargo type to query. 83 * @param industry_id %Industry to query. 84 * @param keep_monitoring If \c true, the given combination continues to be monitored for the next call. If \c false, monitoring ends. 85 * @return Amount of picked up cargo of the given cargo type to the given industry by the given company since the last call, or 86 * \c -1 if a parameter is out-of-bound. 87 * @note Amounts of picked-up cargo are added during final delivery of it, to prevent users from getting credit for picking up without delivering it. 88 */ 89 static int32 GetIndustryPickupAmount(ScriptCompany::CompanyID company, CargoID cargo, IndustryID industry_id, bool keep_monitoring); 90 91 /** Stop monitoring everything. */ 92 static void StopAllMonitoring(); 93 }; 94 95 #endif /* SCRIPT_CARGO_MONITOR_HPP */ 96