Add an autumn forest themed bazaar vault (#551)
[crawl.git] / crawl-ref / docs / arena.txt
1 The crawl arena is a special mode during which the player is absent and
2 monsters fight each other, useful for both testing/debugging and for
3 entertainment. It can be invoked on the command line like this:
4
5     crawl -arena "kobold v goblin"
6
7 Which will cause one kobold to fight one goblin, with crawl shutting down once
8 one of them has won. To be considered valid, a monster's name has to fully
9 match its definition, e.g. "Blork the orc" rather than simply "Blork".
10
11 To make them fight for three rounds you can do:
12
13     crawl -arena "t:3 kobold v goblin"
14
15 You can make monsters fight for at most 99 rounds. You can stop the
16 arena simulation early by pressing Escape, 'q' or Control-G (though if
17 the arena has lots of monsters it might take a few second before it
18 stops).
19
20 You can also give each side more than one monster. For example:
21
22     crawl -arena "rat, giant cockroach v kobold, goblin"
23
24 will give team A a rat and a cockroach and team B a kobold and a goblin; a
25 victory is declared when all of one team is dead and at lest one member of the
26 other team is still alive.
27
28 Some monsters have a band (that is, a group of monsters) that will be
29 generated with them during normal play. You can use the suffix "band" to
30 make a monster appear with its band (if one exists). For example:
31
32     crawl -arena "Margery band v Saint Roka band"
33
34 You can also make multiple of a single type of monster (note that the singular
35 form of the names are still used):
36
37     crawl -arena "2 kobold v 3 goblin:
38     crawl -arena "2 rat, 3 giant cockroach v 4 kobold, 5 goblin"
39
40 You can even have multiple instances of uniques:
41
42     crawl -arena "10 Murray v 11 Boris"
43
44 Additionally, you can specify the monsters by a place in the dungeon, in
45 which case a random monster appropriate for that place will be chosen.
46 For example:
47
48     crawl -arena "2 place:Lair:7 v 3 place:Vaults:4"
49
50 will choose two random monsters from the 7th level of the Lair and pit them
51 against three random monsters from the 4th level of the Vaults.
52 The branches need to use the official abbreviations also used e.g. in the
53 overmap (Ctrl-O): D, Temple, Orc, Elf, Lair, Swamp, Shoals, Slime, Snake,
54 Vaults, Depths, Crypt, Tomb, Hell, Dis, Geh, Coc, Tar, Zot.
55
56 To let the game pick monsters completely at random, use "random" as a
57 monster name. If you use the tag random_uniques all monsters thus chosen
58 will be uniques. For example:
59
60     crawl -arena "random_uniques random v random"
61
62 If you want endless hordes of monsters to kill each other forever you can
63 use the test spawner, an unkillable monster which does nothing but sit there
64 and summon monsters with the Shadow Creatures spell:
65
66     crawl -arena "test spawner v test spawner"
67
68 If you want a *specific* set of monsters to fight each other endlessly,
69 you can use the "respawn" tag, which will cause the initially placed
70 monsters to be replaced when they die. For example,
71
72     crawl -arena "respawn rat v rat"
73
74 will make it so that when one rat dies another takes it's place,
75 resulting in an endless fight between two rats.
76
77                                    Commands
78 ------------------------------------------------------------------------------
79 There are a very limited number of command you can issue to the arena:
80
81 * You can stop the arena simulation early by pressing Escape, 'q' or
82   Control-G.
83
84 * You can look at the message history like in a normal game (Control-P).
85
86 * You can look around the arena like in a normal game ('x').
87
88 * You can suspend the arena like in a normal game (Control-Z).
89
90 If the arena has lots of monsters it might take a few seconds before it
91 responds.
92
93                            Options and parameters
94 ------------------------------------------------------------------------------
95 There are four arena parameters that you can set in your crawl options file:
96
97 * arena_delay: The delay in milliseconds between turns within the arena.
98       Can be set to 0 to make the simulation zip along. Defaults to 600.
99
100 * arena_dump_msgs: If set to true causes messages to be dumped to the file
101       arena.result. Defaults to false.
102
103 * arena_dump_msgs_all: If both this and arena_dump_msgs are set to true
104       then diagnostic messages will be dumped as well as other messages.
105       Defaults to false.
106
107 * arena_list_eq:  Dump to the file arena.result the equipment of the
108       monsters placed at the beginning of each round.
109
110
111 The are also a number a parameters you can use by putting them in the
112 string which specifies the monsters:
113
114     crawl -arena "parameter1 parameter2 parameter3 goblin v kobold"
115
116 The parameters include:
117
118 * "arena:name" lets you pick the name of the arena to place the monsters
119       in (defaults to "arena:default"). See source/dat/des/builder/arena.des
120       for a list.
121
122 * names: Causes all non-unique monsters to be given random names.
123
124 * no_animate: Prevents corpses from being animated into zombies.
125
126 * no_summons: Prevents monsters from summoning more monsters.
127
128 * no_chain_summons: Allows the original monsters to summon more monsters,
129       but the *summoned* monsters can't themselves summon any more.
130
131 * no_immobile: Prevents immobile monsters from being randomly generated.
132
133 * allow_zero_xp: Allows zero xp monsters like plants to be randomly generated,
134       which are forbidden from the arena by default.
135
136 * "arena_place:place" sets the place used when determining which monsters the
137       spell Shadow Creatures uses. So "arena:Lair:5" would make it
138       summon the types of monsters you'd find on the 5th lair of the Lair.
139       It also controls what type of monster "random" places, assuming
140       that "random_uniques" isn't used.
141       (This defaults to the 1st level of the Depths).
142
143 * real_summons: Summoned monsters are made real as soon as they're placed in
144       the arena, so they can drop corpses and equipment (no_chain_summons
145       still prevents them from summoning more monsters, though).
146
147 * move_summons: Moves summoned monsters to a new, random location as soon
148       as they're placed, so they don't end up clustered around the
149       summoner.
150
151 * "summon_throttle:N" prevents summoned monsters from being placed if the
152       summoner has N or more allies present.
153
154 * cycle_random: If any monster summons monsters with the spell Shadow
155       Creatures spell (including test spawners) then arena cycles through
156       the list of valid monsters, rather than taking rarity into account.
157
158 * random_uniques: If the team is made up of random monsters
159       (e.g. "random v random") the chosen monsters will be uniques. Also,
160       any monster using Shadow Creatures will summon uniques.
161
162 * "ban_glyphs:ABC" prevents monsters with the listed ASCII glyphs from
163       being placed in the arena. For instance, "ban_glyphs:&C" prevents
164       demon lords and giants/cyclopses/titans/etc from being placed.
165
166 * "delay:N" allows the delay between turns to be specified on the command
167       line instead of in the options file.
168
169 * miscasts: Every turn each monster (besides test spawners) will have a
170       random miscast happen to it.
171
172 * respawn: When one of the originally replaced monsters is killed it will
173       be replaced by the same type of monster. This allows for an endless
174       fight between exactly specified factions, rather than the random
175       kind you get by pitting two test spawners against each other.
176
177 * move_respawns: Moves respawned monsters to a new, random location as
178       soon as they're placed, to avoid monsters clumping up in a massive
179       brawl at the center of the arena.