mini_arcade_core.scenes.systems.builtins.maze¶

Reusable maze and lane-based grid gameplay helpers.

Classes¶

`CardinalDirection`	Four-way grid direction.
`TileMap`	Dense grid of maze/tile values.
`GridNavigatorState`	Mutable cell-based movement state for one maze agent.
`GridNavigationBinding`	Declarative lane/junction navigation rule.
`GridNavigationSystem`	Advance one or more maze agents through a tile map with turn buffering.
`TunnelWrapBinding`	Declarative horizontal/vertical wrap rule for maze agents.
`TunnelWrapSystem`	Wrap maze agents across configured grid edges.
`CollectibleKind`	Common collectible kinds for maze games.
`CollectibleState`	Mutable collectible metadata stored inside a field.
`CollectibleField`	Dense collectible state keyed by grid cell.
`CollectibleCollisionBinding`	Declarative collectible pickup rule.
`CollectibleCollisionSystem`	Consume collectibles when a collector enters the same cell.
`TimedMode`	One timed gameplay mode segment.
`ModeTimerState`	Mutable state for timed mode progression.
`ModeTimerBinding`	Declarative timed mode schedule.
`ModeTimerSystem`	Advance timed mode schedules using the current frame dt.

Functions¶

`step_in_direction`(...)	Return the adjacent cell in the given direction.
`tile_map_from_strings`(→ TileMap[TCell])	Build a tile map from ASCII rows and a legend.
`available_directions`(→ tuple[CardinalDirection, Ellipsis])	Return the cardinal exits available from one cell.
`choose_direction_toward`(→ CardinalDirection \| None)	Choose the exit that minimizes Manhattan distance to a target cell.
`choose_direction_away`(→ CardinalDirection \| None)	Choose the exit that maximizes Manhattan distance from a target cell.
`choose_random_direction`(→ CardinalDirection \| None)	Choose one valid exit randomly.
`is_junction`(→ bool)	Return whether a cell exposes more than two valid exits.

Module Contents¶

class mini_arcade_core.scenes.systems.builtins.maze.CardinalDirection[source]¶

Bases: str, enum.Enum

Four-way grid direction.

UP = 'up'¶

DOWN = 'down'¶

LEFT = 'left'¶

RIGHT = 'right'¶

property vector: tuple[int, int]¶: Return the (dcol, drow) vector for this direction.

property opposite: CardinalDirection¶: Return the opposite cardinal direction.

mini_arcade_core.scenes.systems.builtins.maze.step_in_direction(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, direction: CardinalDirection) → mini_arcade_core.scenes.systems.builtins.grid.GridCoord[source]¶: Return the adjacent cell in the given direction.

class mini_arcade_core.scenes.systems.builtins.maze.TileMap[source]¶

Bases: Generic[TCell]

Dense grid of maze/tile values.

bounds: mini_arcade_core.scenes.systems.builtins.grid.GridBounds¶

default: TCell | None = None¶

__post_init__() → None[source]¶

contains(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) → bool[source]¶: Return whether a coordinate falls inside the tile-map bounds.

get(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) → TCell | None[source]¶: Return the stored tile value at one coordinate, if in bounds.

set(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, value: TCell | None) → None[source]¶: Store a tile value at one coordinate.

iter_cells() → tuple[tuple[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, TCell | None], Ellipsis][source]¶: Return all cells with their stored values.

mini_arcade_core.scenes.systems.builtins.maze.tile_map_from_strings(*rows: str, legend: Mapping[str, TCell], default: TCell | None = None) → TileMap[TCell][source]¶: Build a tile map from ASCII rows and a legend.

mini_arcade_core.scenes.systems.builtins.maze.available_directions(tile_map: TileMap[TCell], coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, *, can_enter: Callable[[TCell | None], bool]) → tuple[CardinalDirection, Ellipsis][source]¶: Return the cardinal exits available from one cell.

mini_arcade_core.scenes.systems.builtins.maze.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[source]¶: Choose the exit that minimizes Manhattan distance to a target cell.

mini_arcade_core.scenes.systems.builtins.maze.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[source]¶: Choose the exit that maximizes Manhattan distance from a target cell.

mini_arcade_core.scenes.systems.builtins.maze.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[source]¶: Choose one valid exit randomly.

mini_arcade_core.scenes.systems.builtins.maze.is_junction(tile_map: TileMap[TCell], coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, *, can_enter: Callable[[TCell | None], bool]) → bool[source]¶: Return whether a cell exposes more than two valid exits.

class mini_arcade_core.scenes.systems.builtins.maze.GridNavigatorState[source]¶

Mutable cell-based movement state for one maze agent.

cell: mini_arcade_core.scenes.systems.builtins.grid.GridCoord¶

direction: CardinalDirection¶

pending_direction: CardinalDirection | None = None¶

moved_this_frame: int = 0¶

class mini_arcade_core.scenes.systems.builtins.maze.GridNavigationBinding[source]¶

Bases: Generic[TCtx, TCell]

Declarative lane/junction navigation rule.

state_getter: Callable[[TCtx], GridNavigatorState]¶

tile_map_getter: Callable[[TCtx], TileMap[TCell]]¶

desired_direction_getter: Callable[[TCtx], CardinalDirection | None]¶

can_enter: Callable[[TCell | None], bool]¶

on_cell_entered: Callable[[TCtx, mini_arcade_core.scenes.systems.builtins.grid.GridCoord], None] | None = None¶

allow_reverse: bool = True¶

steps_getter: Callable[[TCtx], int]¶

class mini_arcade_core.scenes.systems.builtins.maze.GridNavigationSystem[source]¶

Bases: Generic[TCtx, TCell]

Advance one or more maze agents through a tile map with turn buffering.

name: str = 'common_grid_navigation'¶

phase: int¶

order: int = 30¶

enabled_when: Callable[[TCtx], bool]¶

bindings: tuple[GridNavigationBinding[TCtx, TCell], Ellipsis] = ()¶

step(ctx: TCtx) → None[source]¶: Advance bound navigators through the tile map with turn buffering.

class mini_arcade_core.scenes.systems.builtins.maze.TunnelWrapBinding[source]¶

Bases: Generic[TCtx]

Declarative horizontal/vertical wrap rule for maze agents.

states_getter: Callable[[TCtx], Iterable[GridNavigatorState]]¶

bounds_getter: Callable[[TCtx], mini_arcade_core.scenes.systems.builtins.grid.GridBounds]¶

wrap_horizontal: bool = True¶

wrap_vertical: bool = False¶

class mini_arcade_core.scenes.systems.builtins.maze.TunnelWrapSystem[source]¶

Bases: Generic[TCtx]

Wrap maze agents across configured grid edges.

name: str = 'common_tunnel_wrap'¶

phase: int¶

order: int = 31¶

enabled_when: Callable[[TCtx], bool]¶

bindings: tuple[TunnelWrapBinding[TCtx], Ellipsis] = ()¶

step(ctx: TCtx) → None[source]¶: Wrap navigator states across configured map edges.

class mini_arcade_core.scenes.systems.builtins.maze.CollectibleKind[source]¶

Bases: str, enum.Enum

Common collectible kinds for maze games.

PELLET = 'pellet'¶

POWER = 'power'¶

BONUS = 'bonus'¶

class mini_arcade_core.scenes.systems.builtins.maze.CollectibleState[source]¶

Mutable collectible metadata stored inside a field.

kind: CollectibleKind¶

payload: Any = None¶

class mini_arcade_core.scenes.systems.builtins.maze.CollectibleField[source]¶

Dense collectible state keyed by grid cell.

items: dict[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, CollectibleState]¶

item_at(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) → CollectibleState | None[source]¶: Return the collectible stored at one cell, if any.

occupied_cells() → tuple[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, Ellipsis][source]¶: Return the cells that currently contain collectibles.

remove(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) → CollectibleState | None[source]¶: Remove and return the collectible stored at one cell.

class mini_arcade_core.scenes.systems.builtins.maze.CollectibleCollisionBinding[source]¶

Bases: Generic[TCtx]

Declarative collectible pickup rule.

collector_cell_getter: Callable[[TCtx], mini_arcade_core.scenes.systems.builtins.grid.GridCoord]¶

field_getter: Callable[[TCtx], CollectibleField | None]¶

on_collect: Callable[[TCtx, mini_arcade_core.scenes.systems.builtins.grid.GridCoord, CollectibleState], None] | None = None¶

class mini_arcade_core.scenes.systems.builtins.maze.CollectibleCollisionSystem[source]¶

Bases: Generic[TCtx]

Consume collectibles when a collector enters the same cell.

name: str = 'common_collectible_collision'¶

phase: int¶

order: int = 35¶

enabled_when: Callable[[TCtx], bool]¶

bindings: tuple[CollectibleCollisionBinding[TCtx], Ellipsis] = ()¶

step(ctx: TCtx) → None[source]¶: Consume collectibles that share a cell with the collector.

class mini_arcade_core.scenes.systems.builtins.maze.TimedMode[source]¶

One timed gameplay mode segment.

name: str¶

duration_seconds: float | None¶

payload: Any = None¶

class mini_arcade_core.scenes.systems.builtins.maze.ModeTimerState[source]¶

Mutable state for timed mode progression.

mode_index: int = 0¶

elapsed_in_mode: float = 0.0¶

current_mode: str = ''¶

class mini_arcade_core.scenes.systems.builtins.maze.ModeTimerBinding[source]¶

Bases: Generic[TCtx]

Declarative timed mode schedule.

state_getter: Callable[[TCtx], ModeTimerState]¶

schedule: tuple[TimedMode, Ellipsis]¶

on_mode_changed: Callable[[TCtx, TimedMode], None] | None = None¶

loop: bool = False¶

class mini_arcade_core.scenes.systems.builtins.maze.ModeTimerSystem[source]¶

Bases: Generic[TCtx]

Advance timed mode schedules using the current frame dt.

name: str = 'common_mode_timer'¶

phase: int¶

order: int = 15¶

enabled_when: Callable[[TCtx], bool]¶

bindings: tuple[ModeTimerBinding[TCtx], Ellipsis] = ()¶

step(ctx: TCtx) → None[source]¶: Advance scheduled timed modes using the current frame delta.