Instructions for using converse.t
---------------------------------

Introduction
------------
To demonstrate how to use 'converse' I'll use an example.  Throughout this 
I'll explain in stepwise fashion what to do.  I'll also point out any 
things you'll need to remember.  I've written it to make it as simplistic as 
possible, so (hopefully :-) ) should be easy to understand.  

This example assumes proficiency with TADS.  If you're having any problems
with TADS there's documentation available somewhere in the Interactive Fiction
archive located at: ftp://ftp.gmd.de/if-archive/
You could also try posting to the newsgroup for developing Interactive 
Fiction: rec.arts.int-fiction

A Sample Game
-------------

Step 1 If you are using adv.t include the file:
        converseADV.t into your game.
       If you are using WorldClass include the file:
        converseWC.t into your game.

Step 2 Create a simple room.  (Preferably the secret headquarters for the 
       agnostic jugglers of Vienna, but anything will do) 

Step 3 Create an actor within that room called joe.  We'll make it so we
       can talk to joe.

Step 4 In the code for joe add the lines:

       verDoTalkTo(actor) = {}
       doTalkTo(actor) = {
          conversation(self, &greet);
       }

       Whenever we want to make a conversation between the player and a NPC,
       we call the function 'conversation'.  It takes as parameters the actor
       to have the conversation with, joe (self), and the property pointer to
       the start of the conversation.  This property pointer points to a 
       property within the code for Joe.  So we have to add a property in the 
       code for Joe called greet.

Step 5 OK, now we want to add the greet parameter into joe.  
       Add the following line into the code for joe:

       greet = [[' "Hi there joe."\n ', nil], [' "How\'s it going joe?"\n ',
                  nil]]

       Note that this is a list of lists.  Each element of the list, a list 
       itself, represents something your character can say to joe.
        
       Run the code now and see the results.
       (To select a thing to say, press the corresponding number on the 
        keyboard and press enter.)

       Notice that you had a choice of the two things to say?
       Notice that when you chose one of the two possible things to say, it
       was just displayed to the screen and then nothing happened? 
       Lets look at the greet property to see why.
       
       The first element of the list is: [' "Hi there joe."\n ', nil]
       ' "Hi there joe." ' this tells the system one of the things you can 
       say.  The next element in the list 'nil' tells the system that the 
       conversation ends.
       The same applies for the second element of the greet list:
         [' "How\'s it going joe?"\n ', nil].
   
       NOTE: Don't let the double quotes (") in the greet property put you 
             off.  They're only there to make what the player and NPC says
             appear in the game as spoken, like: "Huh, how bout that".  
             Remember, what you want to be displayed to the screen will be
             held in a string, using the single (') quotes. 

Step 6 Adding a bit more to the conversation.
 
       OK now we want joe to reply to what you have said.  
       Modify the greet property to look like this:
       greet = [[' "Hi there joe."\n ', &hiReply], 
                [' "How\'s it going joe?"\n ', &howsItGoingReply]]

       now add these two lines of code to code for joe:
       hiReply = [' "Hi", joe replies.\n ', nil]
       howsItGoingReply = [' "Not bad," he says.  "Yourself?"\n ', 
                            nil]

       notice that the names of these two properties are the same as the
       property pointers in the greet property?  So if you chose
        "Hi there joe" to say, the game will come to the &hiReply instead of
       the nil and know to continue the conversation on using the hiReply
       property.

       You might noticed something different about the last two properties
       compared to the greet property.  The greet property is a list of lists,
       these last two are only just lists.  That's because greet is something 
       you say; usually you have a choice of things to say, each of which 
       being a list within the whole list.  The last two lists are something 
       the NPC, joe, is saying back to you.  Because joe will only ever have 
       one reply to each thing you say it's just a list.

       Now try running the game.

Step 7 Adding more to the conversation.  

       If you ask Joe how he's going, he'll reply with "not bad, yourself?"
       If you play the game you'll notice that the conversation will stop
       at this point; that's because of the nil in the list there which 
       signifies the end of the conversation.
       Try replacing the nil with a property pointer so that you can reply.

Well that's pretty well it.  If you have any trouble with this, email me,
at jrcole@ozemail.com.au

Extra stuff
-----------

- The NPC can start a conversation too.  Just make the property pointer
  you pass to the conversation function point to a list rather than a list
  of lists.  The function will automatically detect this as being the NPC 
  starting the conversation.  (Note that the "next" property in the 
  conversation, what you're player will say in response, will need to be
  a list of lists.)

- If there is only one choice for the player to say the game will 
  automatically display it; rather than the player having to choose it.