osrlib.data
Load the compiled B/X rules content: classes, spells, monsters, items, languages, and tables.
A content id identifies an entry in one of these catalogs: a class id, a spell id, a monster id,
an equipment or magic item id, a language id, or a treasure-type letter. An adventure can also
bundle monster and item templates, with ids that aren't in these catalogs. Each load_* function returns one
catalog, and the catalog's entries are the valid ids:
[entry.id for entry in load_classes().classes] lists every class id, and the other catalogs
work the same way. The content-id pages on the documentation site list the same ids:
The loaders, one per catalog:
load_classes: the character classes, by class id.load_ability_tables: what each ability score from 3 to 18 is worth.load_languages: the spoken languages, by language id.load_equipment: weapons, armour, gear, and ammunition, by item id.load_magic_items: magic items, by item id.load_spells: spells, by spell id.load_monsters: monster templates, by monster id.load_combat_tables: the attack matrix, monster saves, XP awards, turning, and reactions.load_encounter_tables: wandering monsters by dungeon level.load_treasure_tables: the treasure types, by letter.
To use a catalog with ids, call the loader, look one entry up by id, then pass that entry to
the function that takes it. load_classes().get("fighter") gives you the
ClassDefinition that
level_up takes, and load_monsters().get("goblin") gives you
the MonsterTemplate that
spawn_monster takes. A
GameSession loads what it needs itself. Call these
loaders when you run the rules without a session, or to show a player what content exists
before play starts.
Each loader caches its result. The first call reads the data and validates it, and every
later call in the process returns the same catalog object. That object is a frozen model,
shared with every other caller, and nothing in it can be changed. Its mapping fields, like a
monster ability's params, are read-only FrozenMaps. During
play, osrlib creates mutable instances from these templates, the way
spawn_monster creates a
MonsterInstance from a template. To make a template
that differs from a built-in one, dump the built-in template with model_dump, change the dump,
and validate it with model_validate under a new id.
The data files are part of this package, and a loader reads only what the installed package
includes. The project generates them from the Old-School Essentials SRD, so a change you make
to a JSON file in an installed copy is lost at the next upgrade. To add content of your own,
construct the model yourself, like a MonsterTemplate,
and pass it to the same functions you pass the included entries to. To use your own monster or
item template in a session, bundle it with the Adventure
that uses it. If a data file is missing, isn't valid JSON, has no JSON object at its top level,
or fails validation, the loader raises
ContentValidationError instead of returning a
partial catalog.
The compiled data is Open Game Content under the Open Game License 1.0a. The license text
and Section 15 notice are in this package as osrlib/data/LICENSE-OGL.md.
Typical usage:
from osrlib.data import load_classes, load_monsters
fighter = load_classes().get("fighter")
print(fighter.name, fighter.hit_die)
# Fighter 8
goblin = load_monsters().get("goblin")
print(goblin.name, goblin.ac, goblin.morale)
# Goblin 6 7
Language
Bases: BaseModel
One spoken language from the language catalog.
You get one from LanguageCatalog.get, or from
LanguageCatalog.languages when you want to
offer a player the whole list. Pass its id in the extra_languages argument of
create_character, or in the choices argument
of validate_extra_languages.
The alignment languages aren't in the catalog. A character speaks the language of its
Alignment without choosing it.
The model is frozen: assigning to a field raises pydantic's ValidationError.
id
instance-attribute
id: str
The id to pass wherever a function takes a language id, like "gnoll" or "common".
choosable
instance-attribute
choosable: bool
Whether a character with a high enough INT may take this language as an extra.
True for the languages the SRD lists under Other Languages, which a high-INT character chooses from. False for Common, which every character already speaks.
LanguageCatalog
Bases: BaseModel
The whole language list, with lookup by id.
load_languages returns this catalog, and
get returns one
Language from it by id. Each id appears once, and a catalog with a
repeated id fails validation.
The model is frozen, and the loader returns the same instance on every call.
languages
instance-attribute
Every language in the catalog, in the order the data file lists them.
The data file in this package lists them in alphabetical order by id, with Common among
the rest. Keep the ones whose Language.choosable is True
for the languages a high-INT character may take.
get
Return the language with language_id.
Use this to turn a stored id back into a display name. To check a player's picks
before you pass them to create_character,
call validate_extra_languages
instead. It checks the whole set against a class and an INT score, and returns a
rejection for each problem instead of raising on the first unknown id.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
language_id
|
str
|
A language id, like |
required |
Returns:
| Type | Description |
|---|---|
Language
|
The language. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no language has that id. Pass an id from the catalog. |
Examples:
load_ability_tables
cached
load_ability_tables() -> AbilityTables
Load the ability score modifier tables and the prime requisite XP table.
The returned AbilityTables gives what a score is
worth. It has a method for each modifier: the STR melee modifier and open-doors chance, the
INT extra languages and literacy, the WIS modifier to saves against magic, the DEX armour
class, missile, and initiative modifiers, the CON hit point modifier, the CHA reaction
modifier, retainer limit, and retainer loyalty, and the prime requisite XP percentage.
Call it to show these values on a character sheet.
create_character and
level_up read the tables themselves.
Every method takes a score from 3 to 18 and raises ValueError for any other score.
No content-id page covers this catalog, because a score is its only key.
Returns:
| Type | Description |
|---|---|
AbilityTables
|
The frozen tables. The first call validates the data, and every later call returns the same object. |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If the generated data is missing, isn't valid JSON, or fails validation. |
Examples:
load_classes
cached
load_classes() -> ClassCatalog
Load the character class catalog.
Call ClassCatalog.get on the result for a
ClassDefinition.
level_up,
xp_modifier_pct,
level_title,
thief_skill_check, and
caster_profile take the definition, not the id.
create_character takes class_id and looks the
definition up itself, so to create a character you need this loader only to show a player
the classes they can choose.
The catalog contains only the classes in this package. To use a class of your own, build a
ClassDefinition and pass it to the same functions.
Returns:
| Type | Description |
|---|---|
ClassCatalog
|
The frozen class catalog. The first call validates the data, and every later call
returns the same object. Its |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If the generated data is missing, isn't valid JSON, or fails validation. |
Examples:
load_combat_tables
cached
load_combat_tables() -> CombatTables
Load the combat tables: the attack matrix, monster saves, XP awards, turning, and reactions.
monster_xp takes these tables and a monster's hit
dice and returns its XP award. To read a row yourself, get its label from the monster's
hit dice first. Pass the label from
monster_save_band_label to
CombatTables.save_band, and the label from
xp_band_label to
CombatTables.xp_row.
You don't pass tables for most of combat: attack_roll
and saving_throw read the tables they need themselves.
Load the tables to show the numbers, or to award XP without a session. No content-id page
covers this catalog, because hit dice and armour class are its keys, not ids.
Returns:
| Type | Description |
|---|---|
CombatTables
|
The frozen combat tables. The first call validates the data, and every later call returns the same object. |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If the generated data is missing, isn't valid JSON, or fails validation. |
Examples:
load_encounter_tables
cached
load_encounter_tables() -> EncounterTables
Load the dungeon encounter tables, with the NPC adventuring party tables.
EncounterTables.for_level takes a dungeon
level number from 1 up and returns the table the SRD prints for it. Level 8 and every deeper
level share the last table. Roll on the table for an entry, then call
select_encounter_individuals with a
monster entry and a count to get the template ids that appear.
generate_npc_party rolls on the NPC party tables.
A session rolls wandering monsters itself, through
wandering_check. Load these tables when you
stock a dungeon yourself, or to show which monsters a level can have. No content-id page
covers this catalog, because dungeon level and die roll are its keys.
Returns:
| Type | Description |
|---|---|
EncounterTables
|
The frozen encounter tables. The first call validates the data, and every later call returns the same object. |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If the generated data is missing, isn't valid JSON, or fails validation. |
Examples:
load_equipment
cached
load_equipment() -> EquipmentCatalog
Load the mundane equipment catalog: weapons, armour, gear, ammunition, and treasure weights.
EquipmentCatalog.get looks an id up across the
weapons, armour, gear, and ammunition lists and returns its template. Pass the
template to validate_purchase and
purchase. purchase returns an
ItemInstance, which is what
validate_equip and
equip take. treasure_weights is a separate list, which
treasure_weight_coins reads to weigh the coins
and gems a character finds instead of buying.
Magic items are in a separate catalog, from load_magic_items.
This catalog contains only the items in this package. A session also looks up the item
templates an adventure bundles.
Returns:
| Type | Description |
|---|---|
EquipmentCatalog
|
The frozen equipment catalog. The first call validates the data, and every later
call returns the same object. Its |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If the generated data is missing, isn't valid JSON, or fails validation. |
Examples:
load_languages
cached
load_languages() -> LanguageCatalog
Load the language catalog.
To offer a player the languages a high-INT character may add, read
LanguageCatalog.languages and keep the entries
whose choosable is True. Call
LanguageCatalog.get to turn an id back into a display
name. Check the chosen ids with
validate_extra_languages, which counts
them against what the character's INT allows, then pass them to
create_character as extra_languages.
Returns:
| Type | Description |
|---|---|
LanguageCatalog
|
The frozen language catalog. The first call validates the data, and every later call
returns the same object. Its |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If the generated data is missing, isn't valid JSON, or fails validation. |
Examples:
load_magic_items
cached
load_magic_items() -> MagicItemCatalog
Load the magic item catalog: the templates, the generation sub-tables, and the sword tables.
MagicItemCatalog.get returns the frozen
MagicItemTemplate for an id.
magic_item_template does the same lookup for a
MagicItemInstance you already have.
generate_magic_item rolls on the catalog's
other tables, like the sub-tables, the armour-type table, the scroll spell-level table, and
the sentient sword tables, so you rarely read them yourself.
An id identifies a kind of item, not one particular item. Two potions of healing share a template.
As instances, each has a separate instance id, charges, and identification state. Mundane gear
is in load_equipment.
Returns:
| Type | Description |
|---|---|
MagicItemCatalog
|
The frozen magic item catalog. The first call validates the data, and every later
call returns the same object. Its |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If the generated data is missing, isn't valid JSON, or fails validation. |
Examples:
load_monsters
cached
load_monsters() -> MonsterCatalog
Load the monster catalog.
MonsterCatalog.get returns the frozen
MonsterTemplate that
spawn_monster turns into a mutable
MonsterInstance with rolled hit points and a
session-unique id. The instance is the creature that fights. The template stays shared and
unchanged however many instances you spawn from it.
A session looks up a monster id from a dungeon or an encounter table in this catalog and in the templates the adventure bundles. Read a template directly to show a monster's statistics, or to plan an encounter before any monster exists.
Returns:
| Type | Description |
|---|---|
MonsterCatalog
|
The frozen monster catalog. The first call validates the data, and every later call
returns the same object. Its |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If the generated data is missing, isn't valid JSON, or fails validation. |
Examples:
load_spells
cached
load_spells() -> SpellCatalog
Load the spell catalog.
memorize_spells and
add_spell_to_book take this catalog whole, so
they can check a chosen id against the caster's spell list and level.
SpellCatalog.get returns one
SpellTemplate by id.
SpellCatalog.by_list returns every spell on one
spell list, like "cleric", and takes an optional spell level. Show its result to a player
who is choosing spells to memorize.
A reversible spell has one id. Its reversed form, like blight for bless, is the
template's reversed_form, and you cast it by passing reversed=True to
cast_spell. To use a spell of your own, build a
SpellTemplate and pass it to the same functions.
Returns:
| Type | Description |
|---|---|
SpellCatalog
|
The frozen spell catalog. The first call validates the data, and every later call
returns the same object. Its |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If the generated data is missing, isn't valid JSON, or fails validation. |
Examples:
load_treasure_tables
cached
load_treasure_tables() -> TreasureTables
Load the treasure tables: the treasure types, gem values, magic item types, stocking, and unguarded hoards.
TreasureTables.treasure_type returns
the table for a letter. A monster's letters are in the letters of its
MonsterTemplate.treasure. Read the table
to show what a hoard can contain before anything is rolled.
To roll a hoard, call generate_treasure with the
letter instead. It loads these tables itself and returns a
GeneratedTreasure with its coins, valuables, and
magic items already rolled from the stream you pass.
roll_room_contents rolls on the room stocking
table, and generate_unguarded_treasure
on the unguarded treasure table.
Returns:
| Type | Description |
|---|---|
TreasureTables
|
The frozen treasure tables. The first call validates the data, and every later call
returns the same object. Its |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If the generated data is missing, isn't valid JSON, or fails validation. |
Examples: