How to install bots for StarCraft II

(c) Blizzard Entertainment

StarCraft II has built-in bots, and they’re all good, except they’re a little dumb, but that’s not what I’m talking about here. In 2017, the game developer Blizzard Entertainment published An API that allows you to create external bots. However, for some strange reason, Blizzard treats this API as a purely research project where bots should only fight each other. For some reason, they didn’t make a normal opportunity for a person to play with bots, although many gamers consider bots as a pretty good training tool.

However, everything is not so bad. Since there is no regular possibility, we will use the non-standard one. We will still set up bots and fight against them. Then we, driven by a research impulse, will figure out how the API works, and we will raise a development environment in which we can write such bots ourselves.

A virtual machine was used as a laboratory stand. This was done for a variety of reasons, one of which was the need to run unknown executables “from the Internet”. The game on the virtual machine started up normally and even quite playable, though with minimal graphics settings. Using a virtual machine as a stand provides a number of advantages: firstly, you can run the game on non-Windows computers, and secondly, the virtual machine can be used as the basis for undetectable clicker bots.

The virtual machine used in the experiments was running (important) Windows 10 x64. The operating system was installed with default options (Next, Next, Next…) and a single user “user” was created with administrator rights.

StarCraft II

free

game, and the installation process is quite simple:

On the Battle.net website create an account.

Download and install Battle.net client.

Log in to the client under the previously created account and install StarCraft II (important) to the “C:\Program Files (x86)\StarCraft II\” directory (this is the default directory).

To use external bots, we need to install local game cards. In theory, bots can work on any maps, even those that you create using the built-in editor. However, for the first acquaintance, it is recommended to download maps on which

competitions

bots among themselves (yes, yes, and there is such a thing). The fact is that in some bots the names of the cards are hard-coded into the code, and at first it will be quite difficult to understand why this or that bot does not start.

We will download maps from a special repository Blizzard on GitHub. It is recommended to download all available maps. They are there arranged in archives for each season.

(important) In the game directory, you need to make a subdirectory “Maps” and unpack the archives with maps there. The password for the archives is “iagreetotheeula”. It is necessary to unpack the archives while maintaining the directory structure.

In our case, the game is installed in “C:\Program Files (x86)\StarCraft II\”, respectively, the map directory will be “C:\Program Files (x86)\StarCraft II\Maps\”. After unpacking the cards, everything should turn out as in the screenshot below:

In order to try our hand against external bots, we need a special launcher –

SC2AI Manager(Win10 only)

by Cryptious admin

Discord channel SC2 AI

. It’s fair to say that some bots can be run without a launcher, but that’s the next level of complexity, as they say, and we’ll look at it a bit later.

SC2AI Mannager allows you to both play against bots and pit different bots against each other. We will not launch the launcher with arbitrary bots in this article, but instead we will take ready set (launcher, maps, bots)which was used in demonstration battles ProBots 2021 Season 3 — ProBots vs Humans Exhibition.

Using the kit comes down to the following simple steps:

Download the set and unpack it to an arbitrary folder on the disk.

Maps from the set, that is, files with the *.SC2Map extension, are copied to “C:\Program Files (x86)\StarCraft II\Maps\”.

Launch Sc2AiApp.exe launcher.

He asks to log in, but it is possible without authorization, click “Continue Without Login”, then go to the “Play Vs Bot” tab.

Select the race you want to play and click “Launch”. As a result, 2 game clients and the bot console application should start.

For a normal game in the custom window, you need to enable full screen display. To do this, press F10 (Option)->Graphics select Windowed (Fullscreen)

Well, a quick start behind. Let’s now look a little deeper. By default, the external bots API does not work in the game; to activate it, you need to run the client with special command line parameters. The startup procedure is as follows:

It is necessary to determine the installation path of SC2 and determine the bitness of the client

It is necessary to make the working directory the directory in which the libraries for the client of the corresponding bitness are stored. For x64 client this is “c:\Program Files (x86)\StarCraft II\Support64\”

Start the client with command line options. For example: “”C:\\Program Files (x86)\\StarCraft II\\Versions\\Base87702\\SC2_x64.exe” -listen “127.0.0.1” -port “18080” -dataDir “C:\\Program Files (x86)\\StarCraft II” -tempDir “C:\\Users\\user\\AppData\\Local\\Temp\\SC2_xp3zu_33” -displayMode “0” -verbose”

Note. The specified example is taken from the source text of one of the investigated bots.

If everything is done correctly, then just a black window with the title StarCraft II will start, and nothing else will happen.

In fact, the client started normally, it switched to the network socket connection waiting mode (IP address + port), which we specified as command line parameters. In the example above, this is 127.0.0.1 and port 18080.

To manage the client, a special network protocol is used, using as a transport web socketson top of which the protocol is implemented Google Protocol Bufferswhose serialization options are defined by Blizzard and described in specifications.

The API treats the game as a state machine that has the following states:

(c) Blizzard Entertainment

Accordingly, when we launched the game using the example above, it entered the “Launched” state and then waited for requests to transfer to the next state. That’s why it was just a black screen.

This knowledge is enough for us for the first acquaintance with the device of external SC2 bots and how they can work in principle. In the future, if there is a desire to write something yourself, then you will need to familiarize yourself with the API documentation from the GitHub repository Blizzard/s2client-proto.

Due to the fact that the API is based on a standard network protocol, bots can be developed in any programming language, but we will only consider Python. This is due to the following reasons:

Firstly, Python is quite popular among bot developers, and there are good libraries written for it (for example, BurnySc2/python-sc2, deepmind/pysc2) to help develop your own bots.

Secondly, preparing such an environment will be quite simple and accessible even to beginners.

Let’s start preparing the environment:

Install Python by downloading it from official site. Version 3.10.4 was used in the current example, however some bots may require a different version, so check which version the bot developer recommends before starting. During installation, don’t forget to add the path to python to your PATH environment variable. If you did everything correctly, then after installation, by launching the console (cmd) and typing “python”, you should start the interpreter.

The next step is to deploy one of the Python libraries used to write bots. In this example, we will use BurnySc2/python-sc2. To install it in the console, type:

pip install burnysc2

If the library is installed correctly, then there should be no error messages in the console, and the Python libraries directory (for example, c:\users\user\appdata\local\programs\python\python310\lib\site-packages\) should show directory “sc2”.

Install the additional six library, which is required for burnysc2 to work

pip install six

Let’s go to the Web interface of the BurnySc2 GitHub repository and download it all as an archive. To do this, click on the green button “Code”, and then in the menu that appears “Download ZIP”.

Unpack the downloaded archive to an arbitrary folder, for example, to c:\python-sc2-develop\.

The development environment is ready. Now let’s try to run the Zerg-rush example bot. To do this, open the console and go to the directory “C:\python-sc2-develop\examples\zerg\”. After that, enter the command:

python zerg_rush.py

As a result, we should start the console window of the bot and the window of the StarCraft II client, where in the accelerated mode the “Zerg-rush” bot will fight with the built-in bot of an average level of complexity. At the end of the battle, a replay of ZvT.SC2Replay will be recorded.

There are many more examples of bots in the BurnySc2 library, but the play_tvz.py example deserves special attention. It shows how to run a bot against a human.

Note. The example contains an error: the first line contains an incorrect import path. The corrected example, meant to be run from the “C:\python-sc2-develop\examples\” directory looks like this:

from zerg.zerg_rush import ZergRushBot
from sc2 import maps
from sc2.data import Race
from sc2.main import run_game
from sc2.player import Bot, Human


def main():
    run_game(maps.get("Abyssal Reef LE"), [Human(Race.Terran), Bot(Race.Zerg, ZergRushBot())], realtime=True)


if __name__ == "__main__":
    main()

Successful launch of this example will launch 2 SC2 clients, one of which will have a bot, and the second will be playable by a person.