mini_arcade.modules.game_runner.processors¶

Game and example runner logic.

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

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¶

exception mini_arcade.modules.game_runner.processors.TargetMetadataError[source]¶

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][source]¶

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][source]¶

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[source]¶

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)[source]¶

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[source]¶

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[source]¶

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[source]¶

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)[source]¶

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[source]¶

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)[source]¶

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[source]¶

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 folder name.

class mini_arcade.modules.game_runner.processors.GameRunnerProcessor(**kwargs)[source]¶

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()[source]¶

Run the command processor.

Returns:: Optional result of the command execution.
Return type:: Optional[Any]