1 files changed, 57 insertions, 7 deletions
diff --git a/crawl-ref/docs/level_design.txt b/crawl-ref/docs/level_design.txt
index 95cce6b6c4..f8c9932d1d 100644
--- a/crawl-ref/docs/level_design.txt
+++ b/crawl-ref/docs/level_design.txt
@@ -298,12 +298,62 @@ DEPTH:    For random vaults, branch entry vaults, and minivaults, this
           have no DEPTH: constraint. Note that maps without a DEPTH: constraint
           cannot be selected as random vaults or minivaults.
 
-CHANCE:   (number with 10 being default)
+CHANCE:   <priority>:<roll> or <roll>
+
+          CHANCE allows you to control the probability that your map
+          is used on any given level with an absolute roll.
+
+          There are two ways to specify the CHANCE roll:
+
+          CHANCE: 500
+          or
+          CHANCE: 5%
+
+          If specified as a raw number, the chance of selecting the
+          vault is <number> in 10000. If specified as a percentage,
+          the chance of selecting the vault is <perc> * 100 in 10000.
+          Note that CHANCE accepts only integers, no fractions or
+          decimals.
+
+          For any map with alternatives, a CHANCE influences how
+          likely the map is to be picked instead of the alternatives.
+          If a map has a CHANCE, Crawl will roll a random number in
+          the range 1-10000, and select the map if the CHANCE is >=
+          the rolled random number.
+
+          If there are multiple alternative maps with CHANCE, they
+          will be tested in an unspecified order; the first map that
+          makes the CHANCE roll will be used. If you'd like to specify
+          an order of testing CHANCEs, specify a CHANCE with a
+          priority:
+
+             CHANCE: 10 : 20%
+
+          This specifies a CHANCE of 20%, with a priority of 10, which
+          means this vault will be checked before any other vault with
+          a lower priority (the default priority is 0).
+
+          If no map with a CHANCE is picked, Crawl will select a map
+          based on WEIGHT, ignoring vaults with a CHANCE set.
+
+          Note that the Lua equivalent for CHANCE is a two-argument
+          function:
+
+          : chance(<priority>, <number>)
+
+          These lines are all equivalent:
+          CHANCE: 5%
+          CHANCE: 500
+          CHANCE: 0 : 5%
+          CHANCE: 0 : 500
+          : chance(0, 500)
+
+WEIGHT:   (number with 10 being default)
           For entry vaults and any other vaults randomly picked from among
           a set, this type of line affects the likelihood of the given vault
-          being picked in a given game. The default CHANCE: is 10. The
+          being picked in a given game. The default WEIGHT: is 10. The
           likelihood of a vault getting picked is:
-          [vault's CHANCE: / sum of all CHANCE:s of vaults of that type]
+          [vault's WEIGHT: / sum of all WEIGHT:s of vaults of that type]
 
 PLACE:    Used to specify certain special levels. Existing special levels
           include most branch ends.
@@ -1042,7 +1092,7 @@ G.    Hints for level makers
   The same goes for traps. This is much less so if there are several places
   for the chamber (or trap) and there's even a chance it doesn't exist.
 
-  You can also use CHANCE to create modified versions of the same map. In
+  You can also use WEIGHT to create modified versions of the same map. In
   order to do this, make several maps and endow each with a chance such
   that the sum of chances add up to 10.
 
@@ -1068,13 +1118,13 @@ G.    Hints for level makers
   necromancy) is even better.
 
 * Testing your maps.
-  This is easy for entry vaults. Temporarily introducing a CHANCE: 50000
+  This is easy for entry vaults. Temporarily introducing a WEIGHT: 50000
   will make your entry appear almost always. For other vaults, you can
-  for the moment declare them as entry vaults with a huge CHANCE: as
+  for the moment declare them as entry vaults with a huge WEIGHT: as
   above (and preferably in wizard mode). For more intricate things like
   new branch ends, you have to resort to wizard mode and use the &~ command
   to go directly to the place where the map is used, say Snake:5. You may want
-  to use a high CHANCE: again, if the map has alternatives (like Snake:5, or
+  to use a high WEIGHT: again, if the map has alternatives (like Snake:5, or
   Coc:7). Minivaults can also be tested by adding a PLACE: to the definition,
   which makes it very likely that the minivault will appear in the chosen
   level.