This is the archive for the Choose Your Own Adventure library designed for
the TADS system.  This archive contains the following files:

1. readme.txt
	This text file.  It should contain the manifest for this archive along
	with a few words on how to use the library.

2. cyoa_lib.t
	This is the actual library.  It replaces the adv.t/std.t combination
	that comes with TADS and contains the basic definitions necessary to
	make a stand-alone library.

3. bluehunt.t
	This is a sample game created using the cyoa_lib.t library.  It is
	hoped by the author that anyone who wishes to use the library consult
	this sample as the 'manual' for the library.

4. bluehunt.gam
	A compiled version of bluehunt.t.

-----------------

How to use the library:

The library defines all the necessary objects that the TADS run-time needs to
function.  In addition, it defines a single class that is used to control the
game states: the 'Place' class.

The Place class uses several members:

  1. statusLine
  	This is used by the TADS run-time for the text that goes on the status
	line.  For example:
		asking_a_favour: Place
			statusLine = "To Ask or Not To Ask"
		;
	This text will show up as soon as the player reaches the "What do you
	want to do?" prompt.  It should be descriptive of the player's current
	situation.  Think of it as the 'incidental music' for the scene.

  2. desc
  	This is a long text string which describes the player's current
	situation.  Unlike the standard convention in text adventures, which
	suggest only a few lines of text per room (lest the player get bogged
	down in detail), this can be quite long indeed.  The difference here is
	that you're actually writing a story, telling the player what's going
	on.  A screenfull or so of text is not unacceptable.

	In addition, the library will automatically output a "\t" (tab)
	character before printing the description, so your first line doesn't
	need one.

	An example:
		asking_a_favour: Place
			statusLine = "To Ask or Not To Ask"
			desc = "You stumble into the ship's hold, where the the
				cargo is being held for the long journey. You
				pick among the crates and boxes, looking for a
				good place to sleep, when you stumble across an
				old man!\n
				\t\"What are you doin' here?\"\ he asks.\n
				\t\"I.., um..,"\ you stammer, unsure of what to
				say.\n
				\t\"You stowin' away too?\"\ the old man grins
				at you.\n
				\tYou figure you've got nothing to lose.
				\"Yeah,\"\ you admit.\n
				\"Well, I've been doin' this for a long time,
				sonny,\"\ he says. \"I knows all the ins an'
				outs of the stowin' bizness.\""
		;
			

  3. choices
  	This is where you present the choices to the player.  It's a single
	text string, formatted however you like. My suggestion would be to
	present the options as in a multiple choice exam, but you are by no
	means limited to this.  Just so long as your choices are numbered.

	As an example, assume we're continuing the 'asking_a_favour' object
	from the 'desc' description above:
		asking_a_favour: Place
			// ...
			choices = "\t1. Ask for pointers on surviving.\n
				\t2. Ask for some food.\n
				\t3. Get away from the old man quickly."
		;
	
	Note that you have to insert the initial tab yourself (if that's how
	you want to enumerate the choices).  You could also do something like
		choices = "(1) Ask for pointers..., (2) ask for food, or (3)
			get away as quickly as possible."
	Just remember the library is looking for responses in the form of a
	number.

  4. choice_X
  	This is the final piece of the puzzle. When a user enters a choice from
	the list you present, the library then calls one of the 'choice_X'
	methods (choice_1, choice_2, ..., choice_9).  You should only provide
	those choices that you give in the 'choices' member.  The library will
	check to see if you've defined the choice that the user enters, and
	will call the method if you did, in fact define it.  If you didn't
	define the method, the library will print a message to the player that
	he/she must choose from the menu presented.

	You may put anything you like in the choice_X methods. The return value
	of the choice will define the next 'Place' object that the library
	displays.  A return value of 'nil' indicates that the library will not
	move from the current place.

	To continue the example from above:
		asking_a_favour: Place
			// ...
			choice_1 = survival_skills
			choice_2 = food_request
			choice_3 = run_away
		;
	
	Note that you could also have referenced other 'Place' objects in these
	choices, as in:
		choice_1 = run_away.choice_3
	which means that, if the player selects choice 1 at this current
	'Place', it will result in the same thing as if the player picked
	choice 3 from the Place 'run_away'.

	Additionally, you can have code executed by the choices:
		choice_2 = {
			"\tYou beg for food, and the old man chases you off to
			another part of the ship...";
			return in_another_bind;
		}

	The library only supports choice_1 through choice_9.
	
That about wraps it up for the Place class.  You also will want to come up with
various endings for your story.  To do this, use the die() function in
conjunction with the variable "global.death_msg".  When the player reaches an
end to your story, you can make one of the choices call die(), like so:
	choice_3 = {
		"\tYou turn to run away from the old man, but he pulls out a
		knife and throws it into your back.";
		global.death_msg := 'been killed';
		die();
	}

The die() function prints out "You have" followed by whatever is in the
death_msg member of the global object.  So, in this case, the player will see:

    You turn to run away from the old man, but he pulls out a knife and throws
it into your back.

    * * * You have been killed. * * *

And then the player will be be presented with the standard restart/restore/
undo/quit choices.

The last two items are the 'intro' object and the 'version' object.  The
library uses a single method in the 'intro' object: 'desc'.  Set this to
whatever text you'd like displayed when the player starts (or restarts) the
game.

The 'version' object also should define a 'desc' method.  This should contain
the title of the game, the serial no., relase no., any copyright information,
and so on.  See bluehunt.t for an example of this.

You should also feel free to define any additional commands that the game
should recognize.  Do a 'replace' on the 'action( actor )' method of the
'helpVerb' object to tell the user about these commands.

-----------------

That's it.  I hope this little manual helps you create CYOA-type games.  If
you have any suggestions for improvements, please feel free to email them to
me.  Currently (as of Feb 1998) my email address is olorin@world.std.com

Thanks for considering using this library.


	Mark J. Musante
	Cedar Rapids, Iowa