StarCraft II API -- Technical Design

StarCraft II API
DeepMind and Blizzard have been collaborating on building an AI research platform around StarCraft II. The interface we are building into the game to support this is called the “StarCraft II API”. While this high-level design is subject to change, we want to give the community an early look to provide the opportunity for feedback.

Goals:
  • Support AI research using StarCraft II.
  • Support a traditional “scripted” interface that allows programmatic control of individual units.
  • Support image-based interfaces that mimic a human’s experience.
  • Available in the retail Windows and Mac game client.

Shared Interface:
  • External processes can communicate with the StarCraft II client using a schema defined in the Protocol Buffer format.
  • Open source libraries and example code to simplify getting up and running -- making it unnecessary to know the details of the communication layer.
    • C++ Q1
    • Python TBD
  • Supports externally launching games and stepping the simulation forward.
    • Can configure games with one or multiple externally created agents/bots.
    • Support for playing against the built-in AI.
    • Initially restricted to offline games.
  • Basic map information at startup.
  • A catalog of all possible commands.
  • A catalog of all units with basic data.
  • The ability to load a replay and examine the state of the game as it plays.
  • Access to a variety of methods of scoring games in progress.

Scripted Interface (Alpha in Q1 2017):
  • Allow access to the full state of a game, or just the portion visible to a player.
  • Identification of units by tag.
  • Allow commands to be issued to individual or groups of units.
  • 2D arrays representing grids for visibility and creep.
  • Under consideration:
    • A mechanism to query for pathing.
    • Debug markers and debug text.
    • Set debug camera placement.

Vision-Based Interface (Date TBD):
  • Simplified low resolution image data for map & minimap:
    • Terrain heightfield
    • Visibility
    • Creep
    • Camera
    • Units
      • Player ownership
      • Unit type
      • Selection status
      • Hit points, energy and shields
  • Allow selection and targeting in screenspace.
  • Allow commands to be sent to selected units.

Future Releases:
  • Support for setting up a human vs. AI game.
  • New interface type for actual game rendering of the map and minimap for pure visual processing.
Any plans on how people might be able to run multiple sped up games, or interface with a Linux based AI? They mentioned they were running multiple games in parallel on google datacenter, and I know that Deepmind's API, tensorflow, requires Linux or Mac to use GPU acceleration. Do you plan on having a way for hobbyists to use these kinds of methods, or will they be stuck doing what they can in Windows, or on Apple hardware?
what about plans for Java interface?
Will there be the ability to get your AI to run on ladder ? would be fun !
This is awesome! Can't wait to start playing with this stuff
I'm extremely excited for non-AI ways to use this API. I wanted to experiment with a touch based UI for SC2, but I found the current custom map scripts are too limited (no multitouch or anything.) If I understand properly, I could write a program that runs on top of SC2 to provide an input layer, and actually ties into SC2.

Excited that you're planning Python support someday, but I'll settle for C++ for now.
11/05/2016 11:37 AMPosted by Aecium
what about plans for Java interface?


Nobody who knows a large mix of languages actually chooses Java. If you think Java is a good language, it's because you haven't been exposed to enough other languages. Python and Racket are my favorites. I understand why some people like Ruby although I don't care for it myself. Groovy and C# are each pretty good.

C++... eh. I'd rather get a more complete OO language like C# or go for C or Swift for better performance. C++ is a middle ground that doesn't make sense to me.
I have some questions.

1. What queues has this API movement taken from BWAPI?

2. Could any language be used to interface with the underlying communication framework in the shared interface (given the language supports the relevant IPC)?

3. Will the open sourced libraries be on Github and accept pull requests?
Hi, Chris Coxe, author of the Brood War bot ZZZKBot here. Really exciting news! It's great that Blizzard (with DeepMind) is adding API support for people wanting to write bots. It's just a pity nothing similar has been announced for Brood War too (yet? I can hope...). Here are my initial thoughts on some feature suggestions for SC2. I realize it is still very early days though.
  • Optional headless mode for all SC2 client instances that are being controlled by a bot as opposed to being controlled by a human (and similarly for a bot while it is processing a replay file). By "headless", I mean avoiding rendering for graphical display on a monitor, and avoiding any other resource utilization (CPU/memory/disk etc) that is unnecessary for such a system - I am not talking about the virtual "vision-based" interface that the bot may or may not have subscribed to (presumably it is built from the game state rather than built from the output of graphical rendering). E.g. if a bot is running on PC 1 against a human that is using PC 2, the bot on PC 1 can run optionally in headless mode. It might be a good idea to get support for this in early rather than adding it later. A use case is to avoid all unnecessary graphical rendering when you just want your bot to play as many games as possible 24x7 in an automated training/tournament system. This should speed up the number of games a bot can play per hour a lot, because rendering is so expensive computationally (in terms of GPU and memory at least). I would rather use my GPUs as much as possible for machine learning computations rather than for unnecessary graphics, or I might want to be able to run it on a system that doesn't need a fancy GPU :) Currently, in Brood War bots using BWAPI, the main performance bottleneck (i.e. frame rate bottleneck) in multiplayer (LAN) games in AIIDE/CIG tournaments is graphically rendering frames - you can only skip rendering 255 out of every 256 frames and that one frame per 256 can make all the difference. I expect the same problem would happen in SC2, especially if no support for skipping rendering frames is added for SC2(?).
  • Ability to run multiple games on the same OS instance concurrently (e.g. play four AI-vs-AI games concurrently) so we do not have to mess about setting up one virtual machine dedicated to each and every individual bot. Each OS instance requires a lot of disk and memory etc overheads that I would rather avoid.
  • Support for running on Linux-based OS'es if it doesn't already (or if you think it does already, at least verify it).
  • Preferably no internet access/DRM phoning home required (while training or running tournaments anyway), to avoid potential performance bottlenecks waiting for internet I/O to begin/end games or forcefully uploading replays to Blizzard etc. I am not sure whether "Initially restricted to offline games." covers this. I'm not sure whether Blizzard is worried about piracy for AI vs AI or AI vs Human games though.
  • A fully automated training/tournament management system that can be set up in any environment (e.g. all on one PC or a set of PCs or VMs - not just on Blizzard servers), similar to StarcraftAITournamentManager which is used for Brood War BWAPI bot tournaments like AIIDE and CIG. Currently it works in round robin fashion for a fixed pool of bots, but something similar to SSCAIT's system could be supported for matching up bots and maps in a probabilistic fashion.
  • I suggest publishing rules about where and how persistent file I/O should be implemented (for bot log files etc and data used for inter-game learning), because the rules need to be clear for tournaments that are run on hosted environments. For example, see http://www.cs.mun.ca/~dchurchill/starcraftaicomp/rules.shtml for the rules used in AIIDE and CIG tournaments for Brood War.


On a separate note, I know APM has been mentioned, but I am not sure whether response time has been mentioned. Response time is a different concept than APM, i.e. response time is a human's typical delay between sensory stimulus and any physical response, like the delay before pulling your hand away when burning it on a hot stove. I am not sure whether Blizzard/DeepMind have considered limiting response time to a more human like level somehow, i.e. forcefully imposing some kind of delay between when game state information is available and when actions involving that game state are allowed to be executed, e.g. after selecting my entire army via the hotkey then moving the camera across the screen to a nuclear launch alert, imposing a small delay before being allowed to attack the enemy ghost rather than simply being allowed to focus-fire it on the same frame it becomes visible.

Humans also use sound alerts. So I suppose humans will have at least one advantage over bots unless some kind of alerting system is implemented for sound triggers, if nothing else :) jk
Hi, Chris Coxe, author of the Brood War bot ZZZKBot here. Really exciting news! It's great that Blizzard (with DeepMind) is adding API support for people wanting to write bots. It's just a pity nothing similar has been announced for Brood War too (yet? I can hope...). Here are my initial thoughts on some feature suggestions for SC2. I realize it is still very early days though.
  • Optional headless mode for all SC2 client instances that are being controlled by a bot as opposed to being controlled by a human (and similarly for a bot while it is processing a replay file). By "headless", I mean avoiding rending for graphical display on a monitor, and avoiding any other resource utilization (CPU/memory/disk etc) that is unnecessary for such a system - I am not talking about the virtual "vision-based" interface that the bot may or may not have subscribed to (presumably it is built from the game state rather than built from the output of graphical rendering). E.g. if a bot is running on PC 1 against a human that is using PC 2, the bot on PC 1 can run optionally in headless mode. It might be a good idea to get support for this in early rather than adding it later. A use case is to avoid all unnecessary graphical rendering when you just want your bot to play as many games as possible 24x7 in an automated training/tournament system. This should speed up the number of games a bot can play per hour a lot, because rendering is so expensive computationally (in terms of GPU and memory at least). I would rather use my GPUs as much as possible for machine learning computations rather than for unnecessary graphics, or I might want to be able to run it on a system that doesn't need a fancy GPU :) Currently, in Brood War bots using BWAPI, the main performance bottleneck (i.e. frame rate bottleneck) in multiplayer (LAN) games in AIIDE/CIG tournaments is graphically rendering frames - you can only skip rendering 255 out of every 256 frames and that one frame per 256 can make all the difference. I expect the same problem would happen in SC2, especially if no support for skipping rendering frames is added for SC2(?).
  • Ability to run multiple games on the same OS instance concurrently (e.g. play four AI-vs-AI games concurrently) so we do not have to mess about setting up one virtual machine dedicated to each and every individual bot. Each OS instance requires a lot of disk and memory etc overheads that I would rather avoid.
  • Support for running on Linux-based OS'es if it doesn't already (or if you think it does already, at least verify it).
  • Preferably no internet access/DRM phoning home required (while training or running tournaments anyway), to avoid potential performance bottlenecks waiting for internet I/O to begin/end games or forcefully uploading replays to Blizzard etc. I am not sure whether "Initially restricted to offline games." covers this. I'm not sure whether Blizzard is worried about piracy for AI vs AI or AI vs Human games though.
  • A fully automated training/tournament management system that can be set up in any environment (e.g. all on one PC or a set of PCs or VMs - not just on Blizzard servers), similar to StarcraftAITournamentManager which is used for Brood War BWAPI bot tournaments like AIIDE and CIG. Currently it works in round robin fashion for a fixed pool of bots, but something similar to SSCAIT's system could be supported for matching up bots and maps in a probabilistic fashion.
  • I suggest publishing rules about where and how persistent file I/O should be implemented (for inter-game learning as opposed to just intra-game learning), because the rules need to be clear for tournaments that are run on hosted environments. For example, see http://www.cs.mun.ca/~dchurchill/starcraftaicomp/rules.shtml for the rules used in AIIDE and CIG tournaments for Brood War.


On a separate note, I know APM has been mentioned, but I am not sure whether response time has been mentioned. Response time is a different concept than APM, i.e. response time is a human's typical delay between sensory stimulus and any physical response, like the delay before pulling your hand away when burning it on a hot stove. I am not sure whether Blizzard/DeepMind have considered limiting response time to a more human like level somehow, i.e. forcefully imposing some kind of delay between when game state information is available and when actions involving that game state are allowed to be executed, e.g. after selecting my entire army via the hotkey then moving the camera across the screen to a nuclear launch alert, imposing a small delay before being allowed to attack the enemy ghost rather than simply being allowed to focus-fire it on the same frame it becomes visible.

Humans also use sound alerts. So I suppose humans will have at least one advantage over bots unless some kind of alerting system is implemented for sound triggers, if nothing else :) jk


Well, all the sound alerts have an accompanying UI element so that shouldn't be a problem. You could also train an NN to classify different audio queues if you really wanted. :P

I can't imagine getting SC2 to run on Linux would take that much effort, and I would really like to see it happen. It runs very well on wine and there is already an OpenGL renderer for the Mac version. Of course, that's another thing to QA and whatnot.

Thanks for better conveying most of my thoughts though, Chris.

--------

Why the delay for the image based API though? A similar library already exists for BWAPI. (BWEM, specifically the GridMap functions, http://bwem.sourceforge.net/) I could understand wanting to finalize what feature maps you include, but at least you could include some functions for making feature maps.

Maybe I'm wrong, but making something like an HP image seems fairly easy, just something like:

image = array.zeros(w,h)
for each unit in units:
image[unit.position] = unit.hp
Oh, and another thing worth considering is whether/how some kind of (hopefully headless) menu automation will be used to automate creating/joining games (and selecting game options such as which map, etc). This includes games hosted by Blizzard servers, and games hosted in other environments (e.g. running a tournament on a single PC). From my experience with BWAPI for Brood War, it would be better to use some kind of headless system to control this, to avoid having to do graphical rendering for that stuff between games. BWAPI supports menu automation, but it is not headless, and a lot of time is wasted waiting to progress through the menus, and for the game start countdown timer to finish, etc.
An R library connecting to the API would be on my wishlist.

Really cool initiative Traysent and Blizzard!
11/05/2016 02:55 PMPosted by lalush
An R library connecting to the API would be on my wishlist.

Really cool initiative Traysent and Blizzard!


Unlikely that they're going to spend time doing stuff that the community would gladly do for them. If there's enough demand for an R package, it will be ported by a 3rd party in no-time.
Personally I'll be writing bindings for the C++ lib for Python if there is a lot of time between the C++ and Python kit release date. Python is definitely the language of choice for many ML devs, including Google themselves.
11/05/2016 03:35 PMPosted by GrackyChan
11/05/2016 02:55 PMPosted by lalush
An R library connecting to the API would be on my wishlist.

Really cool initiative Traysent and Blizzard!


Unlikely that they're going to spend time doing stuff that the community would gladly do for them. If there's enough demand for an R package, it will be ported by a 3rd party in no-time.
Personally I'll be writing bindings for the C++ lib for Python if there is a lot of time between the C++ and Python kit release date. Python is definitely the language of choice for many ML devs, including Google themselves.


Assuming you're using tensorflow, I think it would be easier to just use python to define your graph, then use the tensorflow C++ API to run it from the SC2 environment.
11/05/2016 11:40 AMPosted by Dawn
Will there be the ability to get your AI to run on ladder ? would be fun !


was just thinking that.

It would be pretty awesome.
I'm really curious to know how the AIs' APM will be throttled, because there's a difference between burst APM and average APM. I might have a somewhat high APM when I'm just injecting larva, but I'm still horrible at stutter-stepping. What about the accuracy of the inputs? Will the AI always click on the exact pixel it wants?

Will the AI always spot DTs and observers? :)
Will the AlphaSC be smart enough to not be tricked by Sentry hallucination? Also definitely make the micro AI configurable, no human can beat AI that can avoid splash damage etc.
Some more ideas:

  • Similarly to as in BWAPI for Brood War, consider implementing a distinct tournament module that arbitrates/enforces rules so that it is easy to support different environments/tournaments that use different rule sets (e.g. whether or not complete map information is allowed, or whether bots are only allowed to use the vision-based interface, etc).
  • For training purposes, repeatability and being able to control/avoid the RNG that contributes to the game state might be very important for some people. So, consider adding special settings that can be used for training a bot that allows bots special access/control that a human would not normally be allowed, as follows. A setting to give the bot access to the entire game state (not just the game state normally allowed to be accessible such as map visibility) has already been mentioned, but there are other settings that would be useful to train bots such as the ability to control the exact spawn positions every player gets (only from among the permutations of spawn positions that are normally valid of course), or which race is rolled for players (bot players or perhaps even human players too) that chose Random race, or probabilistic control over which race(s) the bot can pick in the game lobby (e.g. say "I want to pick Zerg race with probability 1/6, Terran 1/6, Protoss 1/6, Random race 1/2", or whatever probability distribution you want, similar to what I proposed for BWAPI in Brood War in https://github.com/bwapi/bwapi/issues/680), or even being able to control the initial seed that is used for RNG (I gather this was already implemented in BWAPI for Brood War). For Random race vs Random race games, I can't remember whether SC2 makes mirror matchups less likely (Brood War certainly does), but if so, I don't know whether that logic should be left untouched or give access to be able to control that as well (or at least document what the logic is for that). This would be helpful for researchers wanting keep games repeatable and play out games deterministically to avoid the element of luck caused by RNG. However, the spawn position control in particular might be thought of giving bots an unfair advantage by access to abilities/resources while training that humans wanting to train in the same way would not be able to (unless that level of control is also delivered to humans wanting to train in the same way). Also, I imagine a complication might be that there may be other factors that introduce nondeterminism, e.g. will latency due to ping times introduce non-determinism for AI vs AI games, or is it feasible to make AI vs AI games completely deterministic?
  • In Starcraft, providing information about the game state accessible to my bot (as a player) is necessary, but due to the nature of Starcraft, to play well, at least in some scenarios, it may also be important to have an idea what information is accessible to your opponent(s) as well. E.g. in addition to knowing what enemy units my units can see, it is nice to know which of my units I know for sure my opponent(s) have the opportunity to see (at least on their minimap, not necessarily in their camera). Some units can see further than others. My overlord can see that enemy probe but can that enemy probe see my overlord? That is just a simple example, but you could make similar examples for other information such as whether an opponent currently has the opportunity to see that I have already upgraded air attack on my mutalisks depending on whether or not one of their units (one of their units that I can see) can see one of my mutalisks. It might be handy to see other players' perspectives, but limited according to what information it is possible to identify as common knowledge at least as far as the current frame is concerned (https://en.wikipedia.org/wiki/Common_knowledge_(logic)). If the tournament module requires a player to select an enemy unit (e.g. by clicking on it) before they are allowed access to information about the unit (e.g. what attack/armor upgrades it has) rather than limiting the amount of queries done programatically in any way, this makes the issue much more complicated. I imagine this might be very tricky and a lot of effort to implement, but if Blizzard is committed to supporting AI research in the long term, perhaps it is better in the long term to implement it in the API (because the API has access to the full game state and has enough information to know for sure what information should be accessible to each individual player) rather than individual bots attempting to reinvent the wheel every time by every botter writing their own implementation of it (and relying on guesswork about unit sight ranges etc because the logic for sight ranges and for calculating "distance" between units would presumably still be closed source). It's a tricky problem.
  • Optional ability for a bot to process the replay file immediately when each game ends (as opposed to needing to set this up in an ad-hoc fashion), so that this can be automated as part of a training/tournament environment. Whether or not this ability is allowed could be controlled via the tournament manager. This ability would be useful so that the bot can learn as a human would. It would be especially useful in tournament structures where the bot may only play a handful of games against a particular player, e.g. a Blizzard showmatch between the best AI and a top human. Maybe humans aren't allowed to watch the replay between games in big streamed tournaments like Blizzcon showmatches though.
  • I think it would be cool if there was a way to simulate the game engine (i.e., a no-graphics simulation) so that full AI-vs-AI games could be "played" within seconds. If simulated games could be calculated within seconds, I think it's pretty easy to come up with a genetic algorithm to evolve the AI's.

    But if the engine needs to be run in real time... that's a real killer. I think coming up with any good solutions (i.e., generating AI's that are substantially better than what blizzard already has) is just going to be too hard.

    Join the Conversation

    Return to Forum