larvaworld.lib.reg.keymap
=========================

.. py:module:: larvaworld.lib.reg.keymap

.. autoapi-nested-parse::

   Keymap/shortcuts for interactive pygame visualization of simulations.



Classes
-------

.. autoapisummary::

   larvaworld.lib.reg.keymap.ControlRegistry


Functions
---------

.. autoapisummary::

   larvaworld.lib.reg.keymap.default_controls
   larvaworld.lib.reg.keymap.build_pygame_keys
   larvaworld.lib.reg.keymap.merge_controls
   larvaworld.lib.reg.keymap.validate_key_name
   larvaworld.lib.reg.keymap.validate_shortcut_conf


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

.. py:function:: default_controls() -> larvaworld.lib.util.AttrDict

   Return a fresh controls configuration without filesystem writes.


.. py:function:: build_pygame_keys(keys: dict[str, dict[str, str]]) -> dict[str, str]

   Build flattened action -> pygame key mapping from nested shortcut keys.


.. py:function:: merge_controls(defaults: dict[str, Any], overrides: dict[str, Any]) -> larvaworld.lib.util.AttrDict

   Merge workspace overrides over defaults and rebuild derived pygame keys.


.. py:function:: validate_key_name(key: str) -> bool

   Return True when key name is supported by the V1a shortcut editor.


.. py:function:: validate_shortcut_conf(keys: dict[str, dict[str, str]]) -> list[str]

   Validate shortcut keys and return a list of human-readable errors.


.. py:class:: ControlRegistry

   Registry for keyboard and mouse controls in pygame visualizations.

   Manages keyboard shortcuts and mouse controls for interactive simulation
   visualization. Controls are saved to and loaded from a configuration file.

   Attributes:
       path: Path to the controls configuration file
       conf: AttrDict containing control mappings with sections:
           - keys: Keyboard shortcuts organized by category
           - mouse: Mouse control mappings
           - pygame_keys: Pygame key constant mappings

   Example:
       >>> controls = ControlRegistry()
       >>> controls.conf.keys['draw']['visible_trails']  # 'p'
       >>> controls.conf.mouse['select item']  # 'left click'
       >>> controls.save()  # Save current configuration
       >>> loaded = controls.load()  # Load from file


   .. py:attribute:: path
      :value: 'Uninferable/lib/reg/confDicts/controls.txt'



   .. py:attribute:: conf


   .. py:method:: save(conf: larvaworld.lib.util.AttrDict | None = None) -> None


   .. py:method:: load() -> larvaworld.lib.util.AttrDict