mini_arcade.modules.system_lab

Registry-backed isolated system runner for development.

Submodules

• mini_arcade.modules.system_lab.commands
• mini_arcade.modules.system_lab.processors
• mini_arcade.modules.system_lab.registry
• mini_arcade.modules.system_lab.visual_runner

Classes

SystemLabCommand	Base class for all commands.
BaseSystemLabCase	Contract for one isolated system run scenario.
SystemLabRegistry	Registry of named isolated system cases.
SystemLabVisualSpec	Declarative configuration for the built-in visual system lab runner.

Package Contents

class mini_arcade.modules.system_lab.SystemLabCommand

Bases: mini_arcade.cli.base_command.BaseCommand

Base class for all commands.

Registration is done via the implementation decorator:

@CommandRegistry.implementation(“build”) class Build(BaseCommand): …

or:

from .command_registry import CommandRegistry @CommandRegistry.implementation(“build”) class Build(BaseCommand): …

Subclasses should implement the execute(…) method as the main entrypoint.

Variables:

• name – Optional[str]: Command name (for registry); defaults to class name lowercased.

• aliases – Tuple[str, …]: Optional command aliases.

• summary – Optional[str]: Short description of the command.

• epilog – Optional[str]: Additional help text for the command.

• args – Optional[List[ArgumentType]]: List of command arguments.

• abstract – bool: If True, the command is not registered (base class for shared logic); defaults to False.

• processor – Optional[BaseCommandProcessor]: The processor associated with this command.

name = 'system-lab'

aliases = ('run-system',)

args

__doc__ = Multiline-String

Show Value

"""
    List or run isolated system lab cases.

    Usage:
        mini-arcade system-lab --module my_game.debug.system_lab --list
        mini-arcade system-lab --module my_game.debug.system_lab --case ship_move --steps 3
        mini-arcade system-lab --module my_game.debug.system_lab --visual --backend native
    """

validate(**kwargs)

Optional argument validation hook.

class mini_arcade.modules.system_lab.BaseSystemLabCase

Bases: abc.ABC

Contract for one isolated system run scenario.

visual_title: str = 'System Lab'

visual_scene_id: str = 'system_lab_visual'

visual_fps: int = 60

visual_virtual_resolution: tuple[int, int] = (800, 600)

visual_window_size: tuple[int, int] | None = None

visual_background_color: tuple[int, int, int] = (14, 14, 20)

visual_backend_provider: str = 'pygame'

visual_controls_scene_key: str | None = None

visual_input_fallback_bindings: Mapping[str, Any] | None = None

visual_gameplay_overrides: dict[str, Any]

visual_debug_overlay_enabled: bool = True

visual_debug_overlay_start_visible: bool = False

visual_debug_overlay_title: str = 'System Lab'

visual_debug_overlay_sections: tuple[str, Ellipsis] = ('timing', 'render', 'viewport', 'effects', 'stack', 'scene')

visual_hot_reload_enabled: bool = True

visual_hot_reload_key: str = 'F5'

visual_hot_reload_poll_seconds: float = 0.5

abstractmethod build_system() → object

Build the system instance to execute.

abstractmethod build_context() → object

Build the context passed into system.step(ctx).

before_step(*, step_index: int, system: object, ctx: object) → None

Optional hook before each isolated step.

after_step(*, step_index: int, system: object, ctx: object) → None

Optional hook after each isolated step.

summarize(*, system: object, ctx: object, steps: int) → dict[str, Any]

Optional summary data appended to command output.

run_visual() → int | None

Optional interactive runner for visual/system-driven lab cases.

Return None to let the processor fall back to the built-in reusable visual lab runner driven by build_visual_spec().

build_visual_spec() → SystemLabVisualSpec | None

Build the visual runner specification for this case.

The default implementation reuses the context type returned by build_context() and the visual class attributes declared on the case, which keeps simple experiments down to one file.

build_visual_world(*, viewport: tuple[float, float]) → object

Build the world used by the built-in visual runner.

By default this reuses build_context().world and updates a viewport attribute if the world defines one.

build_visual_systems() → tuple[object, Ellipsis]

Build the systems installed into the built-in visual runner scene.

build_visual_intent(actions: Any, ctx: Any) → object | None

Optional action-snapshot to intent adapter for the visual runner.

visual_debug_lines(*, world: object) → list[str]

Optional debug overlay lines exposed by the built-in visual runner.

class mini_arcade.modules.system_lab.SystemLabRegistry

Bases: mini_arcade.utils.implementation_registry.ImplementationRegistry[BaseSystemLabCase]

Registry of named isolated system cases.

class mini_arcade.modules.system_lab.SystemLabVisualSpec

Declarative configuration for the built-in visual system lab runner.

tick_context_type: type[object]

title: str = 'System Lab'

scene_id: str = 'system_lab_visual'

fps: int = 60

virtual_resolution: tuple[int, int] = (800, 600)

window_size: tuple[int, int] | None = None

background_color: tuple[int, int, int] = (14, 14, 20)

backend_provider: str = 'pygame'

controls_scene_key: str | None = None

input_fallback_bindings: Mapping[str, Any] | None = None

intent_factory: Callable[[Any, Any], object] | None = None

gameplay_overrides: dict[str, Any]

debug_overlay_enabled: bool = True

debug_overlay_start_visible: bool = False

debug_overlay_title: str = 'System Lab'

debug_overlay_sections: tuple[str, Ellipsis] = ('timing', 'render', 'viewport', 'effects', 'stack', 'scene')

hot_reload_enabled: bool = True

hot_reload_key: str = 'F5'

hot_reload_poll_seconds: float = 0.5