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]
class Cheat(sc2nachos._shared.readable_int_enum.ReadableIntEnum):
 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.

SHOW_MAP = <Cheat.SHOW_MAP: 1>

Shows the whole map, the fog lifted.

CONTROL_ENEMY = <Cheat.CONTROL_ENEMY: 2>

Lets this player order the enemy's units (stated).

FOOD = <Cheat.FOOD: 3>

Lifts the supply cap.

FREE = <Cheat.FREE: 4>

Makes everything cost nothing, a spell's energy included.

GOD = <Cheat.GOD: 6>

Keeps this player's units from taking damage, and multiplies every weapon's damage in the game's tables by 10.

COOLDOWN = <Cheat.COOLDOWN: 9>

Takes the cooldowns off abilities (stated).

TECH_TREE = <Cheat.TECH_TREE: 10>

Waives every requirement, and grants 42 upgrades.

FAST_BUILD = <Cheat.FAST_BUILD: 12>

Makes building, training and research take seconds.

class Color(enum.Enum):
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.

WHITE = <Color.WHITE: (255, 255, 255)>
BLACK = <Color.BLACK: (0, 0, 0)>
GRAY = <Color.GRAY: (128, 128, 128)>
RED = <Color.RED: (255, 0, 0)>
GREEN = <Color.GREEN: (0, 255, 0)>
BLUE = <Color.BLUE: (0, 0, 255)>
YELLOW = <Color.YELLOW: (255, 255, 0)>
CYAN = <Color.CYAN: (0, 255, 255)>
MAGENTA = <Color.MAGENTA: (255, 0, 255)>
ORANGE = <Color.ORANGE: (255, 165, 0)>
PURPLE = <Color.PURPLE: (128, 0, 128)>
@final
@dataclass(frozen=True, slots=True)
class DebugBox:
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)

A box width across, depth deep and height high, centered on where it is placed and standing on it.

DebugBox( width: float, depth: float, height: float = 1.0, color: Color | tuple[int, int, int] | None = None, offset: tuple[float, float, float] = (0.0, 0.0, 0.0))
width: float
depth: float
height: float
color: Color | tuple[int, int, int] | None
offset: tuple[float, float, float]
@final
class DebugCommands:
 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.

DebugCommands( client: sc2nachos.protocol.Client, game_map: sc2nachos.gamemap.GameMap, *, opponent_id: int | None, step: int)
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.

refresh_interval: sc2nachos.GameTime
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.

default_color: Color | tuple[int, int, int]
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.

default_text_size: int
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.

def draw( self, at: 'PointLike | Unit[Any]', *shapes: DebugShape, color: Color | tuple[int, int, int] | None = None, shown_for: sc2nachos.GameTime | None = GameTime(steps=1)) -> Drawing:
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.

def draw_text_on_screen( self, text: str, *, at: tuple[float, float], color: Color | tuple[int, int, int] | None = None, size: int | None = None, shown_for: sc2nachos.GameTime | None = GameTime(steps=1)) -> Drawing:
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.

cheats: frozenset[Cheat]
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).

def turn_on(self, cheat: Cheat) -> None:
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.

def turn_off(self, cheat: Cheat) -> None:
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.

def give_minerals(self) -> None:
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).

def give_resources(self) -> None:
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).

def give_upgrades(self) -> None:
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).

def create_units( self, unit_type: sc2nachos.UnitTypeId, *, at: 'PointLike', count: int = 1, owner: sc2nachos.units.Alliance = <Alliance.OWN: 1>) -> None:
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.

def kill( self, units: Union[sc2nachos.Unit[Any], Iterable[sc2nachos.Unit[Any]]]) -> None:
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.

def set_vitals( self, units: Union[sc2nachos.Unit[Any], Iterable[sc2nachos.Unit[Any]]], *, life: float | None = None, energy: float | None = None, shields: float | None = None) -> None:
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.

def declare_victory(self) -> None:
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).

def surrender(self) -> None:
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).

@final
class DebugGroup:
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.

DebugGroup( *shapes: DebugShape, color: Color | tuple[int, int, int] | None = None, offset: tuple[float, float, float] = (0.0, 0.0, 0.0))
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.

shapes: tuple[DebugShape, ...]
178    @property
179    def shapes(self) -> tuple[DebugShape, ...]:
180        """The shapes drawn together."""
181        return self._shapes

The shapes drawn together.

color: Color | tuple[int, int, int] | None
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

The color of each shape with none of its own, or None for the drawing's.

offset: tuple[float, float, float]
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

How far the group is drawn from where it is placed, across, up the map and up.

@final
@dataclass(frozen=True, slots=True)
class DebugLine:
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.

DebugLine( to: 'PointLike | Unit[Any]', color: Color | tuple[int, int, int] | None = None, offset: tuple[float, float, float] = (0.0, 0.0, 0.0), to_offset: tuple[float, float, float] = (0.0, 0.0, 0.0))
to: 'PointLike | Unit[Any]'
color: Color | tuple[int, int, int] | None
offset: tuple[float, float, float]
to_offset: tuple[float, float, float]
@final
@dataclass(frozen=True, slots=True)
class DebugMark:
 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))

A Marker around where it is placed, its arms or its corners radius from it, level with it.

DebugMark( marker: Marker, radius: float = 0.5, color: Color | tuple[int, int, int] | None = None, offset: tuple[float, float, float] = (0.0, 0.0, 0.0))
marker: Marker
radius: float
color: Color | tuple[int, int, int] | None
offset: tuple[float, float, float]
@final
@dataclass(frozen=True, slots=True)
class DebugSphere:
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.

DebugSphere( radius: float, color: Color | tuple[int, int, int] | None = None, offset: tuple[float, float, float] = (0.0, 0.0, 0.0))
radius: float
color: Color | tuple[int, int, int] | None
offset: tuple[float, float, float]
@final
@dataclass(frozen=True, slots=True)
class DebugText:
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.

DebugText( text: str, size: int | None = None, color: Color | tuple[int, int, int] | None = None, offset: tuple[float, float, float] = (0.0, 0.0, 0.0))
text: str
size: int | None
color: Color | tuple[int, int, int] | None
offset: tuple[float, float, float]
@final
class Drawing:
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.

Drawing( anchor: _Anchor, parts: tuple[sc2nachos.debug._drawing._PlacedShape, ...], *, until: int | None)
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.

def remove(self) -> None:
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

Take the drawing off the screen at the next refresh. Removing it again does nothing.

class Marker(enum.Enum):
 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.

CROSS = <Marker.CROSS: 'x'>

An ×, its two arms on the diagonals.

PLUS = <Marker.PLUS: '+'>

A +, its two arms along the axes.

STAR = <Marker.STAR: '*'>

The × and the + together.

TRIANGLE = <Marker.TRIANGLE: 'triangle'>

A triangle, pointing up the map.

SQUARE = <Marker.SQUARE: 'square'>

A square, its sides along the axes.

PENTAGON = <Marker.PENTAGON: 'pentagon'>

A pentagon, pointing up the map.

HEXAGON = <Marker.HEXAGON: 'hexagon'>

A hexagon, flat at the top and the bottom.