NachOS
An event-driven StarCraft II bot API for Python, built directly on the StarCraft II client protocol.
Status: alpha. The Terran bot AvocaDOS has played on the AI Arena ladder on NachOS since its version 1.4.0. Until NachOS 1.0, a release may still change the API.
pip install sc2nachos
import sc2nachos
NachOS needs Python 3.12 or later. The distribution and the import name are both sc2nachos. The project is called
NachOS; the bare nachos name on PyPI belongs to an unrelated project.
Getting started
-
Install StarCraft II. On Linux, download Blizzard's headless client from s2client-proto: NachOS is tested against its 4.10 build, 75689, the one the AI Arena ladder plays, and
run_locallogs a warning for any other. On Windows and macOS, Battle.net installs the current build, free to play, which NachOS is not tested on. NachOS finds the game throughSC2PATH, then where the launcher recorded it, then where the platform installs it by default:C:\Program Files (x86)\StarCraft II,/Applications/StarCraft IIor~/StarCraftII. -
Add the maps. NachOS finds a map by its name anywhere under the game's
Mapsfolder, so a folder of maps can go in as it is.sc2maps/AIEholds the AI Arena ladder's maps that NachOS is tested on. -
Play a game.
examples/demo_bot.pyis a whole bot in one file: a Terran that trains SCVs, expands and attacks with marines, and beats the built-in computer at medium difficulty. Save it and run:python demo_bot.py --Map PylonAIE_v4 --ComputerRace ZERG --ComputerDifficulty MEDIUM
What NachOS has
- Units:
api.units, this player's, the enemy's and the map's, remembered structures included, selected by type group, alliance and distance; and a bot's own data for each unit in aUnitDict, which forgets a unit once it dies. - Events for what happens in a game, from a unit's death to an upgrade finishing, each subscribed to with
api.on(guide). - Orders through
api.orders.issue, with what the game refused listed inapi.action_failureson the next turn (guide). - The game's data:
api.data, every unit type, ability, upgrade and weapon from the game's tables, with the tech tree, the structures' footprints and what the tables leave out, measured in the game (reference). - The map:
api.map's heights, ramps and start locations,api.expansions, and each player'sstart_locationwith its main's ramp, its ground, its natural and its thirds (reference). - Placement:
api.placement, where a structure may stand now, sites kept for builds to come, and the walls at a main's ramp (reference). - Pathing:
api.pathing, the cheapest paths on the game's current pathing grid, and the game's own distances (reference). - Combat reads on a unit: the weapon that can hit a target, whether it is in range, one attack's damage and the damage per second.
- Debugging: drawing on the game's screen, cheats and creating units (guide).
- Running a game against the built-in computer, on the ladder, and on GitHub Actions (ladder, GitHub Actions).
- Recordings and replays: a game recorded and played back through a bot with no game client, and a replay played back as one of its players saw it (replays).
- Testing:
sc2nachos.testingmakes units for a bot's unit tests (guide). - Extensions: features a bot opts into, NachOS's or anyone's, which the api builds once the game starts and holds
as
api.extensions. NachOS's own are speed mining and upgrade inference (guide).
Design
You instantiate the API. You do not subclass it, and your bot does not live inside it. NachOS exposes an
Api that owns the client, game state, game data, units, orders and event handlers. Construct one and reach it
however suits your bot — most bots will want a module-level singleton:
# my_bot/api.py
from sc2nachos import Api
api = Api()
# my_bot/economy.py — anywhere else in your bot
from sc2nachos import GameTime
from sc2nachos.events import TurnEvent
from my_bot.api import api
@api.on(TurnEvent, min_interval=GameTime(steps=4))
def manage_workers(event):
for worker in api.units.own.workers.idle:
...
NachOS itself never creates or exposes a singleton and holds no module-level mutable state. The singleton is your choice, confined to one line of your own code. An api plays one game, so a bot plays a game per process, as on a ladder, and two bots playing each other run in a process each. A program that plays several games in one process, such as a script reading replays, makes an api for each.
Your own helpers live in your own modules, as ordinary functions and objects, and there is no mixin to inherit. A
feature a bot opts into, NachOS's or anyone's, is an extension: Api(extensions=Extensions) builds the bot's own
object holding its extensions once the game starts, and api.extensions holds it
(extensions). If you want to subclass so you can
hang a helper off api, that is a gap in NachOS, not a pattern to follow — please open an issue.
Api() is cheap and needs no live connection, so you can construct it at import time and register handlers as
your modules load. Connecting happens later, in the runner:
from sc2nachos import Computer, Difficulty, Race, run_local
run_local("PylonAIE_v4", api, Computer(Race.ZERG, Difficulty.VERY_HARD), race=Race.TERRAN)
Documentation
- API reference: every public module, class and function, from its docstrings, for the latest release.
- Events: every event a game hands out, and how to subscribe to only some of them.
- Orders: how a bot orders its units, and what it learns about each order.
- Debugging: drawing on the game's screen, cheats, and creating units.
- Extensions: features a bot opts into, how to use one and how to write one.
- Running StarCraft II on GitHub Actions: playing matches in a bot repository's workflows.
- Playing on the ladder: one script for the ladder and for local games, and what the ladder passes.
- Testing a bot: making units for a unit test, and playing a bot through a recorded game, with no game client.
- Playing back a replay: a replay played through an api as one of its players saw the game, with every unit besides if the fog is off, and recorded to play again with no game client; or opened with no api, for a tool to read the game's observations itself.
- Migrating from python-sc2: the same bot in both, and where a translation goes wrong; python-sc2 and NachOS has every name and every difference.
- How the game behaves: what StarCraft II was seen to do through the API, by topic, each finding with how it was seen.
License
MIT. See LICENSE, and NOTICE for attribution — NachOS is an independent reimplementation that used python-sc2 (MIT, © 2017 Hannes Karppila) as a reference.
Metadata
Release files for sc2nachos 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sc2nachos-0.3.0.tar.gz | 2.5 MB | With provenance | Details for sc2nachos-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sc2nachos-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for sc2nachos-0.3.0-py3-none-any.whl |
Total release size: 2.9 MB
Release files / sc2nachos-0.3.0.tar.gz
| Download URL | sc2nachos-0.3.0.tar.gz |
|---|---|
| Size | 2.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d6ef654a2fa91d51ef87bcfecc5238cf1e455facc8d4010fb31991657edc862d
|
|
BLAKE2b-256 checksum How to use checksums |
eac99a94b62f9a5d71771475bc71e2919d22cde80b5b97f3f0a109c9409a2b06
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logRelease files / sc2nachos-0.3.0-py3-none-any.whl
| Download URL | sc2nachos-0.3.0-py3-none-any.whl |
|---|---|
| Size | 475.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4845b08daea86c3b8016b764224cc163edacd46222c587f7e8c441b09ccc84c6
|
|
BLAKE2b-256 checksum How to use checksums |
e36a30405a956ab104cf5354eb5dbeaa7421c425efdf76ffde3af6ab58864291
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logSecurity for sc2nachos 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for sc2nachos-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.