osrlib.crawl.content_pack
Content packs, for moving finished rooms from one adventure to another.
A ContentPack contains room content with the geometry left
out. An AreaSpec binds an encounter, a trap, treasure, and
features to particular cells of a particular level. A pack entry has the same content fields and no
cells. That makes it portable. osrlib has no function that applies a pack: an authoring tool, like
one you write, reads an entry and copies its content onto an area that the target adventure
already has. A pack contains no geometry, so it doesn't have to fit a
particular map.
The members, in the order you use them:
ContentPackEntryis one room's content.PackSectiongroups the entries for one dungeon level, with that level'sWanderingSpecif you include it.ContentPackcontains the sections and the monster templates they need.validate_content_packtakes a pack and the built-in catalogs, and returns aPackFindingfor each reference the pack doesn't cover.ContentPack.to_documentandContentPack.from_documentwrite a pack to JSON-compatible data and read it back.
Besides its sections, a pack contains the MonsterTemplates
that its encounters and wandering tables use and that the built-in catalog doesn't have. These
bundled templates are the pack's closure: everything the pack's rooms need that osrlib doesn't
already include. Item templates are outside the closure. An item you bundle in one adventure would
be an unresolved reference in any other adventure, so a pack's features can use items from the
built-in equipment catalog only. Spell templates are outside it too, because nothing in a room
refers to a spell by id.
An authoring tool finds a section, an entry, or a bundled monster by its id. When you construct a pack, osrlib checks that section ids are unique, that entry ids are unique across the whole pack and not only within a section, and that bundled monster ids are unique. If a pack breaks any of these rules, constructing it raises an error.
A reference that resolves to nothing is allowed in a pack, as it is in an
Adventure you haven't finished. An encounter may use a
monster id that neither the pack nor the built-in catalog contains. validate_content_pack returns
those gaps as data instead of raising, so the tool that reads a pack can show them to you and let
you decide what to do.
A pack serializes as a stamped document: an envelope whose kind is
CONTENT_PACK_KIND, with the schema version, the
engine version, and the pack as its payload. A document from an older schema version loads, and one
from a newer version raises SaveVersionError. Writing a pack
always stamps the current versions, so an older pack that you load and save again comes back
current.
Typical usage:
from osrlib.crawl.content_pack import ContentPack, ContentPackEntry, PackSection, validate_content_pack
from osrlib.crawl.dungeon import KeyedEncounter, KeyedMonster
from osrlib.data import load_equipment, load_monsters
pack = ContentPack(
name="The gnawing dark",
sections=(
PackSection(
id="level-1",
label="Level 1",
entries=(
ContentPackEntry(
id="guard-post",
name="Guard post",
encounter=KeyedEncounter(monsters=(KeyedMonster(template_id="orc", count_fixed=4),)),
),
),
),
),
)
document = pack.to_document()
assert document["kind"] == "content_pack"
assert ContentPack.from_document(document) == pack
assert validate_content_pack(pack, load_monsters(), load_equipment()) == ()
CONTENT_PACK_KIND
module-attribute
The kind stamped on a serialized content pack: "content_pack".
Every document osrlib writes has a kind, and this is the kind for a pack.
ContentPack.to_document stamps it, and
ContentPack.from_document refuses a document
of any other kind. Passing a save file to from_document raises an error whose message includes both
kinds, instead of building a pack from the wrong data. Compare a parsed document's kind with this
constant to decide which loader to pass it to.
ContentPack
Bases: BaseModel
A content pack: sections of rooms without geometry, plus the monsters they need.
Construct one yourself, or have an authoring tool build one from an adventure you have already
written. Check it with
validate_content_pack, write it with
to_document, and read it back with
from_document. osrlib has no function
that applies a pack to an adventure, because you decide which target area each entry belongs
on.
A pack is frozen. osrlib checks its id rules when you construct it, not when you validate it, so the ids in any pack you have are already valid.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
str
|
The pack's id, when it has one. |
name |
str
|
The pack's name. |
description |
str
|
Text about the pack. |
author |
str
|
Who wrote it. |
sections |
tuple[PackSection, ...]
|
The level groupings that contain the entries. |
monsters |
tuple[MonsterTemplate, ...]
|
The monster templates the entries need. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If two sections share an id, if two entries anywhere in the pack share an id, or if two bundled monsters share an id. |
id
class-attribute
instance-attribute
id: str = ''
The pack's id, empty by default. osrlib never reads it. Set one when your tool stores several packs and needs to tell them apart.
description
class-attribute
instance-attribute
description: str = ''
Text about what the pack contains and what it is for.
author
class-attribute
instance-attribute
author: str = ''
Who wrote the pack. osrlib never reads it. It stays in the document as credit.
sections
class-attribute
instance-attribute
sections: tuple[PackSection, ...] = ()
The pack's level groupings. Section ids are unique, and entry ids are unique across all the sections together.
monsters
class-attribute
instance-attribute
monsters: tuple[MonsterTemplate, ...] = ()
The MonsterTemplates that the pack's encounters and
wandering tables use and that the built-in catalog doesn't have. Bundle every monster your rooms
use and the pack is self-contained.
There is no field for bundled items, because an item you bundle in an adventure exists only in
that adventure. A pack's features use the built-in equipment and magic-item catalogs, and
validate_content_pack reports an item id from
an adventure's bundle as a gap.
to_document
Serialize the pack to a stamped document you can store or send.
The result is plain JSON-compatible data: an envelope that contains the kind, the schema
version, the engine version, and the pack as its payload. Pass it to json.dump, store it in
a database, or send it over a network. Read it back with
from_document.
Writing always stamps the current versions, so a pack you loaded from an older document becomes a current one when you write it.
Returns:
| Type | Description |
|---|---|
dict[str, object]
|
The stamped document, with the serialized pack as its |
Examples:
from_document
classmethod
from_document(document: Mapping[str, object]) -> ContentPack
Load a content pack from a stamped document.
This reverses to_document. Parse your
file however you like, then pass the resulting mapping here. osrlib checks the pack's id rules
as it loads, so a document with duplicate ids fails here.
A document from an older schema_version loads. One schema change affects packs: from
schema 3, TrapSpec refuses trigger="enter" on a treasure
trap. When an older document has that combination, from_document reads the trap with
trigger="open", as load_game does for a save. It ignores
payload fields this version doesn't recognize, and it doesn't change document.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
document
|
Mapping[str, object]
|
A document from
|
required |
Returns:
| Type | Description |
|---|---|
ContentPack
|
The pack. |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If the envelope is malformed, if its |
SaveVersionError
|
If the document's schema version is newer than this version of osrlib supports, which means a later osrlib wrote it. Upgrade osrlib to read it. |
Examples:
import json
from osrlib.crawl.content_pack import ContentPack, ContentPackEntry, PackSection
entry = ContentPackEntry(id="guard-post", name="Guard post")
written = ContentPack(name="The gnawing dark", sections=(PackSection(id="level-1", entries=(entry,)),))
stored = json.dumps(written.to_document())
# Later, in the authoring tool: read the stored text back and list what the pack offers.
pack = ContentPack.from_document(json.loads(stored))
for section in pack.sections:
print(section.id, [entry.name for entry in section.entries])
# level-1 ['Guard post']
ContentPackEntry
Bases: BaseModel
One portable room: the content of an AreaSpec without its cells.
An entry has the content fields an area has: its name, description, encounter, trap, treasure, and features. It has no cells and nothing else tied to a grid. A tool that applies a pack picks an area the target adventure already has and copies these fields onto it, so the same entry can fill a corridor dead end in one adventure and a vaulted hall in another.
The trap has to be a room trap, as on an AreaSpec. A treasure trap goes on one of the
entry's features instead.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
str
|
The entry's id, unique across the pack. |
name |
str
|
The room's name. |
description |
str
|
Text describing the room. |
encounter |
KeyedEncounter | None
|
The monsters waiting in the room. |
trap |
TrapSpec | None
|
A room trap over the whole room. |
treasure |
AreaTreasureSpec | None
|
Unguarded treasure the session rolls. |
features |
tuple[FeatureSpec, ...]
|
The keyed things in the room. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
id
class-attribute
instance-attribute
The entry's id. It can't be empty, and it has to be unique across the whole pack, not only within its section, because an authoring tool finds an entry by its id alone. Constructing a pack with two entries that share an id raises an error.
name
class-attribute
instance-attribute
name: str = ''
The room's name, for a tool to list and to copy onto the target area.
description
class-attribute
instance-attribute
description: str = ''
Text describing the room, for a tool to copy onto the target area.
encounter
class-attribute
instance-attribute
encounter: KeyedEncounter | None = None
The monsters waiting in the room, or None.
validate_content_pack reports each monster
id in it that is in neither the built-in catalog nor the pack's monsters.
trap
class-attribute
instance-attribute
trap: TrapSpec | None = None
A trap over the whole room, or None. It has to be a room trap.
treasure
class-attribute
instance-attribute
treasure: AreaTreasureSpec | None = None
Treasure the session rolls the first time the party enters the area, or None. It uses
treasure type letters or the unguarded-treasure table, so it works in any adventure.
features
class-attribute
instance-attribute
features: tuple[FeatureSpec, ...] = ()
The keyed things in the room: treasure caches, construction tricks, and custom features. A
pack can't bundle items, so their item_ids and magic_item_ids have to be ids from the built-in
catalogs.
PackFinding
Bases: BaseModel
One reference that a content pack doesn't cover: what is missing, and where.
validate_content_pack returns these. A finding
is data, not an error, so a tool can list the findings beside the pack and let the author decide
whether each gap matters. To refuse any pack with a gap, check whether the result is empty.
A finding states its facts in params, the way a Rejection
does, so a tool can build its own sentence without parsing message. The keys for each code are:
pack.encounter.unknown_monster:monster, the unknown monster id.pack.wandering.unknown_monster:section, the section's id,roll, the d20 result of the table row, andmonster, the unknown monster id.pack.feature.unknown_item:feature, the feature's id, anditem, the unknown item id.pack.feature.unknown_magic_item:feature, the feature's id, anditem, the unknown magic item id.pack.treasure.unknown_type:treasure_type, the letter that isn't a treasure type.pack.monster.unknown_treasure_type:monster, the bundled monster's id, andtreasure_type, the letter that isn't a treasure type.
Attributes:
| Name | Type | Description |
|---|---|---|
code |
str
|
What kind of gap this is. |
message |
str
|
The details, in English. |
params |
dict[str, int | str | tuple[int | str, ...]]
|
The facts behind the finding, keyed by name. |
entry_id |
str | None
|
The entry the gap is on, or |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
code
instance-attribute
code: str
What kind of gap this is, as a dotted snake_case code that starts with pack, like
"pack.encounter.unknown_monster". Read this field in your code. It follows the same format as
Rejection codes, so you can switch on it instead of
parsing the message. The codes validate_content_pack returns are:
pack.encounter.unknown_monster: an entry's encounter uses a monster id the catalogs don't have.pack.wandering.unknown_monster: a section's wandering table uses a monster id the catalogs don't have.pack.feature.unknown_item: a feature'sitem_idshas an id the equipment catalog doesn't have.pack.feature.unknown_magic_item: a feature'smagic_item_idshas an id the magic-item catalog doesn't have.pack.treasure.unknown_type: an entry'streasurehas a letter that isn't a treasure type.pack.monster.unknown_treasure_type: a bundled monster'streasurehas a letter that isn't a treasure type. The finding'sentry_idisNone.
message
instance-attribute
message: str
The details in English: which entry or section, which feature, and which id. It's written for
a person reading a list of findings. In your code, read params instead.
params
class-attribute
instance-attribute
The facts behind the finding, like the monster id that resolves nowhere.
Values are integers, strings, or tuples of either, as in a Rejection. The class docstring lists
the keys for each code. A finding you build yourself has no params unless you pass them.
entry_id
class-attribute
instance-attribute
entry_id: str | None = None
The id of the entry the gap is on, or None when the gap is in a section's wandering table or
a bundled monster rather than in an entry. For a wandering-table gap, params includes the
section's id, and for a bundled monster, the monster's id.
PackSection
Bases: BaseModel
The entries for one dungeon level, and that level's wandering-monster table.
A section groups entries the way a tool shows a pack, level by level. It also has a wandering-monster check, which applies to a whole level. Entry ids are unique across the pack, so a tool doesn't need the section to find an entry.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
str
|
The section's id, unique in the pack. |
label |
str
|
The section's display name. |
entries |
tuple[ContentPackEntry, ...]
|
The rooms in this section. |
wandering |
WanderingSpec | None
|
The level's wandering-monster check. |
id
class-attribute
instance-attribute
The section's id, unique within the pack. It can't be empty.
label
class-attribute
instance-attribute
label: str = ''
The name a tool shows for the section, like "Level 1" or "The lower caves".
entries
class-attribute
instance-attribute
entries: tuple[ContentPackEntry, ...] = ()
The rooms in this section. Their ids are unique across the whole pack, not only here.
wandering
class-attribute
instance-attribute
wandering: WanderingSpec | None = None
The level's wandering-monster check, or None for a section without one. A tool applying the
pack writes it to the target level's wandering field. Bundle each monster in its table that the
built-in catalog doesn't have, as you do for the entries' encounters.
validate_content_pack
validate_content_pack(
pack: ContentPack, monsters: MonsterCatalog, equipment: EquipmentCatalog
) -> tuple[PackFinding, ...]
Report the references that a content pack doesn't cover by itself.
Call it before you share a pack, or whenever a tool needs to show what is still missing. It follows every id in the pack and reports each one that resolves nowhere. For each finding, you can bundle the monster, change the id, or accept the gap for the adventures you plan to apply the pack to.
It checks each monster id in the entries' encounters and the sections' wandering tables against
monsters combined with the pack's monsters. It checks each feature's item_ids against
equipment, and each feature's magic_item_ids against the built-in magic-item catalog, which it
loads itself with load_magic_items because packs bundle no magic
items. It checks each treasure type letter in an entry's treasure and in a bundled monster's
treasure against the treasure types, A to V.
It never raises for a gap. A dangling reference is as allowed in a pack as in an adventure you're
still writing, so the gaps come back as data.
validate_adventure raises instead, because it checks
content that is about to be played.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pack
|
ContentPack
|
The pack to check. |
required |
monsters
|
MonsterCatalog
|
The base monster catalog, usually |
required |
equipment
|
EquipmentCatalog
|
The base equipment catalog, usually
|
required |
Returns:
| Type | Description |
|---|---|
tuple[PackFinding, ...]
|
One finding for each gap, in pack order: the bundled monsters first, then section by section, and within a section, the entries in order, then the wandering table. An id that appears in several places gives a finding for each place. An empty tuple means the pack is self-contained. |
Examples:
from osrlib.crawl.content_pack import ContentPack, ContentPackEntry, PackSection, validate_content_pack
from osrlib.crawl.dungeon import KeyedEncounter, KeyedMonster
from osrlib.data import load_equipment, load_monsters
entry = ContentPackEntry(
id="guard-post",
encounter=KeyedEncounter(monsters=(KeyedMonster(template_id="grue", count_fixed=1),)),
)
pack = ContentPack(name="The gnawing dark", sections=(PackSection(id="level-1", entries=(entry,)),))
for finding in validate_content_pack(pack, load_monsters(), load_equipment()):
print(finding.code, finding.entry_id, finding.params["monster"])
# pack.encounter.unknown_monster guard-post grue