- Documentation improvements and an additional example. No functional changes.

git-svn-id: svn://svn.code.sf.net/p/crossfire/code/maps/trunk@10422 282e977c-c81d-0410-88c4-b93c2d0d6712

python/misc/npc_dialog.py

@@ -17,12 +17,34 @@
 # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 #
 #
-# This is a simple script that make use of CFDialog.py and receive it's
+# This is a simple script that makes use of CFDialog.py and that receives
-# parameters from a JSON inside the event message. Alternativey, the JSON
+# parameters from a JSON inside the event message. Alternatively, the JSON
-# parameters, if >= 4096 characters, can be stored in a file that will be
+# parameters, if >= 4096 characters, can be stored in a separate file.
-# loaded. Use the classical script parameter to specify relative location
+# Use the classical script parameter to specify relative location of dialog.
-# of dialog.
+#
-# exemple
+# An example of a map file entry is:
+#
+# arch guildmaster
+# name Sigmund
+# msg
+# 
+# endmsg
+# x 11
+# y 7
+# resist_physical 100
+# resist_magic 100
+# weight 50000000
+# friendly 1
+# stand_still 1
+# arch event_say
+# name start/sigmund.msg
+# title Python
+# slaying /python/misc/npc_dialog.py
+# end
+# end
+#
+# An example of a JSON dialog similar to the one described in CFDialog.py is:
+#
 # {
 #   "location" : "test_grandpa_01",
 #   "rules": [
@@ -45,18 +67,34 @@
 #     "msg" : ["What ?", "Huh ?", "What do you want ?"]
 #   }
 # ]}
-# The pre and post in rule are variable to test and set depending on that dialog rule.
+#
-# For example, first rule applie if "hello" is set to "0"  (default) and immediatly 
+# "match" is what CFDialog describes as a keyword, and corresponds with what
-# sets it to "1" when rule is used.
+# the player/character says that the dialog will respond to.
-# the Double [ around pre and post are needed. The pre and post are
+#
-# arrays of arrays. Each item in pre and post is an array of [variable,value]
+# "pre" is a list of CFDialog preconditions that identifies flags that must be
-# The match is the rule to apply to what user says
+# set to a particular value in order to trigger a response if a match is
+# detected.
+#
+# "post" is a list of CFDialog postconditions that specify flags that are to be
+# set if a response is triggered.
+#
+# Above, the first rule is applied if the player/character says "hello" or "hi"
+# and if the "hello" flag is set to "0" (default).  When the rule is applied,
+# the "hello" flag is then set to "1".
+#
+# The Double square braces ([[]]) around "pre" and "post" are required. "pre"
+# and "post" are arrays of arrays. Each item in "pre" and "post" is an array of
+# [variable,value].
+#
+# "msg" defines one or more responses that will be given if the rule triggers.
+# When more than one "msg" value is set up, the NPC randomly selects which one
+# to say each time the rule is applied.
 
 import Crossfire
 import os
-
 from CFDialog import DialogRule, Dialog
 import cjson
+
 def ruleConnected(character,rule):
         m = character.Map
         m.TriggerConnected(rule.connected,1)
@@ -90,3 +128,4 @@ for jsonRule in parameters["rules"]:
         
 if speech.speak(Crossfire.WhatIsMessage()) == 0:
     Crossfire.SetReturnValue(1)
+