Skip to content

Commit

Permalink
dosc: update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
raspersc2 committed Oct 6, 2023
1 parent 0df8d4c commit 3dc4e37
Showing 1 changed file with 24 additions and 92 deletions.
116 changes: 24 additions & 92 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,95 +1,27 @@
# ares-sc2-starter-bot

[Documentation](https://aressc2.github.io/ares-sc2/index.html)

## Installation:
Prerequisites, ensure these are installed before proceeding:
- Python 3.11
- [Poetry](https://python-poetry.org/)
- [Git](https://git-scm.com/)
- [Starcraft 2](https://starcraft2.com/en-gb/)
- [Maps](https://sc2ai.net/wiki/maps/)

### Setup
If you have a non-standard starcraft installation or are using Linux, please adjust `MAPS_PATH` in `run.py`.

Click the `Use this template` button to create a new repo based on this template.

Then clone the repo, don't forget `--recursive`:

`git clone --recursive <git_repo_url_here>`

Change into your bot's directory:

`cd <bot_folder>`

Install - this will install dependencies, compile cython, and create a new isolated virtual environment:

`poetry install`

#### Run:

Optionally set your bot name and race in `config.yml`

`poetry run python run.py`

#### Start developing
Open up `bot/main.py` and have fun!

A `ares-sc2` bot is a [python-sc2](https://github.com/BurnySc2/python-sc2) bot by default, so any examples or
documentation in that repo will be relevant here too.

### Uploading to [AiArena](https://www.sc2ai.com)
Included in the repository is a convenient script named `scripts/create_ladder_zip.py`. However, it is important to note that the AIarena ladder infrastructure operates specifically on Linux-based systems. Due to the dependency of ares-sc2 on cython, it is necessary to execute this script on a Linux environment in order to generate Linux binaries.

To streamline this process, a GitHub workflow has been integrated into this repository when pushing to `main`. Upon each push to the main branch, the `create_ladder_zip.py` script is automatically executed on a Debian-based system. As a result, a compressed artifact named `ladder-zip.zip` is generated, facilitating the subsequent upload to AIarena. To access the generated file, navigate to the Actions tab, click on an Action and refer to the Artifacts section. Please note this may take a few
[ares-sc2 repo](https://github.com/AresSC2/ares-sc2) <br>
[ares-sc2 docs](https://aressc2.github.io/ares-sc2/index.html)

## Getting started
Please refer to [this tutorial article](https://aressc2.github.io/ares-sc2/tutorials/installation.html)
which is based on this starter bot repo.

## Uploading to [AiArena](https://www.sc2ai.com)

<b>TLDR:</b> On each push to `main` there is a Github Actions workflow that builds a ladder ready zip. Take a
look on the `Actions` tab to download.

Included in this repository is a convenient script named `scripts/create_ladder_zip.py`.
However, it is important to note that the AIarena ladder infrastructure operates specifically
on Linux-based systems. Due to the dependency of ares-sc2 on cython, it is necessary to execute
this script on a Linux environment in order to generate Linux binaries.

To streamline this process, a GitHub workflow has been integrated into this repository when pushing to `main`
on your GitHub repository (if you previously created a template from the
[starter-bot](https://github.com/AresSC2/ares-sc2-starter-bot)).
Upon each push to the main branch, the `create_ladder_zip.py` script is automatically executed on a
Debian-based system. As a result, a compressed artifact named `ladder-zip.zip` is generated,
facilitating the subsequent upload to AIarena. To access the generated file, navigate to the Actions tab,
click on an Action and refer to the Artifacts section. Please note this may take a few
minutes after pusing to the `main` branch.

### PyCharm

#### Adding `poetry` environment
Find the path of the environment `poetry` created in the installation step previously, copy and paste
or save this path somewhere.

`poetry env list --full-path`


Open this project in PyCharm and navigate to:

File | Settings | Project: <project name> | Python Interpreter

- Click `Add Interpreter`, then `Add Local Interpreter`

![Alt text](img/img1.png "a title")

- Select `Poetry Environment`, and choose `Existing Environment`
- Navigate to the path of the poetry environment from the terminal earlier, and select `Scripts/python.exe`

![Alt text](img/img2.png "a title")

Now when opening terminal in PyCharm, the environment will already be active. New run configurations can be setup,
and they will already be configured to use this environment.


#### Marking sources root
For PyCharm intellisense to work correctly:
- Right-click `ares-sc2/src` -> Mark Directory as -> Sources Root
![Alt text](img/img3.png "a title")


## Update `ares-sc2`:
This may take a minute or two

`python update_ares.py`

## Format code:
`black .`

`isort .`


## Activating the build runner
Use the example `protoss_builds.yml` as a starting point, rename this file as necessary for your race. If playing as
Random you will need a separate file for each race you want to use the build runner with. in the `Builds`
section of this file start crafting an OpeningBuildOrder.
[Read the docs here for more info](https://aressc2.github.io/ares-sc2/tutorials.html#build-runner-system)

0 comments on commit 3dc4e37

Please sign in to comment.