sc2nachos.match
The players of a match, this player and the enemy as the game describes them, how the computer opponent plays, and how the match ended.
1"""The players of a match, this player and the enemy as the game describes them, how the computer opponent plays, 2and how the match ended.""" 3 4from sc2nachos.match._enemy import Enemy 5from sc2nachos.match._errors import NoStartLocationError 6from sc2nachos.match._match import AIBuild, Computer, Difficulty, Participant, PlayerSetup, Race, Result 7from sc2nachos.match._player import Player 8 9__all__ = [ 10 "AIBuild", 11 "Computer", 12 "Difficulty", 13 "Enemy", 14 "NoStartLocationError", 15 "Participant", 16 "Player", 17 "PlayerSetup", 18 "Race", 19 "Result", 20]
86class AIBuild(ReadableIntEnum): 87 """Which opening the built-in computer opponent favors.""" 88 89 RANDOM = sc2api_pb2.AIBuild.RandomBuild 90 RUSH = sc2api_pb2.AIBuild.Rush 91 TIMING = sc2api_pb2.AIBuild.Timing 92 POWER = sc2api_pb2.AIBuild.Power 93 MACRO = sc2api_pb2.AIBuild.Macro 94 AIR = sc2api_pb2.AIBuild.Air
Which opening the built-in computer opponent favors.
102@dataclass(frozen=True, slots=True) 103class Computer: 104 """The built-in computer opponent. It needs no client.""" 105 106 race: Race = Race.RANDOM 107 difficulty: Difficulty = Difficulty.VERY_HARD 108 build: AIBuild = AIBuild.RANDOM 109 name: str | None = None
The built-in computer opponent. It needs no client.
71class Difficulty(ReadableIntEnum): 72 """How strongly the built-in computer opponent plays. The `CHEAT_` levels break the game's own rules.""" 73 74 VERY_EASY = sc2api_pb2.Difficulty.VeryEasy 75 EASY = sc2api_pb2.Difficulty.Easy 76 MEDIUM = sc2api_pb2.Difficulty.Medium 77 MEDIUM_HARD = sc2api_pb2.Difficulty.MediumHard 78 HARD = sc2api_pb2.Difficulty.Hard 79 HARDER = sc2api_pb2.Difficulty.Harder 80 VERY_HARD = sc2api_pb2.Difficulty.VeryHard 81 CHEAT_VISION = sc2api_pb2.Difficulty.CheatVision 82 CHEAT_MONEY = sc2api_pb2.Difficulty.CheatMoney 83 CHEAT_INSANE = sc2api_pb2.Difficulty.CheatInsane
How strongly the built-in computer opponent plays. The CHEAT_ levels break the game's own rules.
20@final 21class Enemy: 22 """The other player, and what NachOS has learned or been told about it. `game_data` says which upgrades each upgrade 23 needs researched first.""" 24 25 __slots__ = ( 26 "_game_data", 27 "_id", 28 "_ladder_id", 29 "_name", 30 "_race", 31 "_requested_race", 32 "_start_location", 33 "_start_locations", 34 "_upgrades", 35 ) 36 37 def __init__( 38 self, 39 *, 40 player_id: int, 41 requested_race: Race, 42 name: str | None, 43 race: Race | None, 44 ladder_id: str | None, 45 game_data: GameData, 46 ) -> None: 47 self._game_data = game_data 48 self._id = player_id 49 self._requested_race = requested_race 50 self._name = name 51 self._race = race 52 self._ladder_id = ladder_id 53 # Replaced whole on every change, since units read it as part of a key many times a step. 54 self._upgrades: frozenset[UpgradeId] = frozenset() 55 # Where it may have started, the map's start locations but this player's: `None` for one no expansion stands at. 56 self._start_locations: tuple[StartLocation | None, ...] = () 57 # Where it started: the other start on a map of two, else the one the bot named, if it has. 58 self._start_location: StartLocation | None = None 59 60 def __repr__(self) -> str: 61 race = None if self._race is None else self._race.name 62 return ( 63 f"Enemy(id={self._id}, race={race}, requested_race={self._requested_race.name}, name={self._name!r}, " 64 f"ladder_id={self._ladder_id!r})" 65 ) 66 67 @classmethod 68 def _from_game( 69 cls, info: sc2api_pb2.ResponseGameInfo, player_id: int, *, game_data: GameData, ladder_id: str | None = None 70 ) -> Self | None: 71 """The one player of the game `info` describes, observers aside, who is not `player_id`, or `None` if there is 72 not one, with `ladder_id`, the ladder's id for it, if the game is a ladder's. Its race is the one the game 73 gives, else the one it asked for unless that is Random.""" 74 others = [ 75 entry 76 for entry in info.player_info 77 if entry.player_id != player_id and entry.type != sc2api_pb2.PlayerType.Observer 78 ] 79 if len(others) != 1: 80 return None 81 (entry,) = others 82 played = (Race.TERRAN, Race.ZERG, Race.PROTOSS) 83 requested = Race(entry.race_requested) 84 actual = Race(entry.race_actual) 85 race = actual if actual in played else requested if requested in played else None 86 return cls( 87 player_id=entry.player_id, 88 requested_race=requested, 89 name=entry.player_name or None, 90 race=race, 91 ladder_id=ladder_id, 92 game_data=game_data, 93 ) 94 95 @property 96 def id(self) -> int: 97 """Its id in the game, which its units read as their `owner_id`.""" 98 return self._id 99 100 @property 101 def requested_race(self) -> Race: 102 """The race it asked for, `RANDOM` included.""" 103 return self._requested_race 104 105 @property 106 def race(self) -> Race | None: 107 """The race it plays, never `RANDOM`, and `None` until it is known. 108 109 A game of two players gives it from the start (tool `sweep_requests`), and so does any enemy that did not ask 110 for Random. Against a computer that did, it is known once the first enemy unit is seen, as that unit's race: 111 `EnemyRaceKnownEvent` comes on the turn it is known. A unit of this player's that a neural parasite holds is 112 the enemy's meanwhile, so if it is the first seen, the race reads as this player's own. 113 """ 114 return self._race 115 116 @property 117 def name(self) -> str | None: 118 """Its name as the game gives it, and `None` where the game gives none, as in every game seen so far, though it 119 joined with one (tool `sweep_requests`).""" 120 return self._name 121 122 @property 123 def ladder_id(self) -> str | None: 124 """The ladder's id for it, the same in every game the ladder plays against it, as the ladder passes it in 125 `--OpponentId`; `None` outside a ladder game.""" 126 return self._ladder_id 127 128 def _learn_race(self, race: Race) -> None: 129 """Take `race` as the race it plays.""" 130 self._race = race 131 132 @property 133 def start_location(self) -> StartLocation: 134 """Where it started: on a map of two start locations the one but this player's, and on a map of more the one 135 `assume_start_location` last named. 136 137 Raises `NotReportedError` on a map with more than two start locations until the bot names one with 138 `assume_start_location`, since the game does not say which the enemy took, and NachOS does not scout for it. 139 Raises `NoStartLocationError` where no expansion stands at its start, as on a mini-game's map, or where the map 140 has no start location but this player's. 141 """ 142 if self._start_location is not None: 143 return self._start_location 144 if len(self._start_locations) > 1: 145 raise NotReportedError( 146 f"the map has {len(self._start_locations)} start locations but this player's, and the game does not " 147 "say which the enemy took: assume_start_location names one" 148 ) 149 if not self._start_locations: 150 raise NoStartLocationError("the map has no start location but this player's") 151 raise NoStartLocationError("no expansion stands where the enemy started") 152 153 def assume_start_location(self, start_location: StartLocation) -> None: 154 """Assume the enemy started at `start_location` from now on, in place of any start assumed before, so that 155 `start_location` reads it on a map with more than two start locations. Raises `ValueError` for one that is not 156 among the map's start locations but this player's.""" 157 if start_location not in self._start_locations: 158 raise ValueError(f"{start_location.center} is not among the map's start locations but this player's") 159 self._start_location = start_location 160 161 def _learn_start_locations(self, start_locations: tuple[StartLocation | None, ...]) -> None: 162 """Take `start_locations`, one for each start location on the map but this player's, as where it may have 163 started: `None` for one no expansion stands at. Where there is one, it started there.""" 164 self._start_locations = start_locations 165 if len(start_locations) == 1 and (start_location := start_locations[0]) is not None: 166 self.assume_start_location(start_location) 167 168 @property 169 def upgrades(self) -> frozenset[UpgradeId]: 170 """Every upgrade the enemy is known or assumed to have. 171 172 The game never reports an enemy upgrade outright. NachOS adds here the attack, armor and shield levels each 173 visible enemy unit reports, as levels of its type's own upgrade lines: a marine at attack level 2 shows the 174 first two Terran Infantry Weapons. Anything else, such as Burrow off a burrowed zergling or Metabolic Boost off 175 how fast zerglings move, the bot or an extension adds with `assume_upgrades`. 176 177 Every enemy unit, in sight or not, counts what is held here. It never holds an upgrade without those the game's 178 tables say it needs researched first, as level 2 of a line needs level 1. 179 """ 180 return self._upgrades 181 182 def assume_upgrades(self, *upgrades: UpgradeId) -> None: 183 """Assume the enemy has `upgrades` from now on, and every upgrade each needs researched first: level 2 of a 184 line brings level 1.""" 185 if new := frozenset(upgrades) - self._upgrades: 186 self._upgrades = self._upgrades.union(*map(self._with_the_upgrades_it_needs, new)) 187 188 def forget_upgrades(self, *upgrades: UpgradeId) -> None: 189 """Assume the enemy no longer has `upgrades`, nor any upgrade that needs one of them researched first: level 1 190 of a line takes levels 2 and 3 with it. 191 192 A level an enemy unit reports puts one back, and so may an extension that adds what it reads. 193 """ 194 forgotten = frozenset(upgrades) 195 self._upgrades = frozenset( 196 held for held in self._upgrades if self._with_the_upgrades_it_needs(held).isdisjoint(forgotten) 197 ) 198 199 def _with_the_upgrades_it_needs(self, upgrade: UpgradeId) -> frozenset[UpgradeId]: 200 """`upgrade`, every upgrade it needs researched first, and those they need in turn.""" 201 if (row := self._game_data.upgrades.get(upgrade)) is None: 202 return frozenset({upgrade}) 203 return frozenset({upgrade}).union(*map(self._with_the_upgrades_it_needs, row.tech_requirements.upgrades))
The other player, and what NachOS has learned or been told about it. game_data says which upgrades each upgrade
needs researched first.
37 def __init__( 38 self, 39 *, 40 player_id: int, 41 requested_race: Race, 42 name: str | None, 43 race: Race | None, 44 ladder_id: str | None, 45 game_data: GameData, 46 ) -> None: 47 self._game_data = game_data 48 self._id = player_id 49 self._requested_race = requested_race 50 self._name = name 51 self._race = race 52 self._ladder_id = ladder_id 53 # Replaced whole on every change, since units read it as part of a key many times a step. 54 self._upgrades: frozenset[UpgradeId] = frozenset() 55 # Where it may have started, the map's start locations but this player's: `None` for one no expansion stands at. 56 self._start_locations: tuple[StartLocation | None, ...] = () 57 # Where it started: the other start on a map of two, else the one the bot named, if it has. 58 self._start_location: StartLocation | None = None
95 @property 96 def id(self) -> int: 97 """Its id in the game, which its units read as their `owner_id`.""" 98 return self._id
Its id in the game, which its units read as their owner_id.
100 @property 101 def requested_race(self) -> Race: 102 """The race it asked for, `RANDOM` included.""" 103 return self._requested_race
The race it asked for, RANDOM included.
105 @property 106 def race(self) -> Race | None: 107 """The race it plays, never `RANDOM`, and `None` until it is known. 108 109 A game of two players gives it from the start (tool `sweep_requests`), and so does any enemy that did not ask 110 for Random. Against a computer that did, it is known once the first enemy unit is seen, as that unit's race: 111 `EnemyRaceKnownEvent` comes on the turn it is known. A unit of this player's that a neural parasite holds is 112 the enemy's meanwhile, so if it is the first seen, the race reads as this player's own. 113 """ 114 return self._race
The race it plays, never RANDOM, and None until it is known.
A game of two players gives it from the start (tool sweep_requests), and so does any enemy that did not ask
for Random. Against a computer that did, it is known once the first enemy unit is seen, as that unit's race:
EnemyRaceKnownEvent comes on the turn it is known. A unit of this player's that a neural parasite holds is
the enemy's meanwhile, so if it is the first seen, the race reads as this player's own.
116 @property 117 def name(self) -> str | None: 118 """Its name as the game gives it, and `None` where the game gives none, as in every game seen so far, though it 119 joined with one (tool `sweep_requests`).""" 120 return self._name
Its name as the game gives it, and None where the game gives none, as in every game seen so far, though it
joined with one (tool sweep_requests).
122 @property 123 def ladder_id(self) -> str | None: 124 """The ladder's id for it, the same in every game the ladder plays against it, as the ladder passes it in 125 `--OpponentId`; `None` outside a ladder game.""" 126 return self._ladder_id
The ladder's id for it, the same in every game the ladder plays against it, as the ladder passes it in
--OpponentId; None outside a ladder game.
132 @property 133 def start_location(self) -> StartLocation: 134 """Where it started: on a map of two start locations the one but this player's, and on a map of more the one 135 `assume_start_location` last named. 136 137 Raises `NotReportedError` on a map with more than two start locations until the bot names one with 138 `assume_start_location`, since the game does not say which the enemy took, and NachOS does not scout for it. 139 Raises `NoStartLocationError` where no expansion stands at its start, as on a mini-game's map, or where the map 140 has no start location but this player's. 141 """ 142 if self._start_location is not None: 143 return self._start_location 144 if len(self._start_locations) > 1: 145 raise NotReportedError( 146 f"the map has {len(self._start_locations)} start locations but this player's, and the game does not " 147 "say which the enemy took: assume_start_location names one" 148 ) 149 if not self._start_locations: 150 raise NoStartLocationError("the map has no start location but this player's") 151 raise NoStartLocationError("no expansion stands where the enemy started")
Where it started: on a map of two start locations the one but this player's, and on a map of more the one
assume_start_location last named.
Raises NotReportedError on a map with more than two start locations until the bot names one with
assume_start_location, since the game does not say which the enemy took, and NachOS does not scout for it.
Raises NoStartLocationError where no expansion stands at its start, as on a mini-game's map, or where the map
has no start location but this player's.
153 def assume_start_location(self, start_location: StartLocation) -> None: 154 """Assume the enemy started at `start_location` from now on, in place of any start assumed before, so that 155 `start_location` reads it on a map with more than two start locations. Raises `ValueError` for one that is not 156 among the map's start locations but this player's.""" 157 if start_location not in self._start_locations: 158 raise ValueError(f"{start_location.center} is not among the map's start locations but this player's") 159 self._start_location = start_location
Assume the enemy started at start_location from now on, in place of any start assumed before, so that
start_location reads it on a map with more than two start locations. Raises ValueError for one that is not
among the map's start locations but this player's.
168 @property 169 def upgrades(self) -> frozenset[UpgradeId]: 170 """Every upgrade the enemy is known or assumed to have. 171 172 The game never reports an enemy upgrade outright. NachOS adds here the attack, armor and shield levels each 173 visible enemy unit reports, as levels of its type's own upgrade lines: a marine at attack level 2 shows the 174 first two Terran Infantry Weapons. Anything else, such as Burrow off a burrowed zergling or Metabolic Boost off 175 how fast zerglings move, the bot or an extension adds with `assume_upgrades`. 176 177 Every enemy unit, in sight or not, counts what is held here. It never holds an upgrade without those the game's 178 tables say it needs researched first, as level 2 of a line needs level 1. 179 """ 180 return self._upgrades
Every upgrade the enemy is known or assumed to have.
The game never reports an enemy upgrade outright. NachOS adds here the attack, armor and shield levels each
visible enemy unit reports, as levels of its type's own upgrade lines: a marine at attack level 2 shows the
first two Terran Infantry Weapons. Anything else, such as Burrow off a burrowed zergling or Metabolic Boost off
how fast zerglings move, the bot or an extension adds with assume_upgrades.
Every enemy unit, in sight or not, counts what is held here. It never holds an upgrade without those the game's tables say it needs researched first, as level 2 of a line needs level 1.
182 def assume_upgrades(self, *upgrades: UpgradeId) -> None: 183 """Assume the enemy has `upgrades` from now on, and every upgrade each needs researched first: level 2 of a 184 line brings level 1.""" 185 if new := frozenset(upgrades) - self._upgrades: 186 self._upgrades = self._upgrades.union(*map(self._with_the_upgrades_it_needs, new))
Assume the enemy has upgrades from now on, and every upgrade each needs researched first: level 2 of a
line brings level 1.
188 def forget_upgrades(self, *upgrades: UpgradeId) -> None: 189 """Assume the enemy no longer has `upgrades`, nor any upgrade that needs one of them researched first: level 1 190 of a line takes levels 2 and 3 with it. 191 192 A level an enemy unit reports puts one back, and so may an extension that adds what it reads. 193 """ 194 forgotten = frozenset(upgrades) 195 self._upgrades = frozenset( 196 held for held in self._upgrades if self._with_the_upgrades_it_needs(held).isdisjoint(forgotten) 197 )
Assume the enemy no longer has upgrades, nor any upgrade that needs one of them researched first: level 1
of a line takes levels 2 and 3 with it.
A level an enemy unit reports puts one back, and so may an extension that adds what it reads.
7class NoStartLocationError(NachOSError, LookupError): 8 """No expansion stands where the player started, as on a mini-game's map with no townhall."""
No expansion stands where the player started, as on a mini-game's map with no townhall.
97@dataclass(frozen=True, slots=True) 98class Participant: 99 """A slot for a client to join. Its race and name are set at the join."""
A slot for a client to join. Its race and name are set at the join.
18@final 19@dataclass(frozen=True, slots=True) 20class Player: 21 """This player: its id in the game, its race and the one it asked for, its name, and where it started.""" 22 23 id: int 24 """Its id in the game, which its units read as their `owner_id`.""" 25 race: Race 26 """The race it plays, which the game gives from the start, where it asked for Random too. A computer's, which the 27 game never gives, as when a replay is played back as one, is the race it asked for, `RANDOM` included (in game).""" 28 requested_race: Race 29 """The race it asked for, `RANDOM` included.""" 30 name: str | None 31 """Its name as the game gives it, and `None` where the game gives none, as in every game seen so far, though it 32 joined with one (tool `sweep_requests`).""" 33 _start_location: StartLocation | None = field(default=None, repr=False, compare=False) 34 35 @property 36 def start_location(self) -> StartLocation: 37 """Where it started: the expansion its first townhall stood on. Raises `NoStartLocationError` where it started 38 on none, as on a mini-game's map with no townhall, where `GameMap.start_location` is the map's center.""" 39 if self._start_location is None: 40 raise NoStartLocationError("no expansion stands where this player started") 41 return self._start_location 42 43 @classmethod 44 def _from_game( 45 cls, info: sc2api_pb2.ResponseGameInfo, player_id: int, *, start_location: StartLocation | None 46 ) -> Self: 47 """The player `player_id` of the game `info` describes, which started at `start_location`, or on no expansion 48 if `None`. Raises `ValueError` if `info` lists no such player.""" 49 entry = next((entry for entry in info.player_info if entry.player_id == player_id), None) 50 if entry is None: 51 raise ValueError(f"the game lists no player {player_id}, the one this client joined as") 52 requested_race = Race(entry.race_requested) 53 actual_race = Race(entry.race_actual) 54 return cls( 55 id=player_id, 56 race=requested_race if actual_race is Race.NONE else actual_race, 57 requested_race=requested_race, 58 name=entry.player_name or None, 59 _start_location=start_location, 60 )
This player: its id in the game, its race and the one it asked for, its name, and where it started.
The race it plays, which the game gives from the start, where it asked for Random too. A computer's, which the
game never gives, as when a replay is played back as one, is the race it asked for, RANDOM included (in game).
Its name as the game gives it, and None where the game gives none, as in every game seen so far, though it
joined with one (tool sweep_requests).
35 @property 36 def start_location(self) -> StartLocation: 37 """Where it started: the expansion its first townhall stood on. Raises `NoStartLocationError` where it started 38 on none, as on a mini-game's map with no townhall, where `GameMap.start_location` is the map's center.""" 39 if self._start_location is None: 40 raise NoStartLocationError("no expansion stands where this player started") 41 return self._start_location
Where it started: the expansion its first townhall stood on. Raises NoStartLocationError where it started
on none, as on a mini-game's map with no townhall, where GameMap.start_location is the map's center.
12class Race(ReadableIntEnum): 13 """A player's race. `RANDOM` is what a player picks, not what they are given.""" 14 15 NONE = common_pb2.Race.NoRace 16 TERRAN = common_pb2.Race.Terran 17 ZERG = common_pb2.Race.Zerg 18 PROTOSS = common_pb2.Race.Protoss 19 RANDOM = common_pb2.Race.Random 20 21 @property 22 def worker_type(self) -> UnitTypeId: 23 """The race's worker: an SCV, a drone or a probe. Raises `ValueError` for `NONE` and `RANDOM`.""" 24 return _unit_types_of(self).worker 25 26 @property 27 def starting_townhall_type(self) -> UnitTypeId: 28 """The townhall the race starts with: a command center, a hatchery or a nexus. Raises `ValueError` for `NONE` 29 and `RANDOM`.""" 30 return _unit_types_of(self).starting_townhall 31 32 @property 33 def supply_type(self) -> UnitTypeId: 34 """What the race builds or makes for supply: a supply depot, an overlord or a pylon. Raises `ValueError` for 35 `NONE` and `RANDOM`.""" 36 return _unit_types_of(self).supply
A player's race. RANDOM is what a player picks, not what they are given.
62class Result(ReadableIntEnum): 63 """How a match ended, from one player's point of view.""" 64 65 VICTORY = sc2api_pb2.Result.Victory 66 DEFEAT = sc2api_pb2.Result.Defeat 67 TIE = sc2api_pb2.Result.Tie 68 UNDECIDED = sc2api_pb2.Result.Undecided
How a match ended, from one player's point of view.