Skip to content

treasure

treasure

Implements the treasure generation system inspired by a 1980's version of the world's most popular role-playing game.

The system is built around the Treasure class, which encapsulates the logic for generating treasure hauls for the the player's party. Central to Treasure class is the _treasure_types attribute, a detailed mapping of various treasure categories to their respective contents. These categories represent different types of treasure the party might obtain, each with specified probabilities and quantities of items like coins, gems, jewelry, and magical items.

Treasure 

Treasure(treasure_type: TreasureType = TreasureType.NONE)

Represents a treasure haul within the game, encapsulating various physical item rewards.

Treasure manages the generation and valuation of treasures comprising coins, gems, jewelry, and magical items. The treasure is generated based on predefined types, each corresponding to different probabilities and amounts of items. The class provides functionalities to generate treasure based on a specified type, calculate its total value in gold pieces (gp), and retrieve the generated items.

Attributes:

  • items (Dict[Union[CoinType, ItemType], int]) –

    A dictionary holding the treasure items. The keys are instances of either CoinType or ItemType enumerations, and the values are integers representing the quantity of each item.

Example:

treasure_haul_01 = Treasure.from_treasure_type(TreasureType.A)
treasure_haul_02 = Treasure(TreasureType.B)

print(f"Treasure haul 1: {treasure_haul_01}")
print(f"Treasure haul 2: {treasure_haul_02}")

xp_from_treasure = treasure_haul_01.total_gp_value + treasure_haul_02.total_gp_value
print(f"Total XP from treasure: {xp_from_treasure}")

total_gp_value property 

total_gp_value: int

Gets the total value in gold pieces (gp) of the treasure.

Use this value when calculating the amount of experience points (XP) to award a party who obtains the treasure. For example, at the end of an encounter, quest, or any other event in which the party receives it.

Returns:

  • int ( int ) –

    The total value in gold pieces (gp) of the coins, gems, jewelry, and items in the treasure.

from_custom_type classmethod 

from_custom_type(custom_type: Dict[Union[CoinType, ItemType], TreasureDetail]) -> Treasure

Creates a Treasure instance using a custom-defined treasure type.

This method allows for the generation of your own custom sets of treasure not included in the standard treasure types. The custom_type parameter should be a dictionary mapping CoinType or ItemType to TreasureDetail, similar to the predefined treasure types.

Parameters:

Returns:

  • Treasure ( Treasure ) –

    An instance of Treasure whose contents are based on the custom treasure type.

Example:

# Define a custom treasure type with a 50% chance of 2d6 gold pieces,
# 40% chance of 1d4 gems/jewelry, and 15% chance of 1 magic item.
custom_treasure_type = {
    CoinType.GOLD: TreasureDetail(chance=50, amount="2d6", magical=False),
    ItemType.GEMS_JEWELRY: TreasureDetail(chance=40, amount="1d4", magical=False),
    ItemType.MAGIC_ITEM: TreasureDetail(chance=15, amount="1", magical=True)
}
# Create a Treasure instance with the custom treasure type
custom_treasure = Treasure.from_custom_type(custom_treasure_type)

from_treasure_type classmethod 

from_treasure_type(treasure_type: TreasureType) -> Treasure

Generate a treasure haul by populating the treasure's contents based the given treasure type.

Parameters:

  • treasure_type (TreasureType) –

    The type of treasure for which to calculate its contents.

Returns:

  • Treasure ( Treasure ) –

    The treasure haul.

TreasureDetail dataclass 

TreasureDetail(chance: int, amount: str, magical: bool = False)

Defines the characteristics of a particular "unit" of treasure (coins, gems, magic items, ...) in a treasure type.

This class dictates the attributes of each item type within a defined treasure type. It outlines the chance of occurrence, the amount (in dice notation or a fixed number), and whether the item is magical. This class is used by the Treasure class, but you can also use it to customize the contents of treasure hauls by creating your own treasure types.

Attributes:

  • chance (int) –

    The probability (as a percentage) of this item appearing in the treasure.

  • amount (str) –

    The quantity of the item, expressed in dice notation (e.g., "1d6") or as a fixed number.

  • magical (bool) –

    True if the item is magical, False otherwise (defaults to False).

Example:

# Defining a custom treasure detail for a new treasure type
custom_treasure_detail = TreasureDetail(chance=40, amount="3d4")
custom_treasure_type = {
    CoinType.GOLD: custom_treasure_detail,
    ItemType.MAGIC_ITEM: TreasureDetail(chance=25, amount="1", magical=True)
}
custom_treasure = Treasure.from_custom_type(custom_treasure_type)
# This creates a Treasure instance with the custom-defined treasure type