# Grid Gameplay Internals

Mini Arcade now includes a small core toolkit for discrete, cell-based games.

This layer is meant for games like Snake, Pac-Man-style prototypes, board games,
or any gameplay loop that advances in fixed cell steps instead of continuous
float motion.

## What lives in core

Core built-ins:

- `CadenceState`
- `CadenceBinding`
- `CadenceSystem`
- `GridCoord`
- `GridBounds`
- `GridLayout`
- `occupied_grid_cells(...)`
- `free_grid_cells(...)`
- `GridCellSpawnBinding`
- `GridCellSpawnSystem`

Source module:

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

## `CadenceSystem`

`CadenceSystem` is the fixed-step helper for gameplay that should advance on a
logical interval rather than every render frame.

Typical use:

- snake movement every `0.12s`
- board/turn simulation every `0.20s`
- timed hazard pulses every `0.50s`

Each binding owns a mutable `CadenceState` in the world:

- `accumulator`: leftover frame time
- `tick_count`: total fixed ticks emitted
- `steps_this_frame`: how many fixed ticks ran this render frame

That lets a scene keep rendering at 60 FPS while the gameplay advances on a
slower logical cadence.

## Grid coordinates and layout

`GridCoord` is an integer `(col, row)` pair.

`GridBounds` defines the playable cell rectangle:

- containment checks
- iteration over every cell

`GridLayout` converts logical cells into world-space positions:

- `cell_origin(...)`
- `cell_center(...)`
- `cell_rect(...)`

This keeps rendering and gameplay separate:

- gameplay works in cells
- rendering works in pixels / virtual coordinates

## Occupancy helpers

`occupied_grid_cells(...)` collects blocked cells from arbitrary scene values.

`free_grid_cells(...)` returns all non-occupied cells inside a `GridBounds`.

These helpers are intentionally simple and data-oriented. They do not assume an
entity model or a specific game rule.

## `GridCellSpawnSystem`

`GridCellSpawnSystem` is the grid equivalent of the generic spawn helpers.

A binding:

- decides whether spawning should happen now
- provides current bounds
- provides occupied cells
- chooses one free cell
- builds one or more entities for that cell

This is useful for:

- food pickup spawning
- bonus item placement
- trap placement
- deterministic board setup

By default, the system uses `choose_first_grid_cell(...)`, but callers can pass
their own chooser for random or weighted placement.

## What is intentionally not in core

Core does not include Snake-specific rules such as:

- buffered direction changes
- instant reverse-turn rejection
- score/length rules
- tail-follow rules
- self-collision semantics

Those belong in game systems built on top of the generic grid primitives above.