sc2nachos.pathing

How units get around the map.

1"""How units get around the map."""
2
3from sc2nachos.pathing._pathing import Pathing
4
5__all__ = ["Pathing"]
@final
class Pathing:
 24@final
 25class Pathing:
 26    """How units get around the map as it stands now, as the game answers."""
 27
 28    __slots__ = ("_client", "_grid", "_present_units")
 29
 30    _grid: Grid[bool] | None
 31    _present_units: Units[Unit[Any]]
 32
 33    def __init__(self, client: Client) -> None:
 34        """Pathing that asks the game `client` plays."""
 35        self._client = client
 36        self._grid = None
 37        self._present_units = Units(())
 38
 39    @property
 40    def grid(self) -> Grid[bool]:
 41        """Where a ground unit can walk now, as the game's pathing grid has it at the turn's observation, over the
 42        playable area, reading false beyond it; read-only. It is asked of the game the first time it is read in a turn,
 43        and the same grid is handed out for the rest of the turn.
 44
 45        Every structure in sight blocks the tiles it stands on, this player's and the enemy's, and so does every mineral
 46        field and geyser in sight; a rock blocks in sight or not. A structure out of sight blocks nothing, its snapshot
 47        included, nor does a lifted structure, nor a lowered supply depot from some 20 steps after it reads lowered; a
 48        unit that is no structure blocks nothing, but a sieged tank its own tile (in game).
 49        """
 50        if self._grid is None:
 51            self._grid = _create_pathing_grid(self._client.game_info().start_raw)
 52        return self._grid
 53
 54    def cheapest_path(
 55        self, start: PointLike | Tile | Unit[Any], end: PointLike | Tile, *, leave_structure: bool = True
 56    ) -> TilePath | None:
 57        """The shortest path over `grid` from `start` to `end`, as `Grid.cheapest_path` finds it, or `None` if there is
 58        none. From a unit, it starts where the unit stands.
 59
 60        With `leave_structure`, a path whose start lies in the footprint of a structure in sight, or that starts from a
 61        structure given, leaves it: the footprint is open to it, as the game's pathing query leaves the structure it
 62        starts in. A rock blocks more than its footprint covers, so a path from its outer tiles stays inside it. A path
 63        never enters a structure, so an end inside one has none.
 64        """
 65        position = start.position if isinstance(start, Unit) else start
 66        return self._grid_leaving_structure(start, leave_structure).cheapest_path(position, end)
 67
 68    def cheapest_paths_from(
 69        self, start: PointLike | Tile | Unit[Any], *, leave_structure: bool = True, outside: float | None = None
 70    ) -> CheapestPaths:
 71        """The shortest path over `grid` from `start` to every tile, as `Grid.cheapest_paths_from` finds them, leaving
 72        the structure the start lies in as `cheapest_path` does. `outside` is what their lengths read beyond the grid.
 73        """
 74        grid = self._grid_leaving_structure(start, leave_structure)
 75        position = start.position if isinstance(start, Unit) else start
 76        return grid.cheapest_paths_from(position, outside=outside)
 77
 78    def _grid_leaving_structure(self, start: PointLike | Tile | Unit[Any], leave_structure: bool) -> Grid[bool]:
 79        """`grid`, with the footprint of the structure `start` lies in open if `leave_structure`, on a copy: a unit
 80        given is its own, if it is a structure on the ground, and a point's is the one `Units.structure_at` finds among
 81        the turn's units."""
 82        if not leave_structure:
 83            return self.grid
 84        if isinstance(start, Unit):
 85            structure = start if start.is_ground_structure else None
 86        else:
 87            structure = self._present_units.structure_at(start)
 88        footprint = None if structure is None else structure.footprint
 89        if structure is None or footprint is None:
 90            return self.grid
 91        grid = self.grid.copy()
 92        grid.fill_footprint(footprint, at=structure.position, value=True)
 93        return grid
 94
 95    def _update(self, present_units: Units[Unit[Any]]) -> None:
 96        """Take in a new turn's observation, which reports `present_units`: the grid is asked for again when next
 97        read."""
 98        self._grid = None
 99        self._present_units = present_units
100
101    def query_distance(self, start: PointLike | Tile | Unit[Any], end: PointLike | Tile) -> float:
102        """The pathing distance from `start` to `end`, as `query_distances` asks the game for it for one pair."""
103        return self.query_distances([(start, end)])[0]
104
105    def query_distances(self, pairs: Iterable[tuple[PointLike | Tile | Unit[Any], PointLike | Tile]]) -> list[float]:
106        """The pathing distance from each start to its end, asked of the game in one request, a tile asked from or to
107        at its center.
108
109        The game paths over the map as of the turn's observation: a structure in the way is walked around, and a
110        lowered supply depot walked over from some 20 steps after the order. From a unit, the distance is that unit's
111        own: a reaper's jumps cliffs, and a flying unit's is the straight line. A path leaves a structure its start
112        lies in, but never enters one, so an end inside one reads `math.inf`, as does any end no path reaches (in
113        game).
114
115        Raises `ValueError` for a unit the last observation did not report.
116        """
117        requests: list[query_pb2.RequestQueryPathing] = []
118        coinciding: list[bool] = []
119        for start, end in pairs:
120            end_point = Point._rounded_to_float32(end.center if isinstance(end, Tile) else end)
121            request = query_pb2.RequestQueryPathing(end_pos=common_pb2.Point2D(x=end_point.x, y=end_point.y))
122            if isinstance(start, Unit):
123                if not start.is_listed:
124                    raise ValueError(f"the last observation did not report {start!r}, so the game cannot path from it")
125                request.unit_tag = start.tag
126                start_point = start.position
127            else:
128                start_point = Point._rounded_to_float32(start.center if isinstance(start, Tile) else start)
129                request.start_pos.x, request.start_pos.y = start_point.x, start_point.y
130            requests.append(request)
131            coinciding.append(start_point == end_point)
132        if not requests:
133            return []
134        answers = self._client.query(query_pb2.RequestQuery(pathing=requests)).pathing
135        if len(answers) != len(requests):
136            raise ProtocolError(f"the game answered {len(answers)} of the {len(requests)} pathing distances asked")
137        # The game answers 0 both for no path and from a point to itself (in game).
138        return [
139            answer.distance if answer.distance > 0 else 0.0 if same else math.inf
140            for answer, same in zip(answers, coinciding, strict=True)
141        ]

How units get around the map as it stands now, as the game answers.

Pathing(client: sc2nachos.protocol.Client)
33    def __init__(self, client: Client) -> None:
34        """Pathing that asks the game `client` plays."""
35        self._client = client
36        self._grid = None
37        self._present_units = Units(())

Pathing that asks the game client plays.

grid: sc2nachos.geometry.Grid[bool]
39    @property
40    def grid(self) -> Grid[bool]:
41        """Where a ground unit can walk now, as the game's pathing grid has it at the turn's observation, over the
42        playable area, reading false beyond it; read-only. It is asked of the game the first time it is read in a turn,
43        and the same grid is handed out for the rest of the turn.
44
45        Every structure in sight blocks the tiles it stands on, this player's and the enemy's, and so does every mineral
46        field and geyser in sight; a rock blocks in sight or not. A structure out of sight blocks nothing, its snapshot
47        included, nor does a lifted structure, nor a lowered supply depot from some 20 steps after it reads lowered; a
48        unit that is no structure blocks nothing, but a sieged tank its own tile (in game).
49        """
50        if self._grid is None:
51            self._grid = _create_pathing_grid(self._client.game_info().start_raw)
52        return self._grid

Where a ground unit can walk now, as the game's pathing grid has it at the turn's observation, over the playable area, reading false beyond it; read-only. It is asked of the game the first time it is read in a turn, and the same grid is handed out for the rest of the turn.

Every structure in sight blocks the tiles it stands on, this player's and the enemy's, and so does every mineral field and geyser in sight; a rock blocks in sight or not. A structure out of sight blocks nothing, its snapshot included, nor does a lifted structure, nor a lowered supply depot from some 20 steps after it reads lowered; a unit that is no structure blocks nothing, but a sieged tank its own tile (in game).

def cheapest_path( self, start: 'PointLike | Tile | Unit[Any]', end: 'PointLike | Tile', *, leave_structure: bool = True) -> sc2nachos.geometry.TilePath | None:
54    def cheapest_path(
55        self, start: PointLike | Tile | Unit[Any], end: PointLike | Tile, *, leave_structure: bool = True
56    ) -> TilePath | None:
57        """The shortest path over `grid` from `start` to `end`, as `Grid.cheapest_path` finds it, or `None` if there is
58        none. From a unit, it starts where the unit stands.
59
60        With `leave_structure`, a path whose start lies in the footprint of a structure in sight, or that starts from a
61        structure given, leaves it: the footprint is open to it, as the game's pathing query leaves the structure it
62        starts in. A rock blocks more than its footprint covers, so a path from its outer tiles stays inside it. A path
63        never enters a structure, so an end inside one has none.
64        """
65        position = start.position if isinstance(start, Unit) else start
66        return self._grid_leaving_structure(start, leave_structure).cheapest_path(position, end)

The shortest path over grid from start to end, as Grid.cheapest_path finds it, or None if there is none. From a unit, it starts where the unit stands.

With leave_structure, a path whose start lies in the footprint of a structure in sight, or that starts from a structure given, leaves it: the footprint is open to it, as the game's pathing query leaves the structure it starts in. A rock blocks more than its footprint covers, so a path from its outer tiles stays inside it. A path never enters a structure, so an end inside one has none.

def cheapest_paths_from( self, start: 'PointLike | Tile | Unit[Any]', *, leave_structure: bool = True, outside: float | None = None) -> sc2nachos.geometry.CheapestPaths:
68    def cheapest_paths_from(
69        self, start: PointLike | Tile | Unit[Any], *, leave_structure: bool = True, outside: float | None = None
70    ) -> CheapestPaths:
71        """The shortest path over `grid` from `start` to every tile, as `Grid.cheapest_paths_from` finds them, leaving
72        the structure the start lies in as `cheapest_path` does. `outside` is what their lengths read beyond the grid.
73        """
74        grid = self._grid_leaving_structure(start, leave_structure)
75        position = start.position if isinstance(start, Unit) else start
76        return grid.cheapest_paths_from(position, outside=outside)

The shortest path over grid from start to every tile, as Grid.cheapest_paths_from finds them, leaving the structure the start lies in as cheapest_path does. outside is what their lengths read beyond the grid.

def query_distance( self, start: 'PointLike | Tile | Unit[Any]', end: 'PointLike | Tile') -> float:
101    def query_distance(self, start: PointLike | Tile | Unit[Any], end: PointLike | Tile) -> float:
102        """The pathing distance from `start` to `end`, as `query_distances` asks the game for it for one pair."""
103        return self.query_distances([(start, end)])[0]

The pathing distance from start to end, as query_distances asks the game for it for one pair.

def query_distances( self, pairs: 'Iterable[tuple[PointLike | Tile | Unit[Any], PointLike | Tile]]') -> list[float]:
105    def query_distances(self, pairs: Iterable[tuple[PointLike | Tile | Unit[Any], PointLike | Tile]]) -> list[float]:
106        """The pathing distance from each start to its end, asked of the game in one request, a tile asked from or to
107        at its center.
108
109        The game paths over the map as of the turn's observation: a structure in the way is walked around, and a
110        lowered supply depot walked over from some 20 steps after the order. From a unit, the distance is that unit's
111        own: a reaper's jumps cliffs, and a flying unit's is the straight line. A path leaves a structure its start
112        lies in, but never enters one, so an end inside one reads `math.inf`, as does any end no path reaches (in
113        game).
114
115        Raises `ValueError` for a unit the last observation did not report.
116        """
117        requests: list[query_pb2.RequestQueryPathing] = []
118        coinciding: list[bool] = []
119        for start, end in pairs:
120            end_point = Point._rounded_to_float32(end.center if isinstance(end, Tile) else end)
121            request = query_pb2.RequestQueryPathing(end_pos=common_pb2.Point2D(x=end_point.x, y=end_point.y))
122            if isinstance(start, Unit):
123                if not start.is_listed:
124                    raise ValueError(f"the last observation did not report {start!r}, so the game cannot path from it")
125                request.unit_tag = start.tag
126                start_point = start.position
127            else:
128                start_point = Point._rounded_to_float32(start.center if isinstance(start, Tile) else start)
129                request.start_pos.x, request.start_pos.y = start_point.x, start_point.y
130            requests.append(request)
131            coinciding.append(start_point == end_point)
132        if not requests:
133            return []
134        answers = self._client.query(query_pb2.RequestQuery(pathing=requests)).pathing
135        if len(answers) != len(requests):
136            raise ProtocolError(f"the game answered {len(answers)} of the {len(requests)} pathing distances asked")
137        # The game answers 0 both for no path and from a point to itself (in game).
138        return [
139            answer.distance if answer.distance > 0 else 0.0 if same else math.inf
140            for answer, same in zip(answers, coinciding, strict=True)
141        ]

The pathing distance from each start to its end, asked of the game in one request, a tile asked from or to at its center.

The game paths over the map as of the turn's observation: a structure in the way is walked around, and a lowered supply depot walked over from some 20 steps after the order. From a unit, the distance is that unit's own: a reaper's jumps cliffs, and a flying unit's is the straight line. A path leaves a structure its start lies in, but never enters one, so an end inside one reads math.inf, as does any end no path reaches (in game).

Raises ValueError for a unit the last observation did not report.