sc2nachos.placement
Where a structure may stand.
1"""Where a structure may stand.""" 2 3from sc2nachos.placement._placement_grids import PlacementGrids 4from sc2nachos.placement._placement_reservation import PlacementReservation 5from sc2nachos.placement._walls import ProtossWall, TerranWall 6 7__all__ = ["PlacementGrids", "PlacementReservation", "ProtossWall", "TerranWall"]
30@final 31class PlacementGrids: 32 """Where a structure may stand, as this player knows the map in the current observation, in layers: `static`, the 33 ground the map lets a structure stand on all game; `dynamic`, where nothing stands now that can go; and 34 `reserved`, where this player's ordered builds will stand, and what it has reserved with `reserve`. 35 36 `free` combines them, and `free_for` adds what a structure type needs: the creep, and for a townhall, the ground 37 resources leave it. `is_free` says whether one may stand at a point, and `nearest_free` finds the nearest site where 38 one may. None of them knows of power or of units in the way. `terran_wall` and `protoss_wall` say where structures 39 close a main's ramp at its top. 40 """ 41 42 __slots__ = ( 43 "_build_sites", 44 "_dynamic", 45 "_game_data", 46 "_game_map", 47 "_ground_by_needs", 48 "_present_units", 49 "_reservations", 50 "_state", 51 "_static", 52 "_step", 53 "_townhall_ground", 54 ) 55 56 def __init__( 57 self, 58 static_placement_grid: Grid[bool], 59 *, 60 game_map: GameMap, 61 build_sites: _BuildSites, 62 present_units: Units[Unit[Any]], 63 state: _State, 64 step: int, 65 game_data: GameData, 66 ) -> None: 67 """The grids of the observation `state` reads, made at `step`, in which this player knows of `present_units`, 68 in sight or remembered, from the game's `static_placement_grid` and its `build_sites`, on `game_map`.""" 69 self._static = static_placement_grid 70 self._game_map = game_map 71 self._build_sites = build_sites 72 self._present_units = present_units 73 self._state = state 74 self._step = step 75 self._game_data = game_data 76 # What `reserve` made that has not ended, withdrawn ones until the next observation. 77 self._reservations: list[PlacementReservation] = [] 78 self._dynamic: Grid[bool] | None = None 79 self._townhall_ground: Grid[bool] | None = None 80 self._ground_by_needs: dict[tuple[bool, CreepRequirement | None], Grid[bool]] = {} 81 82 @classmethod 83 def _build_at_start( 84 cls, 85 game_map: GameMap, 86 *, 87 present_units: Units[Unit[Any]], 88 state: _State, 89 step: int, 90 game_data: GameData, 91 order_book: OrderBook, 92 ) -> Self: 93 """The grids of a game's first observation on `game_map`, which `state` reads, made at `step`, and in which this 94 player knows of `present_units`, from the map's placement grid at the start, and with this player's builds as 95 `order_book` holds them. The placement grid at the start blocks no unit, this player's townhall and the mineral 96 fields in sight included; it is the pathing grid that blocks those.""" 97 static = game_map.placement.copy() 98 for unit in present_units.of_type(UnitType.AnyVespeneGeyser, UnitType.CollapsibleTower): 99 if (footprint := unit.footprint) is not None: 100 static.fill_footprint(footprint, at=unit.position, value=False) 101 build_sites = _BuildSites(game_data, order_book) 102 return cls( 103 static.as_readonly(), 104 game_map=game_map, 105 build_sites=build_sites, 106 present_units=present_units, 107 state=state, 108 step=step, 109 game_data=game_data, 110 ) 111 112 def _update(self, present_units: Units[Unit[Any]], state: _State, step: int) -> None: 113 """Move on to a later observation of the same game, which `state` reads, made at `step`, and in which this 114 player knows of `present_units`. A reservation ends here if it has run its time or one of this player's 115 structures stands on its site.""" 116 self._present_units = present_units 117 self._state = state 118 self._step = step 119 if self._reservations: 120 standing = _standing_centers(present_units.own) 121 self._reservations = [ 122 reservation 123 for reservation in self._reservations 124 if not reservation._withdrawn 125 and (reservation._max_time is None or step < (reservation._time + reservation._max_time).steps) 126 and _placement_key(reservation.at) not in standing 127 ] 128 self._dynamic = None 129 self._townhall_ground = None 130 self._ground_by_needs = {} 131 132 @property 133 def static(self) -> Grid[bool]: 134 """Where a structure may stand whatever happens in the game: the ground the map lets a structure stand on, 135 less its geysers and its collapsible towers, which stay where they fall. It reads the ground under rocks, 136 Xel'Naga towers, mineral fields and townhalls as it is beneath them; cliffs, ramps and the ground beyond the 137 playable area are false.""" 138 return self._static 139 140 @property 141 def dynamic(self) -> Grid[bool]: 142 """Where nothing stands now that can go, as far as this player knows: false under the footprint of every 143 structure, every player's and the map's, in sight or remembered in the fog, and of every mineral field, and 144 true everywhere else, cliffs included. The geysers and collapsible towers `static` closes are not in it, and a 145 unit that moves, a structure in the air and a force field block nothing.""" 146 if self._dynamic is None: 147 dynamic = Grid.like(self._static, dtype=bool, outside=False) 148 dynamic.fill(True) 149 for unit in self._present_units.excluding_type(UnitType.AnyVespeneGeyser, UnitType.CollapsibleTower): 150 if (footprint := unit.footprint) is not None: 151 dynamic.fill_footprint(footprint, at=unit.position, value=False) 152 self._dynamic = dynamic.as_readonly() 153 return self._dynamic 154 155 @property 156 def reserved(self) -> Grid[bool]: 157 """The tiles under this player's builds that are ordered and not standing yet, issued this turn or sent and not 158 yet begun, and under each of `reservations`. A build or a reservation made or withdrawn earlier in the turn 159 shows. An add-on reserves the ground beside its host, and a lifted host's landing site too.""" 160 return self._build_sites.reserved_grid(self._static, self._present_units.own, self.reservations) 161 162 @property 163 def reservations(self) -> tuple[PlacementReservation, ...]: 164 """Every reservation `reserve` made that has not ended, oldest first.""" 165 return tuple(reservation for reservation in self._reservations if not reservation._withdrawn) 166 167 def reserve( 168 self, unit_type: UnitTypeId, *, at: PointLike, margin: Margin = 0, max_time: GameTime | None = None 169 ) -> PlacementReservation: 170 """Keep the ground a structure of `unit_type` would cover at `at`, placed as the game snaps it, and with 171 `margin`, every tile within it of one the footprint covers, as `is_free` takes it, out of `free`, `free_for`, 172 `is_free` and `nearest_free` from now, the rest of this turn included, until the reservation is withdrawn, until 173 `max_time` has passed if given, or until an observation shows one of this player's structures standing on its 174 site, whatever type it stands as. `max_time=GameTime(steps=1)` keeps it for this turn alone. Reservations may 175 overlap, and the game starts with none. 176 177 Raises `TypeError` for a `max_time` that is not a `GameTime` or a margin that is neither a count of tiles nor a 178 tuple of four, and `ValueError` for a type with no footprint, for a gas building, which stands on a geyser, for 179 a negative margin and for a `max_time` under one step.""" 180 footprint = self._footprint_of(unit_type) 181 _margin_sides(margin) 182 if max_time is not None: 183 check_game_time(max_time, "max_time") 184 if max_time.steps < 1: 185 raise ValueError(f"max_time is at least one step, not {max_time!r}") 186 center = footprint.snapped_center(at=at) 187 reservation = PlacementReservation( 188 unit_type, footprint, at=center, margin=margin, time=GameTime(steps=self._step), max_time=max_time 189 ) 190 self._reservations.append(reservation) 191 return reservation 192 193 @property 194 def free(self) -> Grid[bool]: 195 """Where a structure may stand now: on `static` and `dynamic`, and off `reserved`.""" 196 return self._static & self.dynamic & ~self.reserved 197 198 def free_for(self, unit_type: UnitTypeId) -> Grid[bool]: 199 """Where a structure of `unit_type` may stand now: `free`, on creep or off it as the type needs 200 (`UnitTypeData.creep_requirement`), and for a townhall, off the ground around each mineral field and geyser 201 this player knows of that keeps one off, as `api.expansions` heeds it. A gas building stands on a geyser, 202 which `static` closes, so it fits nowhere on any of them.""" 203 return self._ground_for(unit_type) & ~self.reserved 204 205 def is_free(self, unit_type: UnitTypeId, *, at: PointLike, margin: Margin = 0) -> bool: 206 """Whether a structure of `unit_type` may stand at `at` now, placed as the game snaps it: whether every tile 207 its footprint covers is true on `free_for(unit_type)`, and with `margin`, every tile within it of one the 208 footprint covers, as `Grid.fits_footprint` takes it. Raises `ValueError` for a type with no footprint, for a 209 gas building, which stands on a geyser, and for a negative margin.""" 210 footprint = self._footprint_of(unit_type) 211 if not self._ground_for(unit_type).fits_footprint(footprint, at=at, margin=margin): 212 return False 213 return (~self.reserved).fits_footprint(footprint, at=at, margin=margin) 214 215 def nearest_free( 216 self, unit_type: UnitTypeId, *, near: PointLike, max_distance: float, margin: Margin = 0 217 ) -> Point | None: 218 """The center nearest `near`, at most `max_distance` from it, where a structure of `unit_type` may stand now 219 with `margin` free beside it, as `is_free` says, and as the game snaps a structure; the first in tile order of 220 those as near. `None` if there is none; an infinite `max_distance` reaches the whole map. Raises `ValueError` 221 for a type with no footprint, for a gas building, which stands on a geyser, for a `max_distance` that is 222 negative or not a number, and for a negative margin.""" 223 if not max_distance >= 0: 224 raise ValueError(f"max_distance is a distance, at least 0, not {max_distance}") 225 footprint = self._footprint_of(unit_type) 226 sides = _margin_sides(margin) 227 x, y = near[0], near[1] 228 if math.isinf(max_distance): 229 window = self._static.bounds 230 else: 231 # Wide enough that every footprint centered within `max_distance` lies wholly inside, margin and all. 232 reach = math.ceil(max_distance) + max(footprint.width, footprint.height) + max(sides) 233 window = Rectangle(math.floor(x) - reach, math.floor(y) - reach, 2 * reach + 1, 2 * reach + 1) 234 free = self._ground_for(unit_type).cropped(window) & ~self.reserved.cropped(window) 235 fitting = free.where_footprint_fits(footprint, margin=margin) 236 # `distance_from` measures from each tile's center, which along an even side lies half a tile off the center 237 # of the footprint centered in that tile, so `near` moves by as much. 238 shift_x, shift_y = 0.5 - 0.5 * (footprint.width % 2), 0.5 - 0.5 * (footprint.height % 2) 239 distance = fitting.distance_from(Point((x + shift_x, y + shift_y))) 240 candidates = distance.where(fitting & (distance <= max_distance), math.inf) 241 if not fitting.any() or candidates.min() == math.inf: 242 return None 243 return footprint.center_in_tile(candidates.argmin_tile()) 244 245 def terran_wall(self, main_ramp: Ramp) -> TerranWall | None: 246 """Where a Terran wall closes `main_ramp`, the ramp out of a start location's main, its 247 `StartLocation.main_ramp`, at its top, as `TerranWall` says, near and far going by that start: `None` if the 248 ramp is not of the shape every main ramp of the pool is, two top tiles 2 wide climbing along a diagonal. Whether 249 a structure may stand at a site now is for `is_free` to say. Raises `ValueError` for a ramp out of no start 250 location's main.""" 251 return TerranWall._from_ramp(main_ramp, start=self._start_of_main_ramp(main_ramp)) 252 253 def protoss_wall(self, main_ramp: Ramp) -> ProtossWall | None: 254 """Where a Protoss wall closes `main_ramp` at its top, as `ProtossWall` says, its gap at the corner nearer the 255 start whose main the ramp leaves: `None` where `terran_wall` is. Whether a structure may stand at a site now is 256 for `is_free` to say. Raises `ValueError` for a ramp out of no start location's main.""" 257 return ProtossWall._from_ramp(main_ramp, start=self._start_of_main_ramp(main_ramp)) 258 259 def _start_of_main_ramp(self, main_ramp: Ramp) -> Point: 260 """The start location whose main `main_ramp` leaves; raises `ValueError` for a ramp out of no start location's 261 main.""" 262 for start_location in self._game_map.all_start_locations: 263 if self._game_map._main_ramp_of(start_location) == main_ramp: 264 return start_location 265 raise ValueError(f"the ramp at {main_ramp.top.center} leads out of no start location's main") 266 267 def _ground_for(self, unit_type: UnitTypeId) -> Grid[bool]: 268 """`free_for(unit_type)` before `reserved` is taken off, which no order changes: one grid for the types that 269 are townhalls or not alike and keep to creep or off it alike, built once an observation.""" 270 row = self._game_data.units.get(unit_type) 271 requirement = None if row is None else row.creep_requirement 272 keeps_to = requirement if requirement in (CreepRequirement.ON_CREEP, CreepRequirement.OFF_CREEP) else None 273 needs = (unit_type in UnitType.Townhall.type_ids, keeps_to) 274 if (ground := self._ground_by_needs.get(needs)) is None: 275 ground = self._static & self.dynamic 276 if needs[0]: 277 ground = ground & self._ground_townhalls_may_cover() 278 if keeps_to is CreepRequirement.ON_CREEP: 279 ground = ground & self._state.creep 280 elif keeps_to is CreepRequirement.OFF_CREEP: 281 ground = ground & ~self._state.creep 282 ground = self._ground_by_needs[needs] = ground.as_readonly() 283 return ground 284 285 def _footprint_of(self, unit_type: UnitTypeId) -> Footprint: 286 """The footprint a structure of `unit_type` covers; raises `ValueError` for a type with none, and for a gas 287 building, since `static` closes the geysers it stands on.""" 288 if unit_type in UnitType.GasBuilding.type_ids: 289 raise ValueError(f"{unit_type.name} stands on a geyser, which no placement grid leaves free") 290 row = self._game_data.units.get(unit_type) 291 if row is None or row.footprint is None: 292 raise ValueError(f"{unit_type.name} has no footprint, so it stands nowhere") 293 return row.footprint 294 295 def _ground_townhalls_may_cover(self) -> Grid[bool]: 296 """True everywhere but on the ground around each mineral field and geyser this player knows of that a 297 townhall may not cover. Built once an observation.""" 298 if self._townhall_ground is None: 299 ground = Grid.like(self._static, dtype=bool, outside=False) 300 ground.fill(True) 301 _keep_townhalls_off_resources( 302 ground, 303 mineral_fields=self._present_units.of_type(UnitType.AnyMineralField), 304 geysers=self._present_units.of_type(UnitType.AnyVespeneGeyser), 305 ) 306 self._townhall_ground = ground.as_readonly() 307 return self._townhall_ground
Where a structure may stand, as this player knows the map in the current observation, in layers: static, the
ground the map lets a structure stand on all game; dynamic, where nothing stands now that can go; and
reserved, where this player's ordered builds will stand, and what it has reserved with reserve.
free combines them, and free_for adds what a structure type needs: the creep, and for a townhall, the ground
resources leave it. is_free says whether one may stand at a point, and nearest_free finds the nearest site where
one may. None of them knows of power or of units in the way. terran_wall and protoss_wall say where structures
close a main's ramp at its top.
56 def __init__( 57 self, 58 static_placement_grid: Grid[bool], 59 *, 60 game_map: GameMap, 61 build_sites: _BuildSites, 62 present_units: Units[Unit[Any]], 63 state: _State, 64 step: int, 65 game_data: GameData, 66 ) -> None: 67 """The grids of the observation `state` reads, made at `step`, in which this player knows of `present_units`, 68 in sight or remembered, from the game's `static_placement_grid` and its `build_sites`, on `game_map`.""" 69 self._static = static_placement_grid 70 self._game_map = game_map 71 self._build_sites = build_sites 72 self._present_units = present_units 73 self._state = state 74 self._step = step 75 self._game_data = game_data 76 # What `reserve` made that has not ended, withdrawn ones until the next observation. 77 self._reservations: list[PlacementReservation] = [] 78 self._dynamic: Grid[bool] | None = None 79 self._townhall_ground: Grid[bool] | None = None 80 self._ground_by_needs: dict[tuple[bool, CreepRequirement | None], Grid[bool]] = {}
The grids of the observation state reads, made at step, in which this player knows of present_units,
in sight or remembered, from the game's static_placement_grid and its build_sites, on game_map.
132 @property 133 def static(self) -> Grid[bool]: 134 """Where a structure may stand whatever happens in the game: the ground the map lets a structure stand on, 135 less its geysers and its collapsible towers, which stay where they fall. It reads the ground under rocks, 136 Xel'Naga towers, mineral fields and townhalls as it is beneath them; cliffs, ramps and the ground beyond the 137 playable area are false.""" 138 return self._static
Where a structure may stand whatever happens in the game: the ground the map lets a structure stand on, less its geysers and its collapsible towers, which stay where they fall. It reads the ground under rocks, Xel'Naga towers, mineral fields and townhalls as it is beneath them; cliffs, ramps and the ground beyond the playable area are false.
140 @property 141 def dynamic(self) -> Grid[bool]: 142 """Where nothing stands now that can go, as far as this player knows: false under the footprint of every 143 structure, every player's and the map's, in sight or remembered in the fog, and of every mineral field, and 144 true everywhere else, cliffs included. The geysers and collapsible towers `static` closes are not in it, and a 145 unit that moves, a structure in the air and a force field block nothing.""" 146 if self._dynamic is None: 147 dynamic = Grid.like(self._static, dtype=bool, outside=False) 148 dynamic.fill(True) 149 for unit in self._present_units.excluding_type(UnitType.AnyVespeneGeyser, UnitType.CollapsibleTower): 150 if (footprint := unit.footprint) is not None: 151 dynamic.fill_footprint(footprint, at=unit.position, value=False) 152 self._dynamic = dynamic.as_readonly() 153 return self._dynamic
Where nothing stands now that can go, as far as this player knows: false under the footprint of every
structure, every player's and the map's, in sight or remembered in the fog, and of every mineral field, and
true everywhere else, cliffs included. The geysers and collapsible towers static closes are not in it, and a
unit that moves, a structure in the air and a force field block nothing.
155 @property 156 def reserved(self) -> Grid[bool]: 157 """The tiles under this player's builds that are ordered and not standing yet, issued this turn or sent and not 158 yet begun, and under each of `reservations`. A build or a reservation made or withdrawn earlier in the turn 159 shows. An add-on reserves the ground beside its host, and a lifted host's landing site too.""" 160 return self._build_sites.reserved_grid(self._static, self._present_units.own, self.reservations)
The tiles under this player's builds that are ordered and not standing yet, issued this turn or sent and not
yet begun, and under each of reservations. A build or a reservation made or withdrawn earlier in the turn
shows. An add-on reserves the ground beside its host, and a lifted host's landing site too.
162 @property 163 def reservations(self) -> tuple[PlacementReservation, ...]: 164 """Every reservation `reserve` made that has not ended, oldest first.""" 165 return tuple(reservation for reservation in self._reservations if not reservation._withdrawn)
Every reservation reserve made that has not ended, oldest first.
167 def reserve( 168 self, unit_type: UnitTypeId, *, at: PointLike, margin: Margin = 0, max_time: GameTime | None = None 169 ) -> PlacementReservation: 170 """Keep the ground a structure of `unit_type` would cover at `at`, placed as the game snaps it, and with 171 `margin`, every tile within it of one the footprint covers, as `is_free` takes it, out of `free`, `free_for`, 172 `is_free` and `nearest_free` from now, the rest of this turn included, until the reservation is withdrawn, until 173 `max_time` has passed if given, or until an observation shows one of this player's structures standing on its 174 site, whatever type it stands as. `max_time=GameTime(steps=1)` keeps it for this turn alone. Reservations may 175 overlap, and the game starts with none. 176 177 Raises `TypeError` for a `max_time` that is not a `GameTime` or a margin that is neither a count of tiles nor a 178 tuple of four, and `ValueError` for a type with no footprint, for a gas building, which stands on a geyser, for 179 a negative margin and for a `max_time` under one step.""" 180 footprint = self._footprint_of(unit_type) 181 _margin_sides(margin) 182 if max_time is not None: 183 check_game_time(max_time, "max_time") 184 if max_time.steps < 1: 185 raise ValueError(f"max_time is at least one step, not {max_time!r}") 186 center = footprint.snapped_center(at=at) 187 reservation = PlacementReservation( 188 unit_type, footprint, at=center, margin=margin, time=GameTime(steps=self._step), max_time=max_time 189 ) 190 self._reservations.append(reservation) 191 return reservation
Keep the ground a structure of unit_type would cover at at, placed as the game snaps it, and with
margin, every tile within it of one the footprint covers, as is_free takes it, out of free, free_for,
is_free and nearest_free from now, the rest of this turn included, until the reservation is withdrawn, until
max_time has passed if given, or until an observation shows one of this player's structures standing on its
site, whatever type it stands as. max_time=GameTime(steps=1) keeps it for this turn alone. Reservations may
overlap, and the game starts with none.
Raises TypeError for a max_time that is not a GameTime or a margin that is neither a count of tiles nor a
tuple of four, and ValueError for a type with no footprint, for a gas building, which stands on a geyser, for
a negative margin and for a max_time under one step.
198 def free_for(self, unit_type: UnitTypeId) -> Grid[bool]: 199 """Where a structure of `unit_type` may stand now: `free`, on creep or off it as the type needs 200 (`UnitTypeData.creep_requirement`), and for a townhall, off the ground around each mineral field and geyser 201 this player knows of that keeps one off, as `api.expansions` heeds it. A gas building stands on a geyser, 202 which `static` closes, so it fits nowhere on any of them.""" 203 return self._ground_for(unit_type) & ~self.reserved
Where a structure of unit_type may stand now: free, on creep or off it as the type needs
(UnitTypeData.creep_requirement), and for a townhall, off the ground around each mineral field and geyser
this player knows of that keeps one off, as api.expansions heeds it. A gas building stands on a geyser,
which static closes, so it fits nowhere on any of them.
205 def is_free(self, unit_type: UnitTypeId, *, at: PointLike, margin: Margin = 0) -> bool: 206 """Whether a structure of `unit_type` may stand at `at` now, placed as the game snaps it: whether every tile 207 its footprint covers is true on `free_for(unit_type)`, and with `margin`, every tile within it of one the 208 footprint covers, as `Grid.fits_footprint` takes it. Raises `ValueError` for a type with no footprint, for a 209 gas building, which stands on a geyser, and for a negative margin.""" 210 footprint = self._footprint_of(unit_type) 211 if not self._ground_for(unit_type).fits_footprint(footprint, at=at, margin=margin): 212 return False 213 return (~self.reserved).fits_footprint(footprint, at=at, margin=margin)
Whether a structure of unit_type may stand at at now, placed as the game snaps it: whether every tile
its footprint covers is true on free_for(unit_type), and with margin, every tile within it of one the
footprint covers, as Grid.fits_footprint takes it. Raises ValueError for a type with no footprint, for a
gas building, which stands on a geyser, and for a negative margin.
215 def nearest_free( 216 self, unit_type: UnitTypeId, *, near: PointLike, max_distance: float, margin: Margin = 0 217 ) -> Point | None: 218 """The center nearest `near`, at most `max_distance` from it, where a structure of `unit_type` may stand now 219 with `margin` free beside it, as `is_free` says, and as the game snaps a structure; the first in tile order of 220 those as near. `None` if there is none; an infinite `max_distance` reaches the whole map. Raises `ValueError` 221 for a type with no footprint, for a gas building, which stands on a geyser, for a `max_distance` that is 222 negative or not a number, and for a negative margin.""" 223 if not max_distance >= 0: 224 raise ValueError(f"max_distance is a distance, at least 0, not {max_distance}") 225 footprint = self._footprint_of(unit_type) 226 sides = _margin_sides(margin) 227 x, y = near[0], near[1] 228 if math.isinf(max_distance): 229 window = self._static.bounds 230 else: 231 # Wide enough that every footprint centered within `max_distance` lies wholly inside, margin and all. 232 reach = math.ceil(max_distance) + max(footprint.width, footprint.height) + max(sides) 233 window = Rectangle(math.floor(x) - reach, math.floor(y) - reach, 2 * reach + 1, 2 * reach + 1) 234 free = self._ground_for(unit_type).cropped(window) & ~self.reserved.cropped(window) 235 fitting = free.where_footprint_fits(footprint, margin=margin) 236 # `distance_from` measures from each tile's center, which along an even side lies half a tile off the center 237 # of the footprint centered in that tile, so `near` moves by as much. 238 shift_x, shift_y = 0.5 - 0.5 * (footprint.width % 2), 0.5 - 0.5 * (footprint.height % 2) 239 distance = fitting.distance_from(Point((x + shift_x, y + shift_y))) 240 candidates = distance.where(fitting & (distance <= max_distance), math.inf) 241 if not fitting.any() or candidates.min() == math.inf: 242 return None 243 return footprint.center_in_tile(candidates.argmin_tile())
The center nearest near, at most max_distance from it, where a structure of unit_type may stand now
with margin free beside it, as is_free says, and as the game snaps a structure; the first in tile order of
those as near. None if there is none; an infinite max_distance reaches the whole map. Raises ValueError
for a type with no footprint, for a gas building, which stands on a geyser, for a max_distance that is
negative or not a number, and for a negative margin.
245 def terran_wall(self, main_ramp: Ramp) -> TerranWall | None: 246 """Where a Terran wall closes `main_ramp`, the ramp out of a start location's main, its 247 `StartLocation.main_ramp`, at its top, as `TerranWall` says, near and far going by that start: `None` if the 248 ramp is not of the shape every main ramp of the pool is, two top tiles 2 wide climbing along a diagonal. Whether 249 a structure may stand at a site now is for `is_free` to say. Raises `ValueError` for a ramp out of no start 250 location's main.""" 251 return TerranWall._from_ramp(main_ramp, start=self._start_of_main_ramp(main_ramp))
Where a Terran wall closes main_ramp, the ramp out of a start location's main, its
StartLocation.main_ramp, at its top, as TerranWall says, near and far going by that start: None if the
ramp is not of the shape every main ramp of the pool is, two top tiles 2 wide climbing along a diagonal. Whether
a structure may stand at a site now is for is_free to say. Raises ValueError for a ramp out of no start
location's main.
253 def protoss_wall(self, main_ramp: Ramp) -> ProtossWall | None: 254 """Where a Protoss wall closes `main_ramp` at its top, as `ProtossWall` says, its gap at the corner nearer the 255 start whose main the ramp leaves: `None` where `terran_wall` is. Whether a structure may stand at a site now is 256 for `is_free` to say. Raises `ValueError` for a ramp out of no start location's main.""" 257 return ProtossWall._from_ramp(main_ramp, start=self._start_of_main_ramp(main_ramp))
Where a Protoss wall closes main_ramp at its top, as ProtossWall says, its gap at the corner nearer the
start whose main the ramp leaves: None where terran_wall is. Whether a structure may stand at a site now is
for is_free to say. Raises ValueError for a ramp out of no start location's main.
14@final 15class PlacementReservation: 16 """The ground a structure would cover at a site, and its margin, which `api.placement.reserve` keeps out of `free`, 17 `free_for`, `is_free` and `nearest_free` from the time it was made at until it ends: once withdrawn, once 18 `max_time` has passed, or at the first observation showing one of this player's structures standing on its 19 site, whatever type it stands as. An ended reservation never comes back.""" 20 21 __slots__ = ("_at", "_footprint", "_margin", "_max_time", "_time", "_type_id", "_withdrawn") 22 23 def __init__( 24 self, 25 type_id: UnitTypeId, 26 footprint: Footprint, 27 *, 28 at: Point, 29 margin: Margin, 30 time: GameTime, 31 max_time: GameTime | None, 32 ) -> None: 33 """A reservation for a structure of `type_id`, which covers `footprint`, centered at `at`, and the tiles within 34 `margin` of it, made at `time`.""" 35 self._type_id = type_id 36 self._footprint = footprint 37 self._at = at 38 self._margin = margin 39 self._time = time 40 self._max_time = max_time 41 self._withdrawn = False 42 43 @property 44 def type_id(self) -> UnitTypeId: 45 """The type of structure the ground is kept for.""" 46 return self._type_id 47 48 @property 49 def at(self) -> Point: 50 """Where the structure would center, snapped as the game snaps one.""" 51 return self._at 52 53 @property 54 def margin(self) -> Margin: 55 """The tiles kept free beside the footprint, as `Grid.fits_footprint` takes them.""" 56 return self._margin 57 58 @property 59 def time(self) -> GameTime: 60 """When it was made.""" 61 return self._time 62 63 @property 64 def max_time(self) -> GameTime | None: 65 """The longest it lasts, or `None` to last until it is withdrawn or construction starts on its site.""" 66 return self._max_time 67 68 def withdraw(self) -> None: 69 """End the reservation at once, for the rest of the turn too. Withdrawing it again does nothing.""" 70 self._withdrawn = True 71 72 def __repr__(self) -> str: 73 return ( 74 f"PlacementReservation({self._type_id.name} at {self._at}, margin {self._margin}, made {self._time}," 75 f" max {self._max_time})" 76 )
The ground a structure would cover at a site, and its margin, which api.placement.reserve keeps out of free,
free_for, is_free and nearest_free from the time it was made at until it ends: once withdrawn, once
max_time has passed, or at the first observation showing one of this player's structures standing on its
site, whatever type it stands as. An ended reservation never comes back.
23 def __init__( 24 self, 25 type_id: UnitTypeId, 26 footprint: Footprint, 27 *, 28 at: Point, 29 margin: Margin, 30 time: GameTime, 31 max_time: GameTime | None, 32 ) -> None: 33 """A reservation for a structure of `type_id`, which covers `footprint`, centered at `at`, and the tiles within 34 `margin` of it, made at `time`.""" 35 self._type_id = type_id 36 self._footprint = footprint 37 self._at = at 38 self._margin = margin 39 self._time = time 40 self._max_time = max_time 41 self._withdrawn = False
43 @property 44 def type_id(self) -> UnitTypeId: 45 """The type of structure the ground is kept for.""" 46 return self._type_id
The type of structure the ground is kept for.
48 @property 49 def at(self) -> Point: 50 """Where the structure would center, snapped as the game snaps one.""" 51 return self._at
Where the structure would center, snapped as the game snaps one.
53 @property 54 def margin(self) -> Margin: 55 """The tiles kept free beside the footprint, as `Grid.fits_footprint` takes them.""" 56 return self._margin
The tiles kept free beside the footprint, as Grid.fits_footprint takes them.
63 @property 64 def max_time(self) -> GameTime | None: 65 """The longest it lasts, or `None` to last until it is withdrawn or construction starts on its site.""" 66 return self._max_time
The longest it lasts, or None to last until it is withdrawn or construction starts on its site.
68@final 69@dataclass(frozen=True, slots=True) 70class ProtossWall: 71 """Where a Protoss wall closes a main's ramp at its top but for a gap one unit closes: a pylon that powers two 3x3 72 buildings, as a gateway, a forge or a cybernetics core is. Each site is a structure's center, as 73 `PlacementGrids.is_free` takes it, and whether one may stand there now is for `is_free` to say. 74 """ 75 76 pylon: Point 77 near_building: Point 78 """The building beside the gap, at the corner nearer the main's start; of two corners as near, the one with the 79 lower x.""" 80 far_building: Point 81 """The building at the corner farther from the main's start.""" 82 gap: Point 83 """Where a unit stands to close the wall, at the corner nearer the main's start.""" 84 85 @classmethod 86 def _from_ramp(cls, ramp: Ramp, *, start: PointLike) -> ProtossWall | None: 87 """The Protoss wall at the top of `ramp` out of the main `start` stands in, or `None` if the ramp is not of the 88 shape every main ramp of the pool is: two top tiles, 2 wide, and climbing along a diagonal.""" 89 if not _is_shaped_like_the_pools_main_ramps(ramp): 90 return None 91 near_corner, _ = _corners_nearer_first(ramp, start) 92 gap_at_the_second_corner = near_corner == ramp._point_at_offset_from_the_top(_CORNER_DEPOT_OFFSETS[1]) 93 94 def site_by_the_near_corner(offset: tuple[float, float]) -> Point: 95 """The site `offset` gives for a wall with its gap at the second corner, mirrored across the line the ramp 96 climbs along where the gap is at the first.""" 97 return ramp._point_at_offset_from_the_top(offset if gap_at_the_second_corner else (offset[1], offset[0])) 98 99 return cls( 100 pylon=ramp._point_at_offset_from_the_top((4.0, 4.0)), 101 near_building=site_by_the_near_corner((0.5, 2.5)), 102 far_building=site_by_the_near_corner((2.5, -0.5)), 103 gap=site_by_the_near_corner((-1.5, 1.5)), 104 )
Where a Protoss wall closes a main's ramp at its top but for a gap one unit closes: a pylon that powers two 3x3
buildings, as a gateway, a forge or a cybernetics core is. Each site is a structure's center, as
PlacementGrids.is_free takes it, and whether one may stand there now is for is_free to say.
The building beside the gap, at the corner nearer the main's start; of two corners as near, the one with the lower x.
22@final 23@dataclass(frozen=True, slots=True) 24class TerranWall: 25 """Where a Terran wall closes a main's ramp at its top: a supply depot at each corner, and between them a barracks 26 or a third depot. Each site is a structure's center, as `PlacementGrids.is_free` takes it, and whether one may 27 stand there now is for `is_free` to say. 28 """ 29 30 near_depot: Point 31 """The corner depot nearer the main's start; of two as near, the one with the lower x.""" 32 far_depot: Point 33 barracks_with_add_on: Point 34 """A barracks between the depots with room for its add-on, on its right. On a main left of its ramp, which climbs 35 toward -x, no barracks between them both closes the wall and leaves that room (corpus), so this one closes it only 36 once its add-on stands.""" 37 add_on: Point 38 """The center of the add-on of the barracks at `barracks_with_add_on`.""" 39 barracks_in_wall: Point 40 """A barracks between the depots that closes the wall by itself. On a main right of its ramp it stands where 41 `barracks_with_add_on` does; on one left of it, it leaves no room for an add-on.""" 42 middle_depot: Point 43 """A third depot, in the barracks's place.""" 44 45 @classmethod 46 def _from_ramp(cls, ramp: Ramp, *, start: PointLike) -> TerranWall | None: 47 """The Terran wall at the top of `ramp` out of the main `start` stands in, or `None` if the ramp is not of the 48 shape every main ramp of the pool is: two top tiles, 2 wide, and climbing along a diagonal.""" 49 if not _is_shaped_like_the_pools_main_ramps(ramp): 50 return None 51 near_corner, far_corner = _corners_nearer_first(ramp, start) 52 barracks_in_wall = ramp._point_at_offset_from_the_top((1.5, 1.5)) 53 barracks_with_add_on = barracks_in_wall 54 if ramp.orientation.value[0] < 0: 55 # Its add-on stands on its right, so where the ramp climbs toward -x it moves 2 left to leave the add-on 56 # room beside the depot. 57 barracks_with_add_on = Point((barracks_in_wall.x - 2, barracks_in_wall.y)) 58 return cls( 59 near_depot=near_corner, 60 far_depot=far_corner, 61 barracks_with_add_on=barracks_with_add_on, 62 add_on=Point((barracks_with_add_on.x + ADD_ON_OFFSET[0], barracks_with_add_on.y + ADD_ON_OFFSET[1])), 63 barracks_in_wall=barracks_in_wall, 64 middle_depot=ramp._point_at_offset_from_the_top((1.0, 1.0)), 65 )
Where a Terran wall closes a main's ramp at its top: a supply depot at each corner, and between them a barracks
or a third depot. Each site is a structure's center, as PlacementGrids.is_free takes it, and whether one may
stand there now is for is_free to say.
The corner depot nearer the main's start; of two as near, the one with the lower x.
A barracks between the depots with room for its add-on, on its right. On a main left of its ramp, which climbs toward -x, no barracks between them both closes the wall and leaves that room (corpus), so this one closes it only once its add-on stands.
A barracks between the depots that closes the wall by itself. On a main right of its ramp it stands where
barracks_with_add_on does; on one left of it, it leaves no room for an add-on.