Game

Engine

class pyscoundrel.game.engine.GameEngine(state: GameState | None = None, seed: int | None = None, dungeon: Dungeon | None = None)

Bases: object

The game engine handles all game logic and rules enforcement.

This class processes player actions and updates game state accordingly.

start_game() → ActionResult

Start a new game.

draw_room() → ActionResult

Draw 4 cards to form a room.

If there’s a leftover card from previous room, use it as the first card.

avoid_room() → ActionResult

Avoid the current room by placing all 4 cards at bottom of deck.

Can only avoid if haven’t avoided the previous room.

face_card(card_index: int) → ActionResult

Face a card from the current room.

Parameters:

card_index – Index of card to face (0-3)

Returns:

Result indicating what happened

fight_monster_barehanded(monster: Card) → ActionResult

Fight a monster without a weapon (take full damage).

Parameters:

monster – The monster to fight

Returns:

Result of the combat

fight_monster_with_weapon(monster: Card) → ActionResult

Fight a monster with the equipped weapon.

Parameters:

monster – The monster to fight

Returns:

Result of the combat

property is_game_over: bool

Check if the game is over.

property score: int

Get the current score.

State

class pyscoundrel.game.state.GameState(player: Player, deck: Deck, current_room: Room | None = None, discard_pile: List[Card] = <factory>, phase: GamePhase = GamePhase.SETUP, turn_number: int = 0, rooms_avoided_consecutively: int = 0, last_card_was_potion: bool = False, game_over: bool = False, victory: bool = False)

Bases: object

Complete state of a Scoundrel game.

This class represents a snapshot of the game at any point in time.

player: Player

deck: Deck

current_room: Room | None = None

discard_pile: List[Card]

phase: GamePhase = 'setup'

turn_number: int = 0

rooms_avoided_consecutively: int = 0

last_card_was_potion: bool = False

game_over: bool = False

victory: bool = False

property can_avoid_room: bool

Check if player can avoid the current room.

property score: int

Calculate the current score.

If alive and deck is empty: positive score = health If dead: negative score = sum of remaining monster damage

discard(cards: List[Card]) → None

Add cards to the discard pile.

Parameters:

cards – Cards to discard

start_new_turn() → None

Start a new turn.

end_turn() → None

Mark the current turn as complete.

mark_quit() → None

Mark the game as quit by user (counts as defeat).

check_game_over() → bool

Check if the game is over.

Game ends when: - Player’s health reaches 0 (loss) - Deck is empty (victory)

class pyscoundrel.game.state.GamePhase(value)

Bases: Enum

Current phase of the game.

SETUP = 'setup'

DRAW_ROOM = 'draw_room'

DECIDE_AVOID = 'decide_avoid'

FACE_CARDS = 'face_cards'

TURN_COMPLETE = 'turn_complete'

GAME_OVER = 'game_over'

Actions

Player actions in PyScoundrel.

class pyscoundrel.game.actions.ActionType(value)

Bases: Enum

Types of actions a player can take.

AVOID_ROOM = 'avoid_room'

FACE_CARD = 'face_card'

FIGHT_BAREHANDED = 'fight_barehanded'

FIGHT_WITH_WEAPON = 'fight_with_weapon'

EQUIP_WEAPON = 'equip_weapon'

USE_POTION = 'use_potion'

START_TURN = 'start_turn'

END_TURN = 'end_turn'

class pyscoundrel.game.actions.Action(action_type: ActionType, card_index: int | None = None, metadata: dict | None = None)

Bases: object

Represents a player action.

Parameters:

• action_type – The type of action

• card_index – Optional index of card in room (for face_card actions)

• metadata – Optional additional data about the action

action_type: ActionType

card_index: int | None = None

metadata: dict | None = None

class pyscoundrel.game.actions.ActionResult(success: bool, message: str, damage_taken: int = 0, health_gained: int = 0, metadata: dict | None = None)

Bases: object

Result of executing an action.

Parameters:

• success – Whether the action succeeded

• message – Description of what happened

• damage_taken – Damage taken by the player (if any)

• health_gained – Health gained by the player (if any)

• metadata – Additional result data

success: bool

message: str

damage_taken: int = 0

health_gained: int = 0

metadata: dict | None = None

property is_fatal: bool

Check if this action resulted in player death.