src/script/api/script_group.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_group.hpp Everything to put vehicles into groups. */
   9
  10 #ifndef SCRIPT_GROUP_HPP
  11 #define SCRIPT_GROUP_HPP
  12
  13 #include "script_vehicle.hpp"
  14 #include "../../group_type.h"
  15
  16 /**
  17  * Class that handles all group related functions.
  18  * @api ai game
  19  */
  20 class ScriptGroup : public ScriptObject {
  21 public:
  22         /**
  23          * The group IDs of some special groups.
  24          */
  25         enum GroupID {
  26                 /* Note: these values represent part of the in-game static values */
  27                 GROUP_ALL     = ::ALL_GROUP,     ///< All vehicles are in this group.
  28                 GROUP_DEFAULT = ::DEFAULT_GROUP, ///< Vehicles not put in any other group are in this one.
  29                 GROUP_INVALID = ::INVALID_GROUP, ///< An invalid group id.
  30         };
  31
  32         /**
  33          * Checks whether the given group is valid.
  34          * @param group_id The group to check.
  35          * @pre group_id != GROUP_DEFAULT && group_id != GROUP_ALL.
  36          * @return True if and only if the group is valid.
  37          */
  38         static bool IsValidGroup(GroupID group_id);
  39
  40         /**
  41          * Create a new group.
  42          * @param vehicle_type The type of vehicle to create a group for.
  43          * @param parent_group_id The parent group id to create this group under, INVALID_GROUP for top-level.
  44          * @game @pre ScriptCompanyMode::IsValid().
  45          * @return The GroupID of the new group, or an invalid GroupID when
  46          *  it failed. Check the return value using IsValidGroup(). In test-mode
  47          *  0 is returned if it was successful; any other value indicates failure.
  48          */
  49         static GroupID CreateGroup(ScriptVehicle::VehicleType vehicle_type, GroupID parent_group_id);
  50
  51         /**
  52          * Delete the given group. When the deletion succeeds all vehicles in the
  53          *  given group will move to the GROUP_DEFAULT.
  54          * @param group_id The group to delete.
  55          * @pre IsValidGroup(group_id).
  56          * @game @pre ScriptCompanyMode::IsValid().
  57          * @return True if and only if the group was successfully deleted.
  58          */
  59         static bool DeleteGroup(GroupID group_id);
  60
  61         /**
  62          * Get the vehicle type of a group.
  63          * @param group_id The group to get the type from.
  64          * @pre IsValidGroup(group_id).
  65          * @return The vehicletype of the given group.
  66          */
  67         static ScriptVehicle::VehicleType GetVehicleType(GroupID group_id);
  68
  69         /**
  70          * Set the name of a group.
  71          * @param group_id The group to set the name for.
  72          * @param name The name for the group (can be either a raw string, or a ScriptText object).
  73          * @pre IsValidGroup(group_id).
  74          * @pre name != null && len(name) != 0
  75          * @game @pre ScriptCompanyMode::IsValid().
  76          * @exception ScriptError::ERR_NAME_IS_NOT_UNIQUE
  77          * @return True if and only if the name was changed.
  78          */
  79         static bool SetName(GroupID group_id, Text *name);
  80
  81         /**
  82          * Get the name of a group.
  83          * @param group_id The group to get the name of.
  84          * @pre IsValidGroup(group_id).
  85          * @return The name the group has.
  86          */
  87         static std::optional<std::string> GetName(GroupID group_id);
  88
  89         /**
  90          * Set parent group of a group.
  91          * @param group_id The group to set the parent for.
  92          * @param parent_group_id The parent group to set.
  93          * @pre IsValidGroup(group_id).
  94          * @pre IsValidGroup(parent_group_id).
  95          * @game @pre ScriptCompanyMode::IsValid().
  96          * @return True if and only if the parent group was changed.
  97          */
  98         static bool SetParent(GroupID group_id, GroupID parent_group_id);
  99
 100         /**
 101          * Get parent group of a group.
 102          * @param group_id The group to get the parent of.
 103          * @pre IsValidGroup(group_id).
 104          * @return The group id of the parent group.
 105          */
 106         static GroupID GetParent(GroupID group_id);
 107
 108         /**
 109          * Enable or disable autoreplace protected. If the protection is
 110          *  enabled, global autoreplace won't affect vehicles in this group.
 111          * @param group_id The group to change the protection for.
 112          * @param enable True if protection should be enabled.
 113          * @pre IsValidGroup(group_id).
 114          * @game @pre ScriptCompanyMode::IsValid().
 115          * @return True if and only if the protection was successfully changed.
 116          */
 117         static bool EnableAutoReplaceProtection(GroupID group_id, bool enable);
 118
 119         /**
 120          * Get the autoreplace protection status.
 121          * @param group_id The group to get the protection status for.
 122          * @pre IsValidGroup(group_id).
 123          * @return The autoreplace protection status for the given group.
 124          */
 125         static bool GetAutoReplaceProtection(GroupID group_id);
 126
 127         /**
 128          * Get the number of engines in a given group.
 129          * @param group_id The group to get the number of engines in.
 130          * @param engine_id The engine id to count.
 131          * @pre ScriptEngine::IsValidEngine(engine_id).
 132          * @pre (IsValidGroup(group_id) && ScriptEngine::GetVehicleType(engine_id) == GetVehicleType(group_id)) ||
 133              group_id == GROUP_ALL || group_id == GROUP_DEFAULT.
 134          * @game @pre ScriptCompanyMode::IsValid().
 135          * @return The number of engines with id engine_id in the group with id group_id.
 136          */
 137         static SQInteger GetNumEngines(GroupID group_id, EngineID engine_id);
 138
 139         /**
 140          * Get the total number of vehicles in a given group and its sub-groups.
 141          * @param group_id The group to get the number of vehicles in.
 142          * @param vehicle_type The type of vehicle of the group.
 143          * @pre IsValidGroup(group_id) || group_id == GROUP_ALL || group_id == GROUP_DEFAULT.
 144          * @pre IsValidGroup(group_id) || vehicle_type == ScriptVehicle::VT_ROAD || vehicle_type == ScriptVehicle::VT_RAIL ||
 145          *   vehicle_type == ScriptVehicle::VT_WATER || vehicle_type == ScriptVehicle::VT_AIR
 146          * @game @pre ScriptCompanyMode::IsValid().
 147          * @return The total number of vehicles in the group with id group_id and it's sub-groups.
 148          * @note If the group is valid (neither GROUP_ALL nor GROUP_DEFAULT), the value of
 149          *  vehicle_type is retrieved from the group itself and not from the input value.
 150          *  But if the group is GROUP_ALL or GROUP_DEFAULT, then vehicle_type must be valid.
 151          */
 152         static SQInteger GetNumVehicles(GroupID group_id, ScriptVehicle::VehicleType vehicle_type);
 153
 154         /**
 155          * Move a vehicle to a group.
 156          * @param group_id The group to move the vehicle to.
 157          * @param vehicle_id The vehicle to move to the group.
 158          * @pre IsValidGroup(group_id) || group_id == GROUP_DEFAULT.
 159          * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
 160          * @game @pre ScriptCompanyMode::IsValid().
 161          * @return True if and only if the vehicle was successfully moved to the group.
 162          * @note A vehicle can be in only one group at the same time. To remove it from
 163          *  a group, move it to another or to GROUP_DEFAULT. Moving the vehicle to the
 164          *  given group means removing it from another group.
 165          */
 166         static bool MoveVehicle(GroupID group_id, VehicleID vehicle_id);
 167
 168         /**
 169          * Enable or disable the removal of wagons when a (part of a) vehicle is
 170          *  (auto)replaced with a longer variant (longer wagons or longer engines)
 171          *  If enabled, wagons are removed from the end of the vehicle until it
 172          *  fits in the same number of tiles as it did before.
 173          * @param keep_length If true, wagons will be removed if the new engine is longer.
 174          * @game @pre ScriptCompanyMode::IsValid().
 175          * @return True if and only if the value was successfully changed.
 176          */
 177         static bool EnableWagonRemoval(bool keep_length);
 178
 179         /**
 180          * Get the current status of wagon removal.
 181          * @game @pre ScriptCompanyMode::IsValid().
 182          * @return Whether or not wagon removal is enabled.
 183          */
 184         static bool HasWagonRemoval();
 185
 186         /**
 187          * Start replacing all vehicles with a specified engine with another engine.
 188          * @param group_id The group to replace vehicles from. Use ALL_GROUP to replace
 189          *  vehicles from all groups that haven't set autoreplace protection.
 190          * @param engine_id_old The engine id to start replacing.
 191          * @param engine_id_new The engine id to replace with.
 192          * @pre IsValidGroup(group_id) || group_id == GROUP_DEFAULT || group_id == GROUP_ALL.
 193          * @pre ScriptEngine.IsBuildable(engine_id_new).
 194          * @game @pre ScriptCompanyMode::IsValid().
 195          * @return True if and if the replacing was successfully started.
 196          * @note To stop autoreplacing engine_id_old, call StopAutoReplace(group_id, engine_id_old).
 197          */
 198         static bool SetAutoReplace(GroupID group_id, EngineID engine_id_old, EngineID engine_id_new);
 199
 200         /**
 201          * Get the EngineID the given EngineID is replaced with.
 202          * @param group_id The group to get the replacement from.
 203          * @param engine_id The engine that is being replaced.
 204          * @pre IsValidGroup(group_id) || group_id == GROUP_DEFAULT || group_id == GROUP_ALL.
 205          * @game @pre ScriptCompanyMode::IsValid().
 206          * @return The EngineID that is replacing engine_id or an invalid EngineID
 207          *   in case engine_id is not begin replaced.
 208          */
 209         static EngineID GetEngineReplacement(GroupID group_id, EngineID engine_id);
 210
 211         /**
 212          * Stop replacing a certain engine in the specified group.
 213          * @param group_id The group to stop replacing the engine in.
 214          * @param engine_id The engine id to stop replacing with another engine.
 215          * @pre IsValidGroup(group_id) || group_id == GROUP_DEFAULT || group_id == GROUP_ALL.
 216          * @game @pre ScriptCompanyMode::IsValid().
 217          * @return True if and if the replacing was successfully stopped.
 218          */
 219         static bool StopAutoReplace(GroupID group_id, EngineID engine_id);
 220
 221         /**
 222          * Get the current profit of a group.
 223          * @param group_id The group to get the profit of.
 224          * @pre IsValidGroup(group_id).
 225          * @return The profit the vehicles in this group have made this economy-year so far.
 226          * @see \ref ScriptEconomyTime
 227          */
 228         static Money GetProfitThisYear(GroupID group_id);
 229
 230         /**
 231          * Get the profit of last year of a group.
 232          * @param group_id The group to get the profit of.
 233          * @pre IsValidGroup(group_id).
 234          * @return The profit the vehicles in this group  made in the previous economy-year.
 235          * @see \ref ScriptEconomyTime
 236          */
 237         static Money GetProfitLastYear(GroupID group_id);
 238
 239         /**
 240          * Get the current vehicle usage of a group.
 241          * @param group_id The group to get the current usage of.
 242          * @pre IsValidGroup(group_id).
 243          * @return The current usage of the group.
 244          */
 245         static SQInteger GetCurrentUsage(GroupID group_id);
 246
 247         /**
 248          * Set primary colour for a group.
 249          * @param group_id The group id to set the colour of.
 250          * @param colour Colour to set.
 251          * @pre IsValidGroup(group_id).
 252          * @game @pre ScriptCompanyMode::IsValid().
 253          * @return True iff the colour was set successfully.
 254          */
 255         static bool SetPrimaryColour(GroupID group_id, ScriptCompany::Colours colour);
 256
 257         /**
 258          * Set secondary colour for a group.
 259          * @param group_id The group id to set the colour of.
 260          * @param colour Colour to set.
 261          * @pre IsValidGroup(group_id).
 262          * @game @pre ScriptCompanyMode::IsValid().
 263          * @return True iff the colour was set successfully.
 264          */
 265         static bool SetSecondaryColour(GroupID group_id, ScriptCompany::Colours colour);
 266
 267         /**
 268          * Get primary colour of a group.
 269          * @param group_id The group id to get the colour of.
 270          * @pre IsValidGroup(group_id).
 271          * @return The primary colour of the group.
 272          */
 273         static ScriptCompany::Colours GetPrimaryColour(GroupID group_id);
 274
 275         /**
 276          * Get secondary colour for a group.
 277          * @param group_id The group id to get the colour of.
 278          * @pre IsValidGroup(group_id).
 279          * @return The secondary colour of the group.
 280          */
 281         static ScriptCompany::Colours GetSecondaryColour(GroupID group_id);
 282 };
 283
 284 #endif /* SCRIPT_GROUP_HPP */