# Falling Blocks Internals

Mini Arcade now includes a small core toolkit for stacking puzzle and
falling-block games.

This layer is meant for Tetris-like prototypes and other games built around:

- a dense board
- active falling pieces
- row clearing
- deterministic piece sequencing

## What lives in core

Core built-ins:

- `BlockBoard`
- `FallingBlockPieceSpec`
- `FallingBlockPiece`
- `block_cells_from_strings(...)`
- `piece_fits(...)`
- `BagRandomizer`
- `BoardRowClearBinding`
- `BoardRowClearSystem`

Source module:

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

## `BlockBoard`

`BlockBoard` is a dense visible board model with:

- fixed `cols` and `rows`
- cell get/set/clear
- filled-row queries
- occupied-cell iteration
- collision checks for candidate piece cells
- row collapse after clears

This is intentionally board-state only. It does not own scoring, piece queues,
hold rules, wall kicks, or rendering.

## Piece specs and active pieces

`FallingBlockPieceSpec` stores the precomputed rotation states for one piece.

`FallingBlockPiece` stores:

- piece/spec id
- board origin
- current rotation index

Together they provide:

- translated piece copies
- rotated piece copies
- occupied board cells for the active piece

`block_cells_from_strings(...)` is a small authoring helper for defining
rotations from ASCII rows instead of manually writing `GridCoord(...)` tuples.

## `piece_fits(...)`

`piece_fits(...)` checks whether a piece can occupy a board without:

- crossing horizontal bounds
- falling below the board
- colliding with settled cells

It also supports `allow_rows_above_board=True`, which is useful for spawn logic
where a piece can begin partially above the visible board.

## `BagRandomizer`

`BagRandomizer` is a deterministic bag-based sequence helper.

It is useful for:

- 7-bag piece sequencing
- deterministic tests
- predictable replays when the game stores the seed

This lives in core because it is a reusable gameplay primitive, not a Tetris UI
feature.

## `BoardRowClearSystem`

`BoardRowClearSystem` clears fully occupied rows and collapses the board
downward.

A binding:

- resolves the board from scene/world state
- optionally gates whether row clearing is active
- can react to cleared rows through `on_cleared(...)`

That callback is where a concrete game would update:

- score
- combo state
- sound triggers
- animation requests

## What is intentionally not in core

Core does not include a full Tetris ruleset.

Still game-specific:

- scoring tables
- level/speed progression
- hold piece rules
- next queue presentation
- ghost piece visuals
- DAS/ARR tuning
- lock delay
- wall-kick tables and rotation systems

Those should sit in game code on top of the generic falling-block primitives.