Intro to SC2 Bots

Get started with developing your own AI agent for one of the most complex video games ever created - StarCraft II.

StarCraft II Battle Cruiser

Writing AI agents, or bots if you will, for StarCraft has been a niche hobby for quite a while. The StarCraft Brood War had an popular but unofficial API created by reverse-engineering the game which allowed developers to create their own bots for the game. Blizzard Entertainment have since released an official API for StarCraft II to facilitate project AlphaStar by DeepMind.

AlphaStar has since been declared a success and major breakthrough. Interest in maintaining the API has subsequently fallen but the API is still functional and provides you with a unique opportunity to challenge your AI skills in one of the most complex video games ever created!

... Let's get you started.

Built from Scratch

The StarCraft II client (which can be downloaded for free) can be launched in a special developer mode that exposes a protobuf API. This mode allows you to interact directly with the client through the API – but will disable multiplayer access, game menu, campaign etc.

start SC2.exe -listen -port 8168

open --args -listen -port 8168

SC2.exe -listen -port 8168

You can interact directly with the exposed interface by sending protobuf messages that adheres to the official protobuf scheme through a TCP connection. I wrote a few words on the subject of protobuf:

[adq_src] Protocol Buffers
An introduction to protocol buffers, the high-performance data interchange format utilized by the StarCraft II API.

This allows you to write your own custom API – or opt for one of the many pre-existing solutions. The official API is written in C++ but most programming languages have a community-made. I wrote NydusNetwork to add .NET Core to the list of supported languages.

This is all you need to write a bot from scratch. It is an existing learning experience but the learning curve is steep. I do not recommend this for novice programmers. I wrote an guide on how to write your own API wrapper:

[adq_src] S2Client-Proto
Introduction to the official StarCraft II API - a request/response message system in protocol buffers.

Template Bots

Writing your own bot from scratch is quite a task. A popular option for new members of the community is to download an established bot and tweak it.

You can find a list of available templates here – but some of them has not been updated in while. I would highly recommend asking around on the community Discord channel for the current best starter pick in your favorite language.

Some templates are bare-bone and simply help you get started while others are advanced and fully fledged bots that are ready to win matches against the built-in AI from the get go. Writing your first bot is a journey filled with numerous unexpected challenges – but basing it off another bot is a great starting point.

This is a great option for novice programmers or for seasoned programmers who which to explore popular strategies for StarCraft II.

AI Framework

Finally there is the option of building your bot utilizing a framework. Frameworks provide you with pre-made solutions for many of the cumbersome challenges that arise when writing a bot from scratch – but with a blank canvas that provides flexibility to structure and implement your own strategies.

The first framework for StarCraft II agents was Abathur – a modularized approach to developing bots in .NET Core. More frameworks has since been created including node-sc2 for Node.Js and sharpy-sc2 for Python.

Modularized AI framework for StarCraft II, written in .NET Core - schmidtgit/SC2Abathur

I recommend this approach for everyone with software development experience. It should be noted that I 'might' have a slight bias towards basing solutions on frameworks as I am co-author of Abathur.


Whichever approach you opt for – reach out to the community! The community is of modest size but everyone is approachable and helpful. Join the Discord, subscribe to r/sc2ai and feel free to contact me.

The Abathur Framework is currently being rewritten to support the changes in patch 4.8.4 – follow along here on the blog, It is an adequate source.