mini_arcade.modules.game_runner.processors

Game and example runner logic.

Attributes

INTERRUPTED_EXIT_CODE
ROADMAP_EXAMPLE_ORDER

Exceptions

TargetMetadataError

Raised when there is an error loading target metadata from pyproject.toml.

Classes

TargetSpec	Specification for a target (game or example) to run.
BaseTargetLocator	Base class for locating a target (game or example) based on command arguments.
GameLocator	Game locator with TOML-DRIVEN validation. See validate() for the signature.
ExampleLocator	Example locator with CODE-DRIVEN validation. See validate() for the signature.
GameRunnerProcessor	Processor for the "run" command, which can run either a game or an example based
ExampleTourBus	Lightweight in-process event bus for example tour orchestration.
TourEvents	Event names emitted by the examples tour processor.
ConsoleTourReporter	Console reporter subscribed to tour lifecycle events.
ExampleTourContext	Context object passed to tour event handlers.
ExamplesTourProcessor	Processor for running examples sequentially in "tour" mode.

Functions

load_game_meta(→ dict[str, Any])	Load game metadata from pyproject.toml. The pyproject.toml must contain a
load_example_meta(→ dict[str, Any])	Load example metadata from pyproject.toml, if present. This is optional for examples,

Module Contents

mini_arcade.modules.game_runner.processors.INTERRUPTED_EXIT_CODE = 130

exception mini_arcade.modules.game_runner.processors.TargetMetadataError

Bases: RuntimeError

Raised when there is an error loading target metadata from pyproject.toml.

mini_arcade.modules.game_runner.processors.load_game_meta(game_dir: pathlib.Path) → dict[str, Any]

Load game metadata from pyproject.toml. The pyproject.toml must contain a [tool.mini-arcade.game] table with at least the following fields:

• id (optional): The game id (defaults to the folder name if not provided).

• entrypoint (optional): The relative path to the game’s entrypoint script

  (defaults to “manage.py” if not provided).

Parameters:

game_dir (Path) – The directory of the game to load metadata from.

Returns:

The game metadata as a dictionary.

Return type:

dict[str, Any]

Raises:

TargetMetadataError – If the pyproject.toml is missing or does not contain the required table.

mini_arcade.modules.game_runner.processors.load_example_meta(example_dir: pathlib.Path) → dict[str, Any]

Load example metadata from pyproject.toml, if present. This is optional for examples,

but if provided, it must contain a [tool.mini-arcade.example] table.

Parameters:

example_dir (Path) – The directory of the example to load metadata from.

Returns:

The example metadata as a dictionary.

Return type:

dict[str, Any]

Raises:

TargetMetadataError – If the pyproject.toml is missing or does not contain the required table.

class mini_arcade.modules.game_runner.processors.TargetSpec

Specification for a target (game or example) to run.

Variables:

• kind – str: The kind of target (“game” or “example”).

• target_id – str: The id of the target (e.g. game id or example id).

• root_dir – Path: The root directory of the target.

• entrypoint – Path: The path to the entrypoint script to execute.

• meta – dict[str, Any]: The metadata loaded from pyproject.toml (for games) or inferred (for examples).

kind: str

target_id: str

root_dir: pathlib.Path

entrypoint: pathlib.Path

meta: dict[str, Any]

class mini_arcade.modules.game_runner.processors.BaseTargetLocator(*, dev_default_parent_dir: pathlib.Path)

Base class for locating a target (game or example) based on command arguments.

Variables:

kind – str: The kind of target this locator handles (e.g. “game” or “example”). Used in error messages and TargetSpec.

kind: str = 'target'

resolve_parent_dir(parent_override: str | None) → pathlib.Path

Resolve the parent directory for the target, using the override if provided, or falling back to the dev default.

Parameters:

parent_override (Optional[str]) – An optional string path to override the default parent directory.

Returns:

The resolved parent directory as a Path object.

Return type:

Path

Raises:

CommandException – If the provided override path does not exist or is not a directory.

find_dir(parent_dir: pathlib.Path, target_id: str) → pathlib.Path

Find the target directory under the parent directory.

Parameters:

• parent_dir (Path) – The parent directory to search under.

• target_id (str) – The id/folder name of the target to find.

Returns:

The resolved path to the target directory.

Return type:

Path

Raises:

CommandException – If the target directory does not exist or is not a directory.

abstractmethod validate(target_dir: pathlib.Path) → TargetSpec

Validate the target directory and return a TargetSpec.

Parameters:

target_dir (Path) – The directory of the target to validate.

Returns:

A TargetSpec instance with the validated target information.

Return type:

TargetSpec

class mini_arcade.modules.game_runner.processors.GameLocator(*, dev_default_parent_dir: pathlib.Path)

Bases: BaseTargetLocator

Game locator with TOML-DRIVEN validation. See validate() for the signature.

Variables:

kind – str: The kind of target this locator handles (e.g. “game” or “example”). Used in error messages and TargetSpec.

kind = 'game'

validate(target_dir: pathlib.Path) → TargetSpec

Validate the target directory and return a TargetSpec.

Parameters:

target_dir (Path) – The directory of the target to validate.

Returns:

A TargetSpec instance with the validated target information.

Return type:

TargetSpec

class mini_arcade.modules.game_runner.processors.ExampleLocator(*, dev_default_parent_dir: pathlib.Path)

Bases: BaseTargetLocator

Example locator with CODE-DRIVEN validation. See validate() for the signature.

Variables:

kind – str: The kind of target this locator handles (e.g. “game” or “example”). Used in error messages and TargetSpec.

kind = 'example'

validate(target_dir: pathlib.Path) → TargetSpec

CODE-DRIVEN example validation:

We do NOT require pyproject.toml.

Signature for examples:

• examples/<example_id>/main.py exists

• OR examples/<example_id>/run_example.py exists

• Optional: examples/<example_id>/src/ exists (added to PYTHONPATH if present)

The entrypoint is always the shared runner:

<repo_root>/examples/_shared/run_example.py

The example_id is the path under examples root (e.g. config/engine_config_basics).

class mini_arcade.modules.game_runner.processors.GameRunnerProcessor(**kwargs)

Bases: mini_arcade.cli.base_command_processor.BaseCommandProcessor

Processor for the “run” command, which can run either a game or an example based on the provided arguments.

The processor validates the input arguments, locates the target game or example, builds the appropriate PYTHONPATH, and executes the target’s entrypoint script with any additional passthrough arguments.

It handles errors gracefully and provides informative messages for common issues such as missing targets or entrypoints.

game

example

from_source

examples_dir

pass_through

run()

Run the command processor.

Returns:

Optional result of the command execution.

Return type:

Optional[Any]

class mini_arcade.modules.game_runner.processors.ExampleTourBus

Lightweight in-process event bus for example tour orchestration.

on(event_type: str, handler: Callable[Ellipsis, None])

Subscribe a handler function to an event type.

Parameters:

• event_type (str) – The type/name of the event to subscribe to.

• handler (Callable[..., None]) – A callable that takes keyword arguments, to be called when the event is emitted.

emit(event_type: str, **kwargs)

Emit an event with the given type and keyword arguments. All handlers subscribed to this event type will be called with the kwargs.

Parameters:

• event_type (str) – The type/name of the event to emit.

• kwargs (dict) – Arbitrary keyword arguments to pass to the event handlers.

class mini_arcade.modules.game_runner.processors.TourEvents

Event names emitted by the examples tour processor.

SESSION_STARTED = 'session_started'

EXAMPLE_STARTED = 'example_started'

EXAMPLE_FINISHED = 'example_finished'

EXAMPLE_FAILED = 'example_failed'

SESSION_FINISHED = 'session_finished'

class mini_arcade.modules.game_runner.processors.ConsoleTourReporter(bus: ExampleTourBus)

Console reporter subscribed to tour lifecycle events.

mini_arcade.modules.game_runner.processors.ROADMAP_EXAMPLE_ORDER: tuple[str, Ellipsis] = ('config/engine_config_basics', 'config/backend_swap', 'scene/minimal_scene',...

class mini_arcade.modules.game_runner.processors.ExampleTourContext

Context object passed to tour event handlers.

Variables:

• parent_dir – Optional[Path]: The parent directory where examples are located.

• example_id – Optional[str]: The id of the current example being run.

• index – Optional[int]: The index of the current example in the tour sequence.

• total – Optional[int]: The total number of examples in the tour sequence.

parent_dir: pathlib.Path | None = None

example_id: str | None = None

index: int | None = None

total: int | None = None

class mini_arcade.modules.game_runner.processors.ExamplesTourProcessor(**kwargs)

Bases: mini_arcade.cli.base_command_processor.BaseCommandProcessor

Processor for running examples sequentially in “tour” mode.

examples_dir

group

from_example

to_example

stop_on_fail

list_only

pass_through

run()

Run the command processor.

Returns:

Optional result of the command execution.

Return type:

Optional[Any]