----------------------------------------------- How to make levels for Dungeon Crawl Stone Soup ----------------------------------------------- Part III: Advanced Methods ================ Contents: I. Conditionalising levels J. Validating levels K. Vetoing levels L. Abyss vaults M. Portal vaults N. Lua reference O. Lua hooks P. Map statistics Q. 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. There are a number of caveats that go with phase 1. You can detect this phase by using the `is_validating()` call or an `e.is_validating()` call where `e` is the current map (`_G`). 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). In phase (1), you should avoid conditionals that impact tags randomly, and if you are using any form of tag randomization, wrap it in a validating check. For example: : if not is_validating() and crawl.coinflip() then TAGS: no_pool_fixup : end See `rng_guidelines.md` for more details on this particular caveat. 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. Vetoing Levels =================== Similarly to validating a level post-placement, it is possible to veto placement of a map before it is even considered. This can be especially useful if, in the example of due_tower_of_silence, you don't want a unique-specific map to be placed if that unique has already been placed by another map. Veto blocks, however, use the inverse logic to validate blocks: if a veto block returns true, the map will not be placed, otherwise placement will continue as normal. For example: veto {{ if you.uniques("Jory") then return true else return false end }} In the event that a map that has been chosen via a PLACE tag is vetoed, and there are no other suitable maps to replace it as a primary vault, then the dungeon builder will fail to generate a level for that place. This will cause the game to close. Do not use veto chunks with vaults tagged with PLACE unless you are absolutely certain this will not happen. L. Abyss Vaults ================= Abyssal vaults have more limitations than vaults in the regular dungeon, because the Abyss is constantly shifting under the player. Normal abyss vaults can be assigned a DEPTH tag as with other branches; it picks vaults tagged "abyss_rune" for abyssal rune vaults and vaults tagged "abyss_exit" for abyssal stairs and exits. When designing abyssal vaults, keep in mind that: a. Abyssal vaults must be small: no larger than 28x23. 23x23 or smaller vaults are best so that they can be rotated and fit in anywhere on the level. b. Unique vaults (vaults without the "allow_dup" tag) are tracked separately for the abyss, so if a map's DEPTH spec allows it to place both inside and outside of the abyss, it may appear up to two times even if unique. The same applies to unique tags. c. The player may never get a chance to explore unique abyss vaults. The player may be teleported away to a different area of the abyss, or never notice your vault before it shifts away. Unique vaults that the player never sees will be reused by the abyss builder, but it is still possible for the player to see an outer wall of your vault and not notice it, or for the player to try to explore it and be teleported away by the abyss before they can finish exploring it. Once any square of a unique vault has been seen by the player in the abyss, that vault cannot be reused within the abyss. d. Timers and other listeners in an abyssal vault may be discarded at any time when the abyss shifts and the vault is destroyed. You can still use timers to modify your vaults, but be aware that the timer may be removed at any time as the abyss shifts away from your vault. M. Portal Vaults ================== Portal vaults are branches accessed by portals in the dungeon. You can create custom portal vaults in the following steps (note that compilation is necessary), assuming that you want to call your new portal "NewPortal" for whatever reason: * Create a new file newportal.des in the dat/portals/ folder. * "newportal.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 branch to dat/descript/branches.txt * Add code for the branch in branch-data.h, like so: { BRANCH_MYPORTAL, NUM_BRANCHES, -1, -1, 1, 14, BFLAG_NO_XLEV_TRAVEL | BFLAG_NO_ITEMS, DNGN_ENTER_MYPORTAL, DNGN_EXIT_MYPORTAL, "NewPortal", "an awesome portal place", "NewPortal", nullptr, BLUE, BLUE, '7', 0 }, * Add code for the entrances and exits to feature-data.h, like so: PORTAL_ENTRANCE(DNGN_ENTER_MYPORTAL, "awesome portal in", "enter_newportal", BLUE), PORTAL_EXIT(DNGN_EXIT_MYPORTAL, "awesome portal out", "exit_newportal", BLUE), * Add BRANCH_MYPORTAL, DNGN_ENTER_MYPORTAL, and DNGN_EXIT_MYPORTAL to enum.h in the appropriate places (copy and paste from another portal vault is fine for this). Before going into the details of portal vault creation, some words about their uses: Portal vaults are different from other 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 particularly 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 KFEAT: O = enter_newportal # name defined in feature-data.h MAP O ENDMAP 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). 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 DEPTH: NewPortal # name defined in branch-data.h TAGS: allow_dup ORIENT: encompass MONS: ancient lich KFEAT: > = exit_newportal # name defined in feature-data.h 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_newportal) or the player will not be able to leave. Simple stairs will not work right as exits. You can use multiple maps with DEPTH: NEWPORTAL, and the dungeon builder will pick one at random. Defining a random monster set ----------------------------- Portal vaults may use 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("bat w:20 / frilled lizard w:20 / small snake / \ ooze / worm / snake / vampire 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. You can also edit mon-pick-data.h, but that is more complicated, and not necessary if you have a random monster list set in the vault. N. 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 anonymous functions (an anonymous function that takes no parameters is called a Lua chunk): function mapchunk() map("1...1") map(".www.") map(".wGw.") map(".www.") map("1...1") end function main() tags("no_rotate") tags("no_pool_fixup") if you.absdepth() < 7 then mons("plant") else mons("oklob plant") end end You'll notice that these functions are not actually anonymous, but they're named just to distinguish them. 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 You can check what Lua code is produced when a .des file is compiled by starting Crawl with the -dump-maps option: ./crawl -dump-maps -builddb 2>compiled-maps.lua This will only produce output for .des files that are compiled, so if Crawl has already compiled all .des files it will produce no output. You can force Crawl to recompile a .des file by updating its modification time or by deleting the $SAVEDIR/des directory. Also note that Crawl writes -dump-maps output to stderr, not stdout, hence the use of 2> for redirection. 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/dlua/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 neighbouring 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. For a more powerful version, you can use set_feature_name() instead. * door_description_suffix: A string to append to the description of any door the marker is on. * 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. * door_description_adjective: Overwrite the adjective for the door. Not currently used. * door_description_noun: Overwrite the noun used by the door. Replaces, for instance, "door" with "doorway". * door_description_veto: Vetoes the use of "open", "closed" and "runed" when applying adjectives to door descriptions. * door_berserk_verb_open: Replace the verb used for opening the door while berserk. Should include "%s%s", as it is printed as a formatted string. * door_berserk_adjective: Replaces the adjective "with a bang" when the player is not silenced while opening a door. * door_noisy_verb_open: Replaces "opens with a creak". Also requires "%s%s" as it is a formatted string. * door_airborne_verb_open: Replaces "reach down and open", also requires "%s%s". * door_open_verb: Replaces "You open". Also requires "%s%s". All of the above "open" have "close" counterparts which are used when closing a door. * 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 property 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. * veto_fire: If this property is set to "veto" then the cell will be unaffected by any fire spells. Special monster-related Lua marker properties --------------------------------------------- Using the MonPropsMarker allows you to permanently 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. * shout_func: If this property is set to a function, that function will be called if the monster shouts, and the string returned by the function will be used as the text of the message. Can return "__NONE" to make the monster not shout, or "__NEXT" to proceed as if there was no speech_func property. * speech_func: If this property is set to a function, that function will be called if the monster speaks, and the string returned by the function will be used as the text of the message. Can return "__NONE" to make the monster not talk, or "__NEXT" to proceed as if there was no speech_func property. * 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"} Note that all of the speech related properties will be reset if the monster polymorphs. 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, 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[0][0] = 'x' The bottom right symbol can be assigned like this: mapgrd[width()-1][height()-1] = "." 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_mutation, res_slowing, gourmand, levitating, flying, transform, stop_activity, floor_items, where, branch, subdepth, absdepth Lua API - colour definitions ---------------------------- The "colour" module provides functions for defining new colour patterns. add_colour O. Lua hooks =============== When the dungeon builder places a vault, it runs hooks at certain steps during vault building. These hooks are: 1. pre_main: This hook is called just before the main chunk's Lua code is called. 2. post_main: This hook is called just after the main Lua code is called. 3. post_place: This hook is called after the vault has been placed, and before the dungeon builder continues with level-generation, i.e. during level-generation time. 4. pre_epilogue: This hook is called just before the epilogue code is run. Note that by the time epilogues run, level generation is complete. 5. post_epilogue: This hook is called after the epilogue code is run. You may also specify hooks as "main", "place", "epilogue", which will select the post_XXX hook. i.e. using "main" as the hook name is the same as writing "post_main". Hooks may be global, in which case they're fired for all vaults placed, or may be specific to a map. Global hooks must be defined in a Lua file, or in a .des file's global prelude. You may use the post_place hook to take an action immediately after a vault is placed successfully. For instance, if you're designing a vault (star) that should always be accompanied by several other vaults (fan), then you might write it as: NAME: star PLACE: D:2 {{ hook("post_place", function() -- Place ten instances of vault(s) tagged "fan" dgn.place_maps{tag="fan", count=10} end) }} MAP *** *** ENDMAP NAME: fan # Must be allow_dup since 10 instances will be used. TAGS: fan allow_dup MONS: human MAP 1 ENDMAP Using global hooks affects every vault, so they should be used very sparingly. Global hooks must be defined in Lua files, or in .des files' global preludes (i.e. before any map definitions). As an example, here's a frivolous global hook to place a pile of gold on each floor square in vaults: {{ dgn.global_hook("main", function () kitem(". = gold") end) }} Note the use of the "main" hook in this example instead of "post_place". "post_place" is too late to modify the vault definition, since the vault is already placed at that point. Errors in hooks --------------- Errors in hooks will usually be ignored by the level builder, although errors will still be displayed to the end user. The only exception is the "post_place" hook -- errors in the post_place hook will cause the dungeon builder to veto its current level and retry level generation. P. Map Statistics =================== Full-debug Crawl builds (i.e., ones built with "make debug") 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 You can instead limit the levels to operate on by providing a comma separated list of level ranges, with same syntax as in DEPTH: stanzas: crawl -mapstat D:15,Zot,!Zot:5 Mapstat tends to take large amounts of time, so remember you can have optimized debug builds by 'make debug CFOPTIMIZE="-Ofast"' if you're not after backtraces (mapstat is quite good for finding map generation crashes). CFOPTIMIZE is also a good place for inserting -pg into. Q. Map Generation =================== Full-debug Crawl builds (see above for more information) include a script that can attempt to generate vaults either singly or in bulk, and test placement conditions. This can be useful for finding closets, among other things, especially in heavily randomized vaults. This script must be run under the fake_pty utility (`make util/fake_pty` to ensure it is built.) To see all command line options, run: util/fake_pty ./crawl -script placement.lua --help An example use case is: util/fake_pty ./crawl -script placement.lua minmay_nonomino_d4 -count 10 -dump This command tries to place the vault `minmay_nonomino_d4` 10 times, generating an ascii output file for each placement. If any of these times generate a placement issue, an error will be shown as part of the command output. For example (this bug is long fixed): Testing map 'minmay_nonomino_d4' Failing vault output to: placement-minmay_nonomino_d4.10.txt script error: ./scripts/placement.lua:184: Isolated area in vault minmay_nonomino_d4 (2 zones) The indicated output file could then be expected to try to identify the placement error. This script supports a number of other modes, and can be run on large batches of vaults at once; see the `--help` output for more information. This script does not handle encompass vaults.