mini_arcade_core.utils
======================

.. py:module:: mini_arcade_core.utils

.. autoapi-nested-parse::

   Mini Arcade Core Utilities Package



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/mini_arcade_core/utils/assets/index
   /autoapi/mini_arcade_core/utils/deprecated_decorator/index
   /autoapi/mini_arcade_core/utils/logging/index
   /autoapi/mini_arcade_core/utils/profiler/index


Attributes
----------

.. autoapisummary::

   mini_arcade_core.utils.logger


Classes
-------

.. autoapisummary::

   mini_arcade_core.utils.FrameTimer


Functions
---------

.. autoapisummary::

   mini_arcade_core.utils.find_assets_root
   mini_arcade_core.utils.deprecated


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

.. py:function:: find_assets_root(anchor: str) -> pathlib.Path

   Find an `assets` directory by walking upward from an anchor file path.

   :param anchor: File path used as the search starting point.
   :type anchor: str
   :raises FileNotFoundError: If assets directory cannot be found.


.. py:function:: deprecated(reason: str | None = None, version: str | None = None, alternative: str | None = None)

   Mark a function as deprecated.

   :param reason: Optional reason for deprecation
   :type reason: str | None

   :param version: Optional version when it will be removed
   :type version: str | None

   :param alternative: Optional alternative function to use
   :type alternative: str | None


.. py:data:: logger

.. py:class:: FrameTimer

   Simple frame timer for marking and reporting time intervals.

   :ivar config (FrameTimerConfig): Configuration for the timer.
   :ivar formatter (FrameTimingFormatter): Formatter for timing reports.
   :ivar marks (Dict[str, float]): Recorded time marks.


   .. py:attribute:: config
      :type:  FrameTimerConfig


   .. py:attribute:: formatter
      :type:  FrameTimingFormatter


   .. py:attribute:: marks
      :type:  Dict[str, float]


   .. py:method:: clear()

      Clear all recorded marks.



   .. py:method:: mark(name: str)

      Record a time mark with the given name.

      :param name: Name of the mark.
      :type name: str



   .. py:method:: report_ms() -> Dict[str, float]

      Returns diffs between consecutive marks in insertion order.

      :return: Dictionary mapping "start->end" to time difference in milliseconds.
      :rtype: Dict[str, float]



   .. py:method:: should_report(frame_index: int) -> bool

      Determine if a report should be emitted for the given frame index.

      :param frame_index: Current frame index.
      :type frame_index: int
      :return: True if a report should be emitted, False otherwise.
      :rtype: bool



   .. py:method:: emit(frame_index: int)

      Emit a timing report to the performance logger.

      :param frame_index: Current frame index.
      :type frame_index: int