src/script/api/script_tunnel.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_tunnel.hpp Everything to query and build tunnels. */
   9
  10 #ifndef SCRIPT_TUNNEL_HPP
  11 #define SCRIPT_TUNNEL_HPP
  12
  13 #include "script_vehicle.hpp"
  14
  15 /**
  16  * Class that handles all tunnel related functions.
  17  * @api ai game
  18  */
  19 class ScriptTunnel : public ScriptObject {
  20 public:
  21         /**
  22          * All tunnel related errors.
  23          */
  24         enum ErrorMessages {
  25
  26                 /** Base for bridge related errors */
  27                 ERR_TUNNEL_BASE = ScriptError::ERR_CAT_TUNNEL << ScriptError::ERR_CAT_BIT_SIZE,
  28
  29                 /** Can't build tunnels on water */
  30                 ERR_TUNNEL_CANNOT_BUILD_ON_WATER,            // [STR_ERROR_CAN_T_BUILD_ON_WATER]
  31
  32                 /** The start tile must slope either North, South, West or East */
  33                 ERR_TUNNEL_START_SITE_UNSUITABLE,            // [STR_ERROR_SITE_UNSUITABLE_FOR_TUNNEL]
  34
  35                 /** Another tunnel is in the way */
  36                 ERR_TUNNEL_ANOTHER_TUNNEL_IN_THE_WAY,        // [STR_ERROR_ANOTHER_TUNNEL_IN_THE_WAY]
  37
  38                 /** Unable to excavate land at the end to create the tunnel's exit */
  39                 ERR_TUNNEL_END_SITE_UNSUITABLE,              // [STR_ERROR_UNABLE_TO_EXCAVATE_LAND]
  40         };
  41
  42         /**
  43          * Check whether the tile is an entrance to a tunnel.
  44          * @param tile The tile to check.
  45          * @pre ScriptMap::IsValidTile(tile).
  46          * @return True if and only if the tile is the beginning or end of a tunnel.
  47          */
  48         static bool IsTunnelTile(TileIndex tile);
  49
  50         /**
  51          * Get the tile that exits on the other end of a (would be) tunnel starting
  52          *  at tile. If there is no 'simple' inclined slope at the start tile,
  53          *  this function will return ScriptMap::TILE_INVALID.
  54          * @param tile The tile that is an entrance to a tunnel or the tile where you may want to build a tunnel.
  55          * @pre ScriptMap::IsValidTile(tile).
  56          * @return The TileIndex that is the other end of the (would be) tunnel, or
  57          *  ScriptMap::TILE_INVALID if no other end was found (can't build tunnel).
  58          * @note Even if this function returns a valid tile, that is no guarantee
  59          *  that building a tunnel will succeed. Use BuildTunnel in ScriptTestMode to
  60          *  check whether a tunnel can actually be build.
  61          */
  62         static TileIndex GetOtherTunnelEnd(TileIndex tile);
  63
  64         /**
  65          * Internal function to help BuildTunnel in case of road.
  66          * @api -all
  67          */
  68         static bool _BuildTunnelRoad1();
  69
  70         /**
  71          * Internal function to help BuildTunnel in case of road.
  72          * @api -all
  73          */
  74         static bool _BuildTunnelRoad2();
  75
  76         /**
  77          * Builds a tunnel starting at start. The direction of the tunnel depends
  78          *  on the slope of the start tile. Tunnels can be created for either
  79          *  rails or roads; use the appropriate ScriptVehicle::VehicleType.
  80          * As an extra for road, this functions builds two half-pieces of road on
  81          *  each end of the tunnel, making it easier for you to connect it to your
  82          *  network.
  83          * @param start Where to start the tunnel.
  84          * @param vehicle_type The vehicle-type of tunnel to build.
  85          * @pre ScriptMap::IsValidTile(start).
  86          * @pre (vehicle_type == ScriptVehicle::VT_ROAD && ScriptRoad::IsRoadTypeAvailable(ScriptRoad::GetCurrentRoadType())) ||
  87          *      (vehicle_type == ScriptVehicle::VT_RAIL && ScriptRail::IsRailTypeAvailable(ScriptRail::GetCurrentRailType())).
  88          * @game @pre ScriptCompanyMode::IsValid() || vehicle_type == ScriptVehicle::VT_ROAD.
  89          * @exception ScriptError::ERR_AREA_NOT_CLEAR
  90          * @exception ScriptTunnel::ERR_TUNNEL_CANNOT_BUILD_ON_WATER
  91          * @exception ScriptTunnel::ERR_TUNNEL_START_SITE_UNSUITABLE
  92          * @exception ScriptTunnel::ERR_TUNNEL_ANOTHER_TUNNEL_IN_THE_WAY
  93          * @exception ScriptTunnel::ERR_TUNNEL_END_SITE_UNSUITABLE
  94          * @return Whether the tunnel has been/can be build or not.
  95          * @note The slope of a tile can be determined by ScriptTile::GetSlope(TileIndex).
  96          * @note No matter if the road pieces were build or not, if building the
  97          *  tunnel succeeded, this function returns true.
  98          * @game @note Building a tunnel as deity (ScriptCompanyMode::IsDeity()) results in a tunnel owned by towns.
  99          */
 100         static bool BuildTunnel(ScriptVehicle::VehicleType vehicle_type, TileIndex start);
 101
 102         /**
 103          * Remove the tunnel whose entrance is located at tile.
 104          * @param tile The tile that is an entrance to a tunnel.
 105          * @pre ScriptMap::IsValidTile(tile) && IsTunnelTile(tile).
 106          * @game @pre ScriptCompanyMode::IsValid().
 107          * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
 108          * @return Whether the tunnel has been/can be removed or not.
 109          */
 110         static bool RemoveTunnel(TileIndex tile);
 111 };
 112
 113 #endif /* SCRIPT_TUNNEL_HPP */