# Maze Gameplay Internals

Mini Arcade now includes a small core toolkit for maze and lane-based arcade
games.

This layer is meant for Pac-Man style prototypes and other games built around:

- tile or maze boards
- four-way lane movement
- buffered turns at junctions
- tunnel wrapping
- collectible fields
- timed gameplay modes

## What lives in core

Core built-ins:

- `CardinalDirection`
- `TileMap`
- `tile_map_from_strings(...)`
- `available_directions(...)`
- `is_junction(...)`
- `GridNavigatorState`
- `GridNavigationBinding`
- `GridNavigationSystem`
- `TunnelWrapBinding`
- `TunnelWrapSystem`
- `CollectibleKind`
- `CollectibleState`
- `CollectibleField`
- `CollectibleCollisionBinding`
- `CollectibleCollisionSystem`
- `TimedMode`
- `ModeTimerState`
- `ModeTimerBinding`
- `ModeTimerSystem`

Source module:

- `packages/mini-arcade-core/src/mini_arcade_core/scenes/systems/builtins/maze.py`

## Tile maps and junction queries

`TileMap` is a dense grid of maze values.

It supports:

- bounds-aware get/set
- iterating all cells
- typed values per cell

`tile_map_from_strings(...)` lets a game author a maze from ASCII rows plus a
legend instead of manually filling the board in code.

`available_directions(...)` and `is_junction(...)` are the reusable query layer
for lane navigation and AI choice logic.

## `GridNavigationSystem`

`GridNavigationSystem` advances one or more agents through a tile map while
supporting buffered direction changes.

Each `GridNavigatorState` stores:

- current cell
- current direction
- pending direction
- how many lane steps moved this frame

The navigation binding can:

- read a desired turn direction from input or AI
- decide whether a tile is enterable
- move multiple cell steps per frame if driven by a cadence/timer layer
- trigger `on_cell_entered(...)` callbacks

This is the core reusable part of Pac-Man style lane movement.

## `TunnelWrapSystem`

`TunnelWrapSystem` wraps navigators across configured grid edges.

Typical use:

- left tunnel exits to right tunnel
- optional vertical wrap for other maze games

This stays separate from `GridNavigationSystem` so games can choose when wrap is
allowed.

## Collectibles

`CollectibleField` stores collectible state by `GridCoord`.

`CollectibleCollisionSystem` removes collectibles when the collector enters the
same cell and emits an optional callback with:

- the collected cell
- the removed `CollectibleState`

That gives game code a clean place to update score, frightened mode, bonus
fruit, and sounds without hardcoding those rules in the field itself.

## Timed modes

`ModeTimerSystem` advances a schedule of `TimedMode` segments.

This is useful for mode-driven arcade gameplay such as:

- scatter
- chase
- frightened
- bonus windows

The system tracks:

- current mode index
- elapsed time in mode
- current mode name

and emits `on_mode_changed(...)` when the schedule advances.

## What is intentionally not in core

Core does not include a full Pac-Man ruleset.

Still game-specific:

- ghost personalities and targeting rules
- house release schedules
- score tables
- fruit rules
- frightened speed tuning
- cutscenes
- exact maze layouts and content

Those should live in game code on top of the reusable maze primitives above.