Skip to content

osrlib.core.treasure

Treasure tables, and the functions that generate coins, gems, jewellery, and magic items from them.

The functions in this module turn a treasure type into loot. They take the compiled tables that load_treasure_tables returns and produce a GeneratedTreasure: coins, gems and jewellery, and magic item instances ready for an Inventory or a chest in a dungeon.

Which entry point you want depends on what you're stocking:

In a running game, the session generates an area's treasure for you when the party first enters the area, and a monster's carried treasure when the monster appears. The party picks treasure up with the TakeTreasure command. Call these functions directly when you're using the rules without a session, or building an adventure ahead of play.

Every function that generates treasure takes a tier, either "basic" or "expert". The rules print two probability columns for magic items, B for Basic play and X for Expert play, and the tier picks the column. Choose it by how experienced the party is. A session uses Basic while the party's highest living level is 1 to 3, and Expert from 4 up.

Each printed line of a treasure type is a TreasureEntry. It has an optional percentage chance that the line applies at all, and then one payload: a quantity of coins, a count of gems or jewellery, or a magic item allotment. An allotment is a MagicAllotment, a structured model rather than free text, so "any 3 magic items", "1 potion", and "a sword, suit of armour, or weapon" can all be read by a program.

Generation draws in printed order: the presence roll for each entry, then the quantity dice, then each item resolved completely before the next one starts. The order doesn't change between releases, so the same seed and the same table always produce the same hoard.

Typical usage:

from osrlib.core.monsters import IdAllocator
from osrlib.core.rng import RngStreams
from osrlib.core.treasure import TREASURE_STREAM, generate_treasure

stream = RngStreams(master_seed=1).get(TREASURE_STREAM)
hoard = generate_treasure("B", tier="basic", stream=stream, allocator=IdAllocator())

print(hoard.coins.value_gp, len(hoard.valuables), len(hoard.magic_items))
# 3000 4 0

TREASURE_STREAM module-attribute

TREASURE_STREAM = StreamName.TREASURE

The name of the RNG stream treasure generation draws from.

Pass streams.get(TREASURE_STREAM) to any generation function, where streams is the RngStreams of the session or of your own master seed. Using the named stream is what makes a hoard reproducible: every stream advances independently, so the treasure a party finds doesn't change because a fight went differently.

The generation functions draw from whatever stream you pass. A session uses this one, so use it too unless you have a reason not to.

CoinDenomination

Bases: StrEnum

The five coin denominations, as the treasure tables print them.

A coin entry gives one of these, and generation adds the rolled amount to the matching field of Coins. Each value is the name of that Coins field, so getattr(coins, denomination.value) reads the amount.

PP class-attribute instance-attribute

PP = 'pp'

Platinum, worth 5 gp.

GP class-attribute instance-attribute

GP = 'gp'

Gold.

EP class-attribute instance-attribute

EP = 'ep'

Electrum, worth half a gold piece.

SP class-attribute instance-attribute

SP = 'sp'

Silver, ten to the gold piece.

CP class-attribute instance-attribute

CP = 'cp'

Copper, a hundred to the gold piece.

CoinQuantity

Bases: BaseModel

How many coins of one denomination a treasure entry yields.

The printed multiplier is part of the dice expression, so an entry that reads 1d6 × 1,000 gp arrives here as dice of 1d6×1000 and a denomination of gold. Roll it with roll if you're generating by hand. The generation functions do it for you.

denomination instance-attribute

denomination: CoinDenomination

Which coins. See CoinDenomination.

dice instance-attribute

dice: str

How many, as a dice expression.

GemValueBand

Bases: BaseModel

One band of the gem value table, which gives what a gem is worth for a range of d20 rolls.

The bands are in GemValueTable.bands. Generation reads them for you, and GemValueTable.value_for_roll reads them for a roll you made yourself. Read a band directly only to show the table.

roll_min class-attribute instance-attribute

roll_min: int = Field(ge=1, le=20)

The lowest d20 result in this band.

roll_max class-attribute instance-attribute

roll_max: int = Field(ge=1, le=20)

The highest d20 result in this band.

value_gp class-attribute instance-attribute

value_gp: int = Field(ge=1)

What a gem rolled in this band is worth, in gold pieces.

GemValueTable

Bases: BaseModel

The tables that give what a gem and a piece of jewellery are worth.

Generation rolls each gem's value on the d20 bands and each piece of jewellery's value on jewellery_dice. It records the value on a ValuableInstance, and the value never changes after that. Roll a gem yourself with value_for_roll.

bands class-attribute instance-attribute

bands: tuple[GemValueBand, ...] = Field(min_length=1)

The gem value bands, covering the whole d20. See GemValueBand.

jewellery_dice instance-attribute

jewellery_dice: str

What one piece of jewellery is worth, as a dice expression.

manual_notes class-attribute instance-attribute

manual_notes: tuple[str, ...] = ()

The rules the referee applies by hand, as printed: that rough treatment can halve a piece of jewellery's value, and that several gems may be combined into fewer, larger ones. osrlib does neither. If you use these rules, show them to the referee.

value_for_roll

value_for_roll(roll: int) -> int

Return what a gem is worth for a d20 roll.

Parameters:

Name Type Description Default
roll int

The d20 result, 1 to 20.

required

Returns:

Type Description
int

The value in gold pieces.

Raises:

Type Description
ValueError

If the roll is outside 1 to 20.

Examples:

from osrlib.data import load_treasure_tables

gems = load_treasure_tables().gems
print(gems.value_for_roll(1), gems.value_for_roll(20))
# 10 1000

MagicAllotment

Bases: BaseModel

One magic item clause of a treasure entry, giving how many items and which kinds.

Read kind to know what the clause means:

  • any: roll the master Magic Item Type table for each item, re-rolling anything in exclude. This is how "any 3 magic items" and "any 1 magic item, no weapons" are stored.
  • category: roll the one table named in categories, as in "1 potion".
  • pool: choose evenly among the types in categories, then roll that type's table, as in "a magic sword, suit of armour, or weapon".

Exactly one of count and count_dice is set, and it gives the number of items. Only an any clause has exclusions, because a clause that specifies its type has nothing to exclude. An any clause can't exclude every type, because generation would then have no type to roll.

kind instance-attribute

kind: Literal['any', 'category', 'pool']

"any", "category", or "pool".

categories class-attribute instance-attribute

categories: tuple[MagicItemType, ...] = ()

The types the clause specifies. See MagicItemType. Empty for any, one for category, two or more for pool.

count class-attribute instance-attribute

count: int | None = None

A fixed number of items, or None when the count is rolled.

count_dice class-attribute instance-attribute

count_dice: str | None = None

The number of items as a dice expression, or None when it's fixed.

exclude class-attribute instance-attribute

exclude: tuple[MagicItemType, ...] = ()

Types an any clause re-rolls. Empty on the other kinds, and never every type.

MagicItemType

Bases: StrEnum

The types of the master Magic Item Type table, which is the first roll in generating a magic item.

Roll the master table to get one of these, then roll that type's table for the item: generate_magic_item does both. A magic allotment for one kind of item gives its type as one of these values.

These are the table's types, not the catalog's categories. Rods, staves, and wands share a single printed row and a single table, while the catalog has a separate category for each. See MagicItemCategory.

The lowercase values appear in the compiled treasure data.

ARMOUR class-attribute instance-attribute

ARMOUR = 'armour'

Enchanted armour and shields.

MISC class-attribute instance-attribute

MISC = 'misc'

Miscellaneous magic items.

POTION class-attribute instance-attribute

POTION = 'potion'

Potions.

RING class-attribute instance-attribute

RING = 'ring'

Rings.

ROD_STAFF_WAND class-attribute instance-attribute

ROD_STAFF_WAND = 'rod_staff_wand'

The rod, staff, and wand row, which covers all three.

SCROLL class-attribute instance-attribute

SCROLL = 'scroll'

The scroll row, which covers treasure maps as well as spell scrolls.

SWORD class-attribute instance-attribute

SWORD = 'sword'

Enchanted swords.

WEAPON class-attribute instance-attribute

WEAPON = 'weapon'

Every other enchanted weapon.

MagicItemTypeRow

Bases: BaseModel

One row of the master Magic Item Type table, with the d% rolls that select its type in each column.

The rules print two columns, B for Basic play and X for Expert play, and some types have different odds in each. Scrolls are likelier in Expert play, and potions and other weapons less likely. A printed 00 is read as 100, so both columns end at 100.

category instance-attribute

category: MagicItemType

The type this row selects. See MagicItemType.

basic_min class-attribute instance-attribute

basic_min: int = Field(ge=1, le=100)

The lowest d% roll that selects it in the B column.

basic_max class-attribute instance-attribute

basic_max: int = Field(ge=1, le=100)

The highest d% roll that selects it in the B column.

expert_min class-attribute instance-attribute

expert_min: int = Field(ge=1, le=100)

The lowest d% roll that selects it in the X column.

expert_max class-attribute instance-attribute

expert_max: int = Field(ge=1, le=100)

The highest d% roll that selects it in the X column.

MagicItemTypeTable

Bases: BaseModel

The master Magic Item Type table, which gives the kind of magic item a d% roll produces.

It's the first of the two rolls that generate a magic item. Roll it with category_for_roll, then roll the type's table, which MagicItemCatalog.sub_table returns. Or let generate_magic_item do both and instantiate the item.

rows class-attribute instance-attribute

rows: tuple[MagicItemTypeRow, ...] = Field(min_length=1)

The rows, in printed order, each column covering the whole d%. See MagicItemTypeRow.

category_for_roll

category_for_roll(roll: int, *, tier: str) -> MagicItemType

Return the type of magic item a d% roll produces, under one tier's column.

Parameters:

Name Type Description Default
roll int

The d% result, 1 to 100, with a rolled 00 passed as 100.

required
tier str

"basic" or "expert", choosing the printed B or X column.

required

Returns:

Type Description
MagicItemType

The selected type.

Raises:

Type Description
ValueError

If the tier isn't one of the two, or the roll is outside 1 to 100.

Examples:

from osrlib.data import load_treasure_tables

table = load_treasure_tables().magic_item_types
print(table.category_for_roll(50, tier="basic"), table.category_for_roll(50, tier="expert"))
# rod_staff_wand scroll

RoomContentsResult

Bases: BaseModel

What one roll on the room stocking table produced.

Returned by roll_room_contents. It contains both rolls, so you can see how a room was decided, or log the rolls when you stock a level with a tool.

roll instance-attribute

roll: int

The d6 that chose the contents.

row instance-attribute

The row it selected. See StockingRow.

treasure_roll class-attribute instance-attribute

treasure_roll: int | None = None

The d6 rolled for treasure, or None when the row gives no chance of treasure and no die was rolled.

treasure_present class-attribute instance-attribute

treasure_present: bool = False

True when the room has treasure as well as its contents. Which treasure is yours to decide: generate it with generate_unguarded_treasure for an empty or trapped room, or from the monster's treasure type when a monster is there.

StockingRow

Bases: BaseModel

One row of the room stocking table, giving what is in a room and how likely treasure is with it.

roll_room_contents rolls the d6, selects the row, and rolls its treasure chance, and returns the row in RoomContentsResult.row. Read contents to decide what to place: a monster, a trap, something special, or nothing.

roll_min class-attribute instance-attribute

roll_min: int = Field(ge=1, le=6)

The lowest d6 result in this row.

roll_max class-attribute instance-attribute

roll_max: int = Field(ge=1, le=6)

The highest d6 result in this row.

contents instance-attribute

contents: Literal['empty', 'monster', 'special', 'trap']

What is in the room: "empty", "monster", "special", or "trap".

treasure_chance_in_six class-attribute instance-attribute

treasure_chance_in_six: int = Field(ge=0, le=6)

How many faces of a d6 mean treasure as well, for example 3 for a 3-in-6 chance. 0 where the table prints no chance, and no die is rolled then.

StockingTable

Bases: BaseModel

The Random Dungeon Room Contents table, which lists what to put in a room when you stock a dungeon.

Rolling it takes two steps, so call roll_room_contents unless you're rolling by hand. It rolls the contents, then the treasure chance that goes with them, and returns both.

You use this table to fill a dungeon level before anyone explores it. The session never rolls on it during play.

rows class-attribute instance-attribute

rows: tuple[StockingRow, ...] = Field(min_length=1)

The rows, covering the whole d6. See StockingRow.

row_for_roll

row_for_roll(roll: int) -> StockingRow

Return the stocking row a d6 roll selects.

Parameters:

Name Type Description Default
roll int

The d6 result, 1 to 6.

required

Returns:

Type Description
StockingRow

The selected row.

Raises:

Type Description
ValueError

If the roll is outside 1 to 6.

Examples:

from osrlib.data import load_treasure_tables

row = load_treasure_tables().stocking.row_for_roll(3)
print(row.contents, row.treasure_chance_in_six)
# monster 3

TreasureEntry

Bases: BaseModel

One printed line of a treasure type, which is one thing that might be in the hoard.

A treasure type is a list of these, and generation goes through them in order. Each has exactly one payload, so an entry is coins, or gems, or jewellery, or magic items, never a mixture. Generate a list of them with generate_treasure_entries, which is also how you generate the hoard a treasure map leads to.

chance_pct class-attribute instance-attribute

chance_pct: int = Field(default=0, ge=0, le=100)

The percentage chance the entry is present at all. 0 means it always is, which is how the entries printed without a chance are stored.

coins class-attribute instance-attribute

coins: CoinQuantity | None = None

The coins this entry yields, or None. See CoinQuantity.

gems_dice class-attribute instance-attribute

gems_dice: str | None = None

How many gems, as a dice expression, or None. Each gem's value is rolled separately on the gem table.

jewellery_dice class-attribute instance-attribute

jewellery_dice: str | None = None

How many pieces of jewellery, as a dice expression, or None. Each piece's value is rolled separately.

magic class-attribute instance-attribute

magic: tuple[MagicAllotment, ...] = ()

The magic item clauses, or empty. See MagicAllotment.

TreasureRefPlan

Bases: BaseModel

A monster's treasure entry, sorted into what to generate and when.

plan_treasure_ref produces one of these from a stat block's treasure reference. The list a letter is in sets when you generate it: the lair letters once when you stock the lair, the individual letters once per monster, and the group letters once for the whole group. A letter in parentheses on the stat block is lair treasure whatever section it belongs to, so the bandit's U (A) means the band carries type U between them and the camp has a type A hoard.

Some references have nothing to generate. Where a stat block marks the treasure special or describes it below, the referee writes it, and plan_treasure_ref leaves those parts out of the plan. It also leaves out the two adjustments the rules leave to the referee: reducing a hoard for a small lair, and changing a hoard's value by hand.

lair class-attribute instance-attribute

lair: tuple[str, ...] = ()

Letters to generate once for the lair, in the order the stat block lists them.

individual class-attribute instance-attribute

individual: tuple[str, ...] = ()

Letters to generate once per monster.

group class-attribute instance-attribute

group: tuple[str, ...] = ()

Letters to generate once for the group.

extra_gp class-attribute instance-attribute

extra_gp: int = 0

Gold pieces the entry adds to the lair hoard on top of what its letters generate, or 0.

multiplier class-attribute instance-attribute

multiplier: int = 1

How many times to run the whole generation, for an entry like the noble's V × 3. 1 for everything else.

TreasureSection

Bases: StrEnum

Which section of the treasure tables a letter belongs to, which sets when you generate it.

A monster's stat block lists treasure types by letter, and when you generate a letter depends on its section: once for the lair, once per monster, or once for the whole group. plan_treasure_ref sorts a stat block's letters into those three groups for you.

The lowercase values appear in the compiled treasure data.

HOARD class-attribute instance-attribute

HOARD = 'hoard'

Types A to O: the treasure in a monster's lair, generated once for the lair.

INDIVIDUAL class-attribute instance-attribute

INDIVIDUAL = 'individual'

Types P to T: what one monster carries, generated once per monster.

GROUP class-attribute instance-attribute

GROUP = 'group'

Types U and V: what a group carries between them, generated once for the group.

TreasureTables

Bases: BaseModel

Every treasure table, loaded and ready to generate from.

Call load_treasure_tables to get the built-in set. It's frozen, and every call returns the same cached object. The generation functions load it themselves, so you need this only to read a table: to show a referee what a letter can produce, or to roll a table by hand.

treasure_types instance-attribute

treasure_types: tuple[TreasureTypeTable, ...]

Every treasure type, A through V. See TreasureTypeTable. Reach one by letter with treasure_type.

gems instance-attribute

What gems and jewellery are worth. See GemValueTable.

magic_item_types instance-attribute

magic_item_types: MagicItemTypeTable

Which kind of magic item a roll produces. See MagicItemTypeTable.

stocking instance-attribute

stocking: StockingTable

What is in a room when you stock a dungeon. See StockingTable.

unguarded instance-attribute

What an unguarded cache contains, by level. See UnguardedTreasureTable.

treasure_type

treasure_type(letter: str) -> TreasureTypeTable

Return the treasure type for letter.

Parameters:

Name Type Description Default
letter str

The type letter, for example "A", as it appears in a monster's stat block. The letters are the letter of each entry in treasure_types, and are listed in the treasure type index. Case-sensitive: the letters are uppercase.

required

Returns:

Type Description
TreasureTypeTable

The treasure type.

Raises:

Type Description
ValueError

If no type has that letter.

Examples:

from osrlib.data import load_treasure_tables

hoard = load_treasure_tables().treasure_type("A")
print(hoard.kind, hoard.average_gp)
# hoard 18000.0

TreasureTypeTable

Bases: BaseModel

One treasure type, A through V, with everything a hoard of that letter can contain.

Get one with TreasureTables.treasure_type, or skip straight to the result with generate_treasure. Read the entries when you want to show a referee what a letter can produce before rolling it.

letter class-attribute instance-attribute

letter: str = Field(min_length=1, max_length=1)

The type letter, for example "A". Every letter is in the treasure_types of the tables that load_treasure_tables returns, and listed in the treasure type index.

kind instance-attribute

Whether the letter is lair treasure, carried by one monster, or carried by a group. See TreasureSection.

average_gp class-attribute instance-attribute

average_gp: float = Field(ge=0)

The average value of a hoard of this type in gold pieces, as the rules print it. Use it to plan an adventure. Generation doesn't adjust a hoard toward it, so a single hoard can be worth far more or less.

entries class-attribute instance-attribute

entries: tuple[TreasureEntry, ...] = Field(min_length=1)

The printed lines, in order. See TreasureEntry.

UnguardedTreasureBand

Bases: BaseModel

One dungeon-level band of the unguarded treasure table.

Deeper levels have more treasure, so the table is divided into bands of levels. Each band's entries have the same structure as a treasure type's. Get the band for a level with UnguardedTreasureTable.band_for_level.

label class-attribute instance-attribute

label: str = Field(min_length=1)

The band as the table prints it, for example "Level 2–3".

min_level class-attribute instance-attribute

min_level: int = Field(ge=1)

The shallowest dungeon level in the band.

max_level class-attribute instance-attribute

max_level: int = Field(ge=1)

The deepest dungeon level in the band.

entries class-attribute instance-attribute

entries: tuple[TreasureEntry, ...] = Field(min_length=1)

The printed lines, in order. See TreasureEntry.

UnguardedTreasureTable

Bases: BaseModel

The unguarded treasure table, which lists what an unguarded cache contains at each dungeon level.

Use it through generate_unguarded_treasure, which picks the band and generates from it. The deepest printed band covers levels 8 and 9, and every deeper level uses it too, so a level 12 cache is no richer than a level 9 one.

bands class-attribute instance-attribute

bands: tuple[UnguardedTreasureBand, ...] = Field(min_length=1)

The bands, in level order and contiguous from level 1. See UnguardedTreasureBand.

band_for_level

band_for_level(level: int) -> UnguardedTreasureBand

Return the band for a dungeon level.

Parameters:

Name Type Description Default
level int

The dungeon level, counting from 1.

required

Returns:

Type Description
UnguardedTreasureBand

The band covering that level. A level deeper than every band gets the deepest band, as the encounter tables do.

Raises:

Type Description
ValueError

If level is below 1.

Examples:

from osrlib.data import load_treasure_tables

table = load_treasure_tables().unguarded
print(table.band_for_level(3).label, table.band_for_level(12).label)
# Level 2–3 Level 8–9

generate_magic_item

generate_magic_item(
    category: MagicItemType | None,
    *,
    tier: str,
    stream: RngStream,
    allocator: Any,
    exclude: tuple[MagicItemType, ...] = ()
) -> list[MagicItemInstance]

Roll one magic item at random: which kind, which item, and all its details.

It does three steps in one call. When category is None, it rolls the master Magic Item Type table for the kind, re-rolling anything you excluded. Then it rolls that kind's table for the item. Then instantiate_magic_item rolls the item's details. Pass a category when the kind is already decided, as it is for an allotment for a potion.

Use it when you want a single random item: a reward, a gift, a hand-placed surprise. For a monster's whole hoard call generate_treasure, which rolls allotments as well as coins and gems.

Parameters:

Name Type Description Default
category MagicItemType | None

The kind of item to roll, or None to roll the kind too. See MagicItemType.

required
tier str

"basic" or "expert", the printed B or X column. It changes the odds of each kind and which items a table can reach.

required
stream RngStream

The RNG stream to draw from, conventionally TREASURE_STREAM.

required
allocator Any

The id source for the new instances, which take the magic-item prefix. An IdAllocator.

required
exclude tuple[MagicItemType, ...]

Kinds to re-roll when the kind is being rolled. Excluded rolls consume draws, as re-rolling at the table does. When category is None, leave at least one kind that the tier's column of the master table can roll.

()

Returns:

Type Description
list[MagicItemInstance]

The new instances, unidentified. Usually one. Two when the table's row is a suit of armour that comes with a shield.

Raises:

Type Description
ValueError

If tier is neither "basic" nor "expert", category is one of the kinds you excluded, or category is None and exclude covers every kind the tier's column can roll. The function raises before it draws.

Examples:

from osrlib.core.monsters import IdAllocator
from osrlib.core.rng import RngStreams
from osrlib.core.treasure import TREASURE_STREAM, generate_magic_item

stream = RngStreams(master_seed=9).get(TREASURE_STREAM)
items = generate_magic_item(None, tier="basic", stream=stream, allocator=IdAllocator())

print([(item.instance_id, item.template_id) for item in items])
# [('magic-item-0001', 'rope_of_climbing')]

generate_treasure

generate_treasure(treasure_type: str, *, tier: str, stream: RngStream, allocator: Any) -> GeneratedTreasure

Generate one treasure type's contents.

Use it for a monster's treasure. A stat block gives a letter, and this rolls everything that letter can contain. Which letters to roll, and whether each belongs to the lair, one monster, or the group, is what plan_treasure_ref works out from the stat block.

It doesn't place anything. Put what comes back in a chest, give it to a monster, or add it to an inventory.

Parameters:

Name Type Description Default
treasure_type str

The type letter, "A" through "V". Get the letters from TreasureTables.treasure_types on load_treasure_tables, or see the treasure type index.

required
tier str

"basic" or "expert", the printed B or X column for magic items. Choose by how experienced the party is. A session uses Basic while the party's highest living level is 1 to 3 and Expert from 4 up, decided when the treasure is generated.

required
stream RngStream

The RNG stream to draw from, conventionally TREASURE_STREAM.

required
allocator Any

The id source for generated gems, jewellery, and magic items, which take the valuable and magic-item prefixes. An IdAllocator.

required

Returns:

Type Description
GeneratedTreasure

The coins, valuables, and magic items. See GeneratedTreasure. An unlucky hoard can be empty.

Raises:

Type Description
ValueError

If no treasure type has that letter, or if tier is neither "basic" nor "expert". Both are checked before the first draw, so a refused call costs no draws and leaves the stream where it was.

Examples:

from osrlib.core.monsters import IdAllocator
from osrlib.core.rng import RngStreams
from osrlib.core.treasure import TREASURE_STREAM, generate_treasure

stream = RngStreams(master_seed=1).get(TREASURE_STREAM)
hoard = generate_treasure("A", tier="expert", stream=stream, allocator=IdAllocator())
assert hoard.coins.total_coins == 7000
assert len(hoard.valuables) == 19
assert {item.template_id for item in hoard.magic_items} == {
    "sword_plus_1_plus_3_vs_dragons",
    "ring_of_protection",
    "potion_of_poison",
}

generate_treasure_entries

generate_treasure_entries(
    entries: Sequence[TreasureEntry], *, tier: str, stream: RngStream, allocator: Any
) -> GeneratedTreasure

Generate treasure from a list of printed entries.

generate_treasure and generate_unguarded_treasure both call this. Call it yourself when you have entries rather than a letter or a level. For example, the hoard a treasure map leads to is a list of entries in the map template's hoard_recipe.

It resolves the entries in printed order. For each one, it makes the presence roll if the entry has a chance, then rolls the quantity dice, then resolves each gem, piece of jewellery, or magic item completely before the next begins. That order doesn't change, so the same seed and the same entries always give the same result.

Parameters:

Name Type Description Default
entries Sequence[TreasureEntry]

The printed entries. See TreasureEntry.

required
tier str

"basic" or "expert", the printed B or X column for magic items.

required
stream RngStream

The RNG stream to draw from, conventionally TREASURE_STREAM.

required
allocator Any

The id source for generated gems, jewellery, and magic items, which take the valuable and magic-item prefixes. An IdAllocator.

required

Returns:

Type Description
GeneratedTreasure

The coins, valuables, and magic items. See GeneratedTreasure. Any of the three can be empty, and entries that failed their presence roll contribute nothing.

Raises:

Type Description
ValueError

If tier is neither "basic" nor "expert". The tier is checked before the first draw, so a refused call costs no draws and leaves the stream where it was, whether or not the entries would have reached a magic item.

Examples:

from osrlib.core.monsters import IdAllocator
from osrlib.core.rng import RngStreams
from osrlib.core.treasure import TREASURE_STREAM, generate_treasure_entries
from osrlib.data import load_magic_items

recipe = load_magic_items().get("treasure_map_i").hoard_recipe
stream = RngStreams(master_seed=2).get(TREASURE_STREAM)
hoard = generate_treasure_entries(recipe, tier="basic", stream=stream, allocator=IdAllocator())

print([item.template_id for item in hoard.magic_items])
# ['mace_plus_1']

generate_unguarded_treasure

generate_unguarded_treasure(dungeon_level: int, *, tier: str, stream: RngStream, allocator: Any) -> GeneratedTreasure

Generate an unguarded cache of treasure for a dungeon level.

Use it instead of generate_treasure when the treasure belongs to the room rather than to a monster. That's the case when roll_room_contents reports treasure in an empty or trapped room.

Deeper levels have more. Every level deeper than 9 uses the band for levels 8 and 9, so treasure stops getting richer past level 9.

Parameters:

Name Type Description Default
dungeon_level int

The dungeon level, counting from 1.

required
tier str

"basic" or "expert", the printed B or X column for magic items.

required
stream RngStream

The RNG stream to draw from, conventionally TREASURE_STREAM.

required
allocator Any

The id source for generated gems, jewellery, and magic items. An IdAllocator.

required

Returns:

Type Description
GeneratedTreasure

The coins, valuables, and magic items. See GeneratedTreasure. Every cache has coins. Gems, jewellery, and magic items are likelier on deeper levels.

Raises:

Type Description
ValueError

If dungeon_level is below 1, or if tier is neither "basic" nor "expert". Both are checked before the first draw, so a refused call costs no draws and leaves the stream where it was.

Examples:

from osrlib.core.monsters import IdAllocator
from osrlib.core.rng import RngStreams
from osrlib.core.treasure import TREASURE_STREAM, generate_unguarded_treasure

stream = RngStreams(master_seed=3).get(TREASURE_STREAM)
cache = generate_unguarded_treasure(1, tier="basic", stream=stream, allocator=IdAllocator())

print(cache.coins.sp, cache.coins.value_gp, len(cache.magic_items))
# 300 30 0

instantiate_magic_item

instantiate_magic_item(
    item_id: str, *, tier: str, stream: RngStream, allocator: Any, params: Mapping[str, Any] | None = None
) -> MagicItemInstance

Create one copy of a magic item you have already chosen, rolling the details that differ between copies.

This is how a hand-placed magic item becomes something a character can carry. An adventure lists the item's id (in FeatureSpec.magic_item_ids), and this function rolls what the item's SRD page leaves to chance: what a generic suit of enchanted armour is made of, how many charges a wand has, how many arrows are in the bundle, how many wishes the ring has, which spells are on the scroll, how many levels the sword can drain, and last of all whether a sword is sentient. It rolls all of these, so the instance that comes back is ready to use.

When you want the item chosen at random too, call generate_magic_item, which rolls the tables and then calls this.

The copy comes back unidentified. In a session, the engine identifies it the first time a character uses it, and IdentifyItem identifies it too.

Parameters:

Name Type Description Default
item_id str

The item to create, as an id from load_magic_items, listed in the magic item id index.

required
tier str

"basic" or "expert", the printed B or X column. It matters only where a detail differs between the two, like the level of a scroll's spells.

required
stream RngStream

The RNG stream to draw from, conventionally TREASURE_STREAM.

required
allocator Any

The id source for the new instance's id, which takes the magic-item prefix. An IdAllocator. In a session, pass the session's allocator. Outside one, make your own.

required
params Mapping[str, Any] | None

Overrides from a generation table row, when this is being called from one: the quantity dice a printed band gives, a fixed Basic-tier quantity, a wish count. Leave it None when placing an item by hand, and the function uses the template's values.

None

Returns:

Type Description
MagicItemInstance

The new instance, unidentified. See MagicItemInstance.

Raises:

Type Description
ValueError

If tier is neither "basic" nor "expert", or the catalog has no item with that id.

Examples:

from osrlib.core.monsters import IdAllocator
from osrlib.core.rng import RngStreams
from osrlib.core.treasure import TREASURE_STREAM, instantiate_magic_item

stream = RngStreams(master_seed=11).get(TREASURE_STREAM)
staff = instantiate_magic_item("staff_of_striking", tier="expert", stream=stream, allocator=IdAllocator())

print(staff.instance_id, staff.charges_remaining, staff.identified)
# magic-item-0001 18 False

plan_treasure_ref

plan_treasure_ref(ref: TreasureRef) -> TreasureRefPlan

Work out what a monster's treasure entry means.

Call this before you generate a monster's treasure. You don't generate all the letters on a stat block at the same moment, and this sorts them into the ones you roll for the lair, the ones you roll for each monster, and the ones you roll for the group. Then call generate_treasure for each letter, multiplier times over, and add extra_gp to the lair hoard.

Parameters:

Name Type Description Default
ref TreasureRef

The treasure reference from a monster template's treasure field. See TreasureRef.

required

Returns:

Type Description
TreasureRefPlan

The plan. See TreasureRefPlan.

Raises:

Type Description
ValueError

If the reference has a letter that isn't a treasure type.

Examples:

from osrlib.core.treasure import plan_treasure_ref
from osrlib.data import load_monsters

plan = plan_treasure_ref(load_monsters().get("bandit").treasure)
print(plan.lair, plan.group, plan.individual)
# ('A',) ('U',) ()

roll_room_contents

roll_room_contents(stream: RngStream) -> RoomContentsResult

Roll what is in a room and whether there's treasure with it.

Use it to fill a dungeon level before play. It rolls a d6 for the contents. When the selected row gives a chance of treasure, it rolls a second d6 for that. A row with no chance of treasure draws no second die.

Generating the treasure is a separate step, because which table to use depends on what is in the room: the monster's treasure type when a monster is there, and generate_unguarded_treasure otherwise.

Parameters:

Name Type Description Default
stream RngStream

The RNG stream to draw from, conventionally TREASURE_STREAM.

required

Returns:

Type Description
RoomContentsResult

Both rolls and the row they selected. See RoomContentsResult.

Examples:

from osrlib.core.rng import RngStreams
from osrlib.core.treasure import TREASURE_STREAM, roll_room_contents

result = roll_room_contents(RngStreams(master_seed=5).get(TREASURE_STREAM))
print(result.roll, result.row.contents, result.treasure_present)
# 6 trap False