Updated .des documentation. We should probably move this to the docs directory.

[1610591] Friendlies on dangerous terrain cannot be displaced. Prompting for
confirmation would be more consistent, but also more irritating.

git-svn-id: https://crawl-ref.svn.sourceforge.net/svnroot/crawl-ref/trunk@587 c06c8d41-db1a-0410-9941-cceddc491573

5 files changed, 73 insertions, 24 deletions

diff --git a/crawl-ref/source/dat/splev.des b/crawl-ref/source/dat/splev.des
index 4143632d17..4e3adb8edd 100644
--- a/crawl-ref/source/dat/splev.des
+++ b/crawl-ref/source/dat/splev.des
@@ -63,12 +63,14 @@
 #
 #  Guidelines for creating new vault maps:
 #
-#  [ds] If your map is not a minivault, make sure the side(s) that form the
-#  border have a rock wall padding at least 6 deep. For instance, if your map
-#  is ORIENT: north, you must have a 6 deep border of rock wall (or any
-#  other kind of wall) along the northern, eastern, and western edges of the
-#  map. If you're doing a fullscreen map (encompass), you must pad all around
-#  the map with 6 layers of wall.
+#  If your map is not a minivault, make sure the side(s) that form the border
+#  have a rock wall padding at least 6 deep. For instance, if your map is
+#  ORIENT: north, you must have a 6 deep border of rock wall (or any other kind
+#  of wall) along the northern, eastern, and western edges of the map. If
+#  you're doing a fullscreen map (encompass), you must pad all around the map
+#  with 6 layers of wall. For ORIENT: encompass maps, you don't need to
+#  explicitly include the padding provided you make the map small enough that
+#  the padding can be provided automatically.
 #
 #  Basically you can just let your creativity run wild. You do not have
 #  to place all of the stairs unless the level is full screen, in which
@@ -87,9 +89,23 @@
 #  ps - remember to add one to the monster array value when placing monsters
 #       on each map (it is 1-7, not 0-6) {dlb}
 #
-#  [dshaligram] All special levels MUST have an ORIENT: attribute; if there's
-#  no ORIENT: attribute, the level is considered to be a minivault, which is
-#  usually not what you want.
+#  All vaults MUST have an ORIENT: attribute; if there's no ORIENT: attribute,
+#  the vault is considered to be a minivault, which is usually not what you
+#  want.
+#
+#  Minivaults are handled very differently from regular vaults and special
+#  levels. They're placed *after* normal map generation, whereas normal vaults
+#  are placed before generating the rest of the level. There's no way to
+#  guarantee generation of a minivault on a particular level, whereas vaults
+#  can be forced to appear using a PLACE: attribute.
+#
+#  Floating vaults:
+#  If you want to do vault-like things in a map that should be positioned like
+#  a minivault, use ORIENT: float. This allows the vault to be placed in the
+#  middle of a level, unlike normal vaults that must be anchored to at least
+#  two edges of the map. Floating maps also do not need explicit entry points -
+#  the dungeon builder will choose random entry points if you don't specify
+#  any.
 #
 #  Special levels are selected either by PLACE: (for most special levels) or 
 #  TAGS: (for the Pandemonium demon lords). If you want to define alternate
diff --git a/crawl-ref/source/dat/vaults.des b/crawl-ref/source/dat/vaults.des
index b9333716d3..960a4bceb7 100644
--- a/crawl-ref/source/dat/vaults.des
+++ b/crawl-ref/source/dat/vaults.des
@@ -62,12 +62,14 @@
 #
 #  Guidelines for creating new vault maps:
 #
-#  [ds] If your map is not a minivault, make sure the side(s) that form the
-#  border have a rock wall padding at least 6 deep. For instance, if your map
-#  is ORIENT: north, you must have a 6 deep border of rock wall (or any
-#  other kind of wall) along the northern, eastern, and western edges of the
-#  map. If you're doing a fullscreen map (encompass), you must pad all around
-#  the map with 6 layers of wall.
+#  If your map is not a minivault, make sure the side(s) that form the border
+#  have a rock wall padding at least 6 deep. For instance, if your map is
+#  ORIENT: north, you must have a 6 deep border of rock wall (or any other kind
+#  of wall) along the northern, eastern, and western edges of the map. If
+#  you're doing a fullscreen map (encompass), you must pad all around the map
+#  with 6 layers of wall. For ORIENT: encompass maps, you don't need to
+#  explicitly include the padding provided you make the map small enough that
+#  the padding can be provided automatically.
 #
 #  Basically you can just let your creativity run wild. You do not have
 #  to place all of the stairs unless the level is full screen, in which
@@ -86,9 +88,23 @@
 #  ps - remember to add one to the monster array value when placing monsters
 #       on each map (it is 1-7, not 0-6) {dlb}
 #
-#  [dshaligram] All vaults MUST have an ORIENT: attribute; if there's no
-#  ORIENT: attribute, the vault is considered to be a minivault, which is
-#  usually not what you want.
+#  All vaults MUST have an ORIENT: attribute; if there's no ORIENT: attribute,
+#  the vault is considered to be a minivault, which is usually not what you
+#  want.
+#
+#  Minivaults are handled very differently from regular vaults and special
+#  levels. They're placed *after* normal map generation, whereas normal vaults
+#  are placed before generating the rest of the level. There's no way to
+#  guarantee generation of a minivault on a particular level, whereas vaults
+#  can be forced to appear using a PLACE: attribute.
+#
+#  Floating vaults:
+#  If you want to do vault-like things in a map that should be positioned like
+#  a minivault, use ORIENT: float. This allows the vault to be placed in the
+#  middle of a level, unlike normal vaults that must be anchored to at least
+#  two edges of the map. Floating maps also do not need explicit entry points -
+#  the dungeon builder will choose random entry points if you don't specify
+#  any.
 #
 ##############################################################################
 
diff --git a/crawl-ref/source/monstuff.cc b/crawl-ref/source/monstuff.cc
index f5e832f4ba..e47b0915e9 100644
--- a/crawl-ref/source/monstuff.cc
+++ b/crawl-ref/source/monstuff.cc
@@ -1145,10 +1145,13 @@ bool swap_places(struct monsters *monster)
     int loc_x = you.x_pos;
     int loc_y = you.y_pos;
 
-    swap = habitat_okay( monster, grd[loc_x][loc_y] );
+    const int mgrid = grd[monster->x][monster->y];
+
+    swap = habitat_okay( monster, grd[loc_x][loc_y] )
+        && !is_grid_dangerous(mgrid);
 
     // chose an appropiate habitat square at random around the target.
-    if (!swap)
+    if (!swap && !is_grid_dangerous(mgrid))
     {
         int num_found = 0;
         int temp_x, temp_y;
diff --git a/crawl-ref/source/player.cc b/crawl-ref/source/player.cc
index 3b4f44b370..8df05fdbf1 100644
--- a/crawl-ref/source/player.cc
+++ b/crawl-ref/source/player.cc
@@ -177,8 +177,7 @@ bool move_player_to_grid( int x, int y, bool stepped, bool allow_shift,
     {
         // XXX: at some point we're going to need to fix the swimming 
         // code to handle burden states.
-        if (new_grid == DNGN_LAVA 
-            || (new_grid == DNGN_DEEP_WATER && you.species != SP_MERFOLK))
+        if (is_grid_dangerous(new_grid))
         {
             // lava and dangerous deep water (ie not merfolk)
             int entry_x = (stepped) ? you.x_pos : x;
@@ -295,6 +294,18 @@ bool move_player_to_grid( int x, int y, bool stepped, bool allow_shift,
     return (true);
 }
 
+bool player_can_swim()
+{
+    return (you.species == SP_MERFOLK);
+}
+
+bool is_grid_dangerous(int grid)
+{
+    return (!player_is_levitating()
+            && (grid == DNGN_LAVA
+                || grid == DNGN_DEEP_WATER && !player_can_swim()));
+}
+
 bool player_in_mappable_area( void )
 {
     return (you.level_type != LEVEL_LABYRINTH && you.level_type != LEVEL_ABYSS);
@@ -322,7 +333,7 @@ bool player_in_water(void)
 
 bool player_is_swimming(void)
 {
-    return (player_in_water() && you.species == SP_MERFOLK);
+    return (player_in_water() && player_can_swim());
 }
 
 bool player_under_penance(void)
@@ -1383,7 +1394,7 @@ int player_movement_speed(void)
 {
     int mv = 10;
 
-    if (you.species == SP_MERFOLK && player_is_swimming())
+    if (player_is_swimming())
     {
         // This is swimming... so it doesn't make sense to really
         // apply the other things (the mutation is "cover ground",
diff --git a/crawl-ref/source/player.h b/crawl-ref/source/player.h
index 8cfc165ee2..088f290228 100644
--- a/crawl-ref/source/player.h
+++ b/crawl-ref/source/player.h
@@ -459,6 +459,9 @@ bool player_weapon_wielded();
 item_def *player_weapon();
 item_def *player_shield();
 
+// Determines if the given grid is dangerous for the player to enter.
+bool is_grid_dangerous(int grid);
+
 void run_macro(const char *macroname = NULL);
 
 #endif