Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/AresSC2/cython-extensions-sc2
Optimized Cython functions for `python-sc2` based bots
https://github.com/AresSC2/cython-extensions-sc2
Last synced: 3 months 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 (10 months ago)
- Default Branch: main
- Last Pushed: 2024-06-19T14:01:15.000Z (5 months ago)
- Last Synced: 2024-07-22T02:23:05.161Z (4 months ago)
- Language: Cython
- Homepage: https://aressc2.github.io/cython-extensions-sc2/
- Size: 2.38 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
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.
For bot authors who have a working development environment for `python-sc2` or `sharpy-sc2`,
there are no additional requirements. Simply check out the releases, download the appropriate zip for your system,
and place the cython_extensions
folder in your bot's root directory. Each release includes a binary that is compatible with the ai-arena
ladder, making it ready for deployment.
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
Note: currently only python 3.11 is supported unless you clone the project and compile it yourself, more
versions will be supported in the future.
To quickly get up and running locally, install with:
`pip install cython-extensions-sc2`
But when shipping to ladder, grab `ubuntu-latest_python3.11.zip` from releases in this repo
and extract `cython_extensions` directory within the zip to the root of your bot's directory.
### Bot developer
If you already have a `python-sc2`, or `sharpy-sc2` development environment setup,
then `cython-extensions` should work out the box with your bot. 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.11.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
```
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
1. Install [poetry](https://python-poetry.org/)
2. Run `poetry install`
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.
#### 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`