Instructions for using converse v2.0            (Copyright (C) James Cole 1997)
------------------------------------

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.   Following this
is a description of the new ask about feature in version 2.

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

How it works
------------
Here I'll provide a brief description of the syntax of Converse, in the 
context of a simple game.  

A Simple Game (using talk to <x>)
---------------------------------
Here is a quick tutorial, to show the basics of using Converse.  If you want
to skip it, a summary of usage appears afterwards.

Step 1 Include the file:
        converse.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, which in this case is 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 talk to Joe, type 'talk to joe' (assuming that you have called the
        actor joe)  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 your statements.  
       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
       those 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,
       while these last two are 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 single 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.
       

Summary
-------
   - An actor you wish to converse with must have the verDoTalkTo and 
     doTalkTo methods defined.
   - Call the converse function within the doTalkTo method.  It takes the
     NPC the conversation is with (usually self, i.e. that NPC) and the
     property pointer of the first thing to be said in the conversation.
   - Conversations consist of lists; a list for each thing the NPC will say,
     and a list of lists for your choices in replying.
   - Each list is a ['what to say', &response-prop] pair
   

Using 'Ask <x> about <y>'
---------------------------------------
The AskAbout function allows you to ask characters specific questions about
objects.  So, if you were to ask someone about the governor, you could ask
about where he/she lives, the person's opinon of him/her, etc.  Typically, 
for most objects you'd just want the player to be able to ask a single, 
general, question about it.  This feature is there so you specific 
questions in certain cases when you want that extra functionallity.

Hopefully, the example below should be enough to give you the gist of it.


---------------- begin cut here ---------------------------------------------

#include <world.t>
#include "converse.t"      

kitchen : Room
   sdesc = "kitchen"
   ldesc = "A fairly large kitchen in Fred's House."
;

shovel : Item
   noun = 'shovel'
   sdesc = "shovel"
   ldesc = "It's a mighty sturdy lookin' shovel"
   location = kitchen
	
   askPropPtr = &askAboutShovel
   verIoAskabout(actor) = {}
   ioAskabout(actor, dobj) = {     
	askAbout(dobj, self);
   }
;
  
fred : Actor
   noun = 'fred'
   sdesc = "fred"
   actorDesc = "Fred"
   ldesc = "Fred looks raggeddy in his old work clothes."
   location = kitchen

   // conversation stuff.
   verDoTalkTo(actor) = {}
   doTalkTo(actor) = { conversation(self, &greet); }
   greet = [['"hi there fred,".\n', &hiResponse], ['"Hiya fredo".\n', &hiResponse]]
   hiResponse = ['"Uh, hi." he replies.\n', nil]

   // ask stuff.
   verDoAskabout(actor, io) = {}
   dontKnow = "I don't know much bout that"    
   askAboutShovel = [['Hey Fred, what can you tell me about this here shovel?',
                       &aaShovelResp], ['This looks like a good shovel.', &aaShovelResp]]
   aaShovelResp = ['Looks mighty fine for a bit a\' diggin', nil]
;

---------- end cut ----------------------------------------------------------

A few notes about AskAbout
   - if the NPC doesn't define the object's askPropPtr property pointer
     (with which to start a conversation about the object), then the actors
     default response property 'dontKnow' will be called.  
   - if an object doesn't have an askPropPtr property defined, then if you
     ask an NPC about it, you'll get the actors dontKnow message.
   - It's probably best to only let the character ask about physical objects,
     like a tree, a rock, etc.  Let the talk to feature handle the other 
     types of things.
   - If don't wish to have the AskAbout feature in your game, you'll have to
     comment out the code for it in converse.t.

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.
