src/script/api/script_tile.hpp

   1 /* $Id: script_tile.hpp 25213 2013-04-30 17:16:32Z rubidium $ */
   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_tile.hpp Everything to query and manipulate tiles. */
  11
  12 #ifndef SCRIPT_TILE_HPP
  13 #define SCRIPT_TILE_HPP
  14
  15 #include "script_error.hpp"
  16 #include "script_company.hpp"
  17 #include "../../slope_type.h"
  18 #include "../../transport_type.h"
  19
  20 /**
  21  * Class that handles all tile related functions.
  22  * @api ai game
  23  */
  24 class ScriptTile : public ScriptObject {
  25 public:
  26         /**
  27          * Error messages related to modifying tiles.
  28          */
  29         enum ErrorMessages {
  30
  31                 /** Base for tile related errors */
  32                 ERR_TILE_BASE = ScriptError::ERR_CAT_TILE << ScriptError::ERR_CAT_BIT_SIZE,
  33
  34                 /** Tile can't be raised any higher */
  35                 ERR_TILE_TOO_HIGH,                     // [STR_ERROR_ALREADY_AT_SEA_LEVEL]
  36
  37                 /** Tile can't be lowered any lower */
  38                 ERR_TILE_TOO_LOW,                      // [STR_ERROR_ALREADY_AT_SEA_LEVEL]
  39
  40                 /** The area was already flat */
  41                 ERR_AREA_ALREADY_FLAT,                 // [STR_ERROR_ALREADY_LEVELLED]
  42
  43                 /** There is a tunnel underneed */
  44                 ERR_EXCAVATION_WOULD_DAMAGE,           // [STR_ERROR_EXCAVATION_WOULD_DAMAGE]
  45         };
  46
  47         /**
  48          * Enumeration for corners of tiles.
  49          */
  50         enum Corner {
  51                 /* Note: these values represent part of the in-game Corner enum */
  52                 CORNER_W       = ::CORNER_W,       ///< West corner
  53                 CORNER_S       = ::CORNER_S,       ///< South corner
  54                 CORNER_E       = ::CORNER_E,       ///< East corner
  55                 CORNER_N       = ::CORNER_N,       ///< North corner
  56
  57                 CORNER_INVALID = ::CORNER_INVALID, ///< An invalid corner
  58         };
  59
  60         /**
  61          * Enumeration for the slope-type.
  62          *
  63          * This enumeration use the chars N, E, S, W corresponding the
  64          *  direction North, East, South and West. The top corner of a tile
  65          *  is the north-part of the tile.
  66          */
  67         enum Slope {
  68                 /* Note: these values represent part of the in-game Slope enum */
  69                 SLOPE_FLAT     = ::SLOPE_FLAT,     ///< A flat tile
  70                 SLOPE_W        = ::SLOPE_W,        ///< The west corner of the tile is raised
  71                 SLOPE_S        = ::SLOPE_S,        ///< The south corner of the tile is raised
  72                 SLOPE_E        = ::SLOPE_E,        ///< The east corner of the tile is raised
  73                 SLOPE_N        = ::SLOPE_N,        ///< The north corner of the tile is raised
  74                 SLOPE_STEEP    = ::SLOPE_STEEP,    ///< Indicates the slope is steep (The corner opposite of the not-raised corner is raised two times)
  75                 SLOPE_NW       = ::SLOPE_NW,       ///< North and west corner are raised
  76                 SLOPE_SW       = ::SLOPE_SW,       ///< South and west corner are raised
  77                 SLOPE_SE       = ::SLOPE_SE,       ///< South and east corner are raised
  78                 SLOPE_NE       = ::SLOPE_NE,       ///< North and east corner are raised
  79                 SLOPE_EW       = ::SLOPE_EW,       ///< East and west corner are raised
  80                 SLOPE_NS       = ::SLOPE_NS,       ///< North and south corner are raised
  81                 SLOPE_ELEVATED = ::SLOPE_ELEVATED, ///< Bit mask containing all 'simple' slopes. Does not appear as a slope.
  82                 SLOPE_NWS      = ::SLOPE_NWS,      ///< North, west and south corner are raised
  83                 SLOPE_WSE      = ::SLOPE_WSE,      ///< West, south and east corner are raised
  84                 SLOPE_SEN      = ::SLOPE_SEN,      ///< South, east and north corner are raised
  85                 SLOPE_ENW      = ::SLOPE_ENW,      ///< East, north and west corner are raised
  86                 SLOPE_STEEP_W  = ::SLOPE_STEEP_W,  ///< A steep slope falling to east (from west)
  87                 SLOPE_STEEP_S  = ::SLOPE_STEEP_S,  ///< A steep slope falling to north (from south)
  88                 SLOPE_STEEP_E  = ::SLOPE_STEEP_E,  ///< A steep slope falling to west (from east)
  89                 SLOPE_STEEP_N  = ::SLOPE_STEEP_N,  ///< A steep slope falling to south (from north)
  90
  91                 /* Custom added value, only valid for this API */
  92                 SLOPE_INVALID  = 0xFFFF,           ///< An invalid slope
  93         };
  94
  95         /**
  96          * The different transport types a tile can have.
  97          */
  98         enum TransportType {
  99                 /* Note: these values represent part of the in-game TransportType enum */
 100                 TRANSPORT_RAIL    =  ::TRANSPORT_RAIL,  ///< Tile with rail.
 101                 TRANSPORT_ROAD    =  ::TRANSPORT_ROAD,  ///< Tile with road.
 102                 TRANSPORT_WATER   =  ::TRANSPORT_WATER, ///< Tile with navigable waterways.
 103                 TRANSPORT_AIR     =  ::TRANSPORT_AIR,   ///< Tile with airport.
 104
 105                 /* Custom added value, only valid for this API */
 106                 TRANSPORT_INVALID = -1, ///< Tile without any transport type.
 107         };
 108
 109         /**
 110          * Get the base cost for building/clearing several things.
 111          */
 112         enum BuildType {
 113                 BT_FOUNDATION,   ///< Build a foundation under something
 114                 BT_TERRAFORM,    ///< Terraform
 115                 BT_BUILD_TREES,  ///< Build trees
 116                 BT_CLEAR_GRASS,  ///< Clear a tile with just grass
 117                 BT_CLEAR_ROUGH,  ///< Clear a rough tile
 118                 BT_CLEAR_ROCKY,  ///< Clear a tile with rocks
 119                 BT_CLEAR_FIELDS, ///< Clear a tile with farm fields
 120                 BT_CLEAR_HOUSE,  ///< Clear a tile with a house
 121         };
 122
 123         /**
 124          * The types of terrain a tile can have.
 125          *
 126          * @note When a desert or rainforest tile are changed, their terrain type will remain the same. In other words, a sea tile can be of the desert terrain type.
 127          * @note The snow terrain type can change to the normal terrain type and vice versa based on landscaping or variable snow lines from NewGRFs.
 128          */
 129         enum TerrainType {
 130                 TERRAIN_NORMAL,     ///< A normal tile (default); not desert, rainforest or snow.
 131                 TERRAIN_DESERT,     ///< A tile in the desert (manually set in in scenarios, below certain height and certain distance from water in random games).
 132                 TERRAIN_RAINFOREST, ///< A tile in the rainforest (manually set in scenarios, certain distance away from deserts in random games),
 133                 TERRAIN_SNOW        ///< A tile on or above the snowline level.
 134         };
 135
 136         /**
 137          * Check if this tile is buildable, i.e. no things on it that needs
 138          *  demolishing.
 139          * @param tile The tile to check on.
 140          * @pre ScriptMap::IsValidTile(tile).
 141          * @return True if it is buildable, false if not.
 142          * @note For trams you also might want to check for ScriptRoad::IsRoad(),
 143          *   as you can build tram-rails on road-tiles.
 144          * @note For rail you also might want to check for ScriptRoad::IsRoad(),
 145          *   as in some cases you can build rails on road-tiles.
 146          */
 147         static bool IsBuildable(TileIndex tile);
 148
 149         /**
 150          * Check if this tile is buildable in a rectangle around a tile, with the
 151          *  entry in the list as top-left.
 152          * @param tile The tile to check on.
 153          * @param width The width of the rectangle.
 154          * @param height The height of the rectangle.
 155          * @pre ScriptMap::IsValidTile(tile).
 156          * @return True if it is buildable, false if not.
 157          */
 158         static bool IsBuildableRectangle(TileIndex tile, uint width, uint height);
 159
 160         /**
 161          * Checks whether the given tile is actually a water tile.
 162          * @param tile The tile to check on.
 163          * @pre ScriptMap::IsValidTile(tile).
 164          * @return True if and only if the tile is a water tile.
 165          */
 166         static bool IsWaterTile(TileIndex tile);
 167
 168         /**
 169          * Checks whether the given tile is actually a coast tile.
 170          * @param tile The tile to check.
 171          * @pre ScriptMap::IsValidTile(tile).
 172          * @return True if and only if the tile is a coast tile.
 173          * @note Building on coast tiles in general is more expensive. This is not
 174          *  true if there are also trees on the tile, see #HasTreeOnTile.
 175          */
 176         static bool IsCoastTile(TileIndex tile);
 177
 178         /**
 179          * Checks whether the given tile is a station tile of any station.
 180          * @param tile The tile to check.
 181          * @pre ScriptMap::IsValidTile(tile).
 182          * @return True if and only if the tile is a station tile.
 183          */
 184         static bool IsStationTile(TileIndex tile);
 185
 186         /**
 187          * Check if a tile has a steep slope.
 188          * Steep slopes are slopes with a height difference of 2 across one diagonal of the tile.
 189          * @param slope The slope to check on.
 190          * @pre slope != SLOPE_INVALID.
 191          * @return True if the slope is a steep slope.
 192          */
 193         static bool IsSteepSlope(Slope slope);
 194
 195         /**
 196          * Check if a tile has a halftile slope.
 197          * Halftile slopes appear on top of halftile foundations. E.g. the slope you get when building a horizontal railtrack on the top of a SLOPE_N or SLOPE_STEEP_N.
 198          * @param slope The slope to check on.
 199          * @pre slope != SLOPE_INVALID.
 200          * @return True if the slope is a halftile slope.
 201          * @note Currently there is no API function that would return or accept a halftile slope.
 202          */
 203         static bool IsHalftileSlope(Slope slope);
 204
 205         /**
 206          * Check if the tile has any tree on it.
 207          * @param tile The tile to check on.
 208          * @pre ScriptMap::IsValidTile(tile).
 209          * @return True if and only if there is a tree on the tile.
 210          */
 211         static bool HasTreeOnTile(TileIndex tile);
 212
 213         /**
 214          * Check if the tile is a farmland tile.
 215          * @param tile The tile to check on.
 216          * @pre ScriptMap::IsValidTile(tile).
 217          * @return True if and only if the tile is farmland.
 218          */
 219         static bool IsFarmTile(TileIndex tile);
 220
 221         /**
 222          * Check if the tile is a rock tile.
 223          * @param tile The tile to check on.
 224          * @pre ScriptMap::IsValidTile(tile).
 225          * @return True if and only if the tile is rock tile.
 226          */
 227         static bool IsRockTile(TileIndex tile);
 228
 229         /**
 230          * Check if the tile is a rough tile.
 231          * @param tile The tile to check on.
 232          * @pre ScriptMap::IsValidTile(tile).
 233          * @return True if and only if the tile is rough tile.
 234          */
 235         static bool IsRoughTile(TileIndex tile);
 236
 237         /**
 238          * Check if the tile without buildings or infrastructure is a snow tile.
 239          * @note If you want to know if a tile (with or without buildings and infrastructure) is on or above the snowline, use ScriptTile::GetTerrainType(tile).
 240          * @param tile The tile to check on.
 241          * @pre ScriptMap::IsValidTile(tile).
 242          * @return True if and only if the tile is snow tile.
 243          */
 244         static bool IsSnowTile(TileIndex tile);
 245
 246         /**
 247          * Check if the tile without buildings or infrastructure is a desert tile.
 248          * @note If you want to know if a tile (with or without buildings and infrastructure) is in a desert, use ScriptTile::GetTerrainType(tile).
 249          * @param tile The tile to check on.
 250          * @pre ScriptMap::IsValidTile(tile).
 251          * @return True if and only if the tile is desert tile.
 252          */
 253         static bool IsDesertTile(TileIndex tile);
 254
 255         /**
 256          * Get the type of terrain regardless of buildings or infrastructure.
 257          * @note When a desert or rainforest tile are changed, their terrain type will remain the same. In other words, a sea tile can be of the desert terrain type.
 258          * @note The snow terrain type can change to the normal terrain type and vice versa based on landscaping or variable snow lines from NewGRFs.
 259          * @param tile The tile to check on.
 260          * @pre ScriptMap::IsValidTile(tile).
 261          * @return The #TerrainType.
 262          */
 263         static TerrainType GetTerrainType(TileIndex tile);
 264
 265         /**
 266          * Get the slope of a tile.
 267          * This is the slope of the bare tile. A possible foundation on the tile does not influence this slope.
 268          * @param tile The tile to check on.
 269          * @pre ScriptMap::IsValidTile(tile).
 270          * @return Bit mask encoding the slope. See #Slope for a description of the returned values.
 271          */
 272         static Slope GetSlope(TileIndex tile);
 273
 274         /**
 275          * Get the complement of the slope.
 276          * @param slope The slope to get the complement of.
 277          * @pre slope != SLOPE_INVALID.
 278          * @pre !IsSteepSlope(slope).
 279          * @pre !IsHalftileSlope(slope).
 280          * @return The complement of a slope. This means that all corners that
 281          *  weren't raised, are raised, and visa versa.
 282          */
 283         static Slope GetComplementSlope(Slope slope);
 284
 285         /**
 286          * Get the minimal height on a tile.
 287          * The returned height is the height of the bare tile. A possible foundation on the tile does not influence this height.
 288          * @param tile The tile to check on.
 289          * @pre ScriptMap::IsValidTile(tile).
 290          * @return The height of the lowest corner of the tile, ranging from 0 to 15.
 291          */
 292         static int32 GetMinHeight(TileIndex tile);
 293
 294         /**
 295          * Get the maximal height on a tile.
 296          * The returned height is the height of the bare tile. A possible foundation on the tile does not influence this height.
 297          * @param tile The tile to check on.
 298          * @pre ScriptMap::IsValidTile(tile).
 299          * @return The height of the highest corner of the tile, ranging from 0 to 15.
 300          */
 301         static int32 GetMaxHeight(TileIndex tile);
 302
 303         /**
 304          * Get the height of a certain corner of a tile.
 305          * The returned height is the height of the bare tile. A possible foundation on the tile does not influence this height.
 306          * @param tile The tile to check on.
 307          * @param corner The corner to query.
 308          * @pre ScriptMap::IsValidTile(tile).
 309          * @return The height of the lowest corner of the tile, ranging from 0 to 15.
 310          */
 311         static int32 GetCornerHeight(TileIndex tile, Corner corner);
 312
 313         /**
 314          * Get the owner of the tile.
 315          * @param tile The tile to get the owner from.
 316          * @pre ScriptMap::IsValidTile(tile).
 317          * @return The CompanyID of the owner of the tile, or COMPANY_INVALID if
 318          *  there is no owner (grass/industry/water tiles, etc.).
 319          */
 320         static ScriptCompany::CompanyID GetOwner(TileIndex tile);
 321
 322         /**
 323          * Checks whether the given tile contains parts suitable for the given
 324          *  TransportType.
 325          * @param tile The tile to check.
 326          * @param transport_type The TransportType to check against.
 327          * @pre ScriptMap::IsValidTile(tile).
 328          * @pre transport_type != TRANSPORT_AIR.
 329          * @note Returns false on tiles with roadworks and on road tiles with only
 330          *       a single piece of road as these tiles cannot be used to transport
 331          *       anything on. It furthermore returns true on some coast tile for
 332          *       TRANSPORT_WATER because ships can navigate over them.
 333          * @note Use ScriptAirport.IsAirportTile to check for airport tiles. Aircraft
 334          *       can fly over every tile on the map so using HasTransportType
 335          *       doesn't make sense for TRANSPORT_AIR.
 336          * @return True if and only if the tile has the given TransportType.
 337          */
 338         static bool HasTransportType(TileIndex tile, TransportType transport_type);
 339
 340         /**
 341          * Check how much cargo this tile accepts.
 342          *  It creates a radius around the tile, and adds up all acceptance of this
 343          *   cargo.
 344          * @param tile The tile to check on.
 345          * @param cargo_type The cargo to check the acceptance of.
 346          * @param width The width of the station.
 347          * @param height The height of the station.
 348          * @param radius The radius of the station.
 349          * @pre ScriptMap::IsValidTile(tile).
 350          * @pre ScriptCargo::IsValidCargo(cargo_type)
 351          * @pre width > 0.
 352          * @pre height > 0.
 353          * @pre radius >= 0.
 354          * @return Value below 8 means no acceptance; the more the better.
 355          */
 356         static int32 GetCargoAcceptance(TileIndex tile, CargoID cargo_type, int width, int height, int radius);
 357
 358         /**
 359          * Checks how many producers in the radius produces this cargo.
 360          *  It creates a radius around the tile, and counts all producer of this cargo.
 361          * @param tile The tile to check on.
 362          * @param cargo_type The cargo to check the production of.
 363          * @param width The width of the station.
 364          * @param height The height of the station.
 365          * @param radius The radius of the station.
 366          * @pre ScriptMap::IsValidTile(tile).
 367          * @pre ScriptCargo::IsValidCargo(cargo_type)
 368          * @pre width > 0.
 369          * @pre height > 0.
 370          * @pre radius >= 0.
 371          * @return The number of producers that produce this cargo within radius of the tile.
 372          */
 373         static int32 GetCargoProduction(TileIndex tile, CargoID cargo_type, int width, int height, int radius);
 374
 375         /**
 376          * Get the manhattan distance from the tile to the tile.
 377          * @param tile_from The tile to get the distance to.
 378          * @param tile_to The tile to get the distance to.
 379          * @return The distance between the two tiles.
 380          */
 381         static int32 GetDistanceManhattanToTile(TileIndex tile_from, TileIndex tile_to);
 382
 383         /**
 384          * Get the square distance from the tile to the tile.
 385          * @param tile_from The tile to get the distance to.
 386          * @param tile_to The tile to get the distance to.
 387          * @return The distance between the two tiles.
 388          */
 389         static int32 GetDistanceSquareToTile(TileIndex tile_from, TileIndex tile_to);
 390
 391         /**
 392          * Raise the given corners of the tile. The corners can be combined,
 393          *  for example: SLOPE_N | SLOPE_W (= SLOPE_NW) will raise the west and the north corner.
 394          * @note The corners will be modified in the order west (first), south, east, north (last).
 395          *       Changing one corner might cause another corner to be changed too. So modifiing
 396          *       multiple corners may result in changing some corners by multiple steps.
 397          * @param tile The tile to raise.
 398          * @param slope Corners to raise (SLOPE_xxx).
 399          * @pre tile < ScriptMap::GetMapSize().
 400          * @game @pre Valid ScriptCompanyMode active in scope.
 401          * @exception ScriptError::ERR_AREA_NOT_CLEAR
 402          * @exception ScriptError::ERR_TOO_CLOSE_TO_EDGE
 403          * @exception ScriptTile::ERR_TILE_TOO_HIGH
 404          * @return 0 means failed, 1 means success.
 405          */
 406         static bool RaiseTile(TileIndex tile, int32 slope);
 407
 408         /**
 409          * Lower the given corners of the tile. The corners can be combined,
 410          *  for example: SLOPE_N | SLOPE_W (= SLOPE_NW) will lower the west and the north corner.
 411          * @note The corners will be modified in the order west (first), south, east, north (last).
 412          *       Changing one corner might cause another corner to be changed too. So modifiing
 413          *       multiple corners may result in changing some corners by multiple steps.
 414          * @param tile The tile to lower.
 415          * @param slope Corners to lower (SLOPE_xxx).
 416          * @pre tile < ScriptMap::GetMapSize().
 417          * @game @pre Valid ScriptCompanyMode active in scope.
 418          * @exception ScriptError::ERR_AREA_NOT_CLEAR
 419          * @exception ScriptError::ERR_TOO_CLOSE_TO_EDGE
 420          * @exception ScriptTile::ERR_TILE_TOO_LOW
 421          * @return 0 means failed, 1 means success.
 422          */
 423         static bool LowerTile(TileIndex tile, int32 slope);
 424
 425         /**
 426          * Level all tiles in the rectangle between start_tile and end_tile so they
 427          *  are at the same height. All tiles will be raised or lowered until
 428          *  they are at height ScriptTile::GetCornerHeight(start_tile, ScriptTile::CORNER_N).
 429          * @param start_tile One corner of the rectangle to level.
 430          * @param end_tile The opposite corner of the rectangle.
 431          * @pre start_tile < ScriptMap::GetMapSize().
 432          * @pre end_tile < ScriptMap::GetMapSize().
 433          * @game @pre Valid ScriptCompanyMode active in scope.
 434          * @exception ScriptError::ERR_AREA_NOT_CLEAR
 435          * @exception ScriptError::ERR_TOO_CLOSE_TO_EDGE
 436          * @return True if one or more tiles were leveled.
 437          * @note Even if leveling some part fails, some other part may have been
 438          *  successfully leveled already.
 439          * @note This function may return true in ScriptTestMode, although it fails in
 440          *  ScriptExecMode.
 441          */
 442         static bool LevelTiles(TileIndex start_tile, TileIndex end_tile);
 443
 444         /**
 445          * Destroy everything on the given tile.
 446          * @param tile The tile to demolish.
 447          * @pre ScriptMap::IsValidTile(tile).
 448          * @game @pre Valid ScriptCompanyMode active in scope.
 449          * @exception ScriptError::ERR_AREA_NOT_CLEAR
 450          * @return True if and only if the tile was demolished.
 451          */
 452         static bool DemolishTile(TileIndex tile);
 453
 454         /**
 455          * Create a random tree on a tile.
 456          * @param tile The tile to build a tree on.
 457          * @pre ScriptMap::IsValidTile(tile).
 458          * @game @pre Valid ScriptCompanyMode active in scope.
 459          * @return True if and only if a tree was added on the tile.
 460          */
 461         static bool PlantTree(TileIndex tile);
 462
 463         /**
 464          * Create a random tree on a rectangle of tiles.
 465          * @param tile The top left tile of the rectangle.
 466          * @param width The width of the rectangle.
 467          * @param height The height of the rectangle.
 468          * @pre ScriptMap::IsValidTile(tile).
 469          * @pre width >= 1 && width <= 20.
 470          * @pre height >= 1 && height <= 20.
 471          * @game @pre Valid ScriptCompanyMode active in scope.
 472          * @return True if and only if a tree was added on any of the tiles in the rectangle.
 473          */
 474         static bool PlantTreeRectangle(TileIndex tile, uint width, uint height);
 475
 476         /**
 477          * Find out if this tile is within the rating influence of a town.
 478          *  If a station sign would be on this tile, the servicing quality of the station would
 479          *  influence the rating of the town.
 480          * @param tile The tile to check.
 481          * @param town_id The town to check.
 482          * @return True if the tile is within the rating influence of the town.
 483          */
 484         static bool IsWithinTownInfluence(TileIndex tile, TownID town_id);
 485
 486         /**
 487          * Find the town which has authority for the tile.
 488          *  The rating of your company in this town will be checked and affected when
 489          *  building stations, trees etc.
 490          * @param tile The tile to check.
 491          * @return The TownID of the town which has authority on this tile.
 492          */
 493         static TownID GetTownAuthority(TileIndex tile);
 494
 495         /**
 496          * Find the town that is closest to a tile. Stations you build at this tile
 497          *  will belong to this town.
 498          * @param tile The tile to check.
 499          * @return The TownID of the town closest to the tile.
 500          */
 501         static TownID GetClosestTown(TileIndex tile);
 502
 503         /**
 504          * Get the baseprice of building/clearing various tile-related things.
 505          * @param build_type the type to build
 506          * @return The baseprice of building or removing the given object.
 507          */
 508         static Money GetBuildCost(BuildType build_type);
 509 };
 510
 511 #endif /* SCRIPT_TILE_HPP */