555-BOOM!
=========

  A Puzzle Game and Electromechanical Sandbox
  by Gregory C. Ewing
  greg.ewing@canterbury.ac.nz

This is a game involving telephones, relays, rotary switches, and other
electrical things that make nice whirring and clicking noises. As well
as challenging yourself to solve the puzzles, you can also use the
comprehensive built-in level editor to create new puzzles for yourself
and others, or just to play around and have fun with the parts.

This game began as an entry in the PyWeek 5 game programming competition:

  Entry in PyWeek #5:  http://www.pyweek.org/5/
  Team:                gregpw5
  Members:             Gregory Ewing


INSTALLATION
------------

* MacOSX version:

Just copy the distribution folder onto your disk anywhere you like, and launch
the game by double-clicking the 555-BOOM! application.

* Windows version:

Copy the distribution folder onto your disk anywhere you like. To run the
game, launch the "run_game.exe" program in the "Game" folder. You may want to
create a shortcut to this on your desktop or in some other convenient place.

* Linux version:

Copy the distribution directory onto your disk anywhere you like. To run
the game, execute the "bin/run_game" script. You may want to put a link
to this script somewhere on your search path.

* Other systems:

The source distribution should be usable on any Unix-like system with
suitable versions of Python and pygame installed. See Dependencies below.
To run the game, cd to the "Game" directory and execute "python run_game.py".

* All versions:

The "Saves" and "Mods" folders are there for your convenience; use them if
you want, or put your saved games and custom levels elsewhere if you
prefer.


DEPENDENCIES
------------

* MacOSX
* Windows

The MacOSX and Windows versions are fully self-contained and have no
dependencies.

* Linux

The Linux version requires a standard installation of Python 2.3 or
later to be present, executable with "/usr/bin/python". If your
Python is called something else, you can edit the bin/run_game script.
All other required libraries are included in the distribution and need
no installation. Most modern Linux installations should already contain
a suitable Python.

* Source

The source distribution has the following dependencies:

  Python:     http://www.python.org/    version 2.3 or later
  PyGame:     http://www.pygame.org/    version 1.7.1 or later
  
  PyGame must be installed with PNG image, TrueType font and
  Ogg Vorbis sound support. (Sound support is optional; the game
  will run without it.)


HOW TO PLAY THE GAME
--------------------

Click the "Tutorial" button on the main menu and it will teach you
everything you need to know.


LEVEL EDITOR
------------

There is some documentation on how to use the level editor in
"LevelEditor.html" in the "Doc" folder.


COMMAND LINE OPTIONS
--------------------

If you run the game from a Unix shell or Windows command window, you
can load a specific level by giving its pathname as a command
line argument.

There are also some command line options that may be useful. Use
the "--help" option for details.


LICENSE
-------

This is free software. You may use and redistribute it freely in any way,
including creation and distribution of derivative works. No promises are made.
Use it at your own risk.

The Bitstream Vera fonts included in this application are covered by their
own (liberal) license. A copy of that license is included alongside the
font files. (If you find the fonts, you'll find the license. If you can't
find the fonts, you won't be able to do anything that their license
disallows, so don't worry.)


COMMUNITY
---------

If you like this game, or have any comments, suggestions or bug reports,
feel free to email me or discuss it in the pygame mailing list.

If you come up with any levels you'd like to share, let me know and
I'll see about making them available on a web site somewhere. It would
be great to start up a 555-BOOM level swap meeting place!

  My email address:     greg.ewing@canterbury.ac.nz
  PyGame mailing list:  pygame-users@seul.org

Have fun,
Greg
