monster_speech.txt

Overview
========

As of Dungeon Crawl Stone Soup 0.3 the previously hard-coded monster
speech has been outsourced. This makes changing existing messages,
or adding new ones really easy. This file will hopefully help you in
this endeavour.

The outsourced messages are used to create two databases out of which
Crawl randomly draws the necessary speech text.

* shout.db (handling speech when monsters first notice you), and
* speak.db (for all other cases).

Because of the amount of definitions necessary, they have been divided
over a number of different files.

The shout database is constructed from the following two files:

* shout.txt     handles message output for monsters noticing you
* insult.txt    handles insults thrown at you by imps and demons

The speak database contains messages defined in these files:

* monspeak.txt  handles messages for monsters communicating with you
* wpnnoise.txt  handles randart weapons with the noises property
* godspeak.txt  handles randomized speech by the gods, as well as
                speech used for some divine abilities
* insult.txt    Same file as above.

The messages defined in insult.txt form a part of both databases.
Apart from that, keywords and statements defined for one database
cannot be automatically accessed from the other. Rather, they have to
be defined a second time.

Whenever Dungeon Crawl is started, the game checks whether any of the
databases needs to be updated. If one of the underlying files has been
changed since the last check, the database is automatically rerolled.
That means that if you'd like to change one of the descriptions or add
some new monster speech all you have to do is modify the file, save,
and restart the game to test your changes.


Contents:
 A. Monster speech probabilities
 B. A simple example
 C. Key lookup in detail
 D. Values in detail
 E. Testing your changes
 F. Publishing your changes


A. Monster speech probabilities
================================

Not all monsters are equally likely to speak. Rather, there are
different chances involved, depending on several attributes, and most
of the time the database lookup stage isn't even reached.

First, the player will only ever hear monsters speak if they are in
line of sight, and monsters will only ever speak if they are not
asleep, not submerged in water, air or lava, and not wandering around
aimlessly (unless neutral).

Berserk monsters are too busy killing and maiming to speak. Also,
invisible monsters the player can't see (for lack of see invisible)
will always stay silent, unless confused.

Monsters capable of speech (i.e. all intelligent humanoid monsters, as
well as all uniques and some non-unique demons) have a base chance of
1/21 of speaking, while humanoid monsters incapable of speech will
never communicate with the player in any form.

Non-humanoid monsters get a 1/84 probability of "speaking" per turn
(non-verbal actions, more like). This chance is divided by another 10,
if the monster in question was generated as a member of a group.
Chances are doubled if this non-humanoid monster is fleeing, and doubled
again if confused.

Neutral monsters only speak half as often, and for charmed monsters
the probability is divided by 3. The same applies to silenced
monsters, i.e. monsters that are not naturally silent will only get to
even attempt to speak in one out of three tries where the above
chances hold.

Note that the definition of which monsters are capable of speech is
entirely hardcoded. We think we made this apply to all sensible
monsters, i.e. all intelligent humanoid monsters, but of course it is
possible we've overlooked something, so if you find that your
carefully constructed monster speech never gets printed, and this
documentation also doesn't help you solve the problem, you might want
to post a bug report on Stone Soup's Mantis site [2].

The exception to the above is when the monster goes away due to dying,
being banished, or a summoned monster being abjured or having it's time
run out. In that case the monster always speaks if the player can see
the grid the monster is on (assuming that there's a speech entry defined
for that occasion, of course).

B. A simple example
====================

If you have a look at some of the speech files, you'll see that all
entries have basically the same structure: a key, followed by one or
more values.
Here is an example.

  %%%%
  # Friendly imps are very common so they speak very rarely
  friendly '5'

  w:1
  @The_monster@ laughs.

  w:1
  @_friendly_imp_@

  __NONE
  %%%%

Let's look at this entry's components in more detail.

  %%%%

Four percentage signs mark beginning and end of a database entry. If
you forget to place these, you will get buggy monster speech.

  # Friendly imps are very common so they speak very rarely

A '#' sign at the beginning of a line causes it to be ignored; these
are comment lines.

  friendly '5'

The first non-comment, non-blank line is interpreted as the key of an
entry. Many keys are hardcoded, but there's place for user defined
ones as well. More on that later, though.
In this case, the key is "friendly '5'".

'5' refers to the monster glyph, so the speech will not be entirely
restricted to imps, though they are by far the most common type of
minor demons.

  w:1
  @The_monster@ laughs.

The rest of the entry consists of messages, separated by blank
lines. This is one of them. Each may be prefixed with an optional
weight ("w:1"). A message will be chosen with a probability of its
weight out of the sum of weights for its entry. Weight defaults to 10
if not specified. In this example, this particular message will be
selected 1 time out of 12.

  @The_monster@ laughs.

This is the message that will be printed. The '@' markers indicate
variables that will be substituted before printing. This particular
variable "@The_monster@" is treated specially by the game; the
substitution will change based on the monster giving the speech. See
below for more details.

  w:1
  @_friendly_imp_@

This is another case of a substitution. Here, "_friendly_imp_" is an
entry in speak.txt. A random line from that entry will be substituted.

  __NONE

This is a special command; it prints no message. See below for more
details on special commands.


C. Key lookup in detail
========================

Key lookup is always case-insensitive. The game will make many
different attempts when trying to find monster speech, all of which
are explained in detail below. You'll find some examples at the end of
this section.

First, a monster may have one or more of a list of attributes that
might influence its speech. We will henceforth refer to these
attributes as prefixes.

"friendly" is one of a couple of allowed prefixes, distinguishing the
speech from "hostile" or "neutral". All prefixes are optional and
tested in the following order:

  default <attitude> fleeing silenced confused [related] <player god> <branch>

where <attitude> can be any of friendly, neutral or hostile. Note that
the game generally treats neutral monsters like hostiles since they
still pose a danger to players.

The prefix "related" is added if the player and the monster share the
same genus, e.g. if you're playing a Sludge Elf, and the monster in
question is a deep elf blademaster, you both are elves and the monster
speech may reflect that. It's currently only used for friendly
humanoids who will now sometimes mention that you're family, if you
are. Stupid monsters, i.e. animals, will judge your relatedness status
according to your transformed looks while smart monsters will see
through that magic, so that e.g. vampires will recognise a vampire in
bat form as one of their own but a giant bat would think the player
really is a bat.

The <player god> prefix is constructed according to the religious
belief of the character. If the monster in question is a member of the
orc species and the character worships Beogh, depending on whether the
monster orc believes in Beogh (rolled at creation, always true when
converted) either the prefix "beogh" or "unbeliever" gets added to the
list, though not for charmed orcs who will simply use the generic
friendly statements instead of the orcish followers' cheers.
If you worship one of the good gods instead (Zin, the Shining One, or
Elyvilon), the prefix "good god" is used.

This allows fine-grained handling of monsters depending on your
character's religion status, e.g. orcs will use special speech for
Beogh worshippers, and neutral holy beings (Angel and Daeva) may
shout messages of encouragement to followers of the good gods, while
demons might attempt to slander the good gods.

Finally, the current branch is added to the list of prefixes, so
monsters may react differently depending on where you encounter them.
This is currently only used for the unique Donald.

Once the entire set of prefixes has been determined, we only need
to add the monster name and start the database search.

First we search for the complete prefix string in combination with the
monster name. Then we try omitting some very specific prefixes that
might not be so important, first skipping on "hostile", then also
ignoring religion status, then hostile and "related", then all three
of them, then dungeon branch, and then finally adding "silenced" to
the list of ignored prefixes, where applicable.

If all of that didn't yield any results, next we'll take the complete
prefix list again, then, reading from left to right, combinations are
tested, beginning at three prefixes and ending at none. At this stage
the list of prefixes is always prepended with "default". This ensures
that, for example, fleeing uniques won't output their normal menacing
speech but rather the default speech defined for fleeing humanoids in
general.

In practise this means that database keys starting with "default" are
the fallback solution if the exact look-up has failed. As such, the
messages should be generic enough to allow for all the possibly
skipped prefixes, or else those cases should be caught earlier, e.g.
if you have "default friendly humanoid", you should also define
"default friendly fleeing humanoid" and "default friendly confused
humanoid" (and possibly both combined) even if only with "__NONE"
(stay silent), as the general friendly messages may look odd for a
monster such afflicted.

Only keys that match a search string perfectly (ignoring case) will
be used. Once all prefixes have been exhausted and still no match has
been found, the database lookup will try for a more general monster
description. There are several possible ways this is attempted, in the
following order:

1. The actual monster name.
   Examples: "crystal golem", "default confused moth of wrath"
2. The monster genus.
   Examples: If "friendly ogre mage" wasn't found, try "friendly ogre"
             instead. Same for "dragon" if "swamp drake" was
             unsuccessful.
3. Then the monster glyph, with prefix "cap-" for capital letters.
   Examples: "default 'cap-J'", "default confused 'k'"
4. A group description (such as 'insect' or 'humanoid') defined by the
   monster's body shape (winged, tailed, etc.) The definition of the
   latter is entirely hardcoded, though.
   Examples: "default winged insect", "default confused humanoid"

If you are playing with tiles, you may not know the monster glyphs,
but internally the monsters are still treated the same, and even under
tiles, the glyph keys used for step 3 are entirely valid. In case you
need to know the monster glyphs for your speech definitions you'll
find a list of monster glyphs at the end of this file.

Note that changing monster glyphs using the mon_glyph option does not
affect speech. Instead, the underlying glyph used in the monster
definition is used.

For the last round (shape comparison, e.g. "winged humanoid")
occasionally an additional intelligence estimate ("stupid", "smart")
is prefixed to the search string, depending on the monster type, e.g.
a "stupid humanoid" may still be smarter than a "smart arachnid".

Here's a list of allowed monster shapes that should hopefully be
self-explanatory:

  humanoid, winged humanoid (angels), tailed humanoid (draconians),
  winged tailed humanoid (gargoyles), centaur, naga, quadruped,
  tailless quadruped (frogs), winged quadruped (hippogriff), bat,
  snake (also eels and worms), fish, insect, winged insect, arachnid,
  centipede, snail, plant, fungus, orb (eyes), and blob (jellies).

If no matching keys are found after all of these rounds, the monster
definitely stays silent.


Examples
--------

Example 1:
  The monster we want to make "speak" is a "confused killer bee".

  However, such an entry cannot be found in the database, so the game
  tries first for "default confused killer bee", then "default killer
  bee", neither of which yields any results.
  The monster genus is also plain "killer bee", so that doesn't help
  us any. For the next round we try again with "confused 'k'", which,
  by itself, also can't be found in the database, but once the prefix
  comparison tries it together with "default", we have a match:

%%%%
default confused 'k'

SOUND:@The_monster@ buzzes around in tight circles.
%%%%

Example 2:
  This time, we're interested in "friendly fleeing related beogh orc wizard".

  This obviously made up example also has no direct equivalent in the
  database, so first we try to remove the less important prefixes, in
  this case "related" and "beogh". Unfortunately, none of "friendly
  fleeing related orc wizard", "friendly fleeing beogh orc wizard", or
  "friendly fleeing orc wizard" has any corresponding entry in the
  database, so that we now check for "default" in combination with,
  one after another, all combinations of three or less prefixes.

  Three prefixes: "default friendly fleeing related orc wizard",
  "default friendly fleeing beogh orc wizard", "default friendly
  related beogh orc wizard", "default fleeing related beogh orc
  wizard".

  Two prefixes: "default friendly fleeing orc wizard", "default
  friendly related orc wizard", "default friendly beogh orc wizard",
  "default fleeing related orc wizard", "default fleeing beogh orc
  wizard", "default related beogh orc wizard".

  One prefix: "default friendly orc wizard", "default fleeing orc
  wizard", "default related orc wizard", "default beogh orc wizard".

  No prefix: "default orc wizard".

  Sadly, none of these is successful. The genus of orc wizards is
  "orc", so we retry the above using "orc" instead of "orc wizard".
  The same is repeated for "friendly fleeing beogh 'o'", and we still
  haven't found anything.

  This is starting to get ridiculous, so it's time for desperate
  measures:

  With the help of some rather complicated functions the game works
  out that orcs can be described as humanoids of average intelligence.
  Thus, in a final attempt of making this orc wizard speak, we search
  the database for "friendly fleeing related beogh humanoid",
  something that, not surprisingly (since Beogh and humanoid don't go
  well together), doesn't exist. Annoyingly enough, neither do the
  variants "friendly fleeing related humanoid", "friendly fleeing
  beogh humanoid" or even "friendly fleeing humanoid".

  Still, we haven't yet tried the prefix combinations: "default
  friendly fleeing related humanoid" is still unsuccessful, as
  are "default friendly fleeing beogh humanoid", "default friendly
  related beogh humanoid", and "default fleeing related beogh
  humanoid", but with "default friendly fleeing humanoid" we finally
  strike gold:

%%%%
default friendly fleeing humanoid

w:30
VISUAL:@The_monster@ tries to hide somewhere.

@The_monster@ @shouts@, "WAIT FOR ME, @player_name@! Could you help me?"

...

  We'll leave it at that, even though the database code still has work
  to do, namely add up the weights of all the entries (and there are
  several more), and randomly choose one of them.


Weapon speech
-------------

For obvious reasons, weapon noises get by without any such prefixes,
and the only hardcoded keywords are "noisy weapon" for weapons with
the noises property, "shield of the gong", while the singing sword uses
"singing sword " + one of: silenced, no_tension, low_tension, high_tension,
SCREAM.


Death speech
------------

You can define messages for the monster to give for when it goes away
in three different manners:

* If it really died, then the game will look up a speech entry with
  the same keys as usual, but with " killed" appended to all the keys.

* If it was banished, then the game will append " banished" to all the
  lookup keys.

* If the monster was summoned and rather than being killed was abjured
  or ran out of time, then the game will append " unsummoned" to all of
  the lookup keys.

The game will always do a lookup in these circumstances if the player
can see the square the monster is on, so if you only want a death message
to be given occasionally then make one of the messages "__NONE" and give
it a high weight.

Of course, if no keys with the given suffix are in the database then the
monster will say nothing in that circumstance.


Special monster speech
----------------------

Rarely, monster speech will also rely on hard-coded keys. If such a
hard-coded key is changed or removed, the speech in question will simply
not be printed.
This may look odd in the game, but will have no other effect. Sometimes,
default messages will be output instead.


God speech
----------

The keys used to search for god speech are entirely hard-coded, though
some local synonyms have been defined as well. Hopefully, the comments
will explain what the different speech messages are used for.


D. Values in detail
====================

Spacing
-------

There have to be blank lines between the different messages. If
messages are placed directly one after another they will be printed as
a block. This can be useful, e.g. for outputting first a "spell" and
then its (fake) result.

Note that this does not work for weapon noises. Here only the first
part of a paragraph before a carriage return is parsed.

The message entries themselves can be longer than a line, though Crawl
will simply truncate it should it exceed the screen width (assuming 80
columns or less). The actual message length will usually differ from
the one defining an entry as parameters can be stripped from the entry
or replaced by other values, as explained in the following section.

Variables
---------

Values can contain variable references, which look like text
surrounded by @@. These variables may be defined by entries in
shout.txt for the shouting database, or monspeak.txt or one of the
other files for the speech database, in which case they are replaced
with a random value from the entry in question; or they may have
hardcoded expansions defined by the game.

Note that variable replacement is recursive, so be careful to avoid
infinite loops. Though the game will abort after a number of
replacement attempts, it will still look ugly in the monster speech.

The following variables are hardcoded:

@monster@       : Plain monster name, e.g. "rat" or "Sigmund"
@a_monster@     : Indefinite article plus monster name,
                  or only the name if it is unique ("Sigmund").
@the_monster@   : Definite article plus monster name ("the rat"),
                  or a possessive if it is friendly ("your rat"),
                  or only the name if it is unique ("Sigmund").
@something@     : Like @monster@, with monster name replaced by
                  "something" if the monster is invisible and the
                  player cannot see invisible.
@a_something@   : similar
@the_something@ : similar
@player_name@   : Player name.
@player_species@: Player base species, with Draconian rather than the
                  actual subtype.
@player_genus@  : Player genus, i.e. "Elf" rather than the exact type,
                  or "Orc" instead of "Hill Orc".
@player_genus_plural@ : pluralised genus form.
@player_god@    : Player's god name, or "you" if non-religious.
@god_is@        : replaced with "<god name> is" or "you are", if
                  non-religious.
@a_God@         : Monster's god name, or "a god" if nameless. [1]
@my_God@        : Monster's god name, or "my God" if nameless. [1]
@possessive_God@  : Monster's god name, or "its/his/her god" if nameless. [1]
@surface@       : Whatever the monster is standing on.
@feature@       : The monster's square's feature description.
@subjective@    : it, she, he, as appropriate
@objective@     : it, her, him, as appropriate
@possessive@    : its, her, his, as appropriate
@imp_taunt@     : imp type insults (see insult.txt)
@demon_taunt@   : demon type insults (see insult.txt)
@hand@          : whatever body part serves as the monster's "hand".
@arm@           : whatever body part serves as the monster's "arm".
@foot@          : whatever body part serves as the monster's "foot".
@hands@         : plural of @hand@ [1]
@arms@          : plural of @arm@ [1]
@feet@          : plural of @foot@ [1]
@says@          : synonym of "say" that fits monsters' (hardcoded)
                  speech pattern and noise level.

Capitalized forms (@Monster@, @A_something@, @Possessive@, @My_God@)
are expanded with capitalized text.

[1] Note that plural body parts such as @hands@, @arms@, and @feet@ may
be inappropriate for some monsters (for example, a fungus's @foot@
is its stem, and an eyeball's @hand@ is its pupil). In those cases,
the plural form will expand to a clearly-erroneous string such as
"NO PLURAL ARMS"; these variables should be used only for monsters
with known body shape. Likewise, the variables concerning the monster's
god expand to "NO GOD" if the monster is non-religious, so should be
used only for monsters known to have religion.

Also, in insult.txt you'll find the hardcoded variables
@species_insult_adj1@, @species_insult_adj2@, and
@species_insult_noun@. These are sometimes used in the construction of
imps' or demons' generic insults, and allow for species-dependent
handling. If the parser encounters such a variable, it will search the
database for the corresponding specific entry, i.e. "insult <genus>
adj1/adj2/noun" where <genus> is replaced with the actual genus name,
that is "draconian", "elf" or "dwarf" instead of the more specific
species name, "ogre" for "ogre mage", or the actual species name in all
other cases.

If this specific search doesn't yield any results, i.e., such an
entry hasn't been defined for the species in question, the general
replacements are used instead.

Weapon noises are handled differently in that most of the above
replacements don't hold. Instead you can use @The_weapon@,
@the_weapon@, @Your_weapon@, @your_weapon@ and @weapon@ which will get
replaced by "The (weapon name)", "the (weapon name)", "Your (weapon
name)", "your (weapon name)", and the plain weapon name, respectively.

@player_name@ is expanded as above, as is @player_god@, though for
atheists it returns "atheism".

Any of these keywords' values can be changed to uppercase if you encase
them by the keywords @CAPS@ and @NOCAPS@. For example,

  "Go to hell, @CAPS@ @player_name@ @NOCAPS@!"

will result in the monster yelling "Go to hell, PLAYER NAME!" with the
actual player name being fully printed in capital letters. For
convenience, leading and dangling spaces within the substring encased
by the two keywords (which can be one or several words, or even the
entire line) are trimmed. If the @NOCAPS@ keyword is left out, the
entire rest of the line gets capitalised.

Note that the Singing Sword, being unique, cannot be referred to by
the possessive variants, so they will be replaced with the appropriate
definite article ones.

Examples of pre-defined variables in the database include
_high_priest_, _mercenary_guard_, _wizard_, _friendly_imp_,
_hostile_imp_, and _tormentor_, but more get added all the time.
There are also a few synonyms defined at the beginning of monspeak.txt
such as for @ATTACK@, @pointless@, @shouts@, @wails@, and others.

Weapon noises also use a number of synonyms which are defined at the
end of wpnnoise.txt.

The best way to learn about how variables and other concepts can be
used is probably to see how it has been done for existing messages.


Random substrings
-----------------

As explained above, you also can use the @@ pattern to define some more
complex parts of a phrase. Here's an example from the Singing Sword:

  @The_weapon@ @_sings_or_hums_@ an eerie @_tune_or_melody_@.
  %%%%
  _sings_or_hums_

  sings

  hums
  %%%%
  _tune_or_melody_

  tune

  melody
  %%%%

This is really useful if a certain pattern turns up a lot, if you want
to assign different weights to the possible choices, or if the
replacements may themselves contain random elements.

However, in all other cases you can greatly simplify the syntax by
putting all possible values, separated by "|", inside square brackets:

  @The_weapon@ [sings|hums] an eerie [tune|melody].

Other than in this example, the choices may also consist of multi-word
phrases. Note that spaces within the patterns don't get trimmed and
that an empty phrase is considered a valid choice.


Speaking to the player vs to another monster
--------------------------------------------

If a message contains a variable starting with "@player", then that
message will only be used by friendly/good-neutral monsters, or by
hostile/neutral monsters which have the player as their foe (and it
will never be used in the arena). Additionally, any message containing
a line starting with "You" or ending in a bare "you." (but not a quoted
"you.") will also be considered player centric. You can explicitly make
a message player-centric by appending "@player_only@" to the end of any
of the lines in the message, which will be removed before displaying it
to the player.

If you want a message to be able to apply to a foe which is another
monster in *addition* to the player, you can replace "@player" with
"@foe" to have the variable filled out with a string appropriate for
the foe being either the player or another monster. If "@foe_name@"
is present then the message will only be used on monster foes which are
named, and if "@foe_god@" or "@god_is@" is present then it will only be
used on priestly monsters or god gift monsters.
"@Foe@" or "@foe@" will be replaced with "You" or "you" if directed at
the player, or if directed at another monster be the same as
"@The_monster@" or "@the_monster@", but with the foe monster's name
rather than the speaking monster's name. "@foe_possessive@" will be
replaced with "your" if directed at the player, or expanded like
"@foe@'s" if directed at a monster.

If you want to indicate which monster a message is directed at, you can
put in "@to_foe@" or "@at_foe@" to fill in the foe name when the
message is directed at a monster; when directed at the player the
variable will be removed. For example, with the message:

    @The_monster@ says @to_foe@, "Defend yourself!"

If directed at an orc will expand to:

    @The_monster@ says to the orc, "Defend yourself!"

but if directed at the player will expand to:

    @The_monster@ says, "Defend yourself!"

You can do something similar with "@foe,@" for asking questions and the
like. For example:

    @The_monster@ asks @foe,@ "Who are you?"

when directed at an orc will expand to:

    @The_monster@ asks the orc, "Who are you?"

and when directed at the player will expand to:

    @The_monster@ asks, "Who are you?"

The @at_foe@ and @to_foe@ tags (only) also allow specifying an alternative
to be substituted when directed at the player:

    @The_monster@ looks @at_foe/around@ nervously.

Channels
--------

An optional channel name at the beginning of a string causes messages
to be sent to that channel. For example:

  SPELL:@The_monster@ casts a spell.
  WARN:Your equipment suddenly seems to weigh more.

Spacing after the channel parameter won't get stripped, so it's a good
idea to double check that the speech message directly follows the
colon.

Here are the defined channels:

  TALK    :  MSGCH_TALK (Default value.)
  DANGER  :  MSGCH_DANGER
  ENCHANT :  MSGCH_MONSTER_ENCHANT
  PLAIN   :  MSGCH_PLAIN
  SOUND   :  MSGCH_SOUND
  SPELL   :  MSGCH_MONSTER_SPELL
  VISUAL  :  MSGCH_TALK_VISUAL
  WARN    :  MSGCH_WARN

The channels have been assigned different colours and are sometimes
treated differently, e.g. any of MSGCH_TALK, MSGCH_SOUND and
MSGCH_TALK_VISUAL will never interrupt resting or travel unless
specifically added in the options file.

Note that MSGCH_SOUND and MSGCH_TALK get filtered out when you are
silenced. For similar reasons monster speech of channel SPELL is muted
under silence, along with ENCHANT and WARN, both of which currently
only occur in combination with SPELL. To allow for silent spells along
with fake warnings and enchantments, you can combine these with VISUAL
and enforce output even when silenced.

  VISUAL ENCHANT : MSGCH_MONSTER_ENCHANT
  VISUAL SPELL   : MSGCH_MONSTER_SPELL
  VISUAL WARN    : MSGCH_WARN

Note, though, that these only will take effect if a VISUAL message
just happens to be chosen. As stated above, the database search
doesn't really care whether a monster is supposed to be silent, so it
may pick any noisy monster speech, but the message output will care
and refuse to print such nonsense, so that in this case the monster
will actually stay silent after all.

To summarize, chances of silent "speech" are overall lower (as is
intended) but only VISUAL messages even have a chance to be printed
under these circumstances.

As explained earlier, "silenced" is one of the prefixes that are
regarded as "less important" and can be ignored in the exact string
search. So that both specially defined silenced messages for a
particular monster and its normal VISUAL messages can sometimes take
effect, chances for actually skipping on silenced in the direct string
matching are 50:50.

Example 3:
  The player has just cast Silence when a Killer Klown wanders into
  view. (Uh oh!) This "silenced Killer Klown" is now attempting to say
  something. The exact look-up is unsuccessful, but now there's a 50%
  chance of skipping on the "silenced" prefix. If this route is chosen
  we may get results such as

%%%%
Killer Klown

@The_monster@ giggles crazily.

@The_monster@ laughs merrily.

...

  none of which, if chosen, would actually be printed, but luckily the
  "Killer Klown" entry also contains VISUAL statements like the
  following:

...

VISUAL:@The_monster@ beckons to you.

VISUAL:@The_monster@ does a flip.

...

  If one of these is chosen, we get a non-verbal "speech" statement of
  this silenced monster.

  However, what happens if the other 50% take effect and we will *not*
  ignore the "silenced" prefix? In this case, we'll simply continue
  like in the earlier examples above, get no results for either of
  "default silenced Killer Klown" or "default Killer Klown", and try
  the genus next: human, which cannot be found in the database,
  silenced or no. Neither will we find anything for the monster glyph
  '@'. Now all that remains is to check the monster shape, which is
  "humanoid" again. "silenced humanoid" won't get us any results, nor
  will simply "humanoid", but "default silenced humanoid" has some
  statements defined.

%%%%
default silenced humanoid

w:30
VISUAL:@The_monster@ says something but you don't hear anything.

w:30
VISUAL:@The_monster@ gestures.

...

  All of the statements in these predefined "silenced" entries have to
  be of the type VISUAL; otherwise they'll never get printed.


For shouts the default channel is also MSGCH_TALK, which is
automatically changed to MSGCH_TALK_VISUAL for monsters that can't
speak (animals, usually), and manually set to MSGCH_SOUND for all
those variants of "You hear a shout!"

Monster spells and enchantments will only interrupt resting/running
if done by a non-friendly creature, and, as stated above, messages
passed through the TALK or SOUND channels never will.

For weapon noises only a subset of the above is relevant, as anything
including VISUAL and the channel keys SPELL and ENCHANT is considered
invalid and will trigger a default message instead. Again, the default
channel is MSGCH_TALK.


Special commands and variables
------------------------------

Message entries may also be one of several special commands. These
aren't variables, so they aren't surrounded by @@. Accordingly, they
are not expanded, but rather they produce special game behaviour.

  __NONE : no message
  __NEXT : try a more general monster description

Some special keys are defined in monspeak.txt and shout.txt, such as
__SHOUT. These are normal variable expansions, and may be used as
such. They are given special-looking names because Crawl looks up the
noises a given monster can produce and looks for keys that match the
string, i.e. __SHOUT, __BARK and so on.


E. Testing your changes
========================

Get a version of Stone Soup that contains WIZARD mode. You can check
whether this is the case by reading the in-game version information
('?v'). If Wizard mode is not listed among the included features, you
will have to compile the game for yourself.

To build Crawl yourself, download the source code from the Crawl
homepage [1] and read the "INSTALL" file in the main directory for
instructions. Should you still have any questions after reading the
documentation you can ask for help e.g. in the Tavern [3].

If you have WIZARD mode compiled in, you can access special wizard
commands by pressing '&'. First answer "yes" to the safety question
and then you can test to your heart's content. Pressing '&' followed
by a number of other keys will execute wizard mode commands that are
all listed in the wizard help menu (press '&?').

In particular, you can create a monster with '&M', and enforce
behaviour on a monster by examining it (with 'x', as usual). In wizard
mode, examining monsters offers several new sub-commands such as 'F'
(make monster friendly/neutral/hostile) and 's' (make monster shout).
These last two are of particular interest to monster speech designers.

Also, the Singing Sword and other hardcoded artefacts can be created
with '&o'. To create all artefacts at the same time, use '&|'. The
Elemental Staff and the spear of Botono are examples of noisy weapons.

You can also temporarily increase the likelihood of a given message by
adding a high weight value before it, e.g. w:5000, or equally
temporarily push it into another channel (e.g. MSGCH_WARN) to make it
more noticeable.

To get detailed information about monster speech generation, you can
use a FULLDEBUG build of crawl (`make debug`); whenever the game is
searching the monspeak database you'll get extensive information on
all keys and prefixes tried.

F. Publishing your changes
===========================

If you feel that your additions really add something to the game and
would like to make them available to the general public, you can post
them as a pull request on github [2], or discuss them in our Tavern forum [3].


.. [1] http://crawl.develz.org/wordpress/
   The official Dungeon Crawl Stone Soup homepage, always linking
   to the latest release.

.. [2] https://github.com/crawl/crawl/pulls
   Our pull requests on github.

.. [3] https://tavern.dcss.io/
   The official DCSS forum. You may find it helpful to discuss new features in
   the Game Design Discussion category here.