Code Guide

Class Organization

After checking out the project, you'll have 4 folders:

• src: the Java source code
• maps: some maps that you can use, feel free to crete your own maps
• lib: the java libraries needed to run the game
• data: some AIs need some data (e.g., the AHTN AI needs an HTN definition of the domain), all of those data files are in this folder.

The source code is organized in 5 packages:

• rts: contains the classes that implement the game (units, actions, game state, loading and saving games to disk, etc.).
• ai: contains all the built-in AIs that come with microRTS.
• util: some auxiliary classes.
• gui: visualization classes to visualize game states and game replays (traces). It also contains a few classes to let humans play the game.
• tests: example code of how to use microRTS. Includes a class called Experimenter that can be used to run systematic experiments, comparing different AIs in a collection of maps.

If you are new to microRTS and want to use it for your research, I recommend checking the tests/GameVisualSimulationTest.java, that loads a map, creates two AIs, and runs a complete game simulation with them. So, it illustrates the whole process of how to run a game, how to control the game speed, etc.

Also, if you want to try to play the game yourself, you can run the tests/PlayGameWithMouseTest.java, that loads a map, and runs a game where a human (controlling the game with mouse) plays player 0, and a random AI plays player 1. See instructions in the "gui/MouseController.java" class for how to play the game with mouse. See this YouTube video. Also, you can run a GUI that will let you load maps, and test different AIs in these maps (gui/frontend/FrontEnd.java).

Game State

The game state is stored via 3 main classes:

• GameState: this is the main class that stores the full game state. The game state consists of 4 parts:
  • A time stamp: how many cycles have passed since the beginning of the game.
  • The PhysicalGameState: the map configuration and the units currently in the game.
  • Action assignments: this is a list of the actions currently assigned to each of the units in the game that are controlled by players.
  • Unit type table: since microRTS allows for the definition of custom types of units, a game state contains the unit definition table.
• PhysicalGameState: this class contains the terrain (width and height of the map, and which cells have walls), and a list of units currently in the game.
• PartiallyObservableGameState: this class extends GameState, and can be used to create a version of the game state that only contains the information that can be seen by a given player in a partially observable game. See the POGameVisualSimulationTest class for an example of how to use it to run a partially observable game. The main idea is to maintain a single GameState instance, but before asking each of the AIs for actions, we create an instance of this class, that contains the game state from the point of view of each player, and that's the game state that is given to the AI.

AI

As can be seen in the GameDefinition page, the action set of microRTS is very low level (for example, units have to move cell by cell, rather than using path-finding, as in standard RTS games). If you want to create an AI at a higher level of abstraction, the package "ai/abstraction" provides such abstraction by defining the actions: Move, Attack, Harvest and Train, with the standard behavior that these actions have in games like Wargus or Starcraft (you need to provide an algorithm for path-finding, in the package "ai/abstraction/pathfinding" you will find a few implementations you can use, including A* and greedy search).

Several example AIs are provided that use this level of abstraction (e.g., LightRush, RangedRush and WorkerRush). These AIs implement a Light unit rush, a Ranged unit rush and a Worker unit rush respectively.

Many AI techniques (such as game tree search techniques) require an evaluation function. The package "ai/evaluation" provides some simple evaluation functions that you can use. In particular SimpleEvaluationFunction is the most simple and fast one. EvaluationFunctionForwarding is more elaborate and takes into account the effect of the actions currently under execution for performing the game state assessment. All of them return a float number that is positive if the game state is good for the "max" player, and negative if the game state is good for the "min" player. I recommend using "SimpleSqrtEvaluationFunction3", which provides normalized scores in the range [-1,1].

Other packages inside of the ai package include many other AI techniques that have been published over the past few years to address the problem of playing RTS games. For example, you will find techniques based on minimax game tree search (such as ABCD), based on Monte Carlo Tree Search (such as UCT, or NaiveMCTS), and or portfolio approaches (like Greedy Portfolio search). More details in the Artificial Intelligence page in this Wiki.

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, which should be sent after the AI has done the preGameAnalysis.
• "gameOver WINNER\n": informs the server the game is over and who was the winner of the game (WINNER will be 0 or 1). SocketAI will be waiting for an "ack" message after sending this.