sc2nachos.debug
Drawing on the game's screen, cheats and debug commands.
1"""Drawing on the game's screen, cheats and debug commands.""" 2 3from sc2nachos.debug._cheat import Cheat 4from sc2nachos.debug._color import Color 5from sc2nachos.debug._debug_commands import DebugCommands 6from sc2nachos.debug._drawing import Drawing 7from sc2nachos.debug._marker import Marker 8from sc2nachos.debug._shapes import ( 9 DebugBox, 10 DebugGroup, 11 DebugLine, 12 DebugMark, 13 DebugShape, 14 DebugSphere, 15 DebugText, 16) 17 18__all__ = [ 19 "Cheat", 20 "Color", 21 "DebugBox", 22 "DebugCommands", 23 "DebugGroup", 24 "DebugLine", 25 "DebugMark", 26 "DebugShape", 27 "DebugSphere", 28 "DebugText", 29 "Drawing", 30 "Marker", 31]
9class Cheat(ReadableIntEnum): 10 """A debug cheat that is on or off for the whole game, as `api.debug.turn_on` and `turn_off` take it. 11 `docs/reference/game-behavior/cheats.md` says what several do to what the game reports.""" 12 13 SHOW_MAP = debug_pb2.show_map 14 """Shows the whole map, the fog lifted.""" 15 CONTROL_ENEMY = debug_pb2.control_enemy 16 """Lets this player order the enemy's units (stated).""" 17 FOOD = debug_pb2.food 18 """Lifts the supply cap.""" 19 FREE = debug_pb2.free 20 """Makes everything cost nothing, a spell's energy included.""" 21 GOD = debug_pb2.god 22 """Keeps this player's units from taking damage, and multiplies every weapon's damage in the game's tables by 10.""" 23 COOLDOWN = debug_pb2.cooldown 24 """Takes the cooldowns off abilities (stated).""" 25 TECH_TREE = debug_pb2.tech_tree 26 """Waives every requirement, and grants 42 upgrades.""" 27 FAST_BUILD = debug_pb2.fast_build 28 """Makes building, training and research take seconds."""
A debug cheat that is on or off for the whole game, as api.debug.turn_on and turn_off take it.
docs/reference/game-behavior/cheats.md says what several do to what the game reports.
Keeps this player's units from taking damage, and multiplies every weapon's damage in the game's tables by 10.
13class Color(Enum): 14 """A standard color, by its red, green and blue, each from 0 to 255. Any other is drawn by giving a tuple of the 15 three.""" 16 17 WHITE = (255, 255, 255) 18 BLACK = (0, 0, 0) 19 GRAY = (128, 128, 128) 20 RED = (255, 0, 0) 21 GREEN = (0, 255, 0) 22 BLUE = (0, 0, 255) 23 YELLOW = (255, 255, 0) 24 CYAN = (0, 255, 255) 25 MAGENTA = (255, 0, 255) 26 ORANGE = (255, 165, 0) 27 PURPLE = (128, 0, 128)
A standard color, by its red, green and blue, each from 0 to 255. Any other is drawn by giving a tuple of the three.
51@final 52@dataclass(frozen=True, slots=True) 53class DebugBox: 54 """A box `width` across, `depth` deep and `height` high, centered on where it is placed and standing on it.""" 55 56 width: float 57 depth: float 58 height: float = 1.0 59 color: Color | tuple[int, int, int] | None = None 60 offset: tuple[float, float, float] = (0.0, 0.0, 0.0) 61 # The red, green and blue of `color`, if it is given. 62 _rgb: _Rgb | None = field(init=False, repr=False, compare=False) 63 64 def __post_init__(self) -> None: 65 """Raises `ValueError` for a side that is not a finite number above 0, and as every shape does.""" 66 for side in (self.width, self.depth, self.height): 67 _check_length(side, "a box's side") 68 _keep_color_and_offset(self) 69 70 def _draw(self, draw: debug_pb2.DebugDraw, at: _Vector, rgb: _Rgb, size: int, end: _Vector | None) -> None: 71 """Add the box to `draw` at `at`, in `rgb`: its own color, or else what it takes from where it is drawn.""" 72 x, y, z = at 73 low = common_pb2.Point(x=x - self.width / 2, y=y - self.depth / 2, z=z) 74 high = common_pb2.Point(x=x + self.width / 2, y=y + self.depth / 2, z=z + self.height) 75 draw.boxes.add(color=_proto_color(rgb), min=low, max=high)
33@final 34class DebugCommands: 35 """Drawing on the game's screen, cheats and debug commands for one game, all sent after the turn's orders in one 36 debug request. The game takes them from a client that joined the game as from the one that created it (in game). 37 38 Each draw method returns the `Drawing`, which is shown for the `shown_for` it is given from the turn it is made in, 39 at least that turn, or until removed if `shown_for` is `None`. A drawing at a unit follows the unit, read where it 40 stands at each refresh, at where it was last seen while out of sight, and ends once the unit is dead. 41 42 The drawing is refreshed at most once every `refresh_interval`, and the screen keeps the last drawing sent 43 meanwhile, so one made between two refreshes waits for the next, and one that ends between them still shows until 44 then. A refresh whose drawing is what was last sent sends nothing; a turn with a cheat or a command goes out at 45 once, with the drawing as it stands then. 46 47 A debug request the game refuses, as a ladder's own proxy may, raises `ProtocolError` out of `api.play`. 48 """ 49 50 __slots__ = ( 51 "_active_cheats", 52 "_client", 53 "_commands", 54 "_default_color", 55 "_default_rgb", 56 "_default_text_size", 57 "_drawings", 58 "_game_map", 59 "_last_refresh", 60 "_opponent_id", 61 "_refresh_interval", 62 "_shown", 63 "_step", 64 "_toggled_cheats", 65 ) 66 67 def __init__(self, client: Client, game_map: GameMap, *, opponent_id: int | None, step: int) -> None: 68 """Debug commands for the game `client` plays on `game_map`, against the player `opponent_id`, if there is 69 one, from `step`.""" 70 self._client = client 71 self._game_map = game_map 72 self._opponent_id = opponent_id 73 self._step = step 74 self._refresh_interval = GameTime(steps=1) 75 self._default_color: Color | tuple[int, int, int] = Color.WHITE 76 self._default_rgb = _rgb_of(Color.WHITE) 77 self._default_text_size = 8 78 self._drawings: list[Drawing] = [] 79 # What the screen shows of ours as last sent, if anything, and the step of the last refresh, which sent the 80 # drawing or found it unchanged. 81 self._shown: debug_pb2.DebugDraw | None = None 82 self._last_refresh: int | None = None 83 self._commands: list[debug_pb2.DebugCommand] = [] 84 self._active_cheats: set[Cheat] = set() 85 # The cheats the turn switched, each sent once. 86 self._toggled_cheats: set[Cheat] = set() 87 88 @property 89 def refresh_interval(self) -> GameTime: 90 """The least time between two refreshes of the drawing, one step unless set. Set to anything but a `GameTime` it 91 raises `TypeError`, and to one that is not a whole number of steps, at least 1, `ValueError`.""" 92 return self._refresh_interval 93 94 @refresh_interval.setter 95 def refresh_interval(self, refresh_interval: GameTime) -> None: 96 check_game_time(refresh_interval, "refresh_interval") 97 if not refresh_interval.is_integer() or refresh_interval.steps < 1: 98 raise ValueError( 99 f"drawings are refreshed every whole number of steps, at least 1, not {refresh_interval!r}" 100 ) 101 self._refresh_interval = refresh_interval 102 103 @property 104 def default_color(self) -> Color | tuple[int, int, int]: 105 """The color of a shape drawn with no color given, `Color.WHITE` unless set. Set to what is not a `Color` or 106 red, green and blue, each a whole number from 0 to 255, it raises `ValueError`.""" 107 return self._default_color 108 109 @default_color.setter 110 def default_color(self, color: Color | tuple[int, int, int]) -> None: 111 self._default_rgb = _rgb_of(color) 112 self._default_color = color if isinstance(color, Color) else self._default_rgb 113 114 @property 115 def default_text_size(self) -> int: 116 """How many pixels high text drawn with no size given is, 8 unless set. Set to anything but a whole number, at 117 least 1, it raises `ValueError`.""" 118 return self._default_text_size 119 120 @default_text_size.setter 121 def default_text_size(self, size: int) -> None: 122 if not is_whole_number(size) or size < 1: 123 raise ValueError(f"text is a whole number of pixels high, at least 1, not {size!r}") 124 self._default_text_size = size 125 126 # Drawing. 127 128 def draw( 129 self, 130 at: PointLike | Unit[Any], 131 *shapes: DebugShape, 132 color: Color | tuple[int, int, int] | None = None, 133 shown_for: GameTime | None = GameTime(steps=1), 134 ) -> Drawing: 135 """Draw `shapes` at `at`, each offset from it as it says, as one drawing. 136 137 A point of two coordinates is drawn on the ground, as `api.map.height_at` gives it, which raises `IndexError` 138 outside the playable area, and one of three at its own height; so is a line's end. A unit is drawn where it 139 stands. A shape with no color of its own, nor its group's, is drawn in `color`, or `default_color` if `None`. 140 Raises `ValueError` for no shapes, for a color that is not a `Color` or red, green and blue, each from 0 to 141 255, and for a `shown_for` that is not a whole number of steps, at least 1, and `TypeError` for one that is not 142 a `GameTime`. 143 """ 144 if not shapes: 145 raise ValueError("draw at least one shape") 146 rgb = self._default_rgb if color is None else _rgb_of(color) 147 parts = tuple(self._placed(shapes, (0.0, 0.0, 0.0), rgb)) 148 return self._add(Drawing(self._anchor(at), parts, until=self._until(shown_for))) 149 150 def draw_text_on_screen( 151 self, 152 text: str, 153 *, 154 at: tuple[float, float], 155 color: Color | tuple[int, int, int] | None = None, 156 size: int | None = None, 157 shown_for: GameTime | None = GameTime(steps=1), 158 ) -> Drawing: 159 """Write `text` on the screen at `at`, from 0 to 1 across and down whatever the window's size, `size` pixels 160 high, or `default_text_size` if `None`. Raises `ValueError` for anything but two coordinates from 0 to 1, and 161 as `draw` and `DebugText` do.""" 162 if len(at) != 2 or not (0 <= at[0] <= 1 and 0 <= at[1] <= 1): 163 raise ValueError(f"a point on the screen is two coordinates, each from 0 to 1, not {at!r}") 164 _check_text(text, size) 165 rgb = self._default_rgb if color is None else _rgb_of(color) 166 part = _PlacedShape(_ScreenText(text, at), (0.0, 0.0, 0.0), rgb, size or self._default_text_size) 167 return self._add(Drawing((0.0, 0.0, 0.0), (part,), until=self._until(shown_for))) 168 169 def _placed(self, shapes: Sequence[DebugShape], offset: _Vector, rgb: _Rgb) -> Iterator[_PlacedShape]: 170 """`shapes` as drawn `offset` from the drawing's place, those of no color of their own in `rgb`, each group's 171 shapes in turn.""" 172 for shape in shapes: 173 x, y, z = offset 174 dx, dy, dz = shape.offset 175 at = (x + dx, y + dy, z + dz) 176 own = rgb if shape._rgb is None else shape._rgb 177 match shape: 178 case DebugGroup(): 179 yield from self._placed(shape.shapes, at, own) 180 case DebugText(): 181 yield _PlacedShape(shape, at, own, shape.size or self._default_text_size) 182 case DebugLine(): 183 yield _PlacedShape(shape, at, own, self._default_text_size, self._anchor(shape.to)) 184 case _: 185 yield _PlacedShape(shape, at, own, self._default_text_size) 186 187 def _anchor(self, at: PointLike | Unit[Any]) -> _Anchor: 188 """Where to draw at `at`: a unit itself, or a point fixed now, on the ground unless it has a height.""" 189 if isinstance(at, Unit): 190 return at 191 if len(at) == 3: 192 return (float(at[0]), float(at[1]), float(at[2])) 193 return (float(at[0]), float(at[1]), self._game_map.height_at(at)) 194 195 def _until(self, shown_for: GameTime | None) -> int | None: 196 """The step a drawing made now that is shown for `shown_for` ends at, or `None` if it lasts until removed.""" 197 if shown_for is None: 198 return None 199 check_game_time(shown_for, "shown_for") 200 if not shown_for.is_integer() or shown_for.steps < 1: 201 raise ValueError( 202 f"a drawing is shown for a whole number of steps, at least 1, or until removed, not {shown_for!r}" 203 ) 204 return self._step + int(shown_for.steps) 205 206 def _add(self, drawing: Drawing) -> Drawing: 207 self._drawings.append(drawing) 208 return drawing 209 210 # Cheats. 211 212 @property 213 def cheats(self) -> frozenset[Cheat]: 214 """The cheats this player has turned on in this game, this turn's included. Each is on for the whole game, and 215 in a game of two the other player can switch it too, which this does not see (in game).""" 216 return frozenset(self._active_cheats) 217 218 def turn_on(self, cheat: Cheat) -> None: 219 """Turn `cheat` on for the rest of the game. One already on stays on, and nothing is sent.""" 220 if cheat not in self._active_cheats: 221 self._active_cheats.add(cheat) 222 self._toggled_cheats ^= {cheat} 223 224 def turn_off(self, cheat: Cheat) -> None: 225 """Turn `cheat` off. One already off stays off, and nothing is sent.""" 226 if cheat in self._active_cheats: 227 self._active_cheats.discard(cheat) 228 self._toggled_cheats ^= {cheat} 229 230 def give_minerals(self) -> None: 231 """Give this player 5000 minerals (in game).""" 232 self._commands.append(debug_pb2.DebugCommand(game_state=debug_pb2.minerals)) 233 234 def give_resources(self) -> None: 235 """Give this player 5000 minerals and 5000 vespene (in game).""" 236 self._commands.append(debug_pb2.DebugCommand(game_state=debug_pb2.all_resources)) 237 238 def give_upgrades(self) -> None: 239 """Grant this player the next level of every upgrade of every race: the researches and the first levels the 240 first time, the second levels the next, and campaign upgrades with them (in game).""" 241 self._commands.append(debug_pb2.DebugCommand(game_state=debug_pb2.upgrade)) 242 243 # Commands. 244 245 def create_units( 246 self, unit_type: UnitTypeId, *, at: PointLike, count: int = 1, owner: Alliance = Alliance.OWN 247 ) -> None: 248 """Create `count` units of `unit_type` at `at` for `owner`: this player, the one player it plays against, or 249 the map, whose units read owner 16. The game can make them a few steps late, beside `at`, or not at all, as 250 for a structure on ground it cannot stand on (in game). 251 252 Raises `ValueError` for a count under 1, for `Alliance.ALLY`, and for `Alliance.ENEMY` in a game without one 253 other player. 254 """ 255 if not is_whole_number(count) or count < 1: 256 raise ValueError(f"units are created a whole number at a time, at least 1, not {count!r}") 257 create = debug_pb2.DebugCreateUnit( 258 unit_type=unit_type, 259 owner=self._player(owner), 260 pos=common_pb2.Point2D(x=at[0], y=at[1]), 261 quantity=count, 262 ) 263 self._commands.append(debug_pb2.DebugCommand(create_unit=create)) 264 265 def kill(self, units: Unit[Any] | Iterable[Unit[Any]]) -> None: 266 """Kill `units`.""" 267 if tags := [unit.tag for unit in _unit_tuple(units)]: 268 self._commands.append(debug_pb2.DebugCommand(kill_unit=debug_pb2.DebugKillUnit(tag=tags))) 269 270 def set_vitals( 271 self, 272 units: Unit[Any] | Iterable[Unit[Any]], 273 *, 274 life: float | None = None, 275 energy: float | None = None, 276 shields: float | None = None, 277 ) -> None: 278 """Set the life, energy or shields given of each of `units`. 279 280 Raises `ValueError` if no vital is given, and for a value that is not a finite number above 0: set to 0, a vital 281 goes to the most the unit can have instead (in game). `kill` takes a unit's life. 282 """ 283 given = {_VITALS.Life: life, _VITALS.Energy: energy, _VITALS.Shields: shields} 284 values = {vital: value for vital, value in given.items() if value is not None} 285 if not values: 286 raise ValueError("give the life, the energy or the shields to set") 287 for value in values.values(): 288 if not 0 < value < math.inf: 289 raise ValueError( 290 f"a vital is set to a finite number above 0, not {value!r}: set to 0, the game sets it to its most" 291 ) 292 for unit in _unit_tuple(units): 293 for vital, value in values.items(): 294 set_value = debug_pb2.DebugSetUnitValue(unit_value=vital, value=value, unit_tag=unit.tag) 295 self._commands.append(debug_pb2.DebugCommand(unit_value=set_value)) 296 297 def declare_victory(self) -> None: 298 """End the game in this player's victory, by the next step (in game).""" 299 end = debug_pb2.DebugEndGame(end_result=debug_pb2.DebugEndGame.DeclareVictory) 300 self._commands.append(debug_pb2.DebugCommand(end_game=end)) 301 302 def surrender(self) -> None: 303 """End the game in this player's defeat, by the next step, as a game ends: unlike `api.leave_game`, the result 304 is reported (in game).""" 305 end = debug_pb2.DebugEndGame(end_result=debug_pb2.DebugEndGame.Surrender) 306 self._commands.append(debug_pb2.DebugCommand(end_game=end)) 307 308 def _player(self, owner: Alliance) -> int: 309 """The id of the player `owner` names in this game.""" 310 match owner: 311 case Alliance.OWN: 312 if (player := self._client.player_id) is None: 313 raise ValueError("this player has no id until it joins a game") 314 return player 315 case Alliance.ENEMY: 316 if self._opponent_id is None: 317 raise ValueError("this game has no single other player to create units for") 318 return self._opponent_id 319 case Alliance.NEUTRAL: 320 # A unit created for player 0 belongs to the map (in game). 321 return 0 322 case _: 323 raise ValueError(f"units are created for this player, its enemy or the map, not {owner!r}") 324 325 # Sending. 326 327 def _update(self, step: int) -> None: 328 """Take in that the turn's observation was made at `step`.""" 329 self._step = step 330 331 def _send(self) -> None: 332 """Send the turn's cheats and commands, and the drawing if it is due and changed, in one debug request, or 333 nothing if neither is to go out.""" 334 step = self._step 335 self._drawings = [drawing for drawing in self._drawings if drawing._shown_at(step)] 336 commands = [ 337 debug_pb2.DebugCommand(game_state=debug_pb2.DebugGameState.ValueType(cheat)) 338 for cheat in sorted(self._toggled_cheats) 339 ] 340 commands += self._commands 341 self._toggled_cheats, self._commands = set(), [] 342 due = self._last_refresh is None or step - self._last_refresh >= self._refresh_interval.steps 343 if not commands and not due: 344 return 345 draw = _draw_all(self._drawings) 346 shown = draw if draw.ListFields() else None 347 if not commands and shown == self._shown: 348 self._last_refresh = step 349 return 350 # Any debug request replaces what the screen shows, so the drawing goes with the commands. 351 drawing = shown is not None or self._shown is not None 352 if drawing: 353 commands.append(debug_pb2.DebugCommand(draw=draw)) 354 self._client.debug(commands) 355 if drawing: 356 self._shown, self._last_refresh = shown, step
Drawing on the game's screen, cheats and debug commands for one game, all sent after the turn's orders in one debug request. The game takes them from a client that joined the game as from the one that created it (in game).
Each draw method returns the Drawing, which is shown for the shown_for it is given from the turn it is made in,
at least that turn, or until removed if shown_for is None. A drawing at a unit follows the unit, read where it
stands at each refresh, at where it was last seen while out of sight, and ends once the unit is dead.
The drawing is refreshed at most once every refresh_interval, and the screen keeps the last drawing sent
meanwhile, so one made between two refreshes waits for the next, and one that ends between them still shows until
then. A refresh whose drawing is what was last sent sends nothing; a turn with a cheat or a command goes out at
once, with the drawing as it stands then.
A debug request the game refuses, as a ladder's own proxy may, raises ProtocolError out of api.play.
67 def __init__(self, client: Client, game_map: GameMap, *, opponent_id: int | None, step: int) -> None: 68 """Debug commands for the game `client` plays on `game_map`, against the player `opponent_id`, if there is 69 one, from `step`.""" 70 self._client = client 71 self._game_map = game_map 72 self._opponent_id = opponent_id 73 self._step = step 74 self._refresh_interval = GameTime(steps=1) 75 self._default_color: Color | tuple[int, int, int] = Color.WHITE 76 self._default_rgb = _rgb_of(Color.WHITE) 77 self._default_text_size = 8 78 self._drawings: list[Drawing] = [] 79 # What the screen shows of ours as last sent, if anything, and the step of the last refresh, which sent the 80 # drawing or found it unchanged. 81 self._shown: debug_pb2.DebugDraw | None = None 82 self._last_refresh: int | None = None 83 self._commands: list[debug_pb2.DebugCommand] = [] 84 self._active_cheats: set[Cheat] = set() 85 # The cheats the turn switched, each sent once. 86 self._toggled_cheats: set[Cheat] = set()
Debug commands for the game client plays on game_map, against the player opponent_id, if there is
one, from step.
88 @property 89 def refresh_interval(self) -> GameTime: 90 """The least time between two refreshes of the drawing, one step unless set. Set to anything but a `GameTime` it 91 raises `TypeError`, and to one that is not a whole number of steps, at least 1, `ValueError`.""" 92 return self._refresh_interval
The least time between two refreshes of the drawing, one step unless set. Set to anything but a GameTime it
raises TypeError, and to one that is not a whole number of steps, at least 1, ValueError.
103 @property 104 def default_color(self) -> Color | tuple[int, int, int]: 105 """The color of a shape drawn with no color given, `Color.WHITE` unless set. Set to what is not a `Color` or 106 red, green and blue, each a whole number from 0 to 255, it raises `ValueError`.""" 107 return self._default_color
The color of a shape drawn with no color given, Color.WHITE unless set. Set to what is not a Color or
red, green and blue, each a whole number from 0 to 255, it raises ValueError.
114 @property 115 def default_text_size(self) -> int: 116 """How many pixels high text drawn with no size given is, 8 unless set. Set to anything but a whole number, at 117 least 1, it raises `ValueError`.""" 118 return self._default_text_size
How many pixels high text drawn with no size given is, 8 unless set. Set to anything but a whole number, at
least 1, it raises ValueError.
128 def draw( 129 self, 130 at: PointLike | Unit[Any], 131 *shapes: DebugShape, 132 color: Color | tuple[int, int, int] | None = None, 133 shown_for: GameTime | None = GameTime(steps=1), 134 ) -> Drawing: 135 """Draw `shapes` at `at`, each offset from it as it says, as one drawing. 136 137 A point of two coordinates is drawn on the ground, as `api.map.height_at` gives it, which raises `IndexError` 138 outside the playable area, and one of three at its own height; so is a line's end. A unit is drawn where it 139 stands. A shape with no color of its own, nor its group's, is drawn in `color`, or `default_color` if `None`. 140 Raises `ValueError` for no shapes, for a color that is not a `Color` or red, green and blue, each from 0 to 141 255, and for a `shown_for` that is not a whole number of steps, at least 1, and `TypeError` for one that is not 142 a `GameTime`. 143 """ 144 if not shapes: 145 raise ValueError("draw at least one shape") 146 rgb = self._default_rgb if color is None else _rgb_of(color) 147 parts = tuple(self._placed(shapes, (0.0, 0.0, 0.0), rgb)) 148 return self._add(Drawing(self._anchor(at), parts, until=self._until(shown_for)))
Draw shapes at at, each offset from it as it says, as one drawing.
A point of two coordinates is drawn on the ground, as api.map.height_at gives it, which raises IndexError
outside the playable area, and one of three at its own height; so is a line's end. A unit is drawn where it
stands. A shape with no color of its own, nor its group's, is drawn in color, or default_color if None.
Raises ValueError for no shapes, for a color that is not a Color or red, green and blue, each from 0 to
255, and for a shown_for that is not a whole number of steps, at least 1, and TypeError for one that is not
a GameTime.
150 def draw_text_on_screen( 151 self, 152 text: str, 153 *, 154 at: tuple[float, float], 155 color: Color | tuple[int, int, int] | None = None, 156 size: int | None = None, 157 shown_for: GameTime | None = GameTime(steps=1), 158 ) -> Drawing: 159 """Write `text` on the screen at `at`, from 0 to 1 across and down whatever the window's size, `size` pixels 160 high, or `default_text_size` if `None`. Raises `ValueError` for anything but two coordinates from 0 to 1, and 161 as `draw` and `DebugText` do.""" 162 if len(at) != 2 or not (0 <= at[0] <= 1 and 0 <= at[1] <= 1): 163 raise ValueError(f"a point on the screen is two coordinates, each from 0 to 1, not {at!r}") 164 _check_text(text, size) 165 rgb = self._default_rgb if color is None else _rgb_of(color) 166 part = _PlacedShape(_ScreenText(text, at), (0.0, 0.0, 0.0), rgb, size or self._default_text_size) 167 return self._add(Drawing((0.0, 0.0, 0.0), (part,), until=self._until(shown_for)))
Write text on the screen at at, from 0 to 1 across and down whatever the window's size, size pixels
high, or default_text_size if None. Raises ValueError for anything but two coordinates from 0 to 1, and
as draw and DebugText do.
212 @property 213 def cheats(self) -> frozenset[Cheat]: 214 """The cheats this player has turned on in this game, this turn's included. Each is on for the whole game, and 215 in a game of two the other player can switch it too, which this does not see (in game).""" 216 return frozenset(self._active_cheats)
The cheats this player has turned on in this game, this turn's included. Each is on for the whole game, and in a game of two the other player can switch it too, which this does not see (in game).
218 def turn_on(self, cheat: Cheat) -> None: 219 """Turn `cheat` on for the rest of the game. One already on stays on, and nothing is sent.""" 220 if cheat not in self._active_cheats: 221 self._active_cheats.add(cheat) 222 self._toggled_cheats ^= {cheat}
Turn cheat on for the rest of the game. One already on stays on, and nothing is sent.
224 def turn_off(self, cheat: Cheat) -> None: 225 """Turn `cheat` off. One already off stays off, and nothing is sent.""" 226 if cheat in self._active_cheats: 227 self._active_cheats.discard(cheat) 228 self._toggled_cheats ^= {cheat}
Turn cheat off. One already off stays off, and nothing is sent.
230 def give_minerals(self) -> None: 231 """Give this player 5000 minerals (in game).""" 232 self._commands.append(debug_pb2.DebugCommand(game_state=debug_pb2.minerals))
Give this player 5000 minerals (in game).
234 def give_resources(self) -> None: 235 """Give this player 5000 minerals and 5000 vespene (in game).""" 236 self._commands.append(debug_pb2.DebugCommand(game_state=debug_pb2.all_resources))
Give this player 5000 minerals and 5000 vespene (in game).
238 def give_upgrades(self) -> None: 239 """Grant this player the next level of every upgrade of every race: the researches and the first levels the 240 first time, the second levels the next, and campaign upgrades with them (in game).""" 241 self._commands.append(debug_pb2.DebugCommand(game_state=debug_pb2.upgrade))
Grant this player the next level of every upgrade of every race: the researches and the first levels the first time, the second levels the next, and campaign upgrades with them (in game).
245 def create_units( 246 self, unit_type: UnitTypeId, *, at: PointLike, count: int = 1, owner: Alliance = Alliance.OWN 247 ) -> None: 248 """Create `count` units of `unit_type` at `at` for `owner`: this player, the one player it plays against, or 249 the map, whose units read owner 16. The game can make them a few steps late, beside `at`, or not at all, as 250 for a structure on ground it cannot stand on (in game). 251 252 Raises `ValueError` for a count under 1, for `Alliance.ALLY`, and for `Alliance.ENEMY` in a game without one 253 other player. 254 """ 255 if not is_whole_number(count) or count < 1: 256 raise ValueError(f"units are created a whole number at a time, at least 1, not {count!r}") 257 create = debug_pb2.DebugCreateUnit( 258 unit_type=unit_type, 259 owner=self._player(owner), 260 pos=common_pb2.Point2D(x=at[0], y=at[1]), 261 quantity=count, 262 ) 263 self._commands.append(debug_pb2.DebugCommand(create_unit=create))
Create count units of unit_type at at for owner: this player, the one player it plays against, or
the map, whose units read owner 16. The game can make them a few steps late, beside at, or not at all, as
for a structure on ground it cannot stand on (in game).
Raises ValueError for a count under 1, for Alliance.ALLY, and for Alliance.ENEMY in a game without one
other player.
265 def kill(self, units: Unit[Any] | Iterable[Unit[Any]]) -> None: 266 """Kill `units`.""" 267 if tags := [unit.tag for unit in _unit_tuple(units)]: 268 self._commands.append(debug_pb2.DebugCommand(kill_unit=debug_pb2.DebugKillUnit(tag=tags)))
Kill units.
270 def set_vitals( 271 self, 272 units: Unit[Any] | Iterable[Unit[Any]], 273 *, 274 life: float | None = None, 275 energy: float | None = None, 276 shields: float | None = None, 277 ) -> None: 278 """Set the life, energy or shields given of each of `units`. 279 280 Raises `ValueError` if no vital is given, and for a value that is not a finite number above 0: set to 0, a vital 281 goes to the most the unit can have instead (in game). `kill` takes a unit's life. 282 """ 283 given = {_VITALS.Life: life, _VITALS.Energy: energy, _VITALS.Shields: shields} 284 values = {vital: value for vital, value in given.items() if value is not None} 285 if not values: 286 raise ValueError("give the life, the energy or the shields to set") 287 for value in values.values(): 288 if not 0 < value < math.inf: 289 raise ValueError( 290 f"a vital is set to a finite number above 0, not {value!r}: set to 0, the game sets it to its most" 291 ) 292 for unit in _unit_tuple(units): 293 for vital, value in values.items(): 294 set_value = debug_pb2.DebugSetUnitValue(unit_value=vital, value=value, unit_tag=unit.tag) 295 self._commands.append(debug_pb2.DebugCommand(unit_value=set_value))
Set the life, energy or shields given of each of units.
Raises ValueError if no vital is given, and for a value that is not a finite number above 0: set to 0, a vital
goes to the most the unit can have instead (in game). kill takes a unit's life.
297 def declare_victory(self) -> None: 298 """End the game in this player's victory, by the next step (in game).""" 299 end = debug_pb2.DebugEndGame(end_result=debug_pb2.DebugEndGame.DeclareVictory) 300 self._commands.append(debug_pb2.DebugCommand(end_game=end))
End the game in this player's victory, by the next step (in game).
302 def surrender(self) -> None: 303 """End the game in this player's defeat, by the next step, as a game ends: unlike `api.leave_game`, the result 304 is reported (in game).""" 305 end = debug_pb2.DebugEndGame(end_result=debug_pb2.DebugEndGame.Surrender) 306 self._commands.append(debug_pb2.DebugCommand(end_game=end))
End the game in this player's defeat, by the next step, as a game ends: unlike api.leave_game, the result
is reported (in game).
157@final 158class DebugGroup: 159 """Shapes drawn together, each offset from the group, and the group offset from where it is placed. A shape with no 160 color of its own takes the group's. Groups compare equal by what they hold, as every shape does.""" 161 162 __slots__ = ("_color", "_offset", "_rgb", "_shapes") 163 164 def __init__( 165 self, 166 *shapes: DebugShape, 167 color: Color | tuple[int, int, int] | None = None, 168 offset: tuple[float, float, float] = (0.0, 0.0, 0.0), 169 ) -> None: 170 """Raises `ValueError` for no shapes, and as every shape does.""" 171 if not shapes: 172 raise ValueError("a group holds at least one shape") 173 self._color = _kept_color(color) 174 self._rgb = _rgb_if_given(self._color) 175 self._offset = _kept_offset(offset) 176 self._shapes = shapes 177 178 @property 179 def shapes(self) -> tuple[DebugShape, ...]: 180 """The shapes drawn together.""" 181 return self._shapes 182 183 @property 184 def color(self) -> Color | tuple[int, int, int] | None: 185 """The color of each shape with none of its own, or `None` for the drawing's.""" 186 return self._color 187 188 @property 189 def offset(self) -> tuple[float, float, float]: 190 """How far the group is drawn from where it is placed, across, up the map and up.""" 191 return self._offset 192 193 def __eq__(self, other: object) -> bool: 194 if not isinstance(other, DebugGroup): 195 return NotImplemented 196 return (self._shapes, self._color, self._offset) == (other._shapes, other._color, other._offset) 197 198 def __hash__(self) -> int: 199 return hash((self._shapes, self._color, self._offset)) 200 201 def __repr__(self) -> str: 202 return f"DebugGroup({', '.join(map(repr, self._shapes))}, color={self._color!r}, offset={self._offset!r})"
Shapes drawn together, each offset from the group, and the group offset from where it is placed. A shape with no color of its own takes the group's. Groups compare equal by what they hold, as every shape does.
164 def __init__( 165 self, 166 *shapes: DebugShape, 167 color: Color | tuple[int, int, int] | None = None, 168 offset: tuple[float, float, float] = (0.0, 0.0, 0.0), 169 ) -> None: 170 """Raises `ValueError` for no shapes, and as every shape does.""" 171 if not shapes: 172 raise ValueError("a group holds at least one shape") 173 self._color = _kept_color(color) 174 self._rgb = _rgb_if_given(self._color) 175 self._offset = _kept_offset(offset) 176 self._shapes = shapes
Raises ValueError for no shapes, and as every shape does.
178 @property 179 def shapes(self) -> tuple[DebugShape, ...]: 180 """The shapes drawn together.""" 181 return self._shapes
The shapes drawn together.
128@final 129@dataclass(frozen=True, slots=True) 130class DebugLine: 131 """A line from where it is placed to `to`, a point placed as `api.debug.draw` places its own, or a unit, which it 132 follows, offset by `to_offset`.""" 133 134 to: PointLike | Unit[Any] 135 color: Color | tuple[int, int, int] | None = None 136 offset: tuple[float, float, float] = (0.0, 0.0, 0.0) 137 to_offset: tuple[float, float, float] = (0.0, 0.0, 0.0) 138 # The red, green and blue of `color`, if it is given. 139 _rgb: _Rgb | None = field(init=False, repr=False, compare=False) 140 141 def __post_init__(self) -> None: 142 """Raises `ValueError` as every shape does, for `to_offset` too.""" 143 _keep_color_and_offset(self) 144 object.__setattr__(self, "to_offset", _kept_offset(self.to_offset)) 145 146 def _draw(self, draw: debug_pb2.DebugDraw, at: _Vector, rgb: _Rgb, size: int, end: _Vector | None) -> None: 147 """Add the line to `draw` from `at` to `end`, offset by `to_offset`, in `rgb`: its own color, or else what it 148 takes from where it is drawn.""" 149 if end is None: 150 return 151 x, y, z = end 152 dx, dy, dz = self.to_offset 153 reached = common_pb2.Point(x=x + dx, y=y + dy, z=z + dz) 154 draw.lines.add(color=_proto_color(rgb), line=debug_pb2.Line(p0=_point(at), p1=reached))
A line from where it is placed to to, a point placed as api.debug.draw places its own, or a unit, which it
follows, offset by to_offset.
99@final 100@dataclass(frozen=True, slots=True) 101class DebugMark: 102 """A `Marker` around where it is placed, its arms or its corners `radius` from it, level with it.""" 103 104 marker: Marker 105 radius: float = 0.5 106 color: Color | tuple[int, int, int] | None = None 107 offset: tuple[float, float, float] = (0.0, 0.0, 0.0) 108 # The red, green and blue of `color`, if it is given. 109 _rgb: _Rgb | None = field(init=False, repr=False, compare=False) 110 111 def __post_init__(self) -> None: 112 """Raises `TypeError` for a marker that is not a `Marker`, `ValueError` for a radius that is not a finite 113 number above 0, and as every shape does.""" 114 if not isinstance(self.marker, Marker): 115 raise TypeError(f"a mark is drawn as a `Marker`, not {self.marker!r}") 116 _check_length(self.radius, "a radius") 117 _keep_color_and_offset(self) 118 119 def _draw(self, draw: debug_pb2.DebugDraw, at: _Vector, rgb: _Rgb, size: int, end: _Vector | None) -> None: 120 """Add the mark to `draw` at `at`, in `rgb`: its own color, or else what it takes from where it is drawn.""" 121 x, y, z = at 122 color = _proto_color(rgb) 123 for (x0, y0), (x1, y1) in _segments_of_marker(self.marker, self.radius): 124 p0, p1 = common_pb2.Point(x=x + x0, y=y + y0, z=z), common_pb2.Point(x=x + x1, y=y + y1, z=z) 125 draw.lines.add(color=color, line=debug_pb2.Line(p0=p0, p1=p1))
78@final 79@dataclass(frozen=True, slots=True) 80class DebugSphere: 81 """A sphere of `radius` around where it is placed.""" 82 83 radius: float 84 color: Color | tuple[int, int, int] | None = None 85 offset: tuple[float, float, float] = (0.0, 0.0, 0.0) 86 # The red, green and blue of `color`, if it is given. 87 _rgb: _Rgb | None = field(init=False, repr=False, compare=False) 88 89 def __post_init__(self) -> None: 90 """Raises `ValueError` for a radius that is not a finite number above 0, and as every shape does.""" 91 _check_length(self.radius, "a radius") 92 _keep_color_and_offset(self) 93 94 def _draw(self, draw: debug_pb2.DebugDraw, at: _Vector, rgb: _Rgb, size: int, end: _Vector | None) -> None: 95 """Add the sphere to `draw` at `at`, in `rgb`: its own color, or else what it takes from where it is drawn.""" 96 draw.spheres.add(color=_proto_color(rgb), p=_point(at), r=self.radius)
A sphere of radius around where it is placed.
27@final 28@dataclass(frozen=True, slots=True) 29class DebugText: 30 """Text written in the world, `size` pixels high, or `api.debug.default_text_size` high if `None`.""" 31 32 text: str 33 size: int | None = None 34 color: Color | tuple[int, int, int] | None = None 35 offset: tuple[float, float, float] = (0.0, 0.0, 0.0) 36 # The red, green and blue of `color`, if it is given. 37 _rgb: _Rgb | None = field(init=False, repr=False, compare=False) 38 39 def __post_init__(self) -> None: 40 """Raises `TypeError` for a text that is not a `str`, `ValueError` for a size that is not a whole number of 41 pixels, at least 1, and as every shape does.""" 42 _check_text(self.text, self.size) 43 _keep_color_and_offset(self) 44 45 def _draw(self, draw: debug_pb2.DebugDraw, at: _Vector, rgb: _Rgb, size: int, end: _Vector | None) -> None: 46 """Add the text to `draw` at `at`, in `rgb`, `size` pixels high: its own color and size, or else what it takes 47 from where it is drawn.""" 48 draw.text.add(color=_proto_color(rgb), text=self.text, world_pos=_point(at), size=size)
Text written in the world, size pixels high, or api.debug.default_text_size high if None.
36@final 37class Drawing: 38 """A drawing on the game's screen, shown until its `shown_for` has passed, a unit it stands at is dead, or it is 39 removed. `api.debug.draw` and `draw_text_on_screen` return it.""" 40 41 __slots__ = ("_anchor", "_parts", "_removed", "_until") 42 43 def __init__(self, anchor: _Anchor, parts: tuple[_PlacedShape, ...], *, until: int | None) -> None: 44 """A drawing of `parts` at `anchor`, shown while the step is before `until`, or until removed if `None`.""" 45 self._anchor = anchor 46 self._parts = parts 47 self._until = until 48 self._removed = False 49 50 def remove(self) -> None: 51 """Take the drawing off the screen at the next refresh. Removing it again does nothing.""" 52 self._removed = True 53 54 def _shown_at(self, step: int) -> bool: 55 """Whether the drawing is still shown at `step`.""" 56 if self._removed or (self._until is not None and step >= self._until): 57 return False 58 anchors = (self._anchor, *(part.to for part in self._parts)) 59 return not any(isinstance(anchor, Unit) and anchor.is_dead for anchor in anchors) 60 61 def _draw(self, draw: debug_pb2.DebugDraw) -> None: 62 """Add the drawing to `draw`, a unit it follows read where it stands now.""" 63 x, y, z = _where(self._anchor) 64 for part in self._parts: 65 dx, dy, dz = part.offset 66 end = None if part.to is None else _where(part.to) 67 part.shape._draw(draw, (x + dx, y + dy, z + dz), part.color, part.size, end)
A drawing on the game's screen, shown until its shown_for has passed, a unit it stands at is dead, or it is
removed. api.debug.draw and draw_text_on_screen return it.
43 def __init__(self, anchor: _Anchor, parts: tuple[_PlacedShape, ...], *, until: int | None) -> None: 44 """A drawing of `parts` at `anchor`, shown while the step is before `until`, or until removed if `None`.""" 45 self._anchor = anchor 46 self._parts = parts 47 self._until = until 48 self._removed = False
A drawing of parts at anchor, shown while the step is before until, or until removed if None.
7class Marker(Enum): 8 """A mark drawn at a point, of lines around it: a cross of arms reaching out from it, or a regular polygon whose 9 corners lie around it, its bottom side level.""" 10 11 CROSS = "x" 12 """An ×, its two arms on the diagonals.""" 13 PLUS = "+" 14 """A +, its two arms along the axes.""" 15 STAR = "*" 16 """The × and the + together.""" 17 TRIANGLE = "triangle" 18 """A triangle, pointing up the map.""" 19 SQUARE = "square" 20 """A square, its sides along the axes.""" 21 PENTAGON = "pentagon" 22 """A pentagon, pointing up the map.""" 23 HEXAGON = "hexagon" 24 """A hexagon, flat at the top and the bottom."""
A mark drawn at a point, of lines around it: a cross of arms reaching out from it, or a regular polygon whose corners lie around it, its bottom side level.