mini_arcade.modules.settings
============================

.. py:module:: mini_arcade.modules.settings

.. autoapi-nested-parse::

   Settings module for mini-arcade.

   Example settings files can be found under `examples/settings/` in the monorepo, and
   are loaded automatically when running examples using
   `mini-arcade run --example <example_id>`.

   ```python
       print("Loaded settings:")
       shared = Settings(SettingsArgs(scope="example", required=False))
       print(shared.as_dict())
       engine_config_basics = Settings(
           SettingsArgs(
               scope="example",
               name="config/engine_config_basics",
               required=False,
           )
       )
       print(engine_config_basics.as_dict())
       backend_swap = Settings(
           SettingsArgs(
               scope="example",
               name="config/backend_swap",
               required=False,
           )
       )
       print(backend_swap.as_dict())
       s_asteroids = Settings(
           SettingsArgs(scope="game", name="asteroids", required=False)
       )
       print(s_asteroids.as_dict())
       s_space = Settings(
           SettingsArgs(scope="game", name="space-invaders", required=False)
       )
       print(s_space.as_dict())
       s_deja = Settings(
           SettingsArgs(scope="game", name="deja-bounce", required=False)
       )
       print(s_deja.as_dict())
   ```



Attributes
----------

.. autoapisummary::

   mini_arcade.modules.settings.settings


Classes
-------

.. autoapisummary::

   mini_arcade.modules.settings.SettingsArgs
   mini_arcade.modules.settings.Settings


Package Contents
----------------

.. py:class:: SettingsArgs

   Arguments for loading settings.


   .. py:attribute:: config_path
      :type:  str | pathlib.Path | None
      :value: None



   .. py:attribute:: scope
      :type:  str | None
      :value: None



   .. py:attribute:: name
      :type:  str | None
      :value: None



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



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



.. py:class:: Settings(args: SettingsArgs | None = None, **kwargs: Any)

   Settings reader with optional profile scoping.

   Supported sources:
   - explicit config_path
   - MINI_ARCADE_CONFIG_PATH env var
   - monorepo game-local settings under `games/<game_id>/settings/`
   - monorepo example settings under `examples/settings/`
   - repo-level defaults under `settings/settings.yml|yaml`

   Profile convention under monorepo root:
   - games: `games/<game_id>/settings/settings.yml|yaml`
   - examples: `examples/settings/<example_id>.yml|yaml`
   - shared examples: `examples/settings/settings.yml|yaml`
   - default: `settings/settings.yml|yaml`


   .. py:method:: for_game(game_id: str, *, required: bool = False, force_reload: bool = False) -> Settings
      :classmethod:


      Load settings profile for one game.



   .. py:method:: for_example(example_id: str | None = None, *, required: bool = False, force_reload: bool = False) -> Settings
      :classmethod:


      Load settings profile for one example.

      If example_id is None, loads shared example settings profile.



   .. py:property:: config_path
      :type: pathlib.Path | None


      Path to currently loaded settings file.


   .. py:method:: get(key_: str, default: Any = None) -> Any

      Get nested key using dot notation.



   .. py:method:: section(key_: str) -> dict[str, Any]

      Return one section as dict.



   .. py:method:: project_root() -> pathlib.Path

      Resolve project root for this settings profile.

      Priority:
      1) project.root / paths.project_root key in yaml
      2) inferred from scope/name:
         - game -> <repo>/games/<game_id>
         - example -> <repo>/examples/catalog/<example_id>
      3) repo root
      4) cwd



   .. py:method:: assets_root() -> pathlib.Path

      Resolve assets root for this settings profile.



   .. py:method:: resolve_path(path_value: str | pathlib.Path, *, default_to_cwd: bool = False) -> pathlib.Path

      Resolve one path using token/env expansion and project-root defaults.

      Supported placeholders:
      - ${repo_root}
      - ${project_root}
      - ${assets_root}
      - ${settings_dir}
      - ${cwd}



   .. py:method:: resolve_asset_path(path_value: str | pathlib.Path) -> pathlib.Path

      Resolve one asset path relative to assets root when not absolute.



   .. py:method:: engine_config_defaults() -> dict[str, Any]

      Engine settings defaults aligned to
      `mini_arcade_core.engine.game_config.EngineConfig`.



   .. py:method:: scene_defaults() -> dict[str, Any]

      Scene bootstrap defaults aligned to
      `mini_arcade_core.engine.game_config.SceneConfig`.



   .. py:method:: gameplay_defaults() -> dict[str, Any]

      Gameplay settings defaults consumed by runtime gameplay settings.



   .. py:method:: backend_defaults(*, resolve_paths: bool = False) -> dict[str, Any]

      Backend settings defaults for backend-specific settings builders.



   .. py:method:: as_dict() -> dict[str, Any]

      Return full settings dictionary.



.. py:data:: settings