mini_arcade_core.scenes.systems.builtins.maze ============================================= .. py:module:: mini_arcade_core.scenes.systems.builtins.maze .. autoapi-nested-parse:: Reusable maze and lane-based grid gameplay helpers. Classes ------- .. autoapisummary:: mini_arcade_core.scenes.systems.builtins.maze.CardinalDirection mini_arcade_core.scenes.systems.builtins.maze.TileMap mini_arcade_core.scenes.systems.builtins.maze.GridNavigatorState mini_arcade_core.scenes.systems.builtins.maze.GridNavigationBinding mini_arcade_core.scenes.systems.builtins.maze.GridNavigationSystem mini_arcade_core.scenes.systems.builtins.maze.TunnelWrapBinding mini_arcade_core.scenes.systems.builtins.maze.TunnelWrapSystem mini_arcade_core.scenes.systems.builtins.maze.CollectibleKind mini_arcade_core.scenes.systems.builtins.maze.CollectibleState mini_arcade_core.scenes.systems.builtins.maze.CollectibleField mini_arcade_core.scenes.systems.builtins.maze.CollectibleCollisionBinding mini_arcade_core.scenes.systems.builtins.maze.CollectibleCollisionSystem mini_arcade_core.scenes.systems.builtins.maze.TimedMode mini_arcade_core.scenes.systems.builtins.maze.ModeTimerState mini_arcade_core.scenes.systems.builtins.maze.ModeTimerBinding mini_arcade_core.scenes.systems.builtins.maze.ModeTimerSystem Functions --------- .. autoapisummary:: mini_arcade_core.scenes.systems.builtins.maze.step_in_direction mini_arcade_core.scenes.systems.builtins.maze.tile_map_from_strings mini_arcade_core.scenes.systems.builtins.maze.available_directions mini_arcade_core.scenes.systems.builtins.maze.choose_direction_toward mini_arcade_core.scenes.systems.builtins.maze.choose_direction_away mini_arcade_core.scenes.systems.builtins.maze.choose_random_direction mini_arcade_core.scenes.systems.builtins.maze.is_junction Module Contents --------------- .. py:class:: CardinalDirection Bases: :py:obj:`str`, :py:obj:`enum.Enum` Four-way grid direction. .. py:attribute:: UP :value: 'up' .. py:attribute:: DOWN :value: 'down' .. py:attribute:: LEFT :value: 'left' .. py:attribute:: RIGHT :value: 'right' .. py:property:: vector :type: tuple[int, int] Return the `(dcol, drow)` vector for this direction. .. py:property:: opposite :type: CardinalDirection Return the opposite cardinal direction. .. py:function:: step_in_direction(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, direction: CardinalDirection) -> mini_arcade_core.scenes.systems.builtins.grid.GridCoord Return the adjacent cell in the given direction. .. py:class:: TileMap Bases: :py:obj:`Generic`\ [\ :py:obj:`TCell`\ ] Dense grid of maze/tile values. .. py:attribute:: bounds :type: mini_arcade_core.scenes.systems.builtins.grid.GridBounds .. py:attribute:: default :type: TCell | None :value: None .. py:method:: __post_init__() -> None .. py:method:: contains(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) -> bool Return whether a coordinate falls inside the tile-map bounds. .. py:method:: get(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) -> TCell | None Return the stored tile value at one coordinate, if in bounds. .. py:method:: set(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, value: TCell | None) -> None Store a tile value at one coordinate. .. py:method:: iter_cells() -> tuple[tuple[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, TCell | None], Ellipsis] Return all cells with their stored values. .. py:function:: tile_map_from_strings(*rows: str, legend: Mapping[str, TCell], default: TCell | None = None) -> TileMap[TCell] Build a tile map from ASCII rows and a legend. .. py:function:: available_directions(tile_map: TileMap[TCell], coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, *, can_enter: Callable[[TCell | None], bool]) -> tuple[CardinalDirection, Ellipsis] Return the cardinal exits available from one cell. .. py:function:: choose_direction_toward(tile_map: TileMap[TCell], coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, target: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, *, can_enter: Callable[[TCell | None], bool], current_direction: CardinalDirection | None = None, allow_reverse: bool = False) -> CardinalDirection | None Choose the exit that minimizes Manhattan distance to a target cell. .. py:function:: choose_direction_away(tile_map: TileMap[TCell], coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, target: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, *, can_enter: Callable[[TCell | None], bool], current_direction: CardinalDirection | None = None, allow_reverse: bool = False) -> CardinalDirection | None Choose the exit that maximizes Manhattan distance from a target cell. .. py:function:: choose_random_direction(tile_map: TileMap[TCell], coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, *, can_enter: Callable[[TCell | None], bool], rng: random.Random | None = None, current_direction: CardinalDirection | None = None, allow_reverse: bool = False) -> CardinalDirection | None Choose one valid exit randomly. .. py:function:: is_junction(tile_map: TileMap[TCell], coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, *, can_enter: Callable[[TCell | None], bool]) -> bool Return whether a cell exposes more than two valid exits. .. py:class:: GridNavigatorState Mutable cell-based movement state for one maze agent. .. py:attribute:: cell :type: mini_arcade_core.scenes.systems.builtins.grid.GridCoord .. py:attribute:: direction :type: CardinalDirection .. py:attribute:: pending_direction :type: CardinalDirection | None :value: None .. py:attribute:: moved_this_frame :type: int :value: 0 .. py:class:: GridNavigationBinding Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ , :py:obj:`TCell`\ ] Declarative lane/junction navigation rule. .. py:attribute:: state_getter :type: Callable[[TCtx], GridNavigatorState] .. py:attribute:: tile_map_getter :type: Callable[[TCtx], TileMap[TCell]] .. py:attribute:: desired_direction_getter :type: Callable[[TCtx], CardinalDirection | None] .. py:attribute:: can_enter :type: Callable[[TCell | None], bool] .. py:attribute:: on_cell_entered :type: Callable[[TCtx, mini_arcade_core.scenes.systems.builtins.grid.GridCoord], None] | None :value: None .. py:attribute:: allow_reverse :type: bool :value: True .. py:attribute:: steps_getter :type: Callable[[TCtx], int] .. py:class:: GridNavigationSystem Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ , :py:obj:`TCell`\ ] Advance one or more maze agents through a tile map with turn buffering. .. py:attribute:: name :type: str :value: 'common_grid_navigation' .. py:attribute:: phase :type: int .. py:attribute:: order :type: int :value: 30 .. py:attribute:: enabled_when :type: Callable[[TCtx], bool] .. py:attribute:: bindings :type: tuple[GridNavigationBinding[TCtx, TCell], Ellipsis] :value: () .. py:method:: step(ctx: TCtx) -> None Advance bound navigators through the tile map with turn buffering. .. py:class:: TunnelWrapBinding Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ] Declarative horizontal/vertical wrap rule for maze agents. .. py:attribute:: states_getter :type: Callable[[TCtx], Iterable[GridNavigatorState]] .. py:attribute:: bounds_getter :type: Callable[[TCtx], mini_arcade_core.scenes.systems.builtins.grid.GridBounds] .. py:attribute:: wrap_horizontal :type: bool :value: True .. py:attribute:: wrap_vertical :type: bool :value: False .. py:class:: TunnelWrapSystem Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ] Wrap maze agents across configured grid edges. .. py:attribute:: name :type: str :value: 'common_tunnel_wrap' .. py:attribute:: phase :type: int .. py:attribute:: order :type: int :value: 31 .. py:attribute:: enabled_when :type: Callable[[TCtx], bool] .. py:attribute:: bindings :type: tuple[TunnelWrapBinding[TCtx], Ellipsis] :value: () .. py:method:: step(ctx: TCtx) -> None Wrap navigator states across configured map edges. .. py:class:: CollectibleKind Bases: :py:obj:`str`, :py:obj:`enum.Enum` Common collectible kinds for maze games. .. py:attribute:: PELLET :value: 'pellet' .. py:attribute:: POWER :value: 'power' .. py:attribute:: BONUS :value: 'bonus' .. py:class:: CollectibleState Mutable collectible metadata stored inside a field. .. py:attribute:: kind :type: CollectibleKind .. py:attribute:: payload :type: Any :value: None .. py:class:: CollectibleField Dense collectible state keyed by grid cell. .. py:attribute:: items :type: dict[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, CollectibleState] .. py:method:: item_at(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) -> CollectibleState | None Return the collectible stored at one cell, if any. .. py:method:: occupied_cells() -> tuple[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, Ellipsis] Return the cells that currently contain collectibles. .. py:method:: remove(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) -> CollectibleState | None Remove and return the collectible stored at one cell. .. py:class:: CollectibleCollisionBinding Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ] Declarative collectible pickup rule. .. py:attribute:: collector_cell_getter :type: Callable[[TCtx], mini_arcade_core.scenes.systems.builtins.grid.GridCoord] .. py:attribute:: field_getter :type: Callable[[TCtx], CollectibleField | None] .. py:attribute:: on_collect :type: Callable[[TCtx, mini_arcade_core.scenes.systems.builtins.grid.GridCoord, CollectibleState], None] | None :value: None .. py:class:: CollectibleCollisionSystem Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ] Consume collectibles when a collector enters the same cell. .. py:attribute:: name :type: str :value: 'common_collectible_collision' .. py:attribute:: phase :type: int .. py:attribute:: order :type: int :value: 35 .. py:attribute:: enabled_when :type: Callable[[TCtx], bool] .. py:attribute:: bindings :type: tuple[CollectibleCollisionBinding[TCtx], Ellipsis] :value: () .. py:method:: step(ctx: TCtx) -> None Consume collectibles that share a cell with the collector. .. py:class:: TimedMode One timed gameplay mode segment. .. py:attribute:: name :type: str .. py:attribute:: duration_seconds :type: float | None .. py:attribute:: payload :type: Any :value: None .. py:class:: ModeTimerState Mutable state for timed mode progression. .. py:attribute:: mode_index :type: int :value: 0 .. py:attribute:: elapsed_in_mode :type: float :value: 0.0 .. py:attribute:: current_mode :type: str :value: '' .. py:class:: ModeTimerBinding Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ] Declarative timed mode schedule. .. py:attribute:: state_getter :type: Callable[[TCtx], ModeTimerState] .. py:attribute:: schedule :type: tuple[TimedMode, Ellipsis] .. py:attribute:: on_mode_changed :type: Callable[[TCtx, TimedMode], None] | None :value: None .. py:attribute:: loop :type: bool :value: False .. py:class:: ModeTimerSystem Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ] Advance timed mode schedules using the current frame dt. .. py:attribute:: name :type: str :value: 'common_mode_timer' .. py:attribute:: phase :type: int .. py:attribute:: order :type: int :value: 15 .. py:attribute:: enabled_when :type: Callable[[TCtx], bool] .. py:attribute:: bindings :type: tuple[ModeTimerBinding[TCtx], Ellipsis] :value: () .. py:method:: step(ctx: TCtx) -> None Advance scheduled timed modes using the current frame delta.