mini_arcade_core.engine.cheats
==============================

.. py:module:: mini_arcade_core.engine.cheats

.. autoapi-nested-parse::

   Cheats module for Mini Arcade Core.
   Provides cheat codes and related functionality.



Attributes
----------

.. autoapisummary::

   mini_arcade_core.engine.cheats.TContext


Classes
-------

.. autoapisummary::

   mini_arcade_core.engine.cheats.CheatCode
   mini_arcade_core.engine.cheats.CheatManager


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

.. py:data:: TContext

.. py:class:: CheatCode

   Represents a registered cheat code.

   :ivar name (str): Unique name of the cheat code.
   :ivar sequence (tuple[str, ...]): Sequence of key strings that trigger the cheat.
   :ivar action (CheatAction): BaseCheatCommand to call when the cheat is activated.
   :ivar clear_buffer_on_match (bool): Whether to clear the input buffer after a match.
   :ivar enabled (bool): Whether the cheat code is enabled.


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


   .. py:attribute:: sequence
      :type:  tuple[str, Ellipsis]


   .. py:attribute:: command_factory
      :type:  Optional[Callable[[TContext], mini_arcade_core.engine.commands.Command]]
      :value: None



   .. py:attribute:: clear_buffer_on_match
      :type:  bool
      :value: False



   .. py:attribute:: enabled
      :type:  bool
      :value: True



.. py:class:: CheatManager

   Reusable cheat code matcher.
   Keeps a rolling buffer of recent keys and triggers callbacks on sequence match.


   .. py:attribute:: buffer_size
      :type:  int
      :value: 16



   .. py:attribute:: enabled
      :type:  bool
      :value: True



   .. py:method:: __post_init__()


   .. py:method:: register(name: str, *, sequence: Sequence[str], command_factory: Callable[[TContext], mini_arcade_core.engine.commands.Command], clear_buffer_on_match: bool = False, enabled: bool = True)

      Register a new cheat code.

      :param name: Unique name of the cheat code.
      :type name: str

      :param sequence: Sequence of key strings that trigger the cheat.
      :type sequence: Sequence[str]

      :param command_factory: Factory function to create the Command when the cheat is activated.
      :type command_factory: Callable[[TContext], Command]

      :param clear_buffer_on_match: Whether to clear the input buffer after a match.
      :type clear_buffer_on_match: bool

      :param enabled: Whether the cheat code is enabled.
      :type enabled: bool

      :raises ValueError: If name is empty or sequence is empty.



   .. py:method:: process_frame(input_frame: mini_arcade_core.runtime.input_frame.InputFrame, *, context: TContext, queue: mini_arcade_core.engine.commands.CommandQueue) -> list[str]

      Process an InputFrame for cheat code matches.

      :param input_frame: InputFrame containing current inputs.
      :type input_frame: InputFrame

      :param context: Context to pass to command factories.
      :type context: TContext

      :param queue: CommandQueue to push matched commands into.
      :type queue: CommandQueue

      :return: List of names of matched cheat codes.
      :rtype: list[str]



   .. py:method:: process_key(key: str, *, context: TContext, queue: mini_arcade_core.engine.commands.CommandQueue) -> list[str]

      Process a single key input.

      :param key: The key string to process.
      :type key: str

      :param context: Context to pass to command factories.
      :type context: TContext

      :param queue: CommandQueue to push matched commands into.
      :type queue: CommandQueue

      :return: List of names of matched cheat codes.
      :rtype: list[str]