mundane.engine.rules
====================

.. py:module:: mundane.engine.rules

.. autoapi-nested-parse::

   The one door: ``apply_action(state, action)`` validates a move, then transitions.

   Every state change in the game goes through here. Each branch runs its ``_require`` preconditions
   first (which raise :class:`IllegalAction` on a bad move, mutating nothing) and only then mutates.
   The function returns the state so it composes as a reducer:
   ``final = reduce(partial(apply_action, cards=pool), actions, initial)``.



Functions
---------

.. autoapisummary::

   mundane.engine.rules._require
   mundane.engine.rules.apply_action
   mundane.engine.rules._push_stack
   mundane.engine.rules._grant_priority_after_stack_change
   mundane.engine.rules._resolve_top
   mundane.engine.rules._advance_phase
   mundane.engine.rules._end_turn
   mundane.engine.rules._check_win


Module Contents
---------------

.. py:function:: _require(condition: bool, message: str) -> None

   Reject the action with ``IllegalAction(message)`` when ``condition`` is false.


.. py:function:: apply_action(state: mundane.engine.state.GameState, action: mundane.engine.actions.Action, cards: dict[str, mundane.engine.state.Card]) -> mundane.engine.state.GameState

   Validate ``action`` against ``state``, then transition. Returns ``state``.


.. py:function:: _push_stack(state: mundane.engine.state.GameState, card_id: str, controller: int, target_id: int | None = None) -> None

   Put a card on the stack with a fresh id, then hand priority back to the active player.


.. py:function:: _grant_priority_after_stack_change(state: mundane.engine.state.GameState) -> None

   After anything goes on the stack, the active player gets priority and the pass count resets.


.. py:function:: _resolve_top(state: mundane.engine.state.GameState, cards: dict[str, mundane.engine.state.Card]) -> None

   Resolve the top stack item (LIFO): permanents hit the board, others fire then go to discard.


.. py:function:: _advance_phase(state: mundane.engine.state.GameState) -> None

   Move to the next phase, or end the turn after the last phase.


.. py:function:: _end_turn(state: mundane.engine.state.GameState) -> None

   Hand the turn to the next player and run Wake Up housekeeping (refresh Time, draw).


.. py:function:: _check_win(state: mundane.engine.state.GameState) -> None

   Set the winner if any player's Composure has dropped to 0.