======= 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

Textadv

Install / Use

README