sc2nachos 0.1.0__tar.gz

sc2nachos-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+.idea
+.vscode
+.claude/*
+!.claude/CLAUDE.md
+!.claude/plans/
+.env
+
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+# Written by hatch-vcs from the git tag.
+src/sc2nachos/__about__.py
+
+.venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/

sc2nachos-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max Nusspickel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sc2nachos-0.1.0/NOTICE

@@ -0,0 +1,47 @@
+NachOS (sc2nachos)
+Copyright (c) 2026 Max Nusspickel
+
+This product is an independent reimplementation of a StarCraft II client API.
+It is not a clean-room implementation: python-sc2 was read and used as a
+reference during development, and portions of this library are derived from or
+directly informed by it.
+
+-------------------------------------------------------------------------------
+
+python-sc2
+https://github.com/BurnySc2/python-sc2
+
+MIT License
+
+Copyright (c) 2017 Hannes Karppila
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-------------------------------------------------------------------------------
+
+StarCraft II Client Protocol
+https://github.com/Blizzard/s2client-proto
+
+Protocol definitions are consumed via the pys2clientprotocol package. StarCraft
+II and its API are the property of Blizzard Entertainment, Inc. Use of the
+StarCraft II client is subject to the AI and Machine Learning License at
+https://blzdistsc2-a.akamaihd.net/AI_AND_MACHINE_LEARNING_LICENSE.html
+
+Identifier data generated from the game's stableid.json is derived from
+StarCraft II game data and remains the property of Blizzard Entertainment, Inc.

sc2nachos-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: sc2nachos
+Version: 0.1.0
+Summary: NachOS — an event-driven StarCraft II bot API for Python
+Project-URL: Homepage, https://github.com/maxnus/NachOS
+Project-URL: Repository, https://github.com/maxnus/NachOS
+Project-URL: Documentation, https://maxnus.github.io/NachOS/
+Author-email: Max Nusspickel <max.nusspickel@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: AI,Bot,StarCraft,StarCraft 2,StarCraft II
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Real Time Strategy
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: loguru>=0.7
+Requires-Dist: numpy>=2.0
+Requires-Dist: pys2clientprotocol>=1.0.2
+Requires-Dist: scipy>=1.14
+Requires-Dist: semita>=0.2.1
+Requires-Dist: websocket-client>=1.9
+Provides-Extra: dev
+Requires-Dist: pdoc>=15; extra == 'dev'
+Requires-Dist: pyright>=1.1.390; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# NachOS
+
+An event-driven StarCraft II bot API for Python, built directly on the
+[StarCraft II client protocol](https://github.com/Blizzard/s2client-proto).
+
+> **Status: alpha.** The Terran bot [AvocaDOS](https://github.com/maxnus/AvocaDOS) has played on the
+> [AI Arena](https://aiarena.net/) ladder on NachOS since its version 1.4.0. Until NachOS 1.0, a release may still
+> change the API.
+
+```bash
+pip install sc2nachos
+```
+
+```python
+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](https://github.com/Blizzard/s2client-proto#downloads): 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`](https://github.com/maxnus/NachOS/tree/main/sc2maps/AIE) holds the AI Arena
+   ladder's maps that NachOS is tested on.
+3. **Play a game.** [`examples/demo_bot.py`](https://github.com/maxnus/NachOS/blob/main/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:
+
+   ```bash
+   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](https://maxnus.github.io/NachOS/sc2nachos/units.html#UnitType), alliance and distance; and a bot's own
+  data for each unit in a [`UnitDict`](https://maxnus.github.io/NachOS/sc2nachos/units.html#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](https://github.com/maxnus/NachOS/blob/main/docs/events.md)).
+- **Orders** through `api.orders.issue`, with what the game refused listed in `api.action_failures` on the next turn
+  ([guide](https://github.com/maxnus/NachOS/blob/main/docs/orders.md)).
+- **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](https://maxnus.github.io/NachOS/sc2nachos/gamedata.html)).
+- **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](https://maxnus.github.io/NachOS/sc2nachos/gamemap.html)).
+- **Placement**: `api.placement`, where a structure may stand now, sites kept for builds to come, and the walls at a
+  main's ramp ([reference](https://maxnus.github.io/NachOS/sc2nachos/placement.html)).
+- **Pathing**: `api.pathing`, the cheapest paths on the game's current pathing grid, and the game's own distances
+  ([reference](https://maxnus.github.io/NachOS/sc2nachos/pathing.html)).
+- **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](https://github.com/maxnus/NachOS/blob/main/docs/debugging.md)).
+- **Running** a game against the built-in computer, on the ladder, and on GitHub Actions
+  ([ladder](https://github.com/maxnus/NachOS/blob/main/docs/ladder.md),
+  [GitHub Actions](https://github.com/maxnus/NachOS/blob/main/docs/github-actions.md)).
+- **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](https://github.com/maxnus/NachOS/blob/main/docs/replays.md)).
+- **Testing**: `sc2nachos.testing` makes units for a bot's unit tests
+  ([guide](https://github.com/maxnus/NachOS/blob/main/docs/testing.md)).
+- **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](https://github.com/maxnus/NachOS/blob/main/docs/extensions.md)).
+
+## 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:
+
+```python
+# my_bot/api.py
+from sc2nachos import Api
+
+api = Api()
+```
+
+```python
+# 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](https://github.com/maxnus/NachOS/blob/main/docs/extensions.md)). 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:
+
+```python
+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](https://maxnus.github.io/NachOS/): every public module, class and function, from its docstrings,
+  for the latest release.
+- [Events](https://github.com/maxnus/NachOS/blob/main/docs/events.md): every event a game hands out, and how to
+  subscribe to only some of them.
+- [Orders](https://github.com/maxnus/NachOS/blob/main/docs/orders.md): how a bot orders its units, and what it learns
+  about each order.
+- [Debugging](https://github.com/maxnus/NachOS/blob/main/docs/debugging.md): drawing on the game's screen, cheats, and
+  creating units.
+- [Extensions](https://github.com/maxnus/NachOS/blob/main/docs/extensions.md): features a bot opts into, how to use
+  one and how to write one.
+- [Running StarCraft II on GitHub Actions](https://github.com/maxnus/NachOS/blob/main/docs/github-actions.md): playing
+  matches in a bot repository's workflows.
+- [Playing on the ladder](https://github.com/maxnus/NachOS/blob/main/docs/ladder.md): one script for the ladder and
+  for local games, and what the ladder passes.
+- [Testing a bot](https://github.com/maxnus/NachOS/blob/main/docs/testing.md): making units for a unit test, and
+  playing a bot through a recorded game, with no game client.
+- [Playing back a replay](https://github.com/maxnus/NachOS/blob/main/docs/replays.md): 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.
+- [Migrating from python-sc2](https://github.com/maxnus/NachOS/blob/main/docs/migrating-from-python-sc2.md): the same
+  bot in both, and where a translation goes wrong;
+  [python-sc2 and NachOS](https://github.com/maxnus/NachOS/blob/main/docs/reference/python-sc2.md) has every name and
+  every difference.
+- [How the game behaves](https://github.com/maxnus/NachOS/blob/main/docs/reference/game-behavior/README.md): what
+  StarCraft II was seen to do through the API, by topic, each finding with how it was seen.
+
+## License
+
+MIT. See [LICENSE](https://github.com/maxnus/NachOS/blob/main/LICENSE), and
+[NOTICE](https://github.com/maxnus/NachOS/blob/main/NOTICE) for attribution — NachOS is an independent
+reimplementation that used [python-sc2](https://github.com/BurnySc2/python-sc2) (MIT, © 2017 Hannes Karppila) as a
+reference.

sc2nachos-0.1.0/README.md

@@ -0,0 +1,155 @@
+# NachOS
+
+An event-driven StarCraft II bot API for Python, built directly on the
+[StarCraft II client protocol](https://github.com/Blizzard/s2client-proto).
+
+> **Status: alpha.** The Terran bot [AvocaDOS](https://github.com/maxnus/AvocaDOS) has played on the
+> [AI Arena](https://aiarena.net/) ladder on NachOS since its version 1.4.0. Until NachOS 1.0, a release may still
+> change the API.
+
+```bash
+pip install sc2nachos
+```
+
+```python
+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](https://github.com/Blizzard/s2client-proto#downloads): 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`](https://github.com/maxnus/NachOS/tree/main/sc2maps/AIE) holds the AI Arena
+   ladder's maps that NachOS is tested on.
+3. **Play a game.** [`examples/demo_bot.py`](https://github.com/maxnus/NachOS/blob/main/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:
+
+   ```bash
+   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](https://maxnus.github.io/NachOS/sc2nachos/units.html#UnitType), alliance and distance; and a bot's own
+  data for each unit in a [`UnitDict`](https://maxnus.github.io/NachOS/sc2nachos/units.html#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](https://github.com/maxnus/NachOS/blob/main/docs/events.md)).
+- **Orders** through `api.orders.issue`, with what the game refused listed in `api.action_failures` on the next turn
+  ([guide](https://github.com/maxnus/NachOS/blob/main/docs/orders.md)).
+- **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](https://maxnus.github.io/NachOS/sc2nachos/gamedata.html)).
+- **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](https://maxnus.github.io/NachOS/sc2nachos/gamemap.html)).
+- **Placement**: `api.placement`, where a structure may stand now, sites kept for builds to come, and the walls at a
+  main's ramp ([reference](https://maxnus.github.io/NachOS/sc2nachos/placement.html)).
+- **Pathing**: `api.pathing`, the cheapest paths on the game's current pathing grid, and the game's own distances
+  ([reference](https://maxnus.github.io/NachOS/sc2nachos/pathing.html)).
+- **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](https://github.com/maxnus/NachOS/blob/main/docs/debugging.md)).
+- **Running** a game against the built-in computer, on the ladder, and on GitHub Actions
+  ([ladder](https://github.com/maxnus/NachOS/blob/main/docs/ladder.md),
+  [GitHub Actions](https://github.com/maxnus/NachOS/blob/main/docs/github-actions.md)).
+- **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](https://github.com/maxnus/NachOS/blob/main/docs/replays.md)).
+- **Testing**: `sc2nachos.testing` makes units for a bot's unit tests
+  ([guide](https://github.com/maxnus/NachOS/blob/main/docs/testing.md)).
+- **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](https://github.com/maxnus/NachOS/blob/main/docs/extensions.md)).
+
+## 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:
+
+```python
+# my_bot/api.py
+from sc2nachos import Api
+
+api = Api()
+```
+
+```python
+# 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](https://github.com/maxnus/NachOS/blob/main/docs/extensions.md)). 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:
+
+```python
+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](https://maxnus.github.io/NachOS/): every public module, class and function, from its docstrings,
+  for the latest release.
+- [Events](https://github.com/maxnus/NachOS/blob/main/docs/events.md): every event a game hands out, and how to
+  subscribe to only some of them.
+- [Orders](https://github.com/maxnus/NachOS/blob/main/docs/orders.md): how a bot orders its units, and what it learns
+  about each order.
+- [Debugging](https://github.com/maxnus/NachOS/blob/main/docs/debugging.md): drawing on the game's screen, cheats, and
+  creating units.
+- [Extensions](https://github.com/maxnus/NachOS/blob/main/docs/extensions.md): features a bot opts into, how to use
+  one and how to write one.
+- [Running StarCraft II on GitHub Actions](https://github.com/maxnus/NachOS/blob/main/docs/github-actions.md): playing
+  matches in a bot repository's workflows.
+- [Playing on the ladder](https://github.com/maxnus/NachOS/blob/main/docs/ladder.md): one script for the ladder and
+  for local games, and what the ladder passes.
+- [Testing a bot](https://github.com/maxnus/NachOS/blob/main/docs/testing.md): making units for a unit test, and
+  playing a bot through a recorded game, with no game client.
+- [Playing back a replay](https://github.com/maxnus/NachOS/blob/main/docs/replays.md): 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.
+- [Migrating from python-sc2](https://github.com/maxnus/NachOS/blob/main/docs/migrating-from-python-sc2.md): the same
+  bot in both, and where a translation goes wrong;
+  [python-sc2 and NachOS](https://github.com/maxnus/NachOS/blob/main/docs/reference/python-sc2.md) has every name and
+  every difference.
+- [How the game behaves](https://github.com/maxnus/NachOS/blob/main/docs/reference/game-behavior/README.md): what
+  StarCraft II was seen to do through the API, by topic, each finding with how it was seen.
+
+## License
+
+MIT. See [LICENSE](https://github.com/maxnus/NachOS/blob/main/LICENSE), and
+[NOTICE](https://github.com/maxnus/NachOS/blob/main/NOTICE) for attribution — NachOS is an independent
+reimplementation that used [python-sc2](https://github.com/BurnySc2/python-sc2) (MIT, © 2017 Hannes Karppila) as a
+reference.