Getting Started

Step 1: Check microRTS out

    • microRTS lives in a github repository: https://github.com/santiontanon/microrts

    • You can check it out using either git or svn

    • For example, assuming you are using a unix machine (Linux / Mac), you can check it out by opening a terminal, navigating to the folder where you want to have microRTS and typing:

    • git clone https://github.com/santiontanon/microrts.git

Step 2: Set it up in your favorite Java development environment (Netbeans / Eclipse / IDEA / etc.)

  • Instructions are IDE-dependent, but for example, assuming you use Netbeans:

    • File -> New Project.... This will open the new project wizard.

    • Select "Java Project with Existing Sources". Then click Next.

    • Name your project. Then click Next.

    • Add the "src" folder inside of microRTS to the "Source Package Folders". Then click Finish.

    • Right click on the newly created project and select "Properties"

    • Go to "Libraries" and click on "Add JAR/Folder", and add the "jdom.jar" file inside of the "lib" folder inside of microRTS

Step 3: Make sure you have microRTS properly set up

  • The easiest way is to see if you can run some of the tests. For example, run the "tests.GameVisualSimulationTest.java" file. If you see the game running and two bots playing each other. Then you are done.

  • You can also run the gui.frontend.FrontEnd.java class for a GUI to launch microRTS games

Video explaining the first 3 steps:

Step 4: Creating your first bot

  • We recommend you develop bots on a separate project than the microRTS project to keep things organized.

  • So, create a new project in your favorite Java development environment (Netbeans / Eclipse / IDEA / etc.).

  • Then, add the microRTS to the dependencies of your new project

  • Create a new class, and call it however you want, for example: "MyNewBot.java", that looks something like this (the important thing is that it extends the "AIWithComputationBudget.java" class):

MyNewAI.java

public class MyNewAI extends AIWithComputationBudget {

UnitTypeTable m_utt = null;

// This is the default constructor that microRTS will call:

public MyNewAI(UnitTypeTable utt) {

super(-1,-1);

m_utt = utt;

}

// This will be called by microRTS when it wants to create new instances of this bot (e.g., to play multiple games).

public AI clone() {

return new MyNewAI(m_utt);

}

// This will be called once at the beginning of each new game:

public void reset() {

}

// Called by microRTS at each game cycle.

// Returns the action the bot wants to execute.

public PlayerAction getAction(int player, GameState gs) {

PlayerAction pa = new PlayerAction();

pa.fillWithNones(gs, player, 10);

return pa;

}

// This will be called by the microRTS GUI to get the

// list of parameters that this bot wants exposed

// in the GUI.

public List<ParameterSpecification> getParameters()

{

return new ArrayList<>();

}

}

Step 5: Testing your bot

    • There are many ways in which you can test your bot, here we explain just a couple:

      • Method A (simple, recommended): copy the class tests.GameVisualSimulationTest.java into the same project were you are creating your bot. Then, set (in the "ai1" and "ai2" variables) the bots that you want to make play. For example, you can make your new bot play by replacing the line "AI ai2 = new RandomBiasedAI();" by "AI ai2 = new MyNewBot(utt);". Run the class, and you'll see your bot playing (if you did not modify the code above, you will see the bot does nothing).

    • Method B (competition mode): compile the project where your bot is into a JAR file. Then launch the microRTS GUI (gui.frontend.FrontEnd.java), go to the "Tournaments" tab. Then click on "Load Specific JAR", and select the JAR file corresponding to your project. You should see your bot added to the list of bots on the left. You can now select it along with the other bots you want to pit it against, select one or more maps, the tournament settings, and run a tournament. This way of running your bot will not be visual (it just runs on the background), but it is the mode that will be used for the competition. The results of the tournament will be saved to disk.

Video Explaining Steps 4 and 5

Step 6: Now that you have a bot setup, start creating some AI algorithms!

  • It is now time to start working on your bot! For more information about how to do that, please check the Wiki pages in the microRTS project: https://github.com/santiontanon/microrts/wiki

    • If you need examples, microRTS comes built-in with a large collection of AI algorithms. Use them as a reference. For example, there are bots that just execute random actions (e.g., RandomAI), there are hard-coded bots (e.g., LightRush), there are Monte Carlo Tree Search (MCTS) bots (e.g., NaiveMCTS), etc.

    • Some notes:

      • Bots must extend the "AIWithComputationBudget.java" class

      • microRTS will call the "setTimeBudget" method before the game start to tell the bot the number of milliseconds of computation time per game frame that are allowed. This information can be accessed in the "TIME_BUDGET" variable.

      • The "ITERATIONS_BUDGET" variable will not be used for this tournament (it is used for bots that perform MCTS to specify the computation budget in "number of playouts", rather than milliseconds).

    • Test your bot against the existing ones in microRTS!!

      • There are 4 hard-coded bots that are not very strong, but can be used for quick testing (WorkerRush, LightRush, HeavyRush and RangedRush).

      • Do not underestimate random bots! RandomAI and RandomBiasedAI (which perform actions mostly randomly) might get lucky and win some games in small maps. So, make sure you test against these bots.

      • Also, make sure to test against some of the MCTS bots. For example, NaiveMCTS and LSI are quite robust. They will struggle in larger maps given the tight computation budgets used in this competition. But they are still a good target to beat.

      • There have been papers published about microRTS bots, check out this page on the microRTS wiki for a list of papers: https://github.com/santiontanon/microrts/wiki/Research

    • If you have any questions, please use the forums: https://groups.google.com/forum/#!forum/microrts

Creating non-Java AIs

The game supports AIs to be developed in any language via socket connections. The "SocketAI" class is an AI that each time it needs to produce a move, it will communicate with a server via a socket sending the current game state, and waiting to receive the action to perform. This server can be done in any language (Python, C++, etc.). The "SocketAI" class currently supports JSON and XML as languages to send information back and forth with the server. A couple of example servers (in Java) is provided in the classes XMLSocketWrapperAI and JSONSocketWrapperAI.

Each message between the SocketAI and the server is a single line ended with a "\n" character. The messages that the SocketAI sends are:

  • "budget TIME_BUDGET ITERATIONS_BUDGET\n": communicates the time and iterations budget to the server. SocketAI will be waiting for an "ack" message.

  • "utt\n": sends the unit type table to the server. The server should expect a second message after this with the UTT encoded in either JSON or XML, as specified in the constructor or SocketAI. SocketAI will be waiting for an "ack" message.

  • "getAction PLAYER\n": requests an action for player "PLAYER". The server should expect a second message after this with the game state in either JSON or XML, as specified in the constructor or SocketAI. SocketAI will be waiting for an action encoded in either JSON or XML.

  • "preGameAnalysis MILLISECONDS\n": informs the server of the initial game state (sent also as a second message), and the amount of time in milliseconds it has to analyze it. SocketAI will be waiting for an "ack" message.

  • "gameOver WINNER\n": informs the server that the game is over and who was the winner of the game. WINNER is 0 or 1. SocketAI will be waiting for an "ack" message.