README

pybotwar is a fun and educational game where players
write computer programs to control simulated robots.

http://pybotwar.googlecode.com



INTRODUCTION

Your task is to create a computer program to control a
robot for the arena. The last robot alive is the winner.

Robot programs run in separate processes from the main
simulation, and communicate with the main program over
standard input and standard output channels. Theoretically,
this means that the robots could be limited in the amount
of system access they have, and how much of the system's
resources they can consume.

CAUTION!
Right now, that is not the case. Robot programs run
as regular Python programs, using the regular Python
interpreter, and can do anything any other program
can do.

In the future, I intend to implement some kind of
sandboxing for robot programs, but that is not done.



INSTALLATION

Make sure the required dependencies are installed.

pybotwar uses pybox2d for the physical simulation,
and uses either pyqt or pygame and pygsear for the
visualization.

Unpack the pybotwar archive and run the program
from the unpacked folder. No installation is needed,
but you may need to change the configuration. See
CONFIGURATION for details.



DEPENDENCIES

python:
    http://python.org/
        (tested with python-2.7.5)

pybox2d:
    http://pybox2d.googlecode.com/
        (tested with pybox2d-2.3b0)

pyqt4 (optional, but strongly recommended):
    http://www.riverbankcomputing.co.uk/software/pyqt/
        (tested with pyqt-4.10.3)

pygame (optional):
    http://pygame.org/
        (tested with pygame-1.9.1)

pygsear (optional -- required if using pygame):
    http://www.nongnu.org/pygsear/
        (tested with pygsear-0.53.2)


RUNNING

Run the main.py program with Python:

    python main.py

Use the -h option for additional help:

    python main.py -h

| usage: main.py [-h] [-T] [-t [TOURNAMENT]] [-n NBATTLES] [--supertournament]
|                [-g] [-Q] [-P] [-D] [-S] [-B] [--robots ROBOT [ROBOT ...]]
| 
| optional arguments:
|   -h, --help            show this help message and exit
|   -T, --testmode        run in test mode
|   -t [TOURNAMENT], --tournament [TOURNAMENT]
|                         run a tournament
|   -n NBATTLES, --battles NBATTLES
|                         number of battles in tournament
|   --supertournament     run a supertournament
|   -g, --no-graphics     non graphics mode
|   -Q, --pyqt-graphics   enable PyQt interface
|   -P, --pygsear-graphics
|                         enable Pygsear interface
|   -D, --upgrade-db      upgrade database (WARNING! Deletes database!)
|   -S, --reset-qt-settings
|                         reset Qt settings
|   -B, --app-debug       enable app debug log
|   --robots ROBOT [ROBOT ...]
|                         list of robots to load


CONFIGURATION

The first time you run pybotwar it will create an empty
configuration file called conf.py

Look in defaults.py to see the values which can be changed.

IMPORTANT NOTE!
Windows users especially will need to change the value for
subproc_python or the program will not run.

Add a line to conf.py like ...

    subproc_python = 'C:/Full/Path/To/Python26.exe'


Also note that it is not necessary for the user to have write
access to the program directory to use the game, but the conf.py
file must be created first. If using the PyQt interface, all
users will have their own settings file and conf.py will not
be used, but the file must be present.



CREATING NEW ROBOTS

Copy the template.py file to a new file in the robots
folder, for example 'mynewrobot.py'


In your new module, add initialization code to the .initialize()
method if needed, or you can delete the method.

The .initialize() method is called once, immediately after the
robot is created, and must return in less than a second or
the robot will be placed in an error state and removed from
the battle.


Add code to generate your robot's response to the .respond()
method.

The .respond() method will be called 60 times per second as
the battle continues and it must return in less than 0.015
seconds or the robot will be placed in an error state and
removed from the battle.


See the robot.Robot class for useful methods to set the
response, or the example robots for hints on how to use
those methods.

For more information, see the pybotwar wiki:
http://code.google.com/p/pybotwar/w/list


STARTING A BATTLE

To use your new robot in a battle, choose Battle -> New Battle.
Select your robot on the left and click "Add," then either
save the robot lineup for future use or click "Start Battle."


To use your robot in pygame or text mode, you can specify the names
of the robots for the battle from the command line:

    python main.py -g --robots myrobot1 anotherrobot robot05


You can also use the older method and modify conf.py directly.
Add a line to conf.py with the name of your new module:

    mine = 'mynewrobot'

Add your module reference to the robots list:

    robots.append(mine)

Or, if you only want to test your own robot:

    robots = [mine]

You can also run with multiple copies of the same robot:

    # Three copies of example robot 1 and three of my new robot
    robots = [r1, r1, r1, mine, mine, mine]

If you want to run with only your new robot, be sure to
run in test mode, or the battle will be over before it
begins:

    python main.py -T




TOURNAMENTS

Robots are placed in the arena at random locations and with
random orientations. Also, many robots will use random numbers
to determine which way to go and when to perform their actions.
Therefore, each time the same set of robots are placed in the
arena, the results may be different.

To determine which robots are truly the strongest, run a
tournament. A tournament is a series of battles run with the
same set of robots. Statistics will be kept during the series
and reported when the series is complete.


SUPERTOURNAMENTS

A supertournament is a series of tournaments where the participating
robots are matched up in all possible combinations. For instance,
a 5-game supertournament with robots r1, r2, and r3 would run a
series of 5-game tournaments like this:

r1, r2
r1, r3
r2, r3
r1, r2, r3

This will result in a total of 20 battles. This can take a long
time, so you may want to run supertournaments either in text mode,
or run them in the background.

All of the statistics from all of the tournaments are combined in
to one report by the end of the supertournament.

Some robots do well at surviving, but not so good at taking other
robots out of the game. Some do well early on, but have trouble
finishing off the last opponent.

To really get a good idea of which are the strongest robots, run
a supertournament instead of a plain tournament.


HISTORY

pybotwar was inspired by the game RobotWar that existed
for the Apple ][ in the early 1980s. However, the method
of coding is more akin to the style of programs used
for the FIRST robotics competition, where a particular
user-defined method is called repeatedly (60 times
per second in this case) and must finish in a set
amount of time to avoid putting the robot in to an
error state and disabling it.

RobotWar:
http://en.wikipedia.org/wiki/RobotWar

FIRST Robotics Competition:
http://en.wikipedia.org/wiki/FIRST_Robotics