DarkLotus / ExampleBot

This repository contains an example bot to play Starcraft 2.

ExampleBot

This repository contains an example C# bot to play Starcraft 2. It is a blank bot, which does nothing, which you can use as a base to build your own bot. It makes use of the Starcraft 2 Client protocol. By starting from this bot, it will be easy to upload your bot for use on the ladder To get started simply follow the instructions below.

Getting started

Preperations

First you will have to install some things, if you haven't already.

1. Download Starcraft 2
2. Install Visual studio. In the installer, choose the .NET desktop development IDE.
3. Go here and download the Season 3 map pack.
4. Extract the maps to 'C:\Program Files (x86)\StarCraft II\Maps'. Make sure you have extracted the maps directly into the folder, if they aren't in exactly the right place the program will be unable to find them.

Preparing the bot

In this section you will prepare the bot for your own use. It is imortant that you have picked a name for your bot! You will have to rename a number of files for your bot. It is important to rename these files if you intend to use your bot on the ladder, since the bot will have to have a unique filename.

1. Clone or download this repository.
2. Open ExampleBot.sln in Visual Studio.
3. Open YourBot.cs in the ExampleBot project.
4. Rename the YourBot class to the name of your bot. You can rename the class by right clicking on it and selecting Rename.
5. Rename the YourBot.cs file to the name of your bot.
6. Rename the ExampleBot namespace.
7. Right click on the ExampleBot project and go to properties. In the Application tab set the Assembly name to the name of your bot. This will determine the name of your bot's .exe file.
8. Open the Program.cs file inside the Launcher project and set the botName variable to the name of your bot.
9. Right click on the Launcher Project and rename the Assembly name to Launcher. This name will have to be unique among existing bots, or you won't be able to upload to the ladder.

Writing your bot

To start writing your bot, let's first look at the existing files.

1. Open the Program.cs file in the ExampleBot project.
2. Set the race variable to the race you want your bot to play.
3. You can set the mapName, opponentRace and opponentDifficulty variables when testing against the built in Blizzard AI.
4. Open the file for your bot. This is the file you renamed in step 5 of 'Preparing the bot'.
5. In the onFrame method you can program the behaviour for your bot. The observation parameter provides all the information about the current frame of the game. The gameInfo parameter will have the same value each frame. It provides static game information such as which parts of the map are buildable. The playerId parameter is the ID for your bot. You can use it to figure out which units are yours.
6. The onFrame method will return a list of actions you want your bot to perform. An action can, for instance, be a command for a unit to move somewhere, or a command for a building to start training a unit. You can simply add actions to the list and the bot will carry them out.
7. To try your bot against the Blizzard AI, you can simply run the ExampleBot project by right clicking it and selecting Debug -> Start new instance. If you haven't specified any actions for your bot to take your bot will do nothing. You will be able to order the units around yourself. It is a good idea to try this, to see if the game manages to load correctly.

Preparing your bot for the ladder

You will need to take a number of steps to prepare your bot for the ladder.

1. Make sure all the projects are built by right clicking the ExampleBot solution and choosing 'Build Solution' (shortcut ctrl-shift-b).
2. Create a new folder with the name of your bot. This will contain the files you upload to the ladder.
3. Copy the Launcher.exe file generated by the BotLauncher project into the new folder. This can be found under BotLauncher/bin/Debug
4. Inside the folder, create another folder called data and inside that another folder with the name of your bot.
5. Copy the contents of ExampleBot/bin/Debug into the /data/ folder you created in step 4.
6. Now start the Launcher.exe. If everything has been done correctly it should start a game with your bot against the Blizzard AI.
7. You can now create a zip file from the folder created at step 2 by right clicking on the folder and selecting Send to -> Compressed (zipped) folder.
8. You can upload the zipped file to the ladder. You may have to create an account first.

Playing your bot against other bots through the LadderManager

You can also run the LadderManager locally. The following instructions will allow you to do so.

1. Follow the instructions here to install the LadderManager. If you only have the .NET version of visual studio you may also need to install the C++ version. This can be done by using the installer from step 2 of the 'Preperations' section and choosing the C++ IDE.
2. Move the contents of the folder created in 'Preparing your bot for the ladder' to the ExeDirectory.
3. Add your bot to the LadderBots.json file.
4. Add a game between your bot and another to the matchuplist.