src/script/api/script_map.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_map.hpp Everything to query and manipulate map metadata. */
   9
  10 #ifndef SCRIPT_MAP_HPP
  11 #define SCRIPT_MAP_HPP
  12
  13 #include "script_object.hpp"
  14 #include "../../tile_type.h"
  15
  16 /**
  17  * Class that handles all map related functions.
  18  * @api ai game
  19  */
  20 class ScriptMap : public ScriptObject {
  21 public:
  22         static const int TILE_INVALID = INVALID_TILE.base(); ///< Invalid TileIndex.
  23
  24         /**
  25          * Checks whether the given tile is valid.
  26          * @param tile The tile to check.
  27          * @return True is the tile it within the boundaries of the map.
  28          */
  29         static bool IsValidTile(TileIndex tile);
  30
  31         /**
  32          * Gets the number of tiles in the map.
  33          * @return The size of the map in tiles.
  34          * @post Return value is always positive.
  35          */
  36         static SQInteger GetMapSize();
  37
  38         /**
  39          * Gets the amount of tiles along the SW and NE border.
  40          * @return The length along the SW and NE borders.
  41          * @post Return value is always positive.
  42          */
  43         static SQInteger GetMapSizeX();
  44
  45         /**
  46          * Gets the amount of tiles along the SE and NW border.
  47          * @return The length along the SE and NW borders.
  48          * @post Return value is always positive.
  49          */
  50         static SQInteger GetMapSizeY();
  51
  52         /**
  53          * Gets the place along the SW/NE border (X-value).
  54          * @param tile The tile to get the X-value of.
  55          * @pre IsValidTile(tile).
  56          * @return The X-value.
  57          * @post Return value is always lower than GetMapSizeX().
  58          */
  59         static SQInteger GetTileX(TileIndex tile);
  60
  61         /**
  62          * Gets the place along the SE/NW border (Y-value).
  63          * @param tile The tile to get the Y-value of.
  64          * @pre IsValidTile(tile).
  65          * @return The Y-value.
  66          * @post Return value is always lower than GetMapSizeY().
  67          */
  68         static SQInteger GetTileY(TileIndex tile);
  69
  70         /**
  71          * Gets the TileIndex given a x,y-coordinate.
  72          * @param x The X coordinate.
  73          * @param y The Y coordinate.
  74          * @return The TileIndex for the given (x,y) coordinate.
  75          * @post When 0 <= x && x < GetMapSizeX() && 0 <= y && y < GetMapSizeY(), then a valid tile index is returned.
  76          *       Otherwise it may be invalid, but could be used to calculated neighbouring tiles, e.g. tile + AIMap.GetTileIndex(-1, -1) gets
  77          *       the tile index of the tile to the north. But be aware that even when tile is a valid tile, the result might not be a valid tile.
  78          */
  79         static TileIndex GetTileIndex(SQInteger x, SQInteger y);
  80
  81         /**
  82          * Calculates the Manhattan distance; the difference of
  83          *  the X and Y added together.
  84          * @param tile_from The start tile.
  85          * @param tile_to The destination tile.
  86          * @pre IsValidTile(tile_from).
  87          * @pre IsValidTile(tile_to).
  88          * @return The Manhattan distance between the tiles.
  89          */
  90         static SQInteger DistanceManhattan(TileIndex tile_from, TileIndex tile_to);
  91
  92         /**
  93          * Calculates the distance between two tiles via 1D calculation.
  94          *  This means the distance between X or the distance between Y, depending
  95          *  on which one is bigger.
  96          * @param tile_from The start tile.
  97          * @param tile_to The destination tile.
  98          * @pre IsValidTile(tile_from).
  99          * @pre IsValidTile(tile_to).
 100          * @return The maximum distance between the tiles.
 101          */
 102         static SQInteger DistanceMax(TileIndex tile_from, TileIndex tile_to);
 103
 104         /**
 105          * The squared distance between the two tiles.
 106          *  This is the distance is the length of the shortest straight line
 107          *  between both points.
 108          * @param tile_from The start tile.
 109          * @param tile_to The destination tile.
 110          * @pre IsValidTile(tile_from).
 111          * @pre IsValidTile(tile_to).
 112          * @return The squared distance between the tiles.
 113          */
 114         static SQInteger DistanceSquare(TileIndex tile_from, TileIndex tile_to);
 115
 116         /**
 117          * Calculates the shortest distance to the edge.
 118          * @param tile From where the distance has to be calculated.
 119          * @pre IsValidTile(tile).
 120          * @return The distances to the closest edge.
 121          */
 122         static SQInteger DistanceFromEdge(TileIndex tile);
 123 };
 124
 125 #endif /* SCRIPT_MAP_HPP */