Skip to main content

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

  1. 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_local logs 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 through SC2PATH, then where the launcher recorded it, then where the platform installs it by default: C:\Program Files (x86)\StarCraft II, /Applications/StarCraft II or ~/StarCraftII.

  2. Add the maps. NachOS finds a map by its name anywhere under the game's Maps folder, so a folder of maps can go in as it is. sc2maps/AIE holds the AI Arena ladder's maps that NachOS is tested on.

  3. Play a game. examples/demo_bot.py is 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 a UnitDict, 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 in api.action_failures on 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's start_location with 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.testing makes 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)

Source distribution for sc2nachos 0.3.0
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)

Table of built distributions (wheels) for sc2nachos 0.3.0
File Interpreter ABI Platform Actions
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 log

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

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

Select from 2 files

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 log

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

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page