(svn r25213) -Fix [FS#5537]: clarify on which tiles IsDesertTile and IsSnowTile work, i.e. the ones without infrastructure or buildings

-Feature: introduce GetTerrainType which allows one to get that information for tiles with buildings and infrastructure as well

7 files changed, 56 insertions, 4 deletions

diff --git a/src/script/api/ai/ai_tile.hpp.sq b/src/script/api/ai/ai_tile.hpp.sq
index 44d5e326c..570e88cd2 100644
--- a/src/script/api/ai/ai_tile.hpp.sq
+++ b/src/script/api/ai/ai_tile.hpp.sq
@@ -66,6 +66,10 @@ void SQAITile_Register(Squirrel *engine)
 	SQAITile.DefSQConst(engine, ScriptTile::BT_CLEAR_ROCKY,              "BT_CLEAR_ROCKY");
 	SQAITile.DefSQConst(engine, ScriptTile::BT_CLEAR_FIELDS,             "BT_CLEAR_FIELDS");
 	SQAITile.DefSQConst(engine, ScriptTile::BT_CLEAR_HOUSE,              "BT_CLEAR_HOUSE");
+	SQAITile.DefSQConst(engine, ScriptTile::TERRAIN_NORMAL,              "TERRAIN_NORMAL");
+	SQAITile.DefSQConst(engine, ScriptTile::TERRAIN_DESERT,              "TERRAIN_DESERT");
+	SQAITile.DefSQConst(engine, ScriptTile::TERRAIN_RAINFOREST,          "TERRAIN_RAINFOREST");
+	SQAITile.DefSQConst(engine, ScriptTile::TERRAIN_SNOW,                "TERRAIN_SNOW");
 
 	ScriptError::RegisterErrorMap(STR_ERROR_ALREADY_AT_SEA_LEVEL,    ScriptTile::ERR_TILE_TOO_HIGH);
 	ScriptError::RegisterErrorMap(STR_ERROR_ALREADY_AT_SEA_LEVEL,    ScriptTile::ERR_TILE_TOO_LOW);
@@ -90,6 +94,7 @@ void SQAITile_Register(Squirrel *engine)
 	SQAITile.DefSQStaticMethod(engine, &ScriptTile::IsRoughTile,                "IsRoughTile",                2, ".i");
 	SQAITile.DefSQStaticMethod(engine, &ScriptTile::IsSnowTile,                 "IsSnowTile",                 2, ".i");
 	SQAITile.DefSQStaticMethod(engine, &ScriptTile::IsDesertTile,               "IsDesertTile",               2, ".i");
+	SQAITile.DefSQStaticMethod(engine, &ScriptTile::GetTerrainType,             "GetTerrainType",             2, ".i");
 	SQAITile.DefSQStaticMethod(engine, &ScriptTile::GetSlope,                   "GetSlope",                   2, ".i");
 	SQAITile.DefSQStaticMethod(engine, &ScriptTile::GetComplementSlope,         "GetComplementSlope",         2, ".i");
 	SQAITile.DefSQStaticMethod(engine, &ScriptTile::GetMinHeight,               "GetMinHeight",               2, ".i");
diff --git a/src/script/api/ai_changelog.hpp b/src/script/api/ai_changelog.hpp
index 6f1741c1c..ce2d55745 100644
--- a/src/script/api/ai_changelog.hpp
+++ b/src/script/api/ai_changelog.hpp
@@ -21,6 +21,7 @@
  *
  * API additions:
  * \li AIStation::HasRating
+ * \li AITile::GetTerrainType
  *
  * Other changes:
  * \li AIStation::GetRating does return -1 for cargo-station combinations that
diff --git a/src/script/api/game/game_tile.hpp.sq b/src/script/api/game/game_tile.hpp.sq
index c2d5cb55e..6224919ff 100644
--- a/src/script/api/game/game_tile.hpp.sq
+++ b/src/script/api/game/game_tile.hpp.sq
@@ -66,6 +66,10 @@ void SQGSTile_Register(Squirrel *engine)
 	SQGSTile.DefSQConst(engine, ScriptTile::BT_CLEAR_ROCKY,              "BT_CLEAR_ROCKY");
 	SQGSTile.DefSQConst(engine, ScriptTile::BT_CLEAR_FIELDS,             "BT_CLEAR_FIELDS");
 	SQGSTile.DefSQConst(engine, ScriptTile::BT_CLEAR_HOUSE,              "BT_CLEAR_HOUSE");
+	SQGSTile.DefSQConst(engine, ScriptTile::TERRAIN_NORMAL,              "TERRAIN_NORMAL");
+	SQGSTile.DefSQConst(engine, ScriptTile::TERRAIN_DESERT,              "TERRAIN_DESERT");
+	SQGSTile.DefSQConst(engine, ScriptTile::TERRAIN_RAINFOREST,          "TERRAIN_RAINFOREST");
+	SQGSTile.DefSQConst(engine, ScriptTile::TERRAIN_SNOW,                "TERRAIN_SNOW");
 
 	ScriptError::RegisterErrorMap(STR_ERROR_ALREADY_AT_SEA_LEVEL,    ScriptTile::ERR_TILE_TOO_HIGH);
 	ScriptError::RegisterErrorMap(STR_ERROR_ALREADY_AT_SEA_LEVEL,    ScriptTile::ERR_TILE_TOO_LOW);
@@ -90,6 +94,7 @@ void SQGSTile_Register(Squirrel *engine)
 	SQGSTile.DefSQStaticMethod(engine, &ScriptTile::IsRoughTile,                "IsRoughTile",                2, ".i");
 	SQGSTile.DefSQStaticMethod(engine, &ScriptTile::IsSnowTile,                 "IsSnowTile",                 2, ".i");
 	SQGSTile.DefSQStaticMethod(engine, &ScriptTile::IsDesertTile,               "IsDesertTile",               2, ".i");
+	SQGSTile.DefSQStaticMethod(engine, &ScriptTile::GetTerrainType,             "GetTerrainType",             2, ".i");
 	SQGSTile.DefSQStaticMethod(engine, &ScriptTile::GetSlope,                   "GetSlope",                   2, ".i");
 	SQGSTile.DefSQStaticMethod(engine, &ScriptTile::GetComplementSlope,         "GetComplementSlope",         2, ".i");
 	SQGSTile.DefSQStaticMethod(engine, &ScriptTile::GetMinHeight,               "GetMinHeight",               2, ".i");
diff --git a/src/script/api/game_changelog.hpp b/src/script/api/game_changelog.hpp
index 4fed0a13a..9ad1a3faf 100644
--- a/src/script/api/game_changelog.hpp
+++ b/src/script/api/game_changelog.hpp
@@ -20,10 +20,11 @@
  * 1.4.0 is not yet released. The following changes are not set in stone yet.
  *
  * API additions:
- * \li AIStation::HasRating
+ * \li GSStation::HasRating
+ * \li GSTile::GetTerrainType
  *
  * Other changes:
- * \li AIStation::GetRating does return -1 for cargo-station combinations that
+ * \li GSStation::GetRating does return -1 for cargo-station combinations that
  *     do not have a rating yet instead of returning 69.
  *
  * \b 1.3.0
diff --git a/src/script/api/script_tile.cpp b/src/script/api/script_tile.cpp
index f6f016213..b14bea649 100644
--- a/src/script/api/script_tile.cpp
+++ b/src/script/api/script_tile.cpp
@@ -135,6 +135,19 @@
 	return (::IsTileType(tile, MP_CLEAR) && ::IsClearGround(tile, CLEAR_DESERT));
 }
 
+/* static */ ScriptTile::TerrainType ScriptTile::GetTerrainType(TileIndex tile)
+{
+	if (!::IsValidTile(tile)) return TERRAIN_NORMAL;
+
+	switch (::GetTerrainType(tile)) {
+		default:
+		case 0: return TERRAIN_NORMAL;
+		case 1: return TERRAIN_DESERT;
+		case 2: return TERRAIN_RAINFOREST;
+		case 4: return TERRAIN_SNOW;
+	}
+}
+
 /* static */ ScriptTile::Slope ScriptTile::GetSlope(TileIndex tile)
 {
 	if (!::IsValidTile(tile)) return SLOPE_INVALID;
diff --git a/src/script/api/script_tile.hpp b/src/script/api/script_tile.hpp
index e4d9cda98..f4a2f0970 100644
--- a/src/script/api/script_tile.hpp
+++ b/src/script/api/script_tile.hpp
@@ -121,6 +121,19 @@ public:
 	};
 
 	/**
+	 * The types of terrain a tile can have.
+	 *
+	 * @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.
+	 * @note The snow terrain type can change to the normal terrain type and vice versa based on landscaping or variable snow lines from NewGRFs.
+	 */
+	enum TerrainType {
+		TERRAIN_NORMAL,     ///< A normal tile (default); not desert, rainforest or snow.
+		TERRAIN_DESERT,     ///< A tile in the desert (manually set in in scenarios, below certain height and certain distance from water in random games).
+		TERRAIN_RAINFOREST, ///< A tile in the rainforest (manually set in scenarios, certain distance away from deserts in random games),
+		TERRAIN_SNOW        ///< A tile on or above the snowline level.
+	};
+
+	/**
 	 * Check if this tile is buildable, i.e. no things on it that needs
 	 *  demolishing.
 	 * @param tile The tile to check on.
@@ -222,7 +235,8 @@ public:
 	static bool IsRoughTile(TileIndex tile);
 
 	/**
-	 * Check if the tile is a snow tile.
+	 * Check if the tile without buildings or infrastructure is a snow tile.
+	 * @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).
 	 * @param tile The tile to check on.
 	 * @pre ScriptMap::IsValidTile(tile).
 	 * @return True if and only if the tile is snow tile.
@@ -230,7 +244,8 @@ public:
 	static bool IsSnowTile(TileIndex tile);
 
 	/**
-	 * Check if the tile is a desert tile.
+	 * Check if the tile without buildings or infrastructure is a desert tile.
+	 * @note If you want to know if a tile (with or without buildings and infrastructure) is in a desert, use ScriptTile::GetTerrainType(tile).
 	 * @param tile The tile to check on.
 	 * @pre ScriptMap::IsValidTile(tile).
 	 * @return True if and only if the tile is desert tile.
@@ -238,6 +253,16 @@ public:
 	static bool IsDesertTile(TileIndex tile);
 
 	/**
+	 * Get the type of terrain regardless of buildings or infrastructure.
+	 * @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.
+	 * @note The snow terrain type can change to the normal terrain type and vice versa based on landscaping or variable snow lines from NewGRFs.
+	 * @param tile The tile to check on.
+	 * @pre ScriptMap::IsValidTile(tile).
+	 * @return The #TerrainType.
+	 */
+	static TerrainType GetTerrainType(TileIndex tile);
+
+	/**
 	 * Get the slope of a tile.
 	 * This is the slope of the bare tile. A possible foundation on the tile does not influence this slope.
 	 * @param tile The tile to check on.
diff --git a/src/script/api/template/template_tile.hpp.sq b/src/script/api/template/template_tile.hpp.sq
index 8897e8c55..e78aaa6ac 100644
--- a/src/script/api/template/template_tile.hpp.sq
+++ b/src/script/api/template/template_tile.hpp.sq
@@ -23,6 +23,8 @@ namespace SQConvert {
 	template <> inline int Return<ScriptTile::TransportType>(HSQUIRRELVM vm, ScriptTile::TransportType res) { sq_pushinteger(vm, (int32)res); return 1; }
 	template <> inline ScriptTile::BuildType GetParam(ForceType<ScriptTile::BuildType>, HSQUIRRELVM vm, int index, SQAutoFreePointers *ptr) { SQInteger tmp; sq_getinteger(vm, index, &tmp); return (ScriptTile::BuildType)tmp; }
 	template <> inline int Return<ScriptTile::BuildType>(HSQUIRRELVM vm, ScriptTile::BuildType res) { sq_pushinteger(vm, (int32)res); return 1; }
+	template <> inline ScriptTile::TerrainType GetParam(ForceType<ScriptTile::TerrainType>, HSQUIRRELVM vm, int index, SQAutoFreePointers *ptr) { SQInteger tmp; sq_getinteger(vm, index, &tmp); return (ScriptTile::TerrainType)tmp; }
+	template <> inline int Return<ScriptTile::TerrainType>(HSQUIRRELVM vm, ScriptTile::TerrainType res) { sq_pushinteger(vm, (int32)res); return 1; }
 
 	/* Allow ScriptTile to be used as Squirrel parameter */
 	template <> inline ScriptTile *GetParam(ForceType<ScriptTile *>, HSQUIRRELVM vm, int index, SQAutoFreePointers *ptr) { SQUserPointer instance; sq_getinstanceup(vm, index, &instance, 0); return  (ScriptTile *)instance; }