-----------------------------------------------
How to make levels for Dungeon Crawl Stone Soup
-----------------------------------------------

Part I:    INTRODUCTION
           ============

Contents:  A. Introduction
           B. Sample map
           C. The .des files
           D. Kinds of vaults
           E. Hints for level makers
           F. Principles of vault making
           G. How vaults are picked

This document explains some basics of vault making. For actual vault work,
you will need to look at syntax.txt. However, by simply looking at the
example provided here and looking through arrival.des, you should be able
to make changes or small vaults on your own.


A.   Introduction
=================

A game like Crawl generally uses random content. This also applies to maps,
which are made in various ways, but all with a large random component.
However, for several reasons, it is also useful to have handmade maps: they
can provide challenges random levels would rarely come up with; they can be
especially thematic, for example on branch ends. Simple pre-made pieces of
maps are called "vaults", these can provide challenge, loot, flavour or
just make the rather big levels of Crawl more interesting.

These vaults come in all sizes, from mere 3x3 to level encompassing maps.
Section B contains an example vault (not to be used somewhere), giving you
an idea of how vaults are defined.

Since predefined and fixed content clashes with the philosophy of randomly
generated content, vaults can be randomised in many ways. The other way to
help lessen the effect of deja vu is by having lots of vaults. Therefore,
new vaults are always appreciated.


B.   Sample Map
===============

Before going into the technical details of the level-file syntax, it might be
a good idea to look at an example - a branch entry for the Ecumenical Temple -
to see what a map definition looks like.

# name below:
NAME:    useless_temple_entry
# header section below:
TAGS:    temple_entry
ORIENT:  float                    # "ORIENT: float" tells the level builder that
                                  #     this entry can be anywhere on the level.
MONS:    butterfly, plant
ITEM:    stone q:1
KFEAT:   O = enter_temple
# actual map below:               # The symbols on the map:
MAP                               # x - rock wall
xx.d.xx                           # . - floor
x..1..x                           # @ - entry point (
@d2O2d.                           # O - stairs to the Temple
x..1..x                           # 1 - first monster from list (here butterfly)
xx.d.xx                           # 2 - second monster from list (here plant)
ENDMAP                            # d - first item from the list (here stones)

Every map consists of a name, a header and the actual map (the order is not
important as long as the name comes first, but try to stick to this order for
consistency).

Lines starting with # are comments. The keywords available are explained
in detail in the syntax.txt file.


C.   The .des files
===================

All fixed level information resides in various .des files to be found inside
folders of the dat/des directory. If you are interested in adding some vaults,
say, start with the existing ones and modify them. If you are new to vault
making, look at the following files:

  dat/des/arrival
    simple.des - particularly simple arrival vaults; they are ordered with
                 learning the map syntax in mind (all games use a premade
                 map like these for the vicinity of the entrance)

  dat/des/variable
    float.des - floating vaults
    large_abstract.des - all regular vaults which have
    large_themed.des   - ORIENT:encompass/northwest etc
    mini_monsters.des  - minivaults with monsters (no ORIENT line at all)
    mini_features.des  - minivaults without monsters (still no ORIENT line)

There are also the following other directories:

  dat/des/branches - contains vaults for specific branches
  dat/des/portals  - contains all maps and lua for portal vaults
  dat/des/builder  - layouts, uniques, etc.; only touch shops.des!

If you feel comfortable with vault making in general, you may want to turn to
branch ends or even portal vaults. Poke into the relevant files to get an
impression, or to find examples of how lua is applied.


D.   Kinds of Vaults
====================

The different kinds of vaults used by Crawl are described below.

Arrival vault:
    A map designed for D:1, which (usually) contains the primary upstair {
and is always tagged "arrival". A player starting a new game will usually
land in an entry vault.

Branch entry vault, or branch portal vault:
    A map containing the entry to a branch - either a branch stair (such as
the stair to the Orcish Mines), or a branch portal (a portal to Hell, say).
Always tagged "<branchname>_entry".

Special level:
    A map for a location of significance in the game, such as the Ecumenical
Temple, or the end of branches such as level 5 of the Snake Pit (Snake:5).
Special level maps usually have a PLACE: attribute.

Random vaults:
    Random vaults may be randomly generated at any level in the dungeon.
Random vault maps are selected by the dungeon builder based on their DEPTH:
attributes.

Random minivaults:
    Random minivaults are small maps that are placed onto a level that the
dungeon builder has already constructed fully otherwise (the level may
include other vaults).

Minivaults are distinguished from normal vaults by the absence of an
ORIENT: declaration. Any map without a specified ORIENT: is a
minivault. Minivaults are handled like floating vaults (ORIENT: float
vaults) in most respects. The differences are:

1. Floating vaults may be placed before the rest of the level layout
   is generated, and the rest of the level may be built around the floating
   vault. This is never the case for minivaults.

2. Floating vaults may be placed anywhere in the map, including places
   completely separated from the rest of the level by rock. The
   dungeon builder will then connect the exits from the floating vault
   to the rest of the level, readily producing obvious "passages" from
   the floating vault to the main body of the level.

   In contrast, minivaults are placed such that at least one square of
   the minivault overlaps with an existing part of the level, and are
   thus more likely to look like part of the level.


E.   Hints for level makers
===========================

Stairs
------
You do not have to place all of the stairs unless the level is full
screen, in which case you must place all except the extra stairs (these
are glyphs > and < and produce escape hatches). Any of the other stairs
which are not present in the vault will be randomly placed outside it.

Also generally try to avoid rooms with no exit (you can use > or < to
make it possible for players to get away, although there are other,
more elaborate options like teleportation traps, etc.). However, unless
needed for the purpose, escape hatches are generally not interesting.
If you do use them, > is almost always better than <.

Entry points
------------
The entry point '@' must be present for all vaults (except for
full-screen vaults where it must not, and for floating vaults and
minivaults where it is optional). All @ will be connected to floor
space in the rest of the map (multiple @ close together may merge
into the same exit corridor). Make sure that no part of your entry
level can be cut off! If no @ is present in a floating vault (and
there are no doors on the edge of the map, see below), the level
builder will use one or more random floor spaces '.' or doors at the
circumference as exits. Note that it is not possible to predict
which spaces the level builder will choose to connect; if you need
predictability, use explicit @ exits on the edge.

The level-builder will also implicitly treat doors and runed doors
on the edge of a map as explicit exits (the same as using @) and
connect them to the rest of the level.

Not using @ will cause the level builder to pick exits randomly from
non-solid squares on the edge of your vault. You should always either
have explicit exits or accessible squares; if the vault is completely
inaccessible (by exits, non-solid squares that can act as exits, or by
stair), it will fail to load - so don't do that.

Minivaults vs. random vaults
----------------------------
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, although
using a PLACE: attribute makes the dungeon builder try very hard to place
the minivault on the specified level. Regular vaults can always be forced to
appear using a PLACE: attribute.

Technically, you make a minivault like a normal floating vault but
without an ORIENT: line. Note that minivaults used to be exclusively of
size 12x12 but this restriction is gone. Still, the smaller the better.

Where possible, use minivaults instead of regular vaults, because the dungeon
builder has greater freedom with the rest of the level layout when using
minivaults.

levdes.vim
----------
If you use vim, the levdes.vim syntax highlighting script (provided
in the dat directory) can make level-editing far more pleasant by colouring
different features in maps and syntax-highlighting .des-file syntax. vim is
available for nearly all operating systems, including Windows.


F.   Principles of vault making
===============================

Small is good!
--------------

This applies mostly to arrival vaults and minivaults. Especially arrival
vaults should be rather small. Their intention is to provide some
atmosphere for the starting room, not to get a grip on the whole of D:1.
Minivaults should be rather small, as well, in order to increase the chances
they may actually be chosen during level generation.

Randomise!
----------
The level making syntax is very supportive for making a single map appear
in many versions. Use the SHUFFLE:, SUBST:, and NSUBST: directives, and
look at the existing arrival vaults. Besides reducing tedium, this avoids
giving veterans a spoiled edge. As an example, if a chamber with loot, the
staircase to another level, or a good chokepoint to fight in are always
put in the same place, it's a no-brainer for those who know. This is much less
so if there are several places for such to exist and also if there's even a
chance such doesn't exist.

If you can't use SHUFFLE and CLEAR to merge map shapes together, you may also
rarely use WEIGHT to create modified versions of the same map. In order to do
this, make several maps and endow each with a weight such that the sum of
weight add up to the default 10.

Randomisation does not just apply to layout: you could also have different
monster population sets (for example make a larger vault skewed for either
melee or ranged opponents), or perhaps couple variable difficulty to variable
loot.

Not too much loot!
------------------
For example, arrival vaults should in general have very little loot - in
particular no good_xxx or '*' items lest they might give incentive for
start-scumming. For random minivaults, there needn't be loot at all and, in
any case, there shouldn't be too much of it. (A small amount of gold, or a few
random floor items, can manage to give off the appearance of some loot without
handing out much power - contrast with the branch ends rich in treasure like
Vaults:5 and Tomb:3 to get a feeling for this.)

It is very easy to fall into the power spiral trap: making newer vaults
harder than the old ones, but handing out more loot. Be strong, don't give in
to that temptation. Later on in the game (post Lair branches), sheer volume of
some item categories (e.g. any weapon, any armour, gold) can provide some of
the spectacle of a large reward pile without actually powering up the player
too much, though some amount of less specific items should still be capable
of providing random genuine loot.

Have a theme (or even two!)
---------------------------
It is often worthwhile to have a theme in mind before making the actual level.
For arrival vaults, something simple like 'forest' or 'fortress' may be a
cliché, but also function fine as potentially some of the first forests and
fortresses a new player may see in the game. Combinations of themes in
particular can help to stand out versus the thousands of vaults already in
Crawl and countless other video games. "A forest's overgrown fortress",
"a flooded library", "a burned-down prison", so on and so forth can imply a
story and history that can sell vaults as more than boxes of monsters and loot.

For later and larger maps, try to think of distinguishing features your map may
have, or a combination of uncommon terrain tiles and cogent monster sets. Being
cool can be good enough, but possessing notable gameplay differences (like
threatening multiple resists, directly helping out support monsters, or giving
big terrain advantages to monsters instead of players) is also quite valuable.

However, while a vault theme can instantly distinguish itself from both other
vaults and the branch it's in to invite monsters from other branches, this
should be done very sparingly depending on the branch.

  * Example branches and portals with many different monster themes:
    Dungeon, Depths, Abyss, Zot, Gauntlet, Necropolis, Wizlabs.
  * Example branches and portals with very narrow monster themes:
    Snake Pit, Spider Nest, Pits of Slime, Elven Halls, Ossuaries, Ice Caves.

The former is less likely to get nearly as much suspicion than the latter; if
every branch contains every monster, then no branch actually stands out on its
own original themes and merits. Some connective themes to the monsters
already available in the branch may help (e.g. other magical constructs in Elf),
but it is better to try and avoid these questions in the first place. If you
want for more ideas on monster fronts (beyond comprehensively checking the
branch population charts in mon-pick-data.h), newer monsters for a branch tend
to far less thoroughly explored than much older monsters - check out the more
recent versions in the changelog to see potential better candidates.

Testing your maps.
------------------
In wizmode, you can use the following commands:
    &L "map name"   (creates that vault on the current level)
    &P "map name"   (creates a level with that vault guaranteed to be in it)
    &~              (for jumping to a branch end).
    &{              (reveals level layout and items)
    &D              (detects all monsters)
    &B              (instantly teleports the player)
For both &L and &P, you don't need to specify the full name of the vault,
a substring which uniquely determines the vault is enough. Using &L is required
for some levels, like Temple maps, but defaulting to &P is usually better
for seeing how the vault mixes with the rest of the layout.

In some contexts, or to rapidly regenerate levels and see how well the vault
connects to the level, it is reasonable to temporarily introduce either
    WEIGHT: 50000   or
    PLACE:  D:1
which will make your vault appear almost always. Be sure to remove this before
submitting the vault.

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.

If the .des file syntax is incorrect, Crawl will tell you on which line of
which des file it found the syntax error, making for easier debugging.

Be fair!
--------
Crawl is hard, but try to balance your monsters. For example, many characters
will see branch entrances long before entering those branches, so it's rather
awkward to place notable branch threats before the player would normally see
them. Orc knights can be found on Orc:1, but orc knights in the entry to the
Orcish Mines are notably much stronger than most other Orc entries.

Phrased more generally, do not use OOD (out-of-depth) monsters unless you
really know what you want. Try to find other vaults placing at the same level
range and tune to around their threat levels.

This also works in the opposite direction, as Crawl has regularly tried to
reduce a fair bit of its previous high levels of weak monsters later in the
game - if a monster is something one would expect to fight as an average threat
ten or more floors ago, it is likely it is no longer much threatening afterwards
for anything beyond flavour. See J. Conditionalising levels in advanced.txt to
adjust a vault's contents versus branch and depth if you want the vault to play
in multiple floors.

Be especially fair when creating arrival vaults, as very few of them manually
place monsters these days. If your vault is too hard, it might get just trashed.
Keep in mind that your vault will be played very very often, so even small
chances of something stupid happening (like creation of a really nasty monster,
or a sudden ambush of too many monsters) will kick in often enough.

Glass, grates, liquids, console recolouring, names: use sparingly!
------------------------------------------------------------------
It can be very tempting to use features with direct gameplay ramifications
to have different gameplay within a vault, but their interruption of regular
gameplay can allow a lot of cheesy luring back and forth that exposes oddities
within Crawl's pathfinding. Many vaults putting decorative monsters behind glass
have been done before, and don't really stand out in-and-of-themselves anymore.
Also, sticking something on an island or behind grates that can't attack back
can allow a player to tediously take them out slowly for free experience and
loot - starting book spells can eventually take down even endgame threats if
lucky enough.

Console's limitations also strongly discourage changing the colours of most
walls or floors. Rock can change between branches and does so regularly, but
this makes it important to not miss if a wall is something else like transparent
stone or crystal. Floor colours, meanwhile, can overlap with monsters with
haloes or umbras. Tiles don't quite have these issues, though tiles used for
other types of wall should always stick to their original wall type.

A long time ago, Crawl had an extreme number of differently named monsters
only used in one vault at a time. They were mostly expunged while we had a far
worse means of finding out what a monster does in-game, but a few have held on
for mostly legacy preservation purposes. Outside of Wizlabs and Sprint,
incredibly few new monsters should threaten the player without being regularly
integrated into the rest of Crawl, as it can add a lot of confusion to see
hyper-rare monsters used in one-off circumstances and rarely warrants such
a particular means of being done.

G.   How vaults are picked
==========================

The dungeon builder selects vaults by:

1. PLACE: Before the dungeon builder starts building a level, it looks
   for non-minivaults that are marked for the same PLACE: and places
   them. After building the level, it looks for minivaults that are marked
   for the same PLACE: and attempts to place them.

2. TAGS: Branch entries, Pandemonium special levels, etc. are placed by
   looking for vaults with a particular tag, for instance "mnoleg".

3. DEPTH: When building a level, the dungeon builder looks for random
   vaults that are eligible to be placed in that DEPTH range.

If you do not want a vault to be randomly generated, give it the "unrand" tag.
This will let the vault still be selected for subvaults and other tag checks.

Vaults without a DEPTH: should be eligible to be selected in some
other way, either by PLACE: or by tag.
