[TOC]
### Getting Started ###
There are a number a libraries you can select to begin writing your bot. [Click here to get started](https://aiarena.net/wiki/bot-development/getting-started/).

### Run Bot vs Bot matches locally

The [local-play-bootstrap](https://github.com/aiarena/local-play-bootstrap) can be used to play bot vs bot matches locally, using the same environment that AI Arena uses for official ladder matches.

### Downloadable Bots
- **Sc2 AI Arena**  
-- [House Bots](https://sc2ai.net/authors/133/): Most of the house bots were originally written by Infy & Merfolk for testing their own bots. They have kindly donated them to the community for use in testing.  
-- [Authors](https://sc2ai.net/authors/): You can search bots by author and check if their bots are downloadable or by searching by
[Bots](https://sc2ai.net/bots/) directly.

### Uploading your Bot
You can upload your bot to test against others in the AI Arena client. On the sidebar in the [SC2 AI Arena homepage](https://sc2ai.net/), select Upload New Bot or go [here](https://sc2ai.net/botupload/) and fill in the form.

### Viewing Bot matches
* **Replays**
    * [**Latest SC2 AI Arena results**](https://aiarena.net/results/?page=1)  
* **VoDs**
    * [**AI Arena 24/7 ladder and Community Streams**](https://www.youtube.com/channel/UCMlH43XHsq1TacKm5n4Wbiw)
    * [**Starcraft 2 AI Season Tournaments**](https://www.youtube.com/channel/UCbXFERumlL7bvXxkdRrdLXQ)
    * [**Probots tournaments by ESChamp**](https://www.youtube.com/c/Eschamp/search?query=Probots)
    * [**Casting by LaughNgamez **](https://www.youtube.com/playlist?list=PLVRQoOk_ltE03RFVAbCT7eutBTz_cmQyv)

### Machine Learning
* **Reinforcement Learning**  
    * [Gym](https://gym.openai.com/): Toolkit for developing and comparing reinforcement learning algorithms  
[**An Introduction to Q-Learning** (Video)](https://www.youtube.com/watch?v=wN3rxIKmMgE)   
[**Reinforcement Learning Course - Full Machine Learning Tutorial** (Video)](https://www.youtube.com/watch?v=ELE2_Mftqoc)  
    * **Frameworks for PySC2**  
[**adept** (Repo)](https://github.com/heronsystems/adeptRL): Reinforcement Learning Framework  
[**Reaver** (Repo)](https://github.com/inoryy/reaver): Modular Deep Reinforcement Learning Framework (No longer maintained)  
    * [**SCC: an efficient deep reinforcement learning agent
mastering the game of StarCraft II** (Paper)](https://arxiv.org/pdf/2012.13169.pdf)
* [**Deep Learning with SC2** (Video)](https://pythonprogramming.net/deep-learning-starcraft-ii-ai-python-sc2-tutorial/): Deep Learning tutorial by Sentdex using the older python-sc2 framework.

### API Disparities
* **Missing** 
    * Enemy worker gathering action.
    * Carrier interceptor count.  
    * Enemy Adept Shade Timer.
    * Enemy Chronoboost
    * UnitType of StarGate warpin. 
    * Attacks coming from bunker.
    * Cyclone lock target.
    * Widow mine target.
    * Enemy Metabolic Boost Upgrade.
    * Enemy Tunneling Claws Upgrade.
    * Morphing Hatch/Lair.
    * Burrowed units dying in vision range, but without detection. Humans can see the death animation, but bots get no notification.
    * There are buffs for workers carrying minerals or gas, but the buff for rich gas is missing.
* **Advantages**   
    * Instantly recognize cloaked and changeling units.
    * Ids of enemy units can be recognized at different points of visibility.

# Extra resources

### [awesome-sc2-ai](https://github.com/aiarena/awesome-sc2-ai)

A curated list of SC2 AI code and resources.

### Bot Memory - The Data folder

Bots can save files to a local `data` folder and these files will persist between matches.
This is a good way to remember what worked and what didn't.

### Recognizing opponents - The Opponent ID

A unique ID for each opponent is provided as a way for bots to recognize opponents. The ID is specified when starting the bot as a command-line argument after a `--OpponentId` flag.  
Example:  
`bot.exe --OpponentId 29381a9a-d299-4fb6-b225-cd455c9cc38b`  
This ID can be saved in your bot's data folder if desired.

### ESChamp - Bits of Code
<https://eschamp.com/shows/bits-of-code/>

# Misc notes below - yet to be structured

## How do I know which of my units has been targeted by a Cyclone/Widowmine/etc?  
The targeted unit will gain the relevant buff.
e.g. for the Cyclone lock, it will gain the `LOCKON` buff as is listed here: <https://github.com/BurnySc2/python-sc2/blob/76e4a435732d4359e5bd9e15b6283a0498e212ca/sc2/ids/buff_id.py#L126>

## Increasing mineral gathering rates

Copy-paste, as written by ImpulseCloud (Holtan) in the sc2ai discord, starting at this message: <https://discordapp.com/channels/350289306763657218/350289306763657220/630252706023342100>  

To see how to get the fastest minerals: https://dke.maastrichtuniversity.nl/m.winands/documents/CIG2017_resourcegathering.pdf
He made one for SC2 too also, and I made some improvements to it, but haven't made any stats visualization for it
can get a 10% speedup doing sock-folding and a couple of other tricks 
 

...  
I gave up before publishing anything. I did work with @yanntm(YoBot) to try to merge them into his bot. You can see some of that in https://github.com/yanntm/YoBot/blob/master/HarvesterStrategy.cpp
It does manual ReturnCargo and Harvest actions to avoid the builtin 4-5 frame delay after the actions are done before the next action is queued. It also takes advantage of the trick of "exiting" mineral-walk will 'bump' the workers away from each other due to collision-physics, so if you have two workers that are mineral-walking thru each other, you have them exit mineral-walk as they pass their center-points, and then they get 'pushed' in their path-directions faster.
and then also the 'magic-spot' trick where you have the worker sprinting to a point right in front of the mineral, so it doesn't take 2-3 extra frames to slow down before reaching (if in 'Harvest' action)  
...  
the one problem is that since it exits mineral-walk often, it will get screwed up by units (yours or enemy) walking thru the mineral-line, so you'd want to check for non-mineral-workers closeby whenever exiting mineral-walk.
oh, using these tricks, you can also get that last load from a MULE
the speedups actually 'oversaturate' close-minerals with just 2 workers, so if you don't force-pair on the mineral, one of the two will eventually end up waiting too long and leave the mineral
you can even saturate far-minerals with just 2 workers if you use 2 speedlings to push/escort the workers back and forth (like pushing a merging-archon)
but that would get too-crowded to do for all workers, especially with the other tricks, there'd be too many collisions  
...  
but it would immensely speedup long-distance-mining, at speedling speed
( the push/escort only works if the pushed/escorted unit doesn't have a Move command tho)

In Romanticide Soupcatcher's Zoe has been able to gather 3975 minerals in 5 minutes (6720 frames) using 12 workers that's 12% more of the 3550 an idle bot would get:
<https://discord.com/channels/350289306763657218/350290846320427011/878162916560482345>

## SC2 Version Considerations
Unfortunately, Blizzard's support for the Protobuf API and bot play seems to be nonexistent as of 2022. Consequently, although can still develop your bot against the latest build of the game, there are annoying quirks and bugs that make it better to test and build against an older version of the game: **4.10**, a.k.a. Build 75689.
To stay up-to-date with the meta, we use custom maps (suffixed with `AIE`) with the latest balance patches applied.

Known issues with newer versions of the game:
- There are no Linux builds past Build 75689. Several attempts have been made to contact Blizzard to release a newer Linux build, but to no avail.
- Multiplayer (Bot vs Bot) games have a tendency to get "desynced", especially in builds past 5.x. This results in both bots playing in alternate realities. On 5.0.10, around 80% of games may end up desynced, which is practically useless.

In short, just use Build 75689. Your chosen language's API should have a way to choose the version, but to launch an older build manually, use this command:

    # Working directory must be here
    cd /c/path/to/Starcraft\ II/Support64
    /c/path/to/Starcraft\ II/Versions/Base75689/SC2_x64.exe -listen 127.0.0.1 -port 8000 -displayMode 0 -dataVersion B89B5D6FA7CBF6452E721311BFBC6CB2 -windowwidth 500 -windowheight 300 -windowx 0 -windowy 0 -verbose

The main thing here is the `dataVersion` - it must match the build. A mapping can be found here. https://github.com/ocraft/ocraft-s2client/blob/master/ocraft-s2client-protocol/src/main/resources/versions.json

## APM Bug
A situation can occur in longer games, where your units appear to executing orders that are very old (even an hour of ingame time). This can result in units spamming move commands on the ground, moving to attack bases that no longer exist, workers spamming minerals that no longer exist, etc. The other bot will be playing normally, so you will probably lose the game.

The best known reason for this is that there is likely a queue of actions (per player) that eventually grows to an unsustainable size and takes a long time to resolve. It has been observed most commonly around 120k APM (although some have observed this issue at 60k APM). To avoid this, try to reduce your APM below the 120k mark.

## Upgrade Mapping
Your bot's language probably uses the StableID (`C:/Users/[UserName]/Documents/StarCraft%20II/stableid.json`) to generate an enum of Upgrades. However, if you are looking for a specific Upgrade, it may not actually have the ID you expect. This may result in you checking for existence of an upgrade that you will never have.

The following table is a partial mapping of some of the more unusual upgrade values, so you don't have to hunt for them yourself:

| ID | Enum Value | English-language name | Notes |
|----|------------|-----------------------|-------|
|15|`SHIELD_WALL`|Combat Shields|Do not use `COMBAT_SHIELD` (234)|
|16|`PUNISHER_GRENADES`|Concussive Shells||
|76|`BATTLECRUISER_ENABLE_SPECIALIZATIONS`|Weapon Refit|Yamato Cannon. Do not use `YAMATO_CANNON` (258).|

Another thing to consider is that the Query interface for Available Abilities returns the **generalised** ability name. So for example, if you are using Available Abilities to determine if your Engineering Bay can upgrade Infantry Weapons Level 2, you need to check that it can use the `RESEARCH_TERRAN_INFANTRY_WEAPONS` (3698) ability, not `RESEARCH_TERRAN_INFANTRY_WEAPONS_LEVEL2` (653).

## Maintaining units in memory
In python-sc2 (and maybe other APIs), if you want to save a group of Units into memory, save only list of ids and retrieve them into Units list at start of bots step. If you save Units type into memory, it will cause crashes as it also saves old positions.