Introduction

This post covers how to connect directly to the StarCraft II client (for writing your own API), not how to set up the official StarCraft II API.
The official client API is written in C++ and can be found on GitHub.

StarCraft II is free to play (since November 14, 2017) and having the full version is not required.

Launching the Client

A special version of the game client, designed for artificial intelligence, must be used instead of the default client. It does not feature any in-game menu and the application cannot be started by double-clicking on the icon. It requires a valid IP address and port parsed as arguments in order to run (double-clicking the icon will not launch the application).

The API-version of the client can be found here (assuming default installation):
C:\Program Files (x84)\StarCraft II\Versions\Base60321\SC2.exe

The client can be launched using command prompt:
C:\Program Files (x86)\StarCraft II\Versions\Base60321>start SC2.exe -listen 127.0.0.1 -port 8168

The API-version of the client can be found in the StarCraft II folder:
StarCraft II\Versions\Base60321\SC2.exe

The client can be launched using Linux Shell (See Linux-exclusive arguments here):
{path}\StarCraft II\Versions\Base60321>SC2.exe -listen 127.0.0.1 -port 8168

The API-version of the client can be found here:
/Applications/StarCraft II/Versions/Base60321/SC2.app

The client can be launched using the terminal:
open "/Applications/StarCraft II/Versions/Base60321/SC2.app" --args -listen 127.0.0.1 -port 8168

Toggle Fullscreen

Launch with the argument -displaymode 0 for windowed mode or -displaymode 1 to launch in fullscreen.

Change Resolution

The arguments -windowwidth 1024 and -windowheigh 768 can be used to define the window resolution (eg. 1024×768)

Window Placement

Use -windowx 125 and -windowy 250 to have the top-left corner of the window be placed 125px left from the left side of your screen and 250px from the top of your screen (useful when launching multiple instances).

ERROR: icuin52.dll was not found

[Bad solution] Add C:\Program Files (x86)\StarCraft II\Support (or \Support64) to your environment path. Restart your computer and try again.

[Better solution] Launch the client with the correct working directory (/Support or /Support64) – see the code section.

Connecting to Client

The StarCraft II client will open a web socket listening on the port you specified when launching the application. Remember to use an available port and to give each client a unique port when launching multiple instances. In our case the absolute URI would read:
ws://127.0.0.1:8168/sc2api

Receiving an “Unable to connect to the remote server” WebSocketException (or similar) when attempting to connect to the client might be caused by the client not yet being ready. Your operating system (Windows 10 at least) will actively decline a connection request made to any closed port. Wait for the client to finish loading and attempt again.

Confirming Connection

The StarCraft II client is using protocol buffer (alias protobuf) to communicate with the API.

Think of it as a way of representing data similar to XML or JSON, but instead of self-describing strings it serializes to a binary format that requires knowing the transmitted object in order to deserialize. This format is 3-10 times more compressed than XML and can be serialized and deserialized 20-100 times faster (according to Google). The official StarCraft II protocol (.proto files) can be found here.

In order to confirm the connection, without having to handle protobuf just yet, the byte array {66,0} can be sent to the client. This corresponds to the binary form of Request { Quit = RequestQuit() } and will make the application shutdown when received.

Code Examples

The code examples are simplified as much as possible in an attempt to make it readable for developers without prior experience with C#. It is meant as working pseudo code, not as an actual implementation suggestion.

Every single Request-command should obviously not be hard-coded as shown in the example but generated using protobuf. However, this approach lets you confirm that the connection with the StarCraft II client is working before implementing Request/Response.