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:
generate_treasurefor a treasure type, the letter in a monster's stat block.generate_unguarded_treasurefor an unguarded cache, by dungeon level.generate_magic_itemfor one magic item rolled at random, andinstantiate_magic_itemfor a particular item you've already chosen.plan_treasure_refto work out what a monster's treasure entry means: what each monster carries and what is in its lair.roll_room_contentsto stock a room at all, which is the roll that decides whether there's treasure to generate.
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
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.
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
The lowest d20 result in this band.
roll_max
class-attribute
instance-attribute
The highest d20 result in this band.
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
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
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:
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 inexclude. This is how "any 3 magic items" and "any 1 magic item, no weapons" are stored.category: roll the one table named incategories, as in "1 potion".pool: choose evenly among the types incategories, 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.
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.
ROD_STAFF_WAND
class-attribute
instance-attribute
The rod, staff, and wand row, which covers all three.
SCROLL
class-attribute
instance-attribute
The scroll row, which covers treasure maps as well as spell scrolls.
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.
basic_min
class-attribute
instance-attribute
The lowest d% roll that selects it in the B column.
basic_max
class-attribute
instance-attribute
The highest d% roll that selects it in the B column.
expert_min
class-attribute
instance-attribute
The lowest 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 |
required |
tier
|
str
|
|
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:
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.
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
The lowest d6 result in this row.
roll_max
class-attribute
instance-attribute
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".
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:
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
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
Letters to generate once for the lair, in the order the stat block lists them.
individual
class-attribute
instance-attribute
Letters to generate once per monster.
group
class-attribute
instance-attribute
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
Types A to O: the treasure in a monster's lair, generated once for the lair.
INDIVIDUAL
class-attribute
instance-attribute
Types P to T: what one monster carries, generated once per monster.
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.
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
unguarded: UnguardedTreasureTable
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 |
required |
Returns:
| Type | Description |
|---|---|
TreasureTypeTable
|
The treasure type. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no type has that letter. |
Examples:
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
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
kind: TreasureSection
Whether the letter is lair treasure, carried by one monster, or carried by a group. See
TreasureSection.
average_gp
class-attribute
instance-attribute
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
The band as the table prints it, for example "Level 2–3".
min_level
class-attribute
instance-attribute
The shallowest dungeon level in the band.
max_level
class-attribute
instance-attribute
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 |
Examples:
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 |
required |
tier
|
str
|
|
required |
stream
|
RngStream
|
The RNG stream to draw from, conventionally
|
required |
allocator
|
Any
|
The id source for the new instances, which take the |
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 |
()
|
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 |
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, |
required |
tier
|
str
|
|
required |
stream
|
RngStream
|
The RNG stream to draw from, conventionally
|
required |
allocator
|
Any
|
The id source for generated gems, jewellery, and magic items, which take
the |
required |
Returns:
| Type | Description |
|---|---|
GeneratedTreasure
|
The coins, valuables, and magic items. See
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If no treasure type has that letter, or if |
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
|
required |
tier
|
str
|
|
required |
stream
|
RngStream
|
The RNG stream to draw from, conventionally
|
required |
allocator
|
Any
|
The id source for generated gems, jewellery, and magic items, which take
the |
required |
Returns:
| Type | Description |
|---|---|
GeneratedTreasure
|
The coins, valuables, and magic items. See
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
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
|
|
required |
stream
|
RngStream
|
The RNG stream to draw from, conventionally
|
required |
allocator
|
Any
|
The id source for generated gems, jewellery, and magic items. An
|
required |
Returns:
| Type | Description |
|---|---|
GeneratedTreasure
|
The coins, valuables, and magic items. See
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
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 |
required |
tier
|
str
|
|
required |
stream
|
RngStream
|
The RNG stream to draw from, conventionally
|
required |
allocator
|
Any
|
The id source for the new instance's id, which takes the |
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
|
Returns:
| Type | Description |
|---|---|
MagicItemInstance
|
The new instance, unidentified. See
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
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 |
required |
Returns:
| Type | Description |
|---|---|
TreasureRefPlan
|
The plan. See |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the reference has a letter that isn't a treasure type. |
Examples:
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
|
required |
Returns:
| Type | Description |
|---|---|
RoomContentsResult
|
Both rolls and the row they selected. See
|
Examples: