----------------------------------------------- How to make levels for Dungeon Crawl Stone Soup ----------------------------------------------- Part III: Advanced Methods ================ Contents: I. Conditionalising levels J. Validating levels K. Portal vaults L. Lua reference M. Feature names N. Map statistics O. Map generation This document describes the advanced features of vault making. This includes usage of lua and how to create portal vaults. Triggerables are covered in a separate document: triggerables.txt. I. Conditionalising levels ============================= Crawl translates level (.des) files into Lua code chunks and runs these chunks to produce the final level that is generated. While you don't need to use Lua for most levels, using Lua allows you to conditionalise or randomise levels with greater control. Let's take a simple example of randomisation: NAME: random_test # Put it on D:1 so it's easy to test. PLACE: D:1 ORIENT: float MAP xxxxxxxxxxxxxxxxxxx x........{........x xxxAxxxxxBxxxxxCxxx xxx.xxxxx.xxxxx.xxx xxx@xxxxx@xxxxx@xxx ENDMAP Now let's say you want A, B, and C to be randomly rock or floor, but B should be floor if both A and C are rock. Here's one way to do it (add these lines to the map definition): : local asolid, csolid : if crawl.random2(2) == 0 then : asolid = true : subst("A = x") : else : subst("A = .") : end : if crawl.random2(2) == 0 then : csolid = true : subst("C = x") : else : subst("C = .") : end : if asolid and csolid then : subst("B = .") : else : subst("B = .x") : end This code uses crawl.random2(N) which returns a number from 0 to N-1 (in this case, returns 0 or 1). So we give A a 50% chance of being rock, and the same for C. If we made both A and C rock, we force B to be floor, otherwise we use a subst that gives B the same 50% chance of being rock. You can conditionalise on various factors, such as player experience level: NAME: condition_002 DEPTH: 1-27 ORIENT: float : if you.xl() > 18 then MONS: greater mummy : else MONS: deep elf priest / deep elf sorcerer / deep elf demonologist : end MAP xxxxxx x1...x x1...+ x1...x xxxxxx ENDMAP Or based on where the map is being generated: NAME: condition_003 DEPTH: Elf:*, Orc:* ORIENT: float : if you.branch() == "Orc" then MONS: orc priest, orc high priest : else MONS: deep elf priest, deep elf high priest : end MAP xxxxxx x1...x x2...+ x1...x xxxxxx ENDMAP When conditionalising maps, remember that your Lua code executes in two contexts: 1) An initial compilation phase before the game starts. 2) The actual mapgen phase when the dungeon builder is at work. In context (1), you will not get useful answers from the Crawl Lua API in general, because the game hasn't started. This is generally ignorable (as in the case above) because the compilation phase just checks the syntax of your Lua code. If you conditionalise your map, however, you may run into compile failures. Take this variant, which (incorrectly) attempts to conditionalise the map: NAME: condition_004 DEPTH: Elf:*, Orc:* ORIENT: float : if you.branch() == "Orc" then MONS: orc priest, orc high priest MAP xxxxxx x1...x x2.I.+ x1...x xxxxxx ENDMAP : elseif you.branch() == "Elf" then MONS: deep elf priest, deep elf high priest MAP xxxxxx x1...x x2.U.+ x1...x xxxxxx ENDMAP : end This map will break the compile with the cryptic message "Must define map." (to compound the confusion, the line number for this error will be the first line number of the map following the buggy map). This error is because although the map is Elf or Orc only, at compile time, the branch is *neither* Elf nor Orc, so the level-compiler thinks you've neglected to define a map. Lua code can detect the compile phase using crawl.game_started() which returns true only when the player has started a game (and will return false when the map is being initially compiled). For more details on the available Lua API and syntax, see the Lua reference section. J. Validating levels ======================= If you have a map with lots of transforms (SUBST and SHUFFLE), and want to guarantee that the map is sane after the transforms, you can use a validation hook. To take a very contrived example: NAME: contrived_001 PLACE: D:2 ORIENT: float TAGS: no_pool_fixup SUBST: .=.w SUBST: c=x. MAP xxxxxx x{.+.c x..+>x xxxxxx ENDMAP This map has a chance of leaving the player stuck on the upstair without access to the rest of the level if the two floor squares near the doors are substituted with deep water (from the SUBST line), or the 'c' glyph is substituted with rock. Since a cut-off vault is uncool, you can force connectedness with the rest of the level: validate {{ return has_exit_from_glyph('{') }} The has_exit_from_glyph() function returns true if it is possible to leave the vault (without digging, etc.) from the position of the { glyph. (This takes things like the merfolk ability to swim into account, so a merfolk character may see deep water between the stair and door.) The validate Lua returns false (or nil) to indicate that the map is invalid, which will force the dungeon builder to reapply transforms (SUBST and SHUFFLE) and validate the map again. If the map fails validation enough times, the dungeon builder will discard the entire level and retry (this may cause a different map to be selected, bypassing the buggy map). Going back to the example, if you just want to ensure that the player can reach the > downstair, you can use: validate {{ return glyphs_connected('{', '>') }} NOTE: You cannot use the colon-prefixed syntax for validation Lua. If you have a big block of code, use the multiline syntax: validate {{ -- This level is always cool. crawl.mpr("This level is guaranteed perfect!") return true }} K. Portal Vaults ================== Portal vaults are vaults accessed by portals in the dungeon (labyrinths and bazaars are special cases of portal vaults). You can create custom portal vaults in the following steps (no compilation is necessary): * Create a new file name.des in the dat/ folder. Rules: The "name" should be descriptive of the vault you're adding. The "name" should not exceed eight letters. The ending must be "des". * Add "name.des" to the list of local files in dat/clua/loadmaps.lua. * "name.des" should contain a comment at the top, explaining flavour and gameplay goals of the portal vault (and perhaps additional ideas etc.) * Define at least one vault containing the portal (see below). * Define at least one destination map (see below). * Add a short in-game description for the string "desc" (see below) to dat/descript/features.txt. Before going into the details of portal vault creation, some words about their uses: Portal vaults are different from branches in that they are not guaranteed. Also, there is only one go at a portal vault - if you leave, it's gone for good. You can apply special rules to a portal vault, like enforcing maprot. Portal vaults can be particulary thematic, using specialised monster sets, fitting loot, coloured dungeon features etc. Avoid death traps; it is no fun to enter a vault, being unable to leave and be killed outright. In order to provide fun and reduce spoiler effects, randomise. For portal vaults, it is desirable to have several different layouts (ideally each of the maps has some randomisation on its own). Often, it is a good idea to skew the map distribution: e.g. with four destination vaults, weights like 40,30,20,10 might be more interesting than 25,25,25,25. In order to test a portal vault, you can either use PLACE: D:2 for an entry vault, or use the wizard mode command &L for conjuring up the entry. Define a vault to hold the portal itself ---------------------------------------- # Bare-bones portal vault entry NAME: portal_generic_entry TAGS: allow_dup ORIENT: float MARKER: O = lua:one_way_stair { desc = "A portal to places unknown", \ dst = "generic_portal" } KFEAT: O = enter_portal_vault MAP O ENDMAP Portal entries must contain a portal vault entry (enter_portal_vault). This feature must always have a marker that provides the portal with a description ("A portal to places unknown") and a destination ("generic_portal"). In case you want to make sure that the portal vault entry is only used once, you add a TAGS: uniq_BAR line. It should be noted that the label BAR may *not* end in _entry (otherwise the level builder assumes that the vault is a branch entry). If you want the place name displayed while in the vault to be different than the destination name, then you can give one_way_stair() a "dstname" parameter. If you want the place origin for items in a character dump to be different than the default you can give one_way_stair a "dstorigin" parameter (i.e., dstname = "garden", dstorigin = "in the gardens"). If you want the place name abbreviation used when displaying notes to be different than than the default you can use the "dstname_abbrev" parameter. You can dynamically change the origin string using the lua function dgn.set_level_type_origin(), and dynamically change the place name abbreviation with dgn.set_set_level_name_abbrev(). Known portal vault entries will be displayed on the overmap. By default the name shown on the overmap will be the "dstname" parameter, or if that isn't present the "dst" paremeter. It can be set to something else with the "overmap" parameter. A note can be made to accompany the portal's position on the overmap with the "overmap_note" parameter. Bones files for characters killed in the portal vault will normally use an extension derived from the first three letters of the 'dst' property. You can override this by setting the 'dstext' property to your preferred extension. This will produce a portal, but attempting to use it will trigger an ASSERT since there's no map for the destination. So we create a destination map like so: Define a destination map ------------------------ NAME: portal_generic_generic # Tag must match dst value of portal in entry. TAGS: generic_portal allow_dup ORIENT: encompass MONS: ancient lich KFEAT: > = exit_portal_vault MAP xxxxxxxxxxx x111111111x x1A111111>x x111111111x xxxxxxxxxxx ENDMAP Note that the entry point into the map will be a stone arch. You must provide an exit to the dungeon explicitly (KFEAT: > = exit_portal_vault) or the player will not be able to leave. Stairs will not work right in portal vaults, do not use them. You can use multiple maps with the destination tag (generic_portal), and the dungeon builder will pick one at random. The MARKER parameters --------------------- The lines MARKER: O = lua:one_way_stair { desc = "A portal to places unknown", \ dst = "generic_portal" } KFEAT: O = enter_portal_vault ensure that an 'O' glyph will be turned into a portal. Upon leaving the portal vault, you will be placed on its entry which has been turned into a floor. You can turn it into something different (usually an empty stone arch), by adding floor = 'stone_arch' to the lua:one_way_stair parameters. Note that the desc string is what you will see upon examining the portal. The dst string is used for Crawl's right hand stat area; it will show Place: generic portal in the above example. Here is a lost of the parameters that can be used within one_way_stair (taken from icecave.des): desc = "A frozen archway", # description of the portal before entry dst = "ice_cave", # label used for maps and entry vaults dstname = "Ice Cave", # used for PLACE: on the main screen dstname_abbrev = "IceCv", # used in the notes dstorigin = "in an ice cave", # appendix for items picked up there overmap = "frozen archway", # used on the overmap (X) floor = "stone_arch" # feature left after escaping the portal The dst string is also used to link the destination maps to the entry maps. In case dstname is missing, dst will be used. You can replace lua:one_way_stair by lua:timed_marker in order to make timed portal vaults (which will disappear after some time). bazaar.des and lab.des contain examples. For timed portals, you may want to add messages to the file dat/clua/lm_tmsg.lua. Using lua functions as shortcuts -------------------------------- If you are making several entry and destination vaults, you will note a lot of duplicated header statements. This can be lessened using lua. Define a lua block right at the top (after your comments) as follows: {{ function generic_portal(e) e.marker([[O = lua:one_way_stair { desc = "A portal to places unknown", dst = "generic_portal", floor = "stone_arch" }]]) e.kfeat("O = enter_portal_vault") e.colour("O = magenta") end }} Instead of the MARKER and KFEAT lines introduced above you now just use :generic_portal(_G) and the resulting portal glyphs will even be magenta! Defining a random monster set ----------------------------- Portal vaults require a defined random monster set to make the Shadow Creatures spell work. This is done by calling dgn.set_random_mon_list() manually. Here's an example from ice_cave_small_02 in icecave.des: : dgn.set_random_mon_list("ice beast w:90 / ice dragon / nothing") You can use "nothing" to have the spell fail sometimes. If you are using the same random monster list in several destination maps, you can define a lua block and call it from the destination map definition. This example is from sewer.des: {{ function sewer_random_monster_list(e) e.set_random_mon_list("giant bat w:20 / giant newt w:20 / small snake / \ ooze / worm / snake / giant mosquito w:15") end }} You can then use this line in the map definition to execute the lua block: : sewer_random_monster_list(_G) You can also set env.spawn_random_rate() to have monsters generated from the list during play. Milestones for portal vaults ---------------------------- This example is from icecave.des, defined in the lua preludes: {{ function ice_cave_milestone(e) crawl.mark_milestone("br.enter", "entered an Ice Cave.") end }} The function is called from each of the destination map definitions: : ice_cave_milestone(_G) This marks down entering the portal vault in the milestones. When the portal is entered, the destination map is chosen and the call to crawl.mark_milestone is executed along with the rest of the map definition. Adding milestones in a .des does have the slight catch of creating multiple milestones if the map fails validation for some reason, so it's best used in maps that will never fail validation. L. Lua reference =================== How maps are processed ---------------------- Under the hood, Crawl translates everything in a .des file to Lua. You don't need to know what the underlying Lua looks like to design levels, but it helps. Crawl uses Lua 5.1 from http://www.lua.org (the site has information on the Lua language). Let's examine how Crawl converts a map definition into Lua code with an example map: NAME: statue_in_pool TAGS: no_rotate no_pool_fixup : if you.absdepth() < 7 then MONS: plant : else MONS: oklob plant : end MAP 1...1 .www. .wGw. .www. 1...1 ENDMAP Crawl will convert this map into the following Lua code, wrapped in an anonymous function (this is called a Lua chunk): function () tags("no_rotate") tags("no_pool_fixup") if you.absdepth() < 7 then mons("plant") else mons("oklob plant") end map(".....") map(".www.") map(".wGw.") map(".www.") map(".....") end If your level defines prelude or validation Lua code, such code is extracted into separate prelude and validation chunks. The prelude and validation chunks are empty unless specified. Apart from the special NAME map header, every map header translates to a Lua function with the same name in lowercase. For instance, KFEAT: is translated into kfeat(""). If you have a space or comma separated list (such as TAGS, MONS, ITEM, etc.), then each space/comma separated item is passed into a separate call to the corresponding Lua function. For instance: TAGS: no_rotate no_pool_fixup -> tags("no_rotate") tags("no_pool_fixup") MONS: orc, gnoll -> mons("orc") mons("gnoll") Knowing what the generated Lua looks like under the hood is useful because it allows you to extract repeated boilerplate in similar vaults into a Lua function in the .des file's prelude. For instance, if you were planning to write a whole slew of vaults featuring statues in water guarded by plants, you could extract the common code into the top of the .des file as: # This block has to be placed before any other vault in the .des file. {{ function statue_pool_map(e) e.tags("no_rotate") e.tags("no_pool_fixup") if you.absdepth() < 7 then e.mons("plant") else e.mons("oklob plant") end end }} NAME: statue_in_pool # Pass in the Lua environment global _G to the prelude function. : statue_pool_map(_G) MAP 1...1 .www. .wGw. .www. 1...1 ENDMAP You can also use arbitrary Lua directly in vault definitions, which is handy when randomizing things: NAME: statue_in_pool : local plant_weight = crawl.random_range(1,10) : mons("plant w:" .. plant_weight .. : " / oklob plant w:" .. (10 - plant_weight)) MAP 1...1 .www. .wGw. .www. 1...1 ENDMAP How Lua chunks are associated with a C++ map object --------------------------------------------------- A map's Lua chunk consists of calls to functions such as tags(), mons(), etc. These functions are defined in the dgn table (see the Lua API reference below), and they expect to act on an instance of Crawl's C++ mapdef object. Given: tags("no_rotate") the actual Lua call needs to be: dgn.tags(, "no_rotate") Where is the C++ map object to which the tag should be added. Since calling dgn.(, ) is tedious, dat/clua/dungeon.lua wraps the Lua chunk for the map into an environment that defines wrappers for all the functions in 'dgn' as: function (...) dgn.(, ...) end i.e. for every function in the 'dgn' table, we define a new function that just calls dgn.() with the current map as the first parameter, and the other parameters as passed in. Thus Lua code that you write as: tags("no_rotate") is translated to the correct dgn.tags(, "no_rotate"). While this is done automatically for map code, if you need to call Lua code that was not defined in the scope of the map, as in the example statue_pool_map() function, you need to pass in the map environment to that function if you want it to modify the map. Thus the call to statue_pool_map looks like: : statue_pool_map(_G) Steps involved in processing .des files --------------------------------------- * Level files are compiled into a series of Lua chunks. Each map can have one or more Lua chunks associated with it: the prelude, the body, and a validation chunk. The body is mandatory, but validation and prelude chunks are necessary only if your map needs validation or fancy selection criteria. * When first compiling a .des file, Crawl compiles each map's Lua chunks, then compiles and runs the prelude, body and validation immediately to verify that the Lua code is not broken. Lua errors at this stage will cause Crawl to exit with an error message (hopefully relevant). Note that the validation Lua chunk's return code is completely ignored at this stage - it is only run to check for syntax errors in the code. * When a new game is started, Crawl will run the Lua preludes for all maps (most maps should have no prelude - map preludes slow the game down). At this point, preludes can change the map's placement or availability. * When the dungeon builder selects a map (based on TAGS, DEPTH, PLACE), it re-runs the map prelude and the map body, applies transforms (SUBST, SHUFFLE) if any, then calls the map's validation Lua. If the map passes validation, the dungeon builder continues with level-generation; otherwise, it restarts from the map prelude. The global prelude ------------------ Every .des file can have (at the start of the file) Lua code that is not associated with any specific map, but with all maps in the file. This is called the global prelude. The global prelude is run before running any other Lua code in the file, once during compilation, and once at start of game. You can use the global prelude to define functions and set up globals that the rest of the maps in the .des file use. If you have a lot of common code, you should probably add it to dungeon.lua instead. Syntax for using Lua in .des files ---------------------------------- * Colon-prefixed lines are individual Lua lines, extending to the end of the line. E.g. : crawl.mpr("Hello") Colon-prefixed lines are always in the main Lua chunk, unless they occur before any map definitions, in which case they go to the global prelude. * Lua blocks for the main (body) Lua lua {{ }} or lua {{ }} The "lua" word is optional; you can also use: {{ }} and {{ }} NOTE: Colon-prefixed lines, or lua {{ }} blocks defined before any map's NAME: directive will add the Lua code to the global prelude. * Lua blocks for the prelude: prelude {{ }} or prelude {{ }} * Lua blocks for the validate chunk: validate {{ }} or validate {{ }} Debugging Lua ------------- Since Lua action happens in the guts of Crawl, it can be hard to tell what's going on. Lua debugging involves the time-honoured method of peppering your code with print statements: * Use error() or print() for compile-time work (i.e. when Crawl reads the .des file). Note that print() just writes to the terminal and keeps going, while error() forces Crawl to exit immediately (at compile time; errors during level-generation are handled differently). * Use crawl.mpr() for output when the game has started (at level-generation time). It's very important that your finished level never croaks during level-generation. A Lua error at this stage is considered a validation failure. Special dungeon-related Lua marker properties --------------------------------------------- There are several properties a Lua marker can have which will affect the dungeon cell which they are on: * connected_exclude: Consider the cell to be separate from neighboring cells with identical or similar features. Currently only useful for preventing adjacent doors from grouping together into a gate, forcing them to open and close as separate doors. See the Evil Zoo (minivault_9) in dat/mini.des for an example. * door_description_prefix: A string to prepend to the description of any door the marker is on. This should be used for doors rather than the feature_description property since it elemintates the need to track if the door is opened or closed, plus it will have no effect on secret doors which have yet to be detected. * door_description_suffix: A string to append to the description of any door the marker is on. This should be used for doors rather than the feature_description property since it elemintates the need to track if the door is opened or closed, plus it will have no effect on secret doors which have yet to be detected. * door_open_prompt: If placed on top of a door, the use will be prompted before opening the door, with the value of the property used as the prompt string. * feature_description: What to use as the short description of the cell's feature. * feature_description_long: What to use as the long description of the cell's feature. * stop_explore: If set to anything, and placed on a cell with a statue or orcish idol, will cause auto-explore to stop with the message "Found ." * stop_explore_msg: Like stop_explore, but when auto-explore is stopped the content of the property will be printed out as a message. * veto_disintegrate: If this property is set to "veto" then the cell will be immune to disintegration. * veto_fragmentation: If this proprety is set to "veto" then the cell will be unaffected by fragmentation (Lee's Rapid Deconstruction spell). * veto_shatter: If this property is set to "veto" then the cell will be unaffected by the Shatter spell. Special monster-related Lua marker properties --------------------------------------------- Using the MonPropsMarker allows you to permanantly alter or mark a monster that the marker is placed upon. The options currently available are: * description: If this property is set, the monster's full description (accessed via the 'xv' command) will be set to whatever string you pass it. * quote: Setting this property to a string will set the monster's quote. * monster_dies_lua_key: If this property is set to a function, that function will be executed upon the monster's death. * speech_key: This will override the initial key searched for in the speech database. Setting this to "Edmund", for example, will give the relevant monster Edmund's speech. * speech_prefix: This allows a single prefix to be added to the prefixes list. These prefixes can be used to adjust monster speech dependant on circumstances. An example of MonPropsMarker to replace the description and quote of a monster: MARKER: 8 = lua:MonPropsMarker:new {description="What a horrible sight!\n", \ quote='"They were filled with fear!'\n"} Lua API reference ----------------- a. The Map. b. Global game state. c. Character information. Lua API - the Map ----------------- Lua functions dealing with the map are mostly grouped under the "dgn" module. For convenience, .des file Lua chunks are run in an environment such that function calls written as: fn(x, y, ...) are translated to dgn.fn(map, x, y, ...) where "map" is the reference to the map that the currently executing Lua chunk belongs to. This is only for Lua chunks that belong to a map, Lua code in the global prelude does not get this treatment (because the global prelude is not associated with any map). Functions in the dgn module: default_depth, name, depth, place, tags, tags_remove, chance, weight, orient, shuffle, shuffle_remove, subst, subst_remove, map, mons, item, kfeat, kitem, kmons, grid, points_connected, gly_point, gly_points, original_map, glyphs_connected, orig_glyphs_connected, orig_gly_point, orig_gly_points, load_des_file, feature_number, feature_name, dgn_event_type, register_listener, remove_listener, remove_marker, num_matching_markers, feature_desc, feature_desc_at, item_from_index, mons_from_index, change_level_flags, change_branch_flags, set_random_mon_list Additionally, the dgn module provides a global "mapgrd" variable that can access the current map glyphs. The top left symbol in the map can be assigned like this: mapgrd[1][1] = 'x' The bottom right symbol can be assigned like this: mapgrd[width()][height()] = "." Lua API - global game state --------------------------- The "crawl" module provides functions that describe the game state or provide utility methods. mpr, mesclr, random2, coinflip, one_chance_in, redraw_screen, input_line, c_input_line, getch, kbhit, flush_input, sendkeys, playsound, runmacro, bindkey, setopt, msgch_num, msgch_name, regex, message_filter, trim, split, game_started, err_trace, args, mark_milestone Lua API - character information ------------------------------- The "you" module provides functions that describe the player character. turn_is_over, spells, abilities, name, race, class, god, hp, mp, hunger, strength, intelligence, dexterity, xl, exp, res_poison, res_fire, res_cold, res_draining, res_shock, res_statdrain, res_mutation, res_slowing, gourmand, levitating, flying, transform, stop_activity, floor_items, where, branch, subdepth, absdepth M. Feature Names ================== These are the feature names usable in MARKER declarations: unseen, rock_wall, stone_wall, closed_door, metal_wall, secret_door, green_crystal_wall, orcish_idol, wax_wall, permarock_wall, silver_statue, granite_statue, orange_crystal_statue, statue_reserved_1, statue_reserved_2, lava, deep_water, shallow_water, water_stuck, floor, exit_hell, enter_hell, open_door, trap_mechanical, trap_magical, trap_iii, undiscovered_trap, enter_shop, enter_labyrinth, stone_stairs_down_i, stone_stairs_down_ii, stone_stairs_down_iii, escape_hatch_down, stone_stairs_up_i, stone_stairs_up_ii, stone_stairs_up_iii, escape_hatch_up, enter_dis, enter_gehenna, enter_cocytus, enter_tartarus, enter_abyss, exit_abyss, stone_arch, enter_pandemonium, exit_pandemonium, transit_pandemonium, builder_special_wall, builder_special_floor, enter_orcish_mines, enter_hive, enter_lair, enter_slime_pits, enter_vaults, enter_crypt, enter_hall_of_blades, enter_zot, enter_temple, enter_snake_pit, enter_elven_halls, enter_tomb, enter_swamp, enter_shoals, enter_reserved_2, enter_reserved_3, enter_reserved_4, return_from_orcish_mines, return_from_hive, return_from_lair, return_from_slime_pits, return_from_vaults, return_from_crypt, return_from_hall_of_blades, return_from_zot, return_from_temple, return_from_snake_pit, return_from_elven_halls, return_from_tomb, return_from_swamp, return_from_shoals, return_reserved_2, return_reserved_3, return_reserved_4, enter_portal_vault, exit_portal_vault, altar_zin, altar_shining_one, altar_kikubaaqudgha, altar_yredelemnul, altar_xom, altar_vehumet, altar_okawaru, altar_makhleb, altar_sif_muna, altar_trog, altar_nemelex_xobeh, altar_elyvilon, altar_lugonu, altar_beogh, fountain_blue, fountain_sparkling, fountain_blood, dry_fountain_blue, dry_fountain_sparkling, dry_fountain_blood, permadry_fountain N. Map Statistics =================== Full-debug Crawl builds (this does not include normal Crawl builds that have wizard-mode - you must build Crawl with "make debug", not "make wizard") can produce map generation statistics. To generate statistics, run crawl from the command-line as: crawl -mapstat This will generate 100 Crawl dungeons and report on the maps used in a file named "mapgen.log" in the working directory. You can change the number of dungeons to generate: crawl -mapstat 10 Will generate 10 dungeons. If you merely want statistics on the probabilities of the random map on each level, use: crawl -mapstat 1 O. Map Generation =================== Full-debug Crawl builds (see above for more information) include a test for generating specific vaults and outputting a copy of the map to a text file for inspection (you can also define the macro DEBUG_TESTS on an ordinary debug build, like "make EXTERNAL_DEFINES=-DDEBUG_TESTS wizard"). This is most useful for portal and other encompass vaults which use randomisation heavily. To use the test, you must edit source/test/vault_generation.lua. Fill in the following variables: * map_to_test: The exact name of the vault you want to generate. * checks: How many times to generate the vault. Default value is 10. * output_to: The basic filename to output the results of generation to. This will have "." appended. For example, "volcano.map" will result in files named "volcano.map.1", "volcano.map.2", etc. * need_to_load_des: If the file is not included in one of the .des files that are listed in source/dat/clua/loadmaps.lua, this should be set to true, and the following variable should be set. * des_file: The name of the file to load. The file should be located in the source/dat folder. Once you have saved your changes, run crawl: crawl -test vault_generation Once all of the tests have been finished successfully you should find the relevant files in your working directory.