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"]
@final
class PlacementGrids:
 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.

PlacementGrids( static_placement_grid: sc2nachos.geometry.Grid[bool], *, game_map: sc2nachos.gamemap.GameMap, build_sites: sc2nachos.placement._build_sites._BuildSites, present_units: sc2nachos.Units[sc2nachos.Unit[typing.Any]], state: sc2nachos.state._state._State, step: int, game_data: sc2nachos.gamedata.GameData)
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.

static: sc2nachos.geometry.Grid[bool]
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.

dynamic: sc2nachos.geometry.Grid[bool]
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.

reserved: sc2nachos.geometry.Grid[bool]
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.

reservations: tuple[PlacementReservation, ...]
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.

def reserve( self, unit_type: sc2nachos.UnitTypeId, *, at: 'PointLike', margin: Margin = 0, max_time: sc2nachos.GameTime | None = None) -> PlacementReservation:
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.

free: sc2nachos.geometry.Grid[bool]
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

Where a structure may stand now: on static and dynamic, and off reserved.

def free_for( self, unit_type: sc2nachos.UnitTypeId) -> sc2nachos.geometry.Grid[bool]:
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.

def is_free( self, unit_type: sc2nachos.UnitTypeId, *, at: 'PointLike', margin: Margin = 0) -> bool:
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.

def nearest_free( self, unit_type: sc2nachos.UnitTypeId, *, near: 'PointLike', max_distance: float, margin: Margin = 0) -> sc2nachos.Point | None:
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.

def terran_wall( self, main_ramp: sc2nachos.gamemap.Ramp) -> TerranWall | None:
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.

def protoss_wall( self, main_ramp: sc2nachos.gamemap.Ramp) -> ProtossWall | None:
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.

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

PlacementReservation( type_id: sc2nachos.UnitTypeId, footprint: sc2nachos.Footprint, *, at: sc2nachos.Point, margin: Margin, time: sc2nachos.GameTime, max_time: sc2nachos.GameTime | None)
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

A reservation for a structure of type_id, which covers footprint, centered at at, and the tiles within margin of it, made at time.

type_id: sc2nachos.UnitTypeId
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.

at: sc2nachos.Point
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.

margin: sc2nachos.geometry.Margin
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.

time: sc2nachos.GameTime
58    @property
59    def time(self) -> GameTime:
60        """When it was made."""
61        return self._time

When it was made.

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

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

End the reservation at once, for the rest of the turn too. Withdrawing it again does nothing.

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

ProtossWall( pylon: sc2nachos.Point, near_building: sc2nachos.Point, far_building: sc2nachos.Point, gap: sc2nachos.Point)
near_building: sc2nachos.Point

The building beside the gap, at the corner nearer the main's start; of two corners as near, the one with the lower x.

far_building: sc2nachos.Point

The building at the corner farther from the main's start.

Where a unit stands to close the wall, at the corner nearer the main's start.

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

TerranWall( near_depot: sc2nachos.Point, far_depot: sc2nachos.Point, barracks_with_add_on: sc2nachos.Point, add_on: sc2nachos.Point, barracks_in_wall: sc2nachos.Point, middle_depot: sc2nachos.Point)
near_depot: sc2nachos.Point

The corner depot nearer the main's start; of two as near, the one with the lower x.

far_depot: sc2nachos.Point
barracks_with_add_on: sc2nachos.Point

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.

add_on: sc2nachos.Point

The center of the add-on of the barracks at barracks_with_add_on.

barracks_in_wall: sc2nachos.Point

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.

middle_depot: sc2nachos.Point

A third depot, in the barracks's place.