sc2nachos.pathing
How units get around the map.
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.
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.
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).
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.
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.
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.
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.