mundane.engine.state
====================

.. py:module:: mundane.engine.state

.. autoapi-nested-parse::

   Game-state dataclasses: the single source of truth for a Mundane game.

   Nothing in this module mutates state; :func:`mundane.engine.rules.apply_action` is the only
   thing that does. Cards are referenced **by id** throughout the state; card *objects* — built from
   JSON sets by :func:`mundane.engine.cards.build_card` — and the effect closures they carry live only
   in the per-game pool, never in serialisable state. That separation is what lets a whole
   :class:`GameState` round-trip through JSON.



Attributes
----------

.. autoapisummary::

   mundane.engine.state.Effect
   mundane.engine.state.PERMANENTS
   mundane.engine.state.PHASES


Classes
-------

.. autoapisummary::

   mundane.engine.state.CardType
   mundane.engine.state.Card
   mundane.engine.state.Player
   mundane.engine.state.StackItem
   mundane.engine.state.GameState


Functions
---------

.. autoapisummary::

   mundane.engine.state._no_effect


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

.. py:class:: CardType

   Bases: :py:obj:`enum.StrEnum`


   The five kinds of card. The first three are permanents (they stay on the board).


   .. py:attribute:: PERSON
      :value: 'person'



   .. py:attribute:: APPLIANCE
      :value: 'appliance'



   .. py:attribute:: HABIT
      :value: 'habit'



   .. py:attribute:: TASK
      :value: 'task'



   .. py:attribute:: INSTANT
      :value: 'instant'



.. py:type:: Effect
   :canonical: Callable[[GameState, StackItem], None]


   An effect mutates the state when its card resolves, given the resolving :class:`StackItem`.

.. py:function:: _no_effect(_state: GameState, _item: StackItem) -> None

   Do nothing. Permanents resolve onto the board, so they carry this placeholder effect.


.. py:class:: Card

   A card *definition*, built from a JSON set by :func:`mundane.engine.cards.build_card`.

   State refers to a card only by its composed ``id`` (``set_id:id``); the bound ``effect`` closure
   lives in the per-game pool, never in serialisable state.


   .. py:attribute:: id
      :type:  str


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: cost
      :type:  int


   .. py:attribute:: type
      :type:  CardType


   .. py:attribute:: effect
      :type:  Effect


   .. py:attribute:: text
      :type:  str
      :value: ''



   .. py:attribute:: flavor
      :type:  str
      :value: ''



.. py:data:: PERMANENTS

.. py:class:: Player

   One household. Card collections hold library ids (``str``), never Card objects.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: composure
      :type:  int
      :value: 20



   .. py:attribute:: time
      :type:  int
      :value: 0



   .. py:attribute:: hand
      :type:  list[str]
      :value: []



   .. py:attribute:: board
      :type:  list[str]
      :value: []



   .. py:attribute:: deck
      :type:  list[str]
      :value: []



   .. py:attribute:: discard
      :type:  list[str]
      :value: []



.. py:class:: StackItem

   A card waiting to resolve. ``id`` is unique within a game (see ``GameState.next_stack_id``).


   .. py:attribute:: card_id
      :type:  str


   .. py:attribute:: controller
      :type:  int


   .. py:attribute:: target_id
      :type:  int | None
      :value: None



   .. py:attribute:: id
      :type:  int
      :value: 0



.. py:data:: PHASES
   :value: ['RESET', 'WAKE_UP', 'PLAN', 'DO_STUFF', 'WIND_DOWN']


.. py:class:: GameState

   The entire game. Fully JSON-serialisable: every field is data, never code.


   .. py:attribute:: players
      :type:  list[Player]


   .. py:attribute:: active_player
      :type:  int
      :value: 0



   .. py:attribute:: priority_player
      :type:  int
      :value: 0



   .. py:attribute:: phase
      :type:  str
      :value: 'PLAN'



   .. py:attribute:: stack
      :type:  list[StackItem]
      :value: []



   .. py:attribute:: passes_in_a_row
      :type:  int
      :value: 0



   .. py:attribute:: turn
      :type:  int
      :value: 1



   .. py:attribute:: winner
      :type:  int | None
      :value: None



   .. py:attribute:: next_stack_id
      :type:  int
      :value: 1



   .. py:method:: next_player(i: int) -> int

      Return the index of the player after ``i`` (wraps around the table).



   .. py:method:: opponent(i: int) -> int

      Return the opponent of player ``i`` (2-player convenience).