mundane.engine.cards
====================

.. py:module:: mundane.engine.cards

.. autoapi-nested-parse::

   The effect vocabulary (the fixed set of behaviours) and the JSON-card loader.

   This is the ONLY place effect functions live. A JSON card names an effect from :data:`EFFECTS` and
   supplies ``params``; it cannot define new behaviour. :func:`build_card` composes the namespaced id
   ``set_id:id`` and binds the named effect's ``params`` into a closure. The hardcoded ``CARD_LIBRARY``
   is gone: card *content* now lives in JSON sets (see ``mundane-cards``), fetched and validated by the
   API, while card *behaviour* stays here as code.



Attributes
----------

.. autoapisummary::

   mundane.engine.cards.EffectFactory
   mundane.engine.cards.EFFECTS


Exceptions
----------

.. autoapisummary::

   mundane.engine.cards.UnknownEffectError
   mundane.engine.cards.InvalidEffectParamsError
   mundane.engine.cards.DuplicateCardError


Functions
---------

.. autoapisummary::

   mundane.engine.cards._require_int_param
   mundane.engine.cards.damage_composure
   mundane.engine.cards.counter_task
   mundane.engine.cards.none
   mundane.engine.cards.build_card
   mundane.engine.cards.build_pool


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

.. py:exception:: UnknownEffectError

   Bases: :py:obj:`Exception`


   A JSON card names an effect that is not in the :data:`EFFECTS` vocabulary.


.. py:exception:: InvalidEffectParamsError

   Bases: :py:obj:`Exception`


   A JSON card's ``params`` are missing or the wrong type for its named effect.


.. py:exception:: DuplicateCardError

   Bases: :py:obj:`Exception`


   Two cards resolved to the same composed id.


.. py:type:: EffectFactory
   :canonical: Callable[[Mapping[str, object]], Effect]


   Takes a card's ``params`` and returns a bound :data:`~mundane.engine.state.Effect` closure.

.. py:function:: _require_int_param(params: collections.abc.Mapping[str, object], key: str) -> int

   Return ``params[key]`` as an int, or reject the card with :class:`InvalidEffectParamsError`.


.. py:function:: damage_composure(params: collections.abc.Mapping[str, object]) -> mundane.engine.state.Effect

   Return an effect that deals ``params['amount']`` chaos to the opponent's Composure.


.. py:function:: counter_task(_params: collections.abc.Mapping[str, object]) -> mundane.engine.state.Effect

   Return an effect that counters a task on the stack (the old Noise Complaint). No params.


.. py:function:: none(_params: collections.abc.Mapping[str, object]) -> mundane.engine.state.Effect

   Return a no-op effect. Permanents name this so that every JSON card names an effect.


.. py:data:: EFFECTS
   :type:  dict[str, EffectFactory]

   name -> factory. The engine is the sole authority on what's valid.

   :type: The fixed effect vocabulary

.. py:function:: build_card(set_id: str, card_dict: collections.abc.Mapping[str, object]) -> mundane.engine.state.Card

   Build one :class:`Card` from a (schema-validated) JSON card dict in set ``set_id``.

   Composes the namespaced id ``set_id:id``, looks the ``effect`` name up in :data:`EFFECTS`
   (raising :class:`UnknownEffectError` if absent), and binds ``params`` into the effect closure
   (the factory raises :class:`InvalidEffectParamsError` on bad params).


.. py:function:: build_pool(set_dict: collections.abc.Mapping[str, object]) -> dict[str, mundane.engine.state.Card]

   Build ``{composed_id: Card}`` from one parsed set dict (offline; used by tests and the demo).

   The API's ``set_loader`` does the same across multiple fetched sets; this is the pure, no-I/O
   helper for a single already-parsed set. Raises :class:`DuplicateCardError` on a repeated id.