sc2hs: Haskell bindings for the StarCraft II API

Introduction

sc2hs is an Effect-based API for StarCraft II. Currently, the API is quite small, basically enough to get the worker rush bot working, but the framework is there.

Example

A quick example of the API is in order!

-- Orders a worker rush on the first frame.
workerRush :: Member Logging r =>   Eff (Agent ':r ) () -- 1
workerRush = do
  updateObservations -- 2
  units <- workers -- 3
  locs <- enemyStartLocations -- 4
  units `attack` (head locs) -- 5
  logMessage 1 "Worker rush ^_^"
  loop
  
loop :: Member Logging r =>  Eff (Agent ': r) ()
loop = do
  step -- 6
  status <- getStatus -- 7
  case status of
    Ended -> logMessage 1 "Ending game"
    _     -> loop

Let's look at what this does:

1. An entity which interacts with SC2 is a computation using the Agent Effect. This is roughly the level of API that is exposed by, for example, python-sc2.
2. updateObservations asks SC2 to send all the info the Agent can legitimately know of, and processes the result. It should be called once per game tick.
3. workers is a function which returns a list of the player's worker units (SCVs/Drones/Probes)
4. enemyStartLocations retrieves the list of possible start locations for the enemy, which is a property of the map.
5. attack is a wrapper around an Order, which instructs units to use abilities. attack just creates an Order to attack, using the specified units and a given Targetable, which can be a point or a specified unit.
6. step tells SC2 that it is ready to advance to the next game tick. This is only useful in non-realtime modes.
7. getStatus returns the status of the protocol state machine.

Installation

Required dependencies

• Stack
• protoc (from the protobuf package) must also be in your path
• If you want to actually run it, then you need StarCraft II installed.

Windows

I think that's it.

Linux

Nix is highly recommended. If not, then make sure you also have zlib headers available.

Mac

No idea. Someone let me know!

Before compilation

Due to a bug in proto-lens-protoc 0.4.0.1, enum generation is broken when there are underscores in names. Thus, you must apply the patch in sc2-proto to the s2client-proto submodule.

Compilation

stack build

Running the demo app

First, launch SC2 and create a game manually. Then, do stack run.

This should run the demo bot, which launches a game, chooses the 9th map in the available maps, and joins as a Protoss player against a random Medium Computer player.

Design

sc2hs is split into several packages:

graph BT
    sc2-proto --> sc2-lowlevel
    sc2-support --> sc2-lowlevel
    sc2-proto --> sc2hs
    sc2-support --> sc2hs
    sc2-lowlevel --> sc2hs
    sc2-lowlevel --> sc2hs-demo
    sc2hs --> sc2hs-demo

sc2-proto

sc2-proto is an autogenerated wrapper library around the SC2 protobuf API description.

sc2-support

sc2-support contains basic SC2-related definitions, such as the various directories, as well as a Template Haskell module which generates data types and functions converting between the raw integers used to refer to units, abilities, upgrades, buffs and effects, into a more usable form. It does this by parsing stableid.json, which is only created after running SC2 using the API at least once. Therefore, it also includes a backup copy, which may be out of date; but it shouldn't change frequently.

Eventually, the goal is for sc2-support to augment this data with properties harvested from balance data extracted from the SC2 editor, but how to do that well when it changes with each patch is still to be worked out.

sc2-lowlevel

sc2-lowlevel handles launching the game, managing its process, connecting to it, and communicating at the protobuf API logical layer. It also has some higher level types used by sc2hs. The protocol state machine is modeled using an Effect.

sc2hs

sc2hs is centered on the Network.SC2.Agent module. This defines an Effect, Agent, which provides an abstraction over the low-level protocol. Currently it uses just the Raw interface, but the goal is to augment it with data from the feature-layer interface and UI.

sc2hs-demo

The demo app shows how to create a basic bot and use it in a game.

Contributing

Currently the focus is on expanding horizontally along the layers, by translating more of the protobuf protocol into Requestables in sc2-lowlevel, and into the Agent Effect. That would be a great place to contribute; however contributions anywhere else are more than welcome! 😻