src/script/api/script_tunnel.hpp

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