src/script/api/script_bridge.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_bridge.hpp Everything to query and build bridges. */
   9
  10 #ifndef SCRIPT_BRIDGE_HPP
  11 #define SCRIPT_BRIDGE_HPP
  12
  13 #include "script_vehicle.hpp"
  14
  15 /**
  16  * Class that handles all bridge related functions.
  17  * @api ai game
  18  */
  19 class ScriptBridge : public ScriptObject {
  20 public:
  21         /**
  22          * All bridge related error messages.
  23          *
  24          * @see ScriptErrorType
  25          */
  26         enum ErrorMessages {
  27                 /** Base for bridge related errors */
  28                 ERR_BRIDGE_BASE = ScriptError::ERR_CAT_BRIDGE << ScriptError::ERR_CAT_BIT_SIZE,
  29
  30                 /**
  31                  * The bridge you want to build is not available yet,
  32                  * or it is not available for the requested length.
  33                  */
  34                 ERR_BRIDGE_TYPE_UNAVAILABLE,         // [STR_ERROR_CAN_T_BUILD_BRIDGE_HERE]
  35
  36                 /** One (or more) of the bridge head(s) ends in water. */
  37                 ERR_BRIDGE_CANNOT_END_IN_WATER,      // [STR_ERROR_ENDS_OF_BRIDGE_MUST_BOTH]
  38
  39                 /** The bride heads need to be on the same height */
  40                 ERR_BRIDGE_HEADS_NOT_ON_SAME_HEIGHT, // [STR_ERROR_BRIDGEHEADS_NOT_SAME_HEIGHT]
  41         };
  42
  43         /**
  44          * Checks whether the given bridge type is valid.
  45          * @param bridge_id The bridge to check.
  46          * @return True if and only if the bridge type is valid.
  47          */
  48         static bool IsValidBridge(BridgeID bridge_id);
  49
  50         /**
  51          * Checks whether the given tile is actually a bridge start or end tile.
  52          * @param tile The tile to check.
  53          * @pre ScriptMap::IsValidTile(tile).
  54          * @return True if and only if the tile is the beginning or end of a bridge.
  55          */
  56         static bool IsBridgeTile(TileIndex tile);
  57
  58         /**
  59          * Get the BridgeID of a bridge at a given tile.
  60          * @param tile The tile to get the BridgeID from.
  61          * @pre IsBridgeTile(tile).
  62          * @return The BridgeID from the bridge at tile 'tile'.
  63          */
  64         static BridgeID GetBridgeID(TileIndex tile);
  65
  66         /**
  67          * Get the name of a bridge.
  68          * @param bridge_id The bridge to get the name of.
  69          * @param vehicle_type The vehicle-type of bridge to get the name of.
  70          * @pre IsValidBridge(bridge_id).
  71          * @pre vehicle_type == ScriptVehicle::VT_ROAD || vehicle_type == ScriptVehicle::VT_RAIL || vehicle_type == ScriptVehicle::VT_WATER
  72          * @return The name the bridge has.
  73          */
  74         static std::optional<std::string> GetName(BridgeID bridge_id, ScriptVehicle::VehicleType vehicle_type);
  75
  76         /**
  77          * Get the maximum speed of a bridge.
  78          * @param bridge_id The bridge to get the maximum speed of.
  79          * @pre IsValidBridge(bridge_id).
  80          * @return The maximum speed the bridge has.
  81          * @note The speed is in OpenTTD's internal speed unit.
  82          *       This is mph / 1.6, which is roughly km/h.
  83          *       To get km/h multiply this number by 1.00584.
  84          */
  85         static SQInteger GetMaxSpeed(BridgeID bridge_id);
  86
  87         /**
  88          * Get the new cost of a bridge, excluding the road and/or rail.
  89          * @param bridge_id The bridge to get the new cost of.
  90          * @param length The length of the bridge.
  91          *               The value will be clamped to 0 .. MAX(int32_t).
  92          * @pre IsValidBridge(bridge_id).
  93          * @return The new cost the bridge has.
  94          */
  95         static Money GetPrice(BridgeID bridge_id, SQInteger length);
  96
  97         /**
  98          * Get the maximum length of a bridge.
  99          * @param bridge_id The bridge to get the maximum length of.
 100          * @pre IsValidBridge(bridge_id).
 101          * @returns The maximum length the bridge has.
 102          */
 103         static SQInteger GetMaxLength(BridgeID bridge_id);
 104
 105         /**
 106          * Get the minimum length of a bridge.
 107          * @param bridge_id The bridge to get the minimum length of.
 108          * @pre IsValidBridge(bridge_id).
 109          * @returns The minimum length the bridge has.
 110          */
 111         static SQInteger GetMinLength(BridgeID bridge_id);
 112
 113         /**
 114          * Internal function to help BuildBridge in case of road.
 115          * @api -all
 116          */
 117         static bool _BuildBridgeRoad1();
 118
 119         /**
 120          * Internal function to help BuildBridge in case of road.
 121          * @api -all
 122          */
 123         static bool _BuildBridgeRoad2();
 124
 125         /**
 126          * Build a bridge from one tile to the other.
 127          * As an extra for road, this functions builds two half-pieces of road on
 128          *  each end of the bridge, making it easier for you to connect it to your
 129          *  network.
 130          * @param vehicle_type The vehicle-type of bridge to build.
 131          * @param bridge_id The bridge-type to build.
 132          * @param start Where to start the bridge.
 133          * @param end Where to end the bridge.
 134          * @pre ScriptMap::IsValidTile(start).
 135          * @pre ScriptMap::IsValidTile(end).
 136          * @pre 'start' and 'end' are in a straight line, i.e.
 137          *  ScriptMap::GetTileX(start) == ScriptMap::GetTileX(end) or
 138          *  ScriptMap::GetTileY(start) == ScriptMap::GetTileY(end).
 139          * @pre vehicle_type == ScriptVehicle::VT_WATER ||
 140          *   (vehicle_type == ScriptVehicle::VT_ROAD && ScriptRoad::IsRoadTypeAvailable(ScriptRoad::GetCurrentRoadType())) ||
 141          *   (vehicle_type == ScriptVehicle::VT_RAIL && ScriptRail::IsRailTypeAvailable(ScriptRail::GetCurrentRailType())).
 142          * @game @pre ScriptCompanyMode::IsValid() || vehicle_type == ScriptVehicle::VT_ROAD.
 143          * @exception ScriptError::ERR_ALREADY_BUILT
 144          * @exception ScriptError::ERR_AREA_NOT_CLEAR
 145          * @exception ScriptError::ERR_LAND_SLOPED_WRONG
 146          * @exception ScriptError::ERR_VEHICLE_IN_THE_WAY
 147          * @exception ScriptBridge::ERR_BRIDGE_TYPE_UNAVAILABLE
 148          * @exception ScriptBridge::ERR_BRIDGE_CANNOT_END_IN_WATER
 149          * @exception ScriptBridge::ERR_BRIDGE_HEADS_NOT_ON_SAME_HEIGHT
 150          * @return Whether the bridge has been/can be build or not.
 151          * @game @note Building a bridge as deity (ScriptCompanyMode::IsDeity()) results in a bridge owned by towns.
 152          * @note No matter if the road pieces were build or not, if building the
 153          *  bridge succeeded, this function returns true.
 154          */
 155         static bool BuildBridge(ScriptVehicle::VehicleType vehicle_type, BridgeID bridge_id, TileIndex start, TileIndex end);
 156
 157         /**
 158          * Removes a bridge, by executing it on either the start or end tile.
 159          * @param tile An end or start tile of the bridge.
 160          * @pre ScriptMap::IsValidTile(tile).
 161          * @game @pre ScriptCompanyMode::IsValid().
 162          * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
 163          * @return Whether the bridge has been/can be removed or not.
 164          */
 165         static bool RemoveBridge(TileIndex tile);
 166
 167         /**
 168          * Get the tile that is on the other end of a bridge starting at tile.
 169          * @param tile The tile that is an end of a bridge.
 170          * @pre ScriptMap::IsValidTile(tile).
 171          * @pre IsBridgeTile(tile).
 172          * @return The TileIndex that is the other end of the bridge.
 173          */
 174         static TileIndex GetOtherBridgeEnd(TileIndex tile);
 175 };
 176
 177 #endif /* SCRIPT_BRIDGE_HPP */