# Guidelines for specific types of vaults 1. [Guidelines for D:1 arrival vaults](#guidelines-for-d1-arrival-vaults) 2. [Guidelines for faded altar and overflow temples](guidelines-for-faded-altar and-overflow-temples) 3. [Guidelines for creating serial vaults](#guidelines-for-creating-serial-vaults) 4. [Guidelines for creating ghost vaults](#guidelines-for-creating-ghost-vaults) 5. [Guidelines for no_tele_into](#guidelines-for-no_tele_into) ## Guidelines for D:1 arrival vaults Arrival vaults should provide atmosphere and a nice starting point. The idea is neither to get a grip on most of D:1 nor to hand out starting gear. Playing Crawl a bit will show you a number of arrival vaults, which live in [crawl-ref/source/dat/des/arrival/](https://github.com/crawl/crawl/tree/master/crawl-ref/source/dat/des/arrival) ### We need more arrival vaults! We love new arrival vaults, and it is easy to make new ones. Coding abilities are not required. If you are completely new to making maps, have a look at simple.des. After that, glance through [crawl-ref/docs/develop/levels/introduction.txt](https://github.com/crawl/crawl/blob/master/crawl-ref/docs/develop/levels/introduction.txt), which will allow you to make your own maps already! Once you are familiar with this, you may look at more complicated vaults and read the more [advanced documentation](https://github.com/crawl/crawl/tree/master/crawl-ref/docs/develop/levels). Crawl also employs vaults in many other places; check the various `.des` files in [crawl-ref/source/dat/des](https://github.com/crawl/crawl/tree/master/crawl-ref/source/dat/des) for what is going on. New maps are always welcome. ### Some guidelines for arrival vault creators * Try to come up with small maps. * Avoid placing guaranteed items. * The same holds for any features which might trigger start-scumming, like altars. * Also avoid ASCII art. It probably won't work in Tiles anyway. * Also avoid monsters-behind-glass-wall vaults. We already have enough of these. * Note that at the start of the game, the dungeon builder removes all monsters in view of the player. Zero experience monsters like plants are exempt. * Arrival vaults should have multiple entry points, escape hatches, or enough space to permit tactics. ### Naming conventions Entry vaults should be NAMEd as follows: ``` NAME: nick_arrival_name ``` where "nick" is the name/nick of the vault designer and "name" is a somewhat descriptive label for the vault. Avoid numbers, please. The actual maps can be found in the following files: | File | Contents | |-------------|--------------------------------| | simple.des | Particularly simple maps: no more than five header lines! | | small.des | Small maps with neither lua nor complicated syntax. | | twisted.des | Maps which either use a lot of lua or heavy `SUBST`ing etc. | | large.des | Sizes of about 30x30 and up. | If a map is both big and complex, file under twisted.des. If a map is both plain and small, file under simple.des. ## Guidelines for faded altar and overflow temples A faded altar vault is placed with very high probability on D:1-3. Overflow temples are specific vaults used by the dungeon builder to guarantee altars to temple gods that did not get an altar in the Ecumenical Temple. In general these should avoid placing significant challenges and leave the altar accessible without need for flight or blinks, as the purpose is to provide the player with a guaranteed altar. Both classes of vaults are seen often in the game and we need a lot of them! These maps are good candidates for a starting vaultmaker who wants to try something other than an arrival vault. For overflow temples, see the comments at the start of [crawl-ref/source/dat/des/altar/overflow.des](https://github.com/crawl/crawl/tree/master/crawl-ref/source/dat/des/altar/overflow.des) for the specific tagging scheme to use for overflow temples, either generic or devoted to particular gods. Ecumenical altars are faded, so the player can't tell which god the altar is devoted to until they worship. Good lore ideas revolve around ruins and decay, but there are plenty of other creative possibilities. The vaults are in [crawl-ref/source/dat/des/altar/ecumenical.des](https://github.com/crawl/crawl/tree/master/crawl-ref/source/dat/des/altar/ecumenical.des) ### General style guidelines for faded altar and overflow temples * Try to come up with small maps. * Avoid placing guaranteed items. * Don't use out-of-depth monsters or a large number of in-depth monsters. * Avoid ASCII art. It probably won't work in Tiles anyway. ### General style guidelines for overflow temples * If your vault places a single specific altar and is a plausible mini vault tag it `uniq_altar_GODNAME` as well as the overflow temple tags * Whenever possible, don't add a depth specification to such a vault. * If a specific monster is necessary for theme, then constrain the vault to that monster's depth. * If your vault is decor (even if it does not have the decor tag, if there are no depth-scaling monsters to fight, and no serious loot), include `: interest_check(_G)` to ensure the vault is tagged appropriately. ## Guidelines for creating serial vaults Sometimes, we want flavour (or also other) vaults to be placed several times, so as to make the level feel more coherent; this is called a **serial vault**. The lua calls for such serial vaults are in the files in the folder [crawl-ref/source/dat/des/serial/](https://github.com/crawl/crawl/tree/master/crawl-ref/source/dat/des/serial). Each serial vault has its own file. The vaults eventually could be just copies of one map, or (much better) come from a list of thematically linked maps. This is mostly for flavour, although it may be interesting to created serial vaults around threats. In general, we don't want more than one serial vault on a level. Use the ``` TAGS: luniq_serial ``` in the serial vault's header map for this. Often, it will be fine to allow the individual maps comprising a serial vault to be chosen by the level builder as usual minivaults. If you want to do that, there are two ways to proceed: * A default-depth line before all maps. * Or non-empty `DEPTH` statements in each map definition. (You can still do * this even if there is a default-depth. It allows you tweak the depths for specific maps.) If you want to disable all or some the maps for from normal minivault placement, you can: * Give them no `DEPTH` line when you have no preceding default-depth. * Explicitly remove them with an empty depth line like this: ``` DEPTH: ``` ## Guidelines for creating ghost vaults Ghost vaults are vaults that place a player ghost, which is an undead monster with properties derived from a player who died. These vaults should place some amount of additional loot to offer some enticement for players where the XP from killing the ghost isn't sufficient reward. Often these vaults place monsters in addition to the ghost. Ghost vaults usually place one ghost, but may less often place multiple ghosts. ### Organization and setup All ghost vaults not placing in the Vaults branch should go in [crawl-ref/source/dat/des/variable/ghost.des](https://github.com/crawl/crawl/tree/master/crawl-ref/source/dat/des/variable/ghost.des) and call the lua ghost setup function the following way: ``` : ghost_setup(_G) ``` This well set the common tags we want for all ghost vaults as well as the common CHANCE to place these vaults, as described in sections below. These vaults can be minivaults or have any of the usual kinds of ORIENT statements. For the Vaults branch, a ghost vault will be a vault room in [crawl-ref/source/dat/des/branches/vaults_room_ghost.des](https://github.com/crawl/crawl/tree/master/crawl-ref/source/dat/des/branches/vaults_room_ghost.des) and it should call the vault lua ghost setup function: ``` : vaults_ghost_setup(_G) ``` This setup will set common tags for ghost rooms and set a `vaults_ghost` tag recognized by the Vaults layout. Vaults calling `vaults_ghost_setup()` do not need to set the `vaults_ghost` tag on their own. ### Basic guidelines Ghost vaults should always be sealed and ideally not diggable by monsters that have a dig wand or the dig spell. This means the vault should have non-rock outer walls and use either runed doors or transporters for entry. The vaults should have transparent walls so that it's always possible for the player to see the ghost before entering, even if the ghost is awake and wandering. For placement in early dungeon levels, relatively less additional loot is necessary, since ghost XP is more impactful then. However it's recommended to place at least some loot in early levels, and more strongly recommended for later depths where ghost XP provides much less incentive on its own. It's fine to place monsters in addition to the ghost monsters; just keep in mind that player ghosts are relatively difficult to kill compared to a large majority of crawl monsters. See the aforementioned [ghost.des](https://github.com/crawl/crawl/tree/master/crawl-ref/source/dat/des/variable/ghost.des) and [vaults_room_ghost.des](https://github.com/crawl/crawl/tree/master/crawl-ref/source/dat/des/branches/vaults_room_ghost.des) for examples and inspiration. ### Distribution The current range of levels that place ghost vaults is: ``` default-depth: D:3-, Lair, Elf, Orc, Snake, Shoals, Swamp, Spider, Depths, \ Crypt, Zot ``` Every ghost vault uses a common chance value defined in [crawl-ref/source/dat/dlua/ghost.lua](https://github.com/crawl/crawl/tree/master/crawl-ref/source/dat/dlua/ghost.lua) that dictates the chance a level will place a ghost vault. This chance is currently 10%. Ghost vaults that call one of the lua setup functions mentioned above will have this chance set automatically and do not need their own CHANCE statement. To make a ghost vault relatively more or less commonly chosen among the set of ghost vaults, use a WEIGHT statement to set a weight other than 10, the default. A vault can use WEIGHT to set different weights for different branches/levels. See examples in [ghost.des](https://github.com/crawl/crawl/tree/master/crawl-ref/source/dat/des/variable/ghost.des) and [syntax.txt](https://github.com/crawl/crawl/tree/master/crawl-ref/docs/develop/levels/syntax.txt). ### Custom Tags If the tags set by `ghost_setup()` or `vaults_ghost_setup()` are somehow not appropriate, ghost vaults can set their own tags instead of calling these functions. For ghost vaults not in the Vaults branch, the vault should at a minimum call the following function to set the CHANCE and set the `chance_player_ghost` tag: ``` : chance_player_ghost(_G) ``` It's strongly recommended that you use this function instead of setting a CHANCE directly in the vault. For ghost vault rooms for Vaults, instead set the `vaults_ghost` tag; these vaults should not have a CHANCE statement at all. Other tags we generally require for ghost vaults are `no_tele_into` and `no_trap_gen`. If you use `allow_dup` in your vault, also use `luniq_player_ghost` to avoid multiple vault placement on the same level. ## Guidelines for no_tele_into The `no_tele_into` KPROP prevents teleports landing you on the tagged locations. Example: ``` NAME: example_vault KPROP: - = no_tele_into SUBST: - = . MAP xxxxxx +.m--x xxxxxx ENDMAP ``` Teleports will never land the player behind the glass wall. Don't overuse this property. It's a hidden mechanic not exposed to the player. Good places to use `no_tele_into`: * Vaults which need the player to enter in a controlled manner to understand/enjoy. For example `gammafunk_steamed_eel`. * Teleport closets: areas the player cannot escape without a scroll of teleportation (or similar). For example `lemuel_altar_in_water`. * Egregiously dangerous/unfair situations. For example `chequers_guarded_unrand_ignorance` (four orange crystal statues). Bad places to use `no_tele_into`: * Any old runed door / transporter vault. It's fine for players to teleport into tough or scary situations. * Islands: areas the player can also reach with flight or similar tools. `no_tele_into` would be an incomplete solution. It's better to place a hatch/shaft, which solves all cases.