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:
- 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.
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.
workers is a function which returns a list of the player's worker units (SCVs/Drones/Probes)
enemyStartLocations retrieves the list of possible start locations for the enemy, which is a property of the map.
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.
step tells SC2 that it is ready to advance to the next game tick. This is only useful in non-realtime modes.
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! 😻
