README for BAGS v0.1
Beany Adventure Game System

Copyright 2005 M. Aaron Wadley

This software contains BeanShell <www.beanshell.org> under the terms of the
LGPL.

Java(TM) is a trademark of Sun Microsystems <www.java.com>

==============================================================================
 Table of Contents
==============================================================================
* Introduction
* Why another IF interpreter?
* Features
* Future development
* Requirements
* Installation
* Running BAGS
* Implementing games
* License

##############################################################################
 Introduction
##############################################################################
BAGS is an engine for running Interactive Fiction (IF) aka Adventure Games.
If you're not familiar with IF, I suggest checking out www.ifarchive.org.  This
is generally regarded as the central repository for IF.  There are some links
to some good beginners resources there too.

##############################################################################
 Why another IF interpreter?
##############################################################################
I wrote BAGS to "scratch an itch", so to speak.  I was an avid fan of IF and 
had decided to write my own, but I didn't care for any of the languages out 
there; Infocom, TADS, HUGO, etc.  I am a Java programmer by profession and 
hobby, so I decided to try writing my own interpreter.  When I discovered 
BeanShell, I was in heaven.  It was the perfect marriage of my two favorite
programming environments, Bash scripting and Java.  After a few days of coding,
the core of a workable engine was born.

My hopes for BAGS have now grown beyond an interesting experiment.  I see a
need in the IF world for a truly cross-platform environment for IF authors to
reach a broad audience.  While the current crop of languages today have 
interpreters available for many platforms, they are generally each a unique 
product, each with its own set of features and quirks.  Through the use of
Java, the same interpreter can be used on any platform, providing the user with
a unified experience no matter which platform they happen to be using.

In addition, the introduction of graphics and sound to IF has some exciting
possibilities.  Support for these features is spotty among today's interpreters
and is virtually non-existent for my preferred platform, GNU/Linux.  Thanks
to the nature of Java and it's support for multimedia, BAGS will allow the 
easy introduction of such features into IF games.  Since the IF games 
themselves are implemented in BeanShell script, any feature available to Java
is available be used in an IF game.

I suppose I should mention that BAGS was written without any reference to 
the source code from any other IF interpreter.  I based my design solely upon
my experience of playing IF games.  There are probably better ways to do 
many of the things I did in BAGS, but this is just a first cut.  Ideas for 
enhancements, bug reports, comments, complaints, etc. are always welcome. 
Please feel free to contact me at admin@cyberlizard.org with any of the above.

Most of all, thank you for taking the time to look at this and I hope that you
come to enjoy it!

##############################################################################
 Features
##############################################################################
The basic IF features are currently implemented; navigation, object 
interaction, inventory, examination of surroundings.  A sample game comes with
this distribution that demonstrates several of these features.

##############################################################################
 Future development
##############################################################################
A lot of things will eventually go into BAGS.

##############################################################################
 Requirements
##############################################################################
In order to run BAGS, you must have the latest Java Runtime Environment 
installed on your system.  Theoretically, it should run with version 1.4 or 
greater, but I have only tested it with 5.0 (aka 1.5).

##############################################################################
 Installation
##############################################################################
Eventually, the goal is to make BAGS available via Java WebStart, eliminating
the need for any specialized installation.  However, this is currently not
implemented.  Please read the INSTALL file that came with this distribution
for specific installation instructions.

##############################################################################
 Running BAGS
##############################################################################
Currently, BAGS has only been tested on Linux, Cygwin and Windows.  The 
instructions below should work, but some tweaking to the scripts starting BAGS
might be needed, depending on your setup.

Depending on which platform you are running, there are different ways of 
starting BAGS.

Unix-like platforms (Linux, Cygwin on Windows, Solaris, OSX)
NOTE: This procedure has only been verified on Linux and Cygwin. YMMV

- The Java runtime executable (java) must be in your path.
- From the command line, cd to the directory where you extracted BAGS.  
- If you installed BAGS in $HOME, then all you should be all set.  Jump down
  to the end of these instructions.
- Open the file 'bags' with your favorite text editor.
- Change the line below the phrase "# Change this to match your environment"
  to reflect where you installed BAGS.

- type './bags' (or './cygbags' if you're using Cygwin)

Windows
- The Java Runtime Environment must be installed
- Open the folder where you installed BAGS
- Double-click on the bags.bat file (depending on your settings, you might
  not see the file extension .bat)

You should now see a file selector box.  To run the sample game, surf to the 
folder where you installed BAGS.  Go into a subdirectory called 'wadley' and
select the file bags.properties.

Have fun!

##############################################################################
 Implementing games
##############################################################################
Please see the accompanying file gameManual.txt for detailed information.

##############################################################################
 License
##############################################################################
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

See the file COPYING, included with this distribution, for the text of the 
GNU General Public License

