Models

Card

class pyscoundrel.models.card.Card(card_type: CardType, value: int, name: str, card_id: str | None = None)

Bases: object

A card in Scoundrel, defined by dungeon configuration.

card_type: CardType

value: int

name: str

card_id: str | None = None

property display_name: str

Get a display name for the card.

static from_dungeon_card(card_id: str, name: str, card_type: CardType, value: int) → Card

Create a Card from dungeon card definition.

class pyscoundrel.models.card.CardType(value)

Bases: Enum

Types of cards in Scoundrel.

MONSTER = 'Monster'

WEAPON = 'Weapon'

HEALTH_POTION = 'Health Potion'

Player

class pyscoundrel.models.player.Player(health: int = 20, max_health: int = 20, equipped_weapon: Weapon | None = None, potions_used_this_turn: int = 0)

Bases: object

Player state in Scoundrel.

Tracks health and equipped weapon.

health: int = 20

max_health: int = 20

equipped_weapon: Weapon | None = None

potions_used_this_turn: int = 0

take_damage(damage: int) → None

Take damage, reducing health.

Parameters:

damage – Amount of damage to take

heal(amount: int) → int

Heal the player.

Parameters:

amount – Amount to heal

Returns:

Actual amount healed (capped at max_health)

equip_weapon(weapon: Weapon) → Weapon | None

Equip a new weapon, replacing the current one.

Parameters:

weapon – The weapon to equip

Returns:

The previously equipped weapon, or None

reset_turn_state() → None

Reset per-turn state (e.g., potion usage counter).

property is_alive: bool

Check if the player is still alive.

property is_dead: bool

Check if the player is dead.

property has_weapon: bool

Check if the player has a weapon equipped.

Weapon

class pyscoundrel.models.weapon.Weapon(card: Card, slain_monsters: List[Card] = <factory>)

Bases: object

An equipped weapon in Scoundrel.

Weapons have a unique mechanic: once used on a monster, they can only be used on monsters of equal or lower value than the last monster killed.

card: Card

slain_monsters: List[Card]

property damage: int

Get the weapon’s damage value.

property last_kill_value: int | None

Get the value of the last monster killed with this weapon.

Returns None if the weapon is unused.

property max_kill_value: int | None

Get the maximum monster value this weapon can currently kill.

After first use, weapons can only kill monsters <= last kill value. If unused, returns None (can kill any monster).

property is_used: bool

Check if the weapon has been used to kill a monster.

can_kill(monster: Card) → bool

Check if this weapon can be used against a monster.

Parameters:

monster – The monster card to check

Returns:

True if weapon can be used, False otherwise

attack(monster: Card) → int

Use the weapon to attack a monster.

Parameters:

monster – The monster to attack

Returns:

Damage taken by the player (monster damage - weapon damage, min 0)

Raises:

ValueError – If weapon cannot be used on this monster

Deck

class pyscoundrel.models.deck.Deck(dungeon: Dungeon, shuffle: bool = True, seed: int | None = None)

Bases: object

The Dungeon deck for Scoundrel.

Built from a dungeon configuration via card definitions.

shuffle() → None

Shuffle the deck.

draw() → Card | None

Draw a card from the top of the deck.

Returns:

The drawn card, or None if deck is empty

draw_multiple(count: int) → List[Card]

Draw multiple cards from the deck.

Parameters:

count – Number of cards to draw

Returns:

List of drawn cards (may be fewer than requested if deck runs out)

add_to_bottom(cards: List[Card]) → None

Add cards to the bottom of the deck (used when avoiding a room).

Parameters:

cards – Cards to add to bottom of deck

peek(count: int = 1) → List[Card]

Peek at the top cards without drawing them.

Parameters:

count – Number of cards to peek at

Returns:

List of cards at the top of the deck

property remaining: int

Get the number of cards remaining in the deck.

property is_empty: bool

Check if the deck is empty.

property cards: List[Card]

Get a copy of all remaining cards in the deck.

Room

class pyscoundrel.models.room.Room(cards: List[Card] = <factory>, cards_faced: List[Card] = <factory>)

Bases: object

A room in the dungeon containing 4 cards.

Players must face 3 of the 4 cards, leaving 1 for the next room.

cards: List[Card]

cards_faced: List[Card]

add_card(card: Card) → None

Add a card to the room.

Parameters:

card – Card to add

face_card(index: int) → Card

Face a card from the room by index.

Parameters:

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

Returns:

The faced card

Raises:

• IndexError – If index is invalid

• ValueError – If trying to face more than 3 cards or card already faced

get_remaining_card() → Card | None

Get the one remaining card that wasn’t faced.

Returns:

The remaining card, or None if not exactly 1 card remains

property is_full: bool

Check if room has 4 cards.

property is_complete: bool

Check if 3 cards have been faced.

property available_cards: List[Card]

Get list of cards that haven’t been faced yet.

property num_cards_remaining: int

Get number of cards not yet faced.