<?xml version="1.0" encoding="utf-8"?>
<topic id="3bea1cc0-9ea9-4268-843f-aded2eb0eba5" revisionNumber="1">
  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
    <title>Introduction</title>
    <introduction>
      <para>The Robocode Control API is used for controlling the Robocode
      application from another external application. Basically, it is possible
      to run battles between selected robots and retrieve the results. However,
      it is also possible to get detailed information as snapshots during the
      battles regarding e.g. the positions and headings of the individual robots
      and bullets at a specific time during a battle.
      </para>
      <para>
      The main entry class is the Robocode.Control.RobocodeEngine class, which
      must be instantiated by the application controlling Robocode. With the
      RobocodeEngine, a battle specification must be provided in order to run a
      battle. The battle specification specify the size of the battlefield, and
      which rules that must be used. In addition, the participant robots must be
      selected, which must exist in the robot directory of Robocode in
      advantage.
      </para>
    </introduction>
    <section>
      <title>Example</title>
      <content>
        <para>
        Here is a simple sample application that runs a battle in Robocode for 5
        rounds on the default battlefield of 800x600 pixels. The robots selected
        for the battle are sample.RamFire and sample.Corners.
        </para>
        <para>
        A Visual Studio solution containing this BattleRunner can be found in
        [your robocode dir]\lib\control if you have installed Robocode and the
        .NET plugin for Robocode, where [your robocode dir] is your Robocode
        installation directory, which could be C:\robocode like this example
        assumes.
        </para>
        <code>
// Application that demonstrates how to run two sample robots in Robocode with the RobocodeEngine using the
// Robocode.Control package.
//
// NOTE: this application assumes that Robocode and the .NET plugin has been installed at C:\robocode, and that this
// application is run from the file path C:\robocode\libs\control. If this is not the case, the references for this
// solution must be changed to point at [your robocode dir]\libs directory where these references are located.
// Also note that the application will need some time to start up and initialize Robocode before the battle can begin.
//
// Author: Flemming N. Larsen

using System;
using Robocode;
using Robocode.Control;
using Robocode.Control.Events;

class BattleRunner
{
    static void Main(string[] args)
    {
        // Create the RobocodeEngine
        RobocodeEngine engine = new RobocodeEngine("C:\\robocode"); // Run from C:\Robocode

        // Add battle event handlers
        engine.BattleCompleted += new BattleCompletedEventHandler(BattleCompleted);
        engine.BattleMessage += new BattleMessageEventHandler(BattleMessage);
        engine.BattleError += new BattleErrorEventHandler(BattleError);

        // Show the Robocode battle view
        engine.Visible = true;

        // Setup the battle specification

        int numberOfRounds = 5;
        BattlefieldSpecification battlefield = new BattlefieldSpecification(800, 600); // 800x600
        RobotSpecification[] selectedRobots = engine.GetLocalRepository("sample.RamFire,sample.Corners");

        BattleSpecification battleSpec = new BattleSpecification(numberOfRounds, battlefield, selectedRobots);

        // Run our specified battle and let it run till it is over
        engine.RunBattle(battleSpec, true /* wait till the battle is over */);

        // Cleanup our RobocodeEngine
        engine.Close();
    }

    // Called when the battle is completed successfully with battle results
    private static void BattleCompleted(BattleCompletedEvent e)
    {
        Console.WriteLine("-- Battle has completed --");

        // Print out the sorted results with the robot names
        Console.WriteLine("Battle results:");
        foreach (BattleResults result in e.SortedResults)
        {
            Console.WriteLine("  " + result.TeamLeaderName + ": " + result.Score);
        }
    }

    // Called when the game sends out an information message during the battle
    private static void BattleMessage(BattleMessageEvent e)
    {
        Console.WriteLine("Msg> " + e.Message);
    }

    // Called when the game sends out an error message during the battle
    private static void BattleError(BattleErrorEvent e)
    {
        Console.WriteLine("Err> " + e.Error);
    }
}
        </code>
      </content>
    </section>
  </developerConceptualDocument>
</topic>