### Define StarCraft II installation path

Source: https://github.com/burnysc2/python-sc2/blob/develop/README.md

Example path for a default Lutris installation on Linux.

```text
/home/burny/Games/battlenet/drive_c/Program Files (x86)/StarCraft II/
```

--------------------------------

### Configure and Run Bots

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/docker.md

Commands to install dependencies, copy configuration files, and execute the match runner.

```bash
docker exec -i app uv add "burnysc2>=0.12.12"
```

```bash
docker cp bat_files/docker/custom_run_local.py app:/root/aiarena-client/arenaclient/run_local.py
```

```bash
docker exec -i app uv run python /root/aiarena-client/arenaclient/run_local.py
```

--------------------------------

### Install python-sc2 from GitHub

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/introduction.md

Use this command to install the library directly from the develop branch on GitHub.

```default
pip install --upgrade --force-reinstall https://github.com/BurnySc2/python-sc2/archive/develop.zip
```

--------------------------------

### Install python-sc2 via pip

Source: https://github.com/burnysc2/python-sc2/blob/develop/README.md

Commands to install the library from PyPI or the development branch.

```bash
pip install --upgrade burnysc2
```

```bash
pip install --upgrade --force-reinstall https://github.com/BurnySc2/python-sc2/archive/develop.zip
```

--------------------------------

### Run pre-commit hooks

Source: https://github.com/burnysc2/python-sc2/blob/develop/README.md

Commands to install and execute pre-commit hooks for autoformatting and import sorting.

```sh
uv run pre-commit install
uv run pre-commit run --all-files --hook-stage pre-push
```

--------------------------------

### Create a basic worker rush bot

Source: https://github.com/burnysc2/python-sc2/blob/develop/README.md

A minimal implementation of a bot that commands workers to attack the enemy starting location on the first iteration.

```python
from sc2 import maps
from sc2.player import Bot, Computer
from sc2.main import run_game
from sc2.data import Race, Difficulty
from sc2.bot_ai import BotAI

class WorkerRushBot(BotAI):
    async def on_step(self, iteration: int):
        if iteration == 0:
            for worker in self.workers:
                worker.attack(self.enemy_start_locations[0])

run_game(maps.get("Abyssal Reef LE"), [
    Bot(Race.Zerg, WorkerRushBot()),
    Computer(Race.Protoss, Difficulty.Medium)
], realtime=True)
```

--------------------------------

### Run a bot instance

Source: https://github.com/burnysc2/python-sc2/blob/develop/README.md

Execute a bot script to launch the StarCraft II client.

```sh
python examples/protoss/cannon_rush.py
```

--------------------------------

### Create a basic bot

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/introduction.md

Define a bot class inheriting from BotAI and run a game instance using sc2.run_game.

```default
import sc2
from sc2.bot_ai import BotAI
from sc2.player import Bot, Computer

class MyBot(BotAI):
    async def on_step(self, iteration: int):
        print(f"This is my bot in iteration {iteration}!")

sc2.run_game(
    sc2.maps.get("AcropolisLE"),
    [Bot(sc2.Race.Zerg, MyBot()), Computer(sc2.Race.Zerg, sc2.Difficulty.Hard)],
    realtime=False,
)
```

--------------------------------

### Configure game_step

Source: https://github.com/burnysc2/python-sc2/blob/develop/README.md

Controls the frequency of the bot's step method. Must be set in on_start, not __init__.

```python
class MyBot(BotAI):
    def __init__(self):
        pass  # don't set it here!

    async def on_start(self):
        self.client.game_step: int = 2
```

--------------------------------

### Build a structure manually

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/introduction.md

Full workflow for building a structure by checking affordability, availability, finding a worker, and placing the building.

```default
if self.can_afford(UnitTypeId.SPAWNINGPOOL) and self.already_pending(UnitTypeId.SPAWNINGPOOL) + self.structures.filter(lambda structure: structure.type_id == UnitTypeId.SPAWNINGPOOL and structure.is_ready).amount == 0:
    worker_candidates = self.workers.filter(lambda worker: (worker.is_collecting or worker.is_idle) and worker.tag not in self.unit_tags_received_action)
    # Worker_candidates can be empty
    if worker_candidates:
        map_center = self.game_info.map_center
        position_towards_map_center = self.start_location.towards(map_center, distance=5)
        placement_position = await self.find_placement(UnitTypeId.SPAWNINGPOOL, near=position_towards_map_center, placement_step=1)
        # Placement_position can be None
        if placement_position:
            build_worker = worker_candidates.closest_to(placement_position)
            build_worker.build(UnitTypeId.SPAWNINGPOOL, placement_position)
```

--------------------------------

### Configure Linux environment variables

Source: https://github.com/burnysc2/python-sc2/blob/develop/README.md

Required environment variables for running StarCraft II on Linux via Wine.

```bash
SC2PF=WineLinux
WINE=/usr/bin/wine
# Or a wine binary from lutris:
# WINE=/home/burny/.local/share/lutris/runners/wine/lutris-4.20-x86_64/bin/wine64
# Default Lutris StarCraftII Installation path:
SC2PATH='/home/burny/Games/battlenet/drive_c/Program Files (x86)/StarCraft II/'
```

--------------------------------

### Build a structure using convenience function

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/introduction.md

Uses the self.build helper to automatically select a worker and find a valid placement position.

```default
if self.can_afford(UnitTypeId.SPAWNINGPOOL) and self.already_pending(UnitTypeId.SPAWNINGPOOL) + self.structures.filter(lambda structure: structure.type_id == UnitTypeId.SPAWNINGPOOL and structure.is_ready).amount == 0:
    map_center = self.game_info.map_center
    position_towards_map_center = self.start_location.towards(map_center, distance=5)
    await self.build(UnitTypeId.SPAWNINGPOOL, near=position_towards_map_center, placement_step=1)
```

--------------------------------

### Extract Results and Replays

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/docker.md

Commands to copy result files and replay data from the container to the host machine.

```bash
mkdir -p temp
docker cp app:/root/aiarena-client/arenaclient/proxy/results.json temp/results.json
```

```bash
mkdir -p temp/replays
docker cp app:/root/StarCraftII/Replays/. temp/replays
```

--------------------------------

### Configure WSL2 network variables

Source: https://github.com/burnysc2/python-sc2/blob/develop/README.md

Environment variables required for bot connectivity in WSL version 2.

```text
SC2CLIENTHOST=<your windows IP>
SC2SERVERHOST=0.0.0.0
```

--------------------------------

### Train a Drone using AbilityId

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/introduction.md

Basic method to train a unit by selecting a larva and issuing a train ability command.

```default
from sc2.ids.ability_id import AbilityId

my_larva = self.larva.random
my_larva(AbilityId.LARVATRAIN_DRONE)
```

--------------------------------

### Export WSL environment variables

Source: https://github.com/burnysc2/python-sc2/blob/develop/README.md

Commands to export host connection variables in a shell configuration file.

```bash
export SC2CLIENTHOST
export SC2SERVERHOST
```

--------------------------------

### Manage Docker Containers

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/docker.md

Commands for removing existing containers and launching new ones in interactive mode.

```bash
docker run -it -d --name app test_image
```

```bash
docker run -it -d --name app burnysc2/python-sc2-docker:release-python_3.10-sc2_4.10_arenaclient_burny
```

--------------------------------

### Pull Docker Image

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/docker.md

Download the official SC2 Docker image configured for Python 3.10.

```bash
docker pull burnysc2/python-sc2-docker:release-python_3.10-sc2_4.10_arenaclient_burny
```

--------------------------------

### Performant Batch Training of Drones

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/introduction.md

Iterates through available larva to train multiple drones if resources and supply allow.

```default
for loop_larva in self.larva:
    if self.can_afford(UnitTypeId.DRONE):
        loop_larva.train(UnitTypeId.DRONE)
        # Add break statement here if you only want to train one
    else:
        # Can't afford drones anymore
        break
```

--------------------------------

### Configure raw_affects_selection

Source: https://github.com/burnysc2/python-sc2/blob/develop/README.md

Enable this setting to improve bot performance.

```python
class MyBot(BotAI):
    def __init__(self):
        self.raw_affects_selection = True
```

--------------------------------

### Train a Drone with Cost and Supply Tracking

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/introduction.md

Updates the bot's internal state for minerals and supply immediately upon issuing the command.

```default
self.larva.random(AbilityId.LARVATRAIN_DRONE, subtract_cost=True, subtract_supply=True)
```

--------------------------------

### Configure unit_command_uses_self_do

Source: https://github.com/burnysc2/python-sc2/blob/develop/README.md

Enable this setting if the bot issues commands using self.do().

```python
class MyBot(BotAI):
    def __init__(self):
        self.unit_command_uses_self_do = True
```

--------------------------------

### Disable WSL detection in Python

Source: https://github.com/burnysc2/python-sc2/blob/develop/README.md

Use this to force Linux StarCraft II execution when running inside WSL.

```python
import os
os.environ["SC2_WSL_DETECT"] = "0"
```

--------------------------------

### Check for existing structures

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/introduction.md

Verifies that no instances of a specific building type are currently pending or completed.

```default
if self.already_pending(UnitTypeId.SPAWNINGPOOL) + self.structures.filter(lambda structure: structure.type_id == UnitTypeId.SPAWNINGPOOL and structure.is_ready).amount == 0:
    # Build spawning pool
```

--------------------------------

### Access bot information

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/introduction.md

Properties available within the bot class to track resources, supply, and unit counts.

```default
# Resources and supply
self.minerals: int
self.vespene: int
self.supply_army: int # 0 at game start
self.supply_workers: int # 12 at game start
self.supply_cap: int # 14 for zerg, 15 for T and P at game start
self.supply_used: int # 12 at game start
self.supply_left: int # 2 for zerg, 3 for T and P at game start

# Units
self.warp_gate_count: Units # Your warp gate count (only protoss)
self.idle_worker_count: int # Workers that are doing nothing
self.army_count: int # Amount of army units
self.workers: Units # Your workers
self.larva: Units # Your larva (only zerg)
self.townhalls: Units # Your townhalls (nexus, hatchery, lair, hive, command center, orbital command, planetary fortress
self.gas_buildings: Units # Your gas structures (refinery, extractor, assimilator
self.units: Units # Your units (includes larva and workers)
self.structures: Units # Your structures (includes townhalls and gas buildings)

# Other information about your bot
self.race: Race # The race your bot plays. If you chose random, your bot gets assigned a race and the assigned race will be in here (not random)
self.player_id: int # Your bot id (can be 1 or 2 in a 2 player game)
# Your spawn location (your first townhall location)
self.start_location: Point2
# Location of your main base ramp, and has some information on how to wall the main base as terran bot (see GameInfo)
self.main_base_ramp: Ramp
```

--------------------------------

### Train a Drone using the API train function

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/introduction.md

High-level method that automatically finds a valid structure and handles resource/supply deduction.

```default
self.train(UnitTypeId.DRONE, amount=1)
```

--------------------------------

### Find valid building placement

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/introduction.md

Uses find_placement to locate a valid position for a structure near a target point. Returns None if no valid position is found.

```default
map_center = self.game_info.map_center
position_towards_map_center = self.start_location.towards(map_center, distance=5)
placement_position = await self.find_placement(UnitTypeId.SPAWNINGPOOL, near=position_towards_map_center, placement_step=1)
# Can return None if no position was found
if placement_position:
```

--------------------------------

### Remove all Docker images

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/docker.md

Deletes all images stored on the local system by passing the output of docker images -q to the rmi command.

```default
docker rmi $(docker images -q)
```

--------------------------------

### Access neutral and game state information

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/introduction.md

Properties for accessing neutral units, map data, and current game state metrics.

```default
# Neutral units and structures
self.mineral_field: Units # All mineral fields on the map
self.vespene_geyser: Units # All vespene fields, even those that have a gas building on them
self.resources: Units # Both of the above combined
self.destructables: Units # All destructable rocks (except the platforms below the main base ramp)
self.watchtowers: Units # All watch towers on the map (some maps don't have watch towers)
self.all_units: Units # All units combined: yours, enemy's and neutral

# Locations of possible expansions
self.expansion_locations: dict[Point2, Units]

# Game data about units, abilities and upgrades (see game_data.py)
self.game_data: GameData

# Information about the map: pathing grid, building placement, terrain height, vision and creep are found here (see game_info.py)
self.game_info: GameInfo

# Other information that gets updated every step (see game_state.py)
self.state: GameState

# Extra information
self.realtime: bool # Displays if the game was started in realtime or not. In realtime, your bot only has limited time to execute on_step()
self.time: float # The current game time in seconds
self.time_formatted: str # The current game time properly formatted in 'min:sec'
```

--------------------------------

### Safe Batch Training with Tag Validation

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/introduction.md

Prevents issuing multiple commands to the same unit in a single frame by checking against unit_tags_received_action.

```default
for loop_larva in self.larva:
    if loop_larva.tag in self.unit_tags_received_action:
        continue
    if self.can_afford(UnitTypeId.DRONE):
        loop_larva.train(UnitTypeId.DRONE)
        # Add break statement here if you only want to train one
    else:
        # Can't afford drones anymore
        break
```

--------------------------------

### Access enemy information

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/introduction.md

Properties to retrieve data about enemy units, structures, and spawn locations within vision range.

```default
# The following contains enemy units and structures inside your units' vision range (including invisible units, but not burrowed units)
self.enemy_units: Units
self.enemy_structures: Units

# Enemy spawn locations as a list of Point2 points
self.enemy_start_locations: list[Point2]

# Enemy units that are inside your sensor tower range
self.blips: set[Blip]

# The enemy race. If the enemy chose random, this will stay at random forever
self.enemy_race: Race
```

--------------------------------

### Train a Drone using UnitTypeId

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/introduction.md

Uses the unit type ID to automatically resolve the required ability ID for training.

```default
from sc2.ids.unit_typeid import UnitTypeId

self.larva.random.train(UnitTypeId.DRONE)
```

--------------------------------

### Calculate building placement position

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/introduction.md

Determines a target coordinate for a building relative to the map center.

```default
map_center = self.game_info.map_center
placement_position = self.start_location.towards(map_center, distance=5)
```

--------------------------------

### Prune Docker system resources

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/docker.md

Removes unused data including stopped containers, networks, and dangling images, with the --volumes flag to also remove unused volumes.

```default
docker system prune --volumes
```

--------------------------------

### Configure distance_calculation_method

Source: https://github.com/burnysc2/python-sc2/blob/develop/README.md

Set the method used for distance calculations, where 0 is raw python, 1 is scipy pdist, and 2 is scipy cdist.

```python
class MyBot(BotAI):
    def __init__(self):
        self.distance_calculation_method: int = 2
```

--------------------------------

### Force remove all Docker containers

Source: https://github.com/burnysc2/python-sc2/blob/develop/docs_generate/text_files/docker.md

Removes all containers, including those currently running, by passing the output of docker ps -aq to the rm command.

```default
docker rm -f $(docker ps -aq)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.