Text Adventure Game Maker

text_game_maker is a framework for building simple text-based games. Supports Python 2 and 3 on Linux and Windows (tested on Debian and Windows 10).


  • Builder API pattern that implements a 2D tile-based grid system for building maps and creating game objects with a few lines of Python.
  • Flexible object model for defining game objects and NPCs. Many useful game objects and behaviours are pre-defined so you can start making a game straight away, but these classes are easy to extend if you need to implement your own custom game objects.
  • NPCs that you can actually speak to, like a chatbot. text_game_maker NPCs allow you to define custom responses and contexts for discussions using regular expressions, so you can build an NPC which responds with some contextual awareness like a chatbot.
  • Arbitrary saving/loading of game states. All game objects can be serialized to, or loaded from, JSON data.
  • Flexible and extensible parser. The parser that handles game input already has a lot of useful commands and behaviours built-in. However, any of the built-in commands can be disabled if necessary, and the parser provides methods that allow new commands to be defined.
  • Configurable input/output streams. text_game_maker allows custom handlers to be set for handling user input, and for displaying game output. By default, text_game_maker will use a prompt-toolkit session that interacts with stdin and stdout of the process it is running in. Defining custom input/output handlers allows you to run your game, for example, as a slack bot instead (see scripts/text-game-slackbot-runner.py).
  • text_game_maker has a music system that allows polyphonic music (not fancy, just simple tones that sound like an old Nokia ringtone, but with full polyphony) to be written as simple text files that can be loaded and played during the game (see PTTTL). pygame is used for playback of the raw audio samples.
  • Much more… check out the API documentation!

Getting started


pip install text_game_maker

Run the example map

python -m text_game_maker.example

Writing maps

  1. Write a class that extends the text_game_maker.utils.runner.MapRunner class and implements the build_map (and optionally build_parser) methods. See example-map/example_map.py and the API documentation for reference.

  2. Run text_game_maker.runner with the name of the .py file containing your MapRunner class, e.g.:

    python -m text_game_maker.runner mymaprunner.py

    In this example, text_game_maker.runner will import the mymaprunner.py file and run the first instance it finds of a class which is a subclass of text_game_maker.utils.runner.MapRunner

To run a MapRunner class as a slackbot to play your game over slack, the procedure is the same, except use the text_game_maker.slackbot_runner script, e.g.:

python -m text_game_maker.slackbot_runner mymaprunner.py

Note that when using the slackbot runner you must have already created a bot user in your slack workspace, and the API token for the bot user must be available in an environment variable named SLACK_BOT_TOKEN.