cython-extensions-sc2 0.4.2

No project description provided

cython-extensions-sc2

API Documentation - for a full list of included functions.

cython-extensions-sc2 is a library designed for the 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:

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
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 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