mini_arcade_core.scenes.systems.builtins.grid

Reusable grid/discrete-step gameplay helpers.

Classes

GridCoord	One integer grid cell coordinate.
GridBounds	Rectangular grid bounds measured in cells.
GridLayout	World-space layout for a rectangular cell grid.
CadenceState	Mutable state for fixed-interval gameplay stepping.
CadenceBinding	Declarative fixed-cadence simulation rule.
CadenceSystem	Execute one or more fixed-timestep callbacks from variable frame dt.
GridCellSpawnBinding	Declarative spawn rule that chooses one currently free cell in a grid.
GridCellSpawnSystem	Spawn entities into currently free grid cells.

Functions

occupied_grid_cells(→ set[GridCoord])	Collect occupied cells from arbitrary values.
free_grid_cells(→ tuple[GridCoord, Ellipsis])	Return free cells inside bounds after subtracting occupied cells.
choose_first_grid_cell(→ GridCoord | None)	Deterministic default cell chooser.

Module Contents

class mini_arcade_core.scenes.systems.builtins.grid.GridCoord

One integer grid cell coordinate.

col: int

row: int

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

Return a new cell translated by integer deltas.

class mini_arcade_core.scenes.systems.builtins.grid.GridBounds

Rectangular grid bounds measured in cells.

cols: int

rows: int

contains(coord: GridCoord) → bool

Return whether a cell lies inside this grid.

iter_cells() → tuple[GridCoord, Ellipsis]

Return every cell inside the bounds in row-major order.

class mini_arcade_core.scenes.systems.builtins.grid.GridLayout

World-space layout for a rectangular cell grid.

bounds: GridBounds

cell_width: float

cell_height: float

origin_x: float = 0.0

origin_y: float = 0.0

cell_origin(coord: GridCoord) → tuple[float, float]

Return the top-left world coordinate for a grid cell.

cell_center(coord: GridCoord) → tuple[float, float]

Return the center world coordinate for a grid cell.

cell_rect(coord: GridCoord) → tuple[float, float, float, float]

Return a world-space rect tuple (x, y, w, h) for a grid cell.

contains(coord: GridCoord) → bool

Delegate containment checks to bounds.

mini_arcade_core.scenes.systems.builtins.grid.occupied_grid_cells(values: Iterable[object], *, coord_getter: Callable[[object], GridCoord | None], include: Callable[[object], bool] | None = None) → set[GridCoord]

Collect occupied cells from arbitrary values.

mini_arcade_core.scenes.systems.builtins.grid.free_grid_cells(bounds: GridBounds, occupied: Iterable[GridCoord]) → tuple[GridCoord, Ellipsis]

Return free cells inside bounds after subtracting occupied cells.

mini_arcade_core.scenes.systems.builtins.grid.choose_first_grid_cell(_ctx: object, cells: tuple[GridCoord, Ellipsis]) → GridCoord | None

Deterministic default cell chooser.

class mini_arcade_core.scenes.systems.builtins.grid.CadenceState

Mutable state for fixed-interval gameplay stepping.

accumulator: float = 0.0

tick_count: int = 0

steps_this_frame: int = 0

class mini_arcade_core.scenes.systems.builtins.grid.CadenceBinding

Bases: Generic[TCtx]

Declarative fixed-cadence simulation rule.

state_getter: Callable[[TCtx], CadenceState]

interval_seconds: float

on_tick: Callable[[TCtx], None]

enabled_when: Callable[[TCtx], bool]

max_steps_per_frame: int = 4

class mini_arcade_core.scenes.systems.builtins.grid.CadenceSystem

Bases: Generic[TCtx]

Execute one or more fixed-timestep callbacks from variable frame dt.

name: str = 'common_cadence'

phase: int

order: int = 20

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Advance cadence timers and fire callbacks when they elapse.

class mini_arcade_core.scenes.systems.builtins.grid.GridCellSpawnBinding

Bases: Generic[TCtx]

Declarative spawn rule that chooses one currently free cell in a grid.

should_spawn: Callable[[TCtx], bool]

bounds_getter: Callable[[TCtx], GridBounds]

occupied_cells_getter: Callable[[TCtx], Iterable[GridCoord]]

spawn: Callable[[TCtx, GridCoord], SpawnResult]

choose_cell: Callable[[TCtx, tuple[GridCoord, Ellipsis]], GridCoord | None]

on_spawned: Callable[[TCtx, tuple[mini_arcade_core.engine.entities.BaseEntity, Ellipsis], GridCoord], None] | None = None

insert_into_world: bool = True

class mini_arcade_core.scenes.systems.builtins.grid.GridCellSpawnSystem

Bases: Generic[TCtx]

Spawn entities into currently free grid cells.

name: str = 'common_grid_spawn'

phase: int

order: int = 25

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Spawn entities into the first available grid cell per binding.