sc2hs: An interface to the Starcraft II bot API

[ ffi, game, library, network, program ] [ Propose Tags ]


  • Control
    • Effects
      • Control.Effects.Logging
      • Modalities
        • Control.Effects.Modalities.Belief
        • Control.Effects.Modalities.Knowledge
  • Network
    • SC2
      • Network.SC2.Agent


Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


  • No Candidates
Versions [RSS]
Dependencies base (>=4.12 && <5), bytestring (>=0.10), containers (>=0.6), directory (>=1.3), etc, filepath (>=1.4), freer-simple (>=1.2), gitrev (>=1.3), lens, lens-labels (>=0.3), proto-lens (>=0.4), sc2-lowlevel, sc2-proto, sc2-support, sc2hs, text (>=1.2) [details]
License LicenseRef-OtherLicense
Author Sophie Taylor <>
Maintainer Sophie Taylor <>
Revised Revision 1 made by spacekitteh at 2019-02-06T08:40:09Z
Category Network, FFI, Game
Home page
Source repo head: git clone
Uploaded by spacekitteh at 2019-02-06T06:44:32Z
Executables sc2hs-demo
Downloads 576 total (4 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
All reported builds failed as of 2019-02-08 [all 3 reports]

Readme for sc2hs-

[back to package description]

sc2hs: Haskell bindings for the StarCraft II API


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.


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 :: 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.


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.


I think that's it.


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


No idea. Someone let me know!

Before compilation

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


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.


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 is an autogenerated wrapper library around the SC2 protobuf API description.


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 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 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.


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


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! 😻