Battle is a distributed framework which allows users to programme the control algorithms for a robot, then run it within a simulation, to see how it performs against other robots.

The framework consists of a server (Server.exe), which runs the simulation. A viewer client (Viewer.exe) can be used to connect to the server, to view the state of the simulation. An API is provided which can be used to programme a robot controller client. The controller client connects to the server, inserts a robot, then sends it commands to control how it acts within the simulation environment. The API is provided in both C++ and C#.


The following development environments are supported for creating robots:



If you aren't using Visual Studio 2003 or 2005, then to run the viewer and other utilities you will need v1.1 of the .NET framework. The framework includes the free csc command-line compiler. You will also need v2.0 of the .NET framework if you wish to do .NET 2.0 development using the command-line compiler. You can download the framework from Microsoft at

Visual Studio 2005 Express is a free version of Visual Studio 2005 which can be downloaded from Microsoft at

To use the 3D display option in the viewer, you will need DirectX 9 or newer, and a reasonable 3D video card. If you have Windows XP you may already have a sufficiently recent version of DirectX. Otherwise, you can download DirectX from Microsoft at

Running a sample simulation

The basic steps to run a sample simulation are as follows:

  1. Run Server.exe.

  2. Run Viewer.exe, and use the File -> Connect command to connect to the server.

  3. Run one or more of the sample robot clients, via one of the batch files:

    • Samples\RunSimpleRobot.bat
    • Samples\RunSimpleRobotNet.bat
    • Samples\RunDumbRobot.bat
    • Samples\RunDumbRobotNet.bat
    • Samples\RunCooperativeRobots.bat
    • Samples\RunCooperativeRobotsNet.bat
    • Samples\RunInteractiveRobotNet.bat

    The SimpleRobot, DumbRobot and CooperativeRobots samples are written in C++, and the SimpleRobotNet, DumbRobotNet, CooperativeRobotsNet and InteractiveRobot samples are written in C#.

    The dumb robots just move around in a circle and fire randomly.

    The simple robots aren't very smart, but they are smart enough to wander around the map randomly until they find another robot, and then try to kill them. The dumb robots make good fodder for the simple robots.

    The cooperative robots demonstrate how to use a single exe to control multiple robots. They contain a leader robot which operates similarly to simple robot (wanders around randomly until it finds a robot to kill) and a follower robot which wanders around randomly until the leader finds a robot, and then tries to attack the same robot as the leader.

    Each of the sample robots includes solution files for Visual Studio 2003 (with a suffix of 71 for v7.1) and Visual Studio 2005 (with a suffix of 80 for v8.0). The simple robot sample also includes solution files for Visual C++ 6.0 (with a suffix of 60), and batch files which use the csc command-line compiler (with a suffix of 11 or 20, for targeting .NET 1.1 or 2.0 respectively).

  4. Watch the battle!

When first started the viewer defaults to 2D mode. In this mode the rendering of the simulation can be moved by dragging it with the left mouse button. The mouse wheel can be used to zoom in and out.

To switch to 3D mode, use View -> 3D. In this mode dragging with the left mouse button can be used to move the world (ie pan the camera), the mouse wheel can be used to zoom in and out, and dragging with the right mouse button changes the view angle.

While in 3D mode, if you choose the View -> Follow Selected Robot menu item and then select a robot in the list at the top left of the display, the camera will follow the selected robot.

Use View -> 2D to switch back to 2D mode.

Creating your own robots

The sample robots are the best place to start to work out how to configure robot projects, and how to use the API to develop a robot.

The following are the steps to create a robot console application in your choice of language (C++ or C#):



The general stages of a robot controller programme are as follows:

  1. Create a Controller class.
  2. Connect to the server.
  3. Create a robot.
  4. Set its name (something you make up) and owner (ideally your real name).
  5. Buy the equipment you want your robot to use during the simulation. Your robot starts the simulation with a limited budget of $1000 with which to buy equipment. The available equipment is described here.
  6. Enter the simulation.
  7. Start an 'infinite' loop where you continuously monitor your robot's progress, sending it commands to do things such as move, fire its weapon, etc.

Every method on the Controller API class sends a message to the server, then waits for a response from the server, before the method returns. For the methods which are used while the robot is in its simulation loop, the server will pause (therefore also pausing the client) if it has been less than 1/30th of a second since the last message was received. This means that the client can only send up to 30 messages per second, so it needs to make the most of the API methods it decides to call.

Reference frames

The playing field within which the simulation takes place is a rectangle with a specified width and height, shown as the dark blue rectangle in the viewer. The dimensions of the playing field can be queried using the Controller API. Currently this is 30 metres wide by 20 metres high, but this should not be assumed to stay constant.

The coordinate system used by the simulation for positions places the origin (x = 0, y = 0) at the centre of the playing field. Positive x is to the right, and positive y is down.

The orientation of a robot is the angle in radians which the robot makes with the positive x axis, increasing positively in the clockwise direction. So if the robot is facing right, its orientation is 0. If it is facing down, its orientation is pi/2, if it is facing up, its orientation is -pi/2. There is a discontinuity at the point where the robot is facing left, since the angle wraps around from -pi to pi.

The orientation of the sensor and turret are specified in radians, relative to the robot's orientation. So an orientation of zero means pointing in the same direction as the robot. An orientation of pi/2 means pointing directly to the robot's right, and -pi/2 means pointing to the left, etc.

The following formulae can be used to convert between radians and degrees:

radians = degrees * pi / 180

degrees = radians * 180 / pi

The robots are modelled as if they are 1 metre long and 60 centimetres wide, with a turret 1 metre in length. For the purpose of collision detection between robots and other robots, munitions and the playing field boundaries, the robots are treated as circles with a radius of 60 centimetres.

Graphical debugging

Often it is difficult to visualise whether your robot is doing what you want, simply based on what it is doing in the viewer and any text your robot console app might be printing. For this reason an additional server and client API are provided which make it possible to debug your robot graphically.

C++ robots can use it by adding an additional linker input of [path to API]GraphicsNN_d.lib in Debug mode and [path to API]GraphicsNN.lib in Release mode, as well as including Graphics.h. NN is 60, 71 or 80 for Visual C++ 6.0, Visual Studio 2003 (v7.1) or Visual Studio 2005 (v8.0) respectively. C# robots can use it by adding a reference to Graphics11.dll or Graphics20.dll for Visual Studio 2003 (.NET 1.1) or Visual Studio 2005 (.NET 2.0) respectively.

GraphicsServer.exe is the server application. Run it, select File -> Start then click Start. The server will now wait for a client connection. Note that only one client can be connected at a time.

The comments in Graphics.h and the sample usage in the simple robot samples should be sufficient to work out how to use the API. Essentially you create a graphics client object, connect, then send commands to draw shapes.

The graphics server has the same mouse control as the battle viewer, ie left mouse drag to move the display, and mouse wheel to zoom in and out.

It is probably a good idea to make it possible for you to turn off your robot's use of the graphics API, because the graphics server won't be running in a public robot battle. The simple robot samples use a command-line parameter to control whether to use the graphics API, defaulting to off. The following batch files are provided to run the simple robots with the graphics API turned on:

• Samples\RunSimpleRobotGraphics.bat
• Samples\RunSimpleRobotNetGraphics.bat

Running competitions

In its normal mode of operation, the simulation runs continuously. Robots enter when they connect and start at a random position in the playing field. When running a competition between robots the basic approach is to run all robots at once so they enter the game at roughly the same time, and then award points and/or placings based on the order in which they leave (ie are killed).

One disadvantage of this approach is that it can be unfair - if the initial starting position of a robot is in the middle of a pack of other robots, that robot is at a disadvantage. Also, robots which enter the simulation late (either intentionally or because other robots' exes happened to be spawned first) will gain an advantage by being attacked for (slightly) less time.

The solution to this is the server administrator (ServerAdmin.exe). This can be used to control running tournaments consisting of one or more rounds, in a way which is fair. To use:

  1. Run ServerAdmin.exe.
  2. Connect to the server (File -> Connect).
  3. To switch into tournament mode, choose Tournament -> Start. Any existing robots in the simulation will be cleared.
  4. Run robot clients to add them to the simulation. The server will be in a state where robots can enter, but they will be blocked when they call EnterSimulation(). You will see the robots who have entered appear in the server administrator's list.
  5. When all robots have been added, run Tournament -> Begin Round to begin the round. Each robot's call to EnterSimulation will return, and simulation will begin. In tournament mode the robots are placed in a circle facing outwards (in a random order), so no robot is disadvantaged from being too close to other robots.
  6. As robots leave the simulation, either from being killed or disconnecting, they are awarded a placing. Their details in the robot list turn red to indicate that the robot is no longer connected to the server.
  7. When the last robot is remaining, select Tournament -> Next Round. This will award the remaining robot 1st place, disconnect it, and award points to all robots based on their placings (1st place = 10 points, 2nd place = 8 points, 3rd place = 6 points, 4th place = 4 points, 5th place = 2 points, 6th place or higher = 0 points). If there is more than one robot remaining when Next Round is selected, they will be ranked based on their remaining health.
  8. When Next Round is selected the simulation goes back into the mode where it is waiting for robots to enter. So to hold a multi-round tournament, repeat steps 4 to 7 for each desired round. The administrator also keeps track of each robot's total number of points from all rounds, and therefore its overall placing. If a robot doesn't enter a round then its placing for that round will be listed as DNE (Did Not Enter).
  9. Use Tournament -> End to go back to normal simulation mode. When the administrator disconnects from the server, the server will also automatically switch back to normal simulation mode.

The administrator uses the name and owner of robots to distinguish between them. Therefore the combination of name and owner of each robot must be unique. If there is a duplicate, a warning message is displayed in the Notes column.

If you have a tournament consisting of multiple robots developed by the same owner, you can choose View -> Owner Scores to reveal additional columns containing the total points of all robots of each owner, and also each owner's ranking based on those points.

Server options

By default when the server is run it listens for connections on port 9386. To run the server on a different port, use the /p command-line option:

Server /p [port]


Server /p 2801