board.py

Part of Bloom.

"""Bloom board: pure game logic. No graphics, no input, no randomness.

The capture resolver here is the single source of truth shared by the human
turn, the cascade animation, and the AI search. It is fully deterministic and
unit-testable headlessly.
"""

from enum import IntEnum

from hex_grid import DIRECTIONS, Hex, hex_in_range

# --- tunable rules ----------------------------------------------------------
BOARD_RADIUS = 4  # 61 cells (3R(R+1)+1); odd => no draw possible
CENTRE = Hex(0, 0)
WARM_START = Hex(0, -BOARD_RADIUS)
COOL_START = Hex(0, BOARD_RADIUS)  # exact mirror of WARM_START through centre
OUTNUMBER_MARGIN = 1  # strict: attackers must exceed friends by this


class Owner(IntEnum):
    EMPTY = 0
    WARM = 1  # amber. Solo: "You". Hotseat: "Player 1". First mover.
    COOL = 2  # azure. Solo: the AI. Hotseat: "Player 2".


def opponent(o: Owner) -> Owner:
    """Swap WARM<->COOL. Never called on EMPTY by the resolver."""
    return Owner.COOL if o is Owner.WARM else Owner.WARM


class Board:
    """Mutable hex board: one :class:`Owner` per cell plus ``last_placed``."""

    __slots__ = ("cells", "last_placed", "radius")

    def __init__(self, radius: int = BOARD_RADIUS):
        self.radius = radius
        self.cells: dict[Hex, Owner] = {}
        self.last_placed: Hex | None = None

    # --- construction -------------------------------------------------------
    def reset(self) -> None:
        """Lay out the deterministic mirrored opening."""
        self.cells = dict.fromkeys(hex_in_range(CENTRE, self.radius), Owner.EMPTY)
        assert len(self.cells) % 2 == 1, "board must have an odd cell count (no draws)"
        self.cells[WARM_START] = Owner.WARM
        self.cells[COOL_START] = Owner.COOL
        self.last_placed = None

    def copy(self) -> Board:
        b = Board(self.radius)
        b.cells = dict(self.cells)
        b.last_placed = self.last_placed
        return b

    # --- queries ------------------------------------------------------------
    def legal_moves(self) -> list[Hex]:
        """Empty cells in canonical (q, r) order. Always non-empty until full."""
        return sorted((h for h, o in self.cells.items() if o is Owner.EMPTY), key=lambda h: (h.q, h.r))

    def is_full(self) -> bool:
        return not any(o is Owner.EMPTY for o in self.cells.values())

    def score(self) -> tuple[int, int]:
        """(warm_count, cool_count)."""
        warm = sum(1 for o in self.cells.values() if o is Owner.WARM)
        cool = sum(1 for o in self.cells.values() if o is Owner.COOL)
        return warm, cool

    def winner(self) -> Owner:
        """The majority owner. Draws are impossible on an odd board."""
        warm, cool = self.score()
        return Owner.WARM if warm > cool else Owner.COOL


def board_neighbours(board: Board, h: Hex) -> list[Hex]:
    """On-board neighbours only. Off-board cells are never anyone's neighbour,
    which is what makes rim and corner cells defensible."""
    return [h + d for d in DIRECTIONS if (h + d) in board.cells]


def resolve_placement(board: Board, where: Hex, player: Owner) -> list[list[Hex]]:
    """Place ``player`` at ``where`` and run the outnumber cascade.

    Mutates ``board`` and returns the captured cells grouped by ring:
    ring 0 = direct captures triggered by the seed, ring 1 = captures triggered
    by ring-0 flips, and so on. ``where`` itself is not in the returned list.

    Precondition: ``board.cells[where] is Owner.EMPTY``.
    """
    assert board.cells.get(where) is Owner.EMPTY, "resolve_placement requires an empty target"
    cells = board.cells
    cells[where] = player
    board.last_placed = where
    foe = opponent(player)

    def is_captured(c: Hex) -> bool:
        attackers = friends = 0
        for n in board_neighbours(board, c):
            o = cells[n]
            if o is player:
                attackers += 1
            elif o is foe:
                friends += 1
        return attackers - friends >= OUTNUMBER_MARGIN

    flips_by_ring: list[list[Hex]] = []
    flipped: set[Hex] = set()
    frontier = [where]
    while frontier:
        # Candidate enemy cells adjacent to the current frontier, deduped and
        # processed in canonical (q, r) order for determinism.
        candidates: set[Hex] = set()
        for f in frontier:
            for n in board_neighbours(board, f):
                if n not in flipped and cells[n] is foe:
                    candidates.add(n)
        ring = [c for c in sorted(candidates, key=lambda h: (h.q, h.r)) if is_captured(c)]
        if not ring:
            break
        for c in ring:  # flip in-order; later cells see earlier flips
            cells[c] = player
            flipped.add(c)
        flips_by_ring.append(ring)
        frontier = ring
    return flips_by_ring


def build_board(radius: int = BOARD_RADIUS) -> Board:
    b = Board(radius)
    b.reset()
    return b