mini_arcade_core.scenes.systems.builtins.falling_blocks

Reusable falling-block gameplay helpers for stacking puzzle games.

Classes

BlockBoard	Dense visible board state for stacking puzzle games.
FallingBlockPieceSpec	One falling-piece definition with precomputed rotation states.
FallingBlockPiece	Active falling piece instance positioned on a board grid.
BagRandomizer	Deterministic bag-based sequence generator.
BoardRowClearBinding	Declarative row-clear rule for one falling-block board.
BoardRowClearSystem	Clear fully occupied rows and collapse the board downward.

Functions

block_cells_from_strings(...)	Parse one rotation from ASCII rows into local grid cells.
piece_fits(→ bool)	Return whether an active piece fits on a board without collisions.

Module Contents

mini_arcade_core.scenes.systems.builtins.falling_blocks.block_cells_from_strings(*rows: str, filled_chars: str = '#XO@[]') → tuple[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, Ellipsis]

Parse one rotation from ASCII rows into local grid cells.

class mini_arcade_core.scenes.systems.builtins.falling_blocks.BlockBoard

Bases: Generic[TCell]

Dense visible board state for stacking puzzle games.

cols: int

rows: int

empty: TCell | None = None

__post_init__() → None

in_bounds(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) → bool

Return whether a cell lies inside the visible board.

get(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) → TCell | None

Return the stored value for a visible cell.

set(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, value: TCell | None) → None

Write a value into a visible cell.

clear(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) → None

Reset one visible cell to the configured empty value.

row_values(row: int) → tuple[TCell | None, Ellipsis]

Return one row as an immutable tuple.

row_is_filled(row: int) → bool

Return whether a row contains no empty cells.

filled_rows() → tuple[int, Ellipsis]

Return the indexes of completely filled rows.

occupied_cells() → tuple[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, Ellipsis]

Return the coordinates of all non-empty cells.

occupied_entries() → tuple[tuple[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, TCell], Ellipsis]

Return coordinates paired with stored cell values.

can_place(cells: Iterable[mini_arcade_core.scenes.systems.builtins.grid.GridCoord], *, allow_rows_above_board: bool = False) → bool

Return whether the given cells can be occupied without collisions.

stamp(cells: Iterable[mini_arcade_core.scenes.systems.builtins.grid.GridCoord], *, value: TCell, ignore_rows_above_board: bool = True) → tuple[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, Ellipsis]

Write one value into multiple cells and return written coordinates.

collapse_rows(rows: Iterable[int]) → tuple[int, Ellipsis]

Remove filled rows and shift higher rows downward.

class mini_arcade_core.scenes.systems.builtins.falling_blocks.FallingBlockPieceSpec

One falling-piece definition with precomputed rotation states.

name: str

rotations: tuple[tuple[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, Ellipsis], Ellipsis]

__post_init__() → None

cells(rotation: int = 0) → tuple[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, Ellipsis]

Return the local cells for the normalized rotation index.

class mini_arcade_core.scenes.systems.builtins.falling_blocks.FallingBlockPiece

Active falling piece instance positioned on a board grid.

spec_name: str

origin: mini_arcade_core.scenes.systems.builtins.grid.GridCoord

rotation: int = 0

translated(*, dcol: int = 0, drow: int = 0) → FallingBlockPiece

Return a translated copy of the active piece.

rotated(delta: int = 1) → FallingBlockPiece

Return a copy rotated by a relative delta.

cells(spec: FallingBlockPieceSpec) → tuple[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, Ellipsis]

Return the occupied board cells for this active piece.

mini_arcade_core.scenes.systems.builtins.falling_blocks.piece_fits(board: BlockBoard[TCell], piece: FallingBlockPiece, spec: FallingBlockPieceSpec, *, allow_rows_above_board: bool = False) → bool

Return whether an active piece fits on a board without collisions.

class mini_arcade_core.scenes.systems.builtins.falling_blocks.BagRandomizer

Bases: Generic[TItem]

Deterministic bag-based sequence generator.

items: tuple[TItem, Ellipsis]

seed: int = 1

__post_init__() → None

refill() → tuple[TItem, Ellipsis]

Refill and shuffle the current bag.

next() → TItem

Draw the next item, refilling the bag as needed.

peek() → tuple[TItem, Ellipsis]

Return the remaining contents of the current bag.

class mini_arcade_core.scenes.systems.builtins.falling_blocks.BoardRowClearBinding

Bases: Generic[TCtx]

Declarative row-clear rule for one falling-block board.

board_getter: Callable[[TCtx], BlockBoard[object]]

enabled_when: Callable[[TCtx], bool]

on_cleared: Callable[[TCtx, tuple[int, Ellipsis]], None] | None = None

class mini_arcade_core.scenes.systems.builtins.falling_blocks.BoardRowClearSystem

Bases: Generic[TCtx]

Clear fully occupied rows and collapse the board downward.

name: str = 'common_board_row_clear'

phase: int

order: int = 70

enabled_when: Callable[[TCtx], bool]

bindings: tuple[BoardRowClearBinding[TCtx], Ellipsis] = ()

step(ctx: TCtx) → None

Collapse filled rows for each configured board and emit callbacks.