i151-engine 0.1.0__py3-none-any.whl

i151_engine/__init__.py

@@ -0,0 +1,6 @@
+"""i151 competition headless game engine."""
+
+from i151_engine.models.card import Card, Rank, Suit
+from i151_engine.models.action import Action, ActionType
+
+__all__ = ["Card", "Rank", "Suit", "Action", "ActionType"]

i151_engine/bots/protocol.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from i151_engine.models.action import Action
+from i151_engine.view.player_view import PlayerView
+
+
+class Bot(Protocol):
+    def setup(self, submission_dir: Path) -> None: ...
+
+    def decide(
+        self,
+        view: PlayerView,
+        legal_actions: list[Action],
+        time_left_ms: int,
+    ) -> Action: ...
+
+    def teardown(self) -> None: ...

i151_engine/bots/random_bot.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import random
+from pathlib import Path
+
+from i151_engine.bots.protocol import Bot, PlayerView
+from i151_engine.models.action import Action
+
+
+class RandomBot:
+    def __init__(self, *, seed: int | None = None) -> None:
+        self._seed = seed
+        self._rng = random.Random(seed)
+
+    def setup(self, submission_dir: Path) -> None:
+        del submission_dir
+        self._rng = random.Random(self._seed)
+
+    def decide(
+        self,
+        view: PlayerView,
+        legal_actions: list[Action],
+        time_left_ms: int,
+    ) -> Action:
+        del view, time_left_ms
+        if not legal_actions:
+            raise RuntimeError("No legal actions")
+        return self._rng.choice(legal_actions)
+
+    def teardown(self) -> None:
+        return None

i151_engine/core/__init__.py

@@ -0,0 +1,15 @@
+from i151_engine.core.deck import Deck
+from i151_engine.core.errors import IllegalActionError
+from i151_engine.core.rules import (
+    hand_score,
+    is_valid_multiple_play,
+    is_valid_single_play,
+)
+
+__all__ = [
+    "Deck",
+    "IllegalActionError",
+    "hand_score",
+    "is_valid_multiple_play",
+    "is_valid_single_play",
+]

i151_engine/core/deck.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+
+from i151_engine.models.card import Card, standard_deck
+
+STANDARD_DECK_SIZE = 32
+
+
+def validate_cards_per_player(cards_per_player: int, *, player_count: int) -> None:
+    """Vérifie qu'une distribution initiale est possible avec un jeu de 32 cartes."""
+    if cards_per_player < 1:
+        raise ValueError(f"cards_per_player doit être >= 1 (reçu {cards_per_player})")
+    max_deal = STANDARD_DECK_SIZE // player_count
+    if cards_per_player > max_deal:
+        raise ValueError(
+            f"cards_per_player={cards_per_player} trop élevé pour {player_count} joueur(s) "
+            f"(maximum {max_deal})"
+        )
+
+
+@dataclass
+class Deck:
+    """Mutable deck + bank — copied when building immutable round states."""
+
+    _draw_pile: list[Card] = field(default_factory=list)
+    _bank: list[Card] = field(default_factory=list)
+    cards_per_player: int = 8
+
+    def reset(self, seed: int | None = None) -> None:
+        self._draw_pile = standard_deck()
+        self.shuffle(seed)
+
+    def shuffle(self, seed: int | None = None) -> None:
+        rng = random.Random(seed)
+        rng.shuffle(self._draw_pile)
+
+    def deal(self, player_count: int, *, seed: int | None = None) -> list[list[Card]]:
+        if not self._draw_pile:
+            self.reset(seed)
+        elif seed is not None:
+            self.shuffle(seed)
+
+        cards_per_player = self.cards_per_player
+        if player_count == 4:
+            cards_per_player = 7
+
+        max_cards = min(cards_per_player, len(self._draw_pile) // player_count)
+        total_to_deal = player_count * max_cards
+        if len(self._draw_pile) < total_to_deal:
+            per_player = len(self._draw_pile) // player_count
+            total_to_deal = per_player * player_count
+
+        hands: list[list[Card]] = [[] for _ in range(player_count)]
+        current = 0
+        for i in range(total_to_deal):
+            hands[current].append(self._draw_pile[i])
+            current = (current + 1) % player_count
+
+        self._bank = self._draw_pile[total_to_deal:]
+        self._draw_pile = []
+        return hands
+
+    def draw(self, count: int) -> list[Card]:
+        drawn: list[Card] = []
+        for _ in range(count):
+            if not self._bank:
+                break
+            drawn.append(self._bank.pop(0))
+        return drawn
+
+    @property
+    def bank_size(self) -> int:
+        return len(self._bank)
+
+    def add_to_bank(self, cards: list[Card] | tuple[Card, ...]) -> None:
+        self._bank.extend(cards)
+
+    def bank_tuple(self) -> tuple[Card, ...]:
+        return tuple(self._bank)
+
+    def set_bank(self, bank: list[Card] | tuple[Card, ...]) -> None:
+        self._bank = list(bank)
+
+    def copy(self) -> Deck:
+        other = Deck(cards_per_player=self.cards_per_player)
+        other._draw_pile = self._draw_pile.copy()
+        other._bank = self._bank.copy()
+        return other

i151_engine/core/errors.py

@@ -0,0 +1,2 @@
+class IllegalActionError(ValueError):
+    """Raised when a player attempts an illegal action."""

i151_engine/core/legal_actions.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from i151_engine.models.action import Action, ActionType
+from i151_engine.models.card import Card, Rank, Suit
+from i151_engine.models.player import PlayerState
+from i151_engine.game.round_state import RoundState
+
+
+def legal_actions(state: RoundState) -> list[Action]:
+    if state.phase.value != "playing":
+        return []
+
+    player = state.current_player
+    actions: list[Action] = []
+
+    playable = _playable_cards(player, state)
+    if player.is_chaining and state.top_card is not None:
+        playable = [c for c in playable if c.rank == state.top_card.rank]
+
+    for card in playable:
+        actions.append(Action.play_card(card))
+
+    if state.choose_suit and state.top_card is not None and state.top_card.rank == Rank.EIGHT:
+        for suit in Suit:
+            actions.append(Action.choose_suit(suit))
+
+    if state.top_card is not None and not state.choose_suit:
+        if player.has_drawn_this_turn or player.is_chaining:
+            actions.append(Action.pass_turn())
+        else:
+            actions.append(Action.draw_card())
+
+    if state.top_card is None and not state.choose_suit:
+        if player.has_drawn_this_turn or player.is_chaining:
+            actions.append(Action.pass_turn())
+        elif not actions:
+            actions.append(Action.draw_card())
+
+    return actions
+
+
+def _playable_cards(player: PlayerState, state: RoundState) -> list[Card]:
+    result: list[Card] = []
+    for card in player.hand:
+        if state.top_card is None and state.required_suit is None:
+            result.append(card)
+        elif card.can_play_on_with_required_suit(state.top_card, state.required_suit):
+            result.append(card)
+    return result

i151_engine/core/reducer.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+from dataclasses import replace
+
+from i151_engine.core.deck import Deck
+from i151_engine.core.errors import IllegalActionError
+from i151_engine.core.rules import is_valid_multiple_play, is_valid_single_play
+from i151_engine.game.round_state import RoundState
+from i151_engine.models.action import Action, ActionType
+from i151_engine.models.card import Rank
+from i151_engine.models.enums import RoundPhase
+from i151_engine.models.player import PlayerState
+
+
+def apply_action(state: RoundState, action: Action) -> RoundState:
+    if state.phase != RoundPhase.PLAYING:
+        raise IllegalActionError("Round is not in playing phase")
+
+    player = state.current_player
+    if action.type == ActionType.PLAY_CARD:
+        if action.card is None:
+            raise IllegalActionError("Missing card")
+        return _handle_play(state, player, [action.card], action.chosen_suit)
+    if action.type == ActionType.PLAY_MULTIPLE_CARDS:
+        if not action.cards:
+            raise IllegalActionError("Missing cards")
+        return _handle_play(state, player, list(action.cards), action.chosen_suit)
+    if action.type == ActionType.DRAW_CARD:
+        return _handle_draw(state, player)
+    if action.type == ActionType.PASS_TURN:
+        return _handle_pass(state, player)
+    if action.type == ActionType.CHOOSE_SUIT:
+        if action.chosen_suit is None:
+            raise IllegalActionError("Missing chosen suit")
+        return _handle_choose_suit(state, player, action.chosen_suit)
+    raise IllegalActionError(f"Unsupported action: {action.type}")
+
+
+def _handle_play(
+    state: RoundState,
+    player: PlayerState,
+    cards: list,
+    chosen_suit,
+) -> RoundState:
+    if len(cards) == 1:
+        if not is_valid_single_play(player, cards[0], state):
+            raise IllegalActionError("Invalid single play")
+    else:
+        if not is_valid_multiple_play(player, cards, state):
+            raise IllegalActionError("Invalid multiple play")
+
+    idx = state.current_player_index
+    updated = player.remove_cards(cards)
+    played_pile = state.played_pile + tuple(cards)
+
+    same_rank_remaining = any(c.rank == cards[-1].rank for c in updated.hand)
+    chaining = (
+        (
+            (state.top_card is not None and state.top_card.rank == cards[0].rank)
+            or cards[-1].rank == Rank.EIGHT
+        )
+        and _same_rank(cards)
+        and same_rank_remaining
+    )
+
+    updated = replace(
+        updated,
+        has_drawn_this_turn=False,
+        is_chaining=chaining,
+    )
+
+    new_state = _replace_player(state, idx, updated)
+    new_state = replace(
+        new_state,
+        top_card=cards[-1],
+        played_pile=played_pile,
+        last_play_count=len(cards),
+        ace_effect_active=False,
+        required_suit=None,
+        choose_suit=False,
+    )
+
+    new_state = _apply_special_card(new_state, cards[-1], chosen_suit, idx)
+
+    if not updated.hand:
+        active = [p for p in new_state.players if not p.is_excluded]
+        if len(active) == 2 and cards[-1].rank == Rank.QUEEN:
+            bank, drawn = _draw_from_bank(new_state.bank, new_state.played_pile, 1)
+            updated = updated.add_cards(drawn)
+            updated = replace(updated, has_drawn_this_turn=True, is_chaining=False)
+            new_state = _replace_player(new_state, idx, updated)
+            new_state = replace(new_state, bank=bank, played_pile=new_state.played_pile)
+            return _next_player(new_state, drawn=True)
+
+        return replace(
+            new_state,
+            phase=RoundPhase.ENDED,
+            round_winner_id=player.player_id,
+        )
+
+    if not updated.is_chaining and not new_state.choose_suit:
+        return _next_player(new_state)
+    return new_state
+
+
+def _handle_draw(state: RoundState, player: PlayerState) -> RoundState:
+    idx = state.current_player_index
+    if player.has_drawn_this_turn:
+        return _next_player(state)
+
+    count = 2 if state.ace_effect_active else 1
+    bank, played_pile = state.bank, state.played_pile
+    bank, played_pile, drawn = _draw_with_refill(bank, played_pile, count)
+
+    updated = player.add_cards(drawn)
+    new_state = replace(
+        _replace_player(state, idx, updated),
+        bank=bank,
+        played_pile=played_pile,
+        last_play_count=0,
+    )
+
+    if state.ace_effect_active:
+        new_state = replace(new_state, ace_effect_active=False)
+        return _next_player(new_state)
+
+    updated = replace(updated, has_drawn_this_turn=True)
+    new_state = _replace_player(new_state, idx, updated)
+
+    if new_state.bank_size == 0 and not new_state.played_pile:
+        new_state = replace(new_state, top_card=None, required_suit=None)
+    return new_state
+
+
+def _handle_pass(state: RoundState, player: PlayerState) -> RoundState:
+    if not (player.has_drawn_this_turn or player.is_chaining):
+        raise IllegalActionError("Must draw before passing")
+    return _next_player(state)
+
+
+def _handle_choose_suit(state: RoundState, player: PlayerState, suit) -> RoundState:
+    idx = state.current_player_index
+    updated = replace(player, is_chaining=False)
+    new_state = _replace_player(state, idx, updated)
+    new_state = replace(
+        new_state,
+        required_suit=suit,
+        choose_suit=False,
+    )
+    return _next_player(new_state)
+
+
+def _apply_special_card(state: RoundState, card, chosen_suit, player_idx: int):
+    if card.rank == Rank.EIGHT:
+        if chosen_suit is not None:
+            return replace(
+                state,
+                required_suit=chosen_suit,
+                choose_suit=False,
+            )
+        return replace(state, choose_suit=True)
+    if card.rank == Rank.ACE:
+        return replace(state, ace_effect_active=True)
+    if card.rank == Rank.QUEEN:
+        return replace(state, skip_next_player=True)
+    return state
+
+
+def _next_player(state: RoundState, *, drawn: bool = False) -> RoundState:
+    idx = state.current_player_index
+    current = state.players[idx]
+    current = replace(current, has_drawn_this_turn=drawn, is_chaining=False)
+    state = _replace_player(state, idx, current)
+    state = replace(state, choose_suit=False)
+
+    n = len(state.players)
+    next_idx = (idx + 1) % n
+    while state.players[next_idx].is_excluded:
+        next_idx = (next_idx + 1) % n
+
+    if state.skip_next_player:
+        next_idx = (next_idx + 1) % n
+        while state.players[next_idx].is_excluded:
+            next_idx = (next_idx + 1) % n
+        state = replace(state, skip_next_player=False)
+
+    return replace(state, current_player_index=next_idx)
+
+
+def _draw_with_refill(
+    bank: tuple,
+    played_pile: tuple,
+    count: int,
+) -> tuple[tuple, tuple, list]:
+    bank_list = list(bank)
+    pile = list(played_pile)
+    if len(bank_list) < count and pile:
+        bank_list.extend(pile)
+        pile = []
+    drawn: list = []
+    for _ in range(count):
+        if not bank_list:
+            break
+        drawn.append(bank_list.pop(0))
+    return tuple(bank_list), tuple(pile), drawn
+
+
+def _draw_from_bank(bank: tuple, played_pile: tuple, count: int) -> tuple[tuple, list]:
+    bank, pile, drawn = _draw_with_refill(bank, played_pile, count)
+    return bank, drawn
+
+
+def _replace_player(state: RoundState, index: int, player: PlayerState) -> RoundState:
+    players = list(state.players)
+    players[index] = player
+    return state.with_players(tuple(players))
+
+
+def _same_rank(cards: list) -> bool:
+    return all(c.rank == cards[0].rank for c in cards)

i151_engine/core/rules.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from i151_engine.models.card import Card, Rank
+from i151_engine.models.player import PlayerState
+
+if TYPE_CHECKING:
+    from i151_engine.game.round_state import RoundState
+
+
+def hand_score(hand: list[Card] | tuple[Card, ...]) -> int:
+    return sum(card.points for card in hand)
+
+
+def _same_rank_cards(cards: list[Card] | tuple[Card, ...]) -> bool:
+    if not cards:
+        return False
+    first = cards[0].rank
+    return all(card.rank == first for card in cards)
+
+
+def is_valid_single_play(player: PlayerState, card: Card, state: RoundState) -> bool:
+    if card not in player.hand:
+        return False
+    if player.is_chaining and state.top_card is not None and card.rank != state.top_card.rank:
+        return False
+    if state.top_card is not None and card.rank != Rank.EIGHT:
+        if not card.can_play_on_with_required_suit(state.top_card, state.required_suit):
+            return False
+    return True
+
+
+def is_valid_multiple_play(
+    player: PlayerState,
+    cards: list[Card] | tuple[Card, ...],
+    state: RoundState,
+) -> bool:
+    if not cards or len(cards) > 8:
+        return False
+
+    for card in cards:
+        if card not in player.hand:
+            return False
+
+    if player.is_chaining and (
+        state.top_card is None
+        or cards[0].rank != state.top_card.rank
+        or not _same_rank_cards(cards)
+    ):
+        return False
+
+    if not cards[0].can_play_on_with_required_suit(state.top_card, state.required_suit):
+        return False
+
+    active_count = sum(1 for p in state.players if not p.is_excluded)
+    if active_count == 2 and cards[0].rank == Rank.QUEEN:
+        last_queen_index = max(i for i, c in enumerate(cards) if c.rank == Rank.QUEEN)
+        if not all(cards[i].rank == Rank.QUEEN for i in range(last_queen_index + 1)):
+            return False
+        if last_queen_index == len(cards) - 1:
+            return True
+        next_card = cards[last_queen_index + 1]
+        if next_card.rank == Rank.EIGHT:
+            return all(c.rank == Rank.EIGHT for c in cards[last_queen_index + 1 :])
+        if next_card is not cards[-1]:
+            return False
+        return cards[-1].can_play_on(cards[last_queen_index])
+
+    if not _same_rank_cards(cards):
+        return False
+
+    if state.top_card is not None and cards[0].rank != Rank.EIGHT:
+        for card in cards:
+            if not card.can_play_on_with_required_suit(state.top_card, state.required_suit):
+                return False
+
+    if state.top_card is None and len(cards) > 1:
+        if any(card.rank != Rank.EIGHT for card in cards):
+            return False
+
+    return True
+
+
+def recent_table_cards(played_pile: tuple[Card, ...], *, limit: int = 3) -> tuple[Card, ...]:
+    return played_pile[-limit:]
+
+
+def last_play_cards(played_pile: tuple[Card, ...], last_play_count: int) -> tuple[Card, ...]:
+    """Cartes posées par la dernière action (multi-jeu inclus, max 4 en pratique)."""
+    if last_play_count <= 0 or not played_pile:
+        return ()
+    return played_pile[-last_play_count:]

i151_engine/core/scoring.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from i151_engine.core.rules import hand_score
+from i151_engine.game.round_state import RoundState
+from i151_engine.models.enums import MatchStatus, RoundPhase
+from i151_engine.models.player import PlayerState
+
+
+@dataclass(frozen=True)
+class MatchState:
+    status: MatchStatus
+    players: tuple[PlayerState, ...]
+    round_number: int
+    dealer_index: int
+    target_score: int
+    last_winner_id: str | None
+    winner_id: str | None
+    current_round: RoundState | None
+    seed: int
+    cards_per_player: int = 8
+
+    def player_by_id(self, player_id: str) -> PlayerState:
+        for player in self.players:
+            if player.player_id == player_id:
+                return player
+        raise KeyError(player_id)
+
+    def replace_players(self, players: tuple[PlayerState, ...]) -> MatchState:
+        from dataclasses import replace
+
+        return replace(self, players=players)
+
+
+def apply_round_scoring(match: MatchState, winner_id: str) -> MatchState:
+    """Apply hand scores to losers and consecutive-win bonus to winner."""
+    round_state = match.current_round
+    if round_state is None:
+        raise ValueError("Fin de manche sans état de manche")
+
+    meta = {p.player_id: p for p in match.players}
+    players_list: list[PlayerState] = []
+    for round_player in round_state.players:
+        match_player = meta[round_player.player_id]
+        players_list.append(
+            PlayerState(
+                player_id=round_player.player_id,
+                name=match_player.name,
+                hand=round_player.hand,
+                total_score=match_player.total_score,
+                is_excluded=match_player.is_excluded,
+                has_drawn_this_turn=False,
+                is_chaining=False,
+                consecutive_round_wins=match_player.consecutive_round_wins,
+            )
+        )
+
+    winner_idx = next(i for i, p in enumerate(players_list) if p.player_id == winner_id)
+    winner = players_list[winner_idx]
+
+    for i, player in enumerate(players_list):
+        if player.player_id == winner_id:
+            continue
+        new_score = player.total_score + hand_score(player.hand)
+        players_list[i] = PlayerState(
+            player_id=player.player_id,
+            name=player.name,
+            hand=player.hand,
+            total_score=new_score,
+            is_excluded=player.is_excluded or new_score >= match.target_score,
+            has_drawn_this_turn=False,
+            is_chaining=False,
+            consecutive_round_wins=player.consecutive_round_wins,
+        )
+
+    winner, last_winner_id = _track_consecutive_wins(
+        winner,
+        match.last_winner_id,
+    )
+    players_list[winner_idx] = winner
+
+    active = [p for p in players_list if not p.is_excluded]
+    if len(active) <= 1:
+        winner_id_final = active[0].player_id if active else None
+        return MatchState(
+            status=MatchStatus.FINISHED,
+            players=tuple(players_list),
+            round_number=match.round_number,
+            dealer_index=match.dealer_index,
+            target_score=match.target_score,
+            last_winner_id=last_winner_id,
+            winner_id=winner_id_final,
+            current_round=None,
+            seed=match.seed,
+        )
+
+    dealer_index, _ = _next_dealer_and_starter(players_list, match.dealer_index)
+    return MatchState(
+        status=MatchStatus.IN_PROGRESS,
+        players=tuple(players_list),
+        round_number=match.round_number + 1,
+        dealer_index=dealer_index,
+        target_score=match.target_score,
+        last_winner_id=last_winner_id,
+        winner_id=None,
+        current_round=None,
+        seed=match.seed,
+    )
+
+
+def _track_consecutive_wins(
+    winner: PlayerState,
+    last_winner_id: str | None,
+) -> tuple[PlayerState, str]:
+    winner_id = winner.player_id
+    consecutive = winner.consecutive_round_wins
+    total_score = winner.total_score
+
+    if last_winner_id == winner_id:
+        consecutive += 1
+        if consecutive == 3:
+            total_score -= 10
+            consecutive = 0
+    else:
+        consecutive = 1
+
+    updated = PlayerState(
+        player_id=winner.player_id,
+        name=winner.name,
+        hand=winner.hand,
+        total_score=total_score,
+        is_excluded=winner.is_excluded,
+        has_drawn_this_turn=False,
+        is_chaining=False,
+        consecutive_round_wins=consecutive,
+    )
+    return updated, winner_id
+
+
+def _next_dealer_and_starter(
+    players: list[PlayerState],
+    current_dealer: int,
+) -> tuple[int, int]:
+    n = len(players)
+    dealer_index = (current_dealer + 1) % n
+    while players[dealer_index].is_excluded:
+        dealer_index = (dealer_index + 1) % n
+    starter_index = (dealer_index + 1) % n
+    while players[starter_index].is_excluded:
+        starter_index = (starter_index + 1) % n
+    return dealer_index, starter_index