=======
textadv
=======
by Kyle Miller, 2011

The textadv package is a system written in python for creating
interactive fiction (also known as text adventures) in Python.  Where
most interactive fiction engines seem to have their own programming
language in which to write the games, the approach taken here was to
create a domain-specific language for Python which makes writing these
games easy.  And, an added benefit is that we get to program in
Python, so all of the standard libraries are included.

Unlike many interactive fiction engines, this one is purely rule-based
(much like Inform 7).


------------
Requirements
------------

This system requires the tornado library for Python, and I implemented
the system on Python 2.7.  Beyond it working also in Python 2.6, I
don't know if it works in other versions of Python.


-----------------
Running the games
-----------------

Run, with respect to the root of the repository,

$ ./startserver

Then, point your browser to the URL http://localhost:8888/


------------------------
Generating documentation
------------------------

Much of the engine is self-documenting.  Run ./make_documentation from
the root of the repository.  To document a specific game, such as
Cloak of Darkness, then run ./make_documentation cloak.py

The output is in ./doc (you may need to create this directory first).


----------------
Directory layout
----------------

The games directory contains three test games, testgame2.py (which has
some enterable objects and a ball that's lit), isleadv.py (which is
silly, but a very large test of the system), and cloak.py (which is
the standard Cloak of Darkness).  I would recommend trying isleadv.py
and cloak.py and seeing its source code to get an idea of what this
DSL is like.

Inside this folder is also the main textadv package (I'll label things
as python packages now):

* textadv.basicsetup

This imports everything you probably need.  See isleadv.py for an
example.

* textadv.core

This package contains everything the main game system uses, which
includes a pattern-matching system (patterns), a rule system
(rulesystem).

* textadv.gamesystem

This package contains the parser, the world model, the idea of a "game
context," the relation model, and the action system.  This package
uses textadv.core heavily.

The module actionsystem is the definition of how a player action is
checked and executed.  See run_action in that module for more details.

The idea with contexts is that modal changes may occur in the game,
and the hope is that these will help with these switches (for
instance, it'll probably be possible to play a game inside the game
without much difficulty.  I haven't tried it yet).

The utilities module contains many useful utilities, including
eval_str, which evaluates 'if' statements within strings, among other
things.

The relations module contains models for one-to-many, many-to-many,
etc. relations.

* textadv.gameworld

This package contains the definitions of basic game objects like
rooms, doors, and actors, and it contains the definitions of many of
the basic actions a player may attempt on these objects.

* textadv.tornado

This contains the web interface for playing the games.  One runs
'python textadv/tornado/server.py' in the main repository, and then
points a web browser to the URL 'http://localhost:8888/' to play.


----------------
Acknowledgements
----------------

Many ideas have been taken from reading about Inform 7 and TADS.  I
thank Zarf for codifying on his website ideas similar to the ones I
was thinking about.  Also, thanks to Will Doenlen, Steven Valdez, and
Colleen Josephson for testing the engine.


-------
History
-------

Jul 2011 - Removed object system and made it purely rule-based

Jun 2011 - Implemented a new engine and got a small game working

Oct 2008 - Made an engine in Python, there were problems which made
           game definition much too complicated