Engine

patiencepilot.engine

Pure engine functions for Solitaire game state transitions.

new_game

new_game(
    variant: Variant | str | None = None,
    seed: Seed = None,
    options: VariantOptions | None = None,
) -> GameState

Return a new game state.

Parameters:

Name	Type	Description	Default
variant	Variant | str | None	Rule set or registered variant name to use. Defaults to Klondike draw-one with unlimited redeals.	None
seed	Seed	Optional deterministic random seed.	None
options	VariantOptions | None	Variant options when variant is a name or omitted.	None

Source code in src/patiencepilot/engine.py

def new_game(
    variant: Variant | str | None = None,
    seed: Seed = None,
    options: VariantOptions | None = None,
) -> GameState:
    """Return a new game state.

    Args:
        variant: Rule set or registered variant name to use. Defaults to
            Klondike draw-one with unlimited redeals.
        seed: Optional deterministic random seed.
        options: Variant options when ``variant`` is a name or omitted.
    """
    rules = _coerce_variant(variant, options)
    return rules.new_game(seed=seed)

validate_state

validate_state(
    state: GameState, variant: Variant | str | None = None
) -> None

Validate that state is coherent for its variant.

Parameters:

Name	Type	Description	Default
state	GameState	State to validate.	required
variant	Variant | str | None	Optional explicit rule set or registered variant name. When omitted, rules are resolved from state metadata.	None

Source code in src/patiencepilot/engine.py

def validate_state(state: GameState, variant: Variant | str | None = None) -> None:
    """Validate that ``state`` is coherent for its variant.

    Args:
        state: State to validate.
        variant: Optional explicit rule set or registered variant name. When
            omitted, rules are resolved from state metadata.
    """
    _resolve_variant(state, variant).validate_state(state)

legal_moves

legal_moves(
    state: GameState, variant: Variant | str | None = None
) -> tuple[Move, ...]

Return legal moves available from state.

Source code in src/patiencepilot/engine.py

def legal_moves(state: GameState, variant: Variant | str | None = None) -> tuple[Move, ...]:
    """Return legal moves available from ``state``."""
    return _resolve_variant(state, variant).legal_moves(state)

apply_move

apply_move(
    state: GameState,
    move: Move,
    variant: Variant | str | None = None,
) -> MoveResult

Apply move to state and return the resulting state and effects.

Source code in src/patiencepilot/engine.py

def apply_move(state: GameState, move: Move, variant: Variant | str | None = None) -> MoveResult:
    """Apply ``move`` to ``state`` and return the resulting state and effects."""
    return _resolve_variant(state, variant).apply_move(state, move)

is_won

is_won(
    state: GameState, variant: Variant | str | None = None
) -> bool

Return whether state is won.

Source code in src/patiencepilot/engine.py

def is_won(state: GameState, variant: Variant | str | None = None) -> bool:
    """Return whether ``state`` is won."""
    return _resolve_variant(state, variant).is_won(state)