File	Date	Author	Commit
data	2023-03-18	Lee Harr	[c6c7d8] fix project url
doc	2009-11-29	Lee Harr	[c5cbbf] add new screenshots for v0.7
lib	2019-12-06	Lee Harr	[d40a95] add setting for robot info panel sorting
robots	2019-10-25	Lee Harr	[d1d8da] reorganize to make pybotwar lib
.hgignore	2018-12-21	Lee Harr	[fb2ffd] tune ignoring log files a bit
.hgtags	2012-08-16	Lee Harr	[ff0f19] Added tag pybotwar-0.8 for changeset 3baeef7bd5e1
.tar-ignore	2018-12-21	Lee Harr	[fb2ffd] tune ignoring log files a bit
COPYING	2009-08-02	Lee Harr	[db1035] add COPYING
README	2019-11-07	Lee Harr	[05c079] update readme
TODO	2019-11-16	Lee Harr	[ee67fd] update todo
announce	2019-10-25	Lee Harr	[d1d8da] reorganize to make pybotwar lib
control.py	2023-03-18	Lee Harr	[f899a7] isAlive to is_alive
pybotwar	2019-10-28	Lee Harr	[ae3ffa] try to create a writeable location when started...

Read Me

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

https://bitbucket.org/leeharr/pybotwar/



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.

As long as you wrote the program yourself, using the
standard Pybotwar API, it should not be a problem, but
do not run robot programs written by other people
without thorough consideration.



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

python3:
    http://python.org/
        (tested with python-3.6.7)

box2d-py:
    http://pybox2d.googlecode.com/
        (tested with pybox2d-2.3.8)
        (pip3 install box2d-py)

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

qtsvg5 (optional -- required if using pyqt5):
    http://pyqt.sourceforge.net/Docs/PyQt5/QtSvg.html
        (tested with python3-pyqt5.qtsvg-5.10.1)

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 program:

    ./pybotwar

If running from the development environment
    (ie. from a cloned mercurial repo)
    use the development flag:

    ./pybotwar -d

Use the -h option for additional help:

    ./pybotwar -d -h

|usage: main.py [-h] [-T] [-n NAME] [-A] [-b NBATTLES]
|               [--robots ROBOT [ROBOT ...]] [--lineup LNAME]
|               [--supertournament] [--supertournament-continue] [-10]
|               [--tournaments [N]] [--results TNAME|TDATETIME] [-g] [-u] [-U]
|               [-Q] [-P] [-D] [-S] [-B]
|
|optional arguments:
|  -h, --help            show this help message and exit
|  -T, --testmode        run in test mode (All robots log. No cleanup on exit.)
|  -n NAME, --tournament-name NAME
|                        tournament name (default=<datetime>)
|  -A, --add-to-tournament
|                        if tournament named in -n already exists, continue it.
|  -b NBATTLES, --battles NBATTLES
|                        number of battles in tournament (default=1)
|  --robots ROBOT [ROBOT ...]
|                        list of robots to load
|  --lineup LNAME        load robots from lineup file
|  --supertournament     run a supertournament (all possible combinations of
|                        robots play in tournaments with the same name,
|                        combining all stats.)
|  --supertournament-continue
|                        internal use only.
|  -10, --top-10         show top 10 robot stats (implies -g)
|  --tournaments [N]     list N most recent tournaments and exit (default=5)
|  --results TNAME|TDATETIME
|                        show results for tournament TNAME or at TDATETIME
|  -g, --no-graphics     non graphics mode
|  -u, --quiet           reduce output
|  -U, --very-quiet      no output
|  -Q, --pyqt-graphics   enable PyQt interface
|  -P, --pygsear-graphics
|                        enable Pygame (and Pygsear) interface
|  -D, --upgrade-db      upgrade database (WARNING! Deletes database!)
|  -S, --reset-qt-settings
|                        reset Qt settings
|  -B, --app-debug       enable app debug log


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/Python36.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:
https://bitbucket.org/leeharr/pybotwar/wiki/Home


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:

    ./pybotwar -d -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:

    ./pybotwar -d -T




TOURNAMENTS

At the start of each battle, the robots are always placed in
the arena at random locations and with random orientations.
Also, many robots 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 vs r2 (5 battles)
r1 vs r3 (5 battles)
r2 vs r3 (5 battles)
r1 vs r2 vs r3 (5 battles)

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