mini_arcade_core.scenes.systems.builtins

Built-in systems for scenes.

Submodules

• mini_arcade_core.scenes.systems.builtins.actions
• mini_arcade_core.scenes.systems.builtins.animation
• mini_arcade_core.scenes.systems.builtins.bomberman
• mini_arcade_core.scenes.systems.builtins.brick_breaker
• mini_arcade_core.scenes.systems.builtins.capture_hotkeys
• mini_arcade_core.scenes.systems.builtins.falling_blocks
• mini_arcade_core.scenes.systems.builtins.grid
• mini_arcade_core.scenes.systems.builtins.intent_commands
• mini_arcade_core.scenes.systems.builtins.maze
• mini_arcade_core.scenes.systems.builtins.movement
• mini_arcade_core.scenes.systems.builtins.particles
• mini_arcade_core.scenes.systems.builtins.pause
• mini_arcade_core.scenes.systems.builtins.powerups
• mini_arcade_core.scenes.systems.builtins.projectiles
• mini_arcade_core.scenes.systems.builtins.score_chain
• mini_arcade_core.scenes.systems.builtins.spawn
• mini_arcade_core.scenes.systems.builtins.timers

Attributes

FIRE_ALPHA_RAMP
FIRE_COLOR_RAMP
FIRE_PARTICLE_PROFILE
MAGIC_ALPHA_RAMP
MAGIC_COLOR_RAMP
MAGIC_PARTICLE_PROFILE
POTION_ALPHA_RAMP
POTION_COLOR_RAMP
POTION_PARTICLE_PROFILE
SMOKE_ALPHA_RAMP
SMOKE_COLOR_RAMP
SMOKE_PARTICLE_PROFILE

Classes

ActionIntentSystem	Input system that converts an ActionMap snapshot into scene intent.
ActionMap	Mapping of action IDs to concrete binding strategies.
ActionSnapshot	Per-frame snapshot for all mapped actions.
AxisActionBinding	Axis action sourced from analog axes and optional digital fallbacks.
ConfiguredActionIntentSystem	Action-intent system configured directly from gameplay.controls settings.
DigitalActionBinding	Digital action sourced from keyboard and/or named buttons.
AnimationTickSystem	Step entity animations during presentation.
ArenaTile	Common arena tile kinds for bomb-based grid games.
BombField	Dense bomb occupancy keyed by cell.
BombFuseBinding	Declarative fuse ticking and detonation rule.
BombFuseSystem	Tick bomb fuses and emit detonation callbacks when they expire.
BombPlacementBinding	Declarative bomb placement rule.
BombPlacementSystem	Place bombs onto walkable floor cells when rules allow.
BombState	Mutable bomb metadata stored in a bomb field.
ChainReactionBinding	Declarative bomb chain-reaction rule.
ChainReactionSystem	Trigger bombs early when an active explosion reaches them.
DestructibleTileBinding	Declarative breakable-tile destruction rule.
DestructibleTileSystem	Destroy breakable tiles touched by active explosion cells.
ExplosionCellState	Mutable active explosion metadata for one cell.
ExplosionField	Dense active explosion occupancy keyed by cell.
ExplosionLifetimeBinding	Declarative active-explosion lifetime rule.
ExplosionLifetimeSystem	Tick active explosion cells until they expire.
HazardCollisionBinding	Declarative explosion hazard collision rule.
HazardCollisionSystem	Invoke callbacks for targets occupying active hazard cells.
BounceCollisionBinding	Declarative ball-vs-rect bounce rule.
BounceCollisionSystem	Reflect one moving rect from one or more target rects.
BounceHit	Resolved bounce collision information.
BrickField	Dense brick layout with per-cell hit points.
BrickFieldCollisionBinding	Declarative ball-vs-brick-field bounce and damage rule.
BrickFieldCollisionSystem	Reflect a ball-like entity from the first hit brick and damage the field.
BrickState	Mutable brick metadata stored inside a brick field.
PaddleBouncePolicy	Shape outgoing ball direction based on paddle contact point.
ViewportBounceBinding	Declarative viewport bounce rule for one or more ball-like entities.
ViewportBounceSystem	Reflect ball-like entities from selected viewport sides.
CaptureHotkey	One hotkey toggle configuration.
CaptureHotkeysConfig	Per-scene capture workflow configuration.
CaptureHotkeysSystem	Handles screenshot/replay/video commands in a reusable way.
SceneCaptureConfig	Scene-level capture controls configuration.
BagRandomizer	Deterministic bag-based sequence generator.
BlockBoard	Dense visible board state for stacking puzzle games.
BoardRowClearBinding	Declarative row-clear rule for one falling-block board.
BoardRowClearSystem	Clear fully occupied rows and collapse the board downward.
FallingBlockPiece	Active falling piece instance positioned on a board grid.
FallingBlockPieceSpec	One falling-piece definition with precomputed rotation states.
CadenceBinding	Declarative fixed-cadence simulation rule.
CadenceState	Mutable state for fixed-interval gameplay stepping.
CadenceSystem	Execute one or more fixed-timestep callbacks from variable frame dt.
GridBounds	Rectangular grid bounds measured in cells.
GridCellSpawnBinding	Declarative spawn rule that chooses one currently free cell in a grid.
GridCellSpawnSystem	Spawn entities into currently free grid cells.
GridCoord	One integer grid cell coordinate.
GridLayout	World-space layout for a rectangular cell grid.
IntentCommandSystem	Push commands when configured intent attributes are truthy for this tick.
CardinalDirection	Four-way grid direction.
CollectibleCollisionBinding	Declarative collectible pickup rule.
CollectibleCollisionSystem	Consume collectibles when a collector enters the same cell.
CollectibleField	Dense collectible state keyed by grid cell.
CollectibleKind	Common collectible kinds for maze games.
CollectibleState	Mutable collectible metadata stored inside a field.
GridNavigationBinding	Declarative lane/junction navigation rule.
GridNavigationSystem	Advance one or more maze agents through a tile map with turn buffering.
GridNavigatorState	Mutable cell-based movement state for one maze agent.
ModeTimerBinding	Declarative timed mode schedule.
ModeTimerState	Mutable state for timed mode progression.
ModeTimerSystem	Advance timed mode schedules using the current frame dt.
TileMap	Dense grid of maze/tile values.
TimedMode	One timed gameplay mode segment.
TunnelWrapBinding	Declarative horizontal/vertical wrap rule for maze agents.
TunnelWrapSystem	Wrap maze agents across configured grid edges.
AxisIntentBinding	Bind one intent value to one entity velocity axis.
IntentAxisVelocitySystem	Convert intent values into entity velocity on one axis.
KinematicMotionSystem	Integrate kinematic entities, with optional drag, spin, and TTL ticking.
MotionBinding	Integrate a group of entities with shared motion options.
ViewportConstraintBinding	Apply one viewport policy to a group of entities.
ViewportConstraintSystem	Clamp, wrap, or cull entities against the current viewport.
ProceduralParticle	One simulated procedural particle.
ProceduralParticleBinding	Configuration for one procedural particle emitter.
ProceduralParticleBundle	Compose simulation and render systems for one or more procedural emitters.
ProceduralParticleEmitterState	Mutable state for one emitter.
ProceduralParticleProfile	Reusable visual/physics preset for a particle emitter style.
ProceduralParticleRenderSystem	Render procedural particles using primitive circles.
ProceduralParticleSimulationSystem	Spawn and simulate particles for one or more emitters.
IntentPauseSystem	Generic pause trigger:
PickupCollisionBinding	Declarative collector-vs-pickup intersection rule.
PickupCollisionSystem	Collect overlapping pickup-like entities and optionally remove them.
ProjectileBoundaryBinding	Culling rule for projectile-like entities.
ProjectileBoundarySystem	Cull projectile-like entities against the current viewport.
ProjectileCleanupBinding	Cleanup rule for projectile-like entities.
ProjectileCleanupSystem	Remove dead projectile-like entities and optionally compact tracked ids.
ProjectileLifecycleBinding	Full projectile lifecycle configuration for motion, culling, and cleanup.
ProjectileLifecycleBundle	Compose motion, boundary, and cleanup for projectile-like entities.
ScoreChainBinding	Declarative score-chain expiry rule.
ScoreChainState	Mutable chain state for consecutive score events.
ScoreChainSystem	Expire score chains after their timer runs out.
SpawnBinding	Declarative spawn rule for one spawn source.
SpawnSystem	Execute reusable spawn rules and insert spawned entities into the world.
WaveProgressionBinding	Declarative wave/lap/round progression rule.
WaveProgressionSystem	Advance wave state and optionally spawn the next batch when complete.
TimedState	Mutable state for one temporary status window.
TimedStateBinding	Declarative timed-state decay rule.
TimedStateSystem	Decay active timed states using frame dt.
InputIntentSystem	Converts InputFrame -> MenuIntent.
BaseRenderSystem	Base rendering system.
RenderOverlay	Declarative overlay that emits draw operations into a render queue.
EntityRenderRule	First-match-wins entity rendering override rule.
BaseQueuedRenderSystem	Base class for render systems that build a RenderQueue and submit it.
ConfiguredQueuedRenderSystem	Queue-based render system composed from overlay and entity override rules.

Functions

action_map_from_bindings_config(→ ActionMap)	Build an ActionMap from YAML-friendly binding dictionaries.
action_map_from_controls_config(→ ActionMap)	Resolve one scene ActionMap from gameplay.controls config.
arena_tile_map_from_strings(...)	Build a common arena tile map from ASCII rows.
blast_cells(...)	Compute explosion coverage from one bomb origin.
is_walkable_arena_tile(→ bool)	Return whether an arena tile can be entered by a player/enemy.
spawn_explosion_from_bomb(...)	Populate explosion cells from one bomb and return covered cells.
apply_bounce_hit(→ None)	Reposition and reflect one kinematic entity according to a resolved hit.
reflect_from_viewport(→ tuple[str, Ellipsis])	Reflect one entity from selected viewport sides.
resolve_rect_bounce(→ BounceHit | None)	Resolve the shallowest-axis bounce between two overlapping rects.
action_map_from_scene_capture_config(...)	Build default capture action bindings from SceneCaptureConfig key hotkeys.
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.
choose_first_grid_cell(→ GridCoord | None)	Deterministic default cell chooser.
free_grid_cells(→ tuple[GridCoord, Ellipsis])	Return free cells inside bounds after subtracting occupied cells.
occupied_grid_cells(→ set[GridCoord])	Collect occupied cells from arbitrary values.
available_directions(→ tuple[CardinalDirection, Ellipsis])	Return the cardinal exits available from one cell.
choose_direction_away(→ CardinalDirection | None)	Choose the exit that maximizes Manhattan distance from a target cell.
choose_direction_toward(→ CardinalDirection | None)	Choose the exit that minimizes Manhattan distance to a target cell.
choose_random_direction(→ CardinalDirection | None)	Choose one valid exit randomly.
is_junction(→ bool)	Return whether a cell exposes more than two valid exits.
step_in_direction(...)	Return the adjacent cell in the given direction.
tile_map_from_strings(→ TileMap[TCell])	Build a tile map from ASCII rows and a legend.
fire_particle_binding(→ ProceduralParticleBinding[TCtx])	Convenience preset for a warm fire emitter.
magic_particle_binding(→ ProceduralParticleBinding[TCtx])	Convenience preset for arcane glow/spark emitters.
particle_binding_with_profile(...)	Build an emitter binding from a reusable particle style profile.
potion_particle_binding(→ ProceduralParticleBinding[TCtx])	Convenience preset for bubbling potion/fume emitters.
smoke_particle_binding(→ ProceduralParticleBinding[TCtx])	Convenience preset for a soft smoke emitter.
claim_score_chain_points(→ int)	Claim the next score value in a chain and refresh its timer.
reset_score_chain(→ None)	Clear the current score chain.
activate_timed_state(→ None)	Activate a timed state and reset its countdown.
clear_timed_state(→ None)	Clear a timed state immediately.

Package Contents

class mini_arcade_core.scenes.systems.builtins.ActionIntentSystem

Bases: mini_arcade_core.scenes.systems.base_system.BaseSystem[TContext], Generic[TContext, TIntent]

Input system that converts an ActionMap snapshot into scene intent.

action_map: ActionMap

intent_factory: Callable[[ActionSnapshot, TContext], TIntent]

name: str = 'action_intent'

phase: int

order: int = 10

channel: str | None = None

write_to_ctx_intent: bool = True

step(ctx: TContext) → None

Perform a single step of the system within the given context.

Parameters:

ctx (TSystemContext) – The system context.

class mini_arcade_core.scenes.systems.builtins.ActionMap

Mapping of action IDs to concrete binding strategies.

bindings: Mapping[str, ActionBinding]

read(frame: mini_arcade_core.runtime.input_frame.InputFrame) → ActionSnapshot

Read the current state of all actions from the input frame.

Parameters:

frame (InputFrame) – The input frame containing raw input states.

Returns:

An ActionSnapshot containing the state of all actions.

Return type:

ActionSnapshot

class mini_arcade_core.scenes.systems.builtins.ActionSnapshot

Per-frame snapshot for all mapped actions.

state(action: str) → ActionState

Get the ActionState for the given action, or a default if not found.

Parameters:

action (str) – The name of the action to get the state for.

Returns:

The ActionState for the given action, or a default if not found.

Return type:

ActionState

value(action: str, default: float = 0.0) → float

Get the normalized value of the action, or a default if not found.

Parameters:

• action (str) – The name of the action to get the value for.

• default (float) – The default value to return if the action is not found (default 0.0).

Returns:

The normalized value of the action, or the default if not found.

Return type:

float

down(action: str) → bool

Check if the action is currently held down.

Parameters:

action (str) – The name of the action to check.

Returns:

True if the action is currently held down, False otherwise.

Return type:

bool

pressed(action: str) → bool

Check if the action was pressed this frame.

Parameters:

action (str) – The name of the action to check.

Returns:

True if the action was pressed this frame, False otherwise.

Return type:

bool

released(action: str) → bool

Check if the action was released this frame.

Parameters:

action (str) – The name of the action to check.

Returns:

True if the action was released this frame, False otherwise.

Return type:

bool

class mini_arcade_core.scenes.systems.builtins.AxisActionBinding

Bases: ActionBinding

Axis action sourced from analog axes and optional digital fallbacks.

axes: tuple[str, Ellipsis] = ()

positive_keys: tuple[mini_arcade_core.backend.keys.Key, Ellipsis] = ()

negative_keys: tuple[mini_arcade_core.backend.keys.Key, Ellipsis] = ()

positive_buttons: tuple[str, Ellipsis] = ()

negative_buttons: tuple[str, Ellipsis] = ()

deadzone: float = 0.15

scale: float = 1.0

read(frame: mini_arcade_core.runtime.input_frame.InputFrame) → ActionState

Read the current state of this action from the input frame.

Parameters:

frame (InputFrame) – The input frame containing raw input states.

Returns:

The current ActionState for this binding.

Return type:

ActionState

class mini_arcade_core.scenes.systems.builtins.ConfiguredActionIntentSystem(*, controls: Mapping[str, Any] | None, scene_key: str, intent_factory: Callable[[ActionSnapshot, TContext], TIntent], fallback_bindings: Mapping[str, Any] | None = None, name: str = 'action_intent', phase: int = SystemPhase.INPUT, order: int = 10, channel: str | None = None, write_to_ctx_intent: bool = True)

Bases: ActionIntentSystem[TContext, TIntent], Generic[TContext, TIntent]

Action-intent system configured directly from gameplay.controls settings.

class mini_arcade_core.scenes.systems.builtins.DigitalActionBinding

Bases: ActionBinding

Digital action sourced from keyboard and/or named buttons.

keys: tuple[mini_arcade_core.backend.keys.Key, Ellipsis] = ()

buttons: tuple[str, Ellipsis] = ()

read(frame: mini_arcade_core.runtime.input_frame.InputFrame) → ActionState

Read the current state of this action from the input frame.

Parameters:

frame (InputFrame) – The input frame containing raw input states.

Returns:

The current ActionState for this binding.

Return type:

ActionState

mini_arcade_core.scenes.systems.builtins.action_map_from_bindings_config(bindings: Mapping[str, Any] | None) → ActionMap

Build an ActionMap from YAML-friendly binding dictionaries.

Supported entry formats per action: - digital:

type: digital keys: [ESCAPE] buttons: [pad_start]

• axis:

  type: axis axes: [left_y] positive_keys: [S] negative_keys: [W] positive_buttons: [pad_down] negative_buttons: [pad_up] deadzone: 0.15 scale: 1.0

mini_arcade_core.scenes.systems.builtins.action_map_from_controls_config(controls_cfg: Mapping[str, Any] | None, *, scene_key: str, default_action_map: ActionMap) → ActionMap

Resolve one scene ActionMap from gameplay.controls config.

Expected layout:

gameplay:

controls:

<scene_key>:

bindings: {…}

class mini_arcade_core.scenes.systems.builtins.AnimationTickSystem

Step entity animations during presentation.

Current entities use Anim2D.step(dt). A small compatibility path is kept for older animation objects that still expose update/current_frame.

name: str = 'common_anim_tick'

phase: int

order: int = 0

get_entities: Callable[[object], Iterable[HasAnim]]

step(ctx: object) → None

Advance animations for all alive entities provided by get_entities.

class mini_arcade_core.scenes.systems.builtins.ArenaTile

Bases: str, enum.Enum

Common arena tile kinds for bomb-based grid games.

FLOOR = 'floor'

SOLID = 'solid'

BREAKABLE = 'breakable'

SPAWN = 'spawn'

VOID = 'void'

class mini_arcade_core.scenes.systems.builtins.BombField

Dense bomb occupancy keyed by cell.

bombs: dict[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, BombState]

bomb_at(cell: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) → BombState | None

Return the bomb currently occupying one cell, if any.

active_bombs() → tuple[BombState, Ellipsis]

Return all currently active bombs.

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

Return every cell that currently contains a bomb.

add(bomb: BombState) → BombState

Insert or replace a bomb entry and return it.

remove(cell: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) → BombState | None

Remove and return the bomb at one cell, if present.

count_for_owner(owner_id: int | None) → int

Count bombs owned by a specific actor.

class mini_arcade_core.scenes.systems.builtins.BombFuseBinding

Bases: Generic[TCtx]

Declarative fuse ticking and detonation rule.

bombs_getter: Callable[[TCtx], BombField]

on_detonated: Callable[[TCtx, BombState], None] | None = None

class mini_arcade_core.scenes.systems.builtins.BombFuseSystem

Bases: Generic[TCtx]

Tick bomb fuses and emit detonation callbacks when they expire.

name: str = 'common_bomb_fuse'

phase: int

order: int = 32

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Advance bomb fuses and notify bindings when bombs detonate.

class mini_arcade_core.scenes.systems.builtins.BombPlacementBinding

Bases: Generic[TCtx]

Declarative bomb placement rule.

should_place: Callable[[TCtx], bool]

placement_cell_getter: Callable[[TCtx], mini_arcade_core.scenes.systems.builtins.grid.GridCoord]

bombs_getter: Callable[[TCtx], BombField]

tile_map_getter: Callable[[TCtx], mini_arcade_core.scenes.systems.builtins.maze.TileMap[ArenaTile]]

build_bomb: Callable[[TCtx, mini_arcade_core.scenes.systems.builtins.grid.GridCoord], BombState]

owner_id_getter: Callable[[TCtx], int | None]

max_active_getter: Callable[[TCtx], int]

on_placed: Callable[[TCtx, BombState], None] | None = None

class mini_arcade_core.scenes.systems.builtins.BombPlacementSystem

Bases: Generic[TCtx]

Place bombs onto walkable floor cells when rules allow.

name: str = 'common_bomb_placement'

phase: int

order: int = 24

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Place bombs for every binding whose placement rule passes.

class mini_arcade_core.scenes.systems.builtins.BombState

Mutable bomb metadata stored in a bomb field.

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

fuse_seconds: float = 2.0

blast_range: int = 2

owner_id: int | None = None

payload: Any = None

class mini_arcade_core.scenes.systems.builtins.ChainReactionBinding

Bases: Generic[TCtx]

Declarative bomb chain-reaction rule.

bombs_getter: Callable[[TCtx], BombField]

explosions_getter: Callable[[TCtx], ExplosionField]

on_triggered: Callable[[TCtx, BombState], None] | None = None

class mini_arcade_core.scenes.systems.builtins.ChainReactionSystem

Bases: Generic[TCtx]

Trigger bombs early when an active explosion reaches them.

name: str = 'common_chain_reaction'

phase: int

order: int = 34

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Detonate bombs early when an active blast reaches them.

class mini_arcade_core.scenes.systems.builtins.DestructibleTileBinding

Bases: Generic[TCtx]

Declarative breakable-tile destruction rule.

tile_map_getter: Callable[[TCtx], mini_arcade_core.scenes.systems.builtins.maze.TileMap[ArenaTile]]

explosions_getter: Callable[[TCtx], ExplosionField]

replacement_tile: ArenaTile

on_destroyed: Callable[[TCtx, mini_arcade_core.scenes.systems.builtins.grid.GridCoord], None] | None = None

class mini_arcade_core.scenes.systems.builtins.DestructibleTileSystem

Bases: Generic[TCtx]

Destroy breakable tiles touched by active explosion cells.

name: str = 'common_destructible_tiles'

phase: int

order: int = 36

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Replace breakable tiles touched by active explosion cells.

class mini_arcade_core.scenes.systems.builtins.ExplosionCellState

Mutable active explosion metadata for one cell.

ttl_seconds: float

owner_id: int | None = None

origin: mini_arcade_core.scenes.systems.builtins.grid.GridCoord | None = None

payload: Any = None

class mini_arcade_core.scenes.systems.builtins.ExplosionField

Dense active explosion occupancy keyed by cell.

cells: dict[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, ExplosionCellState]

cell_at(cell: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) → ExplosionCellState | None

Return the explosion metadata for one cell, if active.

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

Return the cells currently covered by an active explosion.

set_or_refresh(cell: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, *, ttl_seconds: float, owner_id: int | None = None, origin: mini_arcade_core.scenes.systems.builtins.grid.GridCoord | None = None, payload: Any = None) → ExplosionCellState

Create or refresh the active explosion metadata for one cell.

tick(dt: float) → tuple[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, Ellipsis]

Advance explosion lifetimes and return the cells that expired.

class mini_arcade_core.scenes.systems.builtins.ExplosionLifetimeBinding

Bases: Generic[TCtx]

Declarative active-explosion lifetime rule.

explosions_getter: Callable[[TCtx], ExplosionField]

on_expired: Callable[[TCtx, tuple[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, Ellipsis]], None] | None = None

class mini_arcade_core.scenes.systems.builtins.ExplosionLifetimeSystem

Bases: Generic[TCtx]

Tick active explosion cells until they expire.

name: str = 'common_explosion_lifetime'

phase: int

order: int = 38

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Tick active explosion cells and emit expiration callbacks.

class mini_arcade_core.scenes.systems.builtins.HazardCollisionBinding

Bases: Generic[TCtx]

Declarative explosion hazard collision rule.

hazard_cells_getter: Callable[[TCtx], Iterable[mini_arcade_core.scenes.systems.builtins.grid.GridCoord]]

targets_getter: Callable[[TCtx], Iterable[object]]

target_cell_getter: Callable[[TCtx, object], mini_arcade_core.scenes.systems.builtins.grid.GridCoord]

on_hit: Callable[[TCtx, object, mini_arcade_core.scenes.systems.builtins.grid.GridCoord], None]

class mini_arcade_core.scenes.systems.builtins.HazardCollisionSystem

Bases: Generic[TCtx]

Invoke callbacks for targets occupying active hazard cells.

name: str = 'common_hazard_collision'

phase: int

order: int = 37

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Invoke hit callbacks for targets occupying active hazard cells.

mini_arcade_core.scenes.systems.builtins.arena_tile_map_from_strings(*rows: str) → mini_arcade_core.scenes.systems.builtins.maze.TileMap[ArenaTile]

Build a common arena tile map from ASCII rows.

mini_arcade_core.scenes.systems.builtins.blast_cells(tile_map: mini_arcade_core.scenes.systems.builtins.maze.TileMap[ArenaTile], origin: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, *, blast_range: int) → tuple[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, Ellipsis]

Compute explosion coverage from one bomb origin.

mini_arcade_core.scenes.systems.builtins.is_walkable_arena_tile(tile: ArenaTile | None) → bool

Return whether an arena tile can be entered by a player/enemy.

mini_arcade_core.scenes.systems.builtins.spawn_explosion_from_bomb(explosions: ExplosionField, tile_map: mini_arcade_core.scenes.systems.builtins.maze.TileMap[ArenaTile], bomb: BombState, *, ttl_seconds: float) → tuple[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, Ellipsis]

Populate explosion cells from one bomb and return covered cells.

class mini_arcade_core.scenes.systems.builtins.BounceCollisionBinding

Bases: Generic[TCtx]

Declarative ball-vs-rect bounce rule.

mover_getter: Callable[[TCtx], mini_arcade_core.engine.entities.BaseEntity | None]

targets_getter: Callable[[TCtx], Iterable[mini_arcade_core.engine.entities.BaseEntity]]

predicate: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool]

stop_after_first_hit: bool = True

on_bounce: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity, mini_arcade_core.engine.entities.BaseEntity, BounceHit], None] | None = None

class mini_arcade_core.scenes.systems.builtins.BounceCollisionSystem

Bases: Generic[TCtx]

Reflect one moving rect from one or more target rects.

name: str = 'common_bounce_collision'

phase: int

order: int = 45

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Resolve mover collisions against rect targets and bounce them.

class mini_arcade_core.scenes.systems.builtins.BounceHit

Resolved bounce collision information.

axis: str

normal_x: float

normal_y: float

penetration: float

class mini_arcade_core.scenes.systems.builtins.BrickField

Dense brick layout with per-cell hit points.

layout: mini_arcade_core.scenes.systems.builtins.grid.GridLayout

bricks: dict[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, BrickState]

brick_at(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) → BrickState | None

Return the brick state at one cell, if alive.

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

Return the currently alive brick cells.

brick_rect(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) → tuple[float, float, float, float]

Return the world-space rect for one brick cell.

apply_damage(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, amount: int = 1) → BrickState | None

Damage one brick cell and delete it when hp reaches zero.

class mini_arcade_core.scenes.systems.builtins.BrickFieldCollisionBinding

Bases: Generic[TCtx]

Declarative ball-vs-brick-field bounce and damage rule.

mover_getter: Callable[[TCtx], mini_arcade_core.engine.entities.BaseEntity | None]

field_getter: Callable[[TCtx], BrickField | None]

damage: int = 1

on_hit: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity, mini_arcade_core.scenes.systems.builtins.grid.GridCoord, BrickState | None, BounceHit], None] | None = None

class mini_arcade_core.scenes.systems.builtins.BrickFieldCollisionSystem

Bases: Generic[TCtx]

Reflect a ball-like entity from the first hit brick and damage the field.

name: str = 'common_brick_field_collision'

phase: int

order: int = 46

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Bounce a mover from the first hit brick cell and apply damage.

class mini_arcade_core.scenes.systems.builtins.BrickState

Mutable brick metadata stored inside a brick field.

hit_points: int = 1

payload: Any = None

property alive: bool

Return whether this brick still has hit points remaining.

class mini_arcade_core.scenes.systems.builtins.PaddleBouncePolicy

Shape outgoing ball direction based on paddle contact point.

max_bounce_angle_deg: float = 70.0

min_speed: float = 180.0

max_speed: float = 420.0

speed_gain: float = 1.04

vertical_bias: float = 1.0

paddle_velocity_influence: float = 0.25

apply(ball: mini_arcade_core.engine.entities.BaseEntity, paddle: mini_arcade_core.engine.entities.BaseEntity) → None

Apply paddle-shaped bounce to a ball-like entity.

class mini_arcade_core.scenes.systems.builtins.ViewportBounceBinding

Bases: Generic[TCtx]

Declarative viewport bounce rule for one or more ball-like entities.

entities_getter: Callable[[TCtx], Iterable[mini_arcade_core.engine.entities.BaseEntity]]

viewport_getter: Callable[[TCtx], tuple[float, float]]

predicate: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool]

bounce_left: bool = True

bounce_right: bool = True

bounce_top: bool = True

bounce_bottom: bool = False

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

class mini_arcade_core.scenes.systems.builtins.ViewportBounceSystem

Bases: Generic[TCtx]

Reflect ball-like entities from selected viewport sides.

name: str = 'common_viewport_bounce'

phase: int

order: int = 40

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Reflect configured entities from the active viewport edges.

mini_arcade_core.scenes.systems.builtins.apply_bounce_hit(entity: mini_arcade_core.engine.entities.BaseEntity, hit: BounceHit) → None

Reposition and reflect one kinematic entity according to a resolved hit.

mini_arcade_core.scenes.systems.builtins.reflect_from_viewport(entity: mini_arcade_core.engine.entities.BaseEntity, *, viewport: tuple[float, float], bounce_left: bool = True, bounce_right: bool = True, bounce_top: bool = True, bounce_bottom: bool = False) → tuple[str, Ellipsis]

Reflect one entity from selected viewport sides.

mini_arcade_core.scenes.systems.builtins.resolve_rect_bounce(mover_rect: tuple[float, float, float, float], target_rect: tuple[float, float, float, float]) → BounceHit | None

Resolve the shallowest-axis bounce between two overlapping rects.

class mini_arcade_core.scenes.systems.builtins.CaptureHotkey

One hotkey toggle configuration.

enabled: bool = True

key: mini_arcade_core.backend.keys.Key | None = None

class mini_arcade_core.scenes.systems.builtins.CaptureHotkeysConfig

Per-scene capture workflow configuration.

screenshot_label: str | None = None

replay_file: str | None = None

replay_game_id: str = 'mini-arcade'

replay_initial_scene: str = 'unknown'

replay_fps: int = 60

action_toggle_video: str = 'capture_toggle_video'

action_toggle_replay_record: str = 'capture_toggle_replay_record'

action_toggle_replay_play: str = 'capture_toggle_replay_play'

action_screenshot: str = 'capture_screenshot'

classmethod from_scene_capture_config(cfg: SceneCaptureConfig) → CaptureHotkeysConfig

Build an action-driven capture config from the scene key config.

class mini_arcade_core.scenes.systems.builtins.CaptureHotkeysSystem

Bases: mini_arcade_core.scenes.systems.base_system.BaseSystem[CaptureContext]

Handles screenshot/replay/video commands in a reusable way.

services: mini_arcade_core.runtime.services.RuntimeServices

action_map: mini_arcade_core.scenes.systems.builtins.actions.ActionMap

cfg: CaptureHotkeysConfig

name: str = 'capture_hotkeys'

phase: int

order: int = 13

step(ctx: CaptureContext) → None

Perform a single step of the system within the given context.

Parameters:

ctx (TSystemContext) – The system context.

class mini_arcade_core.scenes.systems.builtins.SceneCaptureConfig

Scene-level capture controls configuration.

screenshot: CaptureHotkey

video_toggle: CaptureHotkey

replay_record_toggle: CaptureHotkey

replay_play_toggle: CaptureHotkey

screenshot_label: str | None = None

replay_file: str | None = None

replay_game_id: str = 'mini-arcade'

replay_initial_scene: str | None = None

replay_fps: int = 60

any_enabled() → bool

Return True if at least one capture feature is enabled.

with_scene_defaults(scene_id: str) → SceneCaptureConfig

Fill scene-derived defaults while preserving explicit overrides.

mini_arcade_core.scenes.systems.builtins.action_map_from_scene_capture_config(scene_cfg: SceneCaptureConfig, *, hotkeys_cfg: CaptureHotkeysConfig | None = None) → mini_arcade_core.scenes.systems.builtins.actions.ActionMap

Build default capture action bindings from SceneCaptureConfig key hotkeys.

class mini_arcade_core.scenes.systems.builtins.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.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.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.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.

class mini_arcade_core.scenes.systems.builtins.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.

class mini_arcade_core.scenes.systems.builtins.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.

mini_arcade_core.scenes.systems.builtins.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.

mini_arcade_core.scenes.systems.builtins.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.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.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.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.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.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.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.

class mini_arcade_core.scenes.systems.builtins.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.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.choose_first_grid_cell(_ctx: object, cells: tuple[GridCoord, Ellipsis]) → GridCoord | None

Deterministic default cell chooser.

mini_arcade_core.scenes.systems.builtins.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.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.

class mini_arcade_core.scenes.systems.builtins.IntentCommandSystem

Bases: mini_arcade_core.scenes.systems.base_system.BaseSystem[TContext], Generic[TContext]

Push commands when configured intent attributes are truthy for this tick.

bindings: Mapping[str, Callable[[TContext], object]]

name: str = 'intent_commands'

phase: int

order: int = 13

intent_attr: str = 'intent'

step(ctx: TContext) → None

Perform a single step of the system within the given context.

Parameters:

ctx (TSystemContext) – The system context.

class mini_arcade_core.scenes.systems.builtins.CardinalDirection

Bases: str, enum.Enum

Four-way grid direction.

UP = 'up'

DOWN = 'down'

LEFT = 'left'

RIGHT = 'right'

property vector: tuple[int, int]

Return the (dcol, drow) vector for this direction.

property opposite: CardinalDirection

Return the opposite cardinal direction.

class mini_arcade_core.scenes.systems.builtins.CollectibleCollisionBinding

Bases: Generic[TCtx]

Declarative collectible pickup rule.

collector_cell_getter: Callable[[TCtx], mini_arcade_core.scenes.systems.builtins.grid.GridCoord]

field_getter: Callable[[TCtx], CollectibleField | None]

on_collect: Callable[[TCtx, mini_arcade_core.scenes.systems.builtins.grid.GridCoord, CollectibleState], None] | None = None

class mini_arcade_core.scenes.systems.builtins.CollectibleCollisionSystem

Bases: Generic[TCtx]

Consume collectibles when a collector enters the same cell.

name: str = 'common_collectible_collision'

phase: int

order: int = 35

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Consume collectibles that share a cell with the collector.

class mini_arcade_core.scenes.systems.builtins.CollectibleField

Dense collectible state keyed by grid cell.

items: dict[mini_arcade_core.scenes.systems.builtins.grid.GridCoord, CollectibleState]

item_at(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) → CollectibleState | None

Return the collectible stored at one cell, if any.

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

Return the cells that currently contain collectibles.

remove(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord) → CollectibleState | None

Remove and return the collectible stored at one cell.

class mini_arcade_core.scenes.systems.builtins.CollectibleKind

Bases: str, enum.Enum

Common collectible kinds for maze games.

PELLET = 'pellet'

POWER = 'power'

BONUS = 'bonus'

class mini_arcade_core.scenes.systems.builtins.CollectibleState

Mutable collectible metadata stored inside a field.

kind: CollectibleKind

payload: Any = None

class mini_arcade_core.scenes.systems.builtins.GridNavigationBinding

Bases: Generic[TCtx, TCell]

Declarative lane/junction navigation rule.

state_getter: Callable[[TCtx], GridNavigatorState]

tile_map_getter: Callable[[TCtx], TileMap[TCell]]

desired_direction_getter: Callable[[TCtx], CardinalDirection | None]

can_enter: Callable[[TCell | None], bool]

on_cell_entered: Callable[[TCtx, mini_arcade_core.scenes.systems.builtins.grid.GridCoord], None] | None = None

allow_reverse: bool = True

steps_getter: Callable[[TCtx], int]

class mini_arcade_core.scenes.systems.builtins.GridNavigationSystem

Bases: Generic[TCtx, TCell]

Advance one or more maze agents through a tile map with turn buffering.

name: str = 'common_grid_navigation'

phase: int

order: int = 30

enabled_when: Callable[[TCtx], bool]

bindings: tuple[GridNavigationBinding[TCtx, TCell], Ellipsis] = ()

step(ctx: TCtx) → None

Advance bound navigators through the tile map with turn buffering.

class mini_arcade_core.scenes.systems.builtins.GridNavigatorState

Mutable cell-based movement state for one maze agent.

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

direction: CardinalDirection

pending_direction: CardinalDirection | None = None

moved_this_frame: int = 0

class mini_arcade_core.scenes.systems.builtins.ModeTimerBinding

Bases: Generic[TCtx]

Declarative timed mode schedule.

state_getter: Callable[[TCtx], ModeTimerState]

schedule: tuple[TimedMode, Ellipsis]

on_mode_changed: Callable[[TCtx, TimedMode], None] | None = None

loop: bool = False

class mini_arcade_core.scenes.systems.builtins.ModeTimerState

Mutable state for timed mode progression.

mode_index: int = 0

elapsed_in_mode: float = 0.0

current_mode: str = ''

class mini_arcade_core.scenes.systems.builtins.ModeTimerSystem

Bases: Generic[TCtx]

Advance timed mode schedules using the current frame dt.

name: str = 'common_mode_timer'

phase: int

order: int = 15

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Advance scheduled timed modes using the current frame delta.

class mini_arcade_core.scenes.systems.builtins.TileMap

Bases: Generic[TCell]

Dense grid of maze/tile values.

bounds: mini_arcade_core.scenes.systems.builtins.grid.GridBounds

default: TCell | None = None

__post_init__() → None

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

Return whether a coordinate falls inside the tile-map bounds.

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

Return the stored tile value at one coordinate, if in bounds.

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

Store a tile value at one coordinate.

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

Return all cells with their stored values.

class mini_arcade_core.scenes.systems.builtins.TimedMode

One timed gameplay mode segment.

name: str

duration_seconds: float | None

payload: Any = None

class mini_arcade_core.scenes.systems.builtins.TunnelWrapBinding

Bases: Generic[TCtx]

Declarative horizontal/vertical wrap rule for maze agents.

states_getter: Callable[[TCtx], Iterable[GridNavigatorState]]

bounds_getter: Callable[[TCtx], mini_arcade_core.scenes.systems.builtins.grid.GridBounds]

wrap_horizontal: bool = True

wrap_vertical: bool = False

class mini_arcade_core.scenes.systems.builtins.TunnelWrapSystem

Bases: Generic[TCtx]

Wrap maze agents across configured grid edges.

name: str = 'common_tunnel_wrap'

phase: int

order: int = 31

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Wrap navigator states across configured map edges.

mini_arcade_core.scenes.systems.builtins.available_directions(tile_map: TileMap[TCell], coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, *, can_enter: Callable[[TCell | None], bool]) → tuple[CardinalDirection, Ellipsis]

Return the cardinal exits available from one cell.

mini_arcade_core.scenes.systems.builtins.choose_direction_away(tile_map: TileMap[TCell], coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, target: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, *, can_enter: Callable[[TCell | None], bool], current_direction: CardinalDirection | None = None, allow_reverse: bool = False) → CardinalDirection | None

Choose the exit that maximizes Manhattan distance from a target cell.

mini_arcade_core.scenes.systems.builtins.choose_direction_toward(tile_map: TileMap[TCell], coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, target: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, *, can_enter: Callable[[TCell | None], bool], current_direction: CardinalDirection | None = None, allow_reverse: bool = False) → CardinalDirection | None

Choose the exit that minimizes Manhattan distance to a target cell.

mini_arcade_core.scenes.systems.builtins.choose_random_direction(tile_map: TileMap[TCell], coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, *, can_enter: Callable[[TCell | None], bool], rng: random.Random | None = None, current_direction: CardinalDirection | None = None, allow_reverse: bool = False) → CardinalDirection | None

Choose one valid exit randomly.

mini_arcade_core.scenes.systems.builtins.is_junction(tile_map: TileMap[TCell], coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, *, can_enter: Callable[[TCell | None], bool]) → bool

Return whether a cell exposes more than two valid exits.

mini_arcade_core.scenes.systems.builtins.step_in_direction(coord: mini_arcade_core.scenes.systems.builtins.grid.GridCoord, direction: CardinalDirection) → mini_arcade_core.scenes.systems.builtins.grid.GridCoord

Return the adjacent cell in the given direction.

mini_arcade_core.scenes.systems.builtins.tile_map_from_strings(*rows: str, legend: Mapping[str, TCell], default: TCell | None = None) → TileMap[TCell]

Build a tile map from ASCII rows and a legend.

class mini_arcade_core.scenes.systems.builtins.AxisIntentBinding

Bases: Generic[TCtx]

Bind one intent value to one entity velocity axis.

entity_getter: Callable[[TCtx], mini_arcade_core.engine.entities.BaseEntity | None]

value_getter: Callable[[TCtx], float]

axis: MoveAxis

speed_getter: Callable[[mini_arcade_core.engine.entities.BaseEntity], float]

zero_other_axis: bool = False

predicate: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool]

class mini_arcade_core.scenes.systems.builtins.IntentAxisVelocitySystem

Bases: Generic[TCtx]

Convert intent values into entity velocity on one axis.

name: str = 'common_axis_velocity'

phase: int

order: int = 20

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Translate intent axes into kinematic velocity for bound entities.

class mini_arcade_core.scenes.systems.builtins.KinematicMotionSystem

Bases: Generic[TCtx]

Integrate kinematic entities, with optional drag, spin, and TTL ticking.

name: str = 'common_kinematic_motion'

phase: int

order: int = 30

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Integrate velocity and acceleration for bound entities.

class mini_arcade_core.scenes.systems.builtins.MotionBinding

Bases: Generic[TCtx]

Integrate a group of entities with shared motion options.

entities_getter: Callable[[TCtx], Iterable[mini_arcade_core.engine.entities.BaseEntity]]

predicate: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool]

dt_getter: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], float]

drag: float | None = None

drag_getter: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], float | None] | None = None

spin_attr: str | None = None

ttl_step: bool = False

class mini_arcade_core.scenes.systems.builtins.ViewportConstraintBinding

Bases: Generic[TCtx]

Apply one viewport policy to a group of entities.

entities_getter: Callable[[TCtx], Iterable[mini_arcade_core.engine.entities.BaseEntity]]

policy: ViewportPolicy

predicate: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool]

axes: tuple[MoveAxis, Ellipsis] = ('x', 'y')

margin: float = 0.0

margin_getter: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], float]

on_cull: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], None] | None = None

class mini_arcade_core.scenes.systems.builtins.ViewportConstraintSystem

Bases: Generic[TCtx]

Clamp, wrap, or cull entities against the current viewport.

name: str = 'common_viewport_constraints'

phase: int

order: int = 40

enabled_when: Callable[[TCtx], bool]

viewport_getter: Callable[[TCtx], tuple[float, float]]

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

step(ctx: TCtx) → None

Apply clamp, wrap, or cull viewport policies to bound entities.

mini_arcade_core.scenes.systems.builtins.FIRE_ALPHA_RAMP: tuple[AlphaStop, Ellipsis] = ((0.0, 48), (0.08, 128), (0.28, 216), (0.72, 138), (1.0, 0))

mini_arcade_core.scenes.systems.builtins.FIRE_COLOR_RAMP: tuple[ColorStop, Ellipsis] = ((0.0, (255, 252, 220)), (0.14, (255, 236, 150)), (0.34, (255, 182, 84)), (0.58, (255, 96, 44)),...

mini_arcade_core.scenes.systems.builtins.FIRE_PARTICLE_PROFILE

mini_arcade_core.scenes.systems.builtins.MAGIC_ALPHA_RAMP: tuple[AlphaStop, Ellipsis] = ((0.0, 34), (0.1, 96), (0.45, 188), (0.82, 92), (1.0, 0))

mini_arcade_core.scenes.systems.builtins.MAGIC_COLOR_RAMP: tuple[ColorStop, Ellipsis] = ((0.0, (244, 222, 255)), (0.25, (188, 126, 255)), (0.55, (108, 72, 255)), (0.82, (56, 34, 162)),...

mini_arcade_core.scenes.systems.builtins.MAGIC_PARTICLE_PROFILE

mini_arcade_core.scenes.systems.builtins.POTION_ALPHA_RAMP: tuple[AlphaStop, Ellipsis] = ((0.0, 22), (0.12, 74), (0.38, 146), (0.84, 60), (1.0, 0))

mini_arcade_core.scenes.systems.builtins.POTION_COLOR_RAMP: tuple[ColorStop, Ellipsis] = ((0.0, (198, 255, 226)), (0.28, (120, 255, 200)), (0.56, (62, 214, 166)), (0.82, (20, 98, 88)),...

mini_arcade_core.scenes.systems.builtins.POTION_PARTICLE_PROFILE

mini_arcade_core.scenes.systems.builtins.SMOKE_ALPHA_RAMP: tuple[AlphaStop, Ellipsis] = ((0.0, 18), (0.18, 42), (0.45, 64), (0.82, 34), (1.0, 0))

mini_arcade_core.scenes.systems.builtins.SMOKE_COLOR_RAMP: tuple[ColorStop, Ellipsis] = ((0.0, (146, 128, 124)), (0.3, (118, 104, 102)), (0.7, (82, 76, 78)), (1.0, (36, 32, 36)))

mini_arcade_core.scenes.systems.builtins.SMOKE_PARTICLE_PROFILE

class mini_arcade_core.scenes.systems.builtins.ProceduralParticle

One simulated procedural particle.

x: float

y: float

vx: float

vy: float

age: float

lifetime: float

start_radius: float

end_radius: float

phase: float = 0.0

class mini_arcade_core.scenes.systems.builtins.ProceduralParticleBinding

Bases: Generic[TCtx]

Configuration for one procedural particle emitter.

state_getter: Callable[[TCtx], ProceduralParticleEmitterState]

origin_getter: Callable[[TCtx], tuple[float, float]]

enabled_when: Callable[[TCtx], bool]

intensity_getter: Callable[[TCtx], float]

wind_getter: Callable[[TCtx], float]

viewport_getter: Callable[[TCtx], tuple[float, float]]

spawn_rate: float = 96.0

max_particles: int = 180

spawn_spread_x: float = 18.0

spawn_spread_y: float = 6.0

velocity_x: tuple[float, float]

velocity_y: tuple[float, float]

acceleration_x: float = 0.0

acceleration_y: float = -18.0

turbulence: float = 20.0

turbulence_frequency: float = 7.0

drag: float = 0.9

lifetime: tuple[float, float] = (0.45, 0.9)

start_radius: tuple[float, float] = (8.0, 14.0)

end_radius: tuple[float, float] = (1.0, 4.0)

color_ramp: tuple[ColorStop, Ellipsis] = ((0.0, (255, 252, 220)), (0.14, (255, 236, 150)), (0.34, (255, 182, 84)), (0.58, (255, 96, 44)),...

alpha_ramp: tuple[AlphaStop, Ellipsis] = ((0.0, 48), (0.08, 128), (0.28, 216), (0.72, 138), (1.0, 0))

render_pass_scales: tuple[float, Ellipsis] = (1.4, 0.92, 0.56)

render_pass_color_scales: tuple[float, Ellipsis] = (0.78, 1.0, 1.08)

render_pass_alpha_scales: tuple[float, Ellipsis] = (0.18, 0.52, 0.95)

intensity_radius_scale: float = 0.45

intensity_lifetime_scale: float = 0.16

intensity_velocity_scale: float = 0.28

seed: int = 1

class mini_arcade_core.scenes.systems.builtins.ProceduralParticleBundle

Bases: mini_arcade_core.scenes.systems.SystemBundle[TCtx]

Compose simulation and render systems for one or more procedural emitters.

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

simulation_name: str = 'procedural_particle_simulation'

simulation_phase: int

simulation_order: int = 32

render_name: str = 'procedural_particle_render'

render_phase: int

render_order: int = 105

__post_init__() → None

iter_systems() → Iterable[object]

Return the concrete systems that should be added to the pipeline.

class mini_arcade_core.scenes.systems.builtins.ProceduralParticleEmitterState

Mutable state for one emitter.

particles: list[ProceduralParticle] = []

spawn_accumulator: float = 0.0

elapsed: float = 0.0

class mini_arcade_core.scenes.systems.builtins.ProceduralParticleProfile

Reusable visual/physics preset for a particle emitter style.

spawn_rate: float

max_particles: int

spawn_spread_x: float

spawn_spread_y: float

velocity_x: tuple[float, float]

velocity_y: tuple[float, float]

acceleration_x: float

acceleration_y: float

turbulence: float

turbulence_frequency: float

drag: float

lifetime: tuple[float, float]

start_radius: tuple[float, float]

end_radius: tuple[float, float]

color_ramp: tuple[ColorStop, Ellipsis]

alpha_ramp: tuple[AlphaStop, Ellipsis]

render_pass_scales: tuple[float, Ellipsis]

render_pass_color_scales: tuple[float, Ellipsis]

render_pass_alpha_scales: tuple[float, Ellipsis]

intensity_radius_scale: float = 0.45

intensity_lifetime_scale: float = 0.16

intensity_velocity_scale: float = 0.28

class mini_arcade_core.scenes.systems.builtins.ProceduralParticleRenderSystem

Bases: Generic[TCtx]

Render procedural particles using primitive circles.

name: str = 'procedural_particle_render'

phase: int

order: int = 105

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

step(ctx: TCtx) → None

Build a render packet with draw calls for all particles from all emitters, sorted back-to-front by Y coordinate.

Parameters:

ctx (TCtx) – The current scene context, which must have a packet attribute that is a RenderPacket or None.

class mini_arcade_core.scenes.systems.builtins.ProceduralParticleSimulationSystem

Bases: Generic[TCtx]

Spawn and simulate particles for one or more emitters.

name: str = 'procedural_particle_simulation'

phase: int

order: int = 32

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

__post_init__() → None

step(ctx: TCtx) → None

Advance emitter state, cull dead particles, and spawn new ones.

mini_arcade_core.scenes.systems.builtins.fire_particle_binding(*, state_getter: Callable[[TCtx], ProceduralParticleEmitterState], origin_getter: Callable[[TCtx], tuple[float, float]], intensity_getter: Callable[[TCtx], float] = _default_intensity, wind_getter: Callable[[TCtx], float] = _default_wind, viewport_getter: Callable[[TCtx], tuple[float, float]] = _default_viewport, seed: int = 1) → ProceduralParticleBinding[TCtx]

Convenience preset for a warm fire emitter.

mini_arcade_core.scenes.systems.builtins.magic_particle_binding(*, state_getter: Callable[[TCtx], ProceduralParticleEmitterState], origin_getter: Callable[[TCtx], tuple[float, float]], intensity_getter: Callable[[TCtx], float] = _default_intensity, wind_getter: Callable[[TCtx], float] = _default_wind, viewport_getter: Callable[[TCtx], tuple[float, float]] = _default_viewport, enabled_when: Callable[[TCtx], bool] = _default_enabled_when, seed: int = 3) → ProceduralParticleBinding[TCtx]

Convenience preset for arcane glow/spark emitters.

mini_arcade_core.scenes.systems.builtins.particle_binding_with_profile(*, profile: ProceduralParticleProfile, state_getter: Callable[[TCtx], ProceduralParticleEmitterState], origin_getter: Callable[[TCtx], tuple[float, float]], intensity_getter: Callable[[TCtx], float] = _default_intensity, wind_getter: Callable[[TCtx], float] = _default_wind, viewport_getter: Callable[[TCtx], tuple[float, float]] = _default_viewport, enabled_when: Callable[[TCtx], bool] = _default_enabled_when, seed: int = 1) → ProceduralParticleBinding[TCtx]

Build an emitter binding from a reusable particle style profile.

mini_arcade_core.scenes.systems.builtins.potion_particle_binding(*, state_getter: Callable[[TCtx], ProceduralParticleEmitterState], origin_getter: Callable[[TCtx], tuple[float, float]], intensity_getter: Callable[[TCtx], float] = _default_intensity, wind_getter: Callable[[TCtx], float] = _default_wind, viewport_getter: Callable[[TCtx], tuple[float, float]] = _default_viewport, enabled_when: Callable[[TCtx], bool] = _default_enabled_when, seed: int = 4) → ProceduralParticleBinding[TCtx]

Convenience preset for bubbling potion/fume emitters.

mini_arcade_core.scenes.systems.builtins.smoke_particle_binding(*, state_getter: Callable[[TCtx], ProceduralParticleEmitterState], origin_getter: Callable[[TCtx], tuple[float, float]], intensity_getter: Callable[[TCtx], float] = _default_intensity, wind_getter: Callable[[TCtx], float] = _default_wind, viewport_getter: Callable[[TCtx], tuple[float, float]] = _default_viewport, seed: int = 2) → ProceduralParticleBinding[TCtx]

Convenience preset for a soft smoke emitter.

class mini_arcade_core.scenes.systems.builtins.IntentPauseSystem

Bases: mini_arcade_core.scenes.systems.base_system.BaseSystem[TContext], Generic[TContext]

Generic pause trigger: - checks ctx.intent.<intent_attr> - optionally runs a local pause callback - pushes the pause command into ctx.commands

pause_command_factory: Callable[[TContext], object]

name: str = 'pause_intent'

phase: int

order: int = 12

intent_attr: str = 'pause'

is_already_paused: Callable[[TContext], bool] | None = None

on_pause: Callable[[TContext], None] | None = None

step(ctx: TContext) → None

Perform a single step of the system within the given context.

Parameters:

ctx (TSystemContext) – The system context.

class mini_arcade_core.scenes.systems.builtins.PickupCollisionBinding

Bases: Generic[TCtx]

Declarative collector-vs-pickup intersection rule.

collectors_getter: Callable[[TCtx], Iterable[mini_arcade_core.engine.entities.BaseEntity]]

pickups_getter: Callable[[TCtx], Iterable[mini_arcade_core.engine.entities.BaseEntity]]

predicate: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool]

on_collect: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity, mini_arcade_core.engine.entities.BaseEntity], None] | None = None

remove_collected: bool = True

class mini_arcade_core.scenes.systems.builtins.PickupCollisionSystem

Bases: Generic[TCtx]

Collect overlapping pickup-like entities and optionally remove them.

name: str = 'common_pickup_collision'

phase: int

order: int = 48

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Resolve pickup collection for all configured bindings.

class mini_arcade_core.scenes.systems.builtins.ProjectileBoundaryBinding

Bases: Generic[TCtx]

Culling rule for projectile-like entities.

entities_getter: Callable[[TCtx], Iterable[mini_arcade_core.engine.entities.BaseEntity]]

predicate: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool]

margin: float = 0.0

margin_getter: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], float]

on_cull: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], None]

class mini_arcade_core.scenes.systems.builtins.ProjectileBoundarySystem

Bases: Generic[TCtx]

Cull projectile-like entities against the current viewport.

name: str = 'common_projectile_boundary'

phase: int

order: int = 36

enabled_when: Callable[[TCtx], bool]

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

__post_init__() → None

step(ctx: TCtx) → None

For each binding, cull entities that don’t satisfy the predicate and are outside the viewport plus margin.

Parameters:

ctx (TCtx) – The context object passed to the system, typically containing references to the world, scene, and other relevant state.

class mini_arcade_core.scenes.systems.builtins.ProjectileCleanupBinding

Bases: Generic[TCtx]

Cleanup rule for projectile-like entities.

entities_getter: Callable[[TCtx], Iterable[mini_arcade_core.engine.entities.BaseEntity]]

keep_entity: Callable[[mini_arcade_core.engine.entities.BaseEntity], bool]

tracked_ids_attr: str | None = None

tracked_domain_name: str | None = None

class mini_arcade_core.scenes.systems.builtins.ProjectileCleanupSystem

Bases: Generic[TCtx]

Remove dead projectile-like entities and optionally compact tracked ids.

name: str = 'common_projectile_cleanup'

phase: int

order: int = 46

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

For each binding, remove entities that don’t satisfy keep_entity, and if tracked_ids_attr and tracked_domain_name are provided, compact the tracked ids for the remaining entities.

Parameters:

ctx (TCtx) – The context object passed to the system, typically containing references to the world, scene, and other relevant state.

class mini_arcade_core.scenes.systems.builtins.ProjectileLifecycleBinding

Bases: Generic[TCtx]

Full projectile lifecycle configuration for motion, culling, and cleanup.

entities_getter: Callable[[TCtx], Iterable[mini_arcade_core.engine.entities.BaseEntity]]

predicate: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool]

dt_getter: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], float]

drag: float | None = None

drag_getter: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], float | None] | None = None

spin_attr: str | None = None

ttl_step: bool = False

margin: float = 0.0

margin_getter: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], float]

on_cull: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], None]

keep_entity: Callable[[mini_arcade_core.engine.entities.BaseEntity], bool]

tracked_ids_attr: str | None = None

tracked_domain_name: str | None = None

class mini_arcade_core.scenes.systems.builtins.ProjectileLifecycleBundle

Bases: mini_arcade_core.scenes.systems.SystemBundle[TCtx]

Compose motion, boundary, and cleanup for projectile-like entities.

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

enabled_when: Callable[[TCtx], bool]

motion_name: str = 'common_projectile_motion'

motion_phase: int

motion_order: int = 30

boundary_name: str = 'common_projectile_boundary'

boundary_phase: int

boundary_order: int = 36

cleanup_name: str = 'common_projectile_cleanup'

cleanup_phase: int

cleanup_order: int = 46

include_motion: bool = True

include_boundary: bool = True

include_cleanup: bool = True

__post_init__() → None

iter_systems() → Iterable[object]

Return the concrete systems that should be added to the pipeline.

class mini_arcade_core.scenes.systems.builtins.ScoreChainBinding

Bases: Generic[TCtx]

Declarative score-chain expiry rule.

state_getter: Callable[[TCtx], ScoreChainState]

on_expired: Callable[[TCtx, ScoreChainState], None] | None = None

class mini_arcade_core.scenes.systems.builtins.ScoreChainState

Mutable chain state for consecutive score events.

step_index: int = 0

remaining_seconds: float = 0.0

property active: bool

Whether the score chain is currently active and can be extended.

Returns:

True if the chain is active, False otherwise.

Return type:

bool

class mini_arcade_core.scenes.systems.builtins.ScoreChainSystem

Bases: Generic[TCtx]

Expire score chains after their timer runs out.

name: str = 'common_score_chain'

phase: int

order: int = 17

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Advance active score-chain timers by frame dt.

mini_arcade_core.scenes.systems.builtins.claim_score_chain_points(state: ScoreChainState, *, steps: tuple[int, Ellipsis], window_seconds: float) → int

Claim the next score value in a chain and refresh its timer.

mini_arcade_core.scenes.systems.builtins.reset_score_chain(state: ScoreChainState) → None

Clear the current score chain.

class mini_arcade_core.scenes.systems.builtins.SpawnBinding

Bases: Generic[TCtx]

Declarative spawn rule for one spawn source.

should_spawn: Callable[[TCtx], bool]

spawn: Callable[[TCtx], SpawnResult]

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

insert_into_world: bool = True

class mini_arcade_core.scenes.systems.builtins.SpawnSystem

Bases: Generic[TCtx]

Execute reusable spawn rules and insert spawned entities into the world.

name: str = 'common_spawn'

phase: int

order: int = 25

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Execute the spawn rules for each binding.

Parameters:

ctx (TCtx) – The context object passed to the system, typically containing references to the world, scene, and other relevant state.

class mini_arcade_core.scenes.systems.builtins.WaveProgressionBinding

Bases: Generic[TCtx]

Declarative wave/lap/round progression rule.

is_complete: Callable[[TCtx], bool]

can_progress: Callable[[TCtx], bool]

advance: Callable[[TCtx], None] | None = None

spawn_next: Callable[[TCtx], SpawnResult] | None = None

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

insert_into_world: bool = True

class mini_arcade_core.scenes.systems.builtins.WaveProgressionSystem

Bases: Generic[TCtx]

Advance wave state and optionally spawn the next batch when complete.

name: str = 'common_wave_progression'

phase: int

order: int = 80

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

For each binding, if can_progress and is_complete are both true, call advance and spawn_next (if provided).

Parameters:

ctx (TCtx) – The context object passed to the system, typically containing references to the world, scene, and other relevant state.

class mini_arcade_core.scenes.systems.builtins.TimedState

Mutable state for one temporary status window.

active: bool = False

remaining_seconds: float = 0.0

tag: str = ''

payload: Any = None

class mini_arcade_core.scenes.systems.builtins.TimedStateBinding

Bases: Generic[TCtx]

Declarative timed-state decay rule.

state_getter: Callable[[TCtx], TimedState]

on_expired: Callable[[TCtx, TimedState], None] | None = None

class mini_arcade_core.scenes.systems.builtins.TimedStateSystem

Bases: Generic[TCtx]

Decay active timed states using frame dt.

name: str = 'common_timed_state'

phase: int

order: int = 16

enabled_when: Callable[[TCtx], bool]

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

step(ctx: TCtx) → None

Advance active timed states by the current frame delta.

mini_arcade_core.scenes.systems.builtins.activate_timed_state(state: TimedState, *, duration_seconds: float, tag: str = '', payload: Any = None) → None

Activate a timed state and reset its countdown.

mini_arcade_core.scenes.systems.builtins.clear_timed_state(state: TimedState) → None

Clear a timed state immediately.

class mini_arcade_core.scenes.systems.builtins.InputIntentSystem

Bases: mini_arcade_core.scenes.systems.base_system.BaseSystem

Converts InputFrame -> MenuIntent.

Variables:

• name – Name of the system - default is “base_input”.

• order – Execution order of the system - default is 10.

name: str = 'base_input'

phase: int

order: int = 10

abstractmethod build_intent(ctx: object) → mini_arcade_core.scenes.sim_scene.BaseIntent

Build the intent

step(ctx: object)

Step the input system to extract menu intent.

class mini_arcade_core.scenes.systems.builtins.BaseRenderSystem

Bases: mini_arcade_core.scenes.systems.base_system.BaseSystem[TTickContext], Generic[TTickContext]

Base rendering system.

Variables:

• name – Name of the system - default is “base_render”.

• order – Execution order of the system - default is 100.

name: str = 'base_render'

phase: int

order: int = 100

build_draw_ops(ctx: TTickContext) → list[object]

Build draw calls for the current tick context.

Parameters:

ctx (BaseTickContext) – The tick context containing world state and other info.

Returns:

A list of draw calls to be executed by the render pipeline.

Return type:

list[DrawCall]

step(ctx: TTickContext) → None

Perform a single step of the system within the given context.

Parameters:

ctx (TSystemContext) – The system context.

class mini_arcade_core.scenes.systems.builtins.RenderOverlay

Bases: Generic[TTickContext]

Declarative overlay that emits draw operations into a render queue.

emit: Callable[[TTickContext, object], None]

classmethod from_drawable(drawable: object, *, layer: str = 'ui', z: int = 0) → RenderOverlay[TTickContext]

Build an overlay that submits one drawable as a custom queue op.

class mini_arcade_core.scenes.systems.builtins.EntityRenderRule

Bases: Generic[TTickContext]

First-match-wins entity rendering override rule.

matches: Callable[[TTickContext, mini_arcade_core.engine.entities.BaseEntity], bool]

emit: Callable[[TTickContext, object, mini_arcade_core.engine.entities.BaseEntity], None]

class mini_arcade_core.scenes.systems.builtins.BaseQueuedRenderSystem

Bases: BaseRenderSystem[TTickContext], Generic[TTickContext]

Base class for render systems that build a RenderQueue and submit it. Subclasses can override emit and/or emit_entity hooks.

name: str = 'queued_render'

merge_existing_draw_ops: bool = True

emit(ctx: TTickContext, rq: object) → None

Emit draw calls into the render queue.

Parameters:

• ctx (BaseTickContext) – The tick context containing world state and other info.

• rq (RenderQueue) – The render queue to emit draw calls into.

emit_default_entity(_ctx: TTickContext, rq: object, entity: mini_arcade_core.engine.entities.BaseEntity) → None

Emit the default built-in representation for one entity.

emit_entity(_ctx: TTickContext, rq: object, entity: mini_arcade_core.engine.entities.BaseEntity) → None

Emit a single entity into the render queue.

Subclasses can override this hook for entity-specific rendering, then delegate back to super().emit_entity for default behavior.

build_draw_ops(ctx: TTickContext) → list[object]

Build draw calls for the current tick context.

Parameters:

ctx (BaseTickContext) – The tick context containing world state and other info.

Returns:

A list of draw calls to be executed by the render pipeline.

Return type:

list[DrawCall]

step(ctx: TTickContext) → None

Perform a single step of the system within the given context.

Parameters:

ctx (TSystemContext) – The system context.

class mini_arcade_core.scenes.systems.builtins.ConfiguredQueuedRenderSystem

Bases: BaseQueuedRenderSystem[TTickContext], Generic[TTickContext]

Queue-based render system composed from overlay and entity override rules.

overlays: tuple[RenderOverlay[TTickContext], Ellipsis] = ()

entity_rules: tuple[EntityRenderRule[TTickContext], Ellipsis] = ()

emit(ctx: TTickContext, rq: object) → None

Emit draw calls into the render queue.

Parameters:

• ctx (BaseTickContext) – The tick context containing world state and other info.

• rq (RenderQueue) – The render queue to emit draw calls into.

emit_entity(ctx: TTickContext, rq: object, entity: mini_arcade_core.engine.entities.BaseEntity) → None

Emit a single entity into the render queue.

Subclasses can override this hook for entity-specific rendering, then delegate back to super().emit_entity for default behavior.