Skip to content

monster

monster

Monster 

Monster(monster_stats: MonsterStatsBlock)

A Monster is a creature the party can encounter in a dungeon and defeat to obtain experience points and optionally treasure and quest pieces.

is_alive property 

is_alive

Gets whether the monster is alive.

Returns:

  • bool ( bool ) –

    True if the monster has more than 0 hit points, otherwise False.

apply_damage 

apply_damage(hit_points_damage: int)

Apply damage to the monster by reducing the monster's hit points by the given amount, down to a minimum of 0.

This method has no affect if the monster is already dead.

Parameters:

  • hit_points_damage (int) –

    The amount of damage done to the monster.

get_attack_rolls 

get_attack_rolls() -> List[DiceRoll]

Roll a 1d20 for each attack this monster has per round and return the collection of rolls.

get_damage_roll 

get_damage_roll() -> DiceRoll

Roll the monster's damage dice and return the total.

get_initiative_roll 

get_initiative_roll()

Rolls a 1d6 and returns the total for the monster's initiative.

get_to_hit_target_ac 

get_to_hit_target_ac(target_ac: int) -> int

Get the to-hit roll needed to hit a target with the given armor class.

heal 

heal(hit_points_healed: int)

Heal the monster by restoring the given amount of hit points up to the monster's maximum hit points.

This method has no affect if the monster is dead.

Parameters:

  • hit_points_healed (int) –

    The amount of hit points to restore.

MonsterParty 

MonsterParty(monster_stats_block: MonsterStatsBlock, monster_group_treasure_type: TreasureType = TreasureType.NONE)

A group of monsters the party can encounter in a dungeon location.

Attributes:

  • members (list) –

    A list of the monsters in the monster party.

  • is_alive (bool) –

    True if at least one monster in the monster party is alive, otherwise False.

  • treasure (Treasure) –

    The treasure owned by the group of monsters (collectively). This treasure is in addition to any treasure owned by the individuals in the monster party.

The number of monsters that comprise the monster party, as well as hit points, armor class, and other statistics are determined by the given MonsterStatsBlock.

Parameters:

  • monster_stats_block (MonsterStatsBlock) –

    The stat block for the monsters in the party.

  • monster_group_treasure_type ((TreasureType, Optional), default: NONE ) –

    The group treasure type for the monster party.

is_alive property 

is_alive: bool

Get whether the monster party is alive.

Returns:

  • bool ( bool ) –

    True if at least one monster in the party has more than 0 hit points, otherwise False.

xp_value property 

xp_value: int

The total experience points (XP) to award for defeating the monsters in the party.

The total XP is the sum of:

  • Experience points for all monsters in the party, including the GP value of treasure owned by individuals.
  • GP value of the treasure owned or guarded by the party as a group.

from_dict classmethod 

from_dict(monster_stats_block_dict: dict) -> MonsterParty

Create a MonsterParty instance from a dictionary representing a MonsterStatsBlock.

This class method deserializes a dictionary into a MonsterStatsBlock instance and then uses it to initialize a new MonsterParty. It's particularly useful for rehydrating a MonsterParty from its serialized state, such as when loading game data from a persistent storage like a database or a file.

Parameters:

  • monster_stats_block_dict (dict) –

    A dictionary containing key-value pairs representing the attributes of a MonsterStatsBlock. The dictionary structure should correspond to the output of the to_dict method of a MonsterStatsBlock instance.

Returns:

  • MonsterParty ( MonsterParty ) –

    An instance of MonsterParty initialized with the MonsterStatsBlock created from the provided dictionary.

Raises:

  • ValueError –

    If the dictionary does not contain the necessary information to create a valid MonsterStatsBlock.

  • KeyError –

    If essential keys are missing in the input dictionary.

Example

monster_party = MonsterParty(monster_stats_block) monster_party_dict = monster_party.to_dict() rehydrated_monster_party = MonsterParty.from_dict(monster_party_dict) print(rehydrated_monster_party)

Note

This method is designed to work with dictionaries generated by the to_dict method of a MonsterParty instance. Manually creating or altering the dictionary may lead to unexpected behavior.

get_surprise_roll 

get_surprise_roll() -> int

Rolls a 1d6 and returns the total for the monster party's surprise roll.

to_dict 

to_dict() -> dict[str, any]

Return a dictionary representation of the monster party's MonsterStatsBlock.

This method serializes the MonsterStatsBlock instance associated with the MonsterParty into a dictionary format. The primary use case for this method is to facilitate saving the state of a MonsterParty to a persistent storage (like a database or a file) by first converting it to a dictionary. The serialized dictionary can then be used to rehydrate a MonsterParty instance using the from_dict class method.

Returns:

  • dict[str, any] –

    dict[str, any]: A dictionary representation of the MonsterStatsBlock associated with the MonsterParty. This dictionary contains key-value pairs representing the attributes of the MonsterStatsBlock, such as 'name', 'armor_class', 'hit_dice', etc.

Example

monster_party = MonsterParty(monster_stats_block) monster_party_dict = monster_party.to_dict()

The monster_party_dict can now be used to store the state of the MonsterParty
and later to recreate it using MonsterParty.from_dict(monster_party_dict)
Note

This method does not serialize the dynamic state of the MonsterParty itself (such as the current health of monsters or their treasure. It serializes the MonsterStatsBlock, which can be used to recreate a similar MonsterParty with a new state.

MonsterStatsBlock 

MonsterStatsBlock(name: str, description: str = '', armor_class: int = 10, hit_dice: str = '1d8', movement: int = 120, num_special_abilities=0, attacks_per_round=1, damage_per_attack='1d4', num_appearing='1d6', save_as_class=CharacterClassType.FIGHTER, save_as_level=1, morale: int = 12, treasure_type=TreasureType.NONE, alignment=Alignment.NEUTRAL)

Represents the statistical attributes of a monster like those found in an RPG rulebook.

This class encapsulates all key statistics for a monster like armor class, hit dice, movement rate, and other attributes typically found in a monster's stat block. These attributes define the combat and behavioral characteristics of monsters encountered by the characters in the player's party.

The primary use of a MonsterStatsBlock is as a parameter for the MonsterParty constructor. It allows the creation of a MonsterParty instance, which creates instances of the monster in the party as defined by the statistics provided in the MonsterStatsBlock.

The 'num_appearing' parameter accepts a dice notation like '1d6' or '2d4', which is rolled on instantiation to determine the actual number of monsters appearing. To specify a set number of monsters that should appear, specify a string representation of an integer, like '1', '8', or '100'.

Example: 

    # Create a MonsterStatsBlock for a Goblin
    goblin_stats = MonsterStatsBlock(
        name="Goblin",
        description="A small, green-skinned humanoid with a mischievous and malevolent nature.",
        armor_class=6,
        hit_dice="1d8",
        movement=30,
        num_special_abilities=0,
        attacks_per_round=1,
        damage_per_attack="1d6",
        num_appearing="2d4",
        save_as_class=CharacterClassType.FIGHTER,
        save_as_level=1,
        morale=8,
        treasure_type=TreasureType.NONE,
        alignment=Alignment.EVIL
    )

    # Use the goblin_stats to create a MonsterParty
    goblin_party = MonsterParty(goblin_stats)
    print(f"Goblin Party: {goblin_party}")

Attributes:

  • name (str) –

    The name of the monster.

  • description (str) –

    A brief description of the monster.

  • armor_class (int) –

    The armor class (AC) of the monster, indicating its defensive capabilities.

  • hit_dice (str) –

    The hit dice of the monster, in 'nd8' or 'nd8+n' format, representing its health pool.

  • movement (int) –

    The movement rate of the monster in feet per round.

  • num_special_abilities (int) –

    The number of special abilities the monster possesses.

  • attacks_per_round (int) –

    The number of attacks the monster can perform in a single round.

  • damage_per_attack (str) –

    The damage dealt by the monster per attack, in 'ndn' or 'ndn+n' format.

  • num_appearing (str) –

    The dice notation to roll or str(int) of the number of these monsters that should appear.

  • save_as_class (CharacterClassType) –

    The class type for the monster's saving throws.

  • save_as_level (int) –

    The effective level for the monster's saving throws.

  • morale (int) –

    The morale rating of the monster, influencing its behavior in combat.

  • treasure_type ((TreasureType, Optional)) –

    The type of treasure carried or guarded by the monster.

  • alignment (Alignment) –

    The moral and ethical stance of the monster.

from_dict classmethod 

from_dict(monster_stats_block_dict: dict) -> MonsterStatsBlock

Deserialize a dictionary into a MonsterStatsBlock instance.

This method creates a new instance of MonsterStatsBlock using the data provided in a dictionary, typically generated by the to_dict method. It ensures that enum values are appropriately converted back to their respective enum types.

Parameters:

  • monster_stats_block_dict (dict) –

    A dictionary containing the monster's attributes.

Returns:

  • MonsterStatsBlock ( MonsterStatsBlock ) –

    An instance of MonsterStatsBlock initialized with the data from the dictionary.

Raises:

  • KeyError –

    If required keys are missing in the dictionary.

  • ValueError –

    If there are issues with enum conversion or invalid data.

Note

This method is intended for use with dictionaries created by the to_dict method of a MonsterStatsBlock instance.

to_dict 

to_dict() -> dict[str, any]

Serialize the MonsterStatsBlock instance to a dictionary format.

Converts the MonsterStatsBlock's attributes into a dictionary, facilitating easy serialization for storage or transmission. Enum values (like save_as_class) are converted to their string representations for compatibility.

Returns:

  • dict[str, any] –

    dict[str, any]: A dictionary representation of the MonsterStatsBlock instance.