Yet another change to monster speech and silencing...

I found my previous change to block all messages passed 
through MSGCH_TALK when silenced was too restrictive, so
I've added another channel MSGCH_TALK_VISUAL and adapted the
monster speech files accordingly. For example, imps can now
also "talk" when silenced, but only the visual stuff will
actually be output. (This automatically takes care of 
lowering the output likelihood.) And no, this doesn't hurt 
any, as visual talk also won't interrupt travel or resting.

And I added a how-to file on monster speech, which was the
main reason for my silence during the last couple of hours. 
It's not that the database system is that complicated but it 
surely can't hurt to give players who want to add something 
an idea of what is possible and how to go about it.


git-svn-id: https://crawl-ref.svn.sourceforge.net/svnroot/crawl-ref/trunk@2108 c06c8d41-db1a-0410-9941-cceddc491573

1 files changed, 227 insertions, 0 deletions

diff --git a/crawl-ref/docs/monster_speech.txt b/crawl-ref/docs/monster_speech.txt
new file mode 100644
index 0000000000..27ebc1aae2
--- /dev/null
+++ b/crawl-ref/docs/monster_speech.txt
@@ -0,0 +1,227 @@
+As of Stone Soup 0.3 the previously hard-coded monster 
+speech has been outsourced into shout.txt and speak.txt by 
+Matthew Cline. This makes changing existing messages, or 
+adding new ones really easy. This file will hopefully help 
+you in this endeavour.
+
+shout.txt handles message output for monsters noticing you.
+speak.txt handles messages for monsters communicating.
+
+If you take a look through the two files, you'll see that 
+all entries have basically the same structure. Let's have a 
+look at an xample:
+
+###############
+# Friendly imps
+###############
+%%%%
+# Friendly imps are very common so they speak very rarely
+friendly '5'
+
+w:9
+__NONE
+
+w:1
+@_friendly_imp_@
+
+%%%%
+
+
+Now let's have a look at these in more detail:
+
+# Friendly imps
+  A '#' sign at the beginning of line means this line will 
+  be ignored, so it's used as a comment.
+
+
+%%%%
+  The four percentage signs mark beginning and end of a 
+  database entry. If you forget to place these, buggy 
+  monster speech will result.
+
+
+friendly '5'
+  The first non-comment, non-clear line is interpreted as 
+  the key of an entry. Most keys are hardcoded but there's 
+  place for user defined ones as well. 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 ones. 
+  On the whole there are three ways the game tries to look 
+  for keys in the database. First the actual monster name is 
+  used, then the monster glyph (with prefix "cap-" for 
+  capital letters), then a a group description (such as 
+  insect or humanoid) defined by the monster's body shape. 
+  The latter is entirely hardcoded, though.
+
+  "friendly" is one of a couple of allowed prefixes, 
+  distinguishing the speech from "hostile" (default).
+
+  These prefixes are optional and tested in the following 
+  order: 
+  
+  default friendly/hostile fleeing silenced confused monster
+
+  First the database is searched for the whole prefix 
+  string, then reading from left to right the combinations 
+  are tested, beginning at three prefixes and ending at 
+  none, at which time the prefix "default" is used instead. 
+  For the last round (shape comparison, e.g. winged humanoid 
+  etc.) a prefix on intelligence gets added. If in this last 
+  round still nothing has been found, the monster stays 
+  silent.
+
+
+w:9
+  After a clear line the actual talk begins. You can skew 
+  the probability of a given message with the weight ('w') 
+  tag. A message will be chosen with a probability of its 
+  weight (defaults to 10 if none set) out of the sum of 
+  weights for this entry. In this case, nine times out of 
+  ten a friendly imp will stay silent. 
+
+
+__NONE
+  Aside from "__NONE" there are a few other hardcoded 
+  markers:
+
+  __NONE : no message
+  __NEXT : try the next combination of attributes
+  __MORE : enforce a "-- More --" prompt
+  __YOU_RESIST : "You resist."
+  __NOTHING_HAPPENS : "Nothing appears to happen."
+
+  In addition, some more are defined in speak.txt and 
+  shout.txt, such as __RESIST_OR_NOTHING, __SHOUT, and 
+  others.
+
+
+@_friendly_imp_@
+  Other variables can be defined in the form of @variable@. 
+  The "@_friendly_imp_@" above is key to another entry in 
+  the database entitled "_friendly_imp_" (without those '@' 
+  signs) that actually has imps talking. Their speech 
+  includes messages such as the following.
+
+
+VISUAL:@The_monster@ grins impishly at you.
+
+VISUAL:@The_monster@ picks up some beetles from the @surface@ and offers them to you.
+
+
+Again, there have to be clear 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 it's (fake) result.
+
+Monster speech can be greatly customized by the use of 
+several variables. This example already includes a few.
+
+
+VISUAL:
+  This optional parameter at the beginning of a string 
+  decides which message channel a string will be passed 
+  through. The list of allowed tags is as follows:
+
+  TALK    :  MSGCH_TALK (Default value.)
+  DANGER  :  MSGCH_DANGER
+  ENCHANT :  MSGCH_ENCHANT
+  PLAIN   :  MSGCH_PLAIN
+  SOUND   :  MSGCH_SOUND
+  SPELL   :  MSGCH_MONSTER_SPELL
+  VISUAL  :  MSGCH_TALK_VISUAL
+  WARN    :  MSGCH_WARN
+
+  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 SPELL   : MSGCH_SPELL
+  VISUAL WARN    : MSGCH_WARN
+  VISUAL ENCHANT : MSGCH_ENCHANT
+
+  Note, though, that these hardly ever take effect as 
+  usually the "silenced humanoid" types take precedence. 
+  Only if no message for the silenced monster type is found 
+  these special VISUAL cases will apply.
+  For shouts the default is also MSGCH_TALK which is 
+  changed to MSGCH_TALK_VISUAL for monsters that don't 
+  speak, and manually set to MSGCH_SOUND for all those 
+  variants of "You hear a shout!"
+
+
+@The_monster@, @surface@
+  Like with @_friendly_imp_@ above, variables have been 
+  defined to allow for greater flexibility. When the speech 
+  code encounters an '@' sign it will first search the 
+  database for a variable of that name and execute the 
+  necessary replacement. Note that recursive replacement of 
+  one variable with another is possible, so try to avoid 
+  loops. The remaining variables it was unable to find in 
+  the database are hardcoded and will be replaced before 
+  output. If you add a new variable make sure to also add a 
+  database entry for it (without those '@' marks around!);
+  otherwise it won't get replaced and just look weird.
+
+  A variable that you will see all over the place is 
+  @The_monster@ which is hardcoded and will be replaced with 
+  the monster's name. This is particularly useful for groups 
+  of monsters that share the same speech pattern. Another 
+  variable you can see in this example is @surface@ which 
+  will be replaced by whatever the monster is standing on.
+
+The following variables are hardcoded:
+
+@the_monster@   : replaced with definite article plus 
+                  monster name for non-unique monsters
+@Monster@       : as above, but capitalized
+@the_monster@   : replaced with monster name
+@The_monster@   : replaced with capitalized monster name
+@a_monster@     : replaced with indefinite article plus
+                  monster name, if several can exist
+@A_monster@     : as above, but capitalized
+@Monster@       : replaced with plain monster name
+@monster@       : es above, but capitalized
+
+For friendly monsters an additional "your"/"Your" is 
+placed before the monster name, respecting capitalization 
+and grammar (only for the_xxx).
+
+As an alternative there's also @the_something@, 
+@The_something@, @a_something@, @A_something@, @something@ 
+and @Something@, all of which behave like the corresponding 
+monster definitions above but get replaced by "something" 
+and "Something", respectively, should the monster be 
+invisible and the player be unable to see invisible.
+
+But wait, there's more!
+
+@player_name@ : replaced by player name
+
+@surface@ : replaced with whatever the monster stands on
+@feature@ : replaced with the monster's square's feature 
+            description
+
+@pronoun@     : replaced be it, she, he as appropriate
+@Pronoun@     : replaced be It, She, He, as appropriate
+@possessive@  : replaced by its, her, his as appropriate
+@Possessive@  : replaced by Its, Her, His, as appropriate
+
+@imp_taunt@   : replaced by hardcoded imp type insults
+@demon_taunt@ : replaced by hardcoded demon type insults
+
+Also, @says@ will get replaced with a synonym of 'say' that 
+fits a monster's (hardcoded) speech pattern and noise level.
+
+Pre-defined variables in the database include _high_priest_, 
+_mercenary_guard_, _wizard_, _hostile_adventurer_, 
+_friendly_imp_, _hostile_imp_, _tormentor_. There are also a 
+few synonyms defined at the beginning of speak.txt such as 
+for @ATTACK@, @pointless@, @shouts@, @wails@, @yells@ and 
+others.