mini_arcade_core.scenes.systems.builtins.grid
=============================================

.. py:module:: mini_arcade_core.scenes.systems.builtins.grid

.. autoapi-nested-parse::

   Reusable grid/discrete-step gameplay helpers.



Classes
-------

.. autoapisummary::

   mini_arcade_core.scenes.systems.builtins.grid.GridCoord
   mini_arcade_core.scenes.systems.builtins.grid.GridBounds
   mini_arcade_core.scenes.systems.builtins.grid.GridLayout
   mini_arcade_core.scenes.systems.builtins.grid.CadenceState
   mini_arcade_core.scenes.systems.builtins.grid.CadenceBinding
   mini_arcade_core.scenes.systems.builtins.grid.CadenceSystem
   mini_arcade_core.scenes.systems.builtins.grid.GridCellSpawnBinding
   mini_arcade_core.scenes.systems.builtins.grid.GridCellSpawnSystem


Functions
---------

.. autoapisummary::

   mini_arcade_core.scenes.systems.builtins.grid.occupied_grid_cells
   mini_arcade_core.scenes.systems.builtins.grid.free_grid_cells
   mini_arcade_core.scenes.systems.builtins.grid.choose_first_grid_cell


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

.. py:class:: GridCoord

   One integer grid cell coordinate.


   .. py:attribute:: col
      :type:  int


   .. py:attribute:: row
      :type:  int


   .. py:method:: translated(*, dcol: int = 0, drow: int = 0) -> GridCoord

      Return a new cell translated by integer deltas.



.. py:class:: GridBounds

   Rectangular grid bounds measured in cells.


   .. py:attribute:: cols
      :type:  int


   .. py:attribute:: rows
      :type:  int


   .. py:method:: contains(coord: GridCoord) -> bool

      Return whether a cell lies inside this grid.



   .. py:method:: iter_cells() -> tuple[GridCoord, Ellipsis]

      Return every cell inside the bounds in row-major order.



.. py:class:: GridLayout

   World-space layout for a rectangular cell grid.


   .. py:attribute:: bounds
      :type:  GridBounds


   .. py:attribute:: cell_width
      :type:  float


   .. py:attribute:: cell_height
      :type:  float


   .. py:attribute:: origin_x
      :type:  float
      :value: 0.0



   .. py:attribute:: origin_y
      :type:  float
      :value: 0.0



   .. py:method:: cell_origin(coord: GridCoord) -> tuple[float, float]

      Return the top-left world coordinate for a grid cell.



   .. py:method:: cell_center(coord: GridCoord) -> tuple[float, float]

      Return the center world coordinate for a grid cell.



   .. py:method:: cell_rect(coord: GridCoord) -> tuple[float, float, float, float]

      Return a world-space rect tuple `(x, y, w, h)` for a grid cell.



   .. py:method:: contains(coord: GridCoord) -> bool

      Delegate containment checks to bounds.



.. py:function:: occupied_grid_cells(values: Iterable[object], *, coord_getter: Callable[[object], GridCoord | None], include: Callable[[object], bool] | None = None) -> set[GridCoord]

   Collect occupied cells from arbitrary values.


.. py:function:: free_grid_cells(bounds: GridBounds, occupied: Iterable[GridCoord]) -> tuple[GridCoord, Ellipsis]

   Return free cells inside `bounds` after subtracting occupied cells.


.. py:function:: choose_first_grid_cell(_ctx: object, cells: tuple[GridCoord, Ellipsis]) -> GridCoord | None

   Deterministic default cell chooser.


.. py:class:: CadenceState

   Mutable state for fixed-interval gameplay stepping.


   .. py:attribute:: accumulator
      :type:  float
      :value: 0.0



   .. py:attribute:: tick_count
      :type:  int
      :value: 0



   .. py:attribute:: steps_this_frame
      :type:  int
      :value: 0



.. py:class:: CadenceBinding

   Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ]


   Declarative fixed-cadence simulation rule.


   .. py:attribute:: state_getter
      :type:  Callable[[TCtx], CadenceState]


   .. py:attribute:: interval_seconds
      :type:  float


   .. py:attribute:: on_tick
      :type:  Callable[[TCtx], None]


   .. py:attribute:: enabled_when
      :type:  Callable[[TCtx], bool]


   .. py:attribute:: max_steps_per_frame
      :type:  int
      :value: 4



.. py:class:: CadenceSystem

   Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ]


   Execute one or more fixed-timestep callbacks from variable frame dt.


   .. py:attribute:: name
      :type:  str
      :value: 'common_cadence'



   .. py:attribute:: phase
      :type:  int


   .. py:attribute:: order
      :type:  int
      :value: 20



   .. py:attribute:: enabled_when
      :type:  Callable[[TCtx], bool]


   .. py:attribute:: bindings
      :type:  tuple[CadenceBinding[TCtx], Ellipsis]
      :value: ()



   .. py:method:: step(ctx: TCtx) -> None

      Advance cadence timers and fire callbacks when they elapse.



.. py:class:: GridCellSpawnBinding

   Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ]


   Declarative spawn rule that chooses one currently free cell in a grid.


   .. py:attribute:: should_spawn
      :type:  Callable[[TCtx], bool]


   .. py:attribute:: bounds_getter
      :type:  Callable[[TCtx], GridBounds]


   .. py:attribute:: occupied_cells_getter
      :type:  Callable[[TCtx], Iterable[GridCoord]]


   .. py:attribute:: spawn
      :type:  Callable[[TCtx, GridCoord], SpawnResult]


   .. py:attribute:: choose_cell
      :type:  Callable[[TCtx, tuple[GridCoord, Ellipsis]], GridCoord | None]


   .. py:attribute:: on_spawned
      :type:  Callable[[TCtx, tuple[mini_arcade_core.engine.entities.BaseEntity, Ellipsis], GridCoord], None] | None
      :value: None



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



.. py:class:: GridCellSpawnSystem

   Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ]


   Spawn entities into currently free grid cells.


   .. py:attribute:: name
      :type:  str
      :value: 'common_grid_spawn'



   .. py:attribute:: phase
      :type:  int


   .. py:attribute:: order
      :type:  int
      :value: 25



   .. py:attribute:: enabled_when
      :type:  Callable[[TCtx], bool]


   .. py:attribute:: bindings
      :type:  tuple[GridCellSpawnBinding[TCtx], Ellipsis]
      :value: ()



   .. py:method:: step(ctx: TCtx) -> None

      Spawn entities into the first available grid cell per binding.