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