Battle

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#.

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 of the sample clients:

    • Samples\SimpleRobot\Release\SimpleRobot.exe
    • Samples\SimpleRobotNet\bin\Release\SimpleRobotNet.exe
    • Samples\DumbRobot\Release\DumbRobot.exe
    • Samples\DumbRobotNet\bin\Release\DumbRobotNet.exe

    Or to avoid changing directories constantly, use one of the batch files:

    • Samples\RunSimpleRobot.bat
    • Samples\RunSimpleRobotNet.bat
    • Samples\RunDumbRobot.bat
    • Samples\RunDumbRobotNet.bat

    The SimpleRobot and DumbRobot are written in C++, and the SimpleRobotNet and DumbRobotNet 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 seek out other robots and kill them. The dumb robots make good fodder for the simple robots.

  4. Continue adding more robots as desired.

The rendering of the simulation in the viewer can be moving by dragging it with the left mouse button. The mouse wheel can be used to zoom in and out.

Creating your own robots

To create a robot, use Visual Studio .NET 2003 to create a console application in your choice of language (C++ or C#). Look at the simple or dumb robot sample applications to work out how they need to be configured.

Steps for C++ projects:

  1. Add the 'API' directory to the C/C++ -> General -> Additional Include Directories option (for both Debug and Release configurations).
  2. Under C/C++ -> Code Generation, set the Runtime Library for Debug configurations to 'Multi-threaded Debug DLL', and for Release configurations to 'Multi-threaded DLL'.
  3. Under C/C++ -> Linker -> Input, add 'ws2_32.lib [path to API]\Controller_d.lib' to the Additional Dependencies option for Debug configurations, and 'ws2_32.lib [path to API]\Controller.lib' for Release configurations.
  4. The API you programme against is in Controller.h, in addition you will need to use the vector class in Vec.h. The CommsClient.h and CommsMessage.h files are dependencies which you shouldn't have to look at. It may be worthwhile to add Controller.h and Vec.h to your project, to make the IntelliSense work on the classes they contain.

Steps for C# projects:

  1. Add a reference to ControllerNet.dll and VecNet.dll in the API directory.
  2. There is no documentation for the C# API, but it is very similar to the C++ API in Controller.h, so you should be able to figure it out from that, the sample applications, and the IntelliSense information.

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/15th of a second since the last message was received. This means that the client can only send up to 15 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]Graphics_d.lib in Debug mode and [path to API]Graphics.lib in Release mode, as well as including Graphics.h. C# robots can use it by adding a reference to Graphics.dll.

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