sc2nachos.vision

What this player sees: where it can see now, where it has seen, and when it last saw each tile.

1"""What this player sees: where it can see now, where it has seen, and when it last saw each tile."""
2
3from sc2nachos.vision._vision import Vision
4
5__all__ = ["Vision"]
@final
class Vision:
22@final
23class Vision:
24    """What this player sees, each grid over the playable area like the map's: `in_sight`, where it can see now;
25    `explored`, where it has seen at any point in the game; and `last_in_sight`, when it last saw each tile.
26    `time_unseen` says how long ago a tile or an area was last in sight."""
27
28    __slots__ = ("_handed_out", "_last_in_sight", "_stamped", "_state", "_step")
29
30    def __init__(self, last_in_sight: Grid[int], state: _State, step: int) -> None:
31        """Vision as of `state`, the observation at `step`, which is yet to be stamped, with the steps stamped before it
32        in `last_in_sight`, which it goes on stamping."""
33        self._last_in_sight = last_in_sight
34        self._state = state
35        self._step = step
36        self._stamped = False
37        self._handed_out: Grid[int] | None = None
38
39    @classmethod
40    def _build_at_start(cls, game_map: GameMap, *, state: _State, step: int) -> Vision:
41        """Vision at the start of a game on `game_map`, with no tile yet in sight, as of `state`, the first
42        observation, at `step`."""
43        never = Grid.like(game_map.pathing, dtype=int, outside=_NEVER_IN_SIGHT)
44        never.fill(_NEVER_IN_SIGHT)
45        return cls(never, state, step)
46
47    @property
48    def in_sight(self) -> Grid[bool]:
49        """Where this player can see now."""
50        return self._state.vision
51
52    @property
53    def explored(self) -> Grid[bool]:
54        """Where this player has seen at any point in the game."""
55        return self._state.explored
56
57    @property
58    def last_in_sight(self) -> Grid[int]:
59        """The step of the last observation that showed each tile in sight: -1 for a tile never in sight, and off the
60        grid. A grid read in one turn stays as it was in later ones. A tile in sight only between two observations
61        is never stamped, though `explored` shows it.
62
63        Raises `ProtocolError` if this observation reported no vision, as `in_sight` does.
64        """
65        if (handed_out := self._handed_out) is None:
66            # A copy, so a grid handed out in an earlier turn keeps its values.
67            handed_out = self._handed_out = self._stamped_steps().copy().as_readonly()
68        return handed_out
69
70    def time_unseen(self, where: PointLike | Area) -> GameTime:
71        """How long ago `where`, a tile or any tile of an area, was last in sight: zero while in sight, and
72        `GameTime.INFINITE` if never in sight, as for a point off the grid.
73
74        Raises `ProtocolError` if this observation reported no vision, as `in_sight` does.
75        """
76        last = int(numpy.max(self._stamped_steps()[where], initial=_NEVER_IN_SIGHT))
77        return GameTime.INFINITE if last == _NEVER_IN_SIGHT else GameTime(steps=self._step - last)
78
79    def _update(self, state: _State, step: int) -> None:
80        """Take in `state`, the observation at `step`, stamping `step` on each tile it shows in sight. An observation
81        whose vision cannot be read is not stamped, and the reads that need its stamp raise as `in_sight` does."""
82        self._state = state
83        self._step = step
84        self._handed_out = None
85        try:
86            in_sight = state.vision
87        except ProtocolError:
88            self._stamped = False
89            return
90        self._last_in_sight._data[in_sight.values] = step
91        self._stamped = True
92
93    def _stamped_steps(self) -> Grid[int]:
94        """The steps stamped up to this observation. Raises `ProtocolError` if this observation reported no vision."""
95        if not self._stamped:
96            # Reading the vision again raises why it could not be stamped.
97            _ = self._state.vision
98        return self._last_in_sight

What this player sees, each grid over the playable area like the map's: in_sight, where it can see now; explored, where it has seen at any point in the game; and last_in_sight, when it last saw each tile. time_unseen says how long ago a tile or an area was last in sight.

Vision( last_in_sight: sc2nachos.geometry.Grid[int], state: sc2nachos.state._state._State, step: int)
30    def __init__(self, last_in_sight: Grid[int], state: _State, step: int) -> None:
31        """Vision as of `state`, the observation at `step`, which is yet to be stamped, with the steps stamped before it
32        in `last_in_sight`, which it goes on stamping."""
33        self._last_in_sight = last_in_sight
34        self._state = state
35        self._step = step
36        self._stamped = False
37        self._handed_out: Grid[int] | None = None

Vision as of state, the observation at step, which is yet to be stamped, with the steps stamped before it in last_in_sight, which it goes on stamping.

in_sight: sc2nachos.geometry.Grid[bool]
47    @property
48    def in_sight(self) -> Grid[bool]:
49        """Where this player can see now."""
50        return self._state.vision

Where this player can see now.

explored: sc2nachos.geometry.Grid[bool]
52    @property
53    def explored(self) -> Grid[bool]:
54        """Where this player has seen at any point in the game."""
55        return self._state.explored

Where this player has seen at any point in the game.

last_in_sight: sc2nachos.geometry.Grid[int]
57    @property
58    def last_in_sight(self) -> Grid[int]:
59        """The step of the last observation that showed each tile in sight: -1 for a tile never in sight, and off the
60        grid. A grid read in one turn stays as it was in later ones. A tile in sight only between two observations
61        is never stamped, though `explored` shows it.
62
63        Raises `ProtocolError` if this observation reported no vision, as `in_sight` does.
64        """
65        if (handed_out := self._handed_out) is None:
66            # A copy, so a grid handed out in an earlier turn keeps its values.
67            handed_out = self._handed_out = self._stamped_steps().copy().as_readonly()
68        return handed_out

The step of the last observation that showed each tile in sight: -1 for a tile never in sight, and off the grid. A grid read in one turn stays as it was in later ones. A tile in sight only between two observations is never stamped, though explored shows it.

Raises ProtocolError if this observation reported no vision, as in_sight does.

def time_unseen( self, where: 'PointLike | Area') -> sc2nachos.GameTime:
70    def time_unseen(self, where: PointLike | Area) -> GameTime:
71        """How long ago `where`, a tile or any tile of an area, was last in sight: zero while in sight, and
72        `GameTime.INFINITE` if never in sight, as for a point off the grid.
73
74        Raises `ProtocolError` if this observation reported no vision, as `in_sight` does.
75        """
76        last = int(numpy.max(self._stamped_steps()[where], initial=_NEVER_IN_SIGHT))
77        return GameTime.INFINITE if last == _NEVER_IN_SIGHT else GameTime(steps=self._step - last)

How long ago where, a tile or any tile of an area, was last in sight: zero while in sight, and GameTime.INFINITE if never in sight, as for a point off the grid.

Raises ProtocolError if this observation reported no vision, as in_sight does.