sc2hs-0.1.0.0: README.md

# 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!
```haskell
-- 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:
```mermaid
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 `Requestable`s in `sc2-lowlevel`, and into the `Agent` Effect. That would be a great place to contribute; however contributions anywhere else are more than welcome! :heart_eyes_cat: