https://github.com/AresSC2/cython-extensions-sc2
Optimized Cython functions for `python-sc2` based bots
https://github.com/AresSC2/cython-extensions-sc2
Last synced: about 1 month ago
JSON representation
Optimized Cython functions for `python-sc2` based bots
- Host: GitHub
- URL: https://github.com/AresSC2/cython-extensions-sc2
- Owner: AresSC2
- License: gpl-3.0
- Created: 2024-01-24T12:12:59.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-06-19T14:01:15.000Z (12 months ago)
- Last Synced: 2024-10-03T01:50:42.223Z (8 months ago)
- Language: Cython
- Homepage: https://aressc2.github.io/cython-extensions-sc2/
- Size: 2.38 MB
- Stars: 2
- Watchers: 0
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-sc2-ai - cython-extensions-sc2 - Cython extensions extracted from ares-sc2, for use in any python-sc2 based bot. (Libraries / Python Libraries)
README
[](https://github.com/AresSC2/cython-extensions-sc2/actions/workflows/test.yml)
[](https://github.com/AresSC2/cython-extensions-sc2/actions/workflows/pages.yml)
# cython-extensions-sc2
[API Documentation](https://aressc2.github.io/cython-extensions-sc2/) - for a full list of included functions.
`cython-extensions-sc2` is a library designed for the [python-sc2](https://github.com/BurnySc2/python-sc2) API.
Its purpose is to offer optimized Cython alternatives for commonly used functions,
along with additional useful custom functions.
Note: This library is included for `ares-sc2` users by default, no further setup is required.
This library also supports `python-sc2` and `sharpy-sc2` bots, see Getting Started below.
Example speedups, results may vary depending on machine and exact scenario.
This is by no means a list of all functionality offered.
| function | speedup |
|-------------------------------|-----------------------------------------|
| `units.closest_to` | 6.85 - 13x speedup depending on scenario |
| `distance_to` | 3 to 7x speedup depending on scenario |
| `position.center` | 2x speedup |
| `already_pending` for units | 6.62x speedup |
| `units.in_attack_range` | 2.05x speedup |
| `units.sorted_by_distance_to` | 8.62x speedup |
| `unit.is_facing` | 9.1x speedup |
| `Point2.towards` | 14.29x speedup |
Tip: use `cy_distance_to_squared` where possible for extra 1.3x speedup.
## Getting started
To quickly get up and running locally (for python versions 3.10, 3.11, 3.12, 3.13), install `cython-extensions-sc2` with:
`pip install cython-extensions-sc2`
### Shipping to ladder
When shipping to [ladder](https://aiarena.net/), grab `ubuntu-latest_python3.12.zip` from releases in this repo
and extract `cython_extensions` directory within the zip to the root of your bot's directory, like so:
```
MyBot
└───cython_extensions
│ └───cython-extensions library files
└───your bot files and directories
```
### Alternative local setup
If you already have a `python-sc2`, or `sharpy-sc2` development environment setup,
then `cython-extensions` should work out the box with your bot without the need to install extra requirements. Simply check out the releases on this
repo and download the correct `zip` for your system.
For example a Windows user should download `windows-latest_python3.1.zip`.
Inside this zip you will find a `cython_extensions` directory, this should be placed in your bot's root directory
like so:
```
MyBot
└───cython_extensions
│ └───cython-extensions library files
└───your bot files and directories
```
### Start using `cython-extensions-sc2`
For ease of use all cython functions are importable via the main module, for example:
```python
from cython_extensions import cy_distance_to, cy_attack_ready, cy_closest_to
```
note: in this project all library functions have a `cy_` prefix to prevent confusion with python alternatives.
### Contributor / Cloning the project
Install [poetry](https://python-poetry.org/) if you do not already have it installed.
Then to setup a full development environment run:
`poetry install --with dev,test,docs,semver`
This will set up a new environment, install all required dependencies and compile the cython code for your system.
If you modify the cython code, run `poetry build` to compile it.
#### Jupyter Notebooks
Run `poetry run jupyter notebook` to open jupyter notebook in the environment. See the notebooks
directory for examples. Use `template_notebook.ipynb` as a starting point for your own notebooks.
#### Run Test Bot
Edit the map in `bot_test.py` and run with:
`poetry run python tests/bot_test.py`
#### Contributing
Contributors are very welcome! There are many missing alternative `python-sc2` functions, and if you're
into optimization, the existing functions could likely be improved.
Please use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) if you choose to contribute,
it helps the automatic releases detect
a new version and generates an accurate changelog.
Example git messages:
`feat: add new cython function`
`fix: fixed buggy function`
`test: add new test`
`ci: update github workflow`
`docs: add new docs`
`chore: add dependency`